@doswiftly/storefront-sdk 11.0.0 → 11.2.0

package/dist/react/stores/cart.store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart.store.d.ts","sourceRoot":"","sources":["../../../src/react/stores/cart.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAKhF,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAMhF,gDAAgD;AAChD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACxD,iDAAiD;IACjD,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,oDAAoD;IACpD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxE,4DAA4D;IAC5D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjF,uDAAuD;IACvD,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvE;AAMD,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAEhG,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,UAAU,EAAE,MAAM,WAAW,CAAC;IAC9B,wCAAwC;IACxC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACzE,gCAAgC;IAChC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACxE;AAMD,MAAM,WAAW,SAAS;IAExB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAGtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,IAAI,CAAC;IAGvB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,cAAc,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAMD,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,kBAAiB,CAAC;AAC/D,eAAO,MAAM,gBAAgB,GAAI,OAAO,SAAS,YAAiB,CAAC;AACnE,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,YAAoB,CAAC;AAMzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,yCAkJtD"}
+{"version":3,"file":"cart.store.d.ts","sourceRoot":"","sources":["../../../src/react/stores/cart.store.ts"],"names":[],"mappings":"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"}

package/dist/react/stores/cart.store.js

@@ -1,27 +1,49 @@
 /**
- * Cart Store — DI-based cart state management with cookie persistence.
+ * Cart Store — DI-based cart state management with cookie persistence and
+ * automatic stale-cart recovery.
  *
- * SDK orchestrates cart lifecycle (init, mutations, error handling).
- * Template provides CartActions implementation via DI (getActions getter).
- * Cart ID persisted in cookie (SSR/edge visible) — follows currency store pattern.
+ * SDK orchestrates cart lifecycle (init, mutations, recovery, error handling).
+ * Template provides `CartActions` via DI (getActions getter). Cart id persisted
+ * in cookie (SSR/edge visible) — follows currency store pattern.
+ *
+ * Per-operation recovery strategy (DX-first — caller never thinks about it):
+ *
+ *   - **`addToCart`** auto-replays on stale-cart errors. If the template
+ *     implements the optional `actions.createCartWithLines`, recovery is atomic
+ *     (single `cartCreate({ lines })` round trip). Otherwise falls back to
+ *     `createCart()` + `addLines()` (2 round trips, same end result).
+ *
+ *   - **`updateQuantity`** and **`removeFromCart`** bail on stale-cart errors:
+ *     local cart id is cleared, `onExpired` listeners fire, error surfaces via
+ *     `onMutationError`. Replaying on a fresh empty cart would silently lose
+ *     user intent (the lineId no longer exists).
+ *
+ * Stale-cart detection inspects `err.userErrors[].code` (CART_NOT_FOUND /
+ * ALREADY_COMPLETED) — locale-proof, see {@link isCartRecoverableError}.
  *
  * @example
  * ```typescript
  * import { createCartStore, type CartActions } from '@doswiftly/storefront-sdk/react';
  *
  * const actions: CartActions = {
- *   fetchCart: async (cartId) => api.getCart(cartId),
- *   createCart: async () => api.createCart().then(c => c.id),
- *   addLines: async (cartId, lines) => api.addLines(cartId, lines),
- *   updateLines: async (cartId, lines) => api.updateLines(cartId, lines),
- *   removeLines: async (cartId, lineIds) => api.removeLines(cartId, lineIds),
+ *   fetchCart: (id) => api.getCart(id),
+ *   createCart: () => api.createCart().then(c => c.id),
+ *   addLines: (id, lines) => api.addLines(id, lines),
+ *   updateLines: (id, lines) => api.updateLines(id, lines),
+ *   removeLines: (id, ids) => api.removeLines(id, ids),
+ *   // optional — enables atomic add-to-cart recovery
+ *   createCartWithLines: (lines) => api.cartCreate({ lines }),
  * };
  *
- * const store = createCartStore({ getActions: () => actions });
+ * const store = createCartStore({
+ *   getActions: () => actions,
+ *   onExpired: (e) => toast.error('Koszyk wygasł, dodaj produkty ponownie'),
+ * });
  * ```
  */
 import { createStore } from 'zustand/vanilla';
 import { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from '../../core/cart/cookie-config';
+import { isCartRecoverableError, } from '../../core/cart/cart-recovery';
 import { getCookie, setCookie, deleteCookie } from '../cookies';
 // ---------------------------------------------------------------------------
 // Selectors
@@ -33,7 +55,10 @@ export const selectCartIsLoading = (state) => state.isLoading;
 // Factory
 // ---------------------------------------------------------------------------
 export function createCartStore(config) {
-    // Deduplication: shared Promise in closure (not in state)
+    // Deduplication for initCart only — first-create collision is the common
+    // case (multiple components mounting and seeing an empty cookie). Recovery
+    // recreates are NOT deduplicated: each carries its own lines payload and
+    // merging would silently drop the second caller's intent.
     let initPromise = null;
     // Read initial cartId from cookie (client-side only, returns null on server)
     const initialCartId = getCookie(CART_COOKIE_NAME);
@@ -44,6 +69,25 @@ export function createCartStore(config) {
         }
         catch { /* ignore */ }
     }
+    function emitExpired(event) {
+        if (!config.onExpired)
+            return;
+        try {
+            config.onExpired(event);
+        }
+        catch {
+            // Listener must not break recovery flow.
+        }
+    }
+    async function recreateWithLines(lines) {
+        const actions = config.getActions();
+        if (actions.createCartWithLines) {
+            return actions.createCartWithLines(lines);
+        }
+        // Fallback: two-step (create empty cart, then add lines)
+        const newCartId = await actions.createCart();
+        return actions.addLines(newCartId, lines);
+    }
     async function performInit(set, get) {
         const actions = config.getActions();
         set({ isLoading: true, error: null });
@@ -86,11 +130,12 @@ export function createCartStore(config) {
             });
             return initPromise;
         },
