@doswiftly/storefront-sdk 4.0.0

package/src/core/format.ts

@@ -0,0 +1,254 @@
+/**
+ * Formatting Utilities
+ *
+ * Pure functions for formatting prices, dates, numbers.
+ * 0 runtime dependencies — works in Node.js, Edge, Deno, Bun.
+ */
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface PriceMoney {
+  amount: string;
+  currencyCode: string;
+}
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Currency symbols mapping */
+export const CURRENCY_SYMBOLS: Record<string, string> = {
+  PLN: 'zł',
+  EUR: '€',
+  USD: '$',
+  GBP: '£',
+  CHF: 'CHF',
+  CZK: 'Kč',
+  SEK: 'kr',
+  NOK: 'kr',
+  DKK: 'kr',
+  JPY: '¥',
+  CNY: '¥',
+  AUD: 'A$',
+  CAD: 'C$',
+};
+
+/** Currency locale mapping for proper formatting */
+export const CURRENCY_LOCALES: Record<string, string> = {
+  PLN: 'pl-PL',
+  EUR: 'de-DE',
+  USD: 'en-US',
+  GBP: 'en-GB',
+  CHF: 'de-CH',
+  CZK: 'cs-CZ',
+  SEK: 'sv-SE',
+  NOK: 'nb-NO',
+  DKK: 'da-DK',
+  JPY: 'ja-JP',
+  CNY: 'zh-CN',
+  AUD: 'en-AU',
+  CAD: 'en-CA',
+};
+
+// ============================================================================
+// FORMATTER CACHE (avoids re-creating Intl objects on every call)
+// ============================================================================
+
+const numberFormatCache = new Map<string, Intl.NumberFormat>();
+const dateFormatCache = new Map<string, Intl.DateTimeFormat>();
+
+function getCurrencyFormatter(locale: string, currency: string): Intl.NumberFormat {
+  const key = `${locale}:${currency}`;
+  let fmt = numberFormatCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency,
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    });
+    numberFormatCache.set(key, fmt);
+  }
+  return fmt;
+}
+
+function getNumberFormatter(locale: string): Intl.NumberFormat {
+  let fmt = numberFormatCache.get(locale);
+  if (!fmt) {
+    fmt = new Intl.NumberFormat(locale);
+    numberFormatCache.set(locale, fmt);
+  }
+  return fmt;
+}
+
+function getDateFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let fmt = dateFormatCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options);
+    dateFormatCache.set(key, fmt);
+  }
+  return fmt;
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Get currency symbol
+ */
+export function getCurrencySymbol(code: string): string {
+  return CURRENCY_SYMBOLS[code] || code;
+}
+
+// ============================================================================
+// PRICE FORMATTING
+// ============================================================================
+
+/**
+ * Format price with currency symbol
+ *
+ * @example
+ * ```typescript
+ * formatPrice({ amount: "99.99", currencyCode: "USD" })
+ * // => "$99.99"
+ * ```
+ */
+export function formatPrice(price: PriceMoney | null | undefined): string {
+  if (!price) return '';
+
+  const amount = parseFloat(price.amount);
+  const code = price.currencyCode;
+  const locale = CURRENCY_LOCALES[code] || 'en-US';
+
+  try {
+    return getCurrencyFormatter(locale, code).format(amount);
+  } catch {
+    const symbol = CURRENCY_SYMBOLS[code] || code;
+    return `${amount.toFixed(2)} ${symbol}`;
+  }
+}
+
+/**
+ * Format price range
+ *
+ * @example
+ * ```typescript
+ * formatPriceRange(
+ *   { amount: "10.00", currencyCode: "USD" },
+ *   { amount: "50.00", currencyCode: "USD" }
+ * )
+ * // => "$10.00 - $50.00"
+ * ```
+ */
+export function formatPriceRange(
+  minPrice: PriceMoney,
+  maxPrice: PriceMoney,
+): string {
+  if (minPrice.amount === maxPrice.amount) {
+    return formatPrice(minPrice);
+  }
+
+  return `${formatPrice(minPrice)} - ${formatPrice(maxPrice)}`;
+}
+
+/**
+ * Format amount with currency
+ *
+ * @example
+ * ```tsx
+ * const formatted = formatAmount("115.20", "EUR");
+ * // => "115,20 €"
+ * ```
+ */
+export function formatAmount(
+  amount: string | number,
+  currencyCode: string,
+): string {
+  const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
+  const locale = CURRENCY_LOCALES[currencyCode] || 'en-US';
+
+  try {
+    return getCurrencyFormatter(locale, currencyCode).format(numAmount);
+  } catch {
+    const symbol = CURRENCY_SYMBOLS[currencyCode] || currencyCode;
+    return `${numAmount.toFixed(2)} ${symbol}`;
+  }
+}
+
+// ============================================================================
+// DATE FORMATTING
+// ============================================================================
+
+/**
+ * Format date to locale string
+ *
+ * @example
+ * ```typescript
+ * formatDate(new Date())
+ * // => "Dec 9, 2025"
+ * ```
+ */
+export function formatDate(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+
+  return getDateFormatter('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  }).format(d);
+}
+
+/**
+ * Format date with time
+ *
+ * @example
+ * ```typescript
+ * formatDateTime(new Date())
+ * // => "Dec 9, 2025, 10:30 PM"
+ * ```
+ */
+export function formatDateTime(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+
+  return getDateFormatter('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(d);
+}
+
+// ============================================================================
+// NUMBER FORMATTING
+// ============================================================================
+
+/**
+ * Format number with thousands separator
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234567)
+ * // => "1,234,567"
+ * ```
+ */
+export function formatNumber(num: number): string {
+  return getNumberFormatter('en-US').format(num);
+}
+
+/**
+ * Format percentage
+ *
+ * @example
+ * ```typescript
+ * formatPercentage(0.15)
+ * // => "15%"
+ * ```
+ */
+export function formatPercentage(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}

package/src/core/helpers/assert-no-user-errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Auto-throw on userErrors — used internally by CartClient and AuthClient.
+ *
+ * Frontend code doesn't need to manually check `if (userErrors.length)`.
+ */
+
+import type { UserError } from '../client/types';
+import { StorefrontError, ErrorCodes } from '../errors';
+
+export function assertNoUserErrors(
+  result: { userErrors?: UserError[] | null },
+): void {
+  if (result.userErrors && result.userErrors.length > 0) {
+    const firstError = result.userErrors[0];
+    throw new StorefrontError({
+      code: ErrorCodes.USER_ERROR,
+      message: firstError.message,
+      userErrors: result.userErrors,
+    });
+  }
+}

package/src/core/helpers/normalize-connection.ts

@@ -0,0 +1,48 @@
+/**
+ * Relay-style GraphQL connection normalizer.
+ *
+ * Converts `{ edges: [{ node }], pageInfo, totalCount }` → flat array.
+ * Pure function, 0 deps, works everywhere.
+ */
+
+export interface ConnectionEdge<T> {
+  node: T;
+  cursor: string;
+}
+
+export interface ConnectionPageInfo {
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  startCursor?: string | null;
+  endCursor?: string | null;
+}
+
+export interface Connection<T> {
+  edges: ConnectionEdge<T>[];
+  pageInfo: ConnectionPageInfo;
+  totalCount?: number;
+}
+
+export interface NormalizedConnection<T> {
+  items: T[];
+  pageInfo: ConnectionPageInfo;
+  totalCount?: number;
+}
+
+/**
+ * Normalize a GraphQL Relay connection to a flat array.
+ *
+ * @example
+ * ```typescript
+ * const { items, pageInfo, totalCount } = normalizeConnection(data.products);
+ * ```
+ */
+export function normalizeConnection<T>(
+  connection: Connection<T>,
+): NormalizedConnection<T> {
+  return {
+    items: connection.edges.map((edge) => edge.node),
+    pageInfo: connection.pageInfo,
+    totalCount: connection.totalCount,
+  };
+}

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

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

@@ -0,0 +1,148 @@
+/**
+ * @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 { retryMiddleware, type RetryOptions } from './middleware/retry';
+export { timeoutMiddleware, type TimeoutOptions } from './middleware/timeout';
+export { errorMiddleware } from './middleware/errors';
+
+// 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';
+
+// 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';
+
+// Utilities
+export { getOperationName } from './client/operation-name';
+export { hashQuery } from './client/hash';

package/src/core/middleware/auth.ts

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

@@ -0,0 +1,26 @@
+/**
+ * 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';
+
+export function currencyMiddleware(
+  getCurrency: () => string | null | undefined,
+): Middleware {
+  return (request, next) => {
+    const currency = getCurrency();
+    if (currency) {
+      request.headers['X-Preferred-Currency'] = currency;
+    }
+    return next(request);
+  };
+}

package/src/core/middleware/errors.ts

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