@w6w/react 0.5.0 → 0.9.9

package/README.md

@@ -2,11 +2,13 @@
 
 React bindings for [`@w6w/sdk`](../node) — a `<W6WProvider>` that holds one memoized
 `W6WClient` with per-request token freshness, a small hook set over the SDK's public
-surface (`me`, `documents`, `vars`, `connections`, `workflows`, `run`), and
+surface (`me`, `documents`, `vars`, `connections`, `workflows`, `functions`, `run`), and
 `createW6WUiAdapter`, a structural bridge from a `W6WClient` to
 [`@w6w/ui`](https://github.com/w6w-io/w6w-ui)'s `W6WApi` contract.
 
-License: MIT · Version: 0.3.0
+License: MIT · Version: 0.9.8 · Guides: [docs.w6w.io/clients/react](https://docs.w6w.io/clients/react/)
+(with a [hooks reference](https://docs.w6w.io/clients/react/hooks/) and a
+[Next.js walkthrough](https://docs.w6w.io/clients/react/nextjs/))
 
 This lane implements no endpoint — it composes `@w6w/sdk`, which is already
 conformant against [`endpoints.json`](../endpoints.json). There is nothing here to
@@ -18,6 +20,10 @@ re-verify against the wire contract; verify `@w6w/sdk` instead.
 npm install @w6w/react react
 ```
 
+`@w6w/sdk` comes in as a dependency. Add it to your own `package.json` too
+(`npm install @w6w/sdk`) if you import from it directly — `ApiError` for an
+`instanceof` check, or `exchangeToken` from `@w6w/sdk/server` on your backend.
+
 `react-dom` is not a dependency of this package — `<W6WProvider>`'s only JSX is a
 context wrapper (`<Ctx.Provider>`), never a DOM element of its own. Your app already
 depends on `react-dom` to mount itself; nothing extra is needed here.
@@ -38,11 +44,16 @@ function App() {
 }
 ```
 
-`token` accepts a literal string, or a supplier function called fresh on every
-request — pass a supplier when your token rotates (e.g. a short-lived JWT read from
-an auth SDK) and the client will pick up the new value on the very next call, with no
-teardown/rebuild of the underlying `W6WClient`. See `src/W6WProvider.tsx`'s module
-header for the exact mechanism (the C-4 shim).
+`token` accepts a literal string, or a supplier — sync or **async** — called per
+request (requests in flight at the same time share ONE supplier call; nothing is cached once
+it settles, so memoize an expensive supplier yourself): `() => getCurrentJwt()` or `async () => await getCurrentJwt()` both
+work, and either is awaited before the bearer is attached. Pass a supplier when your
+token rotates (e.g. a short-lived JWT read from an auth SDK, or minted on demand by
+your own backend) and the client picks up the new value on the very next call, with no
+teardown/rebuild of the underlying `W6WClient`. A nullish or blank result (from either
+form) never reaches the wire: every read hook below reports `loading: true` instead of
+sending a request with no credential. See `src/W6WProvider.tsx`'s module header for the
+exact mechanism.
 
 Then, anywhere under the provider:
 
@@ -61,6 +72,70 @@ function DocList() {
 }
 ```
 
+## Embedding for enterprise tenants
+
+A host juggling more than one signed-in identity — or one that does not have a
+token/identity yet at mount time — needs more than the Quick start's one-shot
+`token` prop. `<W6WProvider>` takes five more props for exactly this:
+
+- **`ready`** (default `true`) — set it `false` until you actually have a
+  token/identity to embed with. While `false`, every read hook reports
+  `loading: true` and none of them calls the SDK at all; flipping it back to
+  `true` fetches.
+- **`identityKey`** — a string identifying WHICH signed-in identity this
+  client speaks for, e.g. `` `${subject}:${account}` ``. Changing it rebuilds
+  the underlying `W6WClient` and resets every read hook's state — the
+  supported way to switch accounts without a stale read from the previous
+  identity ever rendering under the new one.
+- **`refreshOnUnauthorized`** + **`onUnauthorized`** — opt in to a single,
+  one-shot recovery when a request 401s with `{code: "unauthorized"}`: your
+  `token` supplier is called once more with `{forceRefresh: true}`, and a
+  usable result retries the same request once. `onUnauthorized` receives the
+  terminal error — after a failed retry, or immediately when recovery is off
+  or not possible — at most once per call.
+- **`headers`** — default headers sent with every request. This is how a
+  tenant on the custom-authorizer integration path (no OIDC on your side)
+  attaches the tenant header your w6w account's authorizer webhook expects
+  (e.g. `headers={{ "X-W6W-Tenant": tenantId }}`) alongside the bearer token.
+  Compared by content, not identity — a new-but-equal object on every render
+  never rebuilds the client.
+
+```tsx
+"use client";
+
+import { W6WProvider } from "@w6w/react";
+
+export default function W6WLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <W6WProvider
+      baseUrl="https://api.example.com"
+      ready={true}
+      identityKey={`${session.subject}:${session.account}`}
+      headers={{ "X-W6W-Tenant": session.tenantId }}
+      refreshOnUnauthorized
+      onUnauthorized={() => redirectToLogin()}
+      token={async () => {
+        // Your own backend route, not w6w's — it holds whatever credential
+        // mints a w6w token for this signed-in user (a tenant exchange, a
+        // cached short-lived token, …). This is a Next.js App Router layout,
+        // so it is a Client Component ("use client" above) even though the
+        // token-minting route itself runs on your server.
+        const res = await fetch("/api/w6w-token");
+        if (!res.ok) return null;
+        const { token } = await res.json();
+        return token;
+      }}
+    >
+      {children}
+    </W6WProvider>
+  );
+}
+```
+
+The [Next.js walkthrough](https://docs.w6w.io/clients/react/nextjs/) builds the
+`/api/w6w-token` route this example fetches from, with `exchangeToken` and a
+cached, refreshable token supplier.
+
 ## Using this package with `@w6w/ui`
 
 `@w6w/ui`'s components (e.g. `AppPicker`, `ActionTestForm`, the flow editor) take a
@@ -68,6 +143,7 @@ function DocList() {
 `@w6w/react` client with `createW6WUiAdapter`:
 
 ```tsx
+import { useMemo } from "react";
 import { createW6WUiAdapter, useW6WClient, W6WProvider } from "@w6w/react";
 import { W6WUIProvider, AppPicker } from "@w6w/ui";
 
@@ -88,23 +164,55 @@ function App() {
 }
 ```
 
-**`@w6w/ui` is not on npm today.** The `@w6w` scope holds only `@w6w/sdk` and
-`@w6w/cli` at the time of writing (`npm view @w6w/ui` → 404); the source itself IS a
-public GitHub repository (`w6w-io/w6w-ui`). `createW6WUiAdapter`'s `W6WApi` return
-type targets that contract *structurally* — this package names `@w6w/ui` nowhere in
-its own manifest and needs no change whenever `@w6w/ui` becomes reachable another
-way (this monorepo, a `git+https://` dependency on the public repo, or a private
-registry). This is an honest statement of today's install story, not a promise that
-`npm i @w6w/ui` resolves.
-
-`createW6WUiAdapter` is built entirely on `@w6w/sdk/console` — the SAME namespace
-`packages/studio`'s own facade uses for these routes (`packages/ui/src/createW6WApi.ts`
-is the *other* hand-rolled client for them; this package is not a third one).
-**`client.console.*` is documented "Studio-internal… unstable" and is deliberately
-excluded from `endpoints.json`'s conformance runner** (`node/src/client.ts:114-116`).
-That means a `console.*` signature change ships with no lockstep protection for this
-bridge beyond `@w6w/sdk`'s own version — pin your `@w6w/sdk` version alongside
-`@w6w/react`'s, and re-test the bridge on an upgrade rather than assuming it.
+**`@w6w/ui` is not on npm today** (`npm view @w6w/ui` → 404, checked 2026-10-06);
+the source is a public GitHub repository (`w6w-io/w6w-ui`). `createW6WUiAdapter`'s
+`W6WApi` return type targets that contract *structurally* — this package needs no
+change whenever `@w6w/ui` becomes reachable another way (a `git+https://`
+dependency on the public repo, or a private registry). `npm i @w6w/ui` does not
+resolve yet.
+
+`createW6WUiAdapter` is built on `@w6w/sdk/console` for most members — the SAME
+namespace `packages/studio`'s own facade uses for these routes
+(`packages/ui/src/createW6WApi.ts` is the *other* hand-rolled client for them; this
+package is not a third one) — and on the BASE `client.functions.*`/
+`client.workflows.*` surface for `listFunctions`/`getFunction`/`invokeFunction`/
+`listWorkflows`/`getWorkflow`/`runWorkflow`. **`client.console.*` is documented
+"Studio-internal… unstable" and is deliberately excluded from `endpoints.json`'s
+conformance runner** (`node/src/client.ts:114-116`). That means a `console.*`
+signature change ships with no lockstep protection for this bridge beyond
+`@w6w/sdk`'s own version — pin your `@w6w/sdk` version alongside `@w6w/react`'s, and
+re-test the bridge on an upgrade rather than assuming it.
+
+### Keeping `createW6WUiAdapter` in sync with the real `@w6w/ui`
+
+`package.json`'s `devDependencies` carries a **dev-only, type-only** edge onto
+`@w6w/ui` — `"@w6w/ui": "github:w6w-io/w6w-ui#<sha>"` — that this package never
+ships: `files: ["dist"]` means `dist/` is the only thing npm packs and publishes, so
+no installer of `@w6w/react` ever resolves or needs `@w6w/ui` at all. Its one job is
+`src/__tests__/ui-conformance.test.ts`, which runs at **dev/CI time only** (`npm
+test`, never part of `dist/`): it compiles `src/__tests__/ui-conformance.check.ts`
+against `@w6w/ui`'s real `provider.tsx` and fails, naming the member, the moment
+`createW6WUiAdapter`'s return type stops being assignable to the real `W6WApi` —
+closing the gap a hand-duplicated interface alone cannot (nothing previously caught
+this package's `W6WApi` drifting from `@w6w/ui`'s own).
+
+**Why a `github:<owner>/<repo>#<sha>` pin, and not a `link:`/workspace reference to
+a sibling checkout:** `release.yml`'s `react` step checks out **this one repo**
+(`w6w-wrappers`) with no sibling checkout and no submodules — a relative `link:` to `../../ui` resolves only in the
+local devcontainer's incidental directory layout and fails `ENOENT` on every CI run
+and on a fresh clone of `w6w-wrappers` alone. A `github:` spec needs nothing but a
+network fetch of the one pinned commit, which is why it is the only install story
+that survives both environments unchanged. The pin targets `provider.tsx` by
+RELATIVE PATH, not the `@w6w/ui` package barrel — the barrel's own import chain
+reaches `@w6w/expr` (`packages/core`) via a `github:…#path:` subpath npm does not
+honor on a `github:` dependency, which `TS2307`s the moment anything resolves it;
+`provider.tsx`'s own closure (`theme.ts` → `types.ts` → `react`) has no such edge.
+
+**Moving the pin:** update the `#<sha>` in `package.json`'s `@w6w/ui` entry to a
+commit on `w6w-io/w6w-ui`'s `main` (`git ls-remote https://github.com/w6w-io/w6w-ui
+main`) and run `npm install` again to refresh `package-lock.json`'s resolved
+entry — no code change is required unless `@w6w/ui`'s `W6WApi` itself changed
+shape, in which case `ui-conformance.test.ts` will say so.
 
 ## Hooks catalog
 
@@ -112,6 +220,11 @@ Every read hook returns `{data, error, loading, refetch}`; every mutation hook
 returns `{call, data, error, loading}`. None depends on react-query or any other
 data-fetching library.
 
+Read hooks asking for the same thing (same hook, same arguments, same provider) while a
+request is in flight share ONE request — two consumers, or React StrictMode's
+mount/unmount/mount, send a single fetch. Nothing is kept once it settles: a hook mounting
+later sends a new request, and `refetch()` starts a fresh one.
+
 | Hook | Wraps |
 |---|---|
 | `useMe()` | `client.me()` |
@@ -128,15 +241,52 @@ data-fetching library.
 | `useDeleteVar()` | `client.vars.delete()` |
 | `useConnections()` | `client.connections.list()` |
 | `useWorkflows(options?)` | `client.workflows.list()` |
+| `useWorkflow(id)` | `client.workflows.get()` |
+| `useCreateWorkflow()` | `client.workflows.create()` |
+| `useUpdateWorkflow()` | `client.workflows.update()` |
+| `useArchiveWorkflow()` | `client.workflows.archive()` |
+| `useDeleteWorkflow()` | `client.workflows.delete()` |
 | `useRunWorkflow()` | `client.workflows.run()`, defaults `wait: true` |
+| `useFunctions()` | `client.functions.list()` |
+| `useFunction(id)` | `client.functions.get()` |
+| `useCreateFunction()` | `client.functions.create()` |
+| `useUpdateFunction()` | `client.functions.update()` |
+| `useDeleteFunction()` | `client.functions.delete()` |
 | `useRun()` | `client.run()` (the generic URN dispatch) |
 
+Three things the definition hooks inherit from the SDK rather than invent:
+
+- **`create` mints the id.** The server requires one in the body and never
+  generates it, so `useCreateWorkflow().call({name, steps})` works and the
+  `wf_…` / `fn_…` id comes back in the result.
+- **`update` is a full replacement, not a patch.** This is the one place they
+  differ from `useUpdateDocument`/`useUpdateVar`, whose second argument is a
+  patch of just the fields to change. Read with `useWorkflow`/`useFunction`,
+  spread, change, send the whole thing back — passing only the changed fields
+  deletes the rest. `useUpdateWorkflow()`'s third argument carries
+  `ifUnmodifiedSince`: hand it the `updatedAt` from `useWorkflow` and a save
+  that would clobber someone else's edit is refused with `409 workflow_stale`
+  rather than winning silently.
+- **Deleting a workflow is two calls**, `useArchiveWorkflow` then
+  `useDeleteWorkflow`. Nothing chains them for you: the archive step is the one
+  a user can still change their mind after.
+
+No mutation hook refetches a list on success — this package carries no cache to
+invalidate, so pair one with the matching read hook's own `refetch`.
+
+`client.functions.run()` has **no** hook, and neither does `endpoints.run()` —
+that predates the definition hooks and is unchanged by them. `useRun()` reaches
+a Function by its `fn_…` id today (the server dispatches it through the same
+service the dedicated invoke route uses); calling one by the `key` a user gave
+it still means `useW6WClient().functions.run("send-email", …)`.
+
 `useRunWorkflow()`'s `call` defaults `wait: true` when the caller's options omit
 `wait`: `workflows.run` without `wait` (`node/src/workflows.ts`) leaves the caller
 with only a `runId` and no public polling operation to follow it with —
 `console.workflows.getRun` exists, but it is the same studio-internal, unstable
 surface described above, so this hook does not reach for it. Pass `wait: false`
-explicitly if you genuinely want the queued-and-walk-away behaviour.
+explicitly if you want the queued-and-walk-away behaviour, and follow the run
+with `` useW6WClient().request({ method: "GET", path: path`/runs/${runId}` }) ``.
 
 `useW6WClient()` returns the underlying `W6WClient` for anything not covered by a
 hook (e.g. `client.console.*` directly, at your own risk per the caveat above).
@@ -151,22 +301,11 @@ hook (e.g. `client.console.*` directly, at your own risk per the caveat above).
   fine — every extra field is optional — and there is no runtime data loss (the JSON
   payload is unfiltered); a caller typing a variable through this adapter's declared
   return type just gets no autocomplete for those extra fields.
-- **`ActionTestForm.tsx:149,176`'s error handling cannot be satisfied from this
-  package.** `@w6w/ui`'s `ActionTestForm` does a NOMINAL `instanceof ApiError` check
-  against its OWN `ApiError` class (`packages/ui/src/createW6WApi.ts`), not a
-  duck-typed one. No error object this adapter throws can ever satisfy that check
-  without importing `@w6w/ui`'s class directly, which this package's MIT/C-1
-  boundary forbids. Concretely: on a failed `invokeAction` used together with
-  `@w6w/ui`'s `ActionTestForm`, the 401/403 permission-hint messaging falls back to a
-  generic message, and the `ApiCallsPanel` egress log renders empty instead of
-  showing the outbound calls the action made — even though this adapter's thrown
-  error genuinely carries that data on `.body`/`.raw`. This adapter still aliases
-  `@w6w/sdk`'s `ApiError.raw` onto `.body` (`err.body === err.raw`) and sets
-  `err.name = "ApiError"`, so it is already correct for any DUCK-TYPING consumer, and
-  needs no further change the moment `@w6w/ui` switches its own check to one. The fix
-  belongs to `@w6w/ui`, not this package, and is filed there:
-  `.ai/projects/backlog/26-08-13-01-ui-error-nominal-check.md`.
-- **No `AbortSignal`/cancellation support in the hook set.** `@w6w/sdk`'s transport
-  (`node/src/http.ts`) has nothing to hook an abort into. A read hook only IGNORES a
-  result that resolves after its component unmounts (a mounted-ref guard); it cannot
-  cancel the in-flight request itself.
+- **Cancellation is per-hook, not exposed to the caller.** Every read hook aborts its
+  own superseded or unmounted calls internally (a superseded call, an `identityKey`
+  switch, or an unmount all abort the in-flight `AbortSignal` — but a shared request
+  aborts only when its LAST subscriber detaches, so StrictMode's remount or a second
+  consumer re-attaches instead of aborting it — see `src/hooks.ts`'s
+  module header) — but there is no option to pass your OWN `AbortSignal` into a hook
+  from outside it. `useW6WClient()` plus the underlying SDK method (which does take a
+  `signal`) is the escape hatch if you need that.

package/dist/mod.d.ts

@@ -1,8 +1,8 @@
 /**
  * `@w6w/react` — the package barrel.
  *
- * A thin React binding over `@w6w/sdk`: `<W6WProvider>` (the C-4
- * token-supplier shim), a small hook set, and `createW6WUiAdapter` (the
+ * A thin React binding over `@w6w/sdk`: `<W6WProvider>` (with its native token
+ * supplier), a small hook set, and `createW6WUiAdapter` (the
  * `@w6w/ui` `W6WApi` structural bridge, C-1/C-2). See `README.md` for the
  * install + wrap-your-root example, the hooks catalog, and this lane's
  * documented limitations.
@@ -14,6 +14,6 @@
  */
 export { VERSION } from "./src/version.ts";
 export { type TokenSource, useW6WClient, W6WProvider, type W6WProviderProps, } from "./src/W6WProvider.tsx";
-export { type MutationResult, type ReadResult, useConnections, useCreateDocument, useCreateVar, useDeleteDocument, useDeleteVar, useDocument, useDocumentByKey, useDocuments, useMe, useRun, useRunWorkflow, useUpdateDocument, useUpdateVar, useVar, useVars, useWorkflows, } from "./src/hooks.ts";
+export { type MutationResult, type ReadResult, useArchiveWorkflow, useConnections, useCreateDocument, useCreateFunction, useCreateVar, useCreateWorkflow, useDeleteDocument, useDeleteFunction, useDeleteVar, useDeleteWorkflow, useDocument, useDocumentByKey, useDocuments, useFunction, useFunctions, useMe, useRun, useRunWorkflow, useUpdateDocument, useUpdateFunction, useUpdateVar, useUpdateWorkflow, useVar, useVars, useWorkflow, useWorkflows, } from "./src/hooks.ts";
 export { createW6WUiAdapter, type W6WApi } from "./src/adapter.ts";
 //# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,MAAM,EACN,OAAO,EACP,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,KAAK,EACL,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/mod.js

@@ -1,8 +1,9 @@
+"use client";
 /**
  * `@w6w/react` — the package barrel.
  *
- * A thin React binding over `@w6w/sdk`: `<W6WProvider>` (the C-4
- * token-supplier shim), a small hook set, and `createW6WUiAdapter` (the
+ * A thin React binding over `@w6w/sdk`: `<W6WProvider>` (with its native token
+ * supplier), a small hook set, and `createW6WUiAdapter` (the
  * `@w6w/ui` `W6WApi` structural bridge, C-1/C-2). See `README.md` for the
  * install + wrap-your-root example, the hooks catalog, and this lane's
  * documented limitations.
@@ -14,6 +15,6 @@
  */
 export { VERSION } from "./src/version.js";
 export { useW6WClient, W6WProvider, } from "./src/W6WProvider.js";
-export { useConnections, useCreateDocument, useCreateVar, useDeleteDocument, useDeleteVar, useDocument, useDocumentByKey, useDocuments, useMe, useRun, useRunWorkflow, useUpdateDocument, useUpdateVar, useVar, useVars, useWorkflows, } from "./src/hooks.js";
+export { useArchiveWorkflow, useConnections, useCreateDocument, useCreateFunction, useCreateVar, useCreateWorkflow, useDeleteDocument, useDeleteFunction, useDeleteVar, useDeleteWorkflow, useDocument, useDocumentByKey, useDocuments, useFunction, useFunctions, useMe, useRun, useRunWorkflow, useUpdateDocument, useUpdateFunction, useUpdateVar, useUpdateWorkflow, useVar, useVars, useWorkflow, useWorkflows, } from "./src/hooks.js";
 export { createW6WUiAdapter } from "./src/adapter.js";
 //# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EAEL,YAAY,EACZ,WAAW,GAEZ,MAAM,sBAAuB,CAAC;AAE/B,OAAO,EAGL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,MAAM,EACN,OAAO,EACP,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAe,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EAEL,YAAY,EACZ,WAAW,GAEZ,MAAM,sBAAuB,CAAC;AAE/B,OAAO,EAGL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,KAAK,EACL,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAe,MAAM,kBAAkB,CAAC"}

package/dist/src/W6WProvider.d.ts

@@ -1,62 +1,104 @@
 /**
- * `<W6WProvider>` — one `W6WClient` per `baseUrl`, with per-request token
- * freshness (C-4).
+ * `<W6WProvider>` — one `W6WClient` per `{baseUrl, project, identityKey,
+ * refreshOnUnauthorized, headers}` combination, with the token resolved per
+ * request (concurrent requests share one supplier call).
  *
- * `@w6w/sdk`'s `W6WClientOptions.token` (`node/src/config.ts:41-63`) is
- * resolved ONCE, at construction, into `readonly` instance state
- * (`node/src/client.ts:59`) — there is no supplier form. A naive
- * `new W6WClient({ token })` therefore captures whatever `token` was at mount
- * time and never sees a later rotation.
+ * `@w6w/sdk`'s `W6WClientOptions.token` (`node/src/config.ts:41-63`) accepts
+ * either a plain string or a {@linkcode TokenProvider} function — the
+ * function form is called (and its result awaited) per request — requests in
+ * flight at the same time share ONE call, nothing is cached once it settles,
+ * and it is never resolved once at construction. This provider hands the
+ * SDK a single STABLE function that reads the CURRENT `token` prop through a
+ * ref: a string prop is returned as-is, a function prop is called with
+ * whatever `ctx` the SDK forwards (including `{forceRefresh: true}` on its
+ * own one-shot 401 recovery retry, `node/src/http.ts`). `fetch` and
+ * `onUnauthorized` are the same shape — stable wrappers over "latest" refs —
+ * so neither a token rotation, a new `fetch` identity, nor a new
+ * `onUnauthorized` closure identity ever rebuilds the client. A nullish or
+ * blank token (sync or async) never reaches the wire: the SDK's own
+ * `requireToken` raises a local {@linkcode ConfigError} before any `fetch`
+ * call, which is the floor `hooks.ts`'s `useAsync` reports as `loading`, not
+ * `error`.
  *
- * The fix lives at the `fetch`-injection seam, not the `token` seam.
- * `node/src/http.ts`'s `request()` builds `headers = new Headers(options.headers)`
- * and then unconditionally `headers.set("authorization", ...)` BEFORE calling
- * the injected `fetchImpl(url, {method, headers, body})` — `Headers.set`
- * REPLACES, so a custom `fetch` passed to `new W6WClient({ fetch })` can read
- * the CURRENT token and overwrite `authorization` on the `Headers` object it
- * receives, immediately before delegating to the real transport. This
- * provider therefore constructs its `W6WClient` ONCE, with a non-blank
- * placeholder token (any non-blank string satisfies `requireToken`,
- * `config.ts:229-237` — it is never actually sent, since the injected `fetch`
- * always overwrites it first) and an injected `fetch` that resolves the
- * current `token` prop (calling it, if it is a supplier) on every call.
+ * **What DOES rebuild the client** (the `useMemo` below): `baseUrl`,
+ * `project`, `identityKey`, `refreshOnUnauthorized`, and a canonical STRING of
+ * `headers`' sorted entries — never the `headers` object's own identity (an
+ * inline literal would rebuild the client on every render) and never
+ * `token`. `identityKey` (e.g. `${subject}:${account}`) is the one supported
+ * way to force a rebuild on purpose, for a host juggling more than one
+ * signed-in identity: every hook built on `useAsync` (`hooks.ts`) resets its
+ * state to `{data: undefined, error: undefined, loading: true}` when the
+ * client it reads through changes, aborting whatever it had in flight first —
+ * a stale account's data is never shown under a new one.
  *
- * **Do not key the outer `useMemo` on `token`.** `packages/studio/src/api/apiClient.tsx`
- * rebuilds its client whenever the token STRING changes — the right policy for
- * studio's own state-variable token, and the wrong one here: a supplier
- * function has a stable identity across renders, so keying on the supplier
- * would never rebuild AND never read a fresh value, while keying on the
- * token's resolved value would tear the client down and rebuild it on every
- * rotation — exactly what C-4 says not to do ("without tearing down"). The
- * memo below depends on `[baseUrl, project]` only; `token` and `fetch` are
- * read through "latest" refs, updated every render but never a dependency, so
- * a rotating token is read fresh per request without ever rebuilding the
- * client.
+ * `ready` (default `true`) gates every READ hook, never a mutation: while
+ * `false`, a read hook reports `loading: true` and never calls the SDK at
+ * all. Flipping it to `true` (or changing `identityKey`) fetches.
  *
  * @module
  */
-import { type FetchLike, W6WClient } from "@w6w/sdk";
+import { type ApiError, type FetchLike, type TokenProvider, W6WClient } from "@w6w/sdk";
 import { type ReactNode } from "react";
-/** A static bearer token, or a supplier read fresh on every request. */
-export type TokenSource = string | (() => string | null | undefined);
+/** A static bearer token, or a supplier called per request (concurrent requests share one call). */
+export type TokenSource = string | TokenProvider;
 export interface W6WProviderProps {
     /** The w6w server's origin, e.g. `"https://api.example.com"`. */
     baseUrl: string;
-    /** A literal bearer token, or a supplier called fresh on every request. */
+    /** A literal bearer token, or a supplier called per request (concurrent requests share one call). */
     token: TokenSource;
     /**
-     * The real transport this provider's injected `fetch` delegates to, after
-     * overwriting the `authorization` header. Defaults to `globalThis.fetch`.
-     * Mainly for tests — a caller wanting to record or stub outbound requests.
+     * The real transport this provider's stable `fetch` wrapper delegates to.
+     * Defaults to `globalThis.fetch`. Mainly for tests — a caller wanting to
+     * record or stub outbound requests.
      */
     fetch?: FetchLike;
     /** Default project id for the project-scoped operations (`documents.*`, `workflows.list`). */
     project?: string;
+    /**
+     * Default headers sent with every request — e.g. `{"X-W6W-Tenant": "t1"}`
+     * for a Path 3 tenant binding. Compared by CONTENT (sorted entries), not by
+     * object identity: a new-but-equal `headers` object on every render never
+     * rebuilds the client.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Gates every read hook. `false` (default `true`) means "I don't have a
+     * token/identity yet": no read hook calls the SDK, and every one reports
+     * `loading: true` until this flips — or forever, if it never does.
+     */
+    ready?: boolean;
+    /**
+     * Identifies WHICH signed-in identity this client speaks for. Changing it
+     * (e.g. `${subject}:${account}`) rebuilds the `W6WClient` and resets every
+     * read hook's state — the one supported way to switch accounts without a
+     * stale read from the previous identity ever rendering under the new one.
+     */
+    identityKey?: string;
+    /**
+     * Opt in to a single, one-shot recovery when a request 401s with
+     * `{code: "unauthorized"}`: the `token` supplier is called once more with
+     * `{forceRefresh: true}`, and a usable result retries the same request
+     * once. See `@w6w/sdk`'s `W6WClientOptions.refreshOnUnauthorized`.
+     */
+    refreshOnUnauthorized?: boolean;
+    /**
+     * Called with the terminal `401`/`unauthorized` error — after a failed
+     * recovery retry, or immediately when recovery is off or not possible — at
+     * most once per call. Always the LATEST `onUnauthorized` prop, read through
+     * a ref like `token`/`fetch`.
+     */
+    onUnauthorized?: (error: ApiError) => void;
     children: ReactNode;
 }
+interface W6WContextValue {
+    client: W6WClient;
+    /** Mirrors the `ready` prop. Read by `hooks.ts`'s `useAsync`, never by `useW6WClient`. */
+    ready: boolean;
+}
 /**
- * Provides one memoized `W6WClient` to every component under it. See this
- * module's header for the C-4 token-freshness mechanism.
+ * Provides one memoized `W6WClient` (plus `ready`) to every component under
+ * it. See this module's header for the token-freshness mechanism and the
+ * memoization policy.
  */
 export declare function W6WProvider(props: W6WProviderProps): ReactNode;
 /**
@@ -65,4 +107,12 @@ export declare function W6WProvider(props: W6WProviderProps): ReactNode;
  * `useW6WApi` shape — read-only reference, transcribed here, never imported).
  */
 export declare function useW6WClient(): W6WClient;
+/**
+ * Internal: the context value including `ready`, consumed only by the read
+ * hooks in `hooks.ts` (via a relative import — never re-exported from
+ * `mod.ts`). `useW6WClient`'s `W6WClient` return type is the public surface;
+ * this is the one extra bit every read hook needs to gate on.
+ */
+export declare function useW6WProviderContext(): W6WContextValue;
+export {};
 //# sourceMappingURL=W6WProvider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"W6WProvider.d.ts","sourceRoot":"","sources":["../../src/W6WProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,KAAK,SAAS,EAA8C,MAAM,OAAO,CAAC;AAEnF,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAUrE,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,KAAK,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CA8B9D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,SAAS,CASxC"}
+{"version":3,"file":"W6WProvider.d.ts","sourceRoot":"","sources":["../../src/W6WProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxF,OAAO,EAAE,KAAK,SAAS,EAA8C,MAAM,OAAO,CAAC;AAEnF,oGAAoG;AACpG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,aAAa,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,KAAK,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC3C,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,0FAA0F;IAC1F,KAAK,EAAE,OAAO,CAAC;CAChB;AAeD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAqE9D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,SAAS,CASxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CASvD"}