@doswiftly/storefront-sdk 4.3.0 → 4.5.0

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

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

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

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

@@ -1,102 +0,0 @@
-/**
- * Cache strategies — functions (not constants) with override support.
- *
- * Inspired by Shopify Hydrogen's caching strategies.
- *
- * @example
- * ```typescript
- * import { cacheLong, cacheShort } from '@doswiftly/storefront-sdk';
- *
- * // Default
- * const data = await client.query(ShopQuery, {}, cacheLong());
- *
- * // Override with tags (Next.js revalidateTag)
- * const data = await client.query(ProductQuery, { slug }, cacheLong({ tags: ['product', slug] }));
- * ```
- */
-
-import type { CacheStrategy, CacheOptions } from './client/types';
-
-export interface CacheOverrides {
-  /** Override max-age (seconds) */
-  maxAge?: number;
-  /** Override stale-while-revalidate (seconds) */
-  staleWhileRevalidate?: number;
-  /** Cache tags (for Next.js revalidateTag) */
-  tags?: string[];
-}
-
-/**
- * No caching — every request hits the server.
- * Use for: Cart, Customer data, real-time inventory.
- */
-export function cacheNone(overrides?: CacheOverrides): CacheStrategy {
-  return {
-    maxAge: 0,
-    mode: 'no-store',
-    tags: overrides?.tags,
-  };
-}
-
-/**
- * Short cache — 1s max-age, 9s stale-while-revalidate (10s total).
- * Use for: Product listings, collections, search results.
- */
-export function cacheShort(overrides?: CacheOverrides): CacheStrategy {
-  return {
-    maxAge: overrides?.maxAge ?? 1,
-    staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 9,
-    mode: 'public',
-    tags: overrides?.tags,
-  };
-}
-
-/**
- * Long cache — 1h max-age, 23h stale-while-revalidate (24h total).
- * Use for: Static content, shop info, rarely changing data.
- */
-export function cacheLong(overrides?: CacheOverrides): CacheStrategy {
-  return {
-    maxAge: overrides?.maxAge ?? 3600,
-    staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 82800,
-    mode: 'public',
-    tags: overrides?.tags,
-  };
-}
-
-/**
- * Private cache — 1s max-age, no sharing between users.
- * Use for: Personalized content, customer-specific data.
- */
-export function cachePrivate(overrides?: CacheOverrides): CacheStrategy {
-  return {
-    maxAge: overrides?.maxAge ?? 1,
-    staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 9,
-    mode: 'private',
-    tags: overrides?.tags,
-  };
-}
-
-/**
- * Custom cache — full control over all options.
- */
-export function cacheCustom(options: CacheOptions): CacheStrategy {
-  return { ...options };
-}
-
-/**
- * Generate Cache-Control header string from cache strategy.
- */
-export function generateCacheControlHeader(cache: CacheStrategy): string {
-  if (cache.mode === 'no-store') {
-    return 'no-store, no-cache, must-revalidate';
-  }
-
-  const parts: string[] = [cache.mode, `max-age=${cache.maxAge}`];
-
-  if (cache.staleWhileRevalidate !== undefined) {
-    parts.push(`stale-while-revalidate=${cache.staleWhileRevalidate}`);
-  }
-
-  return parts.join(', ');
-}

package/src/core/cart/cart-client.ts

