@doswiftly/storefront-sdk 4.0.0

package/src/react/providers/storefront-client-provider.tsx

@@ -0,0 +1,90 @@
+/**
+ * StorefrontClientProvider — React context for SDK clients.
+ *
+ * Creates StorefrontClient + CartClient + AuthClient and provides them
+ * to the component tree via React context.
+ *
+ * Registers default middleware pipeline: auth → currency → retry → timeout → errors.
+ */
+
+'use client';
+
+import React, { createContext, useContext, useMemo } from 'react';
+import { createStorefrontClient } from '../../core/client/create-client';
+import { CartClient } from '../../core/cart/cart-client';
+import { AuthClient } from '../../core/auth/auth-client';
+import { authMiddleware } from '../../core/middleware/auth';
+import { currencyMiddleware } from '../../core/middleware/currency';
+import { retryMiddleware } from '../../core/middleware/retry';
+import { timeoutMiddleware } from '../../core/middleware/timeout';
+import { errorMiddleware } from '../../core/middleware/errors';
+import { useAuthStoreApi, useCurrencyStoreApi } from '../stores/store-context';
+import type { StorefrontClient, StorefrontClientConfig, Middleware } from '../../core/client/types';
+
+export interface StorefrontClientContextValue {
+  client: StorefrontClient;
+  cartClient: CartClient;
+  authClient: AuthClient;
+}
+
+const StorefrontClientContext = createContext<StorefrontClientContextValue | null>(null);
+
+export interface StorefrontClientProviderProps {
+  children: React.ReactNode;
+  config: StorefrontClientConfig;
+  /**
+   * Additional middleware to prepend to the default pipeline.
+   * Default pipeline: auth → currency → [custom] → retry → timeout → errors
+   */
+  middleware?: Middleware[];
+}
+
+export function StorefrontClientProvider({
+  children,
+  config,
+  middleware: customMiddleware = [],
+}: StorefrontClientProviderProps) {
+  const authStore = useAuthStoreApi();
+  const currencyStore = useCurrencyStoreApi();
+
+  const value = useMemo(() => {
+    const client = createStorefrontClient({
+      ...config,
+      middleware: [
+        // Header middleware (runs first)
+        authMiddleware(() => authStore.getState().accessToken),
+        currencyMiddleware(() => currencyStore.getState().currency),
+        // Custom middleware from props
+        ...customMiddleware,
+        // Infrastructure middleware (runs last)
+        retryMiddleware({ maxRetries: 2 }),
+        timeoutMiddleware({ timeout: 5000 }),
+        errorMiddleware(),
+      ],
+    });
+
+    const cartClient = new CartClient(client);
+    const authClient = new AuthClient(client);
+
+    return { client, cartClient, authClient };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config.apiUrl, config.shopSlug, authStore, currencyStore]);
+
+  return (
+    <StorefrontClientContext.Provider value={value}>
+      {children}
+    </StorefrontClientContext.Provider>
+  );
+}
+
+/**
+ * Get StorefrontClient context value.
+ * Must be used within StorefrontClientProvider.
+ */
+export function useStorefrontClientContext(): StorefrontClientContextValue {
+  const ctx = useContext(StorefrontClientContext);
+  if (!ctx) {
+    throw new Error('useStorefrontClientContext must be used within StorefrontClientProvider');
+  }
+  return ctx;
+}

package/src/react/providers/storefront-provider.tsx

