@doswiftly/storefront-sdk 11.1.0 → 11.3.1

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,16 +55,31 @@ 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);
-    // Clean up old localStorage entry from pre-cookie era (v1 persist)
-    if (typeof localStorage !== 'undefined') {
+    function emitExpired(event) {
+        if (!config.onExpired)
+            return;
         try {
-            localStorage.removeItem('cart-storage');
+            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);
         }
-        catch { /* ignore */ }
+        // 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();
@@ -86,11 +123,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 +137,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 +192,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 +222,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/dist/react/stores/store-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-context.d.ts","sourceRoot":"","sources":["../../../src/react/stores/store-context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMtD,eAAO,MAAM,gBAAgB,qDAAkD,CAAC;AAChF,eAAO,MAAM,oBAAoB,yDAAsD,CAAC;AACxF,eAAO,MAAM,oBAAoB,yDAAsD,CAAC;AAMxF,wBAAgB,YAAY,IAAI,SAAS,CAAC;AAC1C,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,CAAC,GAAG,CAAC,CAAC;AAQlE,wBAAgB,eAAe,IAAI,QAAQ,CAAC,SAAS,CAAC,CAIrD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAczC;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,CAAC;AAClD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAAC;AAQ1E,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAI7D;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,CAAC;AAClD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAAC;AAQ1E,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAI7D"}
+{"version":3,"file":"store-context.d.ts","sourceRoot":"","sources":["../../../src/react/stores/store-context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMtD,eAAO,MAAM,gBAAgB,qDAAkD,CAAC;AAChF,eAAO,MAAM,oBAAoB,yDAAsD,CAAC;AACxF,eAAO,MAAM,oBAAoB,yDAAsD,CAAC;AAMxF,wBAAgB,YAAY,IAAI,SAAS,CAAC;AAC1C,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,CAAC,GAAG,CAAC,CAAC;AAQlE,wBAAgB,eAAe,IAAI,QAAQ,CAAC,SAAS,CAAC,CAIrD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAoBzC;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,CAAC;AAClD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAAC;AAQ1E,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAI7D;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,CAAC;AAClD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAAC;AAQ1E,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAI7D"}

package/dist/react/stores/store-context.js

@@ -39,9 +39,7 @@ export function useAuthHydrated() {
     const [hydrated, setHydrated] = useState(false);
     useEffect(() => {
         const persistApi = store.persist;
-        // Subscribe to future hydration completions
         const unsubFinish = persistApi.onFinishHydration(() => setHydrated(true));
-        // Check if hydration already completed before effect ran
         if (persistApi.hasHydrated())
             setHydrated(true);
         return unsubFinish;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "11.1.0",
+  "version": "11.3.1",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
+  "sideEffects": false,
   "files": [
     "dist",
     "README.md",
@@ -39,16 +40,20 @@
   ],
   "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",
+    "@vitest/coverage-v8": "^4.1.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",
@@ -71,6 +76,8 @@
     "test:watch": "vitest",
     "test:unit": "vitest run src/__tests__/unit/",
     "test:contract": "vitest run src/__tests__/contract/",
+    "test:coverage": "vitest run --coverage",
+    "doctor": "node scripts/doctor.cjs",
     "validate:cart": "node scripts/validate-cart-operations.cjs --strict"
   }
 }

package/dist/__tests__/unit/test-helpers.d.ts

@@ -1,46 +0,0 @@
-/**
- * Shared test helpers — mock fetch factory, mock client builder.
- */
-/**
- * Create a mock fetch that returns the specified GraphQL response.
- */
-export declare function createMockFetch(responseData: unknown, options?: {
-    errors?: Array<{
-        message: string;
-    }>;
-    status?: number;
-    delay?: number;
-}): typeof globalThis.fetch;
-/**
- * Create a mock fetch that tracks all calls and returns specified response.
- */
-export declare function createSpyFetch(responseData: unknown, options?: {
-    errors?: Array<{
-        message: string;
-    }>;
-    status?: number;
-}): {
-    fetch: typeof globalThis.fetch;
-    calls: {
-        url: string;
-        init: RequestInit;
-    }[];
-};
-/**
- * Create a mock fetch that fails with a network error.
- */
-export declare function createNetworkErrorFetch(errorMessage?: string): typeof globalThis.fetch;
-/**
- * Create a mock fetch that returns different responses on subsequent calls.
- */
-export declare function createSequenceFetch(responses: Array<{
-    data?: unknown;
-    errors?: Array<{
-        message: string;
-    }>;
-    status?: number;
-}>): {
-    fetch: typeof globalThis.fetch;
-    callCount: () => number;
-};
-//# sourceMappingURL=test-helpers.d.ts.map

package/dist/__tests__/unit/test-helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/test-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,UAAU,CAAC,KAAK,CAqBzB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;WAqB0B,OAAO,UAAU,CAAC,KAAK;;aAnBxB,MAAM;cAAQ,WAAW;;EAoBpD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,SAAiB,GAAG,OAAO,UAAU,CAAC,KAAK,CAI9F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACzF;IAAE,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,MAAM,CAAA;CAAE,CAiB7D"}

package/dist/__tests__/unit/test-helpers.js

@@ -1,72 +0,0 @@
-/**
- * Shared test helpers — mock fetch factory, mock client builder.
- */
-/**
- * Create a mock fetch that returns the specified GraphQL response.
- */
-export function createMockFetch(responseData, options) {
-    const { errors, status = 200, delay: delayMs } = options ?? {};
-    return async (_url, _init) => {
-        if (delayMs) {
-            await new Promise(r => setTimeout(r, delayMs));
-        }
-        // Check for abort signal
-        if (_init?.signal?.aborted) {
-            throw new DOMException('The operation was aborted', 'AbortError');
-        }
-        const body = { data: responseData };
-        if (errors)
-            body.errors = errors;
-        return new Response(JSON.stringify(body), {
-            status,
-            headers: { 'Content-Type': 'application/json' },
-        });
-    };
-}
-/**
- * Create a mock fetch that tracks all calls and returns specified response.
- */
-export function createSpyFetch(responseData, options) {
-    const calls = [];
-    const { errors, status = 200 } = options ?? {};
-    const fetchFn = async (url, init) => {
-        calls.push({ url: url.toString(), init: init });
-        if (init?.signal?.aborted) {
-            throw new DOMException('The operation was aborted', 'AbortError');
-        }
-        const body = { data: responseData };
-        if (errors)
-            body.errors = errors;
-        return new Response(JSON.stringify(body), {
-            status,
-            headers: { 'Content-Type': 'application/json' },
-        });
-    };
-    return { fetch: fetchFn, calls };
-}
-/**
- * Create a mock fetch that fails with a network error.
- */
-export function createNetworkErrorFetch(errorMessage = 'fetch failed') {
-    return async () => {
-        throw new TypeError(errorMessage);
-    };
-}
-/**
- * Create a mock fetch that returns different responses on subsequent calls.
- */
-export function createSequenceFetch(responses) {
-    let index = 0;
-    const fetchFn = async (_url, _init) => {
-        const response = responses[Math.min(index, responses.length - 1)];
-        index++;
-        const body = { data: response.data ?? null };
-        if (response.errors)
-            body.errors = response.errors;
-        return new Response(JSON.stringify(body), {
-            status: response.status ?? 200,
-            headers: { 'Content-Type': 'application/json' },
-        });
-    };
-    return { fetch: fetchFn, callCount: () => index };
-}