@w6w/sdk 0.6.0 → 0.9.8

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAkB,YAAY,EAAuB,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA+FvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,IAAI,CAAC,OAA6B,EAAE,GAAG,MAAgB;IACrE,OAAO,OAAO,CAAC,MAAM,CACnB,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CACnB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,EAC9E,EAAE,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAsB,EAAE,OAAuB;IACtE,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAChE,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAChC,OAAO,GAAG,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAsB,EACtB,SAAoB,EACpB,OAAuB;IAEvB,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,qEAAqE;IACrE,uEAAuE;IACvE,4EAA4E;IAC5E,yDAAyD;IACzD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,wEAAwE;IACxE,gCAAgC;IAChC,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,MAAM,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;IAC3C,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IAE7D,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YACzB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO;YACP,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YACxD,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,0EAA0E;QAC1E,mEAAmE;QACnE,qEAAqE;QACrE,iEAAiE;QACjE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI;YAChD,CAAC,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;QACtD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,IAAI,QAAQ,CAChB,CAAC,EACD,WAAW,EACX,sBAAsB,OAAO,CAAC,MAAM,IAAI,GAAG,IAAI,CAChD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,CAAC,EACD,eAAe,EACf,mCAAmC,OAAO,CAAC,MAAM,IAAI,GAAG,KAAK;YAC3D,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CACzF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,6CAA6C;IAC7C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,IAAI,GAAY,IAAI,CAAC;IACzB,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,8BAA8B,GAAG,CAAC,MAAM,cAAc,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC3E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,QAAQ,GAAI,IAA+D,EAAE,KAAK,IAAI,EAAE,CAAC;QAC/F,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAC3B,GAAG,CAAC,MAAM,EACV,QAAQ,CAAC,IAAI,IAAI,OAAO,EACxB,QAAQ,CAAC,OAAO,IAAI,GAAG,CAAC,UAAU,EAClC,IAAI,CACL,CAAC;QAEF,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC;QACnF,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QAEzB,IACE,MAAM,CAAC,qBAAqB,KAAK,IAAI;YACrC,OAAO,KAAK,KAAK,UAAU;YAC3B,OAAO,CAAC,WAAW,KAAK,KAAK;YAC7B,cAAc,EACd,CAAC;YACD,IAAI,SAAoC,CAAC;YACzC,IAAI,CAAC;gBACH,4DAA4D;gBAC5D,wCAAwC;gBACxC,SAAS,GAAG,MAAM,KAAK,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,GAAG,SAAS,CAAC;YACxB,CAAC;YAED,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjE,sEAAsE;gBACtE,sEAAsE;gBACtE,sEAAsE;gBACtE,oEAAoE;gBACpE,mEAAmE;gBACnE,mEAAmE;gBACnE,kEAAkE;gBAClE,kEAAkE;gBAClE,OAAO,MAAM,OAAO,CAAI,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YAC/E,CAAC;YACD,qEAAqE;YACrE,uDAAuD;QACzD,CAAC;QAED,IAAI,cAAc,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;YACpD,MAAM,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,QAAQ,CAAC;IACjB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAS,EAAE,CAAC;AACjD,CAAC"}

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

@@ -12,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.d.ts.map

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

@@ -12,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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"}
+{"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"}