@@ -0,0 +1,71 @@
+/**
+ * StorefrontProvider — convenience composition of all SDK providers.
+ *
+ * Creates store instances via useRef (stable across re-renders) and provides
+ * them through React Context. Store Contexts wrap StorefrontClientProvider
+ * so that middleware can access store state via useAuthStoreApi/useCurrencyStoreApi.
+ *
+ * Composition order: Store Contexts → StorefrontClientProvider → CurrencyProvider
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ *
+ * export default async function RootLayout({ children }) {
+ *   const shopData = await fetchShop();
+ *   return (
+ *     <StorefrontProvider
+ *       config={{ apiUrl: '...', shopSlug: '...' }}
+ *       shopData={shopData}
+ *     >
+ *       {children}
+ *     </StorefrontProvider>
+ *   );
+ * }
+ * ```
+ */
+
+'use client';
+
+import React, { useRef } from 'react';
+import { AuthStoreContext, CurrencyStoreContext } from '../stores/store-context';
+import { createAuthStore } from '../stores/auth.store';
+import { createCurrencyStore } from '../stores/currency.store';
+import { StorefrontClientProvider, type StorefrontClientProviderProps } from './storefront-client-provider';
+import { CurrencyProvider, type CurrencyProviderProps } from './currency-provider';
+
+export interface StorefrontProviderProps extends StorefrontClientProviderProps {
+  shopData: CurrencyProviderProps['shopData'];
+  /**
+   * Server-side auth hint — set to `true` when httpOnly auth cookie exists.
+   * This allows the auth store to start with `isAuthenticated: true` on first render,
+   * eliminating the flash of "Sign In" while Zustand persist rehydrates from localStorage.
+   *
+   * Read from cookies() in a Server Component (layout.tsx) and pass here.
+   */
+  initialIsAuthenticated?: boolean;
+}
+
+export function StorefrontProvider({
+  children,
+  config,
+  middleware,
+  shopData,
+  initialIsAuthenticated,
+}: StorefrontProviderProps) {
+  const authStoreRef = useRef(createAuthStore(initialIsAuthenticated));
+  const currencyStoreRef = useRef(createCurrencyStore());
+
+  return (
+    <AuthStoreContext.Provider value={authStoreRef.current}>
+      <CurrencyStoreContext.Provider value={currencyStoreRef.current}>
+        <StorefrontClientProvider config={config} middleware={middleware}>
+          <CurrencyProvider shopData={shopData}>
+            {children}
+          </CurrencyProvider>
+        </StorefrontClientProvider>
+      </CurrencyStoreContext.Provider>
+    </AuthStoreContext.Provider>
+  );
+}

package/src/react/server/get-storefront-client.ts

@@ -0,0 +1,60 @@
+/**
+ * Server-side StorefrontClient factory — for Server Components, API routes, etc.
+ *
+ * Creates a StorefrontClient with default middleware pipeline,
+ * without requiring React context (no providers needed server-side).
+ *
+ * @example
+ * ```typescript
+ * // lib/graphql/server.ts
+ * import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * const client = getStorefrontClient({
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ *   shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+ * });
+ *
+ * export const fetchProduct = cache(async (handle: string) => {
+ *   return client.query(ProductDocument, { handle });
+ * });
+ * ```
+ */
+
+import { createStorefrontClient } from '../../core/client/create-client';
+import { retryMiddleware } from '../../core/middleware/retry';
+import { timeoutMiddleware } from '../../core/middleware/timeout';
+import { errorMiddleware } from '../../core/middleware/errors';
+import type { StorefrontClient, StorefrontClientConfig, Middleware } from '../../core/client/types';
+
+export interface ServerClientOptions extends Omit<StorefrontClientConfig, 'middleware'> {
+  /**
+   * Function that returns request-scoped headers (e.g. currency from cookie).
+   * Called once per client creation.
+   */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * Additional middleware (prepended to default pipeline).
+   */
+  middleware?: Middleware[];
+}
+
+/**
+ * Create a StorefrontClient for server-side use.
+ *
+ * Includes default middleware: retry → timeout → errors.
+ * Does NOT include auth/currency middleware (server has no Zustand stores).
+ * Pass headers via config.defaultHeaders or getHeaders option.
+ */
+export function getStorefrontClient(options: ServerClientOptions): StorefrontClient {
+  const { middleware: customMiddleware = [], ...config } = options;
+
+  return createStorefrontClient({
+    ...config,
+    middleware: [
+      ...customMiddleware,
+      retryMiddleware({ maxRetries: 2 }),
+      timeoutMiddleware({ timeout: 10000 }), // Server-side: 10s timeout
+      errorMiddleware(),
+    ],
+  });
+}

