@doswiftly/storefront-operations 14.0.0 → 16.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ 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**: 14.0.0
-- **Queries**: 50
+- **Schema version**: 16.0.0
+- **Queries**: 52
 - **Mutations**: 40
-- **Fragments**: 100
+- **Fragments**: 102
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order
@@ -174,6 +174,29 @@ semantics). Idempotency is the caller's responsibility. If you need retries
 on a mutation, wrap with your own backoff logic and check `userErrors` to
 decide whether to retry.
 
+### Configuration sources — `doswiftly.config.ts` first, env vars only as fallback
+
+`@doswiftly/storefront-sdk` takes `apiUrl` and `shopSlug` as **explicit
+`config`** on `createStorefrontClient` / `<StorefrontProvider>`. The SDK does
+not read env vars, sniff hostnames, or inspect request headers — the
+storefront supplies the values.
+
+Scaffolded storefronts (`doswiftly init`) ship a config helper
+(`lib/graphql/config.ts`) that walks three sources in order:
+
+1. **`doswiftly.config.ts`** — preferred. Committed config file generated at
+   scaffolding. No env wiring needed in normal use.
+2. **`NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG`** — fallback for local
+   dev or storefronts scaffolded outside `doswiftly init`. `doswiftly dev`
+   rewrites `NEXT_PUBLIC_API_URL` at runtime to point at a local CORS proxy.
+3. **`http://localhost:8000` + `demo-shop`** — last-resort defaults.
+
+If you generate code that falls back to env vars, use **exactly these names**.
+**Do NOT invent alternatives** like `API_URL`, `STOREFRONT_URL`,
+`TENANT_SLUG` — `doswiftly dev` keys off the canonical names; alternatives
+mean the proxy starts but the storefront still calls the production API
+directly, and CORS errors only surface on the first client-side mutation.
+
 ## When in doubt
 
 - **Schema question** ("what fields are on `X`?") → grep `schema.graphql`

package/CHANGELOG.md

@@ -1,5 +1,299 @@
 # Changelog
 
