@doswiftly/storefront-sdk 22.3.0 → 22.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 22.5.0
+
+### Minor Changes
+
+- 3d5f1d3: Public reads now use the cacheable `GET` transport **by default** — you no longer opt in per query with `cacheLong()`. A non-mutation query that carries a persisted-document id and no signed-in identity is sent as a shared, credential-less `GET` so a CDN can cache it; a request carrying an `Authorization` bearer or a cart secret automatically stays on `POST` with credentials, so personalised reads are never shared. The server decides whether a result is actually cacheable via its `Cache-Control` response — the client only chooses the transport. Opt a specific persisted read out of the shared cache with `cachePrivate()` or `cacheNone()` (forces `POST`). Mutations and any request without a document id keep the existing `POST` behaviour, so current behaviour is unchanged until document ids are present.
+
+  ```ts
+  // Cacheable GET automatically (anonymous visitor) — no cacheLong() needed:
+  const products = await client.query(ProductsQuery, { first: 20 });
+
+  // Keep a persisted read per-user (forces POST):
+  const account = await client.query(MyAccountQuery, {}, cachePrivate());
+  ```
+
+- 7664b81: Added a ready GraphQL codegen recipe for edge-cacheable reads. Import `createCodegenConfig` from `@doswiftly/storefront-operations/codegen` and `export default` it from your `codegen.ts` — it points the client preset at the bundled schema and emits persisted documents whose `documentId` matches the Storefront API's `sha256:<hex>` contract, so public reads resolve server-side and can be cached at the edge.
+
+  You write operations with the generated `gql(...)` tag. They compile to lightweight typed strings (no `graphql` package at runtime) that the SDK's `query` / `mutate` accept directly, custom scalars are mapped to precision-safe TypeScript types (money and 64-bit integers as strings), and fragment fields are read directly with no unmasking helper. If your project already imports a `gql` from another GraphQL client, override the tag name: `createCodegenConfig({ gqlTagName: 'graphql' })`. Requires `@graphql-codegen/cli`, `@graphql-codegen/client-preset@^4` and `graphql@^16` as devDependencies (the preset doesn't support `graphql` v17 yet — fragment operations fail to generate). See the README "Edge-cacheable reads" section. `@doswiftly/storefront-sdk` accepts these generated documents directly in `query` / `mutate`, and its cacheable `GET` transport degrades to a `POST` on any non-success response.
+
+  Author operations with the generated tag — codegen emits each as a typed document carrying its `documentId`:
+
+  ```ts
+  import { gql } from "./gql";
+
+  export const ProductsQuery = gql(`
+    query Products($first: Int) {
+      products(first: $first) {
+        nodes { id handle title }
+      }
+    }
+  `);
+  ```
+
+## 22.4.0
+
+### Minor Changes
+
+- 848a3fe: Expose payment consents on `PaymentMethod`. The fragment now selects `acknowledgements` — consent statements a buyer can affirm before paying, each with linked documents — so storefronts can render the consent checkboxes and echo accepted codes back in `PaymentCreateInput.acknowledgements`.
+- ecf919f: `<PriceDisplay>` now accepts an optional `locale` prop, forwarded to both the current price and the strikethrough compare-at price. Pass it (e.g. `locale="pl-PL"`) for deterministic, environment-independent formatting — bringing `<PriceDisplay>` in line with the `locale` prop already on `<Money>`. When omitted, behaviour is unchanged (the runtime default locale is used).
+- be11ed6: Add a cacheable `GET` transport for public reads. When a document carries a persisted-document id (`TypedDocumentString.__meta__.hash`), a public cacheable query is sent as a `GET` with only the id — so a shared CDN can cache it — with the shop, currency and language in the URL and no credentials attached; an unrecognised id transparently replays as a `POST`. Mutations and any request without a document id keep the existing `POST` behaviour, so current behaviour is unchanged until document ids are present.
+
 ## 22.3.0
 
 ### Minor Changes

package/README.md

@@ -718,11 +718,11 @@ your CSS approach. Available from `@doswiftly/storefront-sdk/react`:
 
 | Component | Purpose |
 |-----------|---------|
