@w6w/sdk 0.1.0

package/dist/src/vars.js

@@ -0,0 +1,149 @@
+/**
+ * `client.vars.*` — typed variables, addressed the way the server addresses
+ * them.
+ *
+ * Six operations, one HTTP call each. **Create by `name`, read by id or by
+ * name, update and delete by id** (`docs/implementation.md` §7, D6 amended by
+ * D12). No client-side list-then-filter: `getByName` targets a real route,
+ * `GET /vars/by-name/{name}` (verified live 2026-07-28).
+ *
+ * **There is no scoping query parameter on any variable operation, and this
+ * module cannot invent one.** Variables are scoped by tenant/subject only; the
+ * server's `vars` routes read no such parameter and the table has no column for
+ * it, while every document route does — so the two asset surfaces are
+ * deliberately asymmetric (`docs/implementation.md` §7, and `src/documents.ts`
+ * for the other half). The asymmetry is enforced structurally rather than by
+ * discipline: {@linkcode VarsHost} exposes the transport and **not** the
+ * client's resolved configuration, so nothing in this file can reach a default
+ * scope to send even by accident. Adding the parameter later, once the server
+ * honours it, is purely additive; adding it now would be an argument the server
+ * ignores — a lie that typechecks.
+ *
+ * @module
+ */
+import { path } from "./http.js";
+import { unwrap } from "./types.js";
+/**
+ * The `vars` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const v = await client.vars.create({ name: "sender_email", type: "string", value: "a@b.c" });
+ * await client.vars.update(v.id, { value: "c@d.e" });
+ * await client.vars.delete(v.id);
+ * ```
+ */
+export class VarsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's variables.
+     *
+     * @returns The variables, unwrapped from the `vars` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async list() {
+        const res = await this.#host.request({ method: "GET", path: "/vars" });
+        return unwrap(res, "vars");
+    }
+    /**
+     * Fetch one variable by its server-issued id.
+     *
+     * @param id - The `var_…` id.
+     * @returns The variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    async get(id) {
+        const res = await this.#host.request({ method: "GET", path: path `/vars/${id}` });
+        // The singular envelope key is `var` — a reserved word in TypeScript, so it
+        // is read as a property and never destructured into a binding.
+        return unwrap(res, "var");
+    }
+    /**
+     * Fetch one variable by the `name` its author chose.
+     *
+     * The name is percent-encoded at interpolation by the `path` tag. The server's
+     * own rule (`^[a-z_][a-z0-9_]*$`) contains nothing that needs encoding — but
+     * that rule is the *server's* to enforce, and this method encodes rather than
+     * validates: a name the server accepts is sent as-is (encoded), and a name it
+     * rejects comes back as `400 invalid_name` from the one place that owns the
+     * rule, instead of as a client-side error that would go stale the moment the
+     * rule changed.
+     *
+     * @param name - The variable name, sent encoded and otherwise untouched.
+     * @returns The variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such name.
+     */
+    async getByName(name) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/vars/by-name/${name}`,
+        });
+        return unwrap(res, "var");
+    }
+    /**
+     * Create a typed variable under a caller-chosen name.
+     *
+     * @param input - `name`, `type` and `value` are required.
+     * @returns The created variable (the server answers `201`).
+     * @throws {ApiError} `409 var_exists` on a duplicate name — the code reaches the caller intact.
+     */
+    async create(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/vars",
+            // Assembled field by field rather than forwarded wholesale: the body that
+            // goes on the wire is exactly the four documented fields, and `undefined`
+            // ones are dropped by JSON serialisation.
+            body: {
+                name: input.name,
+                type: input.type,
+                value: input.value,
+                description: input.description,
+            },
+        });
+        return unwrap(res, "var");
+    }
+    /**
+     * Patch a variable's type, value or description.
+     *
+     * Addressed by id, never by name, and the name itself cannot be changed.
+     *
+     * @param id - The `var_…` id.
+     * @param patch - The fields to change; omitted fields are left alone.
+     * @returns The updated variable.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    async update(id, patch) {
+        const res = await this.#host.request({
+            method: "PATCH",
+            path: path `/vars/${id}`,
+            body: {
+                type: patch.type,
+                value: patch.value,
+                description: patch.description,
+            },
+        });
+        return unwrap(res, "var");
+    }
+    /**
+     * Delete a variable.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a caller
+     * can use. Deleting an unknown id is `404 unknown_var`, **not** a silent
+     * success — the delete is not idempotent and this method does not pretend
+     * otherwise.
+     *
+     * @param id - The `var_…` id.
+     * @throws {ApiError} `404 unknown_var` when there is no such id.
+     */
+    async delete(id) {
+        await this.#host.request({ method: "DELETE", path: path `/vars/${id}` });
+    }
+}
+//# sourceMappingURL=vars.js.map

package/dist/src/vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.js","sourceRoot":"","sources":["../../src/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,MAAM,EAA0B,MAAM,YAAY,CAAC;AAiD5D;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAO;IACT,KAAK,CAAW;IAEzB;;OAEG;IACH,YAAY,IAAc;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChF,OAAO,MAAM,CAAQ,GAAG,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAA,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1F,4EAA4E;QAC5E,+DAA+D;QAC/D,OAAO,MAAM,CAAM,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,SAAS,CAAC,IAAY;QAC1B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,iBAAiB,IAAI,EAAE;SAClC,CAAC,CAAC;QACH,OAAO,MAAM,CAAM,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,KAAqB;QAChC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,OAAO;YACb,0EAA0E;YAC1E,0EAA0E;YAC1E,0CAA0C;YAC1C,IAAI,EAAE;gBACJ,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B;SACF,CAAC,CAAC;QACH,OAAO,MAAM,CAAM,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,KAAe;QACtC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,IAAI,CAAA,SAAS,EAAE,EAAE;YACvB,IAAI,EAAE;gBACJ,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B;SACF,CAAC,CAAC;QACH,OAAO,MAAM,CAAM,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAA,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IACnF,CAAC;CACF"}

package/dist/src/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The published version of this package.
+ *
+ * It is the same string as `deno.json`'s `version`, `package.json`'s `version`
+ * and the monorepo's `packages/wrappers/VERSION` — the single source of truth all
+ * three w6w wrappers publish under (see `docs/parity.md`). `tests/version_test.ts`
+ * fails if any of those four disagree, so this constant cannot drift silently.
+ *
+ * The explicit `: string` annotation is required, not decorative: JSR publishes
+ * this file as TypeScript source and rejects inferred public types ("no slow
+ * types").
+ */
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/src/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,EAAE,MAAgB,CAAC"}

package/dist/src/version.js

@@ -0,0 +1,14 @@
+/**
+ * The published version of this package.
+ *
+ * It is the same string as `deno.json`'s `version`, `package.json`'s `version`
+ * and the monorepo's `packages/wrappers/VERSION` — the single source of truth all
+ * three w6w wrappers publish under (see `docs/parity.md`). `tests/version_test.ts`
+ * fails if any of those four disagree, so this constant cannot drift silently.
+ *
+ * The explicit `: string` annotation is required, not decorative: JSR publishes
+ * this file as TypeScript source and rejects inferred public types ("no slow
+ * types").
+ */
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAW,OAAO,CAAC"}

package/dist/src/workflows.d.ts

@@ -0,0 +1,180 @@
+/**
+ * `client.workflows.*` — discovery and the typed run.
+ *
+ * Two operations: `list` (T2.1.4) and `run` (T2.1.5). `list` earns its place in
+ * a minimal surface for the same reason `connections.list` does (D4): it is how
+ * a caller discovers a `wf_…` id to pass to `run`.
+ *
+ * ── `run`, and the three things this API gets called wrong ──
+ * 1. **`202` is success.** No `wait` → the run is queued and the server answers
+ *    `202 {runId, status:"queued"}`. With `?wait=true` and a timeout → `202`
+ *    again, with the current status. Neither raises.
+ * 2. **A failed run is data.** `?wait=true` on a run that failed is a plain
+ *    `200` carrying `status: "failed"` and an `error`. This module returns it
+ *    like any other result. Mapping it to an exit code is the CLI's job
+ *    (`cli.exitCodes` in `endpoints.json`), not the SDK's.
+ * 3. **No client-side polling.** The server already polls internally for
+ *    `?wait=true`, up to its own `RUN_WAIT_TIMEOUT_SEC`. The studio's 600 × 500 ms
+ *    browser loop predates that and is deliberately **not** transcribed
+ *    (`docs/implementation.md` §4): three wrappers each re-implementing a poll
+ *    would be three timeout policies and three retry-storm bugs to keep in sync.
+ *    There is no timer, no delay and no retry anywhere in this package — a `202`
+ *    hands the caller `runId` and lets them decide.
+ *
+ * Workflows are **project-scoped**, like documents and unlike vars: the route
+ * accepts an optional `?project=`, resolved per call, then from the client's
+ * default, and otherwise left to the server. This host therefore sees the
+ * client's resolved configuration, which `connections` and `vars` deliberately
+ * do not.
+ *
+ * ── Pagination ──
+ * The route is **not paginated today** and this module does not pretend
+ * otherwise: there is no `cursor` argument, no `cursor` field, and no
+ * client-side paging loop. `list` returns the unwrapped array, exactly as
+ * `docs/implementation.md` §6 pins it.
+ *
+ * That is not a corner this signature is painted into. A JavaScript array is an
+ * object, so the day the server grows a cursor the wrapper can return an array
+ * that carries it (`WorkflowSummary[] & {cursor?: string}`) and widen this
+ * return type to match — every existing caller, which only ever reads the list,
+ * keeps compiling and keeps working. Inventing the field now would put a key on
+ * the type that no server has ever sent, which is the failure mode
+ * `endpoints.json` actually warns about.
+ *
+ * @module
+ */
+import type { ResolvedConfig } from "./config.ts";
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+import { type RunResult, type WorkflowSummary } from "./types.ts";
+/**
+ * The slice of `W6wClient` this namespace needs: the transport, plus the
+ * resolved configuration it reads the **default project** out of. Structural
+ * rather than a concrete client type, so the namespace stays independently
+ * constructible in a test and this module never imports the client back.
+ */
+export interface WorkflowsHost {
+    /** The resolved configuration; only `project` is read. */
+    readonly config: ResolvedConfig;
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * Per-call options for `workflows.list`.
+ *
+ * A named interface rather than a bare `project?: string` parameter, so the
+ * operation can accept a further argument later without changing its arity.
+ */
+export interface WorkflowListOptions {
+    /** Project id to scope this call to; overrides the client's default. */
+    project?: string;
+}
+/**
+ * Per-call options for `workflows.run`.
+ *
+ * **No `project` here, on purpose.** A `wf_…` id is unambiguous on its own, and
+ * `endpoints.json` gives this operation exactly four parameters — `id`, `wait`,
+ * `variables`, `trigger`. Sending a `?project=` the route does not read would be
+ * inventing a parameter.
+ */
+export interface WorkflowRunOptions {
+    /**
+     * Wait for the run to reach a terminal state before answering.
+     *
+     * Sent as `?wait=true` **only when `true`**: the server compares the raw query
+     * value to the string `"true"`, so `?wait=false` would mean the same thing as
+     * omitting it while looking like it meant something else.
+     *
+     * The wait happens **server-side**, bounded by the server's own timeout. On a
+     * timeout the answer is a `202` carrying the current status, which is a normal
+     * outcome — see {@linkcode WorkflowRunResult.terminal}.
+     */
+    wait?: boolean;
+    /** Variables handed to the run, merged into its scope by the engine. Opaque pass-through. */
+    variables?: Record<string, unknown>;
+    /**
+     * What triggered the run; defaults to `"manual"` server-side.
+     *
+     * Typed as a plain `string` rather than a closed union: the value is a
+     * server-owned enum (`"manual" | "schedule" | "webhook" | "event" | "replay"`
+     * today) that the server may extend, and an SDK that froze the set would
+     * reject a value a newer server accepts.
+     */
+    trigger?: string;
+}
+/**
+ * What `workflows.run` returns: the server's flat body, plus two signals derived
+ * locally.
+ *
+ * It **is** a `RunResult` — the wire fields are present under their wire names,
+ * unwrapped from nothing (this route has no envelope). The two extra fields
+ * exist because a caller otherwise cannot tell a queued run from a finished one
+ * without re-deriving the rule:
+ *
+ * - {@linkcode terminal} answers "has this run finished?" from the **run's own
+ *   status**, which is the question a caller actually has.
+ * - {@linkcode httpStatus} is the transport's own answer (`200` finished in
+ *   time, `202` still going), kept because it is the distinction the server
+ *   makes and dropping it would leave a caller unable to tell a `?wait=` timeout
+ *   from a run that was never waited on.
+ */
+export interface WorkflowRunResult extends RunResult {
+    /** `true` when `status` is `succeeded`, `failed` or `canceled`. */
+    terminal: boolean;
+    /** The HTTP status that carried this body: `200` terminal, `202` queued or still running. */
+    httpStatus: number;
+}
+/**
+ * The `workflows` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const active = (await client.workflows.list()).filter((w) => w.status === "active");
+ *
+ * const run = await client.workflows.run(active[0].id, { wait: true });
+ * if (run.status === "failed") console.error(run.error); // data, not an exception
+ * ```
+ */
+export declare class WorkflowsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: WorkflowsHost);
+    /**
+     * List the caller's workflow definitions.
+     *
+     * The project this call is scoped to is the per-call argument first, then the
+     * client's default, then nothing at all — an absent value means "no
+     * `?project=`", which is how the caller asks for every project the credential
+     * can see.
+     *
+     * @param options - Optional per-call project scope.
+     * @returns The workflows, unwrapped from the `workflows` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    list(options?: WorkflowListOptions): Promise<WorkflowSummary[]>;
+    /**
+     * Start a run of one workflow, optionally waiting for it to finish.
+     *
+     * Returns on **both** success statuses this route uses:
+     *
+     * | Call | HTTP | Body | `terminal` |
+     * |---|---|---|---|
+     * | no `wait` | `202` | `{runId, status:"queued"}` | `false` |
+     * | `wait: true`, finished in time | `200` | `{runId, status, output, error, steps}` | `true` |
+     * | `wait: true`, timed out | `202` | `{runId, status}` | `false` |
+     *
+     * **A run that failed is the second row, not an error**: `200` with
+     * `status: "failed"` and the failure in `error`. This method returns it. It
+     * raises only when the *request* failed — `404 unknown_workflow`, a rejected
+     * token, a transport failure.
+     *
+     * @param id - The `wf_…` id, percent-encoded into the path.
+     * @param options - `wait`, plus the `variables` and `trigger` that go in the body.
+     * @returns The run handle, its status, and the result when the run has one.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such workflow.
+     * @throws {ApiError} `bad_response` when a success body is not a run object.
+     */
+    run(id: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+}
+//# sourceMappingURL=workflows.d.ts.map

