@w6w/sdk 0.5.0 → 0.9.8

package/dist/src/functions.js

@@ -0,0 +1,201 @@
+import { ApiError } from "./errors.js";
+import { path } from "./http.js";
+import { mintId, unwrap } from "./types.js";
+/**
+ * The `functions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const output = await client.functions.run("send-email", {
+ *   payload: { to: "ada@example.com", subject: "Hi", html: "<p>Hello</p>" },
+ * });
+ *
+ * // The definition lifecycle.
+ * const fns = await client.functions.list();
+ * const { function: def } = await client.functions.get(fns[0].id);
+ * await client.functions.update(fns[0].id, { ...def, description: "Send an email" });
+ * ```
+ */
+export class FunctionsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * Run one Function and return its output.
+     *
+     * Returns the Function's OUTPUT, not an envelope. `client.run` returns a
+     * `kind`-discriminated envelope because the caller does not know what the URN
+     * will resolve to; here the kind is in the method name, so the discriminant
+     * would be a field the caller has to unwrap to learn nothing.
+     *
+     * @param name - The Function's key (`"send-email"`) or its `fn_…` id. Percent-encoded into the path.
+     * @param options - `payload`, the Function's canonical inputs.
+     * @returns The Function's output, unwrapped from the `output` envelope.
+     * @throws {ApiError} `404 unknown_function` when no Function of that name exists for the caller.
+     * @throws {ApiError} `422 function_incomplete` when the Function has no runnable `impl`.
+     * @throws {ApiError} `bad_response` when a success body carries no `output` key at all.
+     */
+    async run(name, options) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/functions/${name}/invoke`,
+            body: { inputs: options?.payload ?? {} },
+        });
+        // Deliberately NOT `unwrap(res, "output")`. That helper treats `null` as
+        // "the server did not send what it promised" — correct for a `documents` or
+        // `vars` envelope, where null is never a document. It is wrong here: a
+        // Function's output is an OPAQUE pass-through, and an action that returns
+        // nothing yields `{"output": null}`, which is a successful run and not a
+        // malformed response. So the guard is PRESENCE of the key, not truthiness
+        // of the value.
+        const body = res.body;
+        if (typeof body !== "object" || body === null || !("output" in body)) {
+            throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} with no "output" in the response body.`, body);
+        }
+        return body.output;
+    }
+    /**
+     * List the caller's Function definitions.
+     *
+     * This is how a caller discovers a `key` to pass to {@linkcode run} — the
+     * same job `workflows.list` and `connections.list` do for their own ids (D4),
+     * and the reason a read-only integration needs no other write access.
+     *
+     * Each row already carries `valid`, computed server-side; there is no second
+     * call to make to find out whether a Function is runnable.
+     *
+     * **No `project` parameter.** Unlike workflows and documents, the route reads
+     * no `?project=` at all (`admin/functions.ts`) — sending one would be
+     * inventing a parameter, which is the failure mode `endpoints.json` warns
+     * about.
+     *
+     * @param options - Optional per-call transport options (`signal` to abort).
+     * @returns The Functions, unwrapped from the `functions` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async list(options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/functions",
+            signal: options?.signal,
+        });
+        return unwrap(res, "functions");
+    }
+    /**
+     * Fetch one Function's stored definition.
+     *
+     * Returns the whole body — `{function, valid}` — rather than splicing `valid`
+     * into the definition. See {@linkcode FunctionDetail.valid} for why that
+     * placement matters on the way back OUT of this method.
+     *
+     * @param id - The `fn_…` id, or the Function's `key`. Percent-encoded into the path.
+     * @param options - Optional per-call transport options (`signal` to abort).
+     * @returns The definition and the server's runnability verdict.
+     * @throws {ApiError} `404 unknown_function` when there is no such Function for this caller.
+     */
+    async get(id, options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/functions/${id}`,
+            signal: options?.signal,
+        });
+        return res.body;
+    }
+    /**
+     * Create a Function.
+     *
+     * **The id is minted client-side when the definition does not carry one** —
+     * `POST /functions` requires `id` and never generates one, exactly as the
+     * workflow route does. `key` is NOT minted: it is the name the Function is
+     * called by, so it is the caller's to choose, and the server validates it on
+     * first save only (3–39 chars, lowercase, single hyphens, no `_`). That
+     * grammar is what keeps `/functions/{idOrKey}/invoke` unambiguous — a key
+     * containing `_` could be mistaken for an `fn_…` id.
+     *
+     * `create` and {@linkcode update} reach the SAME upsert route; posting a
+     * definition whose id already exists overwrites it.
+     *
+     * @param definition - The whole Function definition, forwarded verbatim apart from a minted `id`.
+     * @returns The new Function's id and key.
+     * @throws {ApiError} `400 invalid_function` — no `key`, no `inputs` array, or a malformed `impl`.
+     * @throws {ApiError} `409 function_conflict` — another `(tenant, subject)` already owns that id.
+     * @throws {ApiError} `409 function_key_conflict` — that `key` is already taken in this scope.
+     */
+    async create(definition) {
+        const body = typeof definition.id === "string" && definition.id.length > 0
+            ? definition
+            : { ...definition, id: mintId("fn") };
+        return await this.#save(body);
+    }
+    /**
+     * Overwrite a Function's stored definition.
+     *
+     * **A full replacement, not a patch** — the server has one write route and it
+     * stores what it is given, so read with {@linkcode get}, change what you mean
+     * to change, and send the whole thing back. There is no concurrency
+     * precondition on this route (workflows have one; Functions do not), so the
+     * write is last-write-wins.
+     *
+     * `id` comes from the FIRST ARGUMENT and is pinned into the body, overriding
+     * any `id` the definition carries — otherwise `update("fn_a", defOfB)` would
+     * quietly write to B.
+     *
+     * Do not send back the `valid` field: it is not part of the stored document,
+     * and {@linkcode get} deliberately leaves it outside the definition so that
+     * a read-modify-write round trip cannot pick it up by accident.
+     *
+     * @param id - The `fn_…` id to write to.
+     * @param definition - The whole replacement definition.
+     * @returns The Function's id and key.
+     * @throws {ApiError} `400 invalid_function` — structurally invalid body.
+     * @throws {ApiError} `409 function_conflict` — another `(tenant, subject)` owns this id.
+     * @throws {ApiError} `409 function_key_conflict` — the new `key` is already taken in this scope.
+     */
+    async update(id, definition) {
+        return await this.#save({ ...definition, id });
+    }
+    /**
+     * Delete a Function.
+     *
+     * Not idempotent, and deliberately so: deleting an id that is not there is
+     * `404 unknown_function`, not a silent success — the same pin
+     * `documents.delete` carries.
+     *
+     * **Nothing checks for callers first.** A Function may be referenced by an
+     * Endpoint, by a Workflow step, or by another Function's `impl` (D-8), and
+     * the server does not walk those references; they break at call time. Deleting
+     * a Function that something else calls is the caller's decision to get right.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a caller
+     * can use (`docs/implementation.md` §5).
+     *
+     * @param id - The `fn_…` id, or the Function's `key`.
+     * @throws {ApiError} `404 unknown_function` when there is no such Function for this caller.
+     */
+    async delete(id) {
+        await this.#host.request({ method: "DELETE", path: path `/functions/${id}` });
+    }
+    /**
+     * The one POST both {@linkcode create} and {@linkcode update} go through.
+     *
+     * Private and shared rather than duplicated: the route answers `201` with the
+     * id and key under a `function` envelope, and two copies of that unwrap is
+     * two places for a server change to be half-applied.
+     *
+     * @param body - The complete definition, id already resolved.
+     * @returns The saved Function's id and key.
+     */
+    async #save(body) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/functions",
+            body,
+        });
+        return unwrap(res, "function");
+    }
+}
+//# sourceMappingURL=functions.js.map

package/dist/src/functions.js.map

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

package/dist/src/http.d.ts

@@ -1,12 +1,24 @@
 /**
- * The transport: one `request()`, three failure modes, no policy.
+ * The transport: one `request()`, three failure modes, and one opt-in policy.
  *
  * Everything the operation modules do goes through {@linkcode request}. It
  * attaches the bearer, serialises a JSON body, reads the response exactly once,
  * parses it guardedly, and raises one of the three failure modes pinned in
- * `docs/implementation.md` §3 — and nothing else. In particular it does **not**
- * retry, does **not** refresh a token, does **not** poll, and does **not**
- * inspect an error code to decide on a side effect. A `401` raises and stops.
+ * `docs/implementation.md` §3 — and nothing else. It does **not** poll and does
+ * **not** inspect an error code to decide on a side effect, beyond the one
+ * policy described next.
+ *
+ * **The one exception is opt-in**: when `config.refreshOnUnauthorized` is
+ * `true`, `config.token` is a function, and the request used a bearer
+ * (`requireAuth !== false`), a `401` whose `code` is exactly `"unauthorized"`
+ * is given a single recovery attempt — the provider is called once more with
+ * `{forceRefresh: true}` and, if that yields a usable token, the identical
+ * request is re-sent once with it by calling `request()` a second time (never
+ * a third). Off by default, this is exactly the old unconditional "a `401`
+ * raises and stops" behaviour. `config.onUnauthorized`, when set, receives the
+ * terminal `401`/`unauthorized` `ApiError` of a bearer request — after a failed
+ * retry, or immediately when recovery is off or impossible — at most once per
+ * call, never on success, and never for a `requireAuth: false` request.
  *
  * It also returns the **HTTP status** alongside the parsed body, because a
  * `202` is a normal outcome on this API (a queued workflow run), not an error —
@@ -45,12 +57,12 @@ export interface RequestOptions {
     /** Request body. Serialised as JSON when present; omit it for a bodiless request. */
     body?: unknown;
     /**
-     * Extra headers to send with this request. Applied as the **base** the
-     * transport builds on, never the other way around: the bearer
-     * (`authorization`) and, when a body is present, `content-type` are set
-     * *after* this base, so a caller-supplied entry with either of those names
-     * can never override what this transport sets. Any other header name passes
-     * through untouched.
+     * Extra headers to send with this request. Precedence, low to high: the
+     * client's own `headers` default < this option < the bearer
+     * (`authorization`) and, when a body is present, `content-type`, which this
+     * transport sets *after* both and which neither can ever override. A
+     * same-named entry here beats the client default; any other header name
+     * passes through untouched.
      */
     headers?: Record<string, string>;
     /**
@@ -67,6 +79,32 @@ export interface RequestOptions {
      * in the first place.
      */
     requireAuth?: boolean;
+    /**
+     * Abort this specific request. Local request control only — it is never
+     * serialized into the URL or the body, and the server never sees it. Wired
+     * straight through to the injected `fetch`'s own `RequestInit.signal`, so
+     * cancellation semantics are whatever the runtime's `fetch` already gives an
+     * aborted request; this transport adds no polling, retry or timeout policy
+     * on top of it (see this module's header).
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Per-call transport options shared by every read method a react hook calls
+ * (R-7): today, just an optional {@linkcode AbortSignal}. A thin, deliberately
+ * minimal bag rather than reusing {@linkcode RequestOptions} itself — the
+ * typed per-method option interfaces (`DocumentOptions`,
+ * `WorkflowListOptions`, …) extend this one, and a method with no options
+ * today takes a bare `options?: CallOptions`, so `signal` lands in exactly one
+ * place for every read operation.
+ *
+ * `signal` reaches the injected `fetch` unchanged through
+ * {@linkcode RequestOptions.signal} and is NEVER serialized into the URL or
+ * the body — see that field's own doc for the cancellation semantics.
+ */
+export interface CallOptions {
+    /** Abort this call. See {@linkcode RequestOptions.signal}. */
+    signal?: AbortSignal;
 }
 /**
  * A successful response: the parsed body plus the status that carried it.
@@ -149,6 +187,16 @@ export declare function buildUrl(config: ResolvedConfig, options: RequestOptions
  * deliberately a 4xx so Cloudflare cannot swallow it. It is never a transport
  * error and is never normalised into a 5xx.
  *
+ * **Recovery (opt-in, this module's header).** When a `401`/`unauthorized`
+ * {@linkcode ApiError} is about to be raised and `config.refreshOnUnauthorized
+ * === true && typeof config.token === "function" && options.requireAuth !==
+ * false`, this function calls `config.token({forceRefresh: true})` once; a
+ * usable result re-enters `request()` itself — never a second mapper — with a
+ * config carrying that **string**, which is what caps the retry at one: the
+ * recursive call's `config.token` is no longer a function, so its own recovery
+ * check is false by construction. `config.onUnauthorized` is invoked with
+ * whichever `401`/`unauthorized` error turns out to be terminal.
+ *
  * @param config - Resolved configuration (base URL and credential).
  * @param fetchImpl - The transport to use; injected, never read from a module global.
  * @param options - The request.

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

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhF;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;AAEhF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,qFAAqF;IACrF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAOhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAiE1B"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhF;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;AAEhF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,qFAAqF;IACrF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAOhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA2H1B"}

package/dist/src/http.js

@@ -1,12 +1,24 @@
 /**
- * The transport: one `request()`, three failure modes, no policy.
+ * The transport: one `request()`, three failure modes, and one opt-in policy.
  *
  * Everything the operation modules do goes through {@linkcode request}. It
  * attaches the bearer, serialises a JSON body, reads the response exactly once,
  * parses it guardedly, and raises one of the three failure modes pinned in
- * `docs/implementation.md` §3 — and nothing else. In particular it does **not**
- * retry, does **not** refresh a token, does **not** poll, and does **not**
- * inspect an error code to decide on a side effect. A `401` raises and stops.
+ * `docs/implementation.md` §3 — and nothing else. It does **not** poll and does
+ * **not** inspect an error code to decide on a side effect, beyond the one
+ * policy described next.
+ *
+ * **The one exception is opt-in**: when `config.refreshOnUnauthorized` is
+ * `true`, `config.token` is a function, and the request used a bearer
+ * (`requireAuth !== false`), a `401` whose `code` is exactly `"unauthorized"`
+ * is given a single recovery attempt — the provider is called once more with
+ * `{forceRefresh: true}` and, if that yields a usable token, the identical
+ * request is re-sent once with it by calling `request()` a second time (never
+ * a third). Off by default, this is exactly the old unconditional "a `401`
+ * raises and stops" behaviour. `config.onUnauthorized`, when set, receives the
+ * terminal `401`/`unauthorized` `ApiError` of a bearer request — after a failed
+ * retry, or immediately when recovery is off or impossible — at most once per
+ * call, never on success, and never for a `requireAuth: false` request.
  *
  * It also returns the **HTTP status** alongside the parsed body, because a
  * `202` is a normal outcome on this API (a queued workflow run), not an error —
@@ -98,6 +110,16 @@ export function buildUrl(config, options) {
  * deliberately a 4xx so Cloudflare cannot swallow it. It is never a transport
  * error and is never normalised into a 5xx.
  *
+ * **Recovery (opt-in, this module's header).** When a `401`/`unauthorized`
+ * {@linkcode ApiError} is about to be raised and `config.refreshOnUnauthorized
+ * === true && typeof config.token === "function" && options.requireAuth !==
+ * false`, this function calls `config.token({forceRefresh: true})` once; a
+ * usable result re-enters `request()` itself — never a second mapper — with a
+ * config carrying that **string**, which is what caps the retry at one: the
+ * recursive call's `config.token` is no longer a function, so its own recovery
+ * check is false by construction. `config.onUnauthorized` is invoked with
+ * whichever `401`/`unauthorized` error turns out to be terminal.
+ *
  * @param config - Resolved configuration (base URL and credential).
  * @param fetchImpl - The transport to use; injected, never read from a module global.
  * @param options - The request.
@@ -107,18 +129,21 @@ export function buildUrl(config, options) {
  */
 export async function request(config, fetchImpl, options) {
     const url = buildUrl(config, options);
-    // The caller-supplied headers are the BASE the transport builds on, never the
-    // reverse: `authorization` and `content-type` are set below, after this base,
-    // so nothing a caller passes here can shadow the bearer this transport
-    // attaches or the content-type it advertises for a JSON body.
-    const headers = new Headers(options.headers);
+    // Precedence, low to high: the client's own default `headers` < this
+    // request's `headers` < the bearer/content-type this transport re-pins
+    // below. `.set` on an already-present name overrides it, which is what lets
+    // a per-request header beat a same-named client default.
+    const headers = new Headers(config.headers);
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+        headers.set(name, value);
+    }
     // Resolved per request rather than at construction: a client with no token is
     // constructible (so a CLI's --help works offline) and fails here instead.
     // Skipped entirely when `requireAuth: false` — not just left unset, but never
     // even attempted, so a tokenless client can call a public route without
     // `requireToken` raising first.
     if (options.requireAuth !== false) {
-        headers.set("authorization", `Bearer ${requireToken(config)}`);
+        headers.set("authorization", `Bearer ${await requireToken(config)}`);
     }
     const hasBody = options.body !== undefined;
     if (hasBody)
@@ -129,9 +154,22 @@ export async function request(config, fetchImpl, options) {
             method: options.method,
             headers,
             body: hasBody ? JSON.stringify(options.body) : undefined,
+            signal: options.signal,
         });
     }
     catch (err) {
+        // An aborted request is a distinct, recognizable outcome from an actual
+        // network failure — a caller that cancelled a stale search/tab-switch
+        // request must be able to tell "I cancelled this" from "the server is
+        // unreachable" without inspecting `err.message` text. `signal.aborted` is
+        // checked rather than matching only on `err.name === "AbortError"`
+        // because it is the runtime-agnostic source of truth (the DOM/undici
+        // `fetch` both set it synchronously before the promise rejects).
+        const cancelled = options.signal?.aborted === true ||
+            (err instanceof Error && err.name === "AbortError");
+        if (cancelled) {
+            throw new ApiError(0, "cancelled", `Request cancelled (${options.method} ${url}).`);
+        }
         throw new ApiError(0, "network_error", `Could not reach the w6w server (${options.method} ${url}). ` +
             `It may be down or unreachable. (${err instanceof Error ? err.message : String(err)})`);
     }
@@ -152,7 +190,40 @@ export async function request(config, fetchImpl, options) {
     }
     if (!res.ok) {
         const envelope = data?.error ?? {};
-        throw new ApiError(res.status, envelope.code ?? "error", envelope.message ?? res.statusText, data);
+        const apiError = new ApiError(res.status, envelope.code ?? "error", envelope.message ?? res.statusText, data);
+        const isUnauthorized = apiError.status === 401 && apiError.code === "unauthorized";
+        const { token } = config;
+        if (config.refreshOnUnauthorized === true &&
+            typeof token === "function" &&
+            options.requireAuth !== false &&
+            isUnauthorized) {
+            let refreshed;
+            try {
+                // The one and only forced refresh: never passed by ordinary
+                // resolution, passed here exactly once.
+                refreshed = await token({ forceRefresh: true });
+            }
+            catch {
+                refreshed = undefined;
+            }
+            if (typeof refreshed === "string" && refreshed.trim().length > 0) {
+                // Re-enter request() itself — the only status→ApiError mapper in this
+                // module — rather than re-implementing it. The retried config carries
+                // the refreshed token as a plain STRING, so this recursive call's own
+                // `typeof config.token === "function"` check is false: that is what
+                // caps this at one retry, never a third attempt, AND it is why the
+                // recursive call's own terminal-error handling below (not a second
+                // copy of it here) is what calls `onUnauthorized` on a retry that
+                // still comes back 401 — calling it here too would fire it twice.
+                return await request({ ...config, token: refreshed }, fetchImpl, options);
+            }
+            // No usable refreshed token (nullish, blank, or the provider threw):
+            // no retry — fall through and report the ORIGINAL 401.
+        }
+        if (isUnauthorized && options.requireAuth !== false) {
+            config.onUnauthorized?.(apiError);
+        }
+        throw apiError;
     }
     return { status: res.status, body: data };
 }

package/dist/src/http.js.map

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

package/dist/src/me.d.ts

@@ -21,7 +21,7 @@
  *
  * @module
  */
-import type { HttpResponse, RequestOptions } from "./http.ts";
+import type { CallOptions, HttpResponse, RequestOptions } from "./http.ts";
 import type { Me } from "./types.ts";
 /**
  * The slice of `W6WClient` this operation needs: the transport, and nothing
@@ -43,11 +43,12 @@ export interface MeHost {
  * the server sent the block at all.
  *
  * @param host - The client this operation issues its request through.
+ * @param options - Optional per-call transport options (`signal` to abort).
  * @returns The caller's identity, with `versions.wrapper` filled in.
  * @throws {ApiError} On any non-2xx, e.g. `401` when the token is not accepted.
  * @throws {ApiError} `bad_response` when a 2xx body is not a plain object — an
  * array included, since `typeof [] === "object"` and a spread array yields
  * character-indexed keys rather than identity fields.
  */
-export declare function fetchMe(host: MeHost): Promise<Me>;
+export declare function fetchMe(host: MeHost, options?: CallOptions): Promise<Me>;
 //# sourceMappingURL=me.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAGrC;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAuCvD"}
+{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAGrC;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,EAAE,CAAC,CA2C9E"}

package/dist/src/me.js

@@ -33,14 +33,19 @@ import { VERSION } from "./version.js";
  * the server sent the block at all.
  *
  * @param host - The client this operation issues its request through.
+ * @param options - Optional per-call transport options (`signal` to abort).
  * @returns The caller's identity, with `versions.wrapper` filled in.
  * @throws {ApiError} On any non-2xx, e.g. `401` when the token is not accepted.
  * @throws {ApiError} `bad_response` when a 2xx body is not a plain object — an
  * array included, since `typeof [] === "object"` and a spread array yields
  * character-indexed keys rather than identity fields.
  */
-export async function fetchMe(host) {
-    const res = await host.request({ method: "GET", path: "/auth/me" });
+export async function fetchMe(host, options) {
+    const res = await host.request({
+        method: "GET",
+        path: "/auth/me",
+        signal: options?.signal,
+    });
     const body = res.body;
     // A body that is not an object cannot be identity data. Raise rather than
     // spread it — the same `bad_response` class the envelope reader uses for the

package/dist/src/me.js.map

@@ -1 +1 @@
-{"version":3,"file":"me.js","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAavC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IACxE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,0EAA0E;IAC1E,6EAA6E;IAC7E,uEAAuE;IACvE,0EAA0E;IAC1E,SAAS;IACT,EAAE;IACF,iFAAiF;IACjF,iFAAiF;IACjF,6EAA6E;IAC7E,iFAAiF;IACjF,+EAA+E;IAC/E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,wCAAwC,EACvE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,+EAA+E;IAC/E,mEAAmE;IACnE,gFAAgF;IAChF,6EAA6E;IAC7E,4EAA4E;IAC5E,+EAA+E;IAC/E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC1F,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,GAAG,IAAI;QACP,2EAA2E;QAC3E,oEAAoE;QACpE,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE;KAC1C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"me.js","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAavC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,OAAqB;IAC/D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAK;QACjC,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,OAAO,EAAE,MAAM;KACxB,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,0EAA0E;IAC1E,6EAA6E;IAC7E,uEAAuE;IACvE,0EAA0E;IAC1E,SAAS;IACT,EAAE;IACF,iFAAiF;IACjF,iFAAiF;IACjF,6EAA6E;IAC7E,iFAAiF;IACjF,+EAA+E;IAC/E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,wCAAwC,EACvE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,+EAA+E;IAC/E,mEAAmE;IACnE,gFAAgF;IAChF,6EAA6E;IAC7E,4EAA4E;IAC5E,+EAA+E;IAC/E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC1F,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,GAAG,IAAI;QACP,2EAA2E;QAC3E,oEAAoE;QACpE,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/dist/src/run.d.ts

@@ -2,8 +2,9 @@
  * `client.run({urn, action, payload})` — run anything a URN addresses.
  *
  * One POST, one kind-tagged body, no envelope key. The URN resolves over the
- * four runnable arms — `conn_…`, `wf_…`, `fn_…`, `ep_…` (D16) — and the answer
- * says which one it hit:
+ * `conn_…`, `wf_…`, `fn_…` and `ep_…` arms (D16), and, additionally, an
+ * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+ * needed to disambiguate the two) — and the answer says which one it hit:
  *
  * | `kind` | Field | HTTP |
  * |---|---|---|
@@ -11,11 +12,20 @@
  * | `"function"` | `output` | `200` |
  * | `"workflow"` | `runId` + `status` | `202` |
  *
- * `value` and `output` are **deliberately different names** and are never
- * normalised into one field: the discrimination is the whole point of the
+ * `value` and `output` were **deliberately different names** and `value` is
+ * never removed: the discrimination is the whole point of the
  * operation (D3). `202` on the workflow arm is **success** — the run is queued
  * and `runId` is how the caller follows it.
  *
+ * ── The invocation frame ──
+ * Since 2026-08-20 every arm also carries the platform's own record of the
+ * attempt — `invocationId` (`inv_…`), `status`, `startedAt`, `finishedAt`,
+ * `durationMs` — and the action arm carries `output` beside `value`, with the
+ * identical payload. All additive; nothing was renamed. `status` is the
+ * PLATFORM's verdict (`succeeded` | `failed` | `queued`), not one the target
+ * reported inside its own payload, and `invocationId` (this call) is not
+ * `runId` (the queued workflow run a call may have started).
+ *
  * ── The unknown fourth kind ──
  * A `kind` this release has never heard of is **returned verbatim**, never
  * raised (`docs/implementation.md` §5). `run` dispatches on whatever a URN
@@ -63,7 +73,11 @@ export interface RunHost {
  * uses it for its `wf_…` id.)
  */
 export interface RunInput {
-    /** What to run: `conn_…`, `wf_…`, `fn_…` or `ep_…`. */
+    /**
+     * What to run: `conn_…`, `wf_…`, `fn_…`, `ep_…`, or, additionally, an
+     * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+     * needed to disambiguate the two).
+     */
     urn: string;
     /**
      * Which action to invoke. Optional, because a workflow, function or endpoint

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

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CA8BjF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CA8BjF"}

package/dist/src/run.js

@@ -2,8 +2,9 @@
  * `client.run({urn, action, payload})` — run anything a URN addresses.
  *
  * One POST, one kind-tagged body, no envelope key. The URN resolves over the
- * four runnable arms — `conn_…`, `wf_…`, `fn_…`, `ep_…` (D16) — and the answer
- * says which one it hit:
+ * `conn_…`, `wf_…`, `fn_…` and `ep_…` arms (D16), and, additionally, an
+ * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+ * needed to disambiguate the two) — and the answer says which one it hit:
  *
  * | `kind` | Field | HTTP |
  * |---|---|---|
@@ -11,11 +12,20 @@
  * | `"function"` | `output` | `200` |
  * | `"workflow"` | `runId` + `status` | `202` |
  *
- * `value` and `output` are **deliberately different names** and are never
- * normalised into one field: the discrimination is the whole point of the
+ * `value` and `output` were **deliberately different names** and `value` is
+ * never removed: the discrimination is the whole point of the
  * operation (D3). `202` on the workflow arm is **success** — the run is queued
  * and `runId` is how the caller follows it.
  *
+ * ── The invocation frame ──
+ * Since 2026-08-20 every arm also carries the platform's own record of the
+ * attempt — `invocationId` (`inv_…`), `status`, `startedAt`, `finishedAt`,
+ * `durationMs` — and the action arm carries `output` beside `value`, with the
+ * identical payload. All additive; nothing was renamed. `status` is the
+ * PLATFORM's verdict (`succeeded` | `failed` | `queued`), not one the target
+ * reported inside its own payload, and `invocationId` (this call) is not
+ * `runId` (the queued workflow run a call may have started).
+ *
  * ── The unknown fourth kind ──
  * A `kind` this release has never heard of is **returned verbatim**, never
  * raised (`docs/implementation.md` §5). `run` dispatches on whatever a URN

package/dist/src/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAoCvC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAa,EAAE,KAAe;IACzD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAU;QACtC,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE;YACJ,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,oEAAoE;YACpE,0EAA0E;YAC1E,mBAAmB;YACnB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;SAC7B;KACF,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IACE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QACzC,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ,EACrD,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,uCAAuC,EACtE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,wBAAwB;IACxB,OAAO,IAAmB,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAwCvC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAa,EAAE,KAAe;IACzD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAU;QACtC,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE;YACJ,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,oEAAoE;YACpE,0EAA0E;YAC1E,mBAAmB;YACnB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;SAC7B;KACF,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IACE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QACzC,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ,EACrD,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,uCAAuC,EACtE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,wBAAwB;IACxB,OAAO,IAAmB,CAAC;AAC7B,CAAC"}