@doswiftly/storefront-sdk 4.0.0 → 4.2.0

package/src/__tests__/unit/cart-store.test.ts

@@ -0,0 +1,349 @@
+/**
+ * Unit tests for createCartStore — DI-based cart state management.
+ *
+ * Tests factory creation, cookie persistence, UI actions, initCart orchestration
+ * (including deduplication), mutations, callbacks, and error handling.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createCartStore, type CartActions, type CartData } from '../../react/stores/cart.store';
+
+// Mock cookies module
+vi.mock('../../react/cookies', () => ({
+  getCookie: vi.fn(() => null),
+  setCookie: vi.fn(),
+  deleteCookie: vi.fn(),
+}));
+
+import { getCookie, setCookie, deleteCookie } from '../../react/cookies';
+const mockGetCookie = vi.mocked(getCookie);
+const mockSetCookie = vi.mocked(setCookie);
+const mockDeleteCookie = vi.mocked(deleteCookie);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMockActions(overrides?: Partial<CartActions>): CartActions {
+  return {
+    fetchCart: vi.fn(async () => ({ id: 'cart-1', totalQuantity: 1 })),
+    createCart: vi.fn(async () => 'new-cart-id'),
+    addLines: vi.fn(async () => ({ id: 'cart-1', totalQuantity: 2 })),
+    updateLines: vi.fn(async () => ({ id: 'cart-1', totalQuantity: 3 })),
+    removeLines: vi.fn(async () => ({ id: 'cart-1', totalQuantity: 0 })),
+    ...overrides,
+  };
+}
+
+function createTestStore(
+  actions?: CartActions,
+  options?: {
+    onMutationSuccess?: (action: string, cart: CartData) => void;
+    onMutationError?: (action: string, error: unknown) => void;
+  },
+) {
+  const mockActions = actions ?? createMockActions();
+  return {
+    store: createCartStore({
+      getActions: () => mockActions,
+      onMutationSuccess: options?.onMutationSuccess,
+      onMutationError: options?.onMutationError,
+    }),
+    actions: mockActions,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Task 3.1: Factory, cookie persistence, UI actions
+// ---------------------------------------------------------------------------
+
+describe('createCartStore — factory & UI actions', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create a valid store instance with initial state', () => {
+    const { store } = createTestStore();
+    const state = store.getState();
+
+    expect(state.cartId).toBeNull();
+    expect(state.isOpen).toBe(false);
+    expect(state.isLoading).toBe(false);
+    expect(state.error).toBeNull();
+  });
+
+  it('should read initial cartId from cookie', () => {
+    mockGetCookie.mockReturnValueOnce('existing-cart-from-cookie');
+    const actions = createMockActions();
+    const store = createCartStore({ getActions: () => actions });
+
+    expect(store.getState().cartId).toBe('existing-cart-from-cookie');
+    expect(mockGetCookie).toHaveBeenCalledWith('cart-id');
+  });
+
+  it('should write cartId to cookie when set', () => {
+    const { store } = createTestStore();
+
+    store.setState({ cartId: 'new-cart' });
+
+    expect(mockSetCookie).toHaveBeenCalledWith('cart-id', 'new-cart', { maxAge: 30 * 24 * 60 * 60 });
+  });
+
+  it('should delete cookie when cartId cleared', () => {
+    const { store } = createTestStore();
+    store.setState({ cartId: 'to-clear' });
+    vi.clearAllMocks();
+
+    store.getState().clearCart();
+
+    expect(mockDeleteCookie).toHaveBeenCalledWith('cart-id');
+    expect(store.getState().cartId).toBeNull();
+  });
+
+  it('openCart should set isOpen to true', () => {
+    const { store } = createTestStore();
+    store.getState().openCart();
+    expect(store.getState().isOpen).toBe(true);
+  });
+
+  it('closeCart should set isOpen to false', () => {
+    const { store } = createTestStore();
+    store.getState().openCart();
+    store.getState().closeCart();
+    expect(store.getState().isOpen).toBe(false);
+  });
+
+  it('toggleCart should flip isOpen', () => {
+    const { store } = createTestStore();
+    expect(store.getState().isOpen).toBe(false);
+    store.getState().toggleCart();
+    expect(store.getState().isOpen).toBe(true);
+    store.getState().toggleCart();
+    expect(store.getState().isOpen).toBe(false);
+  });
+
+  it('clearCart should reset all state', () => {
+    const { store } = createTestStore();
+    store.setState({ cartId: 'cart-1', isOpen: true, isLoading: true, error: new Error('err') });
+
+    store.getState().clearCart();
+
+    const state = store.getState();
+    expect(state.cartId).toBeNull();
+    expect(state.isOpen).toBe(false);
+    expect(state.isLoading).toBe(false);
+    expect(state.error).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task 3.2: initCart orchestration
+// ---------------------------------------------------------------------------
+
+describe('createCartStore — initCart orchestration', () => {
+  afterEach(() => { vi.clearAllMocks(); });
+
+  it('should fetch existing cart when cartId is set', async () => {
+    const actions = createMockActions({
+      fetchCart: vi.fn(async () => ({ id: 'existing-cart', totalQuantity: 5 })),
+    });
+    const { store } = createTestStore(actions);
+    store.setState({ cartId: 'existing-cart' });
+
+    await store.getState().initCart();
+
+    expect(actions.fetchCart).toHaveBeenCalledWith('existing-cart');
+    expect(actions.createCart).not.toHaveBeenCalled();
+    expect(store.getState().cartId).toBe('existing-cart');
+    expect(store.getState().isLoading).toBe(false);
+  });
+
+  it('should create new cart when fetchCart returns null (expired)', async () => {
+    const actions = createMockActions({
+      fetchCart: vi.fn(async () => null),
+      createCart: vi.fn(async () => 'brand-new-cart'),
+    });
+    const { store } = createTestStore(actions);
+    store.setState({ cartId: 'expired-cart' });
+
+    await store.getState().initCart();
+
+    expect(actions.fetchCart).toHaveBeenCalledWith('expired-cart');
+    expect(actions.createCart).toHaveBeenCalled();
+    expect(store.getState().cartId).toBe('brand-new-cart');
+    expect(store.getState().isLoading).toBe(false);
+  });
+
+  it('should create new cart when cartId is null', async () => {
+    const actions = createMockActions({
+      createCart: vi.fn(async () => 'fresh-cart'),
+    });
+    const { store } = createTestStore(actions);
+
+    await store.getState().initCart();
+
+    expect(actions.fetchCart).not.toHaveBeenCalled();
+    expect(actions.createCart).toHaveBeenCalled();
+    expect(store.getState().cartId).toBe('fresh-cart');
+  });
+
+  it('should deduplicate concurrent initCart calls', async () => {
+    let resolveCreate: (value: string) => void;
+    const createPromise = new Promise<string>((resolve) => {
+      resolveCreate = resolve;
+    });
+
+    const actions = createMockActions({
+      createCart: vi.fn(() => createPromise),
+    });
+    const { store } = createTestStore(actions);
+
+    // Fire two concurrent initCart calls
+    const p1 = store.getState().initCart();
+    const p2 = store.getState().initCart();
+
+    // Resolve
+    resolveCreate!('deduped-cart');
+    await Promise.all([p1, p2]);
+
+    // createCart should be called only once
+    expect(actions.createCart).toHaveBeenCalledTimes(1);
+    expect(store.getState().cartId).toBe('deduped-cart');
+  });
+
+  it('should set error and call onMutationError on initCart failure', async () => {
+    const err = new Error('Network error');
+    const actions = createMockActions({
+      createCart: vi.fn(async () => { throw err; }),
+    });
+    const onMutationError = vi.fn();
+    const { store } = createTestStore(actions, { onMutationError });
+
+    await store.getState().initCart();
+
+    expect(store.getState().error).toBe(err);
+    expect(store.getState().isLoading).toBe(false);
+    expect(onMutationError).toHaveBeenCalledWith('initCart', err);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task 3.3: Mutations and callbacks
+// ---------------------------------------------------------------------------
+
+describe('createCartStore — mutations', () => {
+  afterEach(() => { vi.clearAllMocks(); });
+
+  it('addToCart with existing cartId should call addLines', async () => {
+    const cartData: CartData = { id: 'cart-1', totalQuantity: 2 };
+    const actions = createMockActions({
+      addLines: vi.fn(async () => cartData),
+    });
+    const onMutationSuccess = vi.fn();
+    const { store } = createTestStore(actions, { onMutationSuccess });
+    store.setState({ cartId: 'cart-1' });
+
+    await store.getState().addToCart([{ merchandiseId: 'var-1', quantity: 1 }]);
+
+    expect(actions.addLines).toHaveBeenCalledWith('cart-1', [{ merchandiseId: 'var-1', quantity: 1 }]);
+    expect(onMutationSuccess).toHaveBeenCalledWith('addToCart', cartData);
+    expect(store.getState().isLoading).toBe(false);
+  });
+
+  it('addToCart without cartId should auto-init then addLines', async () => {
+    const actions = createMockActions({
+      createCart: vi.fn(async () => 'auto-cart'),
+      addLines: vi.fn(async () => ({ id: 'auto-cart', totalQuantity: 1 })),
+    });
+    const { store } = createTestStore(actions);
+
+    await store.getState().addToCart([{ merchandiseId: 'var-1' }]);
+
+    expect(actions.createCart).toHaveBeenCalled();
+    expect(actions.addLines).toHaveBeenCalledWith('auto-cart', [{ merchandiseId: 'var-1' }]);
+    expect(store.getState().cartId).toBe('auto-cart');
+  });
+
+  it('updateQuantity should call updateLines with correct args', async () => {
+    const cartData: CartData = { id: 'cart-1', totalQuantity: 3 };
+    const actions = createMockActions({
+      updateLines: vi.fn(async () => cartData),
+    });
+    const onMutationSuccess = vi.fn();
+    const { store } = createTestStore(actions, { onMutationSuccess });
+    store.setState({ cartId: 'cart-1' });
+
+    await store.getState().updateQuantity([{ id: 'line-1', quantity: 5 }]);
+
+    expect(actions.updateLines).toHaveBeenCalledWith('cart-1', [{ id: 'line-1', quantity: 5 }]);
+    expect(onMutationSuccess).toHaveBeenCalledWith('updateQuantity', cartData);
+  });
+
+  it('updateQuantity without cartId should set error', async () => {
+    const onMutationError = vi.fn();
+    const { store, actions } = createTestStore(undefined, { onMutationError });
+
+    await store.getState().updateQuantity([{ id: 'line-1', quantity: 5 }]);
+
+    expect(actions.updateLines).not.toHaveBeenCalled();
+    expect(store.getState().error).toBeInstanceOf(Error);
+    expect(onMutationError).toHaveBeenCalledWith('updateQuantity', expect.any(Error));
+  });
+
+  it('removeFromCart should call removeLines with correct args', async () => {
+    const cartData: CartData = { id: 'cart-1', totalQuantity: 0 };
+    const actions = createMockActions({
+      removeLines: vi.fn(async () => cartData),
+    });
+    const onMutationSuccess = vi.fn();
+    const { store } = createTestStore(actions, { onMutationSuccess });
+    store.setState({ cartId: 'cart-1' });
+
+    await store.getState().removeFromCart(['line-1']);
+
+    expect(actions.removeLines).toHaveBeenCalledWith('cart-1', ['line-1']);
+    expect(onMutationSuccess).toHaveBeenCalledWith('removeFromCart', cartData);
+  });
+
+  it('removeFromCart without cartId should silently return', async () => {
+    const { store, actions } = createTestStore();
+
+    await store.getState().removeFromCart(['line-1']);
+
+    expect(actions.removeLines).not.toHaveBeenCalled();
+    expect(store.getState().isLoading).toBe(false);
+  });
+
+  it('should set error state and call onMutationError on DI failure', async () => {
+    const err = new Error('GraphQL error');
+    const actions = createMockActions({
+      addLines: vi.fn(async () => { throw err; }),
+    });
+    const onMutationError = vi.fn();
+    const { store } = createTestStore(actions, { onMutationError });
+    store.setState({ cartId: 'cart-1' });
+
+    await store.getState().addToCart([{ merchandiseId: 'var-1' }]);
+
+    expect(store.getState().error).toBe(err);
+    expect(store.getState().isLoading).toBe(false);
+    expect(onMutationError).toHaveBeenCalledWith('addToCart', err);
+  });
+
+  it('should call getActions on every operation (freshness)', async () => {
+    const actions = createMockActions();
+    const getActions = vi.fn(() => actions);
+    const store = createCartStore({
+      getActions,
+      onMutationSuccess: vi.fn(),
+    });
+    store.setState({ cartId: 'cart-1' });
+
+    await store.getState().addToCart([{ merchandiseId: 'v1' }]);
+    await store.getState().updateQuantity([{ id: 'l1', quantity: 2 }]);
+    await store.getState().removeFromCart(['l1']);
+
+    // getActions called at least once per operation
+    expect(getActions.mock.calls.length).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/core/bot-protection/abstract-manager.ts

@@ -0,0 +1,185 @@
+/**
+ * AbstractBotProtectionManager — base class for all bot protection providers.
+ *
+ * DRY: singleton script loading, lazy mount, in-flight deduplication, timeout.
+ * Subclasses override only: _loadScript(), _renderWidget(), _executeChallenge(), _destroyWidget().
+ *
+ * Framework-agnostic (DOM APIs only) — works in React, Vue, Svelte, vanilla JS.
+ */
+
+import type { BotProtectionTokenProvider } from '../middleware/bot-protection';
+
+export abstract class AbstractBotProtectionManager implements BotProtectionTokenProvider {
+  protected readonly siteKey: string;
+  protected readonly scriptUrl: string;
+
+  /** Singleton script loading promise — one load per provider globally */
+  private scriptPromise: Promise<void> | null = null;
+  /** In-flight deduplication — prevents double-submit */
+  private inFlight: Promise<string | null> | null = null;
+  /** Whether the widget has been mounted */
+  protected widgetId: string | null = null;
+  /** Container element for the widget */
+  protected container: HTMLElement | null = null;
+
+  constructor(siteKey: string, scriptUrl: string) {
+    this.siteKey = siteKey;
+    this.scriptUrl = scriptUrl;
+  }
+
+  /**
+   * Load the provider's script tag. Singleton — only loads once.
+   * Exposed publicly so React wrapper can trigger preload.
+   */
+  loadScript(): Promise<void> {
+    if (this.scriptPromise) return this.scriptPromise;
+
+    this.scriptPromise = new Promise<void>((resolve, reject) => {
+      // Skip in SSR
+      if (typeof document === 'undefined') {
+        resolve();
+        return;
+      }
+
+      // Check if script already exists
+      const existing = document.querySelector(`script[src="${this.scriptUrl}"]`);
+      if (existing) {
+        // Script tag exists — wait for API to be available
+        this._waitForApi().then(resolve).catch(reject);
+        return;
+      }
+
+      const script = document.createElement('script');
+      script.src = this.scriptUrl;
+      script.async = true;
+      script.defer = true;
+
+      // Set up onload callback if provider supports it
+      this._setupOnloadCallback(resolve);
+
+      script.onload = () => {
+        this._waitForApi().then(resolve).catch(reject);
+      };
+
+      script.onerror = () => {
+        this.scriptPromise = null; // Allow retry
+        reject(new Error(`Failed to load bot protection script: ${this.scriptUrl}`));
+      };
+
+      document.head.appendChild(script);
+    });
+
+    return this.scriptPromise;
+  }
+
+  /**
+   * Mount the invisible widget into a container element.
+   * Lazy — called automatically on first execute() if not mounted.
+   */
+  mount(container: HTMLElement): void {
+    this.container = container;
+  }
+
+  /**
+   * Execute challenge and get a fresh token.
+   * In-flight dedup + timeout + lazy mount + lazy script load.
+   */
+  async execute(options?: { action?: string; timeoutMs?: number }): Promise<string | null> {
+    // In-flight deduplication — return existing promise if one is running
+    if (this.inFlight) return this.inFlight;
+
+    const timeoutMs = options?.timeoutMs ?? 10000;
+
+    this.inFlight = this._doExecute(options?.action, timeoutMs).finally(() => {
+      this.inFlight = null;
+    });
+
+    return this.inFlight;
+  }
+
+  /**
+   * Cleanup widget and resources.
+   */
+  destroy(): void {
+    try {
+      if (this.widgetId) {
+        this._destroyWidget(this.widgetId);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    this.widgetId = null;
+    this.container = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private execution pipeline
+  // ---------------------------------------------------------------------------
+
+  private async _doExecute(action: string | undefined, timeoutMs: number): Promise<string | null> {
+    try {
+      // 1. Lazy script load
+      await this.loadScript();
+
+      // 2. Lazy mount — create container if needed
+      if (!this.widgetId) {
+        await this._ensureMounted(action);
+      }
+
+      if (!this.widgetId) {
+        return null; // Mount failed — fail-open
+      }
+
+      // 3. Execute challenge with timeout
+      const tokenPromise = this._executeChallenge(this.widgetId, action);
+
+      const timeoutPromise = new Promise<null>((resolve) => {
+        setTimeout(() => resolve(null), timeoutMs);
+      });
+
+      return await Promise.race([tokenPromise, timeoutPromise]);
+    } catch {
+      // Any error → return null (fail-open at middleware level)
+      return null;
+    }
+  }
+
+  private async _ensureMounted(action?: string): Promise<void> {
+    // Create an invisible container if none provided
+    if (!this.container && typeof document !== 'undefined') {
+      this.container = document.createElement('div');
+      this.container.style.display = 'none';
+      this.container.setAttribute('data-bot-protection', 'true');
+      document.body.appendChild(this.container);
+    }
+
+    if (!this.container) return;
+
+    try {
+      this.widgetId = this._renderWidget(this.container, action);
+    } catch {
+      this.widgetId = null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Abstract methods — subclass responsibility
+  // ---------------------------------------------------------------------------
+
+  /** Wait for the provider API to be available on window */
+  protected abstract _waitForApi(): Promise<void>;
+
+  /** Optional: setup global onload callback for the script */
+  protected _setupOnloadCallback(_resolve: () => void): void {
+    // Default: no-op. Override if provider uses a callback pattern.
+  }
+
+  /** Render the invisible widget. Return widget ID. */
+  protected abstract _renderWidget(container: HTMLElement, action?: string): string;
+
+  /** Execute the challenge and return a token. Called after mount. */
+  protected abstract _executeChallenge(widgetId: string, action?: string): Promise<string | null>;
+
+  /** Destroy/remove the widget. */
+  protected abstract _destroyWidget(widgetId: string): void;
+}

package/src/core/bot-protection/create-manager.ts

@@ -0,0 +1,37 @@
+/**
+ * Bot protection manager factory.
+ *
+ * Creates the appropriate manager based on provider config from shop query.
+ * Supports runtime fallback chain via FallbackBotProtectionManager.
+ */
+
+import type { BotProtectionTokenProvider, BotProtectionConfig, BotProtectionProviderConfig } from '../middleware/bot-protection';
+import { EuCaptchaManager } from './eucaptcha-manager';
+import { TurnstileManager } from './turnstile-manager';
+import { FallbackBotProtectionManager } from './fallback-manager';
+
+/**
+ * Create a single provider manager instance.
+ */
+function createSingleManager(config: BotProtectionProviderConfig): BotProtectionTokenProvider {
+  switch (config.provider) {
+    case 'eucaptcha':
+      return new EuCaptchaManager(config.siteKey, config.scriptUrl);
+    case 'turnstile':
+      return new TurnstileManager(config.siteKey, config.scriptUrl);
+    default:
+      throw new Error(`Unknown bot protection provider: ${config.provider}`);
+  }
+}
+
+/**
+ * Create a bot protection manager with optional fallback chain.
+ *
+ * @param config - Bot protection configuration from shop query
+ * @returns BotProtectionTokenProvider (FallbackBotProtectionManager if fallback configured)
+ */
+export function createBotProtectionManager(config: BotProtectionConfig): BotProtectionTokenProvider {
+  const primary = createSingleManager(config.primary);
+  const fallback = config.fallback ? createSingleManager(config.fallback) : null;
+  return new FallbackBotProtectionManager(primary, fallback);
+}

package/src/core/bot-protection/eucaptcha-manager.ts

@@ -0,0 +1,88 @@
+/**
+ * EuCaptchaManager — EU CAPTCHA (Myra Security) bot protection provider.
+ *
+ * Default provider — GDPR by design, EU-hosted (Germany), privacy-first.
+ * Implements BotProtectionTokenProvider via AbstractBotProtectionManager.
+ * Invisible behavioral analysis, zero user interaction.
+ */
+
+/// <reference path="./types/eucaptcha.d.ts" />
+import { AbstractBotProtectionManager } from './abstract-manager';
+
+export class EuCaptchaManager extends AbstractBotProtectionManager {
+  protected _waitForApi(): Promise<void> {
+    if (typeof window !== 'undefined' && window.eucaptcha) {
+      return Promise.resolve();
+    }
+
+    return new Promise<void>((resolve) => {
+      const check = setInterval(() => {
+        if (typeof window !== 'undefined' && window.eucaptcha) {
+          clearInterval(check);
+          resolve();
+        }
+      }, 50);
+
+      // Safety timeout
+      setTimeout(() => {
+        clearInterval(check);
+        resolve();
+      }, 15000);
+    });
+  }
+
+  protected _renderWidget(container: HTMLElement, action?: string): string {
+    if (!window.eucaptcha) {
+      throw new Error('EU CAPTCHA API not loaded');
+    }
+
+    return window.eucaptcha.render(container, {
+      sitekey: this.siteKey,
+      size: 'invisible',
+      action,
+    });
+  }
+
+  protected _executeChallenge(widgetId: string, action?: string): Promise<string | null> {
+    return new Promise<string | null>((resolve) => {
+      if (!window.eucaptcha) {
+        resolve(null);
+        return;
+      }
+
+      // Reset for fresh token
+      window.eucaptcha.reset(widgetId);
+
+      // Remove old widget and re-render with callback
+      if (!this.container) {
+        resolve(null);
+        return;
+      }
+
+      // Re-render with callback to capture token
+      this.widgetId = window.eucaptcha.render(this.container, {
+        sitekey: this.siteKey,
+        size: 'invisible',
+        action,
+        callback: (token: string) => {
+          resolve(token);
+        },
+        'error-callback': () => {
+          resolve(null);
+        },
+        'expired-callback': () => {
+          resolve(null);
+        },
+      });
+
+      // Trigger execution
+      window.eucaptcha.execute(this.widgetId);
+    });
+  }
+
+  protected _destroyWidget(widgetId: string): void {
+    if (window.eucaptcha) {
+      window.eucaptcha.reset(widgetId);
+    }
+  }
+}

package/src/core/bot-protection/fallback-manager.ts

@@ -0,0 +1,43 @@
+/**
+ * FallbackBotProtectionManager — runtime fallback chain.
+ *
+ * Tries primary provider, falls back to secondary, ultimately returns null (fail-open).
+ * RULE: NEVER block the customer — fail-open is the ultimate fallback.
+ */
+
+import type { BotProtectionTokenProvider } from '../middleware/bot-protection';
+
+export class FallbackBotProtectionManager implements BotProtectionTokenProvider {
+  constructor(
+    private readonly primary: BotProtectionTokenProvider,
+    private readonly fallback: BotProtectionTokenProvider | null,
+  ) {}
+
+  async execute(options?: { action?: string; timeoutMs?: number }): Promise<string | null> {
+    // 1. Try primary
+    try {
+      const token = await this.primary.execute(options);
+      if (token) return token;
+    } catch {
+      // Primary failed — try fallback
+    }
+
+    // 2. Try fallback
+    if (this.fallback) {
+      try {
+        const token = await this.fallback.execute(options);
+        if (token) return token;
+      } catch {
+        // Fallback also failed
+      }
+    }
+
+    // 3. Ultimate fail-open: return null -> middleware decides per-operation strategy
+    return null;
+  }
+
+  destroy(): void {
+    this.primary.destroy();
+    this.fallback?.destroy();
+  }
+}