@doswiftly/storefront-sdk 4.0.0

package/src/core/auth/handlers.ts

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

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

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

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

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

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

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

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