@w6w/sdk 0.6.0 → 0.9.8

package/dist/src/vars.d.ts

@@ -21,7 +21,7 @@
  *
  * @module
  */
-import { type HttpResponse, type RequestOptions } from "./http.ts";
+import { type CallOptions, type HttpResponse, type RequestOptions } from "./http.ts";
 import { type Var, type VarType } from "./types.ts";
 /**
  * The slice of `W6WClient` this namespace needs: the transport, and nothing
@@ -86,18 +86,20 @@ export declare class VarsApi {
     /**
      * List the caller's variables.
      *
+     * @param options - Optional per-call transport options (`signal` to abort).
      * @returns The variables, unwrapped from the `vars` envelope.
      * @throws {ApiError} On any non-2xx.
      */
-    list(): Promise<Var[]>;
+    list(options?: CallOptions): Promise<Var[]>;
     /**
      * Fetch one variable by its server-issued id.
      *
      * @param id - The `var_…` id.
+     * @param options - Optional per-call transport options (`signal` to abort).
      * @returns The variable.
      * @throws {ApiError} `404 unknown_var` when there is no such id.
      */
-    get(id: string): Promise<Var>;
+    get(id: string, options?: CallOptions): Promise<Var>;
     /**
      * Fetch one variable by the `name` its author chose.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"vars.d.ts","sourceRoot":"","sources":["../../src/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAU,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAGlB;;OAEG;gBACS,IAAI,EAAE,QAAQ;IAI1B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAK5B;;;;;;OAMG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAOnC;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQ3C;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBjD;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAavD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}
+{"version":3,"file":"vars.d.ts","sourceRoot":"","sources":["../../src/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAU,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAGlB;;OAEG;gBACS,IAAI,EAAE,QAAQ;IAI1B;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IASjD;;;;;;;OAOG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAW1D;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQ3C;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBjD;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAavD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/src/vars.js

@@ -44,22 +44,32 @@ export class VarsApi {
     /**
      * List the caller's variables.
      *
+     * @param options - Optional per-call transport options (`signal` to abort).
      * @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" });
+    async list(options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/vars",
+            signal: options?.signal,
+        });
         return unwrap(res, "vars");
     }
     /**
      * Fetch one variable by its server-issued id.
      *
      * @param id - The `var_…` id.
+     * @param options - Optional per-call transport options (`signal` to abort).
      * @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}` });
+    async get(id, options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/vars/${id}`,
+            signal: options?.signal,
+        });
         // 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");

package/dist/src/vars.js.map

@@ -1 +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"}
+{"version":3,"file":"vars.js","sourceRoot":"","sources":["../../src/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAuC,IAAI,EAAuB,MAAM,WAAW,CAAC;AAC3F,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;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,OAAqB;QAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAC;QACH,OAAO,MAAM,CAAQ,GAAG,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,OAAqB;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,SAAS,EAAE,EAAE;YACvB,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAC;QACH,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.js

@@ -10,5 +10,5 @@
  * this file as TypeScript source and rejects inferred public types ("no slow
  * types").
  */
-export const VERSION = "0.6.0";
+export const VERSION = "0.9.8";
 //# sourceMappingURL=version.js.map

package/dist/src/workflows.d.ts

@@ -1,9 +1,35 @@
 /**
- * `client.workflows.*` — discovery and the typed run.
+ * `client.workflows.*` — discovery, the typed run, and the definition lifecycle.
  *
- * 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`.
+ * Eight operations: `list` (T2.1.4) and `run` (T2.1.5), `cancel` (T1.1.4), plus
+ * `get`, `create`, `update`, `archive` and `delete`. `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`.
+ *
+ * ── `cancel`, and the one thing addressed differently from its siblings ──
+ * Every other method in this class is `/workflows/…`-rooted; `cancel` alone
+ * hits `/runs/{runId}/cancel`, because it names one RUN, not the workflow that
+ * spawned it — a workflow can have many runs, and only the run id picks one
+ * out. Its `202` means the cancellation was **requested**, not that the run
+ * has stopped: the server does not wait for the transition, so the returned
+ * `status` is the run's status as it is right now (still `queued` or
+ * `running`), never `"canceled"`. Repeating the call on a run that is already
+ * marked but not yet terminal answers `202` again.
+ *
+ * ── The write path, and two things worth knowing about it ──
+ * 1. **It mints an id only when the caller sends none.** A caller-supplied
+ *    `id` on create is accepted only if it matches `^wf_[A-Za-z0-9-]{1,64}$`;
+ *    anything else is `400 invalid_workflow`. `create` still mints one
+ *    client-side (`mintId("wf")`) when the definition has none, so what
+ *    reaches the server already satisfies that grammar — every consumer that
+ *    talked to this route directly had already written that themselves,
+ *    studio's `newWorkflowId` is the same four lines.
+ * 2. **It does not patch.** There is ONE write route and it stores what it is
+ *    given, so `update` is a full replacement. `create` and `update` are the
+ *    same POST; what differs is that one mints the id and the other pins it.
+ *
+ * Deleting is two calls, `archive` then `delete`, and this module keeps it that
+ * way — see {@linkcode WorkflowsApi.delete}.
  *
  * ── `run`, and the three things this API gets called wrong ──
  * 1. **`202` is success.** No `wait` → the run is queued and the server answers
@@ -44,8 +70,8 @@
  * @module
  */
 import type { ResolvedConfig } from "./config.ts";
