@doswiftly/storefront-sdk 4.0.0 → 4.1.0

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

@@ -0,0 +1,92 @@
+/**
+ * TurnstileManager — Cloudflare Turnstile bot protection provider.
+ *
+ * Implements BotProtectionTokenProvider via AbstractBotProtectionManager.
+ * Invisible widget, execution-mode challenge (no user interaction).
+ */
+
+/// <reference path="./types/turnstile.d.ts" />
+import { AbstractBotProtectionManager } from './abstract-manager';
+
+export class TurnstileManager extends AbstractBotProtectionManager {
+  private callbackName = `onloadTurnstileCallback_${Math.random().toString(36).slice(2)}`;
+
+  protected _waitForApi(): Promise<void> {
+    if (typeof window !== 'undefined' && window.turnstile) {
+      return Promise.resolve();
+    }
+
+    return new Promise<void>((resolve) => {
+      const check = setInterval(() => {
+        if (typeof window !== 'undefined' && window.turnstile) {
+          clearInterval(check);
+          resolve();
+        }
+      }, 50);
+
+      // Safety timeout — don't poll forever
+      setTimeout(() => {
+        clearInterval(check);
+        resolve(); // Resolve anyway — execute will fail gracefully
+      }, 15000);
+    });
+  }
+
+  protected _renderWidget(container: HTMLElement, action?: string): string {
+    if (!window.turnstile) {
+      throw new Error('Turnstile API not loaded');
+    }
+
+    return window.turnstile.render(container, {
+      sitekey: this.siteKey,
+      size: 'invisible',
+      execution: 'execute',
+      action,
+    });
+  }
+
+  protected _executeChallenge(widgetId: string, action?: string): Promise<string | null> {
+    return new Promise<string | null>((resolve) => {
+      if (!window.turnstile) {
+        resolve(null);
+        return;
+      }
+
+      // Reset to get a fresh token (tokens are single-use)
+      window.turnstile.reset(widgetId);
+
+      // Remove old widget and re-render with callback
+      window.turnstile.remove(widgetId);
+
+      if (!this.container) {
+        resolve(null);
+        return;
+      }
+
+      this.widgetId = window.turnstile.render(this.container, {
+        sitekey: this.siteKey,
+        size: 'invisible',
+        execution: 'execute',
+        action,
+        callback: (token: string) => {
+          resolve(token);
+        },
+        'error-callback': () => {
+          resolve(null);
+        },
+        'expired-callback': () => {
+          resolve(null);
+        },
+      });
+
+      // Trigger execution
+      window.turnstile.execute(this.widgetId, { action });
+    });
+  }
+
+  protected _destroyWidget(widgetId: string): void {
+    if (window.turnstile) {
+      window.turnstile.remove(widgetId);
+    }
+  }
+}

package/src/core/bot-protection/types/eucaptcha.d.ts

@@ -0,0 +1,28 @@
+/**
+ * EU CAPTCHA (Myra Security) global type declarations.
+ */
+
+interface EuCaptchaRenderOptions {
+  sitekey: string;
+  callback?: (token: string) => void;
+  'error-callback'?: (error: unknown) => void;
+  'expired-callback'?: () => void;
+  size?: 'normal' | 'compact' | 'invisible';
+  action?: string;
+}
+
+interface EuCaptchaApi {
+  render(container: string | HTMLElement, options: EuCaptchaRenderOptions): string;
+  execute(widgetId: string): void;
+  reset(widgetId: string): void;
+  getResponse(widgetId: string): string | undefined;
+}
+
+declare global {
+  interface Window {
+    eucaptcha?: EuCaptchaApi;
+    onloadEuCaptchaCallback?: () => void;
+  }
+}
+
+export {};

package/src/core/bot-protection/types/turnstile.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cloudflare Turnstile global type declarations.
+ */
+
+interface TurnstileRenderOptions {
+  sitekey: string;
+  callback?: (token: string) => void;
+  'error-callback'?: (error: unknown) => void;
+  'expired-callback'?: () => void;
+  size?: 'normal' | 'compact' | 'invisible';
+  theme?: 'light' | 'dark' | 'auto';
+  execution?: 'render' | 'execute';
+  action?: string;
+  cData?: string;
+}
+
+interface TurnstileApi {
+  render(container: string | HTMLElement, options: TurnstileRenderOptions): string;
+  execute(widgetId: string, options?: { action?: string }): void;
+  reset(widgetId: string): void;
+  remove(widgetId: string): void;
+  getResponse(widgetId: string): string | undefined;
+  isExpired(widgetId: string): boolean;
+}
+
+declare global {
+  interface Window {
+    turnstile?: TurnstileApi;
+    onloadTurnstileCallback?: () => void;
+  }
+}
+
+export {};