package/src/react/server/index.ts

@@ -0,0 +1 @@
+export { getStorefrontClient, type ServerClientOptions } from './get-storefront-client';

package/src/react/stores/auth.store.ts

@@ -0,0 +1,112 @@
+/**
+ * Auth store factory — localStorage persistence via Zustand persist.
+ *
+ * Creates a vanilla Zustand store (not a React hook singleton).
+ * Instance is created in StorefrontProvider via useRef and provided
+ * through React Context — eliminates module duplication in Turbopack.
+ *
+ * httpOnly cookie is managed separately (for SSR/middleware).
+ */
+
+import { createStore } from 'zustand/vanilla';
+import { persist } from 'zustand/middleware';
+
+export interface CustomerInfo {
+  id: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+}
+
+export interface AuthStore {
+  // State
+  customer: CustomerInfo | null;
+  accessToken: string | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+
+  // Actions
+  setAuth: (customer: CustomerInfo, accessToken: string) => void;
+  clearAuth: () => void;
+  updateCustomer: (updates: Partial<CustomerInfo>) => void;
+  setLoading: (isLoading: boolean) => void;
+}
+
+export const createAuthStore = (initialIsAuthenticated = false) =>
+  createStore<AuthStore>()(
+    persist(
+      (set) => ({
+        customer: null,
+        accessToken: null,
+        isAuthenticated: initialIsAuthenticated,
+        isLoading: false,
+
+        setAuth: (customer, accessToken) =>
+          set({
+            customer,
+            accessToken,
+            isAuthenticated: true,
+          }),
+
+        clearAuth: () =>
+          set({
+            customer: null,
+            accessToken: null,
+            isAuthenticated: false,
+          }),
+
+        updateCustomer: (updates) =>
+          set((state) => ({
+            customer: state.customer
+              ? { ...state.customer, ...updates }
+              : null,
+          })),
+
+        setLoading: (isLoading) => set({ isLoading }),
+      }),
+      {
+        name: 'auth-storage',
+        version: 2, // Invalidate stale data from old module-level store era
+        partialize: (state) => ({
+          customer: state.customer,
+          accessToken: state.accessToken,
+          isAuthenticated: state.isAuthenticated,
+        }),
+        /**
+         * Custom merge — server cookie check (initialIsAuthenticated) is authoritative
+         * for isAuthenticated. localStorage provides supplementary data (customer, token).
+         *
+         * This prevents stale localStorage from overwriting the server-provided auth state.
+         */
+        merge: (persistedState, currentState) => {
+          const persisted = persistedState as Partial<AuthStore> | undefined;
+          if (!persisted) return currentState;
+
+          return {
+            ...currentState,
+            customer: persisted.customer ?? currentState.customer,
+            accessToken: persisted.accessToken ?? currentState.accessToken,
+            // Server cookie is the authority — never let stale localStorage override it
+            isAuthenticated: currentState.isAuthenticated,
+          } as AuthStore;
+        },
+        migrate: (persistedState, version) => {
+          if (version < 2) {
+            // Data from old module-level store may be unreliable (Turbopack duplication)
+            // Clear it — user will re-authenticate via cookie or login
+            return { customer: null, accessToken: null, isAuthenticated: false } as {
+              customer: CustomerInfo | null;
+              accessToken: string | null;
+              isAuthenticated: boolean;
+            };
+          }
+          return persistedState as {
+            customer: CustomerInfo | null;
+            accessToken: string | null;
+            isAuthenticated: boolean;
+          };
+        },
+      },
+    ),
+  );

package/src/react/stores/currency.store.ts

