@doswiftly/storefront-operations 15.1.0 → 16.1.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**: 15.1.0
-- **Queries**: 51
+- **Schema version**: 16.1.0
+- **Queries**: 52
 - **Mutations**: 40
-- **Fragments**: 101
+- **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,374 @@
 # Changelog
 
+## 16.1.0
+
+### Minor Changes
+
+- 1e6062e: Read the gift card recipient back from the cart.
+
+  `cartUpdateGiftCardRecipient` already persisted the recipient (email, name,
+  personalised message) on a gift card line — but the `CartLine` type didn't
+  expose any field to read it. Storefronts that render the checkout server-side
+  (SSR, deep link, "back to cart" navigation) had no way to know that the buyer
+  had already filled in the recipient form on a previous visit. The recipient
+  dialog opened blank, like nothing had been saved.
+
+  **New field** — `CartLine.giftCardRecipient: GiftCardLineRecipient`
+
+  ```graphql
+  type GiftCardLineRecipient {
+    recipientEmail: String
+    recipientName: String
+    message: String
+  }
+  ```
+
+  All three fields are individually nullable so a partial set (email only, no
+  name or message) is representable as-is. The field on `CartLine` itself is
+  nullable — `null` means the buyer has not set a recipient yet, in which case
+  the gift card is delivered to the order `customerEmail` on completion.
+
+  `null` is also what you get for any non-gift-card line — there is no risk of
+  the field reporting a stale recipient from a previous line at the same index.
+
+  **Use it to seed your form**
+
+  ```tsx
+  const cart = await cartClient.get(cartId);
+  const giftLine = cart?.lines.edges.find(
+    (e) => e.node.productType === "GIFT_CARD",
+  );
+
+  <GiftRecipientForm
+    defaultValues={
+      giftLine?.node.giftCardRecipient ?? {
+        recipientEmail: "",
+        recipientName: "",
+        message: "",
+      }
+    }
+    onSubmit={(values) =>
+      cartClient.updateGiftCardRecipient(cartId, giftLine!.node.id, values)
+    }
+  />;
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. The `CartLine` fragment
+  shipped by the SDK already includes the new field after this release, so
+  upgrading immediately unlocks the read path. No client code changes required
+  to keep existing flows working.
+
+- ac2e306: Distinguish recoverable session loss from permanent cart denial.
+
+  Adds a new `CART_UNAUTHENTICATED` code to the cart error envelope. Until now,
+  both "your sign-in expired" and "this cart belongs to someone else" surfaced
+  as `CART_FORBIDDEN`, so a storefront had no way to know whether to send the
+  buyer to `/login` (recoverable) or to drop the cart cookie (permanent).
+  After the typical ~24h session TTL, the buyer would silently lose their
+  checkout state instead of being prompted to re-authenticate.
+
+  **New code** — `CART_UNAUTHENTICATED`
+
+  | Condition                                                                             | Code                         | Recovery                                                    |
+  | ------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
+  | Anonymous request **or** expired/invalid session on a cart that belongs to a customer | `CART_UNAUTHENTICATED`       | Re-authenticate. Cart is preserved (`cart-id` cookie kept). |
+  | Authenticated as a **different** customer than the cart owner                         | `CART_FORBIDDEN` (unchanged) | Drop the cart cookie and start over.                        |
+
+  The cart resource itself is intact in the `CART_UNAUTHENTICATED` case — the
+  buyer's saved address, line items, discount codes, and gift cards return as
+  soon as they sign in.
+
+  **New SDK signal** — `runner.onSessionExpired(...)`
+
+  The recovery runner now exposes a separate event for session loss, distinct
+  from `onExpired` (which is for cart-resource lifecycle: cart not found, cart
+  already completed). Subscribe once at the provider level and route the buyer
+  to `/login` with a `return_to` parameter; the cart cookie stays put.
+
+  ```ts
+  // app/providers.tsx
+  const unsubExpired = runner.onExpired(() => {
+    // cart resource gone — start fresh
+    router.push("/cart/new");
+  });
+
+  const unsubSession = runner.onSessionExpired(() => {
+    // session gone, cart preserved — sign back in
+    router.push(`/login?return_to=${encodeURIComponent(location.pathname)}`);
+  });
+  ```
+
+  The session branch throws `CartSessionRequiredError` (re-exported alongside
+  `CartRecoveryNotPossibleError`) and does **not** invoke `recreateAndRun` —
+  recreating the cart on a stale session would discard the buyer's progress.
+
+  **Imperative handling**
+
+  If you handle mutation errors directly (Server Action, custom hook), add one
+  case to your existing switch:
+
+  ```ts
+  switch (err.userErrors[0]?.code) {
+    case "CART_UNAUTHENTICATED":
+      redirect(`/login?return_to=${encodeURIComponent("/checkout")}`);
+      break;
+    case "CART_FORBIDDEN":
+      cookies().delete("cart-id");
+      redirect("/cart/expired");
+      break;
+    // ...existing cases for CART_NOT_FOUND / ALREADY_COMPLETED
+  }
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. Existing `case 'CART_FORBIDDEN'`
+  branches keep working as before. Opt in to the new code at your own pace; until
+  you add the case, anonymous and cross-customer denials fall into your existing
+  default branch (one will be recoverable, one will not — adding the case lets
+  you distinguish them).
+
+## 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

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
 
