@clicktap/ui 2.1.4 → 2.2.0

package/docs/migrations/2026/09/ui-2026-09-15-server-request-headers-provider.md

@@ -0,0 +1,52 @@
+# `createAuthAwareGraphqlClient`: a server-side request-headers provider, so SSR calls can carry the shopper
+
+**Date:** 2026-09-15
+**Package:** `@clicktap/ui`
+**Affects:** `utils/createAuthAwareGraphqlClient` — new export `setServerRequestHeadersProvider()`; `executeGraphql` and `createAuthAwareFetch` consult it server-side
+**Classification:** FEATURE
+**Breaking:** No. Nothing changes until a provider is registered; explicit request headers always win over provided ones.
+**Ticket:** CTAP-1719
+
+## Why
+
+A request the Node server makes to the middleware on a shopper's behalf (SSR, route handlers)
+carried nothing identifying the shopper — the middleware saw the Node container for every visitor.
+Anything keyed on the client there (a rate limit, a lockout) would put the whole storefront in one
+bucket.
+
+The fix has to be in the shared client, because that is the one place every server-side request
+passes through — `graphqlRequest`, the quote/checkout transports (`request` and `createFetch`), route
+handlers. But this module is framework-agnostic and reachable from client components, so it cannot
+import `next/headers` itself. Hence a **provider** the app registers:
+
+```ts
+import { setServerRequestHeadersProvider } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+
+setServerRequestHeadersProvider(() => {
+  const forwardedFor = headers().get('x-forwarded-for');   // next/headers, in a server-only module
+  return forwardedFor ? { 'x-forwarded-for': forwardedFor } : undefined;
+});
+```
+
+## Rules
+
+- Consulted **only server-side** (`typeof window === 'undefined'`); the browser path is untouched.
+- **Explicit headers win.** A header the caller passed is never overwritten by the provider.
+- **A throwing provider contributes nothing.** `headers()` throws outside a request scope (a static
+  render, a warm-up); that is "nothing to forward", not a failed request.
+- Sync or async providers are accepted.
+- Applies to both `createAuthAwareGraphqlClient()` requests and `createAuthAwareFetch()` calls.
+
+## What a consumer does
+
+Register a provider from a **server-only** module (`import 'server-only'` + `next/headers`), imported
+by the root layouts and by any route handler that fetches — see the `frontend` guide of the same
+date for the reference module. Forward the incoming `X-Forwarded-For` **verbatim**: the middleware's
+trusted-proxy walk reads it from its own end, so the browser's forged entries are inert and
+"cleaning" the chain here would only remove information.
+
+## Verification
+
+```bash
+nx run ui:test -- createAuthAwareGraphqlClient
+```

package/docs/migrations/index.json

@@ -9,6 +9,16 @@
     "breaking": "No API change. **Behavioral:** while its trigger is closed and has never opened, the overlay now renders `null` instead of a mounted `motion()` wrapper around an empty react-aria overlay. Nothing consumer-visible was in the DOM before either.",
     "affects": "`src/components/ModalOverlay/ModalOverlay.tsx` — every trigger-driven `<ModalOverlay>` (no `isOpen` prop, state from `DialogTrigger` / `OverlayTriggerStateContext`). Controlled overlays (`isOpen` given) are unchanged."
   },