@@ -0,0 +1,113 @@
+/**
+ * Currency store factory — cookie persistence (SSR-safe).
+ *
+ * Creates a vanilla Zustand store (not a React hook singleton).
+ * Instance is created in StorefrontProvider via useRef and provided
+ * through React Context — eliminates module duplication in Turbopack.
+ */
+
+import { createStore } from 'zustand/vanilla';
+
+export interface ShopCurrencyData {
+  currencyCode: string;
+  supportedCurrencies: string[];
+  localeToCurrencyMap?: Array<{
+    locale: string;
+    currency: string;
+  }>;
+}
+
+export interface CurrencyStore {
+  // State
+  baseCurrency: string | null;
+  supportedCurrencies: string[];
+  currency: string | null;
+  isLoaded: boolean;
+
+  // Actions
+  initialize: (shopData: ShopCurrencyData) => void;
+  setCurrency: (currency: string) => void;
+}
+
+/**
+ * Get currency from cookie (client-side).
+ */
+function getCurrencyFromCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(/(?:^|;\s*)preferred-currency=([^;]*)/);
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+/**
+ * Set currency in cookie (client-side).
+ */
+function setCurrencyCookie(currency: string): void {
+  if (typeof document === 'undefined') return;
+  const maxAge = 365 * 24 * 60 * 60; // 1 year
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? ';secure' : '';
+  document.cookie = `preferred-currency=${encodeURIComponent(currency)};max-age=${maxAge};path=/;samesite=lax${secure}`;
+}
+
+export const createCurrencyStore = () =>
+  createStore<CurrencyStore>()((set, get) => ({
+    baseCurrency: null,
+    supportedCurrencies: [],
+    currency: null,
+    isLoaded: false,
+
+    initialize: (shopData: ShopCurrencyData) => {
+      // 1. Try saved currency from cookie (SSR-safe)
+      const saved = getCurrencyFromCookie();
+
+      // 2. Try to detect from browser locale
+      let detected: string | undefined;
+      if (shopData.localeToCurrencyMap && typeof navigator !== 'undefined') {
+        const browserLocale = navigator.language;
+        const match = shopData.localeToCurrencyMap.find(
+          (m) => m.locale === browserLocale,
+        );
+        detected = match?.currency;
+      }
+
+      // 3. Determine final currency (priority: saved > detected > base)
+      const finalCurrency =
+        saved && shopData.supportedCurrencies.includes(saved)
+          ? saved
+          : detected && shopData.supportedCurrencies.includes(detected)
+            ? detected
+            : shopData.currencyCode;
+
+      set({
+        baseCurrency: shopData.currencyCode,
+        supportedCurrencies: shopData.supportedCurrencies,
+        currency: finalCurrency,
+        isLoaded: true,
+      });
+
+      // Ensure cookie is set if we determined a currency
+      if (finalCurrency && !saved) {
+        setCurrencyCookie(finalCurrency);
+      }
+    },
+
+    setCurrency: (currency: string) => {
+      const { supportedCurrencies } = get();
+
+      if (!supportedCurrencies.includes(currency)) {
+        console.warn(`[CurrencyStore] Currency ${currency} not supported`);
+        return;
+      }
+
+      set({ currency });
+      setCurrencyCookie(currency);
+    },
+  }));
+
+// ---------------------------------------------------------------------------
+// Selectors (for use with useCurrencyStore(selector))
+// ---------------------------------------------------------------------------
+
+export const selectCurrency = (state: CurrencyStore) => state.currency;
+export const selectBaseCurrency = (state: CurrencyStore) => state.baseCurrency;
+export const selectSupportedCurrencies = (state: CurrencyStore) => state.supportedCurrencies;
+export const selectIsLoaded = (state: CurrencyStore) => state.isLoaded;

package/src/react/stores/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Zustand stores — factory functions + context hooks.
+ */
+
+// Factory functions
+export { createAuthStore, type AuthStore, type CustomerInfo } from './auth.store';
+export { createCurrencyStore, type CurrencyStore, type ShopCurrencyData } from './currency.store';
+
+// Selectors
+export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './currency.store';
+
+// Context hooks
+export {
+  useAuthStore, useAuthStoreApi, useAuthHydrated,
+  useCurrencyStore, useCurrencyStoreApi,
+  AuthStoreContext, CurrencyStoreContext,
+} from './store-context';

