@doswiftly/storefront-operations 11.2.0 → 11.4.0

package/AGENTS.md

@@ -27,8 +27,8 @@ 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**: 11.2.0
-- **Queries**: 48
+- **Schema version**: 11.4.0
+- **Queries**: 49
 - **Mutations**: 40
 - **Fragments**: 100
 <!-- AUTOGEN:STATS:END -->

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## 11.4.0
+
+### Minor Changes
+
+- 9bd60e8: Added `OrderByToken` query and `accessToken` field on the `Order` type for guest order summary access.
+
+  **What's new for storefronts:**
+  - **`Order.accessToken: String!`** — opaque per-order token returned in `cartComplete.order.accessToken`. Pass it to `OrderByToken` to render the order summary for guests who have not signed in. The token is permanent until the order is deleted and stable across reads (safe to share via signed URLs in confirmation emails).
+  - **`OrderByToken($token: String!, $email: String)` query** — fetches a single order using the access token. The optional `email` argument is a defense-in-depth guard: when provided, it must match the order's buyer email case-insensitively; on mismatch the query returns `null` exactly like an invalid token (response shape is identical so attackers cannot distinguish the failure mode).
+  - Rate-limited to 5 requests per minute per IP+shop. Throttled clients receive a GraphQL error with `extensions.code: THROTTLED`.
+  - Response carries `Cache-Control: no-store` so per-customer data is never served from CDN or browser cache between users.
+
+  **Storage recommendation:** persist the token in an **HTTP-only cookie** (preferred) or `sessionStorage` for the post-checkout summary page — **never `localStorage`** (XSS-readable).
+
+  **Backward compatibility:** strictly additive. Existing queries (`CustomerOrder`, cart mutations, customer auth) are unchanged — upgrade is opt-in.
+
+## 11.3.1
+
+### Patch Changes
+
+- 9ca724e: Removes the `./schema` subpath export from `@doswiftly/storefront-sdk` — it was a duplicate of what `@doswiftly/storefront-operations` already publishes.
+
+  **Why:**
+
+  `@doswiftly/storefront-operations` is a linked package — it is always installed alongside `@doswiftly/storefront-sdk`. It exposes the GraphQL SDL as a raw `schema.graphql` file via the `./schema.graphql` subpath export, which is the format every codegen tool and IDE GraphQL plugin natively consumes. Bundling the same SDL again as an ESM string literal in `@doswiftly/storefront-sdk/schema` added ~128 KB to the npm tarball without giving consumers a meaningful capability that wasn't already there.
+
+  **Migration:**
+
+  Switch from:
+
+  ```ts
+  import { schema } from "@doswiftly/storefront-sdk/schema";
+  ```
+
+  to a direct path reference in your codegen config (or `graphql-config` for your IDE):
+
+  ```ts
+  // codegen.ts
+  const config = {
+    schema: "node_modules/@doswiftly/storefront-operations/schema.graphql",
+    // …
+  };
+  ```
+
+  The schema content is byte-for-byte identical — your codegen output does not change.
+
+  **Internal:**
+  - Removed `scripts/build-schema-export.cjs` and the matching `pnpm build` chain step.
+  - `pnpm build` is now plain `tsc` again.
+  - Removed the `dist/schema.js` + `dist/schema.d.ts` build artifacts and the `schema-export.test.ts` unit test.
+  - `pnpm run doctor` no longer checks for the schema bundle.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+## 11.3.0
+
+### Minor Changes
+
+- 0a2dfd8: Phase 1 of the senior-level audit ships security hardening, dead-code cleanup, and a coverage gate.
+
+  **Security:**
+  - `createSetTokenHandler`, `createClearTokenHandler`, `createWhoamiHandler` now validate the `Origin` header against the `Host` header by parsed URL host (`new URL(origin).host === host`) instead of a substring `includes()` check. The previous implementation was bypassable by empty Host (`includes('')` is always true) and by Origin URLs that embedded the trusted host in their query string. Requests without both `Origin` and `Host` headers now respond with `403`.
+
+  **Removed:**
+  - `ServerClientOptions.getHeaders` (accepted by `getStorefrontClient()` but never wired through). Inject request-scoped headers via the `middleware` option — see updated JSDoc.
+
+  **Internal:**
+  - Inconsistent `setIsRenewingToken` setter in `useAuth` is renamed to `setIsRefreshingToken` to match the exposed `isRefreshingToken` flag.
+  - Removed an unused `callbackName` field in `TurnstileManager` and a pre-cookie-era `localStorage.removeItem('cart-storage')` call in `createCartStore`.
+
+  **Infrastructure:**
+  - `package.json` now declares `sideEffects: false` so consumer bundlers can tree-shake unused exports aggressively.
+  - Adds `test:coverage` script (`vitest run --coverage`) with a baseline threshold (60% statements / 50% branches / 55% functions / 60% lines). The floor will rise as later phases cover the React providers, auth/currency/language stores, and remaining hooks.
+  - Adds 102 new unit tests across `format`, `image`, `cookies`, `auth/handlers`, and additional `errorMiddleware`/`timeoutMiddleware`/`languageMiddleware` cases — including two regression tests for the origin-validation bypass vectors.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+- 09c3744: Phase 2 of the SDK audit ships the developer-experience features external storefront builders have been writing by hand: pre-built React components, tagged-union mutation state, a bundled GraphQL schema export, and a focused-hook auth API.
+
+  **Pre-built React components** (from `@doswiftly/storefront-sdk/react`):
+
+  Six headless, accessibility-aware components — zero styling, framework-agnostic, no `next/image` dependency so they work in any React 18/19 environment.
+  - `<Money amount currency>` — locale-formatted price from minor units (wraps `formatPrice`).
+  - `<Image data sizes priority>` — `<img>` with thumbhash blur placeholder, lazy by default, `fetchpriority` hint.
+  - `<CartCount count label hideWhenEmpty>` — aria-live cart item count.
+  - `<AddToCartButton variantId quantity onSuccess onError>` — orchestrates `useCartManager.addItem` with loading state + sr-only error alert.
+  - `<PriceDisplay price compareAtPrice currency>` — current price + optional strikethrough sale price.
+  - `<CartTotals subtotal discount shipping tax total currency labels>` — `<dl>` breakdown that elides empty rows.
+
+  **Tagged-union status in `useCartManager`**:
+  - New `status` field on the hook return — `{ type: 'idle' | 'loading' | 'error' | 'success', operation? }` — enables exhaustive switching without juggling booleans.
+  - `isLoading` and `error` remain available as derived selectors (backward-compatible).
+  - `clearCart()` resets status to `idle`.
+
+  **Bundled GraphQL schema** (`@doswiftly/storefront-sdk/schema`):
+  - New export path ships the full GraphQL SDL (123 KB) as a string constant, regenerated from `@doswiftly/storefront-operations/schema.graphql` on each build.
+  - Wire GraphQL codegen / IDE plugins without a live backend — no extra `npm install`.
+
+  **`useAuth` split into focused hooks**:
+  - `useLogin({ onSetToken })` — login flow only, `{ login, isLoggingIn, error }`.
+  - `useLogout({ onClearToken })` — logout, always clears local store even on backend failure.
+  - `useRefreshToken({ onSetToken })` — token rotation, keeps existing customer.
+  - `useAuth(options)` is preserved as a thin facade composing the three (backward-compatible, no breaking change).
+
+  Prefer the focused hooks in new code — smaller bundles, isolated state, smaller dependency arrays.
+
+  **Docs**:
+  - README adds a 7-step Next.js 16 App Router setup, BFF route handler examples, components catalog, bundled schema usage.
+  - New `docs/storefront-developer/sdk/nextjs-setup.md` and `auth.md` with end-to-end recipes.
+
+  **Tests**: 476 → 494 unit tests (+18). New files: `components.test.tsx` (37 cases), `schema-export.test.ts` (5 cases), `use-auth.test.tsx` (13 cases). Build clean, 0-deps invariant preserved.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
 ## 11.2.0
 
 ### Minor Changes

