@doswiftly/storefront-sdk 22.4.0 → 22.5.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 22.5.1
+
+### Patch Changes
+
+- 6ca2a5f: Corrected the GraphQL schema descriptions for the `CartStatus` enum and the `Cart.status` field so they match the cart's actual behaviour: an `ABANDONED` cart is revived in place by any deliberate buyer edit (it is not locked), editing an `EXPIRED` cart returns `CART_NOT_FOUND`, and only `CONVERTED` / completed carts return `ALREADY_COMPLETED`. Documentation only — no type or API changes.
+
+## 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

package/README.md

@@ -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,CA0HvF"}
+{"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,17 +47,30 @@ 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 `TypedDocumentString.__meta__.hash`.
+     * 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) {
-        return typeof document === 'string' ? undefined : document.__meta__?.hash;
+        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().

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;AAIjB,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;AA4KD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,IAGnB,SAAS,cAAc,KAAG,OAAO,CAAC,eAAe,CAAC,CAwEjF"}
+{"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,8 +4,7 @@
  * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
  * Error normalization is handled by error middleware, NOT here.
  */
-import { CURRENCY_HEADER_NAME } from '../currency/cookie-config';
-import { LANGUAGE_HEADER_NAME } from '../language/cookie-config';
+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.
@@ -153,21 +152,6 @@ function extractUserErrors(data) {
     }
     return flat;
 }
-/** Backend signal that a `documentId` is not in the allowlist → replay as POST. */
-const TRUSTED_DOC_NOT_FOUND = 'TRUSTED_DOCUMENT_NOT_FOUND';
-/** Shop-routing header the client always sends; lifted into the GET cache key below. */
-const SHOP_SLUG_HEADER = 'X-Shop-Slug';
-/**
- * Variance axes mirrored from request headers into the GET query string. A shared
- * edge cache keys on the URL, not on request headers — without these in the URL two
- * shops / currencies / languages would collide on one cache entry. The backend still
- * reads the values from the headers; the URL copy exists only to split the cache key.
- */
-const AXIS_URL_PARAMS = [
-    [SHOP_SLUG_HEADER, '__shop'],
-    [CURRENCY_HEADER_NAME, '__currency'],
-    [LANGUAGE_HEADER_NAME, '__language'],
-];
 /**
  * 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).
@@ -215,16 +199,28 @@ function buildTrustedGetRequest(endpoint, request) {
     if (request.variables && Object.keys(request.variables).length > 0) {
         url.searchParams.set('variables', JSON.stringify(request.variables));
     }
-    for (const [headerName, param] of AXIS_URL_PARAMS) {
-        const value = request.headers[headerName];
+    // 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 → never carry the bearer token (`omit` also drops
-    // cookies), so the cached response can be served to any visitor.
+    // 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';
@@ -236,11 +232,16 @@ function buildTrustedGetRequest(endpoint, request) {
 export function createExecute(config) {
     const { endpoint, fetch: fetchFn, debug } = config;
     return async function execute(request) {
-        const { query, variables, headers, operationName, isMutation, cache, documentId } = request;
+        const { query, variables, headers, operationName, cache, documentId } = request;
         const startedAt = debug?.timing ? Date.now() : 0;
-        // Cacheable public reads with a resolvable persisted document go over GET so a
-        // shared edge cache can serve them; everything else stays POST.
-        const useTrustedGet = !isMutation && cache?.mode === 'public' && typeof documentId === 'string' && documentId.length > 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, method: useTrustedGet ? 'GET' : 'POST' };
             if (useTrustedGet)
@@ -253,16 +254,27 @@ export function createExecute(config) {
         }
         let response;
         if (useTrustedGet) {
-            const [getUrl, getInit] = buildTrustedGetRequest(endpoint, request);
-            response = await fetchFn(getUrl, getInit);
-            // Unknown documentId (custom selection or manifest skew) → replay as POST with
-            // the full query. The backend never executes a document it cannot resolve.
-            if (response.status === 400) {
-                const fallback = (await response.clone().json().catch(() => null));
-                if (fallback?.error === TRUSTED_DOC_NOT_FOUND) {
-                    const [postUrl, postInit] = buildPostRequest(endpoint, request);
-                    response = await fetchFn(postUrl, postInit);
-                }
+            // 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);
             }
         }
         else {

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;
@@ -211,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":"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"}

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

@@ -551,7 +551,7 @@ export type Cart = Node & {
     selectedShippingMethod?: Maybe<CartShippingMethod>;
     /** Shipping address attached to the cart via `cartSetShippingAddress`. Null until set. */
     shippingAddress?: Maybe<MailingAddress>;
-    /** Lifecycle status — `ACTIVE` for the editable working cart, terminal otherwise. Check this on SSR before rendering the checkout form: a non-`ACTIVE` cart should redirect (typically to the order confirmation when `completedOrder` is populated) instead of presenting a form whose first mutation fails with `CartErrorCode.ALREADY_COMPLETED`. */
+    /** Lifecycle status — `ACTIVE` / `RECOVERED` are editable; `ABANDONED` is a recovery flag a deliberate buyer action revives in place; `CONVERTED` / `EXPIRED` are terminal. Check this on SSR before rendering the checkout form: a `CONVERTED` cart should redirect (typically to the order confirmation when `completedOrder` is populated) instead of presenting a form whose first mutation fails with `CartErrorCode.ALREADY_COMPLETED`. */
     status: CartStatus;
     /** Sum of `quantity` across all lines — the badge number for the cart icon. */
     totalQuantity: Scalars['Int']['output'];