@doswiftly/storefront-sdk 4.0.0

package/src/core/middleware/retry.ts

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

package/src/core/middleware/timeout.ts

@@ -0,0 +1,61 @@
+/**
+ * Timeout middleware — aborts request after timeout via AbortController.
+ *
+ * Edge-safe (no Node.js APIs). Default: 5 seconds.
+ *
+ * @example
+ * ```typescript
+ * import { timeoutMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * client.use(timeoutMiddleware({ timeout: 10000 })); // 10s
+ * ```
+ */
+
+import type { Middleware } from '../client/types';
+import { StorefrontError, ErrorCodes } from '../errors';
+
+export interface TimeoutOptions {
+  /** Timeout in milliseconds (default: 5000) */
+  timeout?: number;
+}
+
+export function timeoutMiddleware(options: TimeoutOptions = {}): Middleware {
+  const { timeout = 5000 } = options;
+
+  return async (request, next) => {
+    const controller = new AbortController();
+
+    // If request already has a signal, link them
+    if (request.signal) {
+      if (request.signal.aborted) {
+        controller.abort(request.signal.reason);
+      } else {
+        request.signal.addEventListener('abort', () => {
+          controller.abort(request.signal!.reason);
+        }, { once: true });
+      }
+    }
+
+    request.signal = controller.signal;
+
+    const timer = setTimeout(() => {
+      controller.abort(new Error(`Request timed out after ${timeout}ms`));
+    }, timeout);
+
+    try {
+      const response = await next(request);
+      return response;
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new StorefrontError({
+          code: ErrorCodes.TIMEOUT,
+          message: `Request timed out after ${timeout}ms`,
+          cause: error,
+        });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}

package/src/core/operations/auth.ts

@@ -0,0 +1,123 @@
+/**
+ * Auth/Customer GraphQL operations — manual query strings (no codegen).
+ *
+ * These match the backend storefront-graphql schema exactly.
+ */
+
+// ---------------------------------------------------------------------------
+// Fragments
+// ---------------------------------------------------------------------------
+
+const CUSTOMER_ACCESS_TOKEN_FRAGMENT = `
+  fragment CustomerAccessTokenFields on CustomerAccessToken {
+    accessToken
+    expiresAt
+  }
+`;
+
+const USER_ERROR_FRAGMENT = `
+  fragment UserErrorFields on UserError {
+    message
+    field
+    code
+  }
+`;
+
+const CUSTOMER_FRAGMENT = `
+  fragment CustomerFields on Customer {
+    id
+    email
+    firstName
+    lastName
+    displayName
+    phone
+    emailVerified
+    emailMarketingState
+    defaultAddress {
+      id
+      address1
+      address2
+      city
+      company
+      country
+      countryCode
+      firstName
+      lastName
+      phone
+      province
+      provinceCode
+      zip
+      isDefault
+    }
+    ordersCount
+    totalSpent {
+      amount
+      currencyCode
+    }
+    createdAt
+    updatedAt
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+export const CUSTOMER_LOGIN = `
+  mutation CustomerLogin($input: CustomerAccessTokenCreateInput!) {
+    customerAccessTokenCreate(input: $input) {
+      customerAccessToken { ...CustomerAccessTokenFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CUSTOMER_ACCESS_TOKEN_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CUSTOMER_LOGOUT = `
+  mutation CustomerLogout($customerAccessToken: String!) {
+    customerAccessTokenDelete(customerAccessToken: $customerAccessToken) {
+      deletedAccessToken
+      deletedCustomerAccessTokenId
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CUSTOMER_TOKEN_RENEW = `
+  mutation CustomerTokenRenew($customerAccessToken: String!) {
+    customerAccessTokenRenew(customerAccessToken: $customerAccessToken) {
+      customerAccessToken { ...CustomerAccessTokenFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CUSTOMER_ACCESS_TOKEN_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CUSTOMER_CREATE = `
+  mutation CustomerCreate($input: CustomerCreateInput!) {
+    customerCreate(input: $input) {
+      customer { ...CustomerFields }
+      customerAccessToken { ...CustomerAccessTokenFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CUSTOMER_FRAGMENT}
+  ${CUSTOMER_ACCESS_TOKEN_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const CUSTOMER_QUERY = `
+  query Customer($customerAccessToken: String!) {
+    customer(customerAccessToken: $customerAccessToken) {
+      ...CustomerFields
+    }
+  }
+  ${CUSTOMER_FRAGMENT}
+`;

package/src/core/operations/cart.ts

@@ -0,0 +1,185 @@
+/**
+ * Cart GraphQL operations — manual query strings (no codegen).
+ *
+ * These match the backend storefront-graphql schema exactly.
+ * Cart mutations always return full Cart + userErrors.
+ */
+
+// ---------------------------------------------------------------------------
+// Fragments
+// ---------------------------------------------------------------------------
+
+const MONEY_FRAGMENT = `
+  fragment Money on Money {
+    amount
+    currencyCode
+  }
+`;
+
+const CART_COST_FRAGMENT = `
+  fragment CartCost on CartCost {
+    totalAmount { ...Money }
+    subtotalAmount { ...Money }
+    totalTaxAmount { ...Money }
+    totalDutyAmount { ...Money }
+  }
+`;
+
+const CART_LINE_FRAGMENT = `
+  fragment CartLineFields on CartLine {
+    id
+    quantity
+    merchandise {
+      id
+      title
+      sku
+      image { url altText }
+      price { ...Money }
+      compareAtPrice { ...Money }
+    }
+    cost {
+      totalAmount { ...Money }
+      amountPerQuantity { ...Money }
+      compareAtAmountPerQuantity { ...Money }
+    }
+    attributes { key value }
+    productId
+    productTitle
+    productHandle
+  }
+`;
+
+const CART_FRAGMENT = `
+  fragment CartFields on Cart {
+    id
+    checkoutUrl
+    totalQuantity
+    note
+    createdAt
+    updatedAt
+    cost { ...CartCost }
+    lines(first: 100) {
+      edges {
+        node { ...CartLineFields }
+      }
+    }
+    buyerIdentity {
+      email
+      phone
+      countryCode
+    }
+    discountCodes {
+      code
+      applicable
+    }
+    discountAllocations {
+      discountedAmount { ...Money }
+    }
+    attributes { key value }
+  }
+  ${MONEY_FRAGMENT}
+  ${CART_COST_FRAGMENT}
+  ${CART_LINE_FRAGMENT}
+`;
+
+const USER_ERROR_FRAGMENT = `
+  fragment UserErrorFields on UserError {
+    message
+    field
+    code
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const CART_QUERY = `
+  query Cart($id: ID!) {
+    cart(id: $id) {
+      ...CartFields
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+export const CART_CREATE = `
+  mutation CartCreate($input: CartCreateInput) {
+    cartCreate(input: $input) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_LINES_ADD = `
+  mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+    cartLinesAdd(cartId: $cartId, lines: $lines) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_LINES_UPDATE = `
+  mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartLinesUpdate(cartId: $cartId, lines: $lines) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_LINES_REMOVE = `
+  mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_DISCOUNT_CODES_UPDATE = `
+  mutation CartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]!) {
+    cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_NOTE_UPDATE = `
+  mutation CartNoteUpdate($cartId: ID!, $note: String!) {
+    cartNoteUpdate(cartId: $cartId, note: $note) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;
+
+export const CART_BUYER_IDENTITY_UPDATE = `
+  mutation CartBuyerIdentityUpdate($cartId: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
+    cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
+      cart { ...CartFields }
+      userErrors { ...UserErrorFields }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`;

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @doswiftly/storefront-sdk v4.0.0
+ *
+ * Layered SDK — Hydrogen-aligned architecture.
+ *
+ * Entry points:
+ *   "."              → Core (framework-agnostic, 0 deps)
+ *   "./react"        → React adapter (providers, stores, hooks)
+ *   "./react/stores" → Zustand stores (direct import)
+ *   "./react/server" → Server-side client factory
+ *   "./cache"        → Cache strategies
+ *
+ * @example Core (CLI, Edge, Remix, Astro — no React)
+ * ```typescript
+ * import { createStorefrontClient, CartClient, errorMiddleware } from '@doswiftly/storefront-sdk';
+ * ```
+ *
+ * @example React
+ * ```tsx
+ * import { StorefrontProvider, useAuth, useCartManager } from '@doswiftly/storefront-sdk/react';
+ * ```
+ */
+
+// Re-export everything from core
+export * from './core';

package/src/react/cookies.ts

@@ -0,0 +1,54 @@
+/**
+ * Cookie utilities for SDK consumers.
+ *
+ * Simple, framework-agnostic cookie read/write for client-side.
+ * For Next.js server-side cookies, use `cookies()` from next/headers.
+ */
+
+/**
+ * Get cookie value by name (client-side only).
+ */
+export function getCookie(name: string): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+/**
+ * Set cookie (client-side only).
+ */
+export function setCookie(
+  name: string,
+  value: string,
+  options: { maxAge?: number; path?: string; sameSite?: string } = {},
+): void {
+  if (typeof document === 'undefined') return;
+  const { maxAge = 365 * 24 * 60 * 60, path = '/', sameSite = 'lax' } = options;
+  document.cookie = `${name}=${encodeURIComponent(value)};max-age=${maxAge};path=${path};samesite=${sameSite}`;
+}
+
+/**
+ * Delete cookie (client-side only).
+ */
+export function deleteCookie(name: string, path = '/'): void {
+  if (typeof document === 'undefined') return;
+  document.cookie = `${name}=;max-age=0;path=${path}`;
+}
+
+/**
+ * Get preferred currency from cookie (async — works with Next.js cookies()).
+ * Falls back to document.cookie on client.
+ */
+export async function getCurrencyFromCookieAsync(): Promise<string | null> {
+  // Server-side: try Next.js cookies()
+  try {
+    const { cookies } = await import('next/headers');
+    const cookieStore = await cookies();
+    return cookieStore.get('preferred-currency')?.value ?? null;
+  } catch {
+    // Not in a server context or next not available
+  }
+
+  // Client-side fallback
+  return getCookie('preferred-currency');
+}

package/src/react/helpers/create-store-context.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { createContext, useContext, createElement, type ReactNode } from 'react';
+import { useStore, type StoreApi } from 'zustand';
+
+/**
+ * Create a Context-based Zustand store pattern.
+ *
+ * Returns Provider, useStore hook, and useApi hook — eliminates
+ * module-level singleton boilerplate (Turbopack duplication bug).
+ *
+ * @example
+ * ```ts
+ * const { Provider: CartProvider, useStore: useCartStore, useApi: useCartStoreApi } =
+ *   createStoreContext<CartState>('CartStore');
+ *
+ * // In layout:
+ * const cartStore = useRef(createCartStore());
+ * <CartProvider store={cartStore.current}>{children}</CartProvider>
+ *
+ * // In components:
+ * const isOpen = useCartStore((s) => s.isOpen);
+ * const api = useCartStoreApi(); // for .getState() in callbacks
+ * ```
+ */
+export function createStoreContext<T>(displayName: string) {
+  const StoreContext = createContext<StoreApi<T> | null>(null);
+  StoreContext.displayName = displayName;
+
+  function Provider({ store, children }: { store: StoreApi<T>; children: ReactNode }) {
+    return createElement(StoreContext.Provider, { value: store }, children);
+  }
+  Provider.displayName = `${displayName}Provider`;
+
+  // Overloads: no selector → full state, with selector → selected slice
+  function useStoreHook(): T;
+  function useStoreHook<U>(selector: (s: T) => U): U;
+  function useStoreHook<U>(selector?: (s: T) => U) {
+    const store = useContext(StoreContext);
+    if (!store) {
+      throw new Error(`${displayName}: useStore must be used within its Provider`);
+    }
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return selector ? useStore(store, selector) : useStore(store);
+  }
+
+  function useApi(): StoreApi<T> {
+    const store = useContext(StoreContext);
+    if (!store) {
+      throw new Error(`${displayName}: useApi must be used within its Provider`);
+    }
+    return store;
+  }
+
+  return { Provider, useStore: useStoreHook, useApi } as const;
+}