@@ -476,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. |
@@ -501,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
 

package/fragments.graphql

@@ -347,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
@@ -364,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`.
@@ -421,6 +427,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 
 # Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
@@ -505,6 +516,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.
@@ -661,6 +681,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
 # ============================================

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **15.1.0**
-> 51 queries · 40 mutations · 101 fragments
+> Schema version: **16.1.0**
+> 52 queries · 40 mutations · 102 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -37,6 +37,25 @@ query Shop {
 }
 ```
 
+### Query: `ShopConfig`
+
+**Section**: Shop
+
+**Description**: 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.
+
+**Variables**: none
+
+**Fragments used**: `ShopConfigFields`
+
+**GraphQL**:
+```graphql
+query ShopConfig {
+  shop {
+    ...ShopConfigFields
+  }
+}
+```
+
 ### Query: `Product`
 
 **Section**: Products
@@ -2920,7 +2939,7 @@ fragment Order on Order {
 
 **Section**: Cart
 
-**Description**: Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment.
+**Description**: Cart-level totals — subtotal, total, tax, duty, discount, shipping, checkout charge. Spread inside the `Cart` fragment.
 
 **Uses fragments**: `Money`
 
@@ -2942,6 +2961,12 @@ fragment CartCost on CartCost {
   checkoutCharge {
     ...Money
   }
+  totalDiscount {
+    ...Money
+  }
+  totalShipping {
+    ...Money
+  }
 }
 ```
 
@@ -3027,6 +3052,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 ```
 
@@ -3147,6 +3177,15 @@ fragment Cart on Cart {
   requiresShipping
   createdAt
   updatedAt
+  status
+  completedOrder {
+    id
+    orderNumber
+    accessToken
+    status
+    paymentStatus
+    fulfillmentStatus
+  }
 }
 ```
 
@@ -3406,6 +3445,31 @@ fragment Shop on Shop {
 }
 ```
 
+### Fragment: `ShopConfigFields` on `Shop`
+
+**Section**: Shop
+
+**Description**: 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.
+
+**Uses fragments**: `BotProtection`
+
+**GraphQL**:
+```graphql
+fragment ShopConfigFields on Shop {
+  currencyCode
+  supportedCurrencies
+  localeToCurrencyMap {
+    locale
+    currency
+  }
+  defaultLanguage
+  supportedLanguages
+  botProtection {
+    ...BotProtection
+  }
+}
+```
+
 ### Fragment: `PaymentMethod` on `PaymentMethod`
 
 **Section**: Payment Methods

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "15.1.0",
+  "schemaVersion": "16.1.0",
   "queries": [
     {
       "name": "Shop",
@@ -12,6 +12,17 @@
       ],
       "body": "query Shop {\n  shop {\n    ...Shop\n  }\n}"
     },
+    {
+      "name": "ShopConfig",
+      "kind": "query",
+      "section": "Shop",
+      "description": "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.",
+      "variables": [],
+      "fragmentRefs": [
+        "ShopConfigFields"
+      ],
+      "body": "query ShopConfig {\n  shop {\n    ...ShopConfigFields\n  }\n}"
+    },
     {
       "name": "Product",
       "kind": "query",
@@ -2072,12 +2083,12 @@
       "name": "CartCost",
       "kind": "fragment",
       "section": "Cart",
-      "description": "Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment.",
+      "description": "Cart-level totals — subtotal, total, tax, duty, discount, shipping, checkout charge. Spread inside the `Cart` fragment.",
       "variables": [],
       "fragmentRefs": [
         "Money"
       ],
-      "body": "fragment CartCost on CartCost {\n  total {\n    ...Money\n  }\n  subtotal {\n    ...Money\n  }\n  totalTax {\n    ...Money\n  }\n  totalDuty {\n    ...Money\n  }\n  checkoutCharge {\n    ...Money\n  }\n}",
+      "body": "fragment CartCost on CartCost {\n  total {\n    ...Money\n  }\n  subtotal {\n    ...Money\n  }\n  totalTax {\n    ...Money\n  }\n  totalDuty {\n    ...Money\n  }\n  checkoutCharge {\n    ...Money\n  }\n  totalDiscount {\n    ...Money\n  }\n  totalShipping {\n    ...Money\n  }\n}",
       "onType": "CartCost"
     },
     {
@@ -2113,7 +2124,7 @@
         "CartLineCost",
         "ProductVariant"
       ],
-      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n}",
+      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n  giftCardRecipient {\n    recipientEmail\n    recipientName\n    message\n  }\n}",
       "onType": "CartLine"
     },
     {
@@ -2166,7 +2177,7 @@
         "MailingAddress",
         "PageInfo"
       ],