-| `<Money amount currency>` | Locale-formatted price string from minor units |
+| `<Money amount currency locale?>` | Locale-formatted price string from minor units |
 | `<Image data sizes priority>` | `<img>` with thumbhash blur placeholder + sane defaults |
 | `<CartCount count label>` | Aria-live cart item count |
 | `<AddToCartButton variantId quantity>` | Button wired to `useCartManager().addItem` (loading state + a11y error surfacing) |
-| `<PriceDisplay price compareAtPrice currency>` | Price + optional strikethrough sale price |
+| `<PriceDisplay price compareAtPrice currency locale?>` | Price + optional strikethrough sale price |
 | `<CartTotals subtotal tax shipping discount total currency>` | Cart financial breakdown `<dl>` |
 | `<PaymentInstrumentTile instrument>` | One selectable payment instrument (card brand, wallet, bank) |
 | `<PaymentInstrumentSection method>` | Instrument group for a payment method (renders tiles) |
@@ -730,8 +730,8 @@ your CSS approach. Available from `@doswiftly/storefront-sdk/react`:
 ```tsx
 import { Money, PriceDisplay, CartCount } from '@doswiftly/storefront-sdk/react';
 
-<Money amount={9990} currency="PLN" />          {/* "99,90 zł" */}
-<PriceDisplay price={7990} compareAtPrice={9990} currency="PLN" />
+<Money amount={9990} currency="PLN" locale="pl-PL" />          {/* "99,90 zł" */}
+<PriceDisplay price={7990} compareAtPrice={9990} currency="PLN" locale="pl-PL" />
 <CartCount count={3} label="items" />
 ```
 