package/dist/src/server/mod.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `@w6w/sdk/server` — a backend-only token exchange, for a partner embedding
+ * w6w inside its own product.
+ *
+ * A **separate** entry point from the package root (`@w6w/sdk`) and from
+ * `@w6w/sdk/console`: deliberately excluded from `endpoints.json`'s
+ * `operations[]` and from the root barrel (`../../mod.ts`), documented
+ * instead in `docs/sdk-surface.md` (R-5). Nothing here is reachable from
+ * either of those entry points, and this module imports nothing from
+ * `../console/mod.ts`.
+ *
+ * **Egress / trust boundary.** {@linkcode exchangeToken} sends a tenant's
+ * client secret over the wire, once per call, and only as an HTTP Basic
+ * credential — never in the body, the URL or a query string. It is built on
+ * the package's existing transport (`../http.ts`'s `request`, `../config.ts`'s
+ * `resolveConfig`) with `requireAuth: false` — the same escape hatch
+ * `console.auth.login` uses for a route that authenticates itself rather than
+ * via a bearer — so this is a thin caller of the one HTTP path this package
+ * has, never a second one.
+ *
+ * This function is meant to run on a partner's OWN backend, never in a
+ * browser: the client secret it takes must never reach client-side code. See
+ * `README.md`'s "Embedding for enterprise tenants" section for the worked
+ * route this is designed to sit behind.
+ *
+ * @module
+ */
+import { type FetchLike } from "../config.ts";
+/** Options for {@linkcode exchangeToken}. */
+export interface ExchangeTokenOptions {
+    /**
+     * The w6w server's origin, e.g. `https://api.example.com`. Same rules as
+     * {@linkcode W6WClientOptions.baseUrl} — an absolute `http(s)` URL with a
+     * host.
+     */
+    baseUrl: string;
+    /** The tenant's client id. Must not contain `:` or a non-latin-1 character. */
+    clientId: string;
+    /** The tenant's client secret. Must be latin-1 encodable. */
+    clientSecret: string;
+    /**
+     * The partner's end-user id. Minted into the returned token's `sub` claim
+     * verbatim — this function does not validate or canonicalise it.
+     */
+    subject: string;
+    /**
+     * Optional account claim. **Trusted verbatim**: the server mints whatever
+     * `account` it is given into the token, so the caller — this function's own
+     * caller, on the partner's backend — is responsible for deriving it from
+     * ITS OWN membership data, never from an unauthenticated client input. See
+     * `README.md`'s embedding example.
+     */
+    account?: string;
+    /** Transport override. Defaults to `globalThis.fetch`, bound. */
+    fetch?: FetchLike;
+}
+/** The shape `POST /auth/exchange` answers with on success. */
+export interface ExchangeTokenResult {
+    /** The minted, short-lived bearer token. */
+    token: string;
+    /** The identity the token carries. */
+    user: {
+        /** The `subject` this call passed, echoed back. */
+        subject: string;
+        /** The tenant the client credentials resolved to. */
+        tenant: string;
+        /** Always `"user"` for a token minted this way. */
+        role: string;
+        /** The resolved account claim — the `account` passed, or the tenant id when omitted. */
+        account: string;
+    };
+    /** Token lifetime, in seconds. */
+    expiresIn: number;
+}
+/**
+ * Exchange a tenant's client credentials for a short-lived, per-user w6w
+ * token: `POST /auth/exchange`.
+ *
+ * Credentials travel ONLY as `Authorization: Basic base64(clientId:clientSecret)`
+ * — never in the body, the URL or a query string. The body sent is exactly
+ * `{ subject }`, or `{ subject, account }` when `account` is given; omitting
+ * `account` never puts the key in the body at all (not even as `null` or
+ * `undefined`).
+ *
+ * Every validation failure below is a local {@linkcode ConfigError}, raised
+ * **before any network call**, and none of them ever echo `clientSecret`.
+ *
+ * @param options - See {@linkcode ExchangeTokenOptions}.
+ * @returns The minted token and the identity it carries.
+ * @throws {ConfigError} Blank `clientId`/`clientSecret`/`subject`; a `clientId`
+ *   containing `:`; a `clientId`/`clientSecret` outside latin-1; no base URL;
+ *   no runtime `fetch`.
+ * @throws {ApiError} `invalid_client` (401, unknown/disabled credentials),
+ *   `invalid_body` / `invalid_subject` / `invalid_account` (400), or any of
+ *   the transport's own failure modes (`../http.ts`). Never retried: this
+ *   call always passes `requireAuth: false`, which `request()` never grants a
+ *   recovery attempt.
+ */
+export declare function exchangeToken(options: ExchangeTokenOptions): Promise<ExchangeTokenResult>;
+//# sourceMappingURL=mod.d.ts.map

package/dist/src/server/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/server/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,cAAc,CAAC;AAI7D,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,EAAE;QACJ,mDAAmD;QACnD,OAAO,EAAE,MAAM,CAAC;QAChB,qDAAqD;QACrD,MAAM,EAAE,MAAM,CAAC;QACf,mDAAmD;QACnD,IAAI,EAAE,MAAM,CAAC;QACb,wFAAwF;QACxF,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAwB9B"}

package/dist/src/server/mod.js

