@openwop/openwop 1.0.0

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @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 { WopError } from './types.js';
+export { streamEvents } 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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAqBtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/run-helpers.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Run-status + error-code helpers — additive utilities over the wire-format
+ * `RunStatus` union, HTTP error envelopes, and run-level error shape
+ * declared in `types.ts`.
+ *
+ * **Why these live here.** `types.ts` declares the canonical wire shapes
+ * (mirroring `api/openapi.yaml` + `schemas/run-snapshot.schema.json`).
+ * This module adds the constants + predicates SDK consumers need to act
+ * on those shapes without redefining them locally. Pulling them into the
+ * SDK makes the protocol vocabulary single-sourced for application,
+ * integration, and test code.
+ *
+ * **Forward-compatibility design.** The spec's `RunStatus` enum is
+ * intentionally narrower than what host engines may emit: the schema
+ * declares *"future statuses MAY be added; readers SHOULD treat unknown
+ * values as terminal-unknown rather than throw"*. So `isTerminalRunStatus`
+ * accepts `string` and uses a **negative-set** check — anything NOT in
+ * the small known-non-terminal set is treated as terminal. This keeps
+ * the helper correct against:
+ *
+ *   - the canonical 8-member spec union (`pending` / `running` / `paused`
+ *     / `waiting-approval` / `waiting-input` / `completed` / `failed` /
+ *     `cancelled`)
+ *   - host extensions like `'planned'`, `'executing'`, `'waiting-external'`,
+ *     `'timed-out'`, `'interrupted'` which the OpenWOP engine emits
+ *   - any future spec additions before the SDK ships an updated minor
+ *
+ * @module @openwop/openwop/run-helpers
+ */
+import type { RunStatus } from './types.js';
+/**
+ * Run statuses considered active — the run MAY still transition. A reader
+ * who does not recognize a status string MUST treat it as terminal-unknown
+ * (per the spec's forward-compat clause). This list is the narrow,
+ * spec-stable enumeration used to derive that decision.
+ */
+export declare const ACTIVE_RUN_STATUSES: readonly ["pending", "running", "paused", "waiting-approval", "waiting-input"];
+/**
+ * Spec-known terminal statuses. Hosts MAY emit additional terminal values
+ * (e.g., `'timed-out'`, `'interrupted'`); use {@link isTerminalRunStatus}
+ * for forward-compatible checks instead of literal-set membership.
+ */
+export declare const TERMINAL_RUN_STATUSES: readonly ["completed", "failed", "cancelled"];
+export type ActiveRunStatus = (typeof ACTIVE_RUN_STATUSES)[number];
+export type TerminalRunStatus = (typeof TERMINAL_RUN_STATUSES)[number];
+/**
+ * Returns true if the status indicates the run will not transition further.
+ *
+ * Implemented as a negative check against {@link ACTIVE_RUN_STATUSES}: any
+ * value NOT in the spec's known-active set is treated as terminal. This
+ * implements the schema's forward-compat clause — a host that emits a
+ * status the SDK doesn't know about is assumed to be reporting a terminal
+ * state, NOT that the run is still active. The alternative (positive check
+ * against {@link TERMINAL_RUN_STATUSES}) would loop polling forever on any
+ * unknown value, which is the documented worst-case the clause prevents.
+ *
+ * Accepts `string` (not just `RunStatus`) so callers can pass values from
+ * extended host emissions without casting.
+ */
+export declare function isTerminalRunStatus(status: RunStatus | string): boolean;
+/**
+ * Canonical REST/MCP error-envelope codes from `auth.md`,
+ * `rest-endpoints.md`, and adjacent v1 specs. The HTTP envelope's `error`
+ * field remains string-typed for forward compatibility, but this list
+ * gives SDK consumers a stable set for common branching.
+ *
+ * Codes here describe request/transport failures. Run execution failures
+ * live in `RUN_ERROR_CODES` below as `RunSnapshot.error.code`.
+ */
+export declare const HTTP_ERROR_CODES: readonly ["unauthenticated", "forbidden", "key_expired", "key_revoked", "validation_error", "not_found", "rate_limited", "run_already_active", "idempotency_in_flight", "idempotency_key_mismatch", "unsupported_stream_mode", "force_engine_version_forbidden", "mock_provider_forbidden", "capability_not_provided", "credential_required", "credential_forbidden", "credential_unavailable", "interrupt_not_found", "approval_token_invalid", "approval_token_expired", "approval_token_consumed", "internal_error"];
+export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
+/**
+ * Type guard that narrows a string to a known canonical HTTP error code.
+ * Returns false for host extensions and future spec additions; callers
+ * should still render a fallback from the envelope's `message`.
+ */
+export declare function isHttpErrorCode(value: unknown): value is HttpErrorCode;
+/**
+ * Run-document error codes — stable identifiers used in
+ * `RunSnapshot.error.code` when a run reaches `failed`. These are distinct
+ * from the HTTP-level `ErrorEnvelope.error` codes above: a request can fail
+ * with `unauthenticated` before a run exists, while a run can fail later
+ * with `node_execution_failed` or `recursion_limit_exceeded`.
+ *
+ * Add a new code here when adding a new run failure mode that crosses the
+ * network boundary. Do NOT add codes for purely internal engine errors.
+ *
+ * **Drift risk note.** This list is canonical for SDK consumers but is
+ * NOT yet pinned by `conformance/src/scenarios/errors.test.ts` against
+ * host emission. A future conformance addition (tracked separately)
+ * SHOULD compare host-emitted error codes against this set and fail on
+ * unrecognized values. Until that lands, drift between this list + the
+ * engine's actual emission set is detectable only by manual review.
+ */
+export declare const RUN_ERROR_CODES: readonly ["auth_required", "forbidden", "workspace_not_found", "run_already_active", "run_not_found", "run_terminal", "engine_version_mismatch", "invalid_workflow_definition", "invalid_trigger_input", "node_type_not_found", "config_validation_failed", "token_budget_exceeded", "concurrent_run_limit_reached", "rate_limited", "node_timeout", "global_timeout", "node_execution_failed", "external_call_failed", "recursion_limit_exceeded", "capability_not_provided", "approval_timeout", "approval_token_invalid", "approval_token_expired", "approval_token_consumed", "persistence_failed", "doc_budget_exceeded"];
+export type RunErrorCode = (typeof RUN_ERROR_CODES)[number];
+/**
+ * Type guard that narrows a string to a known {@link RunErrorCode}.
+ * Returns false for unknown / malformed values rather than throwing —
+ * SDK consumers usually want to display a fallback for unknown codes
+ * rather than crash the render pipeline.
+ */
+export declare function isRunErrorCode(value: unknown): value is RunErrorCode;
+/**
+ * Run-level error shape — the structured `error` field on a `failed` run
+ * document. Distinct from the HTTP-level {@link import('./types.js').ErrorEnvelope}:
+ *
+ *   - `RunError` lives on the run document; describes WHY the run failed.
+ *     `code` is from the typed {@link RunErrorCode} vocabulary.
+ *   - `ErrorEnvelope` lives on HTTP error responses; describes WHY the
+ *     request failed. `error` is a free string code (often from
+ *     {@link HTTP_ERROR_CODES}, but not type-pinned, to permit host
+ *     extensions and future protocol additions).
+ *
+ * The shapes share `message` and `details` but diverge on the code field
+ * name (`code` vs `error`) by design — they represent different layers.
+ */
+export interface RunError {
+    code: RunErrorCode;
+    message: string;
+    /** Optional node-id where the error originated. */
+    nodeId?: string;
+    /** Optional structured context — implementations MAY extend. */
+    details?: Record<string, unknown>;
+}
+//# sourceMappingURL=run-helpers.d.ts.map

