@doswiftly/storefront-sdk 4.3.0 → 4.5.0

package/src/core/auth/handlers.ts

@@ -1,168 +0,0 @@
-/**
- * Auth cookie handlers — factory functions for API routes.
- *
- * 0 deps, pure Web API (Request/Response). Framework-agnostic.
- * Creates set-token and clear-token handlers that any storefront
- * can use as 2-line API routes.
- *
- * @example
- * ```ts
- * // app/api/auth/set-token/route.ts
- * import { createSetTokenHandler } from '@doswiftly/storefront-sdk';
- * export const POST = createSetTokenHandler();
- * ```
- */
-
-import { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS } from './cookie-config';
-
-interface SetTokenHandlerOptions {
-  maxAge?: number;
-}
-
-function serializeCookie(
-  name: string,
-  value: string,
-  options: {
-    maxAge?: number;
-    path?: string;
-    sameSite?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-  },
-): string {
-  const parts = [`${name}=${value}`];
-  if (options.maxAge != null) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.path) parts.push(`Path=${options.path}`);
-  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
-  if (options.secure) parts.push('Secure');
-  if (options.httpOnly) parts.push('HttpOnly');
-  return parts.join('; ');
-}
-
-function validateOrigin(request: Request): Response | null {
-  const origin = request.headers.get('origin');
-  const host = request.headers.get('host');
-
-  if (origin && !origin.includes(host || '')) {
-    return new Response(JSON.stringify({ error: 'Invalid origin' }), {
-      status: 403,
-      headers: { 'Content-Type': 'application/json' },
-    });
-  }
-  return null;
-}
-
-/**
- * Create a POST handler that sets the auth token in an httpOnly cookie.
- *
- * Security: origin validation, Content-Type check, CSRF (SameSite=Lax),
- * httpOnly (XSS protection), Secure in production.
- */
-export function createSetTokenHandler(
-  overrides?: SetTokenHandlerOptions,
-): (request: Request) => Promise<Response> {
-  const maxAge = overrides?.maxAge ?? AUTH_COOKIE_DEFAULTS.maxAge;
-
-  return async (request: Request): Promise<Response> => {
-    try {
-      // 1. CSRF: validate origin
-      const originError = validateOrigin(request);
-      if (originError) return originError;
-
-      // 2. Validate Content-Type
-      const contentType = request.headers.get('content-type');
-      if (!contentType?.includes('application/json')) {
-        return new Response(
-          JSON.stringify({ error: 'Content-Type must be application/json' }),
-          { status: 400, headers: { 'Content-Type': 'application/json' } },
-        );
-      }
-
-      // 3. Parse body
-      let body: { token?: string };
-      try {
-        body = await request.json();
-      } catch {
-        return new Response(
-          JSON.stringify({ error: 'Invalid JSON body' }),
-          { status: 400, headers: { 'Content-Type': 'application/json' } },
-        );
-      }
-
-      const { token } = body;
-      if (!token || typeof token !== 'string' || token.trim() === '') {
-        return new Response(
-          JSON.stringify({ error: 'Token is required and must be a non-empty string' }),
-          { status: 400, headers: { 'Content-Type': 'application/json' } },
-        );
-      }
-
-      // 4. Set httpOnly cookie
-      const cookie = serializeCookie(AUTH_COOKIE_NAME, token, {
-        maxAge,
-        path: AUTH_COOKIE_DEFAULTS.path,
-        sameSite: AUTH_COOKIE_DEFAULTS.sameSite,
-        secure: AUTH_COOKIE_DEFAULTS.secure,
-        httpOnly: AUTH_COOKIE_DEFAULTS.httpOnly,
-      });
-
-      return new Response(
-        JSON.stringify({ success: true, message: 'Token set successfully' }),
-        {
-          status: 200,
-          headers: {
-            'Content-Type': 'application/json',
-            'Set-Cookie': cookie,
-          },
-        },
-      );
-    } catch (error) {
-      console.error('Error setting auth token:', error);
-      return new Response(
-        JSON.stringify({ error: 'Internal server error' }),
-        { status: 500, headers: { 'Content-Type': 'application/json' } },
-      );
-    }
-  };
-}
-
-/**
- * Create a POST handler that clears the auth token cookie.
- *
- * Security: origin validation, immediate expiration (maxAge=0).
- */
-export function createClearTokenHandler(): (request: Request) => Promise<Response> {
-  return async (request: Request): Promise<Response> => {
-    try {
-      // 1. CSRF: validate origin
-      const originError = validateOrigin(request);
-      if (originError) return originError;
-
-      // 2. Clear cookie (maxAge=0)
-      const cookie = serializeCookie(AUTH_COOKIE_NAME, '', {
-        maxAge: 0,
-        path: AUTH_COOKIE_DEFAULTS.path,
-        sameSite: AUTH_COOKIE_DEFAULTS.sameSite,
-        secure: AUTH_COOKIE_DEFAULTS.secure,
-        httpOnly: AUTH_COOKIE_DEFAULTS.httpOnly,
-      });
-
-      return new Response(
-        JSON.stringify({ success: true, message: 'Token cleared successfully' }),
-        {
-          status: 200,
-          headers: {
-            'Content-Type': 'application/json',
-            'Set-Cookie': cookie,
-          },
-        },
-      );
-    } catch (error) {
-      console.error('Error clearing auth token:', error);
-      return new Response(
-        JSON.stringify({ error: 'Internal server error' }),
-        { status: 500, headers: { 'Content-Type': 'application/json' } },
-      );
-    }
-  };
-}

