@clicktap/ui 0.40.8 → 0.40.9

package/docs/migrations/2026/04/2026-04-30-top-down-pdp-option-dependency.md

@@ -0,0 +1,286 @@
+# Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`
+
+**Date:** 2026-04-30
+**Affects:** New utility module `@clicktap/ui/utils/variantOptions` (ships generic `filterAvailableOptions`, `findVariant`, `getDownstreamAxisCodes`)
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+- Builds on the per-axis selection model used in [`apps/frontend/.../2026-04-24-pdp-configurable-selector-ux.md`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-pdp-configurable-selector-ux.md). The previous symmetric filter lived in the frontend app; that logic now lives here in generic, reusable form. See [`apps/frontend/.../2026-04-30-top-down-pdp-option-dependency.md`](2026-04-30-top-down-pdp-option-dependency.md) ↔ for the frontend-side migration steps that adopt the new utilities and switch to top-down semantics.
+
+## Summary
+
+Adds a small reusable module — `@clicktap/ui/utils/variantOptions` — for any consumer that builds a configurable-PDP variant picker. Three pure functions:
+
+1. **`filterAvailableOptions(variants, selections, axes, axisCode)`** — top-down: returns option codes selectable for `axisCode` given only the *upstream* selections (axes earlier in `axes`). Downstream selections never constrain.
+2. **`findVariant(variants, selections)`** — first variant whose attributes match every non-empty selection; matches by option `code` or `id`.
+3. **`getDownstreamAxisCodes(axes, axisCode)`** — axis codes after `axisCode` in `axes`. Useful for clearing dependent selections when an upstream axis changes.
+
+All three are generic (`<V extends VariantLike>`) and operate on a minimal structural shape so consumers don't have to flatten their domain types. Pure, no React dependency, no side effects.
+
+## Why top-down
+
+Symmetric filtering — selecting any axis filters every other axis equally — is what most early implementations do. It feels coherent until the user wants to change a higher-priority pick: every dependent dropdown is now scoped by their previous lower picks, and they can't re-explore the upstream space without manually clearing each lower selection first.
+
+Top-down inverts the relationship: the *first* axis is always fully open, the *second* is filtered by the first, and so on. Changing the first axis is free. The cost is that the consumer must clear lower selections when an upstream changes (their value may not exist in the new scope) — `getDownstreamAxisCodes` makes that mechanical.
+
+This module ships the filter logic only. The selection-state mechanics (clearing downstream when upstream changes, URL sync, manual-clear guards) stay in the consumer app since those are wired into framework-specific state and routing.
+
+## Changes
+
+### New module
+
+**Source:** `libs/ui/src/utils/variantOptions/`
+
+```
+libs/ui/src/utils/variantOptions/
+├── filterAvailableOptions.ts
+├── filterAvailableOptions.test.ts
+├── findVariant.ts
+├── findVariant.test.ts
+├── getDownstreamAxisCodes.ts
+├── getDownstreamAxisCodes.test.ts
+├── index.ts
+└── types.ts
+```
+
+### Public API
+
+```ts
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+  type VariantLike,
+  type VariantAttribute,
+} from '@clicktap/ui/utils/variantOptions';
+```
+
+### Type contract
+
+The minimum structural shape required by every function:
+
+```ts
+// libs/ui/src/utils/variantOptions/types.ts
+export interface VariantAttribute {
+  attribute: { code: string };
+  option: { code: string; id?: string | null };
+}
+
+export interface VariantLike {
+  attributes: VariantAttribute[];
+}
+```
+
+Real-world variants typically carry far more (price, image, sku, …). Pass them in as-is — the generic constraint only requires `attributes`.
+
+### `filterAvailableOptions`
+
+```ts
+export function filterAvailableOptions<V extends VariantLike>(
+  variants: V[],
+  selections: Record<string, string>,
+  axes: string[],
+  axisCode: string,
+): Set<string>
+```
+
+- `axes` is the contract: top-down order, upstream → downstream. The caller decides ordering (typically via the attribute's `sortPriority` from the backend).
+- For `axisCode` at index `i` in `axes`, only `selections[axes[0]]…selections[axes[i-1]]` constrain. Selections on `axes[i+1]…` are ignored.
+- `axisCode === axes[0]` (or any axis not in `axes`) returns the full reachable set across `variants` for that code.
+- Empty-string and `undefined` selections are treated as unconstrained.
+
+### `findVariant`
+
+```ts
+export function findVariant<V extends VariantLike>(
+  variants: V[],
+  selections: Record<string, string>,
+): V | undefined
+```
+
+- Empty/missing selections per axis are unconstrained.
+- A selection matches if it equals either the option's `code` or `id` — supports callers that key by either.
+
+### `getDownstreamAxisCodes`
+
+```ts
+export function getDownstreamAxisCodes(
+  axes: string[],
+  axisCode: string,
+): string[]
+```
+
+- Returns `axes.slice(idx + 1)` where `idx = axes.indexOf(axisCode)`.
+- Returns `[]` if `axisCode` isn't in `axes` (defensive — caller may pass a non-axis code).
+
+## Pattern for Consumers
+
+A minimal PDP variant picker built on these utilities looks like this:
+
+```tsx
+import { useMemo, useCallback, useState } from 'react';
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+} from '@clicktap/ui/utils/variantOptions';
+
+type Variant = {
+  id: string;
+  attributes: Array<{
+    attribute: { code: string };
+    option: { code: string; id?: string };
+  }>;
+  // ...your domain fields
+};
+
+type Props = {
+  // Top-down ordered axes — upstream first.
+  axes: { code: string; label: string; options: { code: string; label: string }[] }[];
+  variants: Variant[];
+};
+
+export function VariantPicker({ axes, variants }: Props) {
+  const axisCodes = useMemo(() => axes.map((a) => a.code), [axes]);
+  const [selections, setSelections] = useState<Record<string, string>>({});
+
+  const setSelection = useCallback(
+    (axisCode: string, optionCode: string) => {
+      setSelections((prev) => {
+        // Top-down: clear any selection downstream of this axis. Their value
+        // may not exist in the new upstream scope.
+        const downstream = getDownstreamAxisCodes(axisCodes, axisCode);
+        const next: Record<string, string> = { ...prev, [axisCode]: optionCode };
+        for (const code of downstream) {
+          delete next[code];
+        }
+        return next;
+      });
+    },
+    [axisCodes],
+  );
+
+  const matchedVariant = useMemo(
+    () => findVariant(variants, selections),
+    [variants, selections],
+  );
+
+  return (
+    <div>
+      {axes.map((axis) => {
+        const reachable = filterAvailableOptions(
+          variants,
+          selections,
+          axisCodes,
+          axis.code,
+        );
+        return (
+          <div key={axis.code}>
+            <label>{axis.label}</label>
+            {axis.options
+              .filter((o) => reachable.has(o.code))
+              .map((o) => (
+                <button
+                  key={o.code}
+                  aria-pressed={selections[axis.code] === o.code}
+                  onClick={() => setSelection(axis.code, o.code)}
+                >
+                  {o.label}
+                </button>
+              ))}
+          </div>
+        );
+      })}
+      {matchedVariant && <p>Matched: {matchedVariant.id}</p>}
+    </div>
+  );
+}
+```
+
+Annotations:
+- The `setSelections` callback is the entire top-down rule — clear downstream on any upstream change. Skip this and the picker behaves as a buggy version of symmetric filtering.
+- `filterAvailableOptions` is called once per axis on each render. Cheap — O(variants × attributes).
+- The pattern intentionally doesn't cover URL sync, manual-clear guards, or auto-collapse. Those are framework- and routing-specific; layer them on top.
+
+## Migration Steps
+
+This module is purely additive — there's no migration *required* of existing `@clicktap/ui` consumers. The steps below are for consumers who want to adopt it.
+
+### 1. Bump `@clicktap/ui`
+
+Once a release including this module is published, update the dependency:
+
+```bash
+pnpm up @clicktap/ui
+```
+
+Minimum version: **next minor after 0.27.2** (set the explicit floor once released).
+
+### 2. Import where needed
+
+```ts
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+} from '@clicktap/ui/utils/variantOptions';
+```
+
+### 3. Pass top-down axis order
+
+Wherever you call `filterAvailableOptions`, pass the axes array in upstream-to-downstream order. The natural source is your attribute list sorted by priority — for backends following the Clicktap shape, that's `sortPriority DESC`:
+
+```ts
+const axisCodes = product.attributes.map((a) => a.code);
+// product.attributes is already sorted by sortPriority DESC server-side.
+
+const reachable = filterAvailableOptions(
+  product.variants,
+  userSelections,
+  axisCodes,
+  attribute.code,
+);
+```
+
+### 4. Clear downstream on upstream change
+
+When the user picks a value for any axis, drop any downstream selections in the same state update:
+
+```ts
+const setUserSelection = (axisCode: string, optionCode: string) => {
+  setSelections((prev) => {
+    const downstream = getDownstreamAxisCodes(axisCodes, axisCode);
+    const next = { ...prev, [axisCode]: optionCode };
+    for (const code of downstream) {
+      delete next[code];
+    }
+    return next;
+  });
+};
+```
+
+Skip this and you'll occasionally see the matched variant query against an impossible (upstream-changed but downstream-stale) selection set.
+
+### Verification
+
+- New axis renders all reachable options regardless of downstream state.
+- Picking the upper axis clears the lower selections.
+- Picking the lowest axis doesn't change which upper options are reachable.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/variantOptions/types.ts` | New — `VariantLike`, `VariantAttribute` |
+| `libs/ui/src/utils/variantOptions/filterAvailableOptions.ts` | New — top-down filter |
+| `libs/ui/src/utils/variantOptions/findVariant.ts` | New — generic match |
+| `libs/ui/src/utils/variantOptions/getDownstreamAxisCodes.ts` | New — slice helper |
+| `libs/ui/src/utils/variantOptions/index.ts` | New — barrel export |
+| `libs/ui/src/utils/variantOptions/*.test.ts` | New — Jest coverage (15 tests) |
+
+## References
+
+- Frontend counterpart migration: [`apps/frontend/.../2026-04-30-top-down-pdp-option-dependency.md`](2026-04-30-top-down-pdp-option-dependency.md) ↔
+- Prior symmetric-filter implementation it replaces: [`apps/frontend/.../2026-04-24-pdp-configurable-selector-ux.md`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-pdp-configurable-selector-ux.md)

package/docs/migrations/2026/05/2026-05-01-build-pdp-url-util.md

@@ -0,0 +1,128 @@
+# `buildPdpUrl` Utility — `@clicktap/ui/utils/buildPdpUrl`
+
+**Date:** 2026-05-01
+**Affects:** `@clicktap/ui/utils/buildPdpUrl` — new export
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+*None.*
+
+## Summary
+
+Adds `buildPdpUrl(canonicalUrl, typeOptions)` to `@clicktap/ui/utils/buildPdpUrl`. Encodes a configurable item's variant selections onto its PDP canonical URL as `?attributeCode=optionCode` pairs, matching `ProductTypeResolver.writeSelectionsToUrl` so deep-linking from a cart/order item lands on the exact variant.
+
+## Why
+
+Cart and order item rows hold both a canonical URL (e.g. `/everyday-backpack`) and a list of selected attributes (e.g. `color: orange`, `size: m`). Linking with just the canonical URL drops the variant context — the customer lands on the PDP with no swatch pre-selected and has to re-pick. Encoding the selections onto the link mirrors what the PDP itself writes back to the URL on swatch change, so navigating into a PDP from a cart/order row produces the same URL as if the user had configured the PDP themselves.
+
+The helper was originally inlined under `apps/frontend/components/Checkout/Success/Items/buildPdpUrl.ts`, used only by the order-success page. Promoting it to `@clicktap/ui` makes it reusable from the cart drawer (and any future consumer that pairs a canonical URL with a `typeOptions`-shaped attribute list).
+
+## Public API
+
+```ts
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+```
+
+```ts
+/**
+ * Append configurable-product variant selections to a PDP canonical URL as
+ * `?attributeCode=optionCode` pairs (e.g. `?color=black`).
+ *
+ * Accepts the structural shape that any cart-item / order-item / quote-item
+ * `typeOptions` produces on the configurable case.
+ *
+ * Returns the URL unchanged when:
+ *   - the URL is null/empty,
+ *   - the item isn't configurable (no attributes), or
+ *   - the existing URL already carries a query string (we don't merge —
+ *     the item's own variant context is authoritative, and bailing keeps
+ *     caller intent clear).
+ */
+function buildPdpUrl(
+  canonicalUrl: string | null | undefined,
+  typeOptions: unknown,
+): string | null;
+```
+
+The `typeOptions` parameter is intentionally typed `unknown` and read structurally as `{ attributes?: Array<{ attribute?: { code? }, option?: { code? } }> }`. This lets the same helper accept both `OrderItemTypeOptions` and `QuoteItemTypeOptions` (and any other GraphQL union with the same shape) without forcing the lib to import the consumer's generated types.
+
+## Behavior summary
+
+| Input | Output |
+|---|---|
+| `(null, ...)` | `null` |
+| `('', ...)` | `null` |
+| `('/foo', null)` | `'/foo'` |
+| `('/foo', { attributes: [] })` | `'/foo'` |
+| `('/foo', { attributes: [{ attribute: { code: 'color' }, option: { code: 'red' } }] })` | `'/foo?color=red'` |
+| `('/foo', { attributes: [{ color }, { size }] })` | `'/foo?color=red&size=m'` |
+| `('/foo?bar=1', { attributes: [...] })` | `'/foo?bar=1'` (URL has a query — bail rather than merge) |
+
+## Pattern for Consumers
+
+Use it wherever a cart/order item row links to its PDP and you want the variant pre-selected:
+
+```tsx
+import { Link } from '@clicktap/ui/components/Link';
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+
+function CartItemRow({ item }: { item: QuoteItem }) {
+  const pdpUrl = buildPdpUrl(item.product.canonicalUrl, item.typeOptions) ?? '';
+  return (
+    <Link href={pdpUrl}>
+      {item.name}
+    </Link>
+  );
+}
+```
+
+The function is structural, so `item.typeOptions` doesn't need to be cast — pass it directly.
+
+## Migration Steps
+
+This is purely additive — existing code keeps compiling. To adopt:
+
+### 1. Bump `@clicktap/ui`
+
+```bash
+pnpm up @clicktap/ui
+```
+
+Minimum version: **next minor after the release that ships this migration**.
+
+### 2. Replace any inlined copies with the shared util
+
+Search consumer projects for inlined copies that predate this migration:
+
+```bash
+grep -rn 'buildPdpUrl' apps/ libs/ --include='*.ts' --include='*.tsx'
+```
+
+Switch each call site to:
+
+```ts
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+```
+
+If the consumer project had its own typed-to-`OrderItemTypeOptions` (or any other concrete) signature, the structural `unknown` parameter accepts it without any cast change at the call site — the existing arguments compile as-is.
+
+### 3. (Optional) Wire it into cart/order link components
+
+Anywhere a cart/order row currently links via `product.canonicalUrl` directly, swap to `buildPdpUrl(product.canonicalUrl, typeOptions)`. Make sure your GraphQL selection actually fetches `canonicalUrl` and the `typeOptions { ... attributes { attribute { code }, option { code } } }` block — without those, the helper returns the URL unchanged and the variant won't pre-select.
+
+### Verification
+
+- **Behavior**: open a cart drawer (or order success page) for a configurable product with attributes set, click the item link. The PDP should load with the swatches matching the variant pre-selected.
+- **Typecheck**: `nx run <app>:typecheck` → no errors.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/buildPdpUrl.ts` | New — structural helper |
+
+## References
+
+- PDP encoding source of truth: `apps/frontend/components/Product/ProductType/.../ProductTypeResolver.writeSelectionsToUrl`

package/docs/migrations/2026/05/2026-05-03-auth-aware-graphql-client.md

@@ -0,0 +1,278 @@
+# Auth-aware GraphQL client — `@clicktap/ui/utils/createAuthAwareGraphqlClient`
+
+**Date:** 2026-05-03
+**Affects:** `@clicktap/ui/utils/createAuthAwareGraphqlClient` — new export
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+*None.*
+
+## Summary
+
+Adds two factories and an event bus for handling `graphql-request` responses uniformly across consumer apps:
+
+- `createAuthAwareGraphqlClient()` — returns a `request(url, doc, vars, headers)` callable plus a `.withOptions({ … signal })` overload. Drop-in for any caller that previously used bare `request()` from `graphql-request`.
+- `createAuthAwareFetch()` — returns a `fetch` function suitable for `new GraphQLClient(url, { fetch: … })` when the caller manages their own client config (cors, credentials, custom headers).
+- `authAwareEvents` — a small, app-runtime-agnostic event bus. Both factories dispatch `unauthenticated` (HTTP 401), `permissionDenied` (403), and `serverError` (5xx) events. Consumer apps subscribe from a Provider component (where xstate actors and routers are in scope) to wire logout / toast / redirect.
+
+The `request()` form additionally returns the partial `data` from a HTTP-200-with-errors response — single-field GraphQL errors don't tear down the whole UI. (Same behavior the prior project-level `apps/frontend/utils/graphqlRequest.ts` had — moved here so every consumer gets it for free.)
+
+## Why
+
+Every consumer app was reinventing the same four pieces in its own actors / mutation handlers:
+
+1. 401 → log out + toast + redirect to login
+2. 403 → permission-denied toast
+3. 5xx → service-unavailable toast
+4. Partial responses → return `data`, don't throw
+
+The 401 path in particular was load-bearing for the upcoming "no-guest storefront" pattern (see [`2026-05-03-guest-checkout-disabled-storefront.md`](#) cross-app guides), but its scope is broader: any project that wants its session-expired UX coherent benefits.
+
+The factory pattern decouples the lib from app runtime context. The lib emits typed events; the app subscribes from a Provider where it has the runtime concerns (auth machine, toast actor, router). Lib stays pure; consumers stay flexible.
+
+## Public API
+
+```ts
+import {
+  createAuthAwareGraphqlClient,
+  createAuthAwareFetch,
+  authAwareEvents,
+  ClientError, // re-exported — see "Cross-package error handling" below
+  GraphQLClient, // re-exported
+  type AuthAwareEventName,
+  type AuthAwareEventDetail,
+} from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+
+import { getRequestErrorStatus } from '@clicktap/ui/utils/error';
+```
+
+```ts
+/**
+ * Returns a callable: `(url, document, variables?, headers?) => Promise<TData>`.
+ * Plus a `.withOptions({ url, document, variables?, headers?, signal? })` form
+ * for actors needing AbortSignal support.
+ *
+ * Internally creates a fresh GraphQLClient per call. On error: dispatches
+ * the appropriate event (401/403/5xx) and either rethrows or returns the
+ * partial `data` from a HTTP-200-with-errors response.
+ */
+function createAuthAwareGraphqlClient(): AuthAwareGraphqlClient;
+
+/**
+ * Returns a `fetch` function. Pass to:
+ *   new GraphQLClient(url, { fetch: createAuthAwareFetch(), credentials, mode, … })
+ *
+ * Wraps the global `fetch`. On 401/403/5xx response, dispatches the
+ * matching event with `{ status, response }`. The original Response is
+ * returned untouched — graphql-request still parses, throws, etc. exactly
+ * as it would have. The event dispatch is a side channel.
+ */
+function createAuthAwareFetch(): typeof fetch;
+
+/**
+ * Module-level event bus. Subscribe with a callback; returns an unsubscribe
+ * function.
+ *
+ *   authAwareEvents.subscribe('unauthenticated', ({ status, error, response }) => { … });
+ */
+export const authAwareEvents: {
+  subscribe(name: AuthAwareEventName, listener: (detail: AuthAwareEventDetail) => void): () => void;
+  dispatch(name: AuthAwareEventName, detail: AuthAwareEventDetail): void;
+};
+
+type AuthAwareEventName = 'unauthenticated' | 'permissionDenied' | 'serverError';
+interface AuthAwareEventDetail {
+  status: number;
+  /** Set when triggered from a `graphql-request` ClientError. */
+  error?: ClientError;
+  /** Set when triggered from the fetch wrapper. */
+  response?: Response;
+}
+```
+
+## Pattern for consumers
+
+Inside a Provider component (where actors + router + toast are in scope):
+
+```tsx
+import { authAwareEvents } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+import { useAuth } from '@/state/auth/AuthProvider';
+import { useToast } from '@/state/toast/ToastProvider';
+
+function AuthAwareEventBridge({ children }: { children: ReactNode }) {
+  const { authActor } = useAuth();
+  const { toastActor } = useToast();
+
+  useEffect(() => {
+    const unsubUnauth = authAwareEvents.subscribe('unauthenticated', () => {
+      authActor.send({ type: 'LOGOUT' });
+      toastActor.send({
+        type: 'ADD_ITEM',
+        item: <Alert type="error" title="Session expired" message="Please log in again." />,
+        duration: 5000,
+      });
+    });
+    const unsubPerm = authAwareEvents.subscribe('permissionDenied', () => {
+      toastActor.send({
+        type: 'ADD_ITEM',
+        item: <Alert type="error" title="Permission denied" />,
+        duration: 5000,
+      });
+    });
+    const unsub5xx = authAwareEvents.subscribe('serverError', () => {
+      toastActor.send({
+        type: 'ADD_ITEM',
+        item: <Alert type="error" title="Service unavailable" />,
+        duration: 5000,
+      });
+    });
+    return () => { unsubUnauth(); unsubPerm(); unsub5xx(); };
+  }, [authActor, toastActor]);
+
+  return <>{children}</>;
+}
+```
+
+For raw callers, two flavors:
+
+**Caller that previously used `request()` from `graphql-request`:**
+
+```ts
+// Before
+import { request } from 'graphql-request';
+const data = await request(url, document, vars, headers);
+
+// After
+import { graphqlRequest } from '@/utils/graphqlRequest';
+// where graphqlRequest is `createAuthAwareGraphqlClient()` instantiated once at module scope
+const data = await graphqlRequest(url, document, vars, headers);
+```
+
+**Caller that constructs its own `GraphQLClient`:**
+
+```ts
+// Before
+const client = new GraphQLClient(url, { credentials: 'include', mode: 'cors' });
+
+// After
+import { createAuthAwareFetch } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+const client = new GraphQLClient(url, {
+  credentials: 'include',
+  mode: 'cors',
+  fetch: createAuthAwareFetch(),
+});
+```
+
+## Cross-package error handling — `ClientError` re-export + `getRequestErrorStatus`
+
+**Added 2026-06-15.**
+
+`graphql-request` is bundled into every consuming package, so its `ClientError`
+class is a *different object* in each bundle. A consumer that catches an error
+thrown by this client and checks `error instanceof ClientError` using its **own**
+`import { ClientError } from 'graphql-request'` always gets `false` — the class
+identities don't match across the package boundary. In practice this silently
+broke the 401→login redirect on SSR route fetches: the `instanceof` guard
+failed, the 401 fell through to a rethrow, and the page **500'd instead of
+redirecting**.
+
+Two fixes, both additive:
+
+1. **`ClientError` (and `GraphQLClient`) are re-exported from the client
+   module.** Import them from `@clicktap/ui` so the class identity matches the
+   one this client throws:
+
+   ```ts
+   import { ClientError } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+
+   try {
+     return await fetchRoute(path);
+   } catch (error) {
+     if (error instanceof ClientError && error.response?.status === 401) {
+       redirect('/account/authenticate?…');
+     }
+     throw error;
+   }
+   ```
+
+2. **`getRequestErrorStatus(error)` — identity-agnostic status extraction.**
+   Prefer this at cross-package boundaries: it duck-types `response.status`, so
+   it works regardless of which bundle threw, with no `instanceof` at all.
+   Returns `undefined` when no numeric status is present.
+
+   ```ts
+   import { getRequestErrorStatus } from '@clicktap/ui/utils/error';
+
+   try {
+     return await fetchRoute(path);
+   } catch (error) {
+     if (getRequestErrorStatus(error) === 401) {
+       redirect(`/account/authenticate?redirect=${path}&reason=authentication_required`);
+     }
+     throw error;
+   }
+   ```
+
+### SSR route fetches must forward the auth token
+
+Now that catalog/entity routes can be auth-gated on the backend (the router's
+`EntityAuthenticationGate` 401s a guest request whose route resolves to a gated
+entity type), an SSR route/data fetch that omits the caller's bearer token makes
+a **logged-in user look unauthenticated to the gate** — they get bounced like a
+guest. SSR fetches for gated routes must forward `Authorization: Bearer <token>`
+from the request's session:
+
+```ts
+const token = await getAccessToken(); // request-memoized; no extra round-trip
+const data = await graphqlRequest(url, GetRoute, { path }, {
+  ...scopeHeaders,
+  ...(token ? { Authorization: `Bearer ${token}` } : {}),
+});
+```
+
+The storefront-auth-gating guide documents where route protection is configured.
+
+## Migration Steps
+
+This is purely additive — existing code keeps compiling. To adopt:
+
+### 1. Bump `@clicktap/ui`
+
+```bash
+pnpm up @clicktap/ui
+```
+
+Minimum version: **next minor after the release that ships this migration**.
+
+### 2. Build a Provider-level event bridge
+
+Mount it once high in the tree (alongside `AuthProvider` / `ToastProvider`). Subscribe to the three events, dispatch into your project's runtime. See "Pattern for consumers" above.
+
+### 3. (Incremental) Migrate actors that hit gated GraphQL operations
+
+For any actor that performs a mutation the backend has gated behind auth (e.g. cart mutations on a no-guest storefront), switch its GraphQL call to one of the two forms above. The wrapping is what fires the events.
+
+Actors that hit non-gated operations don't need migration unless you want their 5xx / 403 to surface a toast too — adopt incrementally.
+
+## Verification
+
+- **Typecheck** clean.
+- **Browser smoke test**:
+  1. Mount a page that performs a wrapped GraphQL request.
+  2. Force the response to 401 (devtools → request blocking → respond with 401, or expire the JWT).
+  3. Confirm: subscriber callback fires; auth/toast/router behave as wired.
+  4. Repeat for 403 and 503.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/createAuthAwareGraphqlClient.ts` | NEW — factories + event bus; re-exports `ClientError`/`GraphQLClient` (2026-06-15) |
+| `libs/ui/src/utils/error.ts` | `getRequestErrorStatus()` — identity-agnostic HTTP-status extraction (2026-06-15) |
+
+## References
+
+- Frontend wiring (consumes this): [`apps/frontend/.../2026-05-03-guest-checkout-disabled-storefront.md`](../../../../../apps/frontend/docs/migrations/2026/05/2026-05-03-guest-checkout-disabled-storefront.md)
+- Backend that 401s the gated operations: [`apps/middleware/.../2026-05-03-guest-checkout-disabled-storefront.md`](../../../../../apps/middleware/docs/migrations/2026/05/2026-05-03-guest-checkout-disabled-storefront.md)