@@ -1,150 +0,0 @@
-/**
- * CartClient — plain async API for cart operations (no React, no React Query).
- *
- * Wraps StorefrontClient.mutate/query with typed operations.
- * Auto-throws on userErrors via assertNoUserErrors.
- *
- * @example
- * ```typescript
- * const cartClient = new CartClient(storefrontClient);
- *
- * const cart = await cartClient.create();
- * const updated = await cartClient.addItem(cart.id, [
- *   { merchandiseId: 'variant-123', quantity: 1 }
- * ]);
- * ```
- */
-
-import type { StorefrontClient } from '../client/types';
-import type {
-  Cart,
-  CartCreateInput,
-  CartLineInput,
-  CartLineUpdateInput,
-  CartBuyerIdentityInput,
-} from './types';
-import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
-import {
-  CART_QUERY,
-  CART_CREATE,
-  CART_LINES_ADD,
-  CART_LINES_UPDATE,
-  CART_LINES_REMOVE,
-  CART_DISCOUNT_CODES_UPDATE,
-  CART_NOTE_UPDATE,
-  CART_BUYER_IDENTITY_UPDATE,
-} from '../operations/cart';
-
-// ---------------------------------------------------------------------------
-// Response types (internal — match the GraphQL mutation shapes)
-// ---------------------------------------------------------------------------
-
-interface CartMutationResult {
-  cart: Cart | null;
-  userErrors: Array<{ message: string; field?: string[]; code?: string }>;
-}
-
-interface CartQueryResult {
-  cart: Cart | null;
-}
-
-export class CartClient {
-  constructor(private readonly client: StorefrontClient) {}
-
-  /**
-   * Fetch existing cart by ID.
-   * Returns null if cart doesn't exist or has expired.
-   */
-  async get(cartId: string): Promise<Cart | null> {
-    const data = await this.client.query<CartQueryResult>(
-      CART_QUERY,
-      { id: cartId },
-    );
-    return data.cart;
-  }
-
-  /**
-   * Create a new cart, optionally with initial lines.
-   */
-  async create(input?: CartCreateInput): Promise<Cart> {
-    const data = await this.client.mutate<{ cartCreate: CartMutationResult }>(
-      CART_CREATE,
-      { input: input ?? {} },
-    );
-    assertNoUserErrors(data.cartCreate);
-    return data.cartCreate.cart!;
-  }
-
-  /**
-   * Add line items to an existing cart.
-   */
-  async addItems(cartId: string, lines: CartLineInput[]): Promise<Cart> {
-    const data = await this.client.mutate<{ cartLinesAdd: CartMutationResult }>(
-      CART_LINES_ADD,
-      { cartId, lines },
-    );
-    assertNoUserErrors(data.cartLinesAdd);
-    return data.cartLinesAdd.cart!;
-  }
-
-  /**
-   * Update line items (quantity, attributes).
-   */
-  async updateItems(cartId: string, lines: CartLineUpdateInput[]): Promise<Cart> {
-    const data = await this.client.mutate<{ cartLinesUpdate: CartMutationResult }>(
-      CART_LINES_UPDATE,
-      { cartId, lines },
-    );
-    assertNoUserErrors(data.cartLinesUpdate);
-    return data.cartLinesUpdate.cart!;
-  }
-
-  /**
-   * Remove line items by their line IDs.
-   */
-  async removeItems(cartId: string, lineIds: string[]): Promise<Cart> {
-    const data = await this.client.mutate<{ cartLinesRemove: CartMutationResult }>(
-      CART_LINES_REMOVE,
-      { cartId, lineIds },
-    );
-    assertNoUserErrors(data.cartLinesRemove);
-    return data.cartLinesRemove.cart!;
-  }
-
-  /**
-   * Update discount codes (replaces all existing codes).
-   * Pass empty array to clear discounts.
-   */
-  async updateDiscountCodes(cartId: string, discountCodes: string[]): Promise<Cart> {
-    const data = await this.client.mutate<{ cartDiscountCodesUpdate: CartMutationResult }>(
-      CART_DISCOUNT_CODES_UPDATE,
-      { cartId, discountCodes },
-    );
-    assertNoUserErrors(data.cartDiscountCodesUpdate);
-    return data.cartDiscountCodesUpdate.cart!;
-  }
-
-  /**
-   * Update cart note / gift message.
-   */
-  async updateNote(cartId: string, note: string): Promise<Cart> {
-    const data = await this.client.mutate<{ cartNoteUpdate: CartMutationResult }>(
-      CART_NOTE_UPDATE,
-      { cartId, note },
-    );
-    assertNoUserErrors(data.cartNoteUpdate);
-    return data.cartNoteUpdate.cart!;
-  }
-
-  /**
-   * Update buyer identity (email, phone, country, customer link).
-   */
-  async updateBuyerIdentity(cartId: string, buyerIdentity: CartBuyerIdentityInput): Promise<Cart> {
-    const data = await this.client.mutate<{ cartBuyerIdentityUpdate: CartMutationResult }>(
-      CART_BUYER_IDENTITY_UPDATE,
-      { cartId, buyerIdentity },
-    );
-    assertNoUserErrors(data.cartBuyerIdentityUpdate);
-    return data.cartBuyerIdentityUpdate.cart!;
-  }
-}

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

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