package/src/core/auth/routes.ts

@@ -1,26 +0,0 @@
-/**
- * Route matching utility for auth redirects.
- *
- * Pure function — route lists stay in the template (SSOT config),
- * but matching logic lives in the SDK (reusable across templates).
- */
-
-export interface RouteProtectionConfig {
-  protectedRoutes: string[];
-  guestOnlyRoutes: string[];
-  redirects: {
-    unauthenticated: string;
-    authenticated: string;
-  };
-}
-
-/**
- * Check if a pathname matches any route in the list.
- * Supports both exact matches and prefix matches
- * (e.g., "/account" matches "/account/orders").
- */
-export function matchesRoute(pathname: string, routes: string[]): boolean {
-  return routes.some(
-    (route) => pathname === route || pathname.startsWith(`${route}/`),
-  );
-}

package/src/core/auth/token-client.ts

@@ -1,51 +0,0 @@
-/**
- * Client-side auth token helpers — fetch-based, 0 deps.
- *
- * Calls API routes to set/clear the httpOnly auth cookie.
- * Used by template hooks (use-auth.ts, use-auth-sync.ts, register-form.tsx).
- *
- * @example
- * ```ts
- * import { createAuthTokenClient } from '@doswiftly/storefront-sdk';
- * const { setToken, clearToken } = createAuthTokenClient();
- *
- * await setToken(accessToken);
- * await clearToken();
- * ```
- */
-
-export interface AuthTokenClient {
-  setToken: (token: string) => Promise<void>;
-  clearToken: () => Promise<void>;
-}
-
-/**
- * Create a client for managing auth tokens via API routes.
- *
- * @param basePath - Base path for API routes (default: "/api/auth")
- */
-export function createAuthTokenClient(basePath = '/api/auth'): AuthTokenClient {
-  return {
-    async setToken(token: string): Promise<void> {
-      const response = await fetch(`${basePath}/set-token`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token }),
-      });
-
-      if (!response.ok) {
-        throw new Error('Failed to set authentication token');
-      }
-    },
-
-    async clearToken(): Promise<void> {
-      const response = await fetch(`${basePath}/clear-token`, {
-        method: 'POST',
-      });
-
-      if (!response.ok) {
-        throw new Error('Failed to clear authentication token');
-      }
-    },
-  };
-}

package/src/core/auth/types.ts

@@ -1,54 +0,0 @@
-/**
- * Auth types — manual (no codegen).
- */
-
-export interface CustomerAccessToken {
-  accessToken: string;
-  expiresAt: string;
-}
-
-export interface Customer {
-  id: string;
-  email: string;
-  firstName: string | null;
-  lastName: string | null;
-  displayName: string | null;
-  phone: string | null;
-  emailVerified: boolean;
-  emailMarketingState: string | null;
-  defaultAddress: MailingAddress | null;
-  ordersCount: number;
-  totalSpent: { amount: string; currencyCode: string } | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface MailingAddress {
-  id: string;
-  address1: string | null;
-  address2: string | null;
-  city: string | null;
-  company: string | null;
-  country: string | null;
-  countryCode: string | null;
-  firstName: string | null;
-  lastName: string | null;
-  phone: string | null;
-  province: string | null;
-  provinceCode: string | null;
-  zip: string | null;
-  isDefault: boolean;
-}
-
-export interface AuthResult {
-  accessToken: string;
-  expiresAt: string;
-  customer?: Customer;
-}
-
-export interface CustomerCreateInput {
-  email: string;
-  password: string;
-  firstName?: string;
-  lastName?: string;
-}

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

@@ -1,185 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,88 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-/**
- * 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();
-  }
-}