+## 16.0.0
+
+### Major Changes
+
+- ca67b92: **BREAKING** — the formatting utilities switch from a hardcoded 13-currency map to runtime-driven `Intl.NumberFormat` resolution. Every ISO 4217 currency known to the runtime is now supported, with the locale-correct symbol and separators.
+
+  **API changes**
+  - `formatDate(date, locale)` — `locale` is now a required argument. The previous hardcoded `'en-US'` default is gone.
+  - `formatDateTime(date, locale)` — `locale` required.
+  - `formatNumber(num, locale)` — `locale` required.
+  - `formatPrice(price, locale?)` — `locale` is now optional. When omitted, the runtime default (`Intl.NumberFormat().resolvedOptions().locale`) is used. The previous `CURRENCY_LOCALES`-keyed auto-selection is gone.
+  - `formatAmount(amount, currencyCode, locale?)` — third argument added (optional).
+  - `formatPriceRange(min, max, locale?)` — third argument added (optional).
+  - `getCurrencySymbol(code, locale?)` — second argument added (optional). The symbol is derived from `Intl.NumberFormat.formatToParts()`; output depends on the locale (`getCurrencySymbol('PLN', 'pl-PL') === 'zł'`, `getCurrencySymbol('PLN', 'en-US') === 'PLN'`).
+
+  **Removed exports**
+  - `CURRENCY_SYMBOLS` — the 13-entry map is gone. Use `getCurrencySymbol(code, locale)` instead, or read the symbol from `Intl.NumberFormat.formatToParts()` directly.
+  - `CURRENCY_LOCALES` — the locale-to-currency map is gone. Pick the locale from the storefront's i18n context (or read `shop.localeToCurrencyMap` from the API for per-shop overrides) and pass it to `formatPrice` / `formatAmount`.
+
+  **Why**
+  - The hardcoded 13-currency map covered ~7% of the ISO 4217 currencies the API now ships in `CurrencyCode` (~180 entries). Every currency outside that list silently fell back to `en-US` formatting — a Brazilian (BRL) or Indian (INR) storefront had to either write its own formatter or accept US-style output.
+  - Locale↔currency is a **per-shop** decision (`shop.localeToCurrencyMap` in the schema is explicitly marked SSOT). A globally-hardcoded map in the SDK is the wrong place for that knowledge — it makes Polish customers of a multi-locale shop unable to see PLN in `'en-PL'` even when the merchant configured it.
+  - Money precision: `formatPrice` and `formatAmount` no longer apply `parseFloat` to `Money.amount`. Decimal strings are forwarded to `Intl.NumberFormat.format()` verbatim, preserving precision across locales and unusual subunit currencies (JPY/KRW zero-decimal, BHD/JOD/KWD three-decimal, ISK rounding).
+
+  **Migration**
+
+  ```ts
+  // Before
+  import {
+    formatDate,
+    formatPrice,
+    CURRENCY_LOCALES,
+    CURRENCY_SYMBOLS,
+  } from "@doswiftly/storefront-sdk";
+
+  formatDate(order.createdAt); // hardcoded "Dec 9, 2025"
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }); // auto-picked pl-PL → "12,50 zł"
+  CURRENCY_LOCALES.PLN; // "pl-PL"
+  CURRENCY_SYMBOLS.PLN; // "zł"
+
+  // After (Client Components)
+  import { useLocale } from "next-intl";
+  import {
+    formatDate,
+    formatPrice,
+    getCurrencySymbol,
+  } from "@doswiftly/storefront-sdk";
+
+  const locale = useLocale(); // e.g. "pl-PL"
+  formatDate(order.createdAt, locale);
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }, locale);
+  getCurrencySymbol("PLN", locale); // "zł"
+
+  // After (Server Components / Route Handlers)
+  import { getLocale } from "next-intl/server";
+  const locale = await getLocale();
+  formatDate(order.createdAt, locale);
+  ```
+
+  For per-shop locale↔currency overrides, read `shop.localeToCurrencyMap` from the Storefront API and resolve the locale yourself before calling `formatPrice` / `formatAmount`.
+
+  **New: Context-driven format hooks**
+
+  `@doswiftly/storefront-sdk/react` now ships convenience hooks that pull the active language from `useLanguageStore` (inside `<StorefrontProvider>`) and return a memoised, locale-bound formatter. Use them when you don't want to pass `locale` to every call:
+
+  ```ts
+  import {
+    useFormatPrice,
+    useFormatAmount,
+    useFormatPriceRange,
+    useFormatDate,
+    useFormatDateTime,
+    useFormatNumber,
+    useGetCurrencySymbol,
+  } from '@doswiftly/storefront-sdk/react';
+
+  function Cart() {
+    const formatPrice = useFormatPrice();
+    return <span>{formatPrice(item.price)}</span>;
+  }
+
+  function OrderRow() {
+    const formatDate = useFormatDate();
+    return <span>{formatDate(order.processedAt)}</span>;
+  }
+  ```
+
+  Each hook accepts an optional last `localeOverride` argument that wins over the store value — useful for a "show in US format" toggle on a single element:
+
+  ```ts
+  const formatPrice = useFormatPrice();
+  return <span>{formatPrice(item.price, 'en-US')}</span>;
+  ```
+
+  Resolution per call: `localeOverride` → `useLanguageStore().language` → runtime default.
+
+  Use the vanilla `formatPrice` / `formatDate` / etc. from `@doswiftly/storefront-sdk` (no hook) with an explicit `locale` for server components, e-mail templates, or any code path outside a provider.
+
+  `formatPercentage` is unchanged.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+### Minor Changes
+
+- 885c011: Re-export checkout types from the public API. `CartClient` methods added in 15.1.0 (`getAvailablePaymentMethods`, `getAvailableShippingMethods`) returned typed payloads, but the named types were not part of the public surface — component props and function signatures touching these payloads required `Awaited<ReturnType<...>>` workarounds. This change closes that gap.
+
+  **Newly exported types:**
+  - `PaymentMethod`, `AvailablePaymentMethods` — shape returned by `CartClient.getAvailablePaymentMethods()`
+  - `AvailableShippingMethod`, `AvailableShippingMethodsPayload`, `FreeShippingProgress`, `DeliveryEstimate`, `ShippingCarrier`, `DeliveryType` — shape returned by `CartClient.getAvailableShippingMethods()`
+  - `PickupPoint`, `PickupPointInput` — locker / pickup-point delivery (surfaced via `MailingAddress.pickupPoint` and `CartAddressInput.pickupPoint`)
+  - `CartAttributeInput` — input shape for `CartClient.updateAttributes()`
+  - `ShippingAddressInput` — input shape for the `availableShippingMethods` standalone query
+
+  **Example:**
+
+  ```ts
+  import type {
+    AvailableShippingMethodsPayload,
+    AvailableShippingMethod,
+    DeliveryType,
+  } from "@doswiftly/storefront-sdk";
+
+  function isPickup(method: AvailableShippingMethod): boolean {
+    return method.deliveryType === "PICKUP_POINT";
+  }
+  ```
+
+  No runtime changes — types already existed internally; this change only adds them to the published surface.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+- fd3d199: Expose `cart.cost.totalDiscount` and `cart.cost.totalShipping` through the `CartCost` fragment.
+
+  The schema already exposed `CartCost.totalDiscount: Money!` (aggregate of every entry in `cart.discountAllocations`) and `CartCost.totalShipping: Money` (cost of the currently selected shipping method, `null` until one is selected), but the shared `CartCost` fragment did not select them — so they were not part of the typed `Cart.cost` returned by `CartClient`. Storefronts wanting to render a single "Discounts: -X" row or a shipping summary had to either sum `discountAllocations` client-side (precision-sensitive across currencies) or query the schema directly and bypass the typed surface.
+
+  After this release, both fields are part of `Cart.cost` returned by every `CartClient` operation — `get`, `create`, `addItems`, `updateItems`, `removeItems`, `setShippingAddress`, `setBillingAddress`, `selectShippingMethod`, `selectPaymentMethod`, `updateBuyerIdentity`, `updateDiscountCodes`, `updateNote`, `updateAttributes`, `applyGiftCard`, `removeGiftCard`, `updateGiftCardRecipient`.
+
+  **Example:**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+
+  const summary = {
+    subtotal: cart.cost.subtotal,
+    discount: cart.cost.totalDiscount, // Money — defaults to amount 0
+    shipping: cart.cost.totalShipping, // Money | null — null until selectShippingMethod()
+    tax: cart.cost.totalTax,
+    total: cart.cost.total, // grand total — use directly on checkout summary
+  };
+  ```
+
+  `totalDiscount` is required (defaults to amount 0 when no discount applies). `totalShipping` is nullable — `null` means no shipping method has been selected yet, an amount of 0 means a free-shipping method was selected.
+
+  Additive — existing consumers keep every field they had before, no breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity (fragment update).
+
+- 51091df: Expose `Cart.status` and `Cart.completedOrder` so storefronts can detect a completed (or expired / abandoned) cart on read, without having to attempt a mutation first and react to its `userErrors[].code`.
+
+  **New fields**
+  - `Cart.status: CartStatus!` — lifecycle status (`ACTIVE`, `ABANDONED`, `CONVERTED`, `RECOVERED`, `EXPIRED`). Only `ACTIVE` carts accept mutations; any other status rejects subsequent mutations with `CartErrorCode.ALREADY_COMPLETED`.
+  - `Cart.completedOrder: Order` — the order this cart converted into. Populated only when `status === CONVERTED`; null on every other status.
+
+  **Why**
+
+  When a buyer returned to the checkout page after completing their order (SSR re-render, deep link, "back" button after redirect), the SDK could only ask `cart(id)` for the cart and got the full pre-completion state back — every form value still there, the "Pay" button still active. The first mutation then failed with `ALREADY_COMPLETED`, after the buyer had already filled out fields. With `status` exposed, the storefront detects the terminal state on initial render and redirects to the order confirmation directly — using the `accessToken` on `completedOrder` for guest tracking, no extra `orderByToken` round-trip.
+
+  **Example**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+  if (!cart) {
+    // Cart not found — guide the buyer to create a new one
+    return redirect("/cart");
+  }
+  if (cart.status !== "ACTIVE") {
+    if (cart.completedOrder) {
+      // Render the order confirmation page off the data you already have
+      return redirect(`/order/${cart.completedOrder.accessToken}`);
+    }
+    // Abandoned / expired — start a fresh cart
+    return redirect("/cart/new");
+  }
+  // Render the checkout form normally
+  ```
+
+  Additive — every existing query that selects the shared `Cart` fragment now sees the two new fields automatically. No breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — schema sync delivers the new fields and the `CartStatus` enum.
+
+- f4efab9: Add `ShopConfigFields` fragment + `query ShopConfig` for `<StorefrontProvider>` setup.
+
+  `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react` expects a `ShopConfig` payload with a specific shape: currency setup (including `localeToCurrencyMap`), language setup, and bot protection. Until now the storefront had to hand-write the field selection, and it was easy to miss `localeToCurrencyMap` (used internally by the SDK for browser-locale-based currency detection) or to add an extra field that didn't match the `ShopConfig` interface.
+
+  **New**
+  - `fragment ShopConfigFields on Shop` — minimal selection that matches the `ShopConfig` interface 1:1.
+  - `query ShopConfig { shop { ...ShopConfigFields } }` — ready-to-use query for the provider.
+
+  **Example**
+
+  ```ts
+  const SHOP_CONFIG_QUERY = /* GraphQL */ `
+    query ShopConfig {
+      shop {
+        ...ShopConfigFields
+      }
+    }
+  `;
+
+  // In a Server Component:
+  const { data } = await execute(SHOP_CONFIG_QUERY);
+  return <StorefrontProvider shopData={data.shop}>{children}</StorefrontProvider>;
+  ```
+
+  Use the larger `Shop` fragment + `query Shop` when you also need branding / contact / business hours for your UI; use `ShopConfig` when you only need to bootstrap the provider.
+
+  Additive — no breaking change.
+
+  `@doswiftly/storefront-sdk` bumped to keep linked parity — no code change.
+
+### Patch Changes
+
+- 7ce8ac4: Clarify how `apiUrl` and `shopSlug` are configured.
+
+  `createStorefrontClient` and `<StorefrontProvider>` take `apiUrl` and `shopSlug` as **explicit `config`** — the SDK does not read environment variables, sniff hostnames, or inspect request headers. The storefront supplies the values; the SDK uses them verbatim.
+
+  Scaffolded storefronts ship a config helper (`lib/graphql/config.ts`) that resolves the two values from these sources, in order:
+  1. `doswiftly.config.ts` (preferred — committed file generated at `doswiftly init`)
+  2. `NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG` (fallback, used for local development)
+  3. `http://localhost:8000` + `demo-shop` (defaults — smoke test only)
+
+  Scratch-built storefronts can skip the helper and pass values into `config={}` directly.
+
+  **What's new**
+  - `@doswiftly/storefront-sdk` README: new `## Configuration` section between `## Installation` and `## Quick Start`. Documents the explicit-config requirement, the three-source resolver shipped with scaffolded storefronts, and when env-var wiring actually matters.
+  - `@doswiftly/storefront-operations` `AGENTS.md`: new `### Configuration sources` convention inside `## Critical conventions — DO NOT hallucinate`. AI assistants now prefer `doswiftly.config.ts` and only fall back to the canonical env-var names.
+
+  Documentation only — no code change.
+
+## 15.1.0
+
+### Minor Changes
+
+- 94c2603: Storefront SDK now covers the full checkout flow end-to-end through typed methods — no more dropping to raw GraphQL for shipping discovery, payment listing, guest order lookup, cart attributes, or saved-address pickers.
+
+  **New `CartClient` methods**
+  - `getAvailableShippingMethods(cartId, address)` — cart-aware shipping discovery. Resolves with `null` when the cart does not exist or has expired (symmetric with `get(cartId)`), otherwise with `AvailableShippingMethodsPayload`: `methods[]` (each carrying `deliveryType` — `HOME`, `PICKUP_POINT`, `LOCKER` — so the storefront picks the pickup / locker UI without inferring from the method name), `freeShippingProgress` (best progress across methods, for the picker banner), and `userErrors[]` populated for business conditions like `DIGITAL_ONLY_NO_SHIPPING` (cart with no shippable lines) or `NO_SHIPPING_METHODS` (unsupported address). Branch on `result.userErrors[0].code`; the `message` is localized per the request's `Accept-Language`.
+  - `getAvailablePaymentMethods()` — shop-level list of active payment methods. Returns `AvailablePaymentMethods`: `methods[]` (sorted by merchant position) and `defaultMethod` (merchant-flagged pre-selection). Prefer `result.defaultMethod ?? result.methods.find(m => m.isDefault)` — the merchant may override the default independently of per-method flags.
+  - `getOrderByToken(token, email?)` — guest order lookup by opaque access token (returned in `complete().order.accessToken`). Optional `email` adds defense in depth; mismatch returns the same `null` shape as an invalid token. Rate-limited server-side (5 req / min per IP + shop).
+  - `updateAttributes(cartId, attributes)` — replace-all of the cart's custom `{ key, value }` pairs (delivery instructions, gift-wrap flags, B2B PO numbers). Pass an empty array to clear.
+
+  **New `AuthClient` method**
+  - `getAddresses()` — saved address book of the authenticated customer (shipping + billing). Resolves with the address list when authenticated, with `null` when no auth context reached the server (symmetric with `getCustomer()`). Each entry carries B2B fields (`taxId`, `vatNumber`) and the `isDefault` flag, so the same list serves both shipping and billing pickers.
+
+  **Schema additions (operations package)**
+  - `MailingAddress` now exposes `taxId`, `vatNumber`, and `pickupPoint`. The new `PickupPoint` type (`provider`, `pointId`, `name?`, `address?`) is returned on shipping addresses delivered to a parcel locker / collection point.
+  - `AvailableShippingMethod` gains the declarative `deliveryType` enum.
+  - `CartAppliedGiftCard` now exposes `id` — the stable handle to pass to `cartRemoveGiftCard` (no need to keep the raw gift card code on the client).
+  - New `CustomerAddresses` query — `customer.addresses(first: 50)` connection returning the address book, normalized to a node list by the SDK wrapper.
+
+  **SDK fragment changes**
+
+  The SDK's `MailingAddress` fragment now selects `taxId`, `vatNumber`, and `pickupPoint`. Existing types that include a mailing address (`Cart.shippingAddress`, `Cart.billingAddress`, `Order.shippingAddress`, `Customer.defaultAddress`) get these fields automatically. The `AvailableShippingMethod` fragment selects `deliveryType`. The `CartAppliedGiftCard` fragment selects `id`.
+
+  **New React hook — server-driven checkout**
+  - `useCart(cartId, options?)` — sister of `useCartManager`, bound to an explicit `cartId` instead of the `cart-id` cookie. Use it for SSR-rendered checkout, deep-link order recovery, and admin "view this cart" UIs where the cart id is known up front and the cookie is irrelevant. Returns the loaded cart plus the same mutation surface as the cookie-based hook (`addItems`, `updateItems`, `removeItems`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote`, `updateAttributes` — each resolves with `{ cart, warnings }` so low-stock and partial-availability hints flow through), reactive `isLoading` / `error` / `operation` state, and a `refetch()` callback. `autoFetch: false` + `initialCart` lets you skip the hydration round-trip when the server already resolved the cart.
+
+  **Field-level descriptions visible in your IDE**
+
+  Hovering on any cart / order / customer / payment / shipping field in your editor now shows a precise English description of what the field carries — when to use it, what its values mean, what is null vs zero, which enum values are relevant. The descriptions were rewritten across every type selected by the SDK so the storefront-developer audience does not need to look anywhere else for the contract. Codegen is configured (`preResolveTypes: false`) to propagate those descriptions through every generated fragment / query type, so the same hover works on the typed shape your codegen produces.
+
+  These additions are backward-compatible — existing calls keep their current signatures and return the same fields (plus the new ones). The mailing-address fragment expansion is purely additive.
+
+## 15.0.0
+
+### Major Changes
+
+- a11f9e4: GraphQL types are now generated from the storefront schema instead of being hand-written. Every exported cart, order, customer, and payment type is derived directly from the schema, so they can no longer drift out of sync with the API.
+
+  **Breaking** — the previous hand-written types were inaccurate, and correcting them changes some shapes:
+  - `Customer.orderCount` is now `string` (was `number`).
+  - `CartLineEdge` and `CartLineConnection.edges` were removed — the cart query never returned edges.
+  - Fields previously typed as `string` are now precise string-literal union types: `Order.status`, `Order.paymentStatus`, `Order.fulfillmentStatus`, `PaymentSession.status`, `CartLine.productType`, `Money.currencyCode`, `CartWarning.code`, and the `AttributeSelection` mode fields. Reading these values still works; assigning arbitrary strings into them no longer compiles.
+
+  **Fixed** — types that were missing fields or had the wrong nullability:
+  - `Order` now includes `accessToken`.
+  - `Cart` and `CartLine` now include `requiresShipping`.
+  - `Customer.displayName`, `Customer.emailMarketing`, and `Customer.totalSpent` are now correctly non-nullable.
+  - The duplicated `MailingAddress` definition is collapsed into one.
+
+  **New** — the schema enum types used by the public types are now exported: `CurrencyCode`, `CountryCode`, `LanguageCode`, `ProductTypeEnum`, `WeightUnit`, `CartWarningCode`, `StorefrontOrderStatus`, `OrderPaymentStatus`, `OrderFulfillmentStatus`, `EmailMarketingState`, `MarketingOptInLevel`, and the attribute enums.
+
+  These are type-only changes — no runtime behaviour changed.
+
 ## 14.0.0
 
 ### Major Changes

package/README.md

@@ -163,6 +163,7 @@ full executable body of each operation.
 | Operation | Description |
 | --- | --- |
 | `Shop` | Returns shop configuration: name, base + supported currencies, supported locales, branding (logo, colors, fonts, social links), contact info, active payment methods, brand metadata, money format template, and the list of countries the shop ships to. Public; no auth required. Call once per session and cache — almost everything else is contextualized by the shop returned here. |
+| `ShopConfig` | Minimal Shop payload for `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react`. Returns exactly the fields the SDK's `ShopConfig` interface declares — currency setup (with `localeToCurrencyMap` for browser-locale-based currency detection), language setup, and bot protection. Cache for the session; refetch when the merchant updates currency / language settings or you want to pick up new bot-protection rules. |
 
 #### Products
 
@@ -200,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. |
+| `CustomerAddresses` | Authenticated customer's saved address book — used on checkout to let the buyer pick a previously-used shipping / billing address instead of typing it. Each entry carries B2B invoicing fields (`taxId`, `vatNumber`) and the `isDefault` flag so the same list serves both as the shipping picker and as the billing/invoice picker. Returns up to 50 addresses (Relay Connection — buyers rarely keep more); for the unauthenticated case the connection is empty (no error). The default address is also surfaced as `Customer.defaultAddress`. |
 | `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. |
 
@@ -465,7 +467,8 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `MailingAddress` | `MailingAddress` | Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Spread on the address book UI and order summaries. |
+| `PickupPoint` | `PickupPoint` | Selected pickup point (parcel locker or collection point) attached to a delivery address. Returned on `MailingAddress.pickupPoint` when the buyer chose a non-home delivery method (`deliveryType` other than `HOME`). Null for home delivery. |
+| `MailingAddress` | `MailingAddress` | Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries. |
 | `CustomerAccessToken` | `CustomerAccessToken` | Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d. |
 | `Customer` | `Customer` | Customer profile — basic info plus B2B fields (`taxId`, `vatNumber`, `regon`, `companyName`), default address, lifetime stats (`orderCount`, `totalSpent`), marketing preferences. Use on profile / settings pages. |
 | `Order` | `Order` | Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps, plus payment capability signal (`canCreatePayment` + `paymentMethodType`) the storefront uses to decide post-completion payment flow without hard-coded provider checks. Spread on the order list, order detail, and the `cartComplete` mutation result. Line items are not included here. |
@@ -474,7 +477,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `CartCost` | `CartCost` | Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment. |
+| `CartCost` | `CartCost` | Cart-level totals — subtotal, total, tax, duty, discount, shipping, checkout charge. Spread inside the `Cart` fragment. |
 | `CartLineCost` | `CartLineCost` | Per-line cost breakdown — unit price, line subtotal/total, compare-at unit price (for showing strikethroughs). Spread inside `CartLine`. |
 | `AttributeSelection` | `AttributeSelection` | Typed snapshot of a customer-filled product attribute (configurator selection) on a cart line. Includes the chosen option / text value, fillingMode, billingMode, surcharge, tax class, and any linked variant. Distinct from `CartLine.attributes` which holds raw key-value line item properties (free-form, untyped). |
 | `CartLine` | `CartLine` | A single line in the cart — variant + quantity + per-line cost, plus dual attribute storage: `attributes[]` for free-form key-value properties (gift wrap, engraving notes), `attributeSelections[]` for typed configurator answers. |
@@ -483,7 +486,7 @@ full executable body of each operation.
 | `CartDiscountAllocation` | `CartDiscountAllocation` | Allocation of a discount code to the cart total — pairs the code with the actual money discounted. Use to show "saved X with code Y" in cart UI. |
 | `Cart` | `Cart` | Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes, plus fulfillment fields (email/phone/addresses/shipping method/payment method/applied gift cards). Spread on the cart drawer / cart page; refetch after every cart mutation including completion lifecycle. |
 | `CartShippingMethod` | `CartShippingMethod` | Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation. |
-| `CartAppliedGiftCard` | `CartAppliedGiftCard` | Gift card applied to a cart — masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`. |
+| `CartAppliedGiftCard` | `CartAppliedGiftCard` | Gift card applied to a cart — `id` is the stable handle the storefront passes to `cartRemoveGiftCard` (no need to keep the raw code around). Plus masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`. |
 | `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
 
 #### Shop
@@ -499,6 +502,7 @@ full executable body of each operation.
 | `BotProtectionProvider` | `BotProtectionProviderInfo` | Bot-protection provider config (provider name, site key, script URL) for storefront-side challenge widgets. |
 | `BotProtection` | `BotProtectionInfo` | Bot-protection setup for the shop — primary + fallback provider, and the list of `protectedOperations` (mutation names that require a challenge token). Spread inside `Shop`. |
 | `Shop` | `Shop` | The shop itself — name, primary domain, currencies + locales, branding, contact info, business hours, bot-protection config. Spread on the root `shop` query; cache for the session. |
+| `ShopConfigFields` | `Shop` | Minimal Shop fields consumed by `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react`. Spread this in your `shop` query to get a response shape that matches the SDK `ShopConfig` interface 1:1 — no manual field selection, no drift when the SDK adds optional fields. Use the larger `Shop` fragment when you also need branding / contact / business hours for your UI. |
 
 #### Payment Methods
 
@@ -543,7 +547,7 @@ full executable body of each operation.
 | `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo URL, internal service code. |
 | `DeliveryEstimate` | `DeliveryEstimate` | Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days"). |
 | `FreeShippingProgress` | `FreeShippingProgress` | Free-shipping progress info — `qualifies` flag, current cart amount, threshold, remaining to qualify, percent progress, and a localized message ("Add 20 PLN more for free shipping"). Use to render a free-shipping progress bar in the cart drawer. |
-| `AvailableShippingMethod` | `AvailableShippingMethod` | One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. Spread on the checkout shipping step. |
+| `AvailableShippingMethod` | `AvailableShippingMethod` | One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. `deliveryType` signals whether to render a pickup-point / locker picker (`HOME` vs `PICKUP_POINT` / `LOCKER`) so the storefront does not have to infer it from the method name. Spread on the checkout shipping step. |
 
 #### Attribute Filters
 

package/fragments.graphql

@@ -244,7 +244,15 @@ fragment Category on Category {
 # Customer
 # ============================================
 
-# Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Spread on the address book UI and order summaries.
+# Selected pickup point (parcel locker or collection point) attached to a delivery address. Returned on `MailingAddress.pickupPoint` when the buyer chose a non-home delivery method (`deliveryType` other than `HOME`). Null for home delivery.
+fragment PickupPoint on PickupPoint {
+  provider
+  pointId
+  name
+  address
+}
+
+# Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
 fragment MailingAddress on MailingAddress {
   id
   streetLine1
@@ -261,6 +269,11 @@ fragment MailingAddress on MailingAddress {
   stateCode
   postalCode
   isDefault
+  taxId
+  vatNumber
+  pickupPoint {
+    ...PickupPoint
+  }
 }
 
 # Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d.
@@ -334,7 +347,7 @@ fragment Order on Order {
 # Cart
 # ============================================
 
-# Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment.
+# Cart-level totals — subtotal, total, tax, duty, discount, shipping, checkout charge. Spread inside the `Cart` fragment.
 fragment CartCost on CartCost {
   total {
     ...Money
@@ -351,6 +364,12 @@ fragment CartCost on CartCost {
   checkoutCharge {
     ...Money
   }
+  totalDiscount {
+    ...Money
+  }
+  totalShipping {
+    ...Money
+  }
 }
 
 # Per-line cost breakdown — unit price, line subtotal/total, compare-at unit price (for showing strikethroughs). Spread inside `CartLine`.
@@ -492,6 +511,15 @@ fragment Cart on Cart {
   requiresShipping
   createdAt
   updatedAt
+  status
+  completedOrder {
+    id
+    orderNumber
+    accessToken
+    status
+    paymentStatus
+    fulfillmentStatus
+  }
 }
 
 # Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation.
@@ -503,8 +531,9 @@ fragment CartShippingMethod on CartShippingMethod {
   }
 }
 
-# Gift card applied to a cart — masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`.
+# Gift card applied to a cart — `id` is the stable handle the storefront passes to `cartRemoveGiftCard` (no need to keep the raw code around). Plus masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`.
 fragment CartAppliedGiftCard on CartAppliedGiftCard {
+  id
   maskedCode
   lastCharacters
   appliedAmount {
@@ -647,6 +676,21 @@ fragment Shop on Shop {
   }
 }
 
+# Minimal Shop fields consumed by `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react`. Spread this in your `shop` query to get a response shape that matches the SDK `ShopConfig` interface 1:1 — no manual field selection, no drift when the SDK adds optional fields. Use the larger `Shop` fragment when you also need branding / contact / business hours for your UI.
+fragment ShopConfigFields on Shop {
+  currencyCode
+  supportedCurrencies
+  localeToCurrencyMap {
+    locale
+    currency
+  }
+  defaultLanguage
+  supportedLanguages
+  botProtection {
+    ...BotProtection
+  }
+}
+
 # ============================================
 # Payment Methods
 # ============================================
@@ -924,11 +968,12 @@ fragment FreeShippingProgress on FreeShippingProgress {
   message
 }
 
-# One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. Spread on the checkout shipping step.
+# One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. `deliveryType` signals whether to render a pickup-point / locker picker (`HOME` vs `PICKUP_POINT` / `LOCKER`) so the storefront does not have to infer it from the method name. Spread on the checkout shipping step.
 fragment AvailableShippingMethod on AvailableShippingMethod {
   id
   name
   description
+  deliveryType
   carrier {
     ...ShippingCarrier
   }