package/src/react/stores/store-context.tsx

@@ -0,0 +1,82 @@
+/**
+ * Store Context — React Context + hooks for Zustand vanilla stores.
+ *
+ * This is the SINGLE source for useAuthStore and useCurrencyStore hooks.
+ * Stores are created in StorefrontProvider (useRef) and provided via Context.
+ * This eliminates module-level singletons and Turbopack duplication bugs.
+ *
+ * useAuthHydrated() replaces the old isHydrated store field — tracks
+ * Zustand persist rehydration via React lifecycle (not module-level code).
+ */
+
+'use client';
+
+import { createContext, useContext, useState, useEffect } from 'react';
+import { useStore, type StoreApi } from 'zustand';
+import type { AuthStore } from './auth.store';
+import type { CurrencyStore } from './currency.store';
+
+// ---------------------------------------------------------------------------
+// Contexts
+// ---------------------------------------------------------------------------
+
+export const AuthStoreContext = createContext<StoreApi<AuthStore> | null>(null);
+export const CurrencyStoreContext = createContext<StoreApi<CurrencyStore> | null>(null);
+
+// ---------------------------------------------------------------------------
+// Auth hooks
+// ---------------------------------------------------------------------------
+
+export function useAuthStore(): AuthStore;
+export function useAuthStore<T>(selector: (s: AuthStore) => T): T;
+export function useAuthStore<T>(selector?: (s: AuthStore) => T) {
+  const store = useContext(AuthStoreContext);
+  if (!store) throw new Error('useAuthStore must be used within StorefrontProvider');
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return selector ? useStore(store, selector) : useStore(store);
+}
+
+export function useAuthStoreApi(): StoreApi<AuthStore> {
+  const store = useContext(AuthStoreContext);
+  if (!store) throw new Error('useAuthStoreApi must be used within StorefrontProvider');
+  return store;
+}
+
+/**
+ * Tracks persist hydration state via React lifecycle (not module-level).
+ * Returns `true` once Zustand persist has finished rehydrating from localStorage.
+ */
+export function useAuthHydrated(): boolean {
+  const store = useAuthStoreApi();
+  const [hydrated, setHydrated] = useState(false);
+
+  useEffect(() => {
+    const persistApi = (store as any).persist;
+    // Subscribe to future hydration completions
+    const unsubFinish = persistApi.onFinishHydration(() => setHydrated(true));
+    // Check if hydration already completed before effect ran
+    if (persistApi.hasHydrated()) setHydrated(true);
+    return unsubFinish;
+  }, [store]);
+
+  return hydrated;
+}
+
+// ---------------------------------------------------------------------------
+// Currency hooks
+// ---------------------------------------------------------------------------
+
+export function useCurrencyStore(): CurrencyStore;
+export function useCurrencyStore<T>(selector: (s: CurrencyStore) => T): T;
+export function useCurrencyStore<T>(selector?: (s: CurrencyStore) => T) {
+  const store = useContext(CurrencyStoreContext);
+  if (!store) throw new Error('useCurrencyStore must be used within StorefrontProvider');
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return selector ? useStore(store, selector) : useStore(store);
+}
+
+export function useCurrencyStoreApi(): StoreApi<CurrencyStore> {
+  const store = useContext(CurrencyStoreContext);
+  if (!store) throw new Error('useCurrencyStoreApi must be used within StorefrontProvider');
+  return store;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  // Suppress CJS deprecation warning
+  define: {
+    "import.meta.vitest": "undefined",
+  },
+  test: {
+    environment: "node",
+    globals: true, // Enable global test functions like describe, it, expect
+    // Use pool threads for better compatibility
+    pool: "threads",
+  },
+});