package/src/core/cart/cookie-config.ts

@@ -0,0 +1,13 @@
+/**
+ * Cart cookie configuration — platform contract.
+ *
+ * Used by:
+ * - SDK cart store (client-side cookie read/write for cartId)
+ * - Server-side cart prefetching (SSR cart badge, middleware)
+ * - proxy.ts (edge cart ID detection)
+ *
+ * Single cookie for cart ID persistence. Value is a plain cart ID string
+ * (not JSON) — server can read it directly via cookies().get('cart-id').
+ */
+export const CART_COOKIE_NAME = 'cart-id';
+export const CART_COOKIE_MAX_AGE = 30 * 24 * 60 * 60; // 30 days

package/src/core/currency/cookie-config.ts

@@ -0,0 +1,13 @@
+/**
+ * Currency configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK currency store (client-side cookie read/write)
+ * - SDK currency middleware (X-Preferred-Currency header)
+ * - Server-side currency detection (SSR helpers)
+ *
+ * Single cookie for preferred currency persistence.
+ */
+export const CURRENCY_COOKIE_NAME = 'preferred-currency';
+export const CURRENCY_COOKIE_MAX_AGE = 365 * 24 * 60 * 60; // 1 year
+export const CURRENCY_HEADER_NAME = 'X-Preferred-Currency';

package/src/core/index.ts