package/dist/run-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-helpers.d.ts","sourceRoot":"","sources":["../src/run-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gFAMtB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,+CAIxB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAEvE;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,yfAoCnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,gmBAwClB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}

package/dist/run-helpers.js

@@ -0,0 +1,182 @@
+/**
+ * Run-status + error-code helpers — additive utilities over the wire-format
+ * `RunStatus` union, HTTP error envelopes, and run-level error shape
+ * declared in `types.ts`.
+ *
+ * **Why these live here.** `types.ts` declares the canonical wire shapes
+ * (mirroring `api/openapi.yaml` + `schemas/run-snapshot.schema.json`).
+ * This module adds the constants + predicates SDK consumers need to act
+ * on those shapes without redefining them locally. Pulling them into the
+ * SDK makes the protocol vocabulary single-sourced for application,
+ * integration, and test code.
+ *
+ * **Forward-compatibility design.** The spec's `RunStatus` enum is
+ * intentionally narrower than what host engines may emit: the schema
+ * declares *"future statuses MAY be added; readers SHOULD treat unknown
+ * values as terminal-unknown rather than throw"*. So `isTerminalRunStatus`
+ * accepts `string` and uses a **negative-set** check — anything NOT in
+ * the small known-non-terminal set is treated as terminal. This keeps
+ * the helper correct against:
+ *
+ *   - the canonical 8-member spec union (`pending` / `running` / `paused`
+ *     / `waiting-approval` / `waiting-input` / `completed` / `failed` /
+ *     `cancelled`)
+ *   - host extensions like `'planned'`, `'executing'`, `'waiting-external'`,
+ *     `'timed-out'`, `'interrupted'` which the OpenWOP engine emits
+ *   - any future spec additions before the SDK ships an updated minor
+ *
+ * @module @openwop/openwop/run-helpers
+ */
+// ─── Run statuses ────────────────────────────────────────────────────────
+/**
+ * Run statuses considered active — the run MAY still transition. A reader
+ * who does not recognize a status string MUST treat it as terminal-unknown
+ * (per the spec's forward-compat clause). This list is the narrow,
+ * spec-stable enumeration used to derive that decision.
+ */
+export const ACTIVE_RUN_STATUSES = [
+    'pending',
+    'running',
+    'paused',
+    'waiting-approval',
+    'waiting-input',
+];
+/**
+ * Spec-known terminal statuses. Hosts MAY emit additional terminal values
+ * (e.g., `'timed-out'`, `'interrupted'`); use {@link isTerminalRunStatus}
+ * for forward-compatible checks instead of literal-set membership.
+ */
+export const TERMINAL_RUN_STATUSES = [
+    'completed',
+    'failed',
+    'cancelled',
+];
+/**
+ * Returns true if the status indicates the run will not transition further.
+ *
+ * Implemented as a negative check against {@link ACTIVE_RUN_STATUSES}: any
+ * value NOT in the spec's known-active set is treated as terminal. This
+ * implements the schema's forward-compat clause — a host that emits a
+ * status the SDK doesn't know about is assumed to be reporting a terminal
+ * state, NOT that the run is still active. The alternative (positive check
+ * against {@link TERMINAL_RUN_STATUSES}) would loop polling forever on any
+ * unknown value, which is the documented worst-case the clause prevents.
+ *
+ * Accepts `string` (not just `RunStatus`) so callers can pass values from
+ * extended host emissions without casting.
+ */
+export function isTerminalRunStatus(status) {
+    return !ACTIVE_RUN_STATUSES.includes(status);
+}
+// ─── HTTP error-envelope codes ───────────────────────────────────────────
+/**
+ * Canonical REST/MCP error-envelope codes from `auth.md`,
+ * `rest-endpoints.md`, and adjacent v1 specs. The HTTP envelope's `error`
+ * field remains string-typed for forward compatibility, but this list
+ * gives SDK consumers a stable set for common branching.
+ *
+ * Codes here describe request/transport failures. Run execution failures
+ * live in `RUN_ERROR_CODES` below as `RunSnapshot.error.code`.
+ */
+export const HTTP_ERROR_CODES = [
+    // Auth / access
+    'unauthenticated',
+    'forbidden',
+    'key_expired',
+    'key_revoked',
+    // Request / routing
+    'validation_error',
+    'not_found',
+    'rate_limited',
+    // Idempotency / run creation conflicts
+    'run_already_active',
+    'idempotency_in_flight',
+    'idempotency_key_mismatch',
+    // Streaming / protocol negotiation
+    'unsupported_stream_mode',
+    'force_engine_version_forbidden',
+    'mock_provider_forbidden',
+    // Capability / credential negotiation
+    'capability_not_provided',
+    'credential_required',
+    'credential_forbidden',
+    'credential_unavailable',
+    // HITL / interrupt callbacks
+    'interrupt_not_found',
+    'approval_token_invalid',
+    'approval_token_expired',
+    'approval_token_consumed',
+    // Generic server failure
+    'internal_error',
+];
+/**
+ * Type guard that narrows a string to a known canonical HTTP error code.
+ * Returns false for host extensions and future spec additions; callers
+ * should still render a fallback from the envelope's `message`.
+ */
+export function isHttpErrorCode(value) {
+    return typeof value === 'string' && HTTP_ERROR_CODES.includes(value);
+}
+// ─── Run error codes ─────────────────────────────────────────────────────
+/**
+ * Run-document error codes — stable identifiers used in
+ * `RunSnapshot.error.code` when a run reaches `failed`. These are distinct
+ * from the HTTP-level `ErrorEnvelope.error` codes above: a request can fail
+ * with `unauthenticated` before a run exists, while a run can fail later
+ * with `node_execution_failed` or `recursion_limit_exceeded`.
+ *
+ * Add a new code here when adding a new run failure mode that crosses the
+ * network boundary. Do NOT add codes for purely internal engine errors.
+ *
+ * **Drift risk note.** This list is canonical for SDK consumers but is
+ * NOT yet pinned by `conformance/src/scenarios/errors.test.ts` against
+ * host emission. A future conformance addition (tracked separately)
+ * SHOULD compare host-emitted error codes against this set and fail on
+ * unrecognized values. Until that lands, drift between this list + the
+ * engine's actual emission set is detectable only by manual review.
+ */
+export const RUN_ERROR_CODES = [
+    // Authorization / access
+    'auth_required',
+    'forbidden',
+    'workspace_not_found',
+    // Run-state conflicts
+    'run_already_active',
+    'run_not_found',
+    'run_terminal',
+    'engine_version_mismatch',
+    // Validation
+    'invalid_workflow_definition',
+    'invalid_trigger_input',
+    'node_type_not_found',
+    'config_validation_failed',
+    // Quota / budget
+    'token_budget_exceeded',
+    'concurrent_run_limit_reached',
+    'rate_limited',
+    // Execution
+    'node_timeout',
+    'global_timeout',
+    'node_execution_failed',
+    'external_call_failed',
+    'recursion_limit_exceeded',
+    'capability_not_provided',
+    // Approval
+    'approval_timeout',
+    'approval_token_invalid',
+    'approval_token_expired',
+    'approval_token_consumed',
+    // Persistence
+    'persistence_failed',
+    'doc_budget_exceeded',
+];
+/**
+ * Type guard that narrows a string to a known {@link RunErrorCode}.
+ * Returns false for unknown / malformed values rather than throwing —
+ * SDK consumers usually want to display a fallback for unknown codes
+ * rather than crash the render pipeline.
+ */
+export function isRunErrorCode(value) {
+    return typeof value === 'string' && RUN_ERROR_CODES.includes(value);
+}
+//# sourceMappingURL=run-helpers.js.map