-import { type HttpResponse, type RequestOptions } from "./http.ts";
-import { type RunResult, type WorkflowSummary } from "./types.ts";
+import { type CallOptions, type HttpResponse, type RequestOptions } from "./http.ts";
+import { type RunResult, type RunStatus, 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
@@ -63,8 +89,11 @@ export interface WorkflowsHost {
  *
  * A named interface rather than a bare `project?: string` parameter, so the
  * operation can accept a further argument later without changing its arity.
+ *
+ * Extends {@linkcode CallOptions}, so this call also takes an optional
+ * `signal` (R-7), forwarded to the transport exactly like `project` is read.
  */
-export interface WorkflowListOptions {
+export interface WorkflowListOptions extends CallOptions {
     /** Project id to scope this call to; overrides the client's default. */
     project?: string;
 }
@@ -130,6 +159,82 @@ export interface WorkflowRunResult extends RunResult {
     /** The HTTP status that carried this body: `200` terminal, `202` queued or still running. */
     httpStatus: number;
 }
+/**
+ * A workflow definition — the portable document, kept OPAQUE.
+ *
+ * `Record<string, unknown>` and not a modelled shape, on purpose. A workflow's
+ * body is `steps[]` of node types the engine owns and extends
+ * (`rfcs/node-types.md`); a wrapper that froze that shape would reject a
+ * workflow a newer server accepts, and would have to ship a release every time
+ * a node type gained a field. What the wrapper *does* pin is the envelope
+ * around it — {@linkcode WorkflowDetail}, {@linkcode WorkflowSaveResult} —
+ * because that is the part the wrapper is responsible for.
+ *
+ * The one field this package reads out of it is `id`, in
+ * {@linkcode WorkflowsApi.create}, to decide whether to mint one.
+ */
+export type WorkflowDefinition = Record<string, unknown>;
+/** What `workflows.get` returns: the definition, plus the two things that are not in it. */
+export interface WorkflowDetail {
+    /** The stored definition, overlaid with the authoritative `status` and `tags`. */
+    workflow: WorkflowDefinition;
+    /** Where this workflow was imported from, when it was imported at all. */
+    sourceRef: string | null;
+    /**
+     * ISO-8601. The optimistic-concurrency token — pass it back as
+     * {@linkcode WorkflowWriteOptions.ifUnmodifiedSince} to make the next save
+     * conditional.
+     */
+    updatedAt: string;
+}
+/**
+ * What `workflows.cancel` returns: the run, as the server's `run` envelope
+ * carries it right after the cancel request lands.
+ *
+ * **`status` is the run's status AS IT IS NOW, not the terminal outcome of the
+ * cancellation.** The server does not wait for the transition, so this is
+ * still `"queued"` or `"running"` — never `"canceled"` — and a caller that
+ * needs to know when the run actually stopped has to re-fetch it elsewhere;
+ * this operation does not poll on the caller's behalf, for the same reason
+ * {@linkcode WorkflowsApi.run}'s own `?wait=` polling stays server-side only.
+ */
+export interface WorkflowCancelResult {
+    /** The run's `run_…` id — the same id passed in. */
+    id: string;
+    /** The run's status as of this request; still in-flight, not yet `"canceled"`. */
+    status: RunStatus;
+    /** ISO-8601. When the server recorded this cancellation request. */
+    cancelRequestedAt: string;
+}
+/** What both `workflows.create` and `workflows.update` return. */
+export interface WorkflowSaveResult {
+    /** The saved workflow's id and display name. */
+    workflow: {
+        id: string;
+        name: string;
+    };
+    /**
+     * `true` when this save also (re)applied a schedule from the definition's
+     * `trigger.cron`. A workflow that already had one is not re-scheduled, so
+     * `false` does not mean "not scheduled" — it means "not scheduled by THIS
+     * call".
+     */
+    scheduled: boolean;
+    /** The new concurrency token, so a caller can chain saves without a re-`get`. */
+    updatedAt: string;
+}
+/** Per-call options for `workflows.create` and `workflows.update`. */
+export interface WorkflowWriteOptions {
+    /** Project id to scope this write to; overrides the client's default. */
+    project?: string;
+    /**
+     * The exact `updatedAt` this client last saw. When given, the server refuses
+     * the write with `409 workflow_stale` if the stored row has moved on since —
+     * recoverable by re-reading and re-saving. Omitted, the save is
+     * last-write-wins.
+     */
+    ifUnmodifiedSince?: string | null;
+}
 /**
  * The `workflows` namespace on a `W6WClient`.
  *
@@ -139,6 +244,21 @@ export interface WorkflowRunResult extends RunResult {
  *
  * const run = await client.workflows.run(active[0].id, { wait: true });
  * if (run.status === "failed") console.error(run.error); // data, not an exception
+ *
+ * // The definition lifecycle: create, read-modify-write, then retire.
+ * const { workflow } = await client.workflows.create({
+ *   manifestVersion: "2",
+ *   name: "Nightly sync",
+ *   steps: [],
+ * });
+ * const current = await client.workflows.get(workflow.id);
+ * await client.workflows.update(
+ *   workflow.id,
+ *   { ...current.workflow, name: "Nightly sync (EU)" },
+ *   { ifUnmodifiedSince: current.updatedAt },
+ * );
+ * await client.workflows.archive(workflow.id);
+ * await client.workflows.delete(workflow.id);
  * ```
  */
 export declare class WorkflowsApi {
@@ -155,7 +275,7 @@ export declare class WorkflowsApi {
      * `?project=`", which is how the caller asks for every project the credential
      * can see.
      *
-     * @param options - Optional per-call project scope.
+     * @param options - Optional per-call project scope and/or `signal` to abort.
      * @returns The workflows, unwrapped from the `workflows` envelope.
      * @throws {ApiError} On any non-2xx.
      */
@@ -176,12 +296,144 @@ export declare class WorkflowsApi {
      * 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 id - The `wf_…` id, or the Workflow's `key`. Percent-encoded into the path.
      * @param options - `wait`, plus the `variables`, `trigger` and `input` 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>;
+    /**
+     * Cancel a queued or running workflow run.
+     *
+     * **Addressed by the RUN id, not the workflow id** — the path root is
+     * `/runs/…`, the one deliberate exception to this class's otherwise
+     * `/workflows/…`-rooted paths, because a workflow can have many runs and
+     * only the run id picks one out.
+     *
+     * **A `202` means the cancellation was requested, not that the run has
+     * stopped.** The server does not wait for the transition, so the returned
+     * {@linkcode WorkflowCancelResult.status} is the run's status as it is
+     * right now — still `queued` or `running` — and this method never reports
+     * it as `"canceled"`. Idempotent: cancelling a run that is already marked
+     * but not yet terminal answers `202` again rather than erroring.
+     *
+     * @param runId - The `run_…` id, percent-encoded into the path.
+     * @returns The run's id, its status as of this request, and when the cancellation was requested.
+     * @throws {ApiError} `404 unknown_run` — no such run, or it is not this caller's (indistinguishable on purpose).
+     * @throws {ApiError} `409 run_not_cancelable` — the run has already reached a terminal state.
+     */
+    cancel(runId: string): Promise<WorkflowCancelResult>;
+    /**
+     * Fetch one workflow's stored definition.
+     *
+     * `workflow` is the definition the server has, overlaid with the
+     * authoritative `status` and `tags` columns — so a freshly created workflow
+     * that carries neither inline still reports its real lifecycle state.
+     *
+     * **`updatedAt` is a TOP-LEVEL SIBLING of `workflow`, never a field inside
+     * it**, and that placement is load-bearing rather than incidental: the
+     * definition is the portable document (it can be exported, re-imported, or
+     * committed to a repo) and a server timestamp must not enter it. It is also
+     * the optimistic-concurrency token — hand it straight back to
+     * {@linkcode update} as `ifUnmodifiedSince` and a save that would clobber
+     * someone else's is refused instead.
+     *
+     * @param id - The `wf_…` id, percent-encoded into the path.
+     * @param options - Optional per-call transport options (`signal` to abort).
+     * @returns The definition, its source ref, and the concurrency token.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    get(id: string, options?: CallOptions): Promise<WorkflowDetail>;
+    /**
+     * Create a workflow.
+     *
+     * **The id is minted client-side when the definition does not carry one.**
+     * The server requires an `id` in the body and never generates one
+     * (`admin/workflows.ts`'s `validateDefinition`), so a `create` that simply
+     * forwarded the caller's object would answer `400 invalid_workflow` for the
+     * most natural call there is — `create({name, steps})`. A caller that wants
+     * to choose its own id still can: an `id` already present is forwarded
+     * untouched, which is what makes this method usable for a seeded or
+     * imported definition.
+     *
+     * `create` and {@linkcode update} reach the SAME upsert route, and the
+     * server does not distinguish them — the distinction is in what each one
+     * does to the body, and it is a real one: `create` mints an id, `update`
+     * pins the one you addressed. Posting a definition whose id already exists
+     * therefore OVERWRITES it; this method does not pre-check, because a
+     * check-then-write is two round trips that still race.
+     *
+     * @param definition - The whole workflow definition, forwarded verbatim apart from a minted `id`.
+     * @param options - `project` scopes the write to one project.
+     * @returns The new workflow's id and name, whether a schedule was applied, and the first `updatedAt`.
+     * @throws {ApiError} `400 invalid_workflow` — missing `name`/`steps`, or a wrong `manifestVersion`.
+     * @throws {ApiError} `400 unknown_project` — `project` names a project this account does not own.
+     * @throws {ApiError} `409 workflow_conflict` — another `(tenant, subject)` already owns that id.
+     */
+    create(definition: WorkflowDefinition, options?: WorkflowWriteOptions): Promise<WorkflowSaveResult>;
+    /**
+     * Overwrite a workflow's stored definition.
+     *
+     * **This is a full replacement, not a patch.** The server has one write
+     * route for workflows and it stores what it is given, so a field left out of
+     * `definition` is a field removed from the workflow — the same semantics as
+     * the studio's own save. Read with {@linkcode get}, change what you mean to
+     * change, and send the whole thing back.
+     *
+     * `id` is taken from the FIRST ARGUMENT and pinned into the body, overriding
+     * any `id` the definition carries. The alternative — trusting the body —
+     * makes `update("wf_a", defOfB)` silently write to B while reading as a
+     * write to A.
+     *
+     * Pass `options.ifUnmodifiedSince` (the `updatedAt` from {@linkcode get} or
+     * from a previous save) to make the write conditional. Without it the save
+     * is last-write-wins.
+     *
+     * @param id - The `wf_…` id to write to.
+     * @param definition - The whole replacement definition.
+     * @param options - `project` scopes the write; `ifUnmodifiedSince` is the concurrency precondition.
+     * @returns The workflow's id and name, whether a schedule was (re)applied, and the new `updatedAt`.
+     * @throws {ApiError} `400 invalid_workflow` / `400 invalid_precondition`.
+     * @throws {ApiError} `409 workflow_conflict` — another `(tenant, subject)` owns this id. NOT recoverable by reloading.
+     * @throws {ApiError} `409 workflow_stale` — the precondition did not match the stored `updatedAt`. IS recoverable by reloading and re-saving.
+     */
+    update(id: string, definition: WorkflowDefinition, options?: WorkflowWriteOptions): Promise<WorkflowSaveResult>;
+    /**
+     * Archive a workflow.
+     *
+     * One-way: there is no unarchive route on this domain. Idempotent —
+     * archiving an already-archived workflow re-returns it unchanged rather than
+     * erroring.
+     *
+     * This is a required step, not a convenience: {@linkcode delete} refuses a
+     * workflow that is still `draft` or `active`.
+     *
+     * @param id - The `wf_…` id.
+     * @returns The archived definition, with `status` and `tags` merged in as {@linkcode get} returns them.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     */
+    archive(id: string): Promise<WorkflowDefinition>;
+    /**
+     * Delete an archived workflow, and everything that hangs off it.
+     *
+     * The workflow's runs, schedules and subscriptions cascade-delete server-side
+     * — there is nothing for the caller to clean up, and nothing to undo.
+     *
+     * **Archive first.** Deleting a workflow whose status is not `archived` is
+     * `409 workflow_not_archived`, which this method deliberately does NOT catch
+     * and retry through {@linkcode archive}: a two-step destructive path that an
+     * SDK silently completes for you is how a caller deletes something they only
+     * meant to look at.
+     *
+     * Returns nothing. The server's `{ok: true}` carries no information a caller
+     * can use, and `Ok` is not a public type of this package
+     * (`docs/implementation.md` §5).
+     *
+     * @param id - The `wf_…` id.
+     * @throws {ApiError} `404 unknown_workflow` when there is no such id.
+     * @throws {ApiError} `409 workflow_not_archived` when it exists but has not been archived yet.
+     */
+    delete(id: string): Promise<void>;
 }
 //# sourceMappingURL=workflows.d.ts.map

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

@@ -1 +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;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;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"}
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/workflows.ts"],"names":[],"mappings":"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"}