@@ -55,10 +55,24 @@ export type {
 // Middleware
 export { authMiddleware } from './middleware/auth';
 export { currencyMiddleware } from './middleware/currency';
+export { languageMiddleware } from './middleware/language';
+export {
+  botProtectionMiddleware,
+  BOT_PROTECTION_HEADER,
+  type BotProtectionTokenProvider,
+  type BotProtectionConfig,
+  type BotProtectionProviderConfig,
+  type BotProtectionMiddlewareOptions,
+  type FailStrategy,
+} from './middleware/bot-protection';
 export { retryMiddleware, type RetryOptions } from './middleware/retry';
 export { timeoutMiddleware, type TimeoutOptions } from './middleware/timeout';
 export { errorMiddleware } from './middleware/errors';
 
+// Bot protection managers (framework-agnostic, DOM APIs)
+export { createBotProtectionManager } from './bot-protection/create-manager';
+export { FallbackBotProtectionManager } from './bot-protection/fallback-manager';
+
 // Errors
 export { StorefrontError, ErrorCodes, type StorefrontErrorOptions } from './errors';
 
@@ -134,6 +148,15 @@ export {
   type AuthCookieConfig,
 } from './auth/cookie-config';
 
+// Language config
+export { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE, LANGUAGE_HEADER_NAME } from './language/cookie-config';
+
+// Currency config
+export { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE, CURRENCY_HEADER_NAME } from './currency/cookie-config';
+
+// Cart cookie config
+export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
+
 // Auth route matching
 export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
 

package/src/core/language/cookie-config.ts

@@ -0,0 +1,13 @@
+/**
+ * Language configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK language store (client-side cookie read/write)
+ * - SDK language middleware (X-Lang header)
+ * - next-intl middleware `localeCookie.name` (server-side locale detection)
+ *
+ * Single cookie replaces both next-intl's NEXT_LOCALE and SDK's preferred-language.
+ */
+export const LANGUAGE_COOKIE_NAME = 'preferred-language';
+export const LANGUAGE_COOKIE_MAX_AGE = 365 * 24 * 60 * 60; // 1 year
+export const LANGUAGE_HEADER_NAME = 'X-Lang';

package/src/core/middleware/bot-protection.ts

@@ -0,0 +1,140 @@
+/**
+ * Bot protection middleware — vendor-agnostic token injection.
+ *
+ * Intercepts protected mutations and adds a bot verification token
+ * via the X-Bot-Protection-Token header. Token acquisition is delegated
+ * to a BotProtectionTokenProvider (EU CAPTCHA, Turnstile, etc.).
+ *
+ * Fail strategy is per-operation: 'open' = continue without token,
+ * 'closed' = throw if token unavailable.
+ */
+
+import type { Middleware } from '../client/types';
+import { StorefrontError } from '../errors';
+
+// ---------------------------------------------------------------------------
+// Token provider interface (implemented by managers)
+// ---------------------------------------------------------------------------
+
+/** Vendor-agnostic token provider interface */
+export interface BotProtectionTokenProvider {
+  /**
+   * Get a fresh bot protection token.
+   * Handles: in-flight deduplication, timeout, singleton script loading.
+   *
+   * @param options.action - Operation name (e.g. 'CustomerCreate') for action validation
+   * @param options.timeoutMs - Timeout in ms (default: 10000)
+   * @returns Token string or null if unavailable (adblock, timeout, error)
+   */
+  execute(options?: { action?: string; timeoutMs?: number }): Promise<string | null>;
+
+  /** Cleanup widget and script resources */
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration types
+// ---------------------------------------------------------------------------
+
+/** Single provider config (from shop query) */
+export interface BotProtectionProviderConfig {
+  /** Provider identifier: 'eucaptcha' | 'turnstile' | 'recaptcha' | extensible */
+  provider: string;
+  /** Site key for the bot protection widget */
+  siteKey: string;
+  /** Script URL — configurable for region-specific / enterprise overrides */
+  scriptUrl: string;
+}
+
+/** Bot protection configuration from shop query */
+export interface BotProtectionConfig {
+  /** Primary provider */
+  primary: BotProtectionProviderConfig;
+  /** Fallback provider (runtime: if primary fails -> fallback -> fail-open) */
+  fallback?: BotProtectionProviderConfig | null;
+  /** GraphQL operation names requiring verification */
+  protectedOperations: string[];
+}
+
+/** Fail strategy per request */
+export type FailStrategy = 'open' | 'closed';
+
+// ---------------------------------------------------------------------------
+// Middleware options
+// ---------------------------------------------------------------------------
+
+export interface BotProtectionMiddlewareOptions {
+  /** Token provider instance (manager or fallback chain) */
+  tokenProvider: BotProtectionTokenProvider;
+  /** GraphQL operation names that require bot protection */
+  protectedOperations: string[];
+  /** Default fail strategy when token acquisition fails (default: 'open') */
+  defaultFailStrategy?: FailStrategy;
+  /** Override fail strategy per operation (e.g. CheckoutComplete = closed) */
+  failStrategyOverrides?: Record<string, FailStrategy>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Header name for bot protection token */
+export const BOT_PROTECTION_HEADER = 'X-Bot-Protection-Token';
+
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates bot protection middleware for the SDK pipeline.
+ *
+ * Only intercepts mutations whose operationName is in protectedOperations.
+ * Token is fetched fresh on every call (single-use tokens, retry-safe).
+ *
+ * Pipeline position: AFTER auth/currency, BEFORE retry/timeout/errors.
+ * Retry middleware re-executes the full chain, so each attempt gets a fresh token.
+ */
+export function botProtectionMiddleware(options: BotProtectionMiddlewareOptions): Middleware {
+  const {
+    tokenProvider,
+    protectedOperations,
+    defaultFailStrategy = 'open',
+    failStrategyOverrides = {},
+  } = options;
+
+  const protectedSet = new Set(protectedOperations);
+
+  return async (request, next) => {
+    // Only intercept mutations
+    if (!request.isMutation) return next(request);
+
+    // Only intercept protected operations
+    const opName = request.operationName;
+    if (!opName || !protectedSet.has(opName)) {
+      return next(request);
+    }
+
+    // Fetch fresh token — action param enables backend action validation
+    const token = await tokenProvider.execute({
+      action: opName,
+      timeoutMs: 10000,
+    });
+
+    if (token) {
+      request.headers[BOT_PROTECTION_HEADER] = token;
+    } else {
+      // Fail strategy: open = continue without token, closed = throw
+      const strategy = failStrategyOverrides[opName] ?? defaultFailStrategy;
+      if (strategy === 'closed') {
+        throw new StorefrontError({
+          code: 'BOT_PROTECTION_REQUIRED',
+          message: 'Bot protection verification failed. Please try again.',
+          status: 0,
+        });
+      }
+      // fail-open: continue without token — backend guard may still reject
+    }
+
+    return next(request);
+  };
+}

package/src/core/middleware/currency.ts

@@ -12,6 +12,7 @@
  */
 
 import type { Middleware } from '../client/types';
+import { CURRENCY_HEADER_NAME } from '../currency/cookie-config';
 
 export function currencyMiddleware(
   getCurrency: () => string | null | undefined,
@@ -19,7 +20,7 @@ export function currencyMiddleware(
   return (request, next) => {
     const currency = getCurrency();
     if (currency) {
-      request.headers['X-Preferred-Currency'] = currency;
+      request.headers[CURRENCY_HEADER_NAME] = currency;
     }
     return next(request);
   };

package/src/core/middleware/language.ts

@@ -0,0 +1,30 @@
+/**
+ * Language middleware — adds X-Lang header.
+ *
+ * Language is resolved lazily so language switches are reflected immediately.
+ * CRITICAL: does NOT send header when language=null (store not yet initialized)
+ * — without this, backend returns default language, React Query caches it,
+ *   and after setLanguage() the cache is stale.
+ *
+ * @example
+ * ```typescript
+ * import { languageMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * client.use(languageMiddleware(() => languageStore.getState().language));
+ * ```
+ */
+
+import type { Middleware } from '../client/types';
+import { LANGUAGE_HEADER_NAME } from '../language/cookie-config';
+
+export function languageMiddleware(
+  getLanguage: () => string | null | undefined,
+): Middleware {
+  return (request, next) => {
+    const language = getLanguage();
+    if (language) {
+      request.headers[LANGUAGE_HEADER_NAME] = language;
+    }
+    return next(request);
+  };
+}

package/src/react/bot-protection/bot-protection-context.ts

@@ -0,0 +1,17 @@
+/**
+ * Bot protection React context.
+ *
+ * Provides access to the BotProtectionTokenProvider manager
+ * for the useBotProtection() escape hatch hook.
+ */
+
+'use client';
+
+import { createContext } from 'react';
+import type { BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
+
+export interface BotProtectionContextValue {
+  manager: BotProtectionTokenProvider | null;
+}
+
+export const BotProtectionContext = createContext<BotProtectionContextValue | null>(null);

package/src/react/bot-protection/bot-protection-widget.tsx

@@ -0,0 +1,46 @@
+/**
+ * BotProtectionWidget — invisible React wrapper that mounts the bot protection manager.
+ *
+ * Renders a hidden div and mounts/unmounts the manager lifecycle.
+ * Triggers lazy script preload on mount.
+ */
+
+'use client';
+
+import React, { useEffect, useRef } from 'react';
+import type { BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
+import type { AbstractBotProtectionManager } from '../../core/bot-protection/abstract-manager';
+
+interface BotProtectionWidgetProps {
+  manager: BotProtectionTokenProvider | null;
+}
+
+export function BotProtectionWidget({ manager }: BotProtectionWidgetProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const mountedRef = useRef(false);
+
+  useEffect(() => {
+    if (!manager || !containerRef.current || mountedRef.current) return;
+
+    mountedRef.current = true;
+
+    // Trigger lazy script preload + mount container
+    const mgr = manager as AbstractBotProtectionManager;
+    if (typeof mgr.loadScript === 'function') {
+      mgr.loadScript().catch(() => {
+        // Script load failure is handled gracefully in execute()
+      });
+    }
+    if (typeof mgr.mount === 'function') {
+      mgr.mount(containerRef.current);
+    }
+
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [manager]);
+
+  if (!manager) return null;
+
+  return <div ref={containerRef} style={{ display: 'none' }} aria-hidden="true" />;
+}

package/src/react/cookies.ts

@@ -16,15 +16,20 @@ export function getCookie(name: string): string | null {
 
 /**
  * Set cookie (client-side only).
+ *
+ * `secure` defaults to auto-detect from `location.protocol` (true on HTTPS).
  */
 export function setCookie(
   name: string,
   value: string,
-  options: { maxAge?: number; path?: string; sameSite?: string } = {},
+  options: { maxAge?: number; path?: string; sameSite?: string; secure?: boolean } = {},
 ): void {
   if (typeof document === 'undefined') return;
   const { maxAge = 365 * 24 * 60 * 60, path = '/', sameSite = 'lax' } = options;
-  document.cookie = `${name}=${encodeURIComponent(value)};max-age=${maxAge};path=${path};samesite=${sameSite}`;
+  const secure = options.secure ??
+    (typeof location !== 'undefined' && location.protocol === 'https:');
+  const securePart = secure ? ';secure' : '';
+  document.cookie = `${name}=${encodeURIComponent(value)};max-age=${maxAge};path=${path};samesite=${sameSite}${securePart}`;
 }
 
 /**
@@ -35,6 +40,9 @@ export function deleteCookie(name: string, path = '/'): void {
   document.cookie = `${name}=;max-age=0;path=${path}`;
 }
 
+import { CURRENCY_COOKIE_NAME } from '../core/currency/cookie-config';
+import { CART_COOKIE_NAME } from '../core/cart/cookie-config';
+
 /**
  * Get preferred currency from cookie (async — works with Next.js cookies()).
  * Falls back to document.cookie on client.
@@ -44,11 +52,38 @@ export async function getCurrencyFromCookieAsync(): Promise<string | null> {
   try {
     const { cookies } = await import('next/headers');
     const cookieStore = await cookies();
-    return cookieStore.get('preferred-currency')?.value ?? null;
+    return cookieStore.get(CURRENCY_COOKIE_NAME)?.value ?? null;
+  } catch {
+    // Not in a server context or next not available
+  }
+
+  // Client-side fallback
+  return getCookie(CURRENCY_COOKIE_NAME);
+}
+
+/**
+ * Get cart ID from cookie (async — works with Next.js cookies()).
+ * Falls back to document.cookie on client.
+ *
+ * Use in Server Components for SSR cart badge:
+ * ```typescript
+ * const cartId = await getCartIdFromCookieAsync();
+ * if (cartId) {
+ *   const cart = await fetchCart(cartId);
+ *   // Render cart badge with real totalQuantity — no skeleton needed
+ * }
+ * ```
+ */
+export async function getCartIdFromCookieAsync(): Promise<string | null> {
+  // Server-side: try Next.js cookies()
+  try {
+    const { cookies } = await import('next/headers');
+    const cookieStore = await cookies();
+    return cookieStore.get(CART_COOKIE_NAME)?.value ?? null;
   } catch {
     // Not in a server context or next not available
   }
 
   // Client-side fallback
-  return getCookie('preferred-currency');
+  return getCookie(CART_COOKIE_NAME);
 }

package/src/react/hooks/use-bot-protection.ts

@@ -0,0 +1,31 @@
+/**
+ * useBotProtection — escape hatch hook for custom bot protection use cases.
+ *
+ * Normally the middleware handles token injection automatically.
+ * Use this hook only when you need manual control (e.g. custom forms).
+ */
+
+'use client';
+
+import { useContext, useCallback } from 'react';
+import { BotProtectionContext } from '../bot-protection/bot-protection-context';
+
+export function useBotProtection() {
+  const ctx = useContext(BotProtectionContext);
+  const manager = ctx?.manager ?? null;
+
+  const execute = useCallback(
+    (options?: { action?: string; timeoutMs?: number }) => {
+      if (!manager) return Promise.resolve(null);
+      return manager.execute(options);
+    },
+    [manager],
+  );
+
+  return {
+    /** Execute a bot protection challenge and get a token */
+    execute,
+    /** Whether bot protection is configured and available */
+    isAvailable: !!manager,
+  };
+}

package/src/react/index.ts

@@ -16,6 +16,7 @@
 export { StorefrontProvider, type StorefrontProviderProps } from './providers/storefront-provider';
 export { StorefrontClientProvider, type StorefrontClientProviderProps } from './providers/storefront-client-provider';
 export { CurrencyProvider, type CurrencyProviderProps } from './providers/currency-provider';
+export { LanguageProvider, type LanguageProviderProps } from './providers/language-provider';
 
 // Hooks
 export { useAuth, type UseAuthOptions, type LoginResult, type LogoutResult, type TokenRenewResult } from './hooks/use-auth';
@@ -26,20 +27,45 @@ export { useCurrency } from './hooks/use-currency';
 // Store hooks (Context-based)
 export { useAuthStore, useAuthStoreApi, useAuthHydrated } from './stores/store-context';
 export { useCurrencyStore, useCurrencyStoreApi } from './stores/store-context';
+export { useLanguageStore, useLanguageStoreApi } from './stores/store-context';
 
 // Store types
 export type { AuthStore, CustomerInfo } from './stores/auth.store';
 export type { CurrencyStore, ShopCurrencyData } from './stores/currency.store';
+export type { LanguageStore } from './stores/language.store';
+export type { ShopConfig } from './types/shop-config';
 
 // Selectors
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
+export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
 
 // Cookie utilities
-export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync } from './cookies';
+export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync } from './cookies';
+
+// Bot protection
+export { useBotProtection } from './hooks/use-bot-protection';
 
 // Generic hooks
 export { useHydrated } from './hooks/use-hydrated';
 export { useDebouncedValue } from './hooks/use-debounced-value';
 
+// Cart store (DI-based)
+export {
+  createCartStore,
+  selectCartId,
+  selectIsCartOpen,
+  selectCartIsLoading,
+} from './stores/cart.store';
+export type {
+  CartState,
+  CartStoreConfig,
+  CartActions,
+  CartData,
+  CartMutationAction,
+  CartLineInput,
+  CartLineUpdateInput,
+} from './stores/cart.store';
+export { CartProvider, useCartStore, useCartStoreApi } from './stores/cart.context';
+
 // Store context helper
 export { createStoreContext } from './helpers/create-store-context';