package/dist/run-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-helpers.js","sourceRoot":"","sources":["../src/run-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,4EAA4E;AAE5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,SAAS;IACT,QAAQ;IACR,kBAAkB;IAClB,eAAe;CACP,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,WAAW;IACX,QAAQ;IACR,WAAW;CACH,CAAC;AAKX;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,OAAO,CAAE,mBAAyC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC;AAED,4EAA4E;AAE5E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,gBAAgB;IAChB,iBAAiB;IACjB,WAAW;IACX,aAAa;IACb,aAAa;IAEb,oBAAoB;IACpB,kBAAkB;IAClB,WAAW;IACX,cAAc;IAEd,uCAAuC;IACvC,oBAAoB;IACpB,uBAAuB;IACvB,0BAA0B;IAE1B,mCAAmC;IACnC,yBAAyB;IACzB,gCAAgC;IAChC,yBAAyB;IAEzB,sCAAsC;IACtC,yBAAyB;IACzB,qBAAqB;IACrB,sBAAsB;IACtB,wBAAwB;IAExB,6BAA6B;IAC7B,qBAAqB;IACrB,wBAAwB;IACxB,wBAAwB;IACxB,yBAAyB;IAEzB,yBAAyB;IACzB,gBAAgB;CACR,CAAC;AAIX;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED,4EAA4E;AAE5E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,yBAAyB;IACzB,eAAe;IACf,WAAW;IACX,qBAAqB;IAErB,sBAAsB;IACtB,oBAAoB;IACpB,eAAe;IACf,cAAc;IACd,yBAAyB;IAEzB,aAAa;IACb,6BAA6B;IAC7B,uBAAuB;IACvB,qBAAqB;IACrB,0BAA0B;IAE1B,iBAAiB;IACjB,uBAAuB;IACvB,8BAA8B;IAC9B,cAAc;IAEd,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,uBAAuB;IACvB,sBAAsB;IACtB,0BAA0B;IAC1B,yBAAyB;IAEzB,WAAW;IACX,kBAAkB;IAClB,wBAAwB;IACxB,wBAAwB;IACxB,yBAAyB;IAEzB,cAAc;IACd,oBAAoB;IACpB,qBAAqB;CACb,CAAC;AAIX;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7F,CAAC"}

