workflow-studio/compute-client

Overview

@workflow-studio/compute-client is the HTTP client for worker APIs.

Use it in server code, CLI tooling, and adapter integrations.

Constructor

import { ComputeClient } from '@workflow-studio/compute-client';

const client = new ComputeClient({
  baseUrl: 'https://worker.example.com',
  apiKey: process.env.WORKFLOW_COMPUTE_API_KEY,
  timeoutMs: 10_000,
  retries: 2,
});

Methods

• trigger(request, { idempotencyKey? })
• getRun(runId)
• cancelRun(runId)
• resumeRun(request)
• createDeployment(manifest, artifact, contentType?)
• activateDeployment(deploymentId)
• getDeployment(deploymentId)
• getActiveDeployment()

Each method has a corresponding Effect variant (e.g. triggerEffect, getRunEffect) that returns Effect.Effect<T, ComputeClientRequestError> instead of Promise<T>.

Request behavior

• Adds Authorization: Bearer <key> when apiKey is configured.
• Adds Idempotency-Key for trigger (auto-generated if omitted).
• Adds x-workflow-correlation-id when absent.
• Supports timeout and retry configuration.

Retry policy

Retries up to configured limit for:

• 429 responses (RateLimitedComputeClientError),
• >=500 responses (ComputeClientError with status >= 500),
• network/timeout failures (TransportComputeClientError).

All other error types (unauthorized, scope, idempotency) fail immediately without retrying.

Error classes

All errors extend Schema.TaggedError and carry a _tag discriminant field for typed matching.

The ComputeClientRequestError union type covers all possible client errors:

type ComputeClientRequestError =
  | ComputeClientError
  | UnauthorizedComputeClientError
  | ScopeComputeClientError
  | IdempotencyComputeClientError
  | RateLimitedComputeClientError
  | TransportComputeClientError;

HTTP status mapping

The client converts non-2xx HTTP responses into typed errors based on status code and response body:

Order matters: 403 with code=missing_scope matches ScopeComputeClientError before the general 401/403 check for UnauthorizedComputeClientError.

Error fields

HTTP-derived errors (ComputeClientError, UnauthorizedComputeClientError, ScopeComputeClientError, IdempotencyComputeClientError, RateLimitedComputeClientError) carry:

• message - human-readable description
• status - HTTP status code
• code - optional error code from response body (e.g. missing_scope, idempotency_conflict)
• causeBody - optional raw response body for debugging

TransportComputeClientError carries:

• message - description (e.g. "Compute request failed", "Compute request timed out")
• cause - optional underlying error

runComputeClient

The runComputeClient helper converts an Effect-based client operation into a Promise while preserving the typed error. Promise methods (trigger, getRun, etc.) use this internally.

import { runComputeClient } from '@workflow-studio/compute-client';

const result = await runComputeClient(client.triggerEffect(req));

Callers should handle the base ComputeClientError as a catch-all because not every non-2xx response maps to a specialized subclass.