@doswiftly/storefront-sdk 4.3.0 → 4.5.0

package/src/core/client/execute.ts

@@ -1,70 +0,0 @@
-/**
- * Native fetch transport — 0 runtime dependencies.
- *
- * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
- * Error normalization is handled by error middleware, NOT here.
- */
-
-import type { GraphQLRequest, GraphQLResponse, GraphQLErrorInfo } from './types';
-
-export interface ExecuteConfig {
-  /** GraphQL endpoint URL */
-  endpoint: string;
-  /** Custom fetch implementation */
-  fetch: typeof globalThis.fetch;
-  /** Enable debug logging */
-  debug: boolean;
-}
-
-/**
- * Create the innermost execute function for the middleware pipeline.
- */
-export function createExecute(config: ExecuteConfig) {
-  const { endpoint, fetch: fetchFn, debug } = config;
-
-  return async function execute(request: GraphQLRequest): Promise<GraphQLResponse> {
-    const { query, variables, headers, signal, operationName } = request;
-
-    if (debug) {
-      console.log('[StorefrontSDK]', operationName ?? 'request', { variables });
-    }
-
-    const body: Record<string, unknown> = { query };
-    if (variables && Object.keys(variables).length > 0) {
-      body.variables = variables;
-    }
-    if (operationName) {
-      body.operationName = operationName;
-    }
-
-    const response = await fetchFn(endpoint, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        ...headers,
-      },
-      body: JSON.stringify(body),
-      signal,
-    });
-
-    const json = await response.json() as {
-      data?: unknown;
-      errors?: GraphQLErrorInfo[];
-    };
-
-    if (debug) {
-      console.log('[StorefrontSDK]', operationName ?? 'response', {
-        status: response.status,
-        hasErrors: !!json.errors?.length,
-      });
-    }
-
-    return {
-      data: json.data as never,
-      errors: json.errors,
-      status: response.status,
-      headers: response.headers,
-    };
-  };
-}

package/src/core/client/hash.ts

@@ -1,21 +0,0 @@
-/**
- * Stable query hashing for request deduplication.
- *
- * Sorts object keys so `{a:1,b:2}` and `{b:2,a:1}` produce the same hash.
- */
-
-function stableStringify(value: unknown): string {
-  if (value === null || value === undefined) return '';
-  if (typeof value !== 'object') return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    return '[' + value.map(stableStringify).join(',') + ']';
-  }
-  const keys = Object.keys(value as Record<string, unknown>).sort();
-  return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify((value as Record<string, unknown>)[k])).join(',') + '}';
-}
-
-export function hashQuery(query: string, variables?: Record<string, unknown>): string {
-  const queryPart = query.trim();
-  const varsPart = variables ? stableStringify(variables) : '';
-  return queryPart + '::' + varsPart;
-}

package/src/core/client/operation-name.ts

@@ -1,12 +0,0 @@
-/**
- * Auto-extract operation name from a GraphQL query string.
- *
- * Used for: X-Operation-Name header (debugging), cache tags, logging.
- */
-
-const OPERATION_RE = /(?:query|mutation|subscription)\s+(\w+)/;
-
-export function getOperationName(query: string): string {
-  const match = query.match(OPERATION_RE);
-  return match?.[1] ?? 'anonymous';
-}

package/src/core/client/types.ts

