@doswiftly/storefront-sdk 4.4.0 → 4.7.1

package/src/core/helpers/sanitize-html.ts

@@ -1,42 +0,0 @@
-/**
- * Lightweight HTML sanitizer for defense-in-depth.
- * Primary sanitization happens on the backend (sanitize-html library).
- * This strips dangerous tags/attributes as an extra safety layer.
- * Works in both Node.js and Edge runtimes (no external dependencies).
- */
-
-const DANGEROUS_TAG_PATTERNS = [
-  // Tags with content that must be fully removed
-  /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script\s*>/gi,
-  /<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe\s*>/gi,
-  /<object\b[^<]*(?:(?!<\/object>)<[^<]*)*<\/object\s*>/gi,
-  /<form\b[^<]*(?:(?!<\/form>)<[^<]*)*<\/form\s*>/gi,
-  /<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style\s*>/gi,
-  // Self-closing / void dangerous tags
-  /<embed\b[^>]*\/?>/gi,
-  /<link\b[^>]*\/?>/gi,
-  /<meta\b[^>]*\/?>/gi,
-  /<base\b[^>]*\/?>/gi,
-  /<applet\b[^<]*(?:(?!<\/applet>)<[^<]*)*<\/applet\s*>/gi,
-];
-
-// Event handler attributes (onclick, onerror, onload, etc.)
-const EVENT_HANDLER_PATTERN = /\s+on\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi;
-
-// javascript: protocol in href/src/action attributes
-const JS_PROTOCOL_PATTERN = /(href|src|action)\s*=\s*["']\s*javascript\s*:/gi;
-
-export function sanitizeHtml(html: string): string {
-  if (!html) return html;
-
-  let result = html;
-
-  for (const pattern of DANGEROUS_TAG_PATTERNS) {
-    result = result.replace(pattern, '');
-  }
-
-  result = result.replace(EVENT_HANDLER_PATTERN, '');
-  result = result.replace(JS_PROTOCOL_PATTERN, '$1="');
-
-  return result;
-}

package/src/core/image.ts

@@ -1,22 +0,0 @@
-/**
- * Image types for DoSwiftly storefronts.
- *
- * GraphQL API returns ready-to-use CDN URLs with transform query params.
- * No client-side loader needed — use `url(transform: { maxWidth: 800 })` in queries.
- */
-
-/**
- * Image data from GraphQL API (matches Image type in storefront schema).
- */
-export interface ImageData {
-  /** Image URL from GraphQL (ready-to-use CDN URL, optionally with transform query params) */
-  url: string;
-  /** Alt text for accessibility + SEO */
-  altText?: string | null;
-  /** Original image width in pixels */
-  width?: number | null;
-  /** Original image height in pixels */
-  height?: number | null;
-  /** Image ID */
-  id?: string | null;
-}

package/src/core/index.ts

@@ -1,174 +0,0 @@
-/**
- * @doswiftly/storefront-sdk — Core (framework-agnostic)
- *
- * 100% framework-agnostic, 0 runtime dependencies.
- * Works in Node.js, Edge Workers, Deno, Bun, CLI scripts — without React.
- *
- * @example
- * ```typescript
- * import {
- *   createStorefrontClient,
- *   authMiddleware,
- *   currencyMiddleware,
- *   retryMiddleware,
- *   timeoutMiddleware,
- *   errorMiddleware,
- *   CartClient,
- *   AuthClient,
- * } from '@doswiftly/storefront-sdk';
- *
- * const client = createStorefrontClient({
- *   apiUrl: 'https://api.doswiftly.pl',
- *   shopSlug: 'my-shop',
- *   middleware: [
- *     authMiddleware(() => getToken()),
- *     currencyMiddleware(() => getCurrency()),
- *     retryMiddleware({ maxRetries: 2 }),
- *     timeoutMiddleware({ timeout: 5000 }),
- *     errorMiddleware(),
- *   ],
- * });
- *
- * const cartClient = new CartClient(client);
- * const cart = await cartClient.create();
- * ```
- */
-
-// Client factory
-export { createStorefrontClient } from './client/create-client';
-
-// Client types
-export type {
-  StorefrontClient,
-  StorefrontClientConfig,
-  Middleware,
-  ExecuteFn,
-  GraphQLRequest,
-  GraphQLResponse,
-  GraphQLErrorInfo,
-  UserError,
-  CacheStrategy,
-  CacheOptions,
-  TypedDocumentString,
-} from './client/types';
-
-// 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';
-
-// Cache strategies
-export {
-  cacheNone,
-  cacheShort,
-  cacheLong,
-  cachePrivate,
-  cacheCustom,
-  generateCacheControlHeader,
-  type CacheOverrides,
-} from './cache';
-
-// Cart client
-export { CartClient } from './cart/cart-client';
-export type {
-  Cart,
-  CartLine,
-  CartLineMerchandise,
-  CartLineCost,
-  CartCost,
-  CartBuyerIdentity,
-  CartDiscountCode,
-  CartDiscountAllocation,
-  CartLineInput,
-  CartLineUpdateInput,
-  CartCreateInput,
-  CartBuyerIdentityInput,
-  Money,
-} from './cart/types';
-
-// Auth client
-export { AuthClient } from './auth/auth-client';
-export type {
-  Customer,
-  CustomerAccessToken,
-  MailingAddress,
-  AuthResult,
-  CustomerCreateInput,
-} from './auth/types';
-
-// Helpers
-export { assertNoUserErrors } from './helpers/assert-no-user-errors';
-export { sanitizeHtml } from './helpers/sanitize-html';
-export {
-  normalizeConnection,
-  type Connection,
-  type ConnectionEdge,
-  type ConnectionPageInfo,
-  type NormalizedConnection,
-} from './helpers/normalize-connection';
-
-// Format utilities
-export {
-  formatPrice,
-  formatPriceRange,
-  formatAmount,
-  formatDate,
-  formatDateTime,
-  formatNumber,
-  formatPercentage,
-  getCurrencySymbol,
-  CURRENCY_SYMBOLS,
-  CURRENCY_LOCALES,
-  type PriceMoney,
-} from './format';
-
-// Auth cookie config (platform contract)
-export {
-  AUTH_COOKIE_NAME,
-  AUTH_COOKIE_DEFAULTS,
-  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';
-
-// Auth cookie handlers (API route factories)
-export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers';
-
-// Auth token client (client-side fetch helpers)
-export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
-
-// Image types (loaders removed — GraphQL returns ready-to-use CDN URLs with transform params)
-export { type ImageData } from './image';
-
-// Utilities
-export { getOperationName } from './client/operation-name';
-export { hashQuery } from './client/hash';

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

@@ -1,13 +0,0 @@
-/**
- * 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/auth.ts

@@ -1,27 +0,0 @@
-/**
- * Auth middleware — adds Authorization header from token getter.
- *
- * Token is resolved lazily (on each request) so it picks up
- * store changes, token renewals, etc.
- *
- * @example
- * ```typescript
- * import { authMiddleware } from '@doswiftly/storefront-sdk';
- *
- * client.use(authMiddleware(() => authStore.getState().accessToken));
- * ```
- */
-
-import type { Middleware } from '../client/types';
-
-export function authMiddleware(
-  getToken: () => string | null | undefined,
-): Middleware {
-  return (request, next) => {
-    const token = getToken();
-    if (token) {
-      request.headers['Authorization'] = `Bearer ${token}`;
-    }
-    return next(request);
-  };
-}

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

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

@@ -1,27 +0,0 @@
-/**
- * Currency middleware — adds X-Preferred-Currency header.
- *
- * Currency is resolved lazily so currency switches are reflected immediately.
- *
- * @example
- * ```typescript
- * import { currencyMiddleware } from '@doswiftly/storefront-sdk';
- *
- * client.use(currencyMiddleware(() => currencyStore.getState().currency));
- * ```
- */
-
-import type { Middleware } from '../client/types';
-import { CURRENCY_HEADER_NAME } from '../currency/cookie-config';
-
-export function currencyMiddleware(
-  getCurrency: () => string | null | undefined,
-): Middleware {
-  return (request, next) => {
-    const currency = getCurrency();
-    if (currency) {
-      request.headers[CURRENCY_HEADER_NAME] = currency;
-    }
-    return next(request);
-  };
-}

package/src/core/middleware/errors.ts

@@ -1,86 +0,0 @@
-/**
- * Error normalization middleware — ALWAYS LAST in the pipeline.
- *
- * Catches all errors from downstream middleware and the transport,
- * normalizes them into StorefrontError instances.
- *
- * Handles:
- * - Network errors (fetch failures)
- * - HTTP errors (non-200 responses)
- * - GraphQL errors (errors array in response)
- * - Abort/timeout errors
- * - Missing data in response
- *
- * @example
- * ```typescript
- * import { errorMiddleware } from '@doswiftly/storefront-sdk';
- *
- * // Always add as the LAST middleware
- * client.use(errorMiddleware());
- * ```
- */
-
-import type { Middleware } from '../client/types';
-import { StorefrontError, ErrorCodes } from '../errors';
-
-export function errorMiddleware(): Middleware {
-  return async (request, next) => {
-    let response;
-
-    try {
-      response = await next(request);
-    } catch (error) {
-      // Already a StorefrontError — re-throw as-is
-      if (error instanceof StorefrontError) {
-        throw error;
-      }
-
-      // AbortError (timeout handled by timeout middleware, manual abort here)
-      if (error instanceof Error && error.name === 'AbortError') {
-        throw new StorefrontError({
-          code: ErrorCodes.TIMEOUT,
-          message: 'Request was aborted',
-          cause: error,
-        });
-      }
-
-      // Network error (fetch failed — DNS, connection refused, etc.)
-      throw new StorefrontError({
-        code: ErrorCodes.NETWORK_ERROR,
-        message: error instanceof Error ? error.message : 'Network request failed',
-        cause: error,
-      });
-    }
-
-    // HTTP error (non-2xx response)
-    if (response.status >= 400) {
-      throw new StorefrontError({
-        code: ErrorCodes.HTTP_ERROR,
-        message: `HTTP ${response.status}`,
-        status: response.status,
-        graphqlErrors: response.errors ?? [],
-      });
-    }
-
-    // GraphQL errors in the response
-    if (response.errors?.length) {
-      throw new StorefrontError({
-        code: ErrorCodes.GRAPHQL_ERROR,
-        message: response.errors[0].message,
-        status: response.status,
-        graphqlErrors: response.errors,
-      });
-    }
-
-    // No data returned
-    if (response.data === undefined || response.data === null) {
-      throw new StorefrontError({
-        code: ErrorCodes.NO_DATA,
-        message: 'No data returned from GraphQL',
-        status: response.status,
-      });
-    }
-
-    return response;
-  };
-}

package/src/core/middleware/language.ts

@@ -1,30 +0,0 @@
-/**
- * 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/core/middleware/retry.ts

@@ -1,75 +0,0 @@
-/**
- * Retry middleware — retries on network errors and 5xx responses.
- *
- * ONLY retries queries, NEVER mutations (to prevent double-charges, etc.).
- * Uses exponential backoff with jitter.
- *
- * @example
- * ```typescript
- * import { retryMiddleware } from '@doswiftly/storefront-sdk';
- *
- * client.use(retryMiddleware({ maxRetries: 2 }));
- * ```
- */
-
-import type { Middleware } from '../client/types';
-import { StorefrontError, ErrorCodes } from '../errors';
-
-export interface RetryOptions {
-  /** Maximum number of retries (default: 2) */
-  maxRetries?: number;
-  /** Initial delay in ms (default: 300) */
-  initialDelay?: number;
-}
-
-export function retryMiddleware(options: RetryOptions = {}): Middleware {
-  const { maxRetries = 2, initialDelay = 300 } = options;
-
-  return async (request, next) => {
-    // Never retry mutations
-    if (request.isMutation) {
-      return next(request);
-    }
-
-    let lastError: unknown;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const response = await next(request);
-
-        // Retry on 5xx server errors
-        if (response.status >= 500 && attempt < maxRetries) {
-          await delay(initialDelay * Math.pow(2, attempt));
-          continue;
-        }
-
-        return response;
-      } catch (error) {
-        lastError = error;
-
-        // Don't retry on non-retriable errors
-        if (error instanceof StorefrontError) {
-          if (error.code === ErrorCodes.TIMEOUT) {
-            // Timeouts are retriable
-          } else if (error.status >= 400 && error.status < 500) {
-            // 4xx errors are not retriable
-            throw error;
-          }
-        }
-
-        if (attempt < maxRetries) {
-          await delay(initialDelay * Math.pow(2, attempt));
-          continue;
-        }
-      }
-    }
-
-    throw lastError;
-  };
-}
-
-function delay(ms: number): Promise<void> {
-  // Add jitter: ±25%
-  const jitter = ms * 0.25 * (Math.random() * 2 - 1);
-  return new Promise(resolve => setTimeout(resolve, ms + jitter));
-}