package/dist/src/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAEL,KAAK,SAAS,EAGd,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;;IAGvB;;OAEG;gBACS,IAAI,EAAE,aAAa;IAI/B;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IASrE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAyDhF"}

package/dist/src/workflows.js

@@ -0,0 +1,160 @@
+/**
+ * `client.workflows.*` — discovery and the typed run.
+ *
+ * Two operations: `list` (T2.1.4) and `run` (T2.1.5). `list` earns its place in
+ * a minimal surface for the same reason `connections.list` does (D4): it is how
+ * a caller discovers a `wf_…` id to pass to `run`.
+ *
+ * ── `run`, and the three things this API gets called wrong ──
+ * 1. **`202` is success.** No `wait` → the run is queued and the server answers
+ *    `202 {runId, status:"queued"}`. With `?wait=true` and a timeout → `202`
+ *    again, with the current status. Neither raises.
+ * 2. **A failed run is data.** `?wait=true` on a run that failed is a plain
+ *    `200` carrying `status: "failed"` and an `error`. This module returns it
+ *    like any other result. Mapping it to an exit code is the CLI's job
+ *    (`cli.exitCodes` in `endpoints.json`), not the SDK's.
+ * 3. **No client-side polling.** The server already polls internally for
+ *    `?wait=true`, up to its own `RUN_WAIT_TIMEOUT_SEC`. The studio's 600 × 500 ms
+ *    browser loop predates that and is deliberately **not** transcribed
+ *    (`docs/implementation.md` §4): three wrappers each re-implementing a poll
+ *    would be three timeout policies and three retry-storm bugs to keep in sync.
+ *    There is no timer, no delay and no retry anywhere in this package — a `202`
+ *    hands the caller `runId` and lets them decide.
+ *
+ * Workflows are **project-scoped**, like documents and unlike vars: the route
+ * accepts an optional `?project=`, resolved per call, then from the client's
+ * default, and otherwise left to the server. This host therefore sees the
+ * client's resolved configuration, which `connections` and `vars` deliberately
+ * do not.
+ *
+ * ── Pagination ──
+ * The route is **not paginated today** and this module does not pretend
+ * otherwise: there is no `cursor` argument, no `cursor` field, and no
+ * client-side paging loop. `list` returns the unwrapped array, exactly as
+ * `docs/implementation.md` §6 pins it.
+ *
+ * That is not a corner this signature is painted into. A JavaScript array is an
+ * object, so the day the server grows a cursor the wrapper can return an array
+ * that carries it (`WorkflowSummary[] & {cursor?: string}`) and widen this
+ * return type to match — every existing caller, which only ever reads the list,
+ * keeps compiling and keeps working. Inventing the field now would put a key on
+ * the type that no server has ever sent, which is the failure mode
+ * `endpoints.json` actually warns about.
+ *
+ * @module
+ */
+import { ApiError } from "./errors.js";
+import { path } from "./http.js";
+import { isTerminalRunStatus, unwrap, } from "./types.js";
+/**
+ * The `workflows` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const active = (await client.workflows.list()).filter((w) => w.status === "active");
+ *
+ * const run = await client.workflows.run(active[0].id, { wait: true });
+ * if (run.status === "failed") console.error(run.error); // data, not an exception
+ * ```
+ */
+export class WorkflowsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's workflow definitions.
+     *
+     * The project this call is scoped to is the per-call argument first, then the
+     * client's default, then nothing at all — an absent value means "no
+     * `?project=`", which is how the caller asks for every project the credential
+     * can see.
+     *
+     * @param options - Optional per-call project scope.
+     * @returns The workflows, unwrapped from the `workflows` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async list(options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/workflows",
+            query: { project: options?.project ?? this.#host.config.project ?? undefined },
+        });
+        return unwrap(res, "workflows");
+    }
+    /**
+     * Start a run of one workflow, optionally waiting for it to finish.
+     *
+     * Returns on **both** success statuses this route uses:
+     *
+     * | Call | HTTP | Body | `terminal` |
+     * |---|---|---|---|
+     * | no `wait` | `202` | `{runId, status:"queued"}` | `false` |
+     * | `wait: true`, finished in time | `200` | `{runId, status, output, error, steps}` | `true` |
+     * | `wait: true`, timed out | `202` | `{runId, status}` | `false` |
+     *
+     * **A run that failed is the second row, not an error**: `200` with
+     * `status: "failed"` and the failure in `error`. This method returns it. It
+     * raises only when the *request* failed — `404 unknown_workflow`, a rejected
+     * token, a transport failure.
+     *
+     * @param id - The `wf_…` id, percent-encoded into the path.
+     * @param options - `wait`, plus the `variables` and `trigger` that go in the body.
+     * @returns The run handle, its status, and the result when the run has one.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such workflow.
+     * @throws {ApiError} `bad_response` when a success body is not a run object.
+     */
+    async run(id, options) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/workflows/${id}/run`,
+            // `?wait=true` or no `wait` at all — never `?wait=false`, which the server
+            // reads as "no wait" anyway and which would misrepresent the request in a
+            // log or a proxy.
+            query: { wait: options?.wait ? true : undefined },
+            // Always a body, even when empty: the route parses one when the text is
+            // non-empty and defaults to `{}` otherwise, so `{}` and no body are the
+            // same request — and sending the object keeps the two optional fields at
+            // one place instead of behind a conditional.
+            body: { variables: options?.variables, trigger: options?.trigger },
+        });
+        const body = res.body;
+        // The `runId` and `status` checks are the guard, not decoration. An
+        // object-only check let `{}`, `[]`, `[{…}]` and `{"ok":true}` through and
+        // returned a `WorkflowRunResult` whose `runId: string` and `status:
+        // RunStatus` were **`undefined` at runtime** (measured) — a lie the compiler
+        // cannot catch, which becomes a `TypeError` somewhere in the caller minutes
+        // later. That is the failure this package's own `unwrap` exists to prevent.
+        //
+        // Requiring the two fields also subsumes the array case (`[].runId` is
+        // `undefined`), and makes this guard exactly as strict as its sibling in
+        // `src/run.ts`, which requires a string `kind`: two operations in one
+        // package must not disagree about what a malformed success body is. It
+        // keeps the lanes in step too — python's idiomatic `isinstance(body, dict)`
+        // rejects `[]` where `typeof [] === "object"` accepts it.
+        if (typeof body !== "object" || body === null ||
+            typeof body.runId !== "string" ||
+            typeof body.status !== "string") {
+            throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} whose body is not a run object.`, body);
+        }
+        const run = body;
+        const status = run.status;
+        return {
+            // Spread first so any field a newer server adds survives; the normalised
+            // ones below then take their pinned shape.
+            ...run,
+            runId: run.runId,
+            status,
+            // A `202` carries no `steps`. Normalised to `{}` rather than left absent,
+            // so a caller iterating a run's steps never has to branch on which status
+            // carried it — the same reason an empty list is `[]` and not `null`.
+            steps: run.steps ?? {},
+            terminal: isTerminalRunStatus(status),
+            httpStatus: res.status,
+        };
+    }
+}
+//# sourceMappingURL=workflows.js.map

package/dist/src/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAqB,IAAI,EAAuB,MAAM,WAAW,CAAC;AACzE,OAAO,EACL,mBAAmB,EAGnB,MAAM,GAEP,MAAM,YAAY,CAAC;AAmFpB;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAgB;IAE9B;;OAEG;IACH,YAAY,IAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,OAA6B;QACtC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,IAAI,SAAS,EAAE;SAC/E,CAAC,CAAC;QACH,OAAO,MAAM,CAAoB,GAAG,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,OAA4B;QAChD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,cAAc,EAAE,MAAM;YAChC,2EAA2E;YAC3E,0EAA0E;YAC1E,kBAAkB;YAClB,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE;YACjD,wEAAwE;YACxE,wEAAwE;YACxE,yEAAyE;YACzE,6CAA6C;YAC7C,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;SACnE,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACtB,oEAAoE;QACpE,0EAA0E;QAC1E,oEAAoE;QACpE,6EAA6E;QAC7E,4EAA4E;QAC5E,4EAA4E;QAC5E,EAAE;QACF,uEAAuE;QACvE,yEAAyE;QACzE,sEAAsE;QACtE,uEAAuE;QACvE,4EAA4E;QAC5E,0DAA0D;QAC1D,IACE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YACzC,OAAQ,IAA4B,CAAC,KAAK,KAAK,QAAQ;YACvD,OAAQ,IAA6B,CAAC,MAAM,KAAK,QAAQ,EACzD,CAAC;YACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,kCAAkC,EACjE,IAAI,CACL,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAA0B,CAAC;QACvC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAmB,CAAC;QACvC,OAAO;YACL,yEAAyE;YACzE,2CAA2C;YAC3C,GAAG,GAAG;YACN,KAAK,EAAE,GAAG,CAAC,KAAe;YAC1B,MAAM;YACN,0EAA0E;YAC1E,0EAA0E;YAC1E,qEAAqE;YACrE,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE;YACtB,QAAQ,EAAE,mBAAmB,CAAC,MAAM,CAAC;YACrC,UAAU,EAAE,GAAG,CAAC,MAAM;SACvB,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@w6w/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the w6w HTTP API. Thin transport, auth and error mapping — nothing else.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/w6w-io/w6w-node.git"
+  },
+  "homepage": "https://github.com/w6w-io/w6w-node#readme",
+  "bugs": "https://github.com/w6w-io/w6w-node/issues",
+  "keywords": ["w6w", "workflow", "sdk", "client", "api"],
+  "type": "module",
+  "types": "./dist/mod.d.ts",
+  "main": "./dist/mod.js",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.ts",
+      "import": "./dist/mod.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}