-      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n}",
+      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n  status\n  completedOrder {\n    id\n    orderNumber\n    accessToken\n    status\n    paymentStatus\n    fulfillmentStatus\n  }\n}",
       "onType": "Cart"
     },
     {
@@ -2306,6 +2317,18 @@
       "body": "fragment Shop on Shop {\n  id\n  name\n  description\n  primaryDomain {\n    host\n    url\n    isSslEnabled\n  }\n  currencyCode\n  supportedCurrencies\n  paymentCurrencies\n  defaultLanguage\n  supportedLanguages\n  logo {\n    ...Image\n  }\n  contactEmail\n  contactPhone\n  address {\n    ...ShopAddress\n  }\n  businessHours {\n    ...BusinessHour\n  }\n  branding {\n    ...ShopBranding\n  }\n  botProtection {\n    ...BotProtection\n  }\n}",
       "onType": "Shop"
     },
+    {
+      "name": "ShopConfigFields",
+      "kind": "fragment",
+      "section": "Shop",
+      "description": "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.",
+      "variables": [],
+      "fragmentRefs": [
+        "BotProtection"
+      ],
+      "body": "fragment ShopConfigFields on Shop {\n  currencyCode\n  supportedCurrencies\n  localeToCurrencyMap {\n    locale\n    currency\n  }\n  defaultLanguage\n  supportedLanguages\n  botProtection {\n    ...BotProtection\n  }\n}",
+      "onType": "Shop"
+    },
     {
       "name": "PaymentMethod",
       "kind": "fragment",

package/package.json

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

package/queries.graphql

@@ -14,6 +14,13 @@ query Shop {
   }
 }
 
+# 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.
+query ShopConfig {
+  shop {
+    ...ShopConfigFields
+  }
+}
+
 # ============================================
 # Products
 # ============================================

package/schema.graphql

@@ -903,6 +903,11 @@ type Cart implements Node {
   """
   checkoutUrl: URL
 
+  """
+  The order that this cart converted into. Populated only when `status` is `CONVERTED` — null on every other status. Use this to render the order confirmation page (subtotals, accessToken for guest tracking) directly off the cart you already loaded, without a second `orderByToken` round-trip.
+  """
+  completedOrder: Order
+
   """
   Cost breakdown for the cart (subtotal, tax, shipping, discount, grand total).
   """
@@ -965,6 +970,11 @@ 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`.
+  """
+  status: CartStatus!
+
   """
   Sum of `quantity` across all lines — the badge number for the cart icon.
   """
@@ -1350,6 +1360,11 @@ type CartLine {
   """
   cost: CartLineCost!
 
+  """
+  Recipient details captured for a `GIFT_CARD` line via `cartUpdateGiftCardRecipient`. Null for non-gift-card lines or when no recipient has been set yet — in that case the gift card is delivered to the order `customerEmail` on completion. Use to initialise the "gift recipient" form from cart state on SSR / page reload / deep link instead of keeping it in client-only state.
+  """
+  giftCardRecipient: GiftCardLineRecipient
+
   """
   Stable line identifier. Use it to address the line in `cartUpdateLines` / `cartRemoveLines`.
   """
@@ -1664,6 +1679,17 @@ type CartShippingMethod {
   title: String!
 }
 
+"""
+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.
+"""
+enum CartStatus {
+  ABANDONED
+  ACTIVE
+  CONVERTED
+  EXPIRED
+  RECOVERED
+}
+
 """Result of `cartUpdateAttributes`."""
 type CartUpdateAttributesPayload {
   """The updated cart on success."""
@@ -3004,6 +3030,22 @@ enum GiftCardErrorCode {
   NOT_FOUND
 }
 
+"""
+Recipient details attached to a `GIFT_CARD` line — set with `cartUpdateGiftCardRecipient`. All fields are nullable individually so a partial set (e.g. email only) is representable.
+"""
+type GiftCardLineRecipient {
+  """Personalised message included with the gift card."""
+  message: String
+
+  """
+  Recipient email — where the gift card code will be delivered on order completion.
+  """
+  recipientEmail: String
+
+  """Recipient display name shown in the gift card email."""
+  recipientName: String
+}
+
 """Gift card status"""
 enum GiftCardStatus {
   ACTIVE