@@ -0,0 +1,121 @@
+/**
+ * `@w6w/sdk/server` — a backend-only token exchange, for a partner embedding
+ * w6w inside its own product.
+ *
+ * A **separate** entry point from the package root (`@w6w/sdk`) and from
+ * `@w6w/sdk/console`: deliberately excluded from `endpoints.json`'s
+ * `operations[]` and from the root barrel (`../../mod.ts`), documented
+ * instead in `docs/sdk-surface.md` (R-5). Nothing here is reachable from
+ * either of those entry points, and this module imports nothing from
+ * `../console/mod.ts`.
+ *
+ * **Egress / trust boundary.** {@linkcode exchangeToken} sends a tenant's
+ * client secret over the wire, once per call, and only as an HTTP Basic
+ * credential — never in the body, the URL or a query string. It is built on
+ * the package's existing transport (`../http.ts`'s `request`, `../config.ts`'s
+ * `resolveConfig`) with `requireAuth: false` — the same escape hatch
+ * `console.auth.login` uses for a route that authenticates itself rather than
+ * via a bearer — so this is a thin caller of the one HTTP path this package
+ * has, never a second one.
+ *
+ * This function is meant to run on a partner's OWN backend, never in a
+ * browser: the client secret it takes must never reach client-side code. See
+ * `README.md`'s "Embedding for enterprise tenants" section for the worked
+ * route this is designed to sit behind.
+ *
+ * @module
+ */
+import { resolveConfig } from "../config.js";
+import { ConfigError } from "../errors.js";
+import { request } from "../http.js";
+/** Non-blank after trimming. */
+function required(value, field) {
+    if (value.trim().length === 0) {
+        throw new ConfigError(`exchangeToken: \`${field}\` must not be blank.`);
+    }
+}
+/**
+ * Base64-encode `clientId:clientSecret` the way the server decodes it:
+ * latin-1 (`atob`'s own alphabet), via `btoa`.
+ *
+ * `btoa` itself rejects any character outside latin-1 (U+0000–U+00FF),
+ * raising for us — this is NOT re-implemented with a UTF-8 path, because that
+ * would silently encode a secret the server's `atob` could never decode back
+ * to the same bytes.
+ *
+ * @throws {ConfigError} When `clientId` contains `:` (indistinguishable from
+ *   the Basic separator on decode) or either value is not latin-1.
+ */
+function basicAuthHeader(clientId, clientSecret) {
+    if (clientId.includes(":")) {
+        throw new ConfigError('exchangeToken: `clientId` must not contain ":" — the server splits a ' +
+            "decoded Basic credential on the FIRST colon, so a colon in `clientId` " +
+            "would be read as part of the secret instead.");
+    }
+    try {
+        return btoa(`${clientId}:${clientSecret}`);
+    }
+    catch {
+        throw new ConfigError("exchangeToken: `clientId`/`clientSecret` must be representable as " +
+            "latin-1 (ISO-8859-1) — the server decodes the Basic header with " +
+            "`atob`, which cannot represent a wider character set.");
+    }
+}
+function resolveFetch(fetchOption) {
+    if (fetchOption)
+        return fetchOption;
+    const global = globalThis.fetch;
+    if (typeof global !== "function") {
+        throw new ConfigError("This runtime has no global fetch. Pass an implementation " +
+            "(exchangeToken({ ..., fetch })) or run on Node 18+, Deno or Bun.");
+    }
+    // Bound, so it keeps working when called as a bare function reference —
+    // exactly W6WClient's own default (../client.ts).
+    return global.bind(globalThis);
+}
+/**
+ * Exchange a tenant's client credentials for a short-lived, per-user w6w
+ * token: `POST /auth/exchange`.
+ *
+ * Credentials travel ONLY as `Authorization: Basic base64(clientId:clientSecret)`
+ * — never in the body, the URL or a query string. The body sent is exactly
+ * `{ subject }`, or `{ subject, account }` when `account` is given; omitting
+ * `account` never puts the key in the body at all (not even as `null` or
+ * `undefined`).
+ *
+ * Every validation failure below is a local {@linkcode ConfigError}, raised
+ * **before any network call**, and none of them ever echo `clientSecret`.
+ *
+ * @param options - See {@linkcode ExchangeTokenOptions}.
+ * @returns The minted token and the identity it carries.
+ * @throws {ConfigError} Blank `clientId`/`clientSecret`/`subject`; a `clientId`
+ *   containing `:`; a `clientId`/`clientSecret` outside latin-1; no base URL;
+ *   no runtime `fetch`.
+ * @throws {ApiError} `invalid_client` (401, unknown/disabled credentials),
+ *   `invalid_body` / `invalid_subject` / `invalid_account` (400), or any of
+ *   the transport's own failure modes (`../http.ts`). Never retried: this
+ *   call always passes `requireAuth: false`, which `request()` never grants a
+ *   recovery attempt.
+ */
+export async function exchangeToken(options) {
+    const { baseUrl, clientId, clientSecret, subject, account } = options;
+    required(clientId, "clientId");
+    required(clientSecret, "clientSecret");
+    required(subject, "subject");
+    const basic = basicAuthHeader(clientId, clientSecret);
+    const config = resolveConfig({ baseUrl });
+    const fetchImpl = resolveFetch(options.fetch);
+    const body = { subject };
+    if (account !== undefined) {
+        body.account = account;
+    }
+    const res = await request(config, fetchImpl, {
+        method: "POST",
+        path: "/auth/exchange",
+        body,
+        headers: { authorization: `Basic ${basic}` },
+        requireAuth: false,
+    });
+    return res.body;
+}
+//# sourceMappingURL=mod.js.map

package/dist/src/server/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/server/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAkB,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAkDrC,gCAAgC;AAChC,SAAS,QAAQ,CAAC,KAAa,EAAE,KAAa;IAC5C,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,WAAW,CAAC,oBAAoB,KAAK,uBAAuB,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CAAC,QAAgB,EAAE,YAAoB;IAC7D,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,WAAW,CACnB,uEAAuE;YACrE,wEAAwE;YACxE,8CAA8C,CACjD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,oEAAoE;YAClE,kEAAkE;YAClE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,WAAkC;IACtD,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,WAAW,CACnB,2DAA2D;YACzD,kEAAkE,CACrE,CAAC;IACJ,CAAC;IACD,wEAAwE;IACxE,kDAAkD;IAClD,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEtE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAEtD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE9C,MAAM,IAAI,GAA0C,EAAE,OAAO,EAAE,CAAC;IAChE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,OAAO,CAAsB,MAAM,EAAE,SAAS,EAAE;QAChE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,gBAAgB;QACtB,IAAI;QACJ,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,KAAK,EAAE,EAAE;QAC5C,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,IAAI,CAAC;AAClB,CAAC"}