@doswiftly/storefront-operations 11.1.0 → 11.2.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 11.1.0
+- **Schema version**: 11.2.0
 - **Queries**: 48
 - **Mutations**: 40
 - **Fragments**: 100

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 11.2.0
+
+### Minor Changes
+
+- 760f965: Added automatic stale-cart recovery to the core SDK so every consumer (React, Vue, mobile, CLI, SSR) gets the same protection against `CART_NOT_FOUND` / `ALREADY_COMPLETED` errors without re-implementing detection, cookie cleanup, and retry orchestration.
+
+  **What's new** (importable from `@doswiftly/storefront-sdk`):
+  - `isCartRecoverableError(err)` — type-safe predicate that inspects `err.userErrors[].code` (works across PL/EN/any backend locale, unlike message string matching).
+  - `CART_RECOVERABLE_ERROR_CODES` — readonly tuple of codes that warrant cart recreation; mirrored against the backend `CartErrorCode` enum by a drift test.
+  - `executeWithCartRecovery(opts)` — pure async orchestrator for any consumer.
+  - `createCartRecoveryRunner({ cartClient, cookieStore })` — DX-friendly factory that curries the dependencies, shares a Phase-0 concurrency mutex across operations, and exposes an `onExpired(listener)` subscription for global UI feedback.
+  - `CartCookieStore` — port interface (`get` / `set` / `clear`) the caller implements once per runtime. From `@doswiftly/storefront-sdk/react` we now also export `createBrowserCartCookieStore()` (SSR-safe).
+  - `CartRecoveryNotPossibleError` — thrown when an operation cannot be safely replayed (line-id / shipping-method references the dead cart). Carries `reason: 'state-dependent' | 'recreate-failed' | 'retry-also-failed'` for diagnostic UX.
+  - `recreateWithInput(input)` / `recreateWithLines(lines)` — sugar helpers for the most common atomic `cartCreate(payload)` recovery strategies.
+
+  **Per-operation taxonomy (decision is in the SDK, not in caller code):**
+
+  | Operation                                                                                    | Strategy                                                                                                                                         |
+  | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | `addItems`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` | Auto-replay via a single atomic `cartCreate(input)` — recovery is invisible to the caller                                                        |
+  | `updateItems`, `removeItems`                                                                 | Bail with `CartRecoveryNotPossibleError` and emit a `cart-expired` event — replaying on a fresh empty cart would silently lose the user's intent |
+
+  **React updates:**
+  - `useCartManager` now uses the recovery runner internally. Detection is code-based (no more PL/EN regression — previous implementation matched `'cart not found'` in the error message, which never matched a Polish backend response). Recovery now covers all mutations exposed by the hook, not just `addItem`. New methods: `updateBuyerIdentity`, `setShippingAddress`. New API: `onExpired(listener)` returning an unsubscribe function.
+  - `createCartStore` now recovers `addToCart` automatically. New optional `CartActions.createCartWithLines(lines)` lets templates wire the atomic single-round-trip path; without it the store falls back to `createCart()` + `addLines()`. `updateQuantity` and `removeFromCart` bail with the `cart-expired` event when the cart is gone (previously the store kept its local id pointing at a dead cart). `CartStoreConfig.onExpired?(event)` lets the consumer subscribe.
+
+  **Migration:**
+  - No required code changes for existing React consumers — `useCartManager` and `createCartStore` keep their public surface.
+  - If you previously caught `StorefrontError` to detect stale carts via message string matching, switch to `isCartRecoverableError(err)` (code-based, locale-proof) or — preferably — subscribe to `runner.onExpired(...)` / `useCartManager().onExpired(...)` / `createCartStore({ onExpired })`.
+  - Non-React consumers should wrap their cart mutations in `createCartRecoveryRunner` and implement a `CartCookieStore` adapter for their environment (browser via `createBrowserCartCookieStore()`, server-side via `next/headers`, CLI via in-memory `Map`, mobile via AsyncStorage).
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
 ## 11.1.0
 
 ### Minor Changes

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **11.1.0**
+> Schema version: **11.2.0**
 > 48 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "11.1.0",
+  "schemaVersion": "11.2.0",
   "queries": [
     {
       "name": "Shop",

package/package.json

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