@@ -1122,6 +1122,28 @@ cacheCustom({ maxAge: 300, swr: 600 })   // 5min + 10min swr
 const data = await client.query(ProductQuery, { handle }, cacheLong());
 ```
 
+### Edge caching is the default for public reads
+
+When an operation is generated with a persisted-document id (the recipe in
+`@doswiftly/storefront-operations` does this), a non-mutation read with no
+signed-in identity is sent as a **cacheable `GET`** automatically — you do not
+need to pass `cacheLong()`. A shared CDN can then serve it, and the server
+decides whether the result is actually cacheable via its `Cache-Control`
+response. Requests carrying an identity (an `Authorization` bearer or a cart
+secret) stay on `POST` with credentials, so personalised reads are never shared.
+
+The cache strategies above are now **tuning / opt-out** rather than the on
+switch: pass `cachePrivate()` or `cacheNone()` to keep a persisted read per-user
+(forces `POST`), or `cacheLong({ tags })` to attach Next.js revalidation tags.
+
+```typescript
+// Cacheable GET automatically — no strategy argument needed:
+const products = await client.query(ProductsQuery, { first: 20 });
+
+// Keep a persisted read per-user (forces POST):
+const account = await client.query(MyAccountQuery, {}, cachePrivate());
+```
+
 ## GraphQL schema for codegen
 
 The GraphQL SDL ships in the linked `@doswiftly/storefront-operations` package

package/dist/core/client/cache-eligibility.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cacheable-public-read eligibility — the platform-default rule deciding whether
+ * a query may travel over the shared, credential-less cacheable GET transport
+ * instead of POST. No per-query `cacheLong()` opt-in is required: a non-mutation
+ * persisted read with no identity is eligible by default.
+ *
+ * Mirror of the backend storefront-cache header SSOT
+ * (`commerce/storefront-graphql/cache/cache-headers.ts`). The published SDK
+ * cannot import the private backend, so the contract is duplicated here
+ * intentionally — the same rationale as `LANGUAGE_HEADER_NAME`. A drift test
+ * (`cache-eligibility.drift.test.ts`, run against the backend source) keeps the
+ * two in sync:
+ *  - {@link IDENTITY_HEADERS} must be a **superset** of the backend's (missing one
+ *    → the SDK sends a credential-less GET that strips the identity → wrong data).
+ *  - {@link VARIANCE_AXIS_HEADERS} must **equal** the backend's (a missing axis
+ *    collapses two shops / currencies / languages onto one shared edge entry →
+ *    cross-tenant / wrong-variant leak; an extra axis fragments the cache).
+ *
+ * The SDK does NOT classify operations as cacheable (PUBLIC_READ vs USER_SCOPED) —
+ * that stays the backend's sole authority. It resolves the documentId, classifies
+ * the operation fail-closed and emits `Cache-Control: public|private`; the SDK
+ * only chooses the *transport*. Do NOT add a PUBLIC_READ allow-list here — it
+ * would duplicate the backend registry and drift.
+ *
+ * Identity manifests as a header by the time a request reaches the transport:
+ * `authMiddleware` adds `Authorization` whenever a customer is signed in (the
+ * token lives in memory, seeded server-side or rehydrated client-side), and
+ * `cartSecretMiddleware` adds `x-cart-secret`. The backend's additional
+ * cookie / `@inContext` identity checks are upstream signals the SDK has already
+ * converted to one of these headers — so the header gate is sufficient.
+ */
+import type { GraphQLRequest } from './types';
+/** Shop-routing header the client always sends; also a cache variance axis. */
+export declare const SHOP_SLUG_HEADER = "X-Shop-Slug";
+/**
+ * Header-level identity signals. Their presence keeps a request on POST (with
+ * credentials) instead of the shared cacheable GET. Mirror of backend
+ * `IDENTITY_HEADERS`; compared case-insensitively.
+ */
+export declare const IDENTITY_HEADERS: readonly ["authorization", "x-cart-secret"];
+/**
+ * Cache variance axes as `[requestHeaderName, getUrlParam]`. The backend keys its
+ * L1 cache on the resolved `{tenant, currency, language}`; the SDK copies the same
+ * axes into the GET URL so a shared edge cache keys correctly (it keys on the URL,
+ * not on request headers). Consumed by `buildTrustedGetRequest`.
+ */
+export declare const VARIANCE_AXIS_PARAMS: readonly [readonly ["X-Shop-Slug", "__shop"], readonly ["X-Preferred-Currency", "__currency"], readonly ["X-Language", "__language"]];
+/**
+ * Lowercase variance header names — the contract compared against the backend
+ * `VARIANCE_HEADERS` SSOT by the drift test. Derived from {@link VARIANCE_AXIS_PARAMS}
+ * so there is one list in the SDK.
+ */
+export declare const VARIANCE_AXIS_HEADERS: readonly string[];
+/**
+ * Whether a request may use the cacheable GET transport (transport safety only —
+ * the backend decides actual cacheability via `Cache-Control`). Eligible when it
+ * is a non-mutation persisted read carrying no identity. The explicit cache
+ * opt-outs (`cachePrivate()` / `cacheNone()`) are applied by the caller.
+ */
+export declare function isPublicReadEligible(request: GraphQLRequest): boolean;
+//# sourceMappingURL=cache-eligibility.d.ts.map

package/dist/core/client/cache-eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-eligibility.d.ts","sourceRoot":"","sources":["../../../src/core/client/cache-eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI9C,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6CAA8C,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,uIAIvB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAElD,CAAC;AAYF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAIrE"}

package/dist/core/client/cache-eligibility.js

@@ -0,0 +1,80 @@
+/**
+ * Cacheable-public-read eligibility — the platform-default rule deciding whether
+ * a query may travel over the shared, credential-less cacheable GET transport
+ * instead of POST. No per-query `cacheLong()` opt-in is required: a non-mutation
+ * persisted read with no identity is eligible by default.
+ *
+ * Mirror of the backend storefront-cache header SSOT
+ * (`commerce/storefront-graphql/cache/cache-headers.ts`). The published SDK
+ * cannot import the private backend, so the contract is duplicated here
+ * intentionally — the same rationale as `LANGUAGE_HEADER_NAME`. A drift test
+ * (`cache-eligibility.drift.test.ts`, run against the backend source) keeps the
+ * two in sync:
+ *  - {@link IDENTITY_HEADERS} must be a **superset** of the backend's (missing one
+ *    → the SDK sends a credential-less GET that strips the identity → wrong data).
+ *  - {@link VARIANCE_AXIS_HEADERS} must **equal** the backend's (a missing axis
+ *    collapses two shops / currencies / languages onto one shared edge entry →
+ *    cross-tenant / wrong-variant leak; an extra axis fragments the cache).
+ *
+ * The SDK does NOT classify operations as cacheable (PUBLIC_READ vs USER_SCOPED) —
+ * that stays the backend's sole authority. It resolves the documentId, classifies
+ * the operation fail-closed and emits `Cache-Control: public|private`; the SDK
+ * only chooses the *transport*. Do NOT add a PUBLIC_READ allow-list here — it
+ * would duplicate the backend registry and drift.
+ *
+ * Identity manifests as a header by the time a request reaches the transport:
+ * `authMiddleware` adds `Authorization` whenever a customer is signed in (the
+ * token lives in memory, seeded server-side or rehydrated client-side), and
+ * `cartSecretMiddleware` adds `x-cart-secret`. The backend's additional
+ * cookie / `@inContext` identity checks are upstream signals the SDK has already
+ * converted to one of these headers — so the header gate is sufficient.
+ */
+import { CURRENCY_HEADER_NAME } from '../currency/cookie-config';
+import { LANGUAGE_HEADER_NAME } from '../language/cookie-config';
+/** Shop-routing header the client always sends; also a cache variance axis. */
+export const SHOP_SLUG_HEADER = 'X-Shop-Slug';
+/**
+ * Header-level identity signals. Their presence keeps a request on POST (with
+ * credentials) instead of the shared cacheable GET. Mirror of backend
+ * `IDENTITY_HEADERS`; compared case-insensitively.
+ */
+export const IDENTITY_HEADERS = ['authorization', 'x-cart-secret'];
+/**
+ * Cache variance axes as `[requestHeaderName, getUrlParam]`. The backend keys its
+ * L1 cache on the resolved `{tenant, currency, language}`; the SDK copies the same
+ * axes into the GET URL so a shared edge cache keys correctly (it keys on the URL,
+ * not on request headers). Consumed by `buildTrustedGetRequest`.
+ */
+export const VARIANCE_AXIS_PARAMS = [
+    [SHOP_SLUG_HEADER, '__shop'],
+    [CURRENCY_HEADER_NAME, '__currency'],
+    [LANGUAGE_HEADER_NAME, '__language'],
+];
+/**
+ * Lowercase variance header names — the contract compared against the backend
+ * `VARIANCE_HEADERS` SSOT by the drift test. Derived from {@link VARIANCE_AXIS_PARAMS}
+ * so there is one list in the SDK.
+ */
+export const VARIANCE_AXIS_HEADERS = VARIANCE_AXIS_PARAMS.map(([header]) => header.toLowerCase());
+const IDENTITY_HEADER_SET = new Set(IDENTITY_HEADERS);
+/** True when any identity header is present (case-insensitive). */
+function hasIdentityHeader(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (value && IDENTITY_HEADER_SET.has(name.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether a request may use the cacheable GET transport (transport safety only —
+ * the backend decides actual cacheability via `Cache-Control`). Eligible when it
+ * is a non-mutation persisted read carrying no identity. The explicit cache
+ * opt-outs (`cachePrivate()` / `cacheNone()`) are applied by the caller.
+ */
+export function isPublicReadEligible(request) {
+    if (request.isMutation)
+        return false;
+    if (typeof request.documentId !== 'string' || request.documentId.length === 0)
+        return false;
+    return !hasIdentityHeader(request.headers);
+}

package/dist/core/client/create-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-client.d.ts","sourceRoot":"","sources":["../../../src/core/client/create-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,gBAAgB,EAKjB,MAAM,SAAS,CAAC;AAQjB,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAgHvF"}
+{"version":3,"file":"create-client.d.ts","sourceRoot":"","sources":["../../../src/core/client/create-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,gBAAgB,EAKjB,MAAM,SAAS,CAAC;AAQjB,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAmIvF"}

package/dist/core/client/create-client.js

@@ -47,16 +47,37 @@ export function createStorefrontClient(config) {
         return compiledPipeline;
     }
     /**
-     * Resolve query string from TypedDocumentString or plain string.
+     * Resolve query string from a typed document or plain string.
      */
     function resolveQuery(document) {
         return typeof document === 'string' ? document : document.toString();
     }
+    /**
+     * Persisted-document id carried by codegen on `__meta__.hash`.
+     * Plain strings (and documents without a populated hash) have none → POST transport.
+     *
+     * `__meta__` is optional codegen metadata, not part of the public document
+     * contract (`TypedDocumentLike`), so it is read defensively via narrowing — no
+     * cast, no assumption that any given document carries it.
+     */
+    function resolveDocumentId(document) {
+        if (typeof document === 'string')
+            return undefined;
+        if (!('__meta__' in document))
+            return undefined;
+        const meta = document.__meta__;
+        if (typeof meta !== 'object' || meta === null)
+            return undefined;
+        if (!('hash' in meta) || typeof meta.hash !== 'string')
+            return undefined;
+        return meta.hash;
+    }
     /**
      * Core request execution — shared by query() and mutate().
      */
     async function request(document, variables, isMutation = false, cache) {
         const query = resolveQuery(document);
+        const documentId = resolveDocumentId(document);
         const operationName = getOperationName(query);
         const pipeline = getPipeline();
         const headers = {
@@ -73,6 +94,7 @@ export function createStorefrontClient(config) {
             headers,
             isMutation,
             cache,
+            documentId,
         };
         // Dedupe queries (not mutations) in the same tick
         const executeFn = () => pipeline(graphqlRequest);

package/dist/core/client/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/core/client/execute.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EAEZ,cAAc,EACd,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B;;;;OAIG;IACH,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAClC;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GACpD,oBAAoB,GAAG,IAAI,CAiB7B;AAwFD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,IAGnB,SAAS,cAAc,KAAG,OAAO,CAAC,eAAe,CAAC,CAyEjF"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/core/client/execute.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EAEZ,cAAc,EACd,eAAe,EAChB,MAAM,SAAS,CAAC;AAGjB,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B;;;;OAIG;IACH,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAClC;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GACpD,oBAAoB,GAAG,IAAI,CAiB7B;AAqKD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,IAGnB,SAAS,cAAc,KAAG,OAAO,CAAC,eAAe,CAAC,CAqFjF"}

package/dist/core/client/execute.js

@@ -4,6 +4,7 @@
  * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
  * Error normalization is handled by error middleware, NOT here.
  */
+import { isPublicReadEligible, VARIANCE_AXIS_PARAMS } from './cache-eligibility';
 const DEFAULT_LOG = (event) => {
     // Header on a separate line so the data dump below renders untruncated in
     // both terminals and DevTools.
@@ -151,45 +152,135 @@ function extractUserErrors(data) {
     }
     return flat;
 }
+/**
+ * Default POST transport — the full query travels in the body and cookies are sent.
+ * Every request that is not a cacheable public read uses this (unchanged contract).
+ */
+function buildPostRequest(endpoint, request) {
+    const body = { query: request.query };
+    if (request.variables && Object.keys(request.variables).length > 0) {
+        body.variables = request.variables;
+    }
+    if (request.operationName) {
+        body.operationName = request.operationName;
+    }
+    return [
+        endpoint,
+        {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...request.headers,
+            },
+            body: JSON.stringify(body),
+            signal: request.signal,
+            // Include httpOnly cookies (e.g. customerAccessToken auth) on cross-origin
+            // requests. Required when the storefront runs on a domain different from the
+            // backend GraphQL endpoint — same-origin browsers send cookies regardless,
+            // but cross-origin needs `credentials: 'include'` paired with the backend's
+            // `Access-Control-Allow-Credentials: true` (already configured).
+            credentials: 'include',
+        },
+    ];
+}
+/**
+ * Cacheable GET transport for public reads with a known `documentId`. Only the id
+ * travels (the backend resolves it to the full query from its allowlist), the variance
+ * axes ride in the URL so a shared edge cache keys correctly, and no credentials are
+ * sent so the response stays shareable across visitors.
+ */
+function buildTrustedGetRequest(endpoint, request) {
+    const url = new URL(endpoint);
+    url.searchParams.set('documentId', request.documentId);
+    if (request.operationName && request.operationName !== 'anonymous') {
+        url.searchParams.set('operationName', request.operationName);
+    }
+    if (request.variables && Object.keys(request.variables).length > 0) {
+        url.searchParams.set('variables', JSON.stringify(request.variables));
+    }
+    // Case-insensitive lookup for the variance axes: request header casing is not guaranteed
+    // (middleware/proxies may normalise), and the identity gate is already case-insensitive.
+    // A casing mismatch here would drop an axis from the URL — and the shared edge keys on the
+    // URL only, so two shops/currencies/languages would collapse onto one entry (cross-tenant /
+    // wrong-variant leak). Build one lowercased view, then look up each axis by lowercase name.
+    const lowerHeaders = {};
+    for (const [name, value] of Object.entries(request.headers))
+        lowerHeaders[name.toLowerCase()] = value;
+    for (const [headerName, param] of VARIANCE_AXIS_PARAMS) {
+        const value = lowerHeaders[headerName.toLowerCase()];
+        if (value)
+            url.searchParams.set(param, value);
+    }
+    const headers = { ...request.headers };
+    // Public read = customer-agnostic → the GET must carry NO credentials, so the cached
+    // response can be served to any visitor. `credentials: 'omit'` drops the browser cookie jar,
+    // but NOT an explicitly-set Cookie header (e.g. forwarded on SSR) — strip it (and the bearer
+    // token) by hand so the request is truly credential-less and can never personalise the body.
+    delete headers.Authorization;
+    delete headers.authorization;
+    delete headers.Cookie;
+    delete headers.cookie;
+    headers.Accept = 'application/json';
+    // Force a CORS preflight so the backend CSRF prevention admits the GET.
+    headers['apollo-require-preflight'] = 'true';
+    return [url.toString(), { method: 'GET', headers, signal: request.signal, credentials: 'omit' }];
+}
 /**
  * Create the innermost execute function for the middleware pipeline.
  */
 export function createExecute(config) {
     const { endpoint, fetch: fetchFn, debug } = config;
     return async function execute(request) {
-        const { query, variables, headers, signal, operationName } = request;
+        const { query, variables, headers, operationName, cache, documentId } = request;
         const startedAt = debug?.timing ? Date.now() : 0;
+        // Platform default: a non-mutation persisted read with no identity goes over the
+        // shared cacheable GET so an edge cache can serve it — no per-query `cacheLong()`
+        // opt-in needed. The caller can still opt OUT with `cachePrivate()` / `cacheNone()`
+        // for a persisted read it wants kept per-user. Whether the result is ACTUALLY
+        // cached is the backend's call (it classifies the operation and emits
+        // `Cache-Control`); the SDK never classifies operations here — adding a PUBLIC_READ
+        // list would duplicate the backend registry and drift.
+        const useTrustedGet = isPublicReadEligible(request) && cache?.mode !== 'private' && cache?.mode !== 'no-store';
         if (debug) {
-            const requestData = { variables };
+            const requestData = { variables, method: useTrustedGet ? 'GET' : 'POST' };
+            if (useTrustedGet)
+                requestData.documentId = documentId;
             if (debug.request)
                 requestData.query = query;
             if (debug.headers)
                 requestData.headers = redactRequestHeaders(headers);
             debug.log({ phase: 'request', operationName, data: requestData });
         }
-        const body = { query };
-        if (variables && Object.keys(variables).length > 0) {
-            body.variables = variables;
+        let response;
+        if (useTrustedGet) {
+            // The cacheable GET is only an optimization for a shared edge cache — it must NEVER
+            // break a read. Use it only on a clean 2xx; degrade to a full-query POST on ANY other
+            // outcome: the GET transport throwing (network / CORS / aborted), an opaque or blocked
+            // response (`status` 0, `ok` false), an unknown documentId surfaced as 400, a 5xx, etc.
+            // The full query travels in the POST body, so the backend always resolves it.
+            let getResponse = null;
+            try {
+                const [getUrl, getInit] = buildTrustedGetRequest(endpoint, request);
+                const candidate = await fetchFn(getUrl, getInit);
+                if (candidate.ok)
+                    getResponse = candidate;
+            }
+            catch {
+                // network / CORS / aborted GET — fall through to the safe POST below
+            }
+            if (getResponse) {
+                response = getResponse;
+            }
+            else {
+                const [postUrl, postInit] = buildPostRequest(endpoint, request);
+                response = await fetchFn(postUrl, postInit);
+            }
         }
-        if (operationName) {
-            body.operationName = operationName;
+        else {
+            const [postUrl, postInit] = buildPostRequest(endpoint, request);
+            response = await fetchFn(postUrl, postInit);
         }
-        const response = await fetchFn(endpoint, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
-                ...headers,
-            },
-            body: JSON.stringify(body),
-            signal,
-            // Include httpOnly cookies (e.g. customerAccessToken auth) on cross-origin
-            // requests. Required when the storefront runs on a domain different from the
-            // backend GraphQL endpoint — same-origin browsers send cookies regardless,
-            // but cross-origin needs `credentials: 'include'` paired with the backend's
-            // `Access-Control-Allow-Credentials: true` (already configured).
-            credentials: 'include',
-        });
         const json = await response.json();
         if (debug) {
             const responseData = {

package/dist/core/client/types.d.ts

@@ -3,13 +3,39 @@
  *
  * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
  */
+/**
+ * Structural contract for a typed GraphQL document accepted by `query` / `mutate`.
+ *
+ * A document carries its result type (`TResult`) and variables type (`TVariables`)
+ * at the type level via the phantom `__apiType` brand (never called at runtime) and
+ * stringifies to the GraphQL operation text. This is the parameter type the client
+ * exposes — deliberately a *structural interface*, not a concrete class, so it is
+ * satisfied by:
+ *  - the SDK's own {@link TypedDocumentString} class, and
+ *  - the class graphql-codegen's client-preset emits in a consumer project
+ *    (which declares a `private` field and would otherwise be nominally
+ *    incompatible with a class-typed parameter — private members only block
+ *    class-to-class assignment, never class-to-interface).
+ *
+ * Inference is preserved either way: `client.query(doc, vars)` infers both the
+ * result and the variables shape from the document.
+ */
+export interface TypedDocumentLike<TResult = unknown, TVariables = unknown> {
+    /** Type-level brand carrying result & variable types — never called at runtime. */
+    __apiType?: (variables: TVariables) => TResult;
+    /** Stringifies to the GraphQL operation text. */
+    toString(): string;
+}
 /**
  * A branded string carrying result & variable types.
  * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
  *
  * SDK also accepts plain strings — TypedDocumentString is purely for DX.
+ *
+ * Structurally satisfies {@link TypedDocumentLike}, the type accepted by
+ * `query` / `mutate`.
  */
-export declare class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String {
+export declare class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String implements TypedDocumentLike<TResult, TVariables> {
     __meta__?: {
         hash: string;
     } | undefined;
@@ -35,6 +61,12 @@ export interface GraphQLRequest {
     isMutation: boolean;
     /** Cache strategy override */
     cache?: CacheStrategy;
+    /**
+     * Persisted-document id (`sha256:<hex>`), carried by `TypedDocumentString.__meta__.hash`.
+     * When present on a cacheable public read, the transport sends only this id over GET
+     * (instead of the full query) so a shared edge cache can serve the response. Absent → POST.
+     */
+    documentId?: string;
 }
 export interface GraphQLResponse<T = unknown> {
     /** Parsed response data */
@@ -205,15 +237,16 @@ export interface StorefrontClient {
     /**
      * Execute a typed GraphQL query.
      *
-     * Accepts TypedDocumentString (from codegen) or plain string.
+     * Accepts any typed document (the SDK's `TypedDocumentString` or a
+     * graphql-codegen client-preset document) or a plain string.
      */
-    query<T = unknown, V = Record<string, unknown>>(document: TypedDocumentString<T, V> | string, variables?: V, cache?: CacheStrategy): Promise<T>;
+    query<T = unknown, V = Record<string, unknown>>(document: TypedDocumentLike<T, V> | string, variables?: V, cache?: CacheStrategy): Promise<T>;
     /**
      * Execute a typed GraphQL mutation.
      *
      * Mutations are never cached and never retried by retry middleware.
      */
-    mutate<T = unknown, V = Record<string, unknown>>(document: TypedDocumentString<T, V> | string, variables?: V): Promise<T>;
+    mutate<T = unknown, V = Record<string, unknown>>(document: TypedDocumentLike<T, V> | string, variables?: V): Promise<T>;
     /**
      * Add middleware to the pipeline (imperative API).
      *

package/dist/core/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/client/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/client/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACxE,mFAAmF;IACnF,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC;IAC/C,iDAAiD;IACjD,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAmB,CAAC,OAAO,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACtE,SAAQ,MACR,YAAW,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC;IAKf,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE;IAH7D,+CAA+C;IAC/C,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC;gBAEnC,KAAK,EAAE,MAAM,EAAS,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,YAAA;IAIpD,QAAQ,IAAI,MAAM;CAG5B;AAMD,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wDAAwD;IACxD,UAAU,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2BAA2B;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,8BAA8B;IAC9B,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAMD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAMhG,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB;IACjB,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACxC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAMzC;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,2GAA2G;IAC3G,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wGAAwG;IACxG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gKAAgK;IAChK,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sIAAsI;IACtI,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2JAA2J;IAC3J,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,kBAAkB,GAAG,eAAe,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,0BAA0B;IAC1B,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,CAAC;CAC5C;AAMD,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,QAAQ,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,EAC1C,SAAS,CAAC,EAAE,CAAC,EACb,KAAK,CAAC,EAAE,aAAa,GACpB,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7C,QAAQ,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,EAC1C,SAAS,CAAC,EAAE,CAAC,GACZ,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;;;OAIG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC"}

package/dist/core/client/types.js

@@ -3,14 +3,14 @@
  *
  * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
  */
-// ---------------------------------------------------------------------------
-// TypedDocumentString (graphql-codegen client-preset pattern)
-// ---------------------------------------------------------------------------
 /**
  * A branded string carrying result & variable types.
  * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
  *
  * SDK also accepts plain strings — TypedDocumentString is purely for DX.
+ *
+ * Structurally satisfies {@link TypedDocumentLike}, the type accepted by
+ * `query` / `mutate`.
  */
 export class TypedDocumentString extends String {
     __meta__;

package/dist/core/generated/operation-types.d.ts

@@ -3940,12 +3940,18 @@ export type AvailablePaymentMethodsQuery = {
             instruments?: Maybe<Array<(Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
                 brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
             })>>;
+            acknowledgements: Array<(Pick<PaymentAcknowledgement, 'code' | 'enforcement' | 'statement'> & {
+                documents: Array<Pick<PaymentAcknowledgementDocument, 'token' | 'kind' | 'url'>>;
+            })>;
         })>;
         defaultMethod?: Maybe<(Pick<PaymentMethod, 'id' | 'name' | 'provider' | 'type' | 'description' | 'isDefault' | 'supportedCurrencies' | 'position' | 'providersAvailable' | 'preferredProvider' | 'available' | 'unavailableReason'> & {
             icon?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
             instruments?: Maybe<Array<(Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
                 brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
             })>>;
+            acknowledgements: Array<(Pick<PaymentAcknowledgement, 'code' | 'enforcement' | 'statement'> & {
+                documents: Array<Pick<PaymentAcknowledgementDocument, 'token' | 'kind' | 'url'>>;
+            })>;
         })>;
     };
 };
@@ -5393,12 +5399,18 @@ export type AvailablePaymentMethodsFragment = {
         instruments?: Maybe<Array<(Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
             brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
         })>>;
+        acknowledgements: Array<(Pick<PaymentAcknowledgement, 'code' | 'enforcement' | 'statement'> & {
+            documents: Array<Pick<PaymentAcknowledgementDocument, 'token' | 'kind' | 'url'>>;
+        })>;
     })>;
     defaultMethod?: Maybe<(Pick<PaymentMethod, 'id' | 'name' | 'provider' | 'type' | 'description' | 'isDefault' | 'supportedCurrencies' | 'position' | 'providersAvailable' | 'preferredProvider' | 'available' | 'unavailableReason'> & {
         icon?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
         instruments?: Maybe<Array<(Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
             brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
         })>>;
+        acknowledgements: Array<(Pick<PaymentAcknowledgement, 'code' | 'enforcement' | 'statement'> & {
+            documents: Array<Pick<PaymentAcknowledgementDocument, 'token' | 'kind' | 'url'>>;
+        })>;
     })>;
 };
 export type PaymentMethodFragment = (Pick<PaymentMethod, 'id' | 'name' | 'provider' | 'type' | 'description' | 'isDefault' | 'supportedCurrencies' | 'position' | 'providersAvailable' | 'preferredProvider' | 'available' | 'unavailableReason'> & {
@@ -5406,6 +5418,9 @@ export type PaymentMethodFragment = (Pick<PaymentMethod, 'id' | 'name' | 'provid
     instruments?: Maybe<Array<(Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
         brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;
     })>>;
+    acknowledgements: Array<(Pick<PaymentAcknowledgement, 'code' | 'enforcement' | 'statement'> & {
+        documents: Array<Pick<PaymentAcknowledgementDocument, 'token' | 'kind' | 'url'>>;
+    })>;
 });
 export type PaymentInstrumentFragment = (Pick<PaymentInstrument, 'provider' | 'code' | 'type' | 'displayName' | 'displayHint' | 'enabled'> & {
     brandImage?: Maybe<Pick<Image, 'id' | 'url' | 'altText' | 'width' | 'height' | 'thumbhash'>>;