@openwop/openwop 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Request/response types for the openwop REST surface.
+ *
+ * Mirrors `api/openapi.yaml` and the JSON Schemas in
+ * `schemas/`. Hand-authored rather than codegen'd — see
+ * SDK README §rationale.
+ *
+ * Forward-compat: types use `string` (not narrow unions) for fields whose
+ * spec'd values may grow over time (status enums, event types, error codes).
+ * Consumers wanting exhaustive narrowing should `as const` their checks
+ * rather than relying on the SDK to refuse unknown values.
+ */
+/** Run statuses per `RunSnapshot.status` in OpenAPI. */
+export type RunStatus = 'pending' | 'running' | 'paused' | 'waiting-approval' | 'waiting-input' | 'completed' | 'failed' | 'cancelled';
+export interface Capabilities {
+    protocolVersion: string;
+    supportedEnvelopes: readonly string[];
+    schemaVersions: Record<string, number>;
+    limits: {
+        clarificationRounds: number;
+        schemaRounds: number;
+        envelopesPerTurn: number;
+        maxNodeExecutions?: number;
+    };
+    extensions?: Record<string, unknown>;
+    implementation?: {
+        name?: string;
+        version?: string;
+        vendor?: string;
+    };
+    engineVersion?: number;
+    eventLogSchemaVersion?: number;
+    supportedTransports?: readonly ('rest' | 'mcp' | 'a2a' | 'grpc')[];
+    configurable?: Record<string, unknown>;
+    observability?: Record<string, unknown>;
+    minClientVersion?: string;
+}
+export interface RunSnapshot {
+    runId: string;
+    workflowId: string;
+    status: RunStatus;
+    currentNodeId?: string;
+    startedAt?: string;
+    completedAt?: string;
+    nodeStates?: Record<string, unknown>;
+    variables?: Record<string, unknown>;
+    channels?: Record<string, unknown>;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/**
+ * Per-run parameter overlay carried in `RunOptions.configurable`. Reserved
+ * keys are typed; unknown keys are passed through verbatim. See
+ * `run-options.md`.
+ */
+export interface RunConfigurable {
+    /** Override the per-run node-execution ceiling. Clamped server-side. */
+    recursionLimit?: number;
+    /** Override AI model for nodes that consume `ctx.config.configurable.model`. */
+    model?: string;
+    /** Override AI temperature (server SHOULD enforce 0..2). */
+    temperature?: number;
+    /** Override AI max-tokens cap. */
+    maxTokens?: number;
+    /** Per-prompt-ID variant override map. */
+    promptOverrides?: Record<string, string>;
+    /** Implementation-specific extensions; passed through verbatim. */
+    [key: string]: unknown;
+}
+export interface CreateRunRequest {
+    workflowId: string;
+    inputs?: Record<string, unknown>;
+    tenantId?: string;
+    scopeId?: string;
+    callbackUrl?: string;
+    configurable?: RunConfigurable;
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+export interface CreateRunResponse {
+    runId: string;
+    status: RunStatus;
+    eventsUrl: string;
+    statusUrl?: string;
+}
+export interface CancelRunRequest {
+    reason?: string;
+}
+export interface CancelRunResponse {
+    runId: string;
+    status: 'cancelled' | 'cancelling';
+}
+export interface ForkRunRequest {
+    fromSeq: number;
+    mode: 'replay' | 'branch';
+    runOptionsOverlay?: Record<string, unknown>;
+}
+export interface ForkRunResponse {
+    runId: string;
+    sourceRunId: string;
+    fromSeq?: number;
+    mode: 'replay' | 'branch';
+    status: RunStatus;
+    eventsUrl: string;
+}
+export interface ResolveInterruptRequest {
+    resumeValue: unknown;
+}
+export interface ResolveInterruptResponse {
+    runId: string;
+    nodeId: string;
+    status: RunStatus;
+}
+/**
+ * Token-scoped interrupt inspection response — mirrors `suspend-request.schema.json`
+ * (the `InterruptPayload` shape).
+ */
+export interface InterruptByTokenInspection {
+    kind: 'approval' | 'clarification' | 'external-event' | 'custom';
+    key: string;
+    resumeSchema?: Record<string, unknown>;
+    timeoutMs?: number;
+    data: unknown;
+}
+export interface ResolveInterruptByTokenResponse {
+    [key: string]: unknown;
+}
+export interface PollEventsResponse {
+    events: readonly RunEventDoc[];
+    isComplete: boolean;
+}
+/** Mirror of `run-event.schema.json` — top-level shape only. */
+export interface RunEventDoc {
+    eventId: string;
+    runId: string;
+    nodeId?: string;
+    type: string;
+    payload: unknown;
+    timestamp: string;
+    sequence: number;
+    schemaVersion?: number;
+    engineVersion?: string;
+    causationId?: string;
+}
+export interface ErrorEnvelope {
+    error: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export type StreamMode = 'values' | 'updates' | 'messages' | 'debug';
+/**
+ * Thrown when the server returns a non-2xx response. Carries the original
+ * status, parsed error envelope (if available), the raw response text,
+ * and any `traceparent` the server returned (per
+ * `observability.md` §Trace context propagation —
+ * "Clients SHOULD display the trace ID in error messages so operators
+ * can search backend traces").
+ */
+export declare class WopError extends Error {
+    readonly status: number;
+    readonly envelope: ErrorEnvelope | undefined;
+    readonly rawText: string;
+    /** W3C `traceparent` from the response headers, when present. */
+    readonly traceparent: string | undefined;
+    /** 32-hex-char trace ID extracted from `traceparent`, when parseable. */
+    readonly traceId: string | undefined;
+    constructor(status: number, rawText: string, envelope: ErrorEnvelope | undefined, traceparent: string | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,57 @@
+/**
+ * Request/response types for the openwop REST surface.
+ *
+ * Mirrors `api/openapi.yaml` and the JSON Schemas in
+ * `schemas/`. Hand-authored rather than codegen'd — see
+ * SDK README §rationale.
+ *
+ * Forward-compat: types use `string` (not narrow unions) for fields whose
+ * spec'd values may grow over time (status enums, event types, error codes).
+ * Consumers wanting exhaustive narrowing should `as const` their checks
+ * rather than relying on the SDK to refuse unknown values.
+ */
+/**
+ * Thrown when the server returns a non-2xx response. Carries the original
+ * status, parsed error envelope (if available), the raw response text,
+ * and any `traceparent` the server returned (per
+ * `observability.md` §Trace context propagation —
+ * "Clients SHOULD display the trace ID in error messages so operators
+ * can search backend traces").
+ */
+export class WopError extends Error {
+    status;
+    envelope;
+    rawText;
+    /** W3C `traceparent` from the response headers, when present. */
+    traceparent;
+    /** 32-hex-char trace ID extracted from `traceparent`, when parseable. */
+    traceId;
+    constructor(status, rawText, envelope, traceparent) {
+        const traceId = traceparent ? extractTraceId(traceparent) : undefined;
+        const baseMessage = envelope?.message ?? `openwop request failed: HTTP ${status}`;
+        const messageWithTrace = traceId ? `${baseMessage} (trace=${traceId})` : baseMessage;
+        super(messageWithTrace);
+        this.name = 'WopError';
+        this.status = status;
+        this.rawText = rawText;
+        this.envelope = envelope;
+        this.traceparent = traceparent;
+        this.traceId = traceId;
+    }
+}
+/**
+ * Extract the 32-hex trace ID from a W3C traceparent header. Format:
+ * `00-<32-hex>-<16-hex>-<2-hex>`. Returns undefined for malformed
+ * input — never throws (errors during error construction would be
+ * truly miserable).
+ */
+function extractTraceId(traceparent) {
+    const parts = traceparent.split('-');
+    if (parts.length < 3)
+        return undefined;
+    const traceId = parts[1];
+    if (!traceId || !/^[0-9a-f]{32}$/i.test(traceId))
+        return undefined;
+    return traceId;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoKH;;;;;;;GAOG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,QAAQ,CAA4B;IACpC,OAAO,CAAS;IACzB,iEAAiE;IACxD,WAAW,CAAqB;IACzC,yEAAyE;IAChE,OAAO,CAAqB;IAErC,YACE,MAAc,EACd,OAAe,EACf,QAAmC,EACnC,WAA+B;QAE/B,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,MAAM,WAAW,GAAG,QAAQ,EAAE,OAAO,IAAI,gCAAgC,MAAM,EAAE,CAAC;QAClF,MAAM,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,WAAW,OAAO,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;QACrF,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,WAAmB;IACzC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACnE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@openwop/openwop",
+  "version": "1.0.0",
+  "description": "Production-ready TypeScript reference SDK for OpenWOP v1.0 compliant servers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openwop/openwop.git",
+    "directory": "sdk/typescript"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^2.1"
+  }
+}

package/src/client.ts

@@ -0,0 +1,277 @@
+/**
+ * OpenwopClient — typed HTTP client for the openwop REST surface.
+ *
+ * Hand-authored. Each method maps 1:1 to a documented endpoint in
+ * ../../api/openapi.yaml. Request/response types live in ./types.ts.
+ *
+ * Auth: a single bearer-style API key, supplied at construction. See
+ * ../../auth.md for credential format.
+ */
+
+import { streamEvents, type EventsStreamOptions } from './sse.js';
+import {
+  WopError,
+  type Capabilities,
+  type CancelRunRequest,
+  type CancelRunResponse,
+  type CreateRunRequest,
+  type CreateRunResponse,
+  type ErrorEnvelope,
+  type ForkRunRequest,
+  type ForkRunResponse,
+  type InterruptByTokenInspection,
+  type PollEventsResponse,
+  type ResolveInterruptByTokenResponse,
+  type ResolveInterruptRequest,
+  type ResolveInterruptResponse,
+  type RunEventDoc,
+  type RunSnapshot,
+} from './types.js';
+
+export interface OpenwopClientOptions {
+  /** Base URL of the openwop server, e.g., `https://api.example.com`. Trailing slash optional. */
+  readonly baseUrl: string;
+  /** API key (bearer-style). See auth.md. */
+  readonly apiKey: string;
+  /** Optional fetch implementation override (test injection). Defaults to global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /** Default `Accept-Language` to send. Optional. */
+  readonly acceptLanguage?: string;
+}
+
+export interface MutationOptions {
+  /** RFC-spec'd Idempotency-Key for at-most-once mutation semantics. */
+  readonly idempotencyKey?: string;
+  /** Optional X-Dedup hint for cross-host claim coordination on POST /v1/runs. */
+  readonly dedup?: 'enforce';
+}
+
+interface RawRequestOptions {
+  readonly method: string;
+  readonly path: string;
+  readonly body?: unknown;
+  readonly headers?: Record<string, string>;
+  readonly signal?: AbortSignal;
+}
+
+export class OpenwopClient {
+  readonly #baseUrl: string;
+  readonly #apiKey: string;
+  readonly #fetch: typeof fetch;
+  readonly #acceptLanguage: string | undefined;
+
+  constructor(opts: OpenwopClientOptions) {
+    if (!opts.baseUrl) throw new TypeError('OpenwopClient: baseUrl is required');
+    if (!opts.apiKey) throw new TypeError('OpenwopClient: apiKey is required');
+    this.#baseUrl = opts.baseUrl.replace(/\/$/, '');
+    this.#apiKey = opts.apiKey;
+    this.#fetch = opts.fetch ?? fetch;
+    this.#acceptLanguage = opts.acceptLanguage;
+  }
+
+  // ── Discovery ────────────────────────────────────────────────────────
+  readonly discovery = {
+    capabilities: (): Promise<Capabilities> =>
+      this.#request<Capabilities>({ method: 'GET', path: '/.well-known/openwop' }, false),
+
+    openapi: (): Promise<unknown> =>
+      this.#request<unknown>({ method: 'GET', path: '/v1/openapi.json' }, false),
+  };
+
+  // ── Workflows ────────────────────────────────────────────────────────
+  readonly workflows = {
+    get: (workflowId: string): Promise<unknown> =>
+      this.#request<unknown>({
+        method: 'GET',
+        path: `/v1/workflows/${encodeURIComponent(workflowId)}`,
+      }),
+  };
+
+  // ── Runs ─────────────────────────────────────────────────────────────
+  readonly runs = {
+    create: (body: CreateRunRequest, opts: MutationOptions = {}): Promise<CreateRunResponse> =>
+      this.#request<CreateRunResponse>({
+        method: 'POST',
+        path: '/v1/runs',
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    get: (runId: string): Promise<RunSnapshot> =>
+      this.#request<RunSnapshot>({
+        method: 'GET',
+        path: `/v1/runs/${encodeURIComponent(runId)}`,
+      }),
+
+    cancel: (
+      runId: string,
+      body: CancelRunRequest = {},
+      opts: MutationOptions = {},
+    ): Promise<CancelRunResponse> =>
+      this.#request<CancelRunResponse>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}/cancel`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    fork: (
+      runId: string,
+      body: ForkRunRequest,
+      opts: MutationOptions = {},
+    ): Promise<ForkRunResponse> =>
+      this.#request<ForkRunResponse>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}:fork`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    pollEvents: (
+      runId: string,
+      params: { lastSequence?: number; timeoutSeconds?: number } = {},
+    ): Promise<PollEventsResponse> => {
+      const search = new URLSearchParams();
+      if (params.lastSequence !== undefined) {
+        search.set('lastSequence', String(params.lastSequence));
+      }
+      if (params.timeoutSeconds !== undefined) {
+        search.set('timeout', String(params.timeoutSeconds));
+      }
+      const qs = search.toString();
+      return this.#request<PollEventsResponse>({
+        method: 'GET',
+        path: `/v1/runs/${encodeURIComponent(runId)}/events/poll${qs ? `?${qs}` : ''}`,
+      });
+    },
+
+    /**
+     * Async-iterable SSE consumer. The connection auto-closes when the
+     * server closes the stream (terminal run event); break out of the
+     * loop or call `signal.abort()` to terminate early.
+     */
+    events: (runId: string, opts: EventsStreamOptions = {}): AsyncGenerator<RunEventDoc, void, void> =>
+      streamEvents({ baseUrl: this.#baseUrl, apiKey: this.#apiKey }, runId, opts),
+  };
+
+  // ── HITL interrupts (run-scoped + signed-token) ──────────────────────
+  readonly interrupts = {
+    resolveByRun: (
+      runId: string,
+      nodeId: string,
+      body: ResolveInterruptRequest,
+      opts: MutationOptions = {},
+    ): Promise<ResolveInterruptResponse> =>
+      this.#request<ResolveInterruptResponse>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(nodeId)}`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    /**
+     * Inspect an interrupt via signed token — useful for showing the
+     * interrupt's `kind`, `data`, and `resumeSchema` to a downstream
+     * UI before the user resolves. Token is the auth, no API key
+     * required (signed-token endpoints intentionally bypass bearer
+     * auth so external systems can resolve without openwop credentials).
+     */
+    inspectByToken: (token: string): Promise<InterruptByTokenInspection> =>
+      this.#request<InterruptByTokenInspection>(
+        {
+          method: 'GET',
+          path: `/v1/interrupts/${encodeURIComponent(token)}`,
+        },
+        false, // unauthenticated (token IS the auth)
+      ),
+
+    /**
+     * Resolve an interrupt via signed token — used by external
+     * systems (calendar webhooks, payment confirmations) that the
+     * engine handed a callback URL at suspension time.
+     */
+    resolveByToken: (
+      token: string,
+      body: ResolveInterruptRequest,
+      opts: MutationOptions = {},
+    ): Promise<ResolveInterruptByTokenResponse> =>
+      this.#request<ResolveInterruptByTokenResponse>(
+        {
+          method: 'POST',
+          path: `/v1/interrupts/${encodeURIComponent(token)}`,
+          body,
+          headers: this.#mutationHeaders(opts),
+        },
+        false, // unauthenticated (token IS the auth)
+      ),
+  };
+
+  // ── Internals ────────────────────────────────────────────────────────
+  #mutationHeaders(opts: MutationOptions): Record<string, string> {
+    const h: Record<string, string> = {};
+    if (opts.idempotencyKey) h['Idempotency-Key'] = opts.idempotencyKey;
+    if (opts.dedup) h['X-Dedup'] = opts.dedup;
+    return h;
+  }
+
+  async #request<T>(opts: RawRequestOptions, authenticated = true): Promise<T> {
+    const url = `${this.#baseUrl}${opts.path}`;
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...(opts.headers ?? {}),
+    };
+    if (opts.body !== undefined && headers['Content-Type'] === undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    if (authenticated) {
+      headers.Authorization = `Bearer ${this.#apiKey}`;
+    }
+    if (this.#acceptLanguage) {
+      headers['Accept-Language'] = this.#acceptLanguage;
+    }
+
+    const init: RequestInit = { method: opts.method, headers };
+    if (opts.body !== undefined) {
+      init.body = JSON.stringify(opts.body);
+    }
+    if (opts.signal) {
+      init.signal = opts.signal;
+    }
+
+    const res = await this.#fetch(url, init);
+    const text = await res.text();
+    // Capture traceparent for error reporting per observability.md
+    // §Trace context propagation. Header name is case-insensitive per
+    // RFC 9110; fetch normalizes to lowercase but be defensive.
+    const traceparent =
+      res.headers.get('traceparent') ?? res.headers.get('Traceparent') ?? undefined;
+
+    if (!res.ok) {
+      let env: ErrorEnvelope | undefined;
+      try {
+        const parsed = text.length > 0 ? JSON.parse(text) : undefined;
+        if (parsed && typeof parsed === 'object' && 'error' in parsed && 'message' in parsed) {
+          env = parsed as ErrorEnvelope;
+        }
+      } catch {
+        // not JSON; leave envelope undefined
+      }
+      throw new WopError(res.status, text, env, traceparent);
+    }
+
+    if (text.length === 0) return undefined as T;
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      throw new WopError(
+        res.status,
+        text,
+        {
+          error: 'invalid_json',
+          message: 'Server returned non-JSON body for a 2xx response',
+        },
+        traceparent,
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @openwop/openwop — TypeScript reference SDK for OpenWOP-compliant servers.
+ *
+ * Public surface:
+ *   - OpenwopClient (auth + endpoint methods)
+ *   - WopError (typed error wrapping ErrorEnvelope)
+ *   - All request/response types mirroring the OpenAPI spec
+ *   - streamEvents helper for advanced SSE use cases
+ *
+ * See README.md for usage examples.
+ */
+
+export { OpenwopClient } from './client.js';
+export type { OpenwopClientOptions, MutationOptions } from './client.js';
+export { WopError } from './types.js';
+export type {
+  Capabilities,
+  CancelRunRequest,
+  CancelRunResponse,
+  CreateRunRequest,
+  CreateRunResponse,
+  ErrorEnvelope,
+  ForkRunRequest,
+  ForkRunResponse,
+  InterruptByTokenInspection,
+  PollEventsResponse,
+  ResolveInterruptByTokenResponse,
+  ResolveInterruptRequest,
+  ResolveInterruptResponse,
+  RunConfigurable,
+  RunEventDoc,
+  RunSnapshot,
+  RunStatus,
+  StreamMode,
+} from './types.js';
+export { streamEvents } from './sse.js';
+export type { EventsStreamContext, EventsStreamOptions } from './sse.js';
+
+// Run-status + run-error helpers (added in 1). Forward-compat predicates
+// over the wire-format unions declared above; full design + rationale in
+// `run-helpers.ts`.
+export {
+  ACTIVE_RUN_STATUSES,
+  TERMINAL_RUN_STATUSES,
+  isTerminalRunStatus,
+  HTTP_ERROR_CODES,
+  isHttpErrorCode,
+  RUN_ERROR_CODES,
+  isRunErrorCode,
+} from './run-helpers.js';
+export type {
+  ActiveRunStatus,
+  TerminalRunStatus,
+  HttpErrorCode,
+  RunErrorCode,
+  RunError,
+} from './run-helpers.js';