TypeScript / Node.js SDK

Features

• ✓Single package: @orch8.io/sdk (client, builder, and polling worker)
• ✓Typed methods across sequences, instances, pools, credentials, circuit breakers, approvals, SSE streaming, and more
• ✓Fluent WorkflowBuilder with .step(), .parallel(), .race(), .loop(), .forEach(), .router(), .tryCatch(), .subSequence(), .abSplit(), .cancellationScope(), .delay(), .raw()
• ✓Polling worker with circuit breaker awareness — skips handlers with open breakers
• ✓Exponential backoff on poll failures (doubles up to 30s, resets on success)
• ✓onTaskComplete / onTaskFail observability callbacks
• ✓SSE streaming via async generator for real-time instance progress
• ✓Full TypeScript types with Zod schema validation on build()

Client methods

Full management surface covering all engine API domains.

• listSequences / createSequence / getSequence / getSequenceByName / deleteSequence / deprecateSequence / listSequenceVersions / migrateInstance
• createInstance / batchCreateInstances / getInstance / listInstances / updateInstanceState / updateInstanceContext / sendSignal / retryInstance / injectBlocks / streamInstance
• getOutputs / getExecutionTree / listAuditLog
• listCheckpoints / saveCheckpoint / getLatestCheckpoint / pruneCheckpoints
• bulkUpdateState / bulkReschedule / listDLQ
• listApprovals
• listWorkerTasks / getWorkerTaskStats / pollTasks / pollTasksFromQueue / completeTask / failTask / heartbeatTask
• createCron / listCron / getCron / updateCron / deleteCron
• createTrigger / listTriggers / getTrigger / deleteTrigger / fireTrigger
• createPlugin / listPlugins / getPlugin / updatePlugin / deletePlugin
• createSession / getSession / getSessionByKey / updateSessionData / updateSessionState / listSessionInstances
• listPools / createPool / getPool / deletePool / listPoolResources / createPoolResource / updatePoolResource / deletePoolResource
• listCredentials / createCredential / getCredential / deleteCredential / updateCredential
• listCircuitBreakers / getCircuitBreaker / resetCircuitBreaker / listTenantCircuitBreakers / getTenantCircuitBreaker / resetTenantCircuitBreaker
• listClusterNodes / drainNode / health

Management Client

Typed helpers for common management domains. Use the generated REST API for routes not yet wrapped by the installed SDK version.

import { Orch8Client } from "@orch8.io/sdk";

const client = new Orch8Client({
  baseUrl: "http://localhost:8080",
  tenantId: "my-tenant",
  apiKey: "optional-bearer-token",
});

// Create a sequence definition
const seq = await client.createSequence({
  tenant_id: "my-tenant",
  namespace: "default",
  name: "onboarding-drip",
  version: 1,
  blocks: [
    { type: "step", id: "send_welcome", handler: "send_welcome_email" },
    { type: "step", id: "wait_48h", handler: "noop", delay: { duration: 172800000 } },
  ],
});

// Schedule an instance
const instance = await client.createInstance({
  sequence_id: seq.id,
  tenant_id: "my-tenant",
  context: { data: { userId: "usr_123", email: "user@example.com" } },
});

// Send a signal
await client.sendSignal(instance.id, "update_context", {
  preferences: "weekly",
});

Workflow Builder

Fluent API for defining sequences in code. Chain blocks, add delays, nest parallel and try-catch — then call .build() to validate with Zod and get the JSON definition.

import { workflow, Orch8Client } from "@orch8.io/sdk";

const onboarding = workflow("onboarding-drip")
  .step("send_welcome", "send_welcome_email")
  .delay({ duration: 172800000 })
  .step("check_activation", "http_request", {
    method: "GET",
    url: "https://api.yourapp.com/users/{{context.user_id}}/activation",
  })
  .router("engagement_branch", [
    {
      condition: "{{steps.check_activation.output.active}}",
      blocks: (b) => b.step("send_tips", "send_tips_email"),
    },
  ], (b) => b.step("send_reminder", "send_reminder_email"))
  .tryCatch("safe_crm_update",
    (b) => b.step("crm_update", "update_hubspot"),
    (b) => b.step("log_error", "log", { level: "error" }),
  )
  .build(); // Validates with Zod, returns sequence JSON

// Deploy
const client = new Orch8Client({
  baseUrl: "http://localhost:8080",
  tenantId: "my-tenant",
});
await client.createSequence(onboarding);

Polling Worker

Register handler functions and let the worker poll, execute, heartbeat, and report results automatically.

import { Orch8Worker } from "@orch8.io/sdk";

const worker = new Orch8Worker({
  engineUrl: "http://localhost:8080",
  workerId: "worker-1",
  pollIntervalMs: 1000,       // poll every 1s per handler
  heartbeatIntervalMs: 15000,  // heartbeat every 15s
  maxConcurrent: 10,           // across all handlers
  handlers: {
    send_welcome_email: async (task) => {
      const { email } = task.context.data;
      await sendEmail(email, "Welcome!");
      return { sent: true };
    },
    check_engagement: async (task) => {
      const score = await getEngagementScore(task.context.data.userId);
      return { route: score > 50 ? "engaged" : "inactive" };
    },
  },
});

await worker.start();
// worker.stop() for graceful shutdown (30s drain)