+  {
+    "path": "2026/09/ui-2026-09-15-server-request-headers-provider.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-15",
+    "title": "`createAuthAwareGraphqlClient`: a server-side request-headers provider, so SSR calls can carry the shopper",
+    "classification": "FEATURE",
+    "breaking": "No. Nothing changes until a provider is registered; explicit request headers always win over provided ones.",
+    "affects": "`utils/createAuthAwareGraphqlClient` — new export `setServerRequestHeadersProvider()`; `executeGraphql` and `createAuthAwareFetch` consult it server-side"
+  },
   {
     "path": "2026/09/ui-2026-09-09-graphql-field-errors-reported-in-production.md",
     "module": "libs/frontend-modules/ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",

package/utils/createAuthAwareGraphqlClient.d.ts

@@ -111,6 +111,24 @@ declare class AuthAwareEventBus {
  * listen, regardless of which call triggered the event).
  */
 export declare const authAwareEvents: AuthAwareEventBus;
+/**
+ * Headers a SERVER-SIDE caller wants attached to every outbound request, resolved per request.
+ *
+ * CTAP-1719: a request the Node server makes to the middleware on a shopper's behalf (SSR, route
+ * handlers) carried no trace of the shopper — the middleware saw the Node container's address for
+ * every visitor, so anything keyed on the client (a rate limit, a lockout) would put the whole
+ * storefront in one bucket. The app registers a provider that reads the incoming request's
+ * `X-Forwarded-For` (via `next/headers`, which only exists in a request scope) and returns it here,
+ * so the middleware's trusted-proxy walk lands on the browser rather than on Node.
+ *
+ * Registered rather than imported because this module must stay framework-agnostic and bundleable
+ * on the client: `next/headers` cannot be imported from anything a client component reaches. The
+ * provider is only ever consulted server-side (`typeof window === 'undefined'`); explicit request
+ * headers always win over what it returns; and a provider that throws (no request scope — a build-time
+ * render, a cron) contributes nothing rather than failing the request.
+ */
+export type ServerRequestHeadersProvider = () => HeadersInit | undefined | Promise<HeadersInit | undefined>;
+export declare function setServerRequestHeadersProvider(provider: ServerRequestHeadersProvider | undefined): void;
 export type AuthAwareGraphqlRequest = <TData, TVariables extends GraphqlVariables = GraphqlVariables>(url: string, document: GraphqlDocument<TData, TVariables>, variables?: TVariables, requestHeaders?: HeadersInit) => Promise<TData>;
 export type AuthAwareGraphqlRequestWithOptions = <TData, TVariables extends GraphqlVariables = GraphqlVariables>(options: {
     url: string;

package/utils/createAuthAwareGraphqlClient.js

@@ -1 +1 @@
-class l extends Error{constructor(t,s){const e=t.errors?.[0]?.message;super(`GraphQL request failed: ${e??`HTTP ${t.status}`}`),this.name="ClientError",this.response=t,this.request=s}}class f{constructor(){this.listeners=new Map}subscribe(t,s){return this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(s),()=>{this.listeners.get(t)?.delete(s)}}dispatch(t,s){this.listeners.get(t)?.forEach(e=>e(s))}}const u=new f;function p(r,t){r===401?u.dispatch("unauthenticated",t):r===403?u.dispatch("permissionDenied",t):r>=500&&u.dispatch("serverError",t)}function w(r,t,s){if(!s.length)return;const e=r.match(/^\s*(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/)?.[1];for(const n of s){const c=n.path?.join(".")??"unknown",a=`[GraphQL] ${e??"operation"} — field error at ${c}: ${n.message}`;if(process.env.NODE_ENV==="development"){console.error(a,{error:n,request:{operationName:e,variables:t,query:r}});continue}console.error(a,{operationName:e,path:n.path,code:n.extensions?.code,debugMessage:n.extensions?.debugMessage})}}async function d(r){const{url:t,query:s,variables:e,requestHeaders:n,signal:c}=r,a=new Headers(n);a.set("Content-Type","application/json"),a.has("Accept")||a.set("Accept","application/json");const i=await fetch(t,{method:"POST",headers:a,body:JSON.stringify({query:s,variables:e}),signal:c});let o;try{o=await i.json()}catch{o=void 0}if(!i.ok){const h=new l({status:i.status,data:o?.data,errors:o?.errors},{query:s,variables:e});throw p(i.status,{status:i.status,error:h}),h}if(o?.data)return o.errors?.length&&w(s,e,o.errors),o.data;throw new l({status:i.status,errors:o?.errors},{query:s,variables:e})}function g(){const r=async(e,n,c,a)=>d({url:e,query:String(n),variables:c,requestHeaders:a}),t=async e=>d({url:e.url,query:String(e.document),variables:e.variables,requestHeaders:e.requestHeaders,signal:e.signal}),s=r;return s.withOptions=t,s}function y(){return async function(t,s){const e=await fetch(t,s);return(e.status===401||e.status===403||e.status>=500)&&p(e.status,{status:e.status,response:e.clone()}),e}}export{l as ClientError,u as authAwareEvents,y as createAuthAwareFetch,g as createAuthAwareGraphqlClient};
+class l extends Error{constructor(t,s){const e=t.errors?.[0]?.message;super(`GraphQL request failed: ${e??`HTTP ${t.status}`}`),this.name="ClientError",this.response=t,this.request=s}}class v{constructor(){this.listeners=new Map}subscribe(t,s){return this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(s),()=>{this.listeners.get(t)?.delete(s)}}dispatch(t,s){this.listeners.get(t)?.forEach(e=>e(s))}}const u=new v;function p(r,t){r===401?u.dispatch("unauthenticated",t):r===403?u.dispatch("permissionDenied",t):r>=500&&u.dispatch("serverError",t)}function g(r,t,s){if(!s.length)return;const e=r.match(/^\s*(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/)?.[1];for(const n of s){const a=n.path?.join(".")??"unknown",o=`[GraphQL] ${e??"operation"} — field error at ${a}: ${n.message}`;if(process.env.NODE_ENV==="development"){console.error(o,{error:n,request:{operationName:e,variables:t,query:r}});continue}console.error(o,{operationName:e,path:n.path,code:n.extensions?.code,debugMessage:n.extensions?.debugMessage})}}let d;function y(r){d=r}async function w(){if(!(typeof window<"u"||!d))try{const r=await d();return r?new Headers(r):void 0}catch{return}}async function q(r){return(await w())?.forEach((s,e)=>{r.has(e)||r.set(e,s)}),r}async function f(r){const{url:t,query:s,variables:e,requestHeaders:n,signal:a}=r,o=await q(new Headers(n));o.set("Content-Type","application/json"),o.has("Accept")||o.set("Accept","application/json");const c=await fetch(t,{method:"POST",headers:o,body:JSON.stringify({query:s,variables:e}),signal:a});let i;try{i=await c.json()}catch{i=void 0}if(!c.ok){const h=new l({status:c.status,data:i?.data,errors:i?.errors},{query:s,variables:e});throw p(c.status,{status:c.status,error:h}),h}if(i?.data)return i.errors?.length&&g(s,e,i.errors),i.data;throw new l({status:c.status,errors:i?.errors},{query:s,variables:e})}function E(){const r=async(e,n,a,o)=>f({url:e,query:String(n),variables:a,requestHeaders:o}),t=async e=>f({url:e.url,query:String(e.document),variables:e.variables,requestHeaders:e.requestHeaders,signal:e.signal}),s=r;return s.withOptions=t,s}function A(){return async function(t,s){const e=await w();let n=s;if(e){const o=new Headers(s?.headers);e.forEach((c,i)=>{o.has(i)||o.set(i,c)}),n={...s,headers:o}}const a=await fetch(t,n);return(a.status===401||a.status===403||a.status>=500)&&p(a.status,{status:a.status,response:a.clone()}),a}}export{l as ClientError,u as authAwareEvents,A as createAuthAwareFetch,E as createAuthAwareGraphqlClient,y as setServerRequestHeadersProvider};