@@ -1,104 +0,0 @@
-/**
- * Cart types — manual (no codegen).
- *
- * These match the backend storefront-graphql Cart type.
- */
-
-export interface Money {
-  amount: string;
-  currencyCode: string;
-}
-
-export interface CartCost {
-  totalAmount: Money;
-  subtotalAmount: Money;
-  totalTaxAmount: Money | null;
-  totalDutyAmount: Money | null;
-}
-
-export interface CartLineCost {
-  totalAmount: Money;
-  amountPerQuantity: Money;
-  compareAtAmountPerQuantity: Money | null;
-}
-
-export interface CartLineMerchandise {
-  id: string;
-  title: string;
-  sku: string | null;
-  image: { url: string; altText: string | null } | null;
-  price: Money;
-  compareAtPrice: Money | null;
-}
-
-export interface CartLine {
-  id: string;
-  quantity: number;
-  merchandise: CartLineMerchandise;
-  cost: CartLineCost;
-  attributes: Array<{ key: string; value: string }>;
-  productId: string;
-  productTitle: string;
-  productHandle: string;
-}
-
-export interface CartDiscountCode {
-  code: string;
-  applicable: boolean;
-}
-
-export interface CartDiscountAllocation {
-  discountedAmount: Money;
-}
-
-export interface CartBuyerIdentity {
-  email: string | null;
-  phone: string | null;
-  countryCode: string | null;
-}
-
-export interface Cart {
-  id: string;
-  checkoutUrl: string | null;
-  totalQuantity: number;
-  note: string | null;
-  createdAt: string;
-  updatedAt: string;
-  cost: CartCost;
-  lines: { edges: Array<{ node: CartLine }> };
-  buyerIdentity: CartBuyerIdentity | null;
-  discountCodes: CartDiscountCode[];
-  discountAllocations: CartDiscountAllocation[];
-  attributes: Array<{ key: string; value: string }>;
-}
-
-// ---------------------------------------------------------------------------
-// Input types
-// ---------------------------------------------------------------------------
-
-export interface CartLineInput {
-  merchandiseId: string;
-  quantity?: number;
-  attributes?: Array<{ key: string; value: string }>;
-}
-
-export interface CartLineUpdateInput {
-  id: string;
-  quantity: number;
-  attributes?: Array<{ key: string; value: string }>;
-}
-
-export interface CartCreateInput {
-  lines?: CartLineInput[];
-  buyerIdentity?: CartBuyerIdentityInput;
-  discountCodes?: string[];
-  note?: string;
-  attributes?: Array<{ key: string; value: string }>;
-}
-
-export interface CartBuyerIdentityInput {
-  email?: string;
-  phone?: string;
-  countryCode?: string;
-  customerId?: string;
-}

package/src/core/client/compose.ts

@@ -1,15 +0,0 @@
-/**
- * Compose middleware chain using reduceRight (Hydrogen pattern).
- *
- * Middleware execute in order: first registered runs first.
- * Each can modify request, modify response, retry, or short-circuit.
- */
-
-import type { Middleware, ExecuteFn } from './types';
-
-export function compose(middlewares: Middleware[], execute: ExecuteFn): ExecuteFn {
-  return middlewares.reduceRight<ExecuteFn>(
-    (next, mw) => (req) => mw(req, next),
-    execute,
-  );
-}

package/src/core/client/create-client.ts