@@ -1,171 +0,0 @@
-/**
- * Core types for Storefront SDK transport layer.
- *
- * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
- */
-
-// ---------------------------------------------------------------------------
-// TypedDocumentString (Saleor / client-preset pattern)
-// ---------------------------------------------------------------------------
-
-/**
- * A branded string carrying result & variable types.
- * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
- *
- * SDK also accepts plain strings — TypedDocumentString is purely for DX.
- */
-export class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String {
-  /** Type-level brand — never used at runtime */
-  __apiType?: (variables: TVariables) => TResult;
-
-  constructor(value: string, public __meta__?: { hash: string }) {
-    super(value);
-  }
-
-  override toString(): string {
-    return this.valueOf();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// GraphQL request / response
-// ---------------------------------------------------------------------------
-
-export interface GraphQLRequest {
-  /** GraphQL query or mutation string */
-  query: string;
-  /** Operation variables */
-  variables?: Record<string, unknown>;
-  /** Operation name (auto-extracted if omitted) */
-  operationName?: string;
-  /** Request headers (merged: default < middleware < request) */
-  headers: Record<string, string>;
-  /** AbortSignal for cancellation */
-  signal?: AbortSignal;
-  /** Whether this is a mutation (affects retry, cache) */
-  isMutation: boolean;
-  /** Cache strategy override */
-  cache?: CacheStrategy;
-}
-
-export interface GraphQLResponse<T = unknown> {
-  /** Parsed response data */
-  data: T;
-  /** GraphQL errors (if any) */
-  errors?: GraphQLErrorInfo[];
-  /** HTTP status code */
-  status: number;
-  /** Raw response headers */
-  headers: Headers;
-}
-
-export interface GraphQLErrorInfo {
-  message: string;
-  locations?: Array<{ line: number; column: number }>;
-  path?: Array<string | number>;
-  extensions?: Record<string, unknown>;
-}
-
-// ---------------------------------------------------------------------------
-// User errors (cart mutations, auth mutations, etc.)
-// ---------------------------------------------------------------------------
-
-export interface UserError {
-  message: string;
-  field?: string[];
-  code?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Middleware
-// ---------------------------------------------------------------------------
-
-/**
- * Execute function — the innermost (or next) handler in the pipeline.
- */
-export type ExecuteFn = (request: GraphQLRequest) => Promise<GraphQLResponse>;
-
-/**
- * Middleware function — receives the request and the next handler.
- *
- * Can modify request, modify response, short-circuit, retry, etc.
- *
- * @example
- * ```typescript
- * const authMiddleware: Middleware = (req, next) => {
- *   req.headers['Authorization'] = `Bearer ${getToken()}`;
- *   return next(req);
- * };
- * ```
- */
-export type Middleware = (request: GraphQLRequest, next: ExecuteFn) => Promise<GraphQLResponse>;
-
-// ---------------------------------------------------------------------------
-// Cache strategy
-// ---------------------------------------------------------------------------
-
-export interface CacheOptions {
-  /** Max age in seconds */
-  maxAge: number;
-  /** Stale-while-revalidate in seconds */
-  staleWhileRevalidate?: number;
-  /** Cache mode */
-  mode: 'public' | 'private' | 'no-store';
-  /** Cache tags (for Next.js revalidateTag) */
-  tags?: string[];
-}
-
-export type CacheStrategy = CacheOptions;
-
-// ---------------------------------------------------------------------------
-// Client config
-// ---------------------------------------------------------------------------
-
-export interface StorefrontClientConfig {
-  /** GraphQL API URL (e.g. 'https://api.doswiftly.pl') */
-  apiUrl: string;
-  /** Shop slug for multi-tenant routing */
-  shopSlug: string;
-  /** Default headers for all requests */
-  defaultHeaders?: Record<string, string>;
-  /** Middleware pipeline */
-  middleware?: Middleware[];
-  /** Custom fetch implementation (polyfill, test mocks, edge) */
-  fetch?: typeof globalThis.fetch;
-  /** Enable debug logging (request/response in dev) */
-  debug?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Client interface
-// ---------------------------------------------------------------------------
-
-export interface StorefrontClient {
-  /**
-   * Execute a typed GraphQL query.
-   *
-   * Accepts TypedDocumentString (from codegen) or plain string.
-   */
-  query<T = unknown, V = Record<string, unknown>>(
-    document: TypedDocumentString<T, V> | string,
-    variables?: V,
-    cache?: CacheStrategy,
-  ): Promise<T>;
-
-  /**
-   * Execute a typed GraphQL mutation.
-   *
-   * Mutations are never cached and never retried by retry middleware.
-   */
-  mutate<T = unknown, V = Record<string, unknown>>(
-    document: TypedDocumentString<T, V> | string,
-    variables?: V,
-  ): Promise<T>;
-
-  /**
-   * Add middleware to the pipeline (imperative API).
-   *
-   * Invalidates the compiled pipeline — next request re-composes.
-   */
-  use(middleware: Middleware): void;
-}

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

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

@@ -1,67 +0,0 @@
-/**
- * StorefrontError — unified error class for all SDK errors.
- *
- * Normalizes GraphQL errors, network errors, user errors, and timeouts
- * into a single throwable type with structured data.
- */
-
-import type { GraphQLErrorInfo, UserError } from './client/types';
-
-export interface StorefrontErrorOptions {
-  /** Error code for programmatic handling */
-  code: string;
-  /** Human-readable message */
-  message: string;
-  /** HTTP status code (0 for network errors) */
-  status?: number;
-  /** GraphQL-level errors from the response */
-  graphqlErrors?: GraphQLErrorInfo[];
-  /** User errors from mutations (field-level validation) */
-  userErrors?: UserError[];
-  /** Original error (if wrapping) */
-  cause?: unknown;
-}
-
-export class StorefrontError extends Error {
-  readonly code: string;
-  readonly status: number;
-  readonly graphqlErrors: GraphQLErrorInfo[];
-  readonly userErrors: UserError[];
-
-  constructor(options: StorefrontErrorOptions) {
-    super(options.message, { cause: options.cause });
-    this.name = 'StorefrontError';
-    this.code = options.code;
-    this.status = options.status ?? 0;
-    this.graphqlErrors = options.graphqlErrors ?? [];
-    this.userErrors = options.userErrors ?? [];
-  }
-
-  /** True if this error contains user errors (field-level validation) */
-  get hasUserErrors(): boolean {
-    return this.userErrors.length > 0;
-  }
-
-  /** True if this is a network error (no HTTP response) */
-  get isNetworkError(): boolean {
-    return this.code === 'NETWORK_ERROR';
-  }
-
-  /** True if the request timed out */
-  get isTimeout(): boolean {
-    return this.code === 'TIMEOUT';
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Error codes
-// ---------------------------------------------------------------------------
-
-export const ErrorCodes = {
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  TIMEOUT: 'TIMEOUT',
-  HTTP_ERROR: 'HTTP_ERROR',
-  GRAPHQL_ERROR: 'GRAPHQL_ERROR',
-  USER_ERROR: 'USER_ERROR',
-  NO_DATA: 'NO_DATA',
-} as const;

package/src/core/format.ts

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

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

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