package/dist/sse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SSE consumer for `GET /v1/runs/{runId}/events`. Async-iterable shape so
+ * consumers can write `for await (const event of client.runs.events(...))`.
+ *
+ * Implementation parses event:/data:/id: lines per RFC 8895. Native fetch +
+ * ReadableStream — zero third-party deps.
+ *
+ * Designed to be cancellable: pass an AbortSignal via options, or break out
+ * of the for-await loop and the underlying connection is torn down on the
+ * next tick.
+ */
+import type { RunEventDoc, StreamMode } from './types.js';
+export interface EventsStreamOptions {
+    /**
+     * Single mode (e.g., 'updates') OR array of modes (S4 mixed-mode,
+     * e.g., ['updates', 'messages']). Arrays serialize to a comma-
+     * separated `?streamMode=updates,messages` query.
+     */
+    readonly streamMode?: StreamMode | readonly StreamMode[];
+    readonly lastEventId?: string;
+    readonly signal?: AbortSignal;
+    /**
+     * S3 batching hint. When set, server batches events for up to N ms;
+     * the SDK transparently flattens batched arrays back into individual
+     * RunEventDoc yields, so consumers see the same per-event surface as
+     * unbuffered streams. Range 0..5000.
+     */
+    readonly bufferMs?: number;
+}
+export interface EventsStreamContext {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+}
+export declare function streamEvents(ctx: EventsStreamContext, runId: string, opts?: EventsStreamOptions): AsyncGenerator<RunEventDoc, void, void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,CAAC;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAuB,YAAY,CACjC,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,mBAAwB,GAC7B,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CA6HzC"}

package/dist/sse.js

@@ -0,0 +1,137 @@
+/**
+ * SSE consumer for `GET /v1/runs/{runId}/events`. Async-iterable shape so
+ * consumers can write `for await (const event of client.runs.events(...))`.
+ *
+ * Implementation parses event:/data:/id: lines per RFC 8895. Native fetch +
+ * ReadableStream — zero third-party deps.
+ *
+ * Designed to be cancellable: pass an AbortSignal via options, or break out
+ * of the for-await loop and the underlying connection is torn down on the
+ * next tick.
+ */
+export async function* streamEvents(ctx, runId, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.streamMode) {
+        const modeParam = typeof opts.streamMode === 'string' ? opts.streamMode : opts.streamMode.join(',');
+        params.set('streamMode', modeParam);
+    }
+    if (opts.bufferMs !== undefined) {
+        params.set('bufferMs', String(opts.bufferMs));
+    }
+    const qs = params.toString();
+    const url = `${ctx.baseUrl}/v1/runs/${encodeURIComponent(runId)}/events${qs ? `?${qs}` : ''}`;
+    const headers = {
+        Accept: 'text/event-stream',
+        Authorization: `Bearer ${ctx.apiKey}`,
+        'Cache-Control': 'no-cache',
+    };
+    if (opts.lastEventId) {
+        headers['Last-Event-ID'] = opts.lastEventId;
+    }
+    const internalAbort = new AbortController();
+    const externalSignal = opts.signal;
+    if (externalSignal) {
+        if (externalSignal.aborted)
+            internalAbort.abort();
+        else
+            externalSignal.addEventListener('abort', () => internalAbort.abort(), { once: true });
+    }
+    const res = await fetch(url, { method: 'GET', headers, signal: internalAbort.signal });
+    if (!res.ok || res.body === null) {
+        throw new Error(`SSE subscribe failed: HTTP ${res.status}`);
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buffer = '';
+    let pendingEvent = 'message';
+    let pendingData = [];
+    let pendingId = null;
+    /**
+     * Flush the buffered event. Returns an array of RunEventDoc:
+     *   - 0 elements when the buffer is empty or non-JSON (skip).
+     *   - 1 element for a normal `event: <type>` event.
+     *   - N elements when the server batched per S3 — `event: batch` with
+     *     `data:` as a JSON array of RunEventDoc.
+     */
+    const flushAndYield = () => {
+        if (pendingData.length === 0) {
+            pendingEvent = 'message';
+            pendingId = null;
+            return [];
+        }
+        const dataStr = pendingData.join('\n');
+        const eventType = pendingEvent;
+        pendingEvent = 'message';
+        pendingData = [];
+        pendingId = null;
+        try {
+            const parsed = JSON.parse(dataStr);
+            // S3 batched envelope — `event: batch` carries an array of events.
+            if (eventType === 'batch' && Array.isArray(parsed)) {
+                return parsed;
+            }
+            // Normal single-event payload.
+            return [parsed];
+        }
+        catch {
+            // Skip non-JSON events (keep-alive payloads, vendor extensions).
+            return [];
+        }
+    };
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let nlIdx;
+            while ((nlIdx = buffer.indexOf('\n')) !== -1) {
+                const rawLine = buffer.slice(0, nlIdx).replace(/\r$/, '');
+                buffer = buffer.slice(nlIdx + 1);
+                if (rawLine === '') {
+                    for (const event of flushAndYield())
+                        yield event;
+                    continue;
+                }
+                if (rawLine.startsWith(':'))
+                    continue; // keep-alive comment
+                const colon = rawLine.indexOf(':');
+                const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+                const valueRaw = colon === -1 ? '' : rawLine.slice(colon + 1);
+                const fieldValue = valueRaw.startsWith(' ') ? valueRaw.slice(1) : valueRaw;
+                switch (field) {
+                    case 'event':
+                        pendingEvent = fieldValue;
+                        break;
+                    case 'data':
+                        pendingData.push(fieldValue);
+                        break;
+                    case 'id':
+                        pendingId = fieldValue;
+                        break;
+                    default:
+                        break;
+                }
+            }
+        }
+        // Flush any final unterminated event.
+        for (const final of flushAndYield())
+            yield final;
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // best-effort
+        }
+        if (!internalAbort.signal.aborted)
+            internalAbort.abort();
+    }
+    // Reference pendingEvent/pendingId so the linter doesn't flag them as
+    // unused; they're consumed via flushAndYield's closure but TS can't see
+    // that across a generator boundary.
+    void pendingEvent;
+    void pendingId;
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

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