-        // Orchestrated: addToCart (auto-init if no cartId)
+        // Orchestrated: addToCart — auto-replay on stale cart.
         addToCart: async (lines) => {
             const actions = config.getActions();
             set({ isLoading: true, error: null });
             try {
+                // Phase 0 — ensure cart exists.
                 let cartId = get().cartId;
                 if (!cartId) {
                     await get().initCart();
@@ -99,16 +144,45 @@ export function createCartStore(config) {
                 if (!cartId) {
                     throw new Error('Failed to initialize cart');
                 }
-                const cart = await actions.addLines(cartId, lines);
-                set({ isLoading: false, error: null });
-                config.onMutationSuccess?.('addToCart', cart);
+                // Phase 1 — happy path.
+                try {
+                    const cart = await actions.addLines(cartId, lines);
+                    set({ isLoading: false, error: null });
+                    config.onMutationSuccess?.('addToCart', cart);
+                    return;
+                }
+                catch (err) {
+                    if (!isCartRecoverableError(err))
+                        throw err;
+                    // Phase 2 — auto-replay against a fresh cart.
+                    const oldCartId = cartId;
+                    try {
+                        const cart = await recreateWithLines(lines);
+                        set({ cartId: cart.id, isLoading: false, error: null });
+                        config.onMutationSuccess?.('addToCart', cart);
+                    }
+                    catch (recoverErr) {
+                        const reason = isCartRecoverableError(recoverErr)
+                            ? 'retry-also-failed'
+                            : 'recreate-failed';
+                        // Clear local cart id so next interaction starts clean.
+                        set({ cartId: null, isLoading: false, error: recoverErr });
+                        config.onMutationError?.('addToCart', recoverErr);
+                        emitExpired({
+                            reason,
+                            oldCartId,
+                            operation: 'addToCart',
+                            cause: recoverErr,
+                        });
+                    }
+                }
             }
             catch (error) {
                 set({ error, isLoading: false });
                 config.onMutationError?.('addToCart', error);
             }
         },
-        // Orchestrated: updateQuantity (error if no cartId)
+        // Orchestrated: updateQuantity — bail on stale cart (lineId is dead).
         updateQuantity: async (lines) => {
             const actions = config.getActions();
             const cartId = get().cartId;
@@ -125,11 +199,24 @@ export function createCartStore(config) {
                 config.onMutationSuccess?.('updateQuantity', cart);
             }
             catch (error) {
+                if (isCartRecoverableError(error)) {
+                    // Clear local cart — replaying on a fresh cart would lose the user's
+                    // intent (the lineId no longer exists).
+                    set({ cartId: null, isLoading: false, error });
+                    config.onMutationError?.('updateQuantity', error);
+                    emitExpired({
+                        reason: 'state-dependent',
+                        oldCartId: cartId,
+                        operation: 'updateQuantity',
+                        cause: error,
+                    });
+                    return;
+                }
                 set({ error, isLoading: false });
                 config.onMutationError?.('updateQuantity', error);
             }
         },
-        // Orchestrated: removeFromCart (silent return if no cartId)
+        // Orchestrated: removeFromCart — bail on stale cart (lineId is dead).
         removeFromCart: async (lineIds) => {
             const cartId = get().cartId;
             if (!cartId)
@@ -142,6 +229,17 @@ export function createCartStore(config) {
                 config.onMutationSuccess?.('removeFromCart', cart);
             }
             catch (error) {
+                if (isCartRecoverableError(error)) {
+                    set({ cartId: null, isLoading: false, error });
+                    config.onMutationError?.('removeFromCart', error);
+                    emitExpired({
+                        reason: 'state-dependent',
+                        oldCartId: cartId,
+                        operation: 'removeFromCart',
+                        cause: error,
+                    });
+                    return;
+                }
                 set({ error, isLoading: false });
                 config.onMutationError?.('removeFromCart', error);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "11.0.0",
+  "version": "11.2.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "files": [
@@ -39,16 +39,19 @@
   ],
   "author": "DoSwiftly Team",
   "license": "MIT",
-  "dependencies": {},
   "devDependencies": {
+    "@testing-library/react": "^16.1.0",
     "@types/node": "^22.10.2",
     "@types/react": "^18.3.0 || ^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "fast-check": "^3.23.2",
+    "jsdom": "^25.0.1",
     "next": "^16.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.0",
-    "zustand": "^5.0.2",
-    "react": "^19.0.0"
+    "zustand": "^5.0.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",