package/README.md

@@ -201,6 +201,7 @@ full executable body of each operation.
 | `Customer` | Full customer profile — basic info plus the first 10 addresses and first 10 orders. Heaviest customer query; for narrow use cases prefer `CustomerProfile` (no orders / addresses) or `CustomerOrder` (single order). Returns null if unauthenticated. |
 | `CustomerProfile` | Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than `Customer`. Returns null if unauthenticated. |
 | `CustomerOrder` | Single order by `orderId`. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full `Customer` payload to access one order. Use on the order detail page. |
+| `OrderByToken` | Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted. |
 
 #### Discount Code Validation
 

package/fragments.graphql

@@ -301,6 +301,7 @@ fragment Customer on Customer {
 fragment Order on Order {
   id
   orderNumber
+  accessToken
   totals {
     total {
       ...Money

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **11.2.0**
-> 48 queries · 40 mutations · 100 fragments
+> Schema version: **11.4.0**
+> 49 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -430,6 +430,27 @@ query CustomerOrder($orderId: ID!) {
 }
 ```
 
+### Query: `OrderByToken`
+
+**Section**: Customer (requires auth)
+
+**Description**: Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.
+
+**Variables**:
+- `$token`: `String!`
+- `$email`: `String`
+
+**Fragments used**: `Order`
+
+**GraphQL**:
+```graphql
+query OrderByToken($token: String!, $email: String) {
+  orderByToken(token: $token, email: $email) {
+    ...Order
+  }
+}
+```
+
 ### Query: `CartValidateDiscountCode`
 
 **Section**: Discount Code Validation
@@ -2782,6 +2803,7 @@ fragment Customer on Customer {
 fragment Order on Order {
   id
   orderNumber
+  accessToken
   totals {
     total {
       ...Money

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "11.2.0",
+  "schemaVersion": "11.4.0",
   "queries": [
     {
       "name": "Shop",
@@ -324,6 +324,28 @@
       ],
       "body": "query CustomerOrder($orderId: ID!) {\n  customerOrder(orderId: $orderId) {\n    ...Order\n  }\n}"
     },
+    {
+      "name": "OrderByToken",
+      "kind": "query",
+      "section": "Customer (requires auth)",
+      "description": "Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish \"token valid, wrong email\" from \"token invalid\"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.",
+      "variables": [
+        {
+          "name": "token",
+          "type": "String!",
+          "defaultValue": null
+        },
+        {
+          "name": "email",
+          "type": "String",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Order"
+      ],
+      "body": "query OrderByToken($token: String!, $email: String) {\n  orderByToken(token: $token, email: $email) {\n    ...Order\n  }\n}"
+    },
     {
       "name": "CartValidateDiscountCode",
       "kind": "query",
@@ -1995,7 +2017,7 @@
         "MailingAddress",
         "Money"
       ],
-      "body": "fragment Order on Order {\n  id\n  orderNumber\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
+      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
       "onType": "Order"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "11.2.0",
+  "version": "11.4.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/queries.graphql

@@ -231,6 +231,13 @@ query CustomerOrder($orderId: ID!) {
   }
 }
 
+# Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.
+query OrderByToken($token: String!, $email: String) {
+  orderByToken(token: $token, email: $email) {
+    ...Order
+  }
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================

package/schema.graphql

@@ -3571,6 +3571,11 @@ enum NodeType {
 
 """Customer order summary"""
 type Order implements Node {
+  """
+  Opaque access token (UUID v4) umożliwiający dostęp do podsumowania zamówienia bez sesji (guest order access via orderByToken query). Trwały per order — share dla forwarded receipts. Storefront powinien przechowywać HTTP-only cookie / sessionStorage (NIGDY localStorage). Defense-in-depth: orderByToken akceptuje opcjonalny email guard żeby ograniczyć blast radius kompromisu.
+  """
+  accessToken: String!
+
   """Czy storefront może zainicjować płatność dla tego order"""
   canCreatePayment: Boolean!
 
@@ -3592,6 +3597,11 @@ type Order implements Node {
   """Line items count"""
   itemCount: Int!
 
+  """
+  Pozycje zamówienia (top-level connection) — eliminuje N+1 vs Order.shipments.items
+  """
+  lineItems(after: String, first: Int = 10): OrderLineItemConnection!
+
   """Lista meta properties (Relay Connection)"""
   metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
 
@@ -3625,9 +3635,12 @@ type Order implements Node {
 
 """Paginated order connection"""
 type OrderConnection {
-  """Order edges"""
+  """Order edges with cursors"""
   edges: [OrderEdge!]!
 
+  """Order nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [Order!]!
+
   """Pagination info"""
   pageInfo: PageInfo!
 
@@ -3656,6 +3669,69 @@ enum OrderFulfillmentStatus {
   UNFULFILLED
 }
 
+"""Pozycja zamówienia (line item) z variant snapshot i live enrichment"""
+type OrderLineItem {
+  """Unique identifier"""
+  id: ID!
+
+  """
+  Całkowita cena linii z momentu zakupu (unitPrice × quantity, minor units)
+  """
+  originalTotalPrice: Money!
+
+  """
+  Cena jednostkowa z momentu zakupu (minor units, include BUNDLED surcharges)
+  """
+  originalUnitPrice: Money!
+
+  """Ilość zamówiona (snapshot z checkout)"""
+  quantity: Int!
+
+  """Ilość już zrealizowana (shipped — per-item fulfillment tracking)"""
+  quantityFulfilled: Int!
+
+  """
+  Ilość pozostała do zwrotu/refund (quantity - returnedQuantity, clamp ≥ 0). Industry-standard semantyka dla refund tracking.
+  """
+  refundableQuantity: Int!
+
+  """
+  Nazwa produktu z momentu zakupu (snapshot). NIE live `Product.name` — preserved nawet po edycji produktu (KSeF/invoice compliance).
+  """
+  title: String!
+
+  """
+  Live wariant produktu (fresh image/price). Null jeśli wariant został usunięty po zakupie — consumer powinien użyć `title` jako fallback.
+  """
+  variant: ProductVariant
+}
+
+"""Paginated order line items (Relay Connection)"""
+type OrderLineItemConnection {
+  """Order line item edges with cursors"""
+  edges: [OrderLineItemEdge!]!
+
+  """Order line item nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [OrderLineItem!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """
+  Total count of line items in the order (convention parity z OrderConnection/MailingAddressConnection)
+  """
+  totalCount: Int!
+}
+
+"""Order line item edge"""
+type OrderLineItemEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Order line item node"""
+  node: OrderLineItem!
+}
+
 """Payment status of an order"""
 enum OrderPaymentStatus {
   AUTHORIZED
@@ -4701,6 +4777,19 @@ type Query {
   """
   nodes(ids: [ID!]!, type: NodeType!): [Node]!
 
+  """
+  Fetch a single order by its opaque access token (guest order access without a session). Optional `email` argument enables defense-in-depth: if provided, must match the order buyer email (case-insensitive); on mismatch the query returns null exactly like an invalid token. Rate-limited to 5 requests per minute per IP+shop. Response carries Cache-Control: no-store.
+  """
+  orderByToken(
+    """
+    Optional email guard (case-insensitive). When provided, must match the order buyer email; on mismatch returns null (same shape as invalid token). The storefront decides per threat model.
+    """
+    email: String
+
+    """Opaque access token from Order.accessToken"""
+    token: String!
+  ): Order
+
   """Get a page by handle or ID"""
   page(
     """Page handle"""