@doswiftly/storefront-operations 22.4.0 → 22.5.1

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 22.4.0
+- **Schema version**: 22.5.1
 - **Queries**: 52
 - **Mutations**: 44
 - **Fragments**: 105
@@ -203,4 +203,4 @@ directly, and CORS errors only surface on the first client-side mutation.
 - **Operation question** ("which mutation does Y?") → grep `llms-full.txt` for the verb in `**Description**:` lines
 - **Programmatic enumeration** → load `operations.json`
 
-For codegen setup and runtime transport, see `README.md` and [`@doswiftly/storefront-sdk`](https://www.npmjs.com/package/@doswiftly/storefront-sdk).
+For codegen setup and runtime transport, see `README.md` and [`@doswiftly/storefront-sdk`](https://www.npmjs.com/package/@doswiftly/storefront-sdk). To make public reads edge-cacheable, use the ready persisted-documents recipe `@doswiftly/storefront-operations/codegen` (`createCodegenConfig`) — it emits `documentId`s in the API's `sha256:<hex>` format. See README → "Edge-cacheable reads".

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

@@ -116,6 +116,45 @@ export default config;
 The schema lives offline as a file in the package — no running backend needed
 for codegen.
 
+### Edge-cacheable reads: persisted documents (recommended)
+
+To make your public reads cacheable at the edge, the API accepts a short
+`documentId` (`sha256:<hex>`) instead of the full query. This package ships a
+codegen recipe that wires it up — it points the client preset at the schema and
+sets the `documentId` hash to the exact format the API validates:
+
+```typescript
+// codegen.ts
+import { createCodegenConfig } from '@doswiftly/storefront-operations/codegen';
+
+export default createCodegenConfig({ documents: 'src/**/*.{ts,tsx}' });
+```
+
+Add `@graphql-codegen/cli`, `@graphql-codegen/client-preset@^4` and `graphql@^16` to
+your devDependencies. (The preset doesn't support `graphql` v17 yet — fragment
+operations fail to generate with it; pin `graphql@^16`.) Codegen then emits a `persisted-documents.json`
+(`documentId → query`) you publish at deploy time, plus typed documents whose
+`documentId` the SDK sends automatically for public reads.
+
+Write operations with the generated `gql(...)` tag. If your project already imports a
+`gql` from another GraphQL client (Apollo, urql, graphql-request), pass a different name
+to avoid a clash: `createCodegenConfig({ documents, gqlTagName: 'graphql' })`.
+
+You can assert your manifest matches the API contract (`documentId` is the SHA-256
+of the query body):
+
+```js
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+const manifest = JSON.parse(readFileSync('src/gql/persisted-documents.json', 'utf8'));
+for (const [id, body] of Object.entries(manifest)) {
+  if (id !== 'sha256:' + createHash('sha256').update(body, 'utf8').digest('hex')) {
+    throw new Error('documentId mismatch: ' + id);
+  }
+}
+```
+
 ### Advanced: codegen the entire catalog (not recommended for custom storefronts)
 
 You *can* hook the package's operation files directly into your codegen as

package/codegen.js

@@ -0,0 +1,113 @@
+/**
+ * Build-time codegen recipe for the DoSwiftly Storefront GraphQL API.
+ *
+ * This is a devDependency helper — NOT runtime code. It returns a `graphql-codegen`
+ * configuration wired to this package's schema and to the persisted-document
+ * contract the Storefront API expects: every operation is identified by
+ * `sha256:<hex of the printed document>` and sent as a short `documentId`, so
+ * public reads can be cached at the edge.
+ *
+ * Requires these devDependencies in your project:
+ *   @graphql-codegen/cli  +  @graphql-codegen/client-preset  +  graphql
+ *
+ * @example
+ *   // codegen.ts
+ *   import { createCodegenConfig } from '@doswiftly/storefront-operations/codegen';
+ *   export default createCodegenConfig({ documents: 'src/**\/*.{ts,tsx}' });
+ */
+
+const path = require('path');
+const crypto = require('crypto');
+
+/** Path to the schema shipped in this package — always matches the installed version. */
+const SCHEMA_PATH = path.join(__dirname, 'schema.graphql');
+
+/**
+ * Compute a persisted-document id for a printed GraphQL document, in the exact
+ * format the Storefront API stores and validates: `sha256:` followed by the
+ * lowercase hex SHA-256 of the document body. Exposed so you can assert your
+ * generated manifest matches (see the README "Verify" snippet).
+ *
+ * @param {string} documentBody - the printed GraphQL document (operation + its fragments).
+ * @returns {string} `sha256:<64 hex chars>`
+ */
+function trustedDocumentHash(documentBody) {
+  return 'sha256:' + crypto.createHash('sha256').update(documentBody, 'utf8').digest('hex');
+}
+
+/**
+ * Build a `graphql-codegen` config (client preset + persisted documents) pointed
+ * at this package's schema, producing `documentId`s in the Storefront API's
+ * trusted-document format. `export default` the result from your codegen file.
+ *
+ * Write operations with the generated `gql(...)` tag. Operations compile to
+ * lightweight typed strings (no `graphql` runtime dependency), custom scalars
+ * are mapped to precision-safe TypeScript types, and fragment fields are read
+ * directly (no unmasking helper) for a simpler developer experience.
+ *
+ * @param {object} options
+ * @param {string | string[]} options.documents - glob(s) for your GraphQL operations.
+ * @param {string} [options.outDir='./src/gql/'] - output directory for generated code.
+ * @param {string} [options.gqlTagName='gql'] - name of the generated operation tag.
+ *   Override (e.g. `'graphql'`) if your project already imports a `gql` from
+ *   another GraphQL client (Apollo, urql, graphql-request) to avoid a clash.
+ * @returns {object} a graphql-codegen configuration object.
+ */
+function createCodegenConfig(options) {
+  const documents = options && options.documents;
+  if (!documents) {
+    throw new Error(
+      'createCodegenConfig: `documents` is required — pass glob(s) pointing at your GraphQL operations.',
+    );
+  }
+  const outDir = (options && options.outDir) || './src/gql/';
+  const gqlTagName = (options && options.gqlTagName) || 'gql';
+  return {
+    schema: SCHEMA_PATH,
+    documents,
+    ignoreNoDocuments: true,
+    generates: {
+      [outDir]: {
+        preset: 'client',
+        config: {
+          // Emit each operation as a lightweight typed string (a `String`
+          // subclass carrying its result/variable types and persisted-document
+          // id), not a parsed AST object. This keeps the `graphql` package out
+          // of your runtime bundle and is the shape the Storefront client's
+          // `query` / `mutate` accept directly (it reads the query body and the
+          // document id off the string — no AST printing at runtime).
+          documentMode: 'string',
+          // Map the API's custom scalars to the TypeScript types your generated
+          // operations use. Money (`Decimal`) and 64-bit integers
+          // (`UnsignedInt64`) are serialized as strings to avoid precision loss;
+          // dates and URLs are encoded strings; `JSON` is an open object.
+          scalars: {
+            DateTime: 'string',
+            URL: 'string',
+            Decimal: 'string',
+            UnsignedInt64: 'string',
+            JSON: 'Record<string, unknown>',
+          },
+        },
+        presetConfig: {
+          // Name the generated document tag `gql(...)` instead of the default
+          // `graphql(...)` — shorter, and the conventional name in examples.
+          // Overridable via `options.gqlTagName` when a project already imports a
+          // `gql` from another GraphQL client.
+          gqlTagName,
+          // Read fragment fields directly, without an unmasking helper, so a
+          // component can use the data it selected as plain typed objects.
+          fragmentMasking: false,
+          persistedDocuments: {
+            // Custom hash → `documentId` matches the Storefront API's trusted-document
+            // format exactly (`sha256:<hex>`), so the published manifest is accepted
+            // verbatim and the runtime `documentId` resolves server-side.
+            hashAlgorithm: trustedDocumentHash,
+          },
+        },
+      },
+    },
+  };
+}
+
+module.exports = { createCodegenConfig, trustedDocumentHash, SCHEMA_PATH };

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **22.4.0**
+> Schema version: **22.5.1**
 > 52 queries · 44 mutations · 105 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "22.4.0",
+  "schemaVersion": "22.5.1",
   "queries": [
     {
       "name": "Shop",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "22.4.0",
+  "version": "22.5.1",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {
@@ -13,6 +13,7 @@
     "./mutations.graphql": "./mutations.graphql",
     "./fragments.graphql": "./fragments.graphql",
     "./operations.json": "./operations.json",
+    "./codegen": "./codegen.js",
     "./*.graphql": "./*.graphql"
   },
   "devDependencies": {
@@ -33,6 +34,7 @@
     "mutations.graphql",
     "fragments.graphql",
     "operations.json",
+    "codegen.js",
     "README.md",
     "AGENTS.md",
     "llms-full.txt",

package/schema.graphql

@@ -1013,7 +1013,7 @@ type Cart implements Node {
   shippingAddress: 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!
 
@@ -1831,7 +1831,7 @@ type CartShippingMethod {
 }
 
 """
-Cart lifecycle status. `ACTIVE` is the only editable state — every other value is terminal and rejects mutations with `CartErrorCode.ALREADY_COMPLETED`. `CONVERTED` carries an associated `completedOrder`; query that to redirect the buyer to their order confirmation. `EXPIRED` / `ABANDONED` are cleanup states with no order; create a fresh cart. `RECOVERED` is a previously-abandoned cart that the buyer returned to via a recovery link.
+Cart lifecycle status. `ACTIVE` and `RECOVERED` are editable carts. `ABANDONED` flags a cart the buyer left inactive (used for recovery campaigns) — it is not locked: a deliberate buyer action revives it in place to `RECOVERED` and the mutation proceeds. `RECOVERED` is a previously-abandoned cart the buyer came back to (via a recovery link or by acting on it again). `CONVERTED` carries an associated `completedOrder`; query that to redirect the buyer to their order confirmation, since editing a converted cart returns `CartErrorCode.ALREADY_COMPLETED`. `EXPIRED` is past its lifetime with no order; editing it returns `CartErrorCode.CART_NOT_FOUND` — create a fresh cart.
 """
 enum CartStatus {
   ABANDONED