Client Wrapper API

Last Updated: 2026-02-13 Audience: Developers Status: Active Related Docs: API Convergence Matrix | Workers Overview

<- Back to Workers Overview

Each FFI worker package (Ruby, Python, TypeScript) includes a high-level client wrapper for the orchestration API. The wrappers provide keyword-argument methods with sensible defaults and return typed response objects, removing the need to construct raw request hashes or parse untyped responses.

Overview

Ruby

Usage

require 'tasker_core'

# All methods are module_function — call directly on TaskerCore::Client
response = TaskerCore::Client.create_task(
  name: 'order_processing',
  namespace: 'ecommerce',
  context: { order_id: 123, items: [...] },
  initiator: 'my-service',       # default: 'tasker-core-ruby'
  source_system: 'my-api',       # default: 'tasker-core'
  reason: 'New order received'   # default: 'Task requested'
)

response.task_uuid  # => "550e8400-..."
response.status     # => "pending"

Methods

Response Types

All response types are Dry::Struct classes defined in TaskerCore::Types::ClientTypes. Access fields as method calls (e.g., response.task_uuid, list.pagination.total_count). If the API returns fields that don’t match the schema, the raw Hash is returned instead for forward-compatibility.

ActionController::Parameters

create_task automatically converts Rails ActionController::Parameters to plain hashes via deep_to_hash, so you can pass params[:context] directly from controllers.

Python

Usage

from tasker_core import TaskerClient

# Create a client with custom defaults
client = TaskerClient(
    initiator="my-service",       # default: "tasker-core-python"
    source_system="my-api",       # default: "tasker-core"
)

response = client.create_task(
    "order_processing",
    namespace="ecommerce",
    context={"order_id": 123, "items": [...]},
    reason="New order received",
)

response.task_uuid  # => "550e8400-..."
response.status     # => "pending"

Methods

Response Types

All response types are frozen dataclasses with from_dict(data) classmethods:

• TaskResponse — task_uuid, name, namespace, status, context, steps, etc.
• TaskListResponse — tasks: list[TaskResponse], pagination: PaginationInfo
• StepResponse — step_uuid, task_uuid, name, current_state, attempts, etc.
• StepAuditResponse — audit_uuid, step_name, to_state, success, etc.
• HealthResponse — healthy, status, timestamp
• PaginationInfo — page, per_page, total_count, total_pages, has_next, has_previous

Exports

All types are re-exported from tasker_core with Client prefix to avoid collisions:

from tasker_core import (
    TaskerClient,
    ClientTaskResponse,
    ClientTaskListResponse,
    ClientStepResponse,
    ClientStepAuditResponse,
    ClientHealthResponse,
    ClientPaginationInfo,
)

TypeScript

Usage

import { FfiLayer, TaskerClient } from '@tasker-systems/tasker';

const ffiLayer = new FfiLayer();
await ffiLayer.load();
const client = new TaskerClient(ffiLayer);

const response = client.createTask({
  name: 'order_processing',
  namespace: 'ecommerce',          // default: 'default'
  context: { orderId: 123 },       // default: {}
  initiator: 'my-service',         // default: 'tasker-core-typescript'
  sourceSystem: 'my-api',          // default: 'tasker-core'
  reason: 'New order received',    // default: 'Task requested'
});

response.task_uuid;  // "550e8400-..."
response.status;     // "pending"

Methods

Interfaces

interface CreateTaskOptions {
  name: string;
  namespace?: string;                    // default: 'default'
  context?: Record<string, unknown>;     // default: {}
  version?: string;                      // default: '1.0.0'
  initiator?: string;                    // default: 'tasker-core-typescript'
  sourceSystem?: string;                 // default: 'tasker-core'
  reason?: string;                       // default: 'Task requested'
  tags?: string[];
  correlationId?: string;                // default: crypto.randomUUID()
  parentCorrelationId?: string;
  idempotencyKey?: string;
  priority?: number;
}

interface ListTasksOptions {
  limit?: number;    // default: 50
  offset?: number;   // default: 0
  namespace?: string;
  status?: string;
}

Error Handling

All methods unwrap the raw FFI ClientResult envelope. On failure, a TaskerClientError is thrown:

import { TaskerClientError } from '@tasker-systems/tasker';

try {
  const task = client.getTask('nonexistent-uuid');
} catch (error) {
  if (error instanceof TaskerClientError) {
    console.error(error.message);
    console.error(error.recoverable);  // boolean — whether retry is appropriate
  }
}

Exports

export {
  TaskerClient,
  TaskerClientError,
  type CreateTaskOptions,
  type ListTasksOptions,
} from '@tasker-systems/tasker';

Raw FFI (Advanced)

The client wrappers call through to raw FFI functions. For advanced use cases or when the wrapper doesn’t expose a needed field, the raw FFI is still available:

Raw FFI returns plain Hash/dict/ClientResult — no type wrapping. TypeScript raw FFI returns a ClientResult envelope ({ success, data, error, recoverable }).