@@ -1,129 +0,0 @@
-/**
- * createStorefrontClient — transport factory (Hydrogen pattern).
- *
- * Creates a framework-agnostic GraphQL client with:
- * - Middleware pipeline (composable, lazy)
- * - Request deduplication (same-tick queries)
- * - TypedDocumentString support (Saleor/client-preset)
- * - Plain string queries (for custom operations)
- * - Debug mode
- *
- * 0 runtime dependencies.
- */
-
-import type {
-  StorefrontClientConfig,
-  StorefrontClient,
-  Middleware,
-  CacheStrategy,
-  TypedDocumentString,
-  ExecuteFn,
-} from './types';
-import { createExecute } from './execute';
-import { compose } from './compose';
-import { dedupe } from './dedupe';
-import { hashQuery } from './hash';
-import { getOperationName } from './operation-name';
-
-export function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient {
-  const {
-    apiUrl,
-    shopSlug,
-    defaultHeaders = {},
-    middleware: initialMiddleware = [],
-    fetch: customFetch = globalThis.fetch,
-    debug = false,
-  } = config;
-
-  const endpoint = `${apiUrl.replace(/\/$/, '')}/storefront/graphql`;
-
-  // Mutable middleware list — use() adds to it, invalidates compiled pipeline
-  const middlewares: Middleware[] = [...initialMiddleware];
-  let compiledPipeline: ExecuteFn | null = null;
-
-  // Create the innermost execute function (native fetch)
-  const innerExecute = createExecute({ endpoint, fetch: customFetch, debug });
-
-  /**
-   * Get or build the compiled middleware pipeline (lazy).
-   * Rebuilt on first call and after use() is called.
-   */
-  function getPipeline(): ExecuteFn {
-    if (!compiledPipeline) {
-      compiledPipeline = middlewares.length > 0
-        ? compose(middlewares, innerExecute)
-        : innerExecute;
-    }
-    return compiledPipeline;
-  }
-
-  /**
-   * Resolve query string from TypedDocumentString or plain string.
-   */
-  function resolveQuery(document: TypedDocumentString | string): string {
-    return typeof document === 'string' ? document : document.toString();
-  }
-
-  /**
-   * Core request execution — shared by query() and mutate().
-   */
-  async function request<T>(
-    document: TypedDocumentString<T, unknown> | string,
-    variables?: Record<string, unknown>,
-    isMutation: boolean = false,
-    cache?: CacheStrategy,
-  ): Promise<T> {
-    const query = resolveQuery(document);
-    const operationName = getOperationName(query);
-    const pipeline = getPipeline();
-
-    const headers: Record<string, string> = {
-      'X-Shop-Slug': shopSlug,
-      ...defaultHeaders,
-    };
-
-    if (operationName !== 'anonymous') {
-      headers['X-Operation-Name'] = operationName;
-    }
-
-    const graphqlRequest = {
-      query,
-      variables,
-      operationName,
-      headers,
-      isMutation,
-      cache,
-    };
-
-    // Dedupe queries (not mutations) in the same tick
-    const executeFn = () => pipeline(graphqlRequest);
-
-    const response = isMutation
-      ? await executeFn()
-      : await dedupe(hashQuery(query, variables), executeFn);
-
-    return response.data as T;
-  }
-
-  return {
-    query<T, V>(
-      document: TypedDocumentString<T, V> | string,
-      variables?: V,
-      cache?: CacheStrategy,
-    ): Promise<T> {
-      return request<T>(document as TypedDocumentString<T, unknown>, variables as Record<string, unknown>, false, cache);
-    },
-
-    mutate<T, V>(
-      document: TypedDocumentString<T, V> | string,
-      variables?: V,
-    ): Promise<T> {
-      return request<T>(document as TypedDocumentString<T, unknown>, variables as Record<string, unknown>, true);
-    },
-
-    use(middleware: Middleware): void {
-      middlewares.push(middleware);
-      compiledPipeline = null; // Invalidate — rebuild on next request
-    },
-  };
-}

package/src/core/client/dedupe.ts

@@ -1,19 +0,0 @@
-/**
- * Request deduplication — identical queries in the same tick share one fetch.
- *
- * Key = hashQuery(query, variables). Only applies to queries, not mutations.
- */
-
-const pending = new Map<string, Promise<unknown>>();
-
-export function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T> {
-  const existing = pending.get(key);
-  if (existing) return existing as Promise<T>;
-
-  const promise = fn().finally(() => {
-    pending.delete(key);
-  });
-
-  pending.set(key, promise);
-  return promise;
-}