@ezghcloud/workflows 0.0.0-stage → 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,209 @@
+import type { RetryPolicy, SDKInfo, WireError } from "./protocol/index.ts";
+import type { FetchLike } from "./runtime/live.ts";
+export type RunStatus = "running" | "cancelling" | "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
+export interface RunStep {
+    seq: number;
+    stepId: string;
+    name: string;
+    kind: string;
+    status: string;
+    attempt: number;
+    hasOutput: boolean;
+    error: WireError | null;
+}
+export interface Run {
+    id: string;
+    runKey: string | null;
+    appId: string;
+    workflow: string;
+    status: RunStatus;
+    attempt: number;
+    error: WireError | null;
+    causeStepId: string | null;
+    steps: RunStep[];
+    createdAt: string;
+    updatedAt: string;
+    endedAt: string | null;
+}
+export interface RunEvent {
+    id: string;
+    at: string;
+    type: string;
+    stepId: string | null;
+    invocationId: string | null;
+    deployment: string | null;
+    detail: unknown;
+}
+export interface AppWorkflow {
+    name: string;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+export interface App {
+    id: string;
+    slug: string;
+    resourceName: string;
+    organizationId: string;
+    projectId: string;
+    name: string;
+    kind: "push" | "pull" | (string & {});
+    endpoint: string | null;
+    syncStatus: "unsynced" | "synced" | "failed" | (string & {});
+    workflows: AppWorkflow[];
+    maxInvocationSeconds: number | null;
+    protocolVersion: string | null;
+    sdk: SDKInfo | null;
+    deployment: string | null;
+    health: string;
+    lastSyncAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    queue?: string | null;
+    partitions?: number | null;
+}
+export interface Schedule {
+    id: string;
+    resourceName: string;
+    appId: string;
+    workflow: string;
+    name: string;
+    cron: string;
+    timeZone: string;
+    overlap: "skip" | "allow" | "bufferOne" | (string & {});
+    jitterSeconds: number;
+    catchupWindowSeconds: number;
+    paused: boolean;
+    revision: number;
+    nextFireAt: string | null;
+    nextScheduledTime: string | null;
+    lastScheduledTime: string | null;
+    activeRunId: string | null;
+    missed: number;
+    skipped: number;
+    hasInput: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ScheduleSummary {
+    id: string;
+    resourceName: string;
+    appId: string;
+    workflow: string;
+    name: string;
+    cron: string;
+    timeZone: string;
+    paused: boolean;
+    revision: number;
+    updatedAt: string;
+}
+export interface ScheduleInput {
+    appId: string;
+    workflow: string;
+    name: string;
+    cron: string;
+    timeZone?: string;
+    input?: unknown;
+    overlap?: "skip" | "allow" | "bufferOne";
+    jitterSeconds?: number;
+    catchupWindowSeconds?: number;
+    paused?: boolean;
+}
+export type ScheduleUpdate = Partial<Omit<ScheduleInput, "appId" | "paused">>;
+export interface AppWithSecret {
+    app: App;
+    signingSecret: string | null;
+}
+export declare class WorkflowsApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfterSeconds?: number | undefined;
+    name: string;
+    constructor(status: number, code: string, message: string, retryAfterSeconds?: number | undefined);
+}
+export interface ClientOptions {
+    apiKey: string;
+    organizationId: string;
+    projectId: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+    retries?: number;
+    maxRetryDelayMs?: number;
+    timeoutMs?: number;
+}
+export declare function completeCallbackURL(url: string, value: unknown, opts?: {
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare class Client {
+    #private;
+    constructor(opts: ClientOptions);
+    private call;
+    private send;
+    private withSecret;
+    createApp(name: string, opts?: {
+        endpoint?: string;
+        kind?: "push" | "pull";
+        queue?: string;
+        partitions?: number;
+        idempotencyKey?: string;
+    }): Promise<AppWithSecret>;
+    getApp(appId: string): Promise<App>;
+    listApps(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        apps: App[];
+        nextCursor: string | null;
+    }>;
+    devApp(opts?: {
+        user?: string;
+        name?: string;
+        partitions?: number;
+    }): Promise<App>;
+    sync(appId: string, opts?: {
+        endpoint?: string;
+        deployment?: string;
+    }): Promise<App>;
+    rotateSecret(appId: string): Promise<AppWithSecret>;
+    start(appId: string, workflow: string, input?: unknown, opts?: {
+        runKey?: string;
+        idempotencyKey?: string;
+    }): Promise<Run>;
+    get(runId: string): Promise<Run>;
+    cancel(runId: string, opts?: {
+        gracePeriodSeconds?: number;
+    }): Promise<Run>;
+    retry(runId: string): Promise<Run>;
+    output(runId: string): Promise<unknown>;
+    input(runId: string): Promise<unknown>;
+    stepOutput(runId: string, stepId: string): Promise<unknown>;
+    events(runId: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        events: RunEvent[];
+        nextCursor: string | null;
+    }>;
+    createSchedule(input: ScheduleInput, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schedule>;
+    getSchedule(scheduleId: string): Promise<Schedule>;
+    listSchedules(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        schedules: ScheduleSummary[];
+        nextCursor: string | null;
+    }>;
+    updateSchedule(scheduleId: string, patch: ScheduleUpdate, opts: {
+        revision: number;
+    }): Promise<Schedule>;
+    pauseSchedule(scheduleId: string): Promise<Schedule>;
+    resumeSchedule(scheduleId: string): Promise<Schedule>;
+    deleteSchedule(scheduleId: string): Promise<void>;
+    triggerSchedule(scheduleId: string, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Run>;
+    scheduleInput(scheduleId: string): Promise<unknown>;
+    completeCallback(runId: string, stepId: string, value: unknown): Promise<Run>;
+}

package/dist/client.js

@@ -0,0 +1,259 @@
+import { devQueue } from "./worker.js";
+// An error answer from the Workflows API: the HTTP status and the platform error code. Status 0
+// with code "outcome_unknown": the request may or may not have taken effect (a network error on
+// createApp or rotateSecret, which aren't resent; see there).
+export class WorkflowsApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    name = "WorkflowsApiError";
+    constructor(status, code, message, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const id = encodeURIComponent;
+const DEFAULT_TIMEOUT_MS = 30_000;
+// What an answer to a request that returns a secret (createApp, rotateSecret) can't be resent on:
+// the request may have taken effect, and its replay returns no secret.
+const outcomeUnknown = (why) => new WorkflowsApiError(0, "outcome_unknown", `${why}, so the request may have taken effect: a resend would return no secret. Check with getApp, and rotate the app's secret if you didn't receive it.`);
+function checkLimit(limit) {
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+        throw new TypeError("limit is a whole number ≥ 1");
+}
+function apiError(res, data) {
+    const e = data?.error;
+    const ra = Number(res.headers.get("Retry-After"));
+    if (res.status >= 300 && res.status < 400)
+        return new WorkflowsApiError(res.status, "redirect", `The API answered a redirect (${res.status}); requests are never redirected, so check baseUrl`);
+    return new WorkflowsApiError(res.status, e?.code ?? "unknown", e?.message ?? `HTTP ${res.status}`, Number.isFinite(ra) && ra >= 0 && res.headers.get("Retry-After") !== null ? ra : undefined);
+}
+// completeCallbackURL completes a callback by its URL (step.createCallback's url): it POSTs value
+// as JSON with no credential (the URL's token is the credential, so errors never include it). The
+// first completion wins: the same value again succeeds, a different one is 409
+// callback_completed, and after the timeout or the run's end it's 410 callback_expired.
+export async function completeCallbackURL(url, value, opts = {}) {
+    const fetchImpl = opts.fetch ?? ((u, i) => fetch(u, i));
+    let res;
+    try {
+        res = await fetchImpl(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(value === undefined ? null : value),
+            redirect: "manual", signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) });
+    }
+    catch (e) {
+        throw new WorkflowsApiError(0, "network_error", `Completing the callback failed in transit: ${e instanceof Error ? e.name : "error"}`);
+    }
+    const text = await res.text();
+    if (res.ok)
+        return;
+    let data;
+    try {
+        data = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        data = undefined;
+    }
+    throw apiError(res, data);
+}
+// Client calls the Workflows API for one project: apps (create, sync, rotate the secret) and runs
+// (start, inspect, cancel, retry, payloads, events).
+export class Client {
+    // ES private fields: the API key never shows in console.log, util.inspect or JSON.stringify.
+    #apiKey;
+    #base;
+    #fetch;
+    #retries;
+    #maxDelay;
+    #timeout;
+    constructor(opts) {
+        this.#apiKey = opts.apiKey;
+        this.#base = `${(opts.baseUrl ?? "https://workflows-api.ezghcloud.com").replace(/\/+$/, "")}/v1/organizations/${id(opts.organizationId)}/projects/${id(opts.projectId)}`;
+        this.#fetch = opts.fetch ?? ((u, i) => fetch(u, i));
+        this.#retries = opts.retries ?? 3;
+        this.#maxDelay = opts.maxRetryDelayMs ?? 10_000;
+        if (!Number.isInteger(this.#retries) || this.#retries < 0)
+            throw new TypeError("retries is a whole number ≥ 0");
+        if (!Number.isFinite(this.#maxDelay) || this.#maxDelay < 0)
+            throw new TypeError("maxRetryDelayMs is a number ≥ 0");
+        this.#timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(this.#timeout) || this.#timeout <= 0)
+            throw new TypeError("timeoutMs is a number > 0");
+    }
+    // call sends one request, retrying 429, 503, a 409 idempotency_in_progress and network errors
+    // (timeouts included) with the same Idempotency-Key, after Retry-After. Redirects are errors.
+    // returnsSecret (createApp, rotateSecret): only a 429 is retried; a network error, 503 or 409
+    // in progress is outcome_unknown, since the request may have taken effect and its replay would
+    // return no secret.
+    call(method, path, body, idempotencyKey, returnsSecret = false, extraHeaders = {}) {
+        if (idempotencyKey !== undefined && (typeof idempotencyKey !== "string" || idempotencyKey === ""))
+            throw new TypeError("An idempotencyKey is a non-empty string");
+        return this.send(method, path, body, idempotencyKey, returnsSecret, extraHeaders);
+    }
+    async send(method, path, body, idempotencyKey, returnsSecret, extraHeaders) {
+        const headers = { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", ...extraHeaders };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (method !== "GET")
+            headers["Idempotency-Key"] = idempotencyKey ?? crypto.randomUUID();
+        const retries = this.#retries;
+        const maxDelay = this.#maxDelay;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(this.#base + path, { method, headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), redirect: "manual", signal: AbortSignal.timeout(this.#timeout) });
+            }
+            catch (e) {
+                if (returnsSecret)
+                    throw outcomeUnknown(`The request failed in transit (${e instanceof Error ? e.message : String(e)})`);
+                if (attempt >= retries)
+                    throw e;
+                await sleep(Math.min(maxDelay, 500 * 2 ** attempt));
+                continue;
+            }
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                data = undefined;
+            }
+            if (res.ok)
+                return data;
+            const err = apiError(res, data);
+            const inProgress = res.status === 409 && err.code === "idempotency_in_progress";
+            if (returnsSecret && (res.status === 503 || inProgress))
+                throw outcomeUnknown(`The API answered ${res.status} ${err.code}`);
+            if ((res.status !== 429 && res.status !== 503 && !inProgress) || attempt >= retries)
+                throw err;
+            await sleep(Math.min(maxDelay, (err.retryAfterSeconds ?? 1) * 1000));
+        }
+    }
+    // withSecret is a secret-bearing answer: a push app's success without its secret is the replay of
+    // an earlier request (an Idempotency-Key reused), and the secret is lost: outcome_unknown.
+    async withSecret(p, pull = false) {
+        const r = await p;
+        if (!pull && r?.signingSecret == null)
+            throw outcomeUnknown("The API answered with no signing secret (the replay of an earlier request with this Idempotency-Key)");
+        return r;
+    }
+    // Apps
+    // createApp returns the app and its signing secret, once. An answer that leaves it unknown
+    // whether the app was created (a network error, a timeout, a 503, a 409 in progress, or a
+    // replay's null secret) throws outcome_unknown: a resend would return no secret. A 429 (not
+    // processed) is retried. A pull app has no secret.
+    createApp(name, opts = {}) {
+        const kind = opts.kind ?? "push";
+        return this.withSecret(this.call("POST", "/apps", { name, kind, ...(opts.endpoint ? { endpoint: opts.endpoint } : {}), ...(opts.queue ? { queue: opts.queue } : {}), ...(opts.partitions !== undefined ? { partitions: opts.partitions } : {}) }, opts.idempotencyKey, true), kind === "pull");
+    }
+    getApp(appId) { return this.call("GET", `/apps/${id(appId)}`); }
+    listApps(opts = {}) {
+        checkLimit(opts.limit);
+        const q = new URLSearchParams();
+        if (opts.cursor)
+            q.set("cursor", opts.cursor);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        return this.call("GET", `/apps${qs ? `?${qs}` : ""}`);
+    }
+    // devApp creates, or finds, a developer's own pull app for dev mode: named and queued
+    // devQueue(user) (dev-<user>), so worker({ app: app.id, dev: true }) polls it. The live host
+    // serves only an app's own queue, so each developer needs an app of their own.
+    async devApp(opts = {}) {
+        const queue = devQueue(opts.user);
+        const name = opts.name ?? queue;
+        try {
+            return (await this.createApp(name, { kind: "pull", queue, ...(opts.partitions !== undefined ? { partitions: opts.partitions } : {}) })).app;
+        }
+        catch (e) {
+            // It exists (409 app_exists), or the create's outcome is unknown: find it by name.
+            if (!(e instanceof WorkflowsApiError && ((e.status === 409 && e.code === "app_exists") || e.code === "outcome_unknown")))
+                throw e;
+        }
+        for (let cursor;;) {
+            const page = await this.listApps({ limit: 100, ...(cursor ? { cursor } : {}) });
+            const app = page.apps.find((a) => a.name === name);
+            if (app) {
+                if (app.kind !== "pull" || app.queue !== queue)
+                    throw new WorkflowsApiError(409, "app_exists", `The app "${name}" exists but isn't a pull app with the queue ${queue}; pass devApp({ name }) another name`);
+                return app;
+            }
+            if (!page.nextCursor)
+                throw new WorkflowsApiError(404, "not_found", `The dev app "${name}" was neither created nor found`);
+            cursor = page.nextCursor;
+        }
+    }
+    // sync asks EZGH to call the app's endpoint and record its workflows; run it after each deploy.
+    // A failed sync is a 409 sync_failed.
+    sync(appId, opts = {}) {
+        return this.call("POST", `/apps/${id(appId)}/sync`, opts);
+    }
+    // rotateSecret returns a new signing secret; the old ones stay valid for 24 hours.
+    // A network error isn't resent, as for createApp (outcome_unknown).
+    rotateSecret(appId) { return this.withSecret(this.call("POST", `/apps/${id(appId)}/rotate-secret`, {}, undefined, true)); }
+    // Runs
+    // start a run: 201 for a new run. With runKey, starting again with the same workflow and input
+    // returns the same run, and different input is a 409 run_key_conflict.
+    start(appId, workflow, input, opts = {}) {
+        return this.call("POST", "/runs", { appId, workflow, ...(input !== undefined ? { input } : {}), ...(opts.runKey ? { runKey: opts.runKey } : {}) }, opts.idempotencyKey);
+    }
+    get(runId) { return this.call("GET", `/runs/${id(runId)}`); }
+    // cancel: the run is cancelling; its code gets gracePeriodSeconds (0–3600, default 300) to clean up.
+    cancel(runId, opts = {}) {
+        return this.call("POST", `/runs/${id(runId)}/cancel`, opts.gracePeriodSeconds === undefined ? {} : { gracePeriodSeconds: opts.gracePeriodSeconds });
+    }
+    // retry a failed run from its failed step; completed steps aren't run again.
+    retry(runId) { return this.call("POST", `/runs/${id(runId)}/retry`, {}); }
+    // The run's output (workflows.runs.getPayload); 409 run_not_completed until it completes.
+    output(runId) { return this.call("GET", `/runs/${id(runId)}/payloads/output`); }
+    input(runId) { return this.call("GET", `/runs/${id(runId)}/payloads/input`); }
+    stepOutput(runId, stepId) { return this.call("GET", `/runs/${id(runId)}/steps/${id(stepId)}/output`); }
+    events(runId, opts = {}) {
+        checkLimit(opts.limit);
+        const q = new URLSearchParams();
+        if (opts.cursor)
+            q.set("cursor", opts.cursor);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        return this.call("GET", `/runs/${id(runId)}/events${qs ? `?${qs}` : ""}`);
+    }
+    // Schedules: cron schedules that start runs of one workflow (design-phase-2 "Schedules"), with
+    // the workflows.schedules.* actions.
+    createSchedule(input, opts = {}) { return this.call("POST", "/schedules", input, opts.idempotencyKey); }
+    getSchedule(scheduleId) { return this.call("GET", `/schedules/${id(scheduleId)}`); }
+    listSchedules(opts = {}) {
+        checkLimit(opts.limit);
+        const q = new URLSearchParams();
+        if (opts.cursor)
+            q.set("cursor", opts.cursor);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        return this.call("GET", `/schedules${qs ? `?${qs}` : ""}`);
+    }
+    // updateSchedule changes the given fields. revision is the schedule's revision you read
+    // (If-Match): a change since then answers 412.
+    updateSchedule(scheduleId, patch, opts) {
+        return this.call("PATCH", `/schedules/${id(scheduleId)}`, patch, undefined, false, { "If-Match": `"${opts.revision}"` });
+    }
+    pauseSchedule(scheduleId) { return this.call("POST", `/schedules/${id(scheduleId)}/pause`, {}); }
+    // resumeSchedule fires again from now, with no catch-up.
+    resumeSchedule(scheduleId) { return this.call("POST", `/schedules/${id(scheduleId)}/resume`, {}); }
+    async deleteSchedule(scheduleId) { await this.call("DELETE", `/schedules/${id(scheduleId)}`); }
+    // triggerSchedule starts a run now. The Idempotency-Key names the run, so the same key always
+    // answers the same run (without one, each call starts a new run).
+    triggerSchedule(scheduleId, opts = {}) { return this.call("POST", `/schedules/${id(scheduleId)}/trigger`, {}, opts.idempotencyKey); }
+    // The input every run of the schedule gets (workflows.runs.getPayload); null when none.
+    scheduleInput(scheduleId) { return this.call("GET", `/schedules/${id(scheduleId)}/payloads/input`); }
+    // Callbacks
+    // completeCallback completes a waiting callback as an authenticated caller
+    // (workflows.callbacks.complete, in the workflows:runs scope) and answers the run. The first
+    // completion wins: the same value again succeeds, a different one is 409 callback_completed,
+    // and after the timeout or the run's end it's 410 callback_expired. The public alternative is
+    // POSTing the value to the callback's URL.
+    completeCallback(runId, stepId, value) { return this.call("POST", `/runs/${id(runId)}/callbacks/${id(stepId)}`, value === undefined ? null : value); }
+}

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare function cleanDeployment(s: string | undefined): string | undefined;
+export declare function detectDeployment(): string | undefined;

package/dist/env.js

@@ -0,0 +1,32 @@
+import { truncateUtf8 } from "./protocol/bytes.js";
+// The longest deployment label the engine stores (internal/protocol MaxDeploymentLen), in bytes.
+const MAX_DEPLOYMENT_BYTES = 256;
+// cleanDeployment: a deployment label as the engine takes it: NUL characters removed, cut to
+// 256 bytes of UTF-8. Empty is none.
+export function cleanDeployment(s) {
+    if (typeof s !== "string")
+        return undefined;
+    return truncateUtf8(s.replaceAll("\u0000", ""), MAX_DEPLOYMENT_BYTES) || undefined;
+}
+// Deployment IDs from the platform's environment (design, "Runs continue on whatever code is
+// deployed"): Vercel, AWS Lambda (function:version, but not $LATEST), Cloud Run, Fly.io and Render.
+export function detectDeployment() {
+    try {
+        // Deno throws on process.env without --allow-env.
+        const env = globalThis.process?.env;
+        if (!env)
+            return undefined;
+        if (env.VERCEL_DEPLOYMENT_ID)
+            return cleanDeployment(env.VERCEL_DEPLOYMENT_ID);
+        const fn = env.AWS_LAMBDA_FUNCTION_NAME, version = env.AWS_LAMBDA_FUNCTION_VERSION;
+        if (fn && version && version !== "$LATEST")
+            return cleanDeployment(`${fn}:${version}`);
+        for (const k of ["K_REVISION", "FLY_MACHINE_VERSION", "RENDER_GIT_COMMIT"])
+            if (env[k])
+                return cleanDeployment(env[k]);
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { SDK_NAME, SDK_VERSION } from "./version.ts";
+export { workflow } from "./runtime/workflow.ts";
+export type { Workflow, WorkflowOptions } from "./runtime/workflow.ts";
+export type { WorkflowContext, Step, StepRunContext, StepRunOptions, Jsonify, Callback, CreateCallbackOptions, InvokeOptions, ReceivedMessage, WaitForMessageOptions } from "./runtime/context.ts";
+export { NonRetriableError, RetryAfterError, CancelledError, WorkflowError, CallbackTimeout, ChildFailed } from "./runtime/errors.ts";
+export { serve } from "./serve.ts";
+export type { ServeOptions } from "./serve.ts";
+export { Client, WorkflowsApiError, completeCallbackURL } from "./client.ts";
+export type { App, AppWithSecret, AppWorkflow, ClientOptions, Run, RunEvent, RunStatus, RunStep, Schedule, ScheduleInput, ScheduleSummary, ScheduleUpdate } from "./client.ts";
+export type { FetchLike } from "./runtime/live.ts";
+export type { RetryPolicy, ScheduleInfo } from "./protocol/types.ts";
+export { worker, devQueue, WorkerAuthError, WorkerConfigError } from "./worker.ts";
+export type { Worker, WorkerOptions } from "./worker.ts";
+export { QueuesClient, QueuesApiError } from "./queues.ts";
+export type { QueuesClientOptions, QueueMessageInput, SentMessage, SentMessages } from "./queues.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { SDK_NAME, SDK_VERSION } from "./version.js";
+export { workflow } from "./runtime/workflow.js";
+export { NonRetriableError, RetryAfterError, CancelledError, WorkflowError, CallbackTimeout, ChildFailed } from "./runtime/errors.js";
+export { serve } from "./serve.js";
+export { Client, WorkflowsApiError, completeCallbackURL } from "./client.js";
+export { worker, devQueue, WorkerAuthError, WorkerConfigError } from "./worker.js";
+export { QueuesClient, QueuesApiError } from "./queues.js";

package/dist/protocol/bytes.d.ts

@@ -0,0 +1,8 @@
+export declare const utf8: (s: string) => Uint8Array<ArrayBuffer>;
+export declare function toHex(b: Uint8Array): string;
+export declare function fromHex(h: string): Uint8Array<ArrayBuffer>;
+export declare function toBase64url(b: Uint8Array): string;
+export declare function fromBase64url(s: string): Uint8Array<ArrayBuffer>;
+export declare function concat(a: Uint8Array, b: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare const utf8Length: (s: string) => number;
+export declare function truncateUtf8(s: string, maxBytes: number): string;

package/dist/protocol/bytes.js

@@ -0,0 +1,49 @@
+export const utf8 = (s) => new TextEncoder().encode(s);
+export function toHex(b) {
+    let s = "";
+    for (const x of b)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+export function fromHex(h) {
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(h.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+export function toBase64url(b) {
+    let bin = "";
+    for (const x of b)
+        bin += String.fromCharCode(x);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// fromBase64url decodes unpadded base64url strictly: only the canonical encoding of the bytes is
+// accepted (Go's base64.RawURLEncoding.Strict()), so one secret has exactly one text form.
+export function fromBase64url(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s) || s.length % 4 === 1)
+        throw new TypeError("not base64url");
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    if (toBase64url(out) !== s)
+        throw new TypeError("not canonical base64url");
+    return out;
+}
+export function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+export const utf8Length = (s) => utf8(s).length;
+// truncateUtf8 cuts s to at most maxBytes of UTF-8, never inside a code point.
+export function truncateUtf8(s, maxBytes) {
+    const b = utf8(s);
+    if (b.length <= maxBytes)
+        return s;
+    let cut = maxBytes;
+    while (cut > 0 && (b[cut] & 0xc0) === 0x80)
+        cut--;
+    return new TextDecoder().decode(b.subarray(0, cut));
+}

package/dist/protocol/callback.d.ts

@@ -0,0 +1,6 @@
+export declare function mintCallbackToken(shard: number, random?: (n: number) => Uint8Array): string;
+export declare function parseCallbackToken(token: string): {
+    shard: number;
+    secret: Uint8Array;
+};
+export declare function callbackTokenHash(token: string): Promise<string>;

package/dist/protocol/callback.js

@@ -0,0 +1,31 @@
+import { fromBase64url, toBase64url, toHex } from "./bytes.js";
+// Callback tokens (design-phase-2, "Callbacks"): "<shard 3 lowercase hex>.<43 base64url>", 256
+// random bits. The shard is the run's, so workflows-api routes a completion without a lookup; the
+// engine stores SHA-256 of the secret (internal/protocol CallbackToken).
+const TOKEN = /^([0-9a-f]{3})\.([A-Za-z0-9_-]{43})$/;
+export function mintCallbackToken(shard, random = (n) => crypto.getRandomValues(new Uint8Array(n))) {
+    if (!Number.isInteger(shard) || shard < 0 || shard > 1023)
+        throw new TypeError("A callback token's shard is 0–1023");
+    const secret = random(32);
+    if (secret.length !== 32)
+        throw new TypeError("A callback token's secret is 32 bytes");
+    return `${shard.toString(16).padStart(3, "0")}.${toBase64url(secret)}`;
+}
+// parseCallbackToken parses the wire form strictly (lowercase hex, canonical base64url).
+export function parseCallbackToken(token) {
+    const m = typeof token === "string" ? TOKEN.exec(token) : null;
+    if (!m)
+        throw new TypeError("Not a callback token");
+    const shard = parseInt(m[1], 16);
+    if (shard > 1023)
+        throw new TypeError("Not a callback token: the shard is out of range");
+    const secret = fromBase64url(m[2]);
+    if (secret.length !== 32)
+        throw new TypeError("Not a callback token: the secret isn't 32 bytes");
+    return { shard, secret };
+}
+// callbackTokenHash: lowercase hex SHA-256 of the token's secret (what the engine stores).
+export async function callbackTokenHash(token) {
+    const { secret } = parseCallbackToken(token);
+    return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", secret)));
+}

package/dist/protocol/codec.d.ts

@@ -0,0 +1,6 @@
+import type { RetryPolicy } from "./types.ts";
+export declare const MAX_OUTPUT_BYTES = 1048576;
+export declare function encodeValue(v: unknown): unknown;
+export declare function jsonByteLength(v: unknown): number;
+export declare function parseDuration(d: string | number): number;
+export declare function backoff(p: RetryPolicy, attempt: number): number;