npm - @commercengine/storefront-sdk-nextjs - Versions diffs - 0.1.0-alpha.0 → 0.1.0 - Mend

@commercengine/storefront-sdk-nextjs 0.1.0-alpha.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +534 -139
package/dist/client.cjs +136 -0
package/dist/client.d.cts +17 -0
package/dist/client.d.cts.map +1 -0
package/dist/client.d.ts +17 -0
package/dist/client.d.ts.map +1 -0
package/dist/client.js +44 -0
package/dist/client.js.map +1 -0
package/dist/index.cjs +128 -319
package/dist/index.d.cts +34 -107
package/dist/index.d.cts.map +1 -0
package/dist/index.d.ts +34 -107
package/dist/index.d.ts.map +1 -0
package/dist/index.js +55 -303
package/dist/index.js.map +1 -0
package/dist/sdk-manager-B9xDQQuv.d.ts +141 -0
package/dist/sdk-manager-B9xDQQuv.d.ts.map +1 -0
package/dist/sdk-manager-CdgrfSVp.js +343 -0
package/dist/sdk-manager-CdgrfSVp.js.map +1 -0
package/dist/sdk-manager-D2ktqPrp.d.cts +141 -0
package/dist/sdk-manager-D2ktqPrp.d.cts.map +1 -0
package/dist/sdk-manager-NWADjRFW.cjs +400 -0
package/dist/server.cjs +102 -0
package/dist/server.d.cts +4 -0
package/dist/server.d.ts +4 -0
package/dist/server.js +6 -0
package/package.json +21 -11

package/README.md CHANGED Viewed

@@ -1,12 +1,15 @@
-# @commercengine/storefront-sdk-nextjs
+# CommerceEngine Next.js SDK
-**Zero-config Next.js wrapper** for the Commerce Engine Storefront SDK. Handles server/client complexity automatically with smart token management.
+**Production-ready Next.js wrapper** for the CommerceEngine Storefront SDK. Provides the perfect developer experience with automatic context detection, universal API, and zero configuration complexity.
-**✨ What makes this special:**
-- **🔥 Zero token management** - Tokens created automatically on first API call
-- **🧠 Smart environment detection** - One API works everywhere
-- **🍪 Cookie-based storage** - Seamless server/client token sync
-- **⚡ No setup required** - Just import and use
+**✨ Perfect DX Pattern:**
+- **🎯 One Config File** - Single `lib/storefront.ts` using `createStorefront()`
+- **🌍 Universal API** - Same `storefront()` import works everywhere
+- **🔥 Automatic Tokens** - Creates and manages tokens automatically
+- **🧠 Smart Context Detection** - Detects Server vs Client vs Build contexts
+- **🍪 Cookie-based State** - Shared authentication via Next.js cookies
+- **⚡ Request Isolation** - Proper per-request SDK instances on server
+- **🛠 Zero Complexity** - Environment variables + one lib file = done
 ## Installation
@@ -18,23 +21,82 @@ pnpm add @commercengine/storefront-sdk-nextjs
 ## Quick Start
-### 1. Initialize in your root layout
+### 1. Environment Variables (Required)
+Add your store configuration to `.env.local`:
+```bash
+NEXT_PUBLIC_STORE_ID=your-store-id
+NEXT_PUBLIC_API_KEY=your-api-key
+# Environment (defaults to "staging")
+NEXT_PUBLIC_ENVIRONMENT=staging  # or "production"
+```
+### 2. Create Your Storefront Configuration
+Create `lib/storefront.ts` in your project:
+```typescript
+// lib/storefront.ts
+import {
+  createStorefront,
+  type StorefrontRuntimeConfig,
+} from "@commercengine/storefront-sdk-nextjs";
+// Optional advanced configuration (everything not in environment variables)
+const storefrontConfig: StorefrontRuntimeConfig = {
+  debug: true,
+  timeout: 15000,
+  logger: (msg: string, ...args: any[]) =>
+    console.log("[STOREFRONT]", msg, ...args),
+  onTokensUpdated: (access: string, refresh: string) => {
+    console.log("🔥 TOKENS UPDATED:", {
+      access: access.slice(0, 20) + "...",
+      refresh: refresh.slice(0, 20) + "...",
+    });
+  },
+  onTokensCleared: () => {
+    console.log("🔄 TOKENS CLEARED");
+  },
+};
+// Create the configured storefront function (storefrontConfig is OPTIONAL)
+export const storefront = createStorefront(storefrontConfig);
+// Re-export types for convenience
+export type { StorefrontRuntimeConfig };
+```
+**All Core SDK Types Available:**
+The Next.js SDK re-exports all types from the core SDK, so you can import them directly:
+```typescript
+// Import any core SDK types you need
+import type {
+  UserInfo,
+  SupportedDefaultHeaders,
+  StorefrontSDKOptions,
+  components,
+  operations
+} from "@commercengine/storefront-sdk-nextjs";
+// Use imported types
+const headers: SupportedDefaultHeaders = {
+  customer_group_id: "01ABC123..."
+};
+```
+### 3. Initialize in Root Layout
 ```typescript
 // app/layout.tsx
-import { StorefrontSDKInitializer, Environment } from '@commercengine/storefront-sdk-nextjs';
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html>
+    <html lang="en">
       <body>
-        <StorefrontSDKInitializer
-          config={{
-            storeId: process.env.NEXT_PUBLIC_STORE_ID!,
-            environment: Environment.Production,
-            apiKey: process.env.NEXT_PUBLIC_API_KEY,
-          }}
-        />
+        <StorefrontSDKInitializer />
         {children}
       </body>
     </html>
@@ -42,198 +104,531 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
-### 2. Use anywhere - tokens created automatically!
+### 4. Use Anywhere with Universal Import
 ```typescript
-// ✅ Client Component - Just works
-'use client';
-import { getStorefrontSDK } from '@commercengine/storefront-sdk-nextjs';
+// Import your configured storefront everywhere
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers"; // Only for server contexts
-export default function AddToCart({ productId }: { productId: string }) {
-  const handleAddToCart = async () => {
-    const sdk = getStorefrontSDK(); // No cookies needed on client
-    // First API call automatically creates anonymous tokens! 🎉
-    const { data } = await sdk.cart.addToCart({
-      product_id: productId,
-      quantity: 1,
-    });
-  };
+// ✅ Client Component - No cookies needed
+const products = await storefront().catalog.listProducts();
-  return <button onClick={handleAddToCart}>Add to Cart</button>;
-}
+// ✅ Server Component, Server Action, or API Route - MUST pass cookies
+const products = await storefront(cookies()).catalog.listProducts();
+// ✅ Root Layout - Special exception with explicit flag
+const products = await storefront({ isRootLayout: true }).catalog.listProducts();
+// ✅ SSG/ISR (build contexts) - Automatic fallback to memory storage
+// (NEXT_BUILD_CACHE_TOKENS=true enables this)
+const products = await storefront().catalog.listProducts();
 ```
+## Usage in Different Next.js Contexts
+### Client Components
+Client Components run in the browser and can persist tokens via cookies:
 ```typescript
-// ✅ Server Action - Cookies required
-'use server';
-import { cookies } from 'next/headers';
-import { getStorefrontSDK } from '@commercengine/storefront-sdk-nextjs';
+// components/ProductList.tsx
+"use client";
+import { useState, useEffect } from "react";
+import { storefront } from "@/lib/storefront";
-export async function addToCartAction(productId: string) {
-  const sdk = getStorefrontSDK(await cookies()); // Cookies needed on server
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
-  // Tokens automatically managed across server/client boundary! 🎉
-  const { data } = await sdk.cart.addToCart({
-    product_id: productId,
-    quantity: 1,
-  });
+  useEffect(() => {
+    async function loadProducts() {
+      const sdk = storefront(); // No cookies() needed on client-side
+      // Tokens are automatically managed by StorefrontSDKInitializer
+      const { data } = await sdk.catalog.listProducts();
+      if (data) setProducts(data.products);
+    }
+    loadProducts();
+  }, []);
-  return { success: true };
+  return (
+    <div>
+      {products.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
 }
 ```
+### Server Components
+Server Components run on the server and can read cookies:
 ```typescript
-// ✅ Server Component - Cookies required
-import { cookies } from 'next/headers';
-import { getStorefrontSDK } from '@commercengine/storefront-sdk-nextjs';
+// app/products/page.tsx
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers";
-export default async function ProductPage({ params }: { params: { id: string } }) {
-  const sdk = getStorefrontSDK(await cookies());
+export default async function ProductsPage() {
+  const sdk = storefront(cookies());
-  // Anonymous tokens work perfectly for public data! 🎉
-  const { data: product } = await sdk.catalog.getProduct({
-    product_id_or_slug: params.id
-  });
+  const { data: products } = await sdk.catalog.listProducts();
+  return (
+    <div>
+      {products?.products.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+### Server Actions
+Server Actions can both read and write cookies, perfect for authentication:
-  return <div>{product?.name}</div>;
+```typescript
+// app/actions.ts
+"use server";
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers";
+export async function loginWithEmail(email: string, password: string) {
+  const sdk = storefront(cookies());
+  const { data, error } = await sdk.auth.loginWithPassword({ email, password });
+  if (data) {
+    // Tokens are automatically saved to cookies
+    return { success: true, user: data.user };
+  }
+  return { success: false, error: error?.message };
 }
 ```
+### API Routes
-## API Reference
+API Routes work identically to Server Actions:
+```typescript
+// app/api/products/route.ts
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers";
+import { NextResponse } from "next/server";
+export async function GET() {
+  try {
+    const sdk = storefront(cookies());
+    const { data, error } = await sdk.catalog.listProducts();
+    if (error) {
+      return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+    return NextResponse.json(data);
+  } catch (error) {
+    return NextResponse.json(
+      { error: "Internal server error" },
+      { status: 500 }
+    );
+  }
+}
+```
-### `getStorefrontSDK()`
+### Root Layout (Special Case)
-**Smart function** that works everywhere:
+Root Layout requires explicit flag since it's outside request context. Passing this flag will instruct the SDK to fallback to MemoryStore when rendering the root layout as the root layout runs on both server and client before cookie context is available.
 ```typescript
-// ✅ Client-side (browser)
-const sdk = getStorefrontSDK();
+// app/layout.tsx
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+import { storefront } from "@/lib/storefront";
-// ✅ Server-side (requires cookies for token persistence)
-const sdk = getStorefrontSDK(await cookies());
+// Root Layout requires explicit flag - no request context available
+const sdk = storefront({ isRootLayout: true });
+const { data: storeConfig } = await sdk.store.getStoreConfig();
-// ❌ Server-side without cookies (helpful error message)
-const sdk = getStorefrontSDK(); // Throws clear error with instructions
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <StorefrontSDKInitializer />
+        <h1>Welcome to {storeConfig?.store_config?.brand.name}</h1>
+        {children}
+      </body>
+    </html>
+  );
+}
 ```
-### `StorefrontSDKInitializer`
+## Static Site Generation (SSG) & Build-Time Optimization
+The SDK provides powerful build-time optimizations through intelligent token caching.
+### Configure Next.js for Build-Time Optimization
-**Lightweight initializer** (recommended for most apps):
+Create or update your `next.config.ts` (or `next.config.js`) to enable automatic token caching during builds:
 ```typescript
-<StorefrontSDKInitializer
-  config={{
-    storeId: "your-store-id",
-    environment: Environment.Production, // or Environment.Staging
-    apiKey: "your-api-key",
-    // Optional: Advanced configuration
-    tokenStorageOptions: {
-      prefix: "ce_", // Cookie prefix (default)
-      maxAge: 30 * 24 * 60 * 60, // 30 days
-      secure: true, // Auto-detected from environment
-      sameSite: "Lax",
+// next.config.ts
+import type { NextConfig } from "next";
+import { PHASE_PRODUCTION_BUILD } from 'next/constants';
+const nextConfig = (phase: string): NextConfig => {
+  const isBuild = phase === PHASE_PRODUCTION_BUILD;
+  return {
+    env: {
+      // Enable build-time token caching during production builds and when explicitly set
+      NEXT_BUILD_CACHE_TOKENS: process.env.NEXT_BUILD_CACHE_TOKENS ?? (isBuild ? 'true' : 'false'),
+      // Critical: tells SDK to use MemoryStore during SSG/Build/ISR to avoid cookie context failures
+      NEXT_IS_BUILD: isBuild ? 'true' : 'false',
     },
-  }}
-/>
+    // Ensure static generation is enabled
+    output: undefined, // Let Next.js decide based on usage
+  };
+};
+export default nextConfig;
 ```
-## Automatic Token Management 🤖
+### SSG with generateStaticParams
-The SDK now handles tokens **completely automatically**:
+```typescript
+// app/products/[slug]/page.tsx
+import { storefront } from "@/lib/storefront";
+import { notFound } from "next/navigation";
+interface ProductPageProps {
+  params: Promise<{ slug: string }>;
+}
+export default async function ProductPage({ params }: ProductPageProps) {
+  const { slug } = await params;
+  const sdk = storefront(); // No cookies() - uses build-time storage
+  const { data, error } = await sdk.catalog.getProductDetail({
+    product_id_or_slug: slug
+  });
+  if (error || !data) {
+    notFound();
+  }
+  return (
+    <div>
+      <h1>{data.product.name}</h1>
+      <p>SKU: {data.product.sku}</p>
+      <p>Description: {data.product.short_description}</p>
+    </div>
+  );
+}
+// Generate static params from real API data
+export async function generateStaticParams() {
+  const sdk = storefront(); // Token will be cached and reused
+  const { data: productsData, error } = await sdk.catalog.listProducts({
+    limit: 100
+  });
+  if (error || !productsData) {
+    return [];
+  }
+  return productsData.products.map(product => ({
+    slug: product.slug || product.id
+  }));
+}
+```
+### Build Performance Benefits
-### ✅ What Happens Automatically:
+With token caching enabled:
+- ✅ Token created once and reused across all pages
+- ✅ 100 pages = ~1 anonymous token API call total
+- ✅ Faster builds, dramatically lower API usage
-1. **First API Call**: Creates anonymous tokens seamlessly
-2. **Token Expiry**: Refreshes tokens transparently
-3. **Token Corruption**: Cleans up orphaned tokens
-4. **User Login**: Upgrades from anonymous to authenticated tokens
-5. **User Logout**: Downgrades gracefully with continuity
-6. **Page Refresh**: Tokens persist via cookies across server/client
+## Authentication Patterns
-### ✅ Zero Configuration Needed:
+> **⚠️ Important:** Any authentication endpoint that returns tokens (like `loginWithPassword`, `verifyOtp`, `register`, etc.) **must** be called in contexts where cookies can be set and managed:
+> - ✅ **Server Actions** (recommended for authentication flows)
+> - ✅ **API Routes** (`/api` directory)
+> - ✅ **Client Components** (browser environment)
+> - ❌ **Server Components** (cannot set cookies, tokens won't persist)
+>
+> This ensures the SDK can automatically handle token storage and user session continuity.
+### Anonymous Users
+The SDK automatically creates anonymous tokens via the `StorefrontSDKInitializer` component imported in your root layout. If this component is not imported (not recommended), a new token will be minted for each request as a fallback. **It is highly recommended** to use the `StorefrontSDKInitializer` and ensure all token-returning endpoints are called from request contexts that can set cookies. [Authentication Patterns](#authentication-patterns).
 ```typescript
-// This just works - no token setup required!
-const sdk = getStorefrontSDK();
-const { data } = await sdk.catalog.listProducts(); // ✨ Tokens created automatically
+// This works everywhere - creates anonymous token automatically
+const { data: products } = await storefront(cookies()).catalog.listProducts();
 ```
-## Error Messages
+### Email/Password Login
-### Server Environment Detection
+```typescript
+// Server Action (✅ Recommended - can set cookies for token persistence)
+"use server";
+export async function loginUser(email: string, password: string) {
+  const sdk = storefront(cookies());
+  const { data, error } = await sdk.auth.loginWithPassword({ email, password });
+  if (data) {
+    // Tokens automatically saved to cookies
+    redirect('/dashboard');
+  }
+  return { error: error?.message };
+}
 ```
-🚨 Server Environment Detected!
-You're calling getStorefrontSDK() on the server without cookies.
-Please pass the Next.js cookie store:
+### Phone/OTP Login
-✅ Correct usage:
-import { cookies } from 'next/headers';
+```typescript
+// Server Action - Step 1: Send OTP (✅ Recommended context)
+export async function sendOTP(phone: string, country_code: string) {
+  const sdk = storefront(await cookies());
+  return await sdk.auth.loginWithPhone({
+    phone,
+    country_code,
+    register_if_not_exists: true
+  });
+}
-// Server Actions & Route Handlers
-const sdk = getStorefrontSDK(await cookies());
+// Server Action - Step 2: Verify OTP (✅ Recommended - can set cookies for token persistence)
+export async function verifyOTP(otp: string, otp_token: string, otp_action: string) {
+  const sdk = storefront(await cookies());
+  const { data, error } = await sdk.auth.verifyOtp({
+    otp,
+    otp_token,
+    otp_action
+  });
+  if (data) {
+    // Tokens automatically saved to cookies
+    return { success: true, user: data.user };
+  }
+  return { success: false, error: error?.message };
+}
+```
-// API Routes (Next.js 12)
-const sdk = getStorefrontSDK(cookies());
+## API Reference
-❌ Your current usage:
-const sdk = getStorefrontSDK(); // Missing cookies!
+### `createStorefront(config?)`
+Creates a configured storefront function that works universally across all Next.js contexts.
+```typescript
+import { createStorefront } from "@commercengine/storefront-sdk-nextjs";
+export const storefront = createStorefront({
+  debug: true,
+  logger: (msg, ...args) => console.log('[DEBUG]', msg, ...args)
+});
+```
+**Parameters:**
+- `config` (optional): `StorefrontRuntimeConfig` - Advanced configuration options
+**Returns:**
+- Universal `storefront()` function that works in all Next.js contexts
+### `StorefrontRuntimeConfig`
+Optional configuration object for `createStorefront()`:
+```typescript
+interface StorefrontRuntimeConfig {
+  // Override environment variables
+  storeId?: string;
+  apiKey?: string;
+  environment?: Environment;
+  baseUrl?: string;
+  timeout?: number;
+  debug?: boolean;
+  // Advanced options (not available via environment variables)
+  accessToken?: string;
+  refreshToken?: string;
+  defaultHeaders?: SupportedDefaultHeaders;
+  logger?: (message: string, ...args: any[]) => void;
+  onTokensUpdated?: (accessToken: string, refreshToken: string) => void;
+  onTokensCleared?: () => void;
+  tokenStorageOptions?: NextJSTokenStorageOptions;
+}
+```
+### Universal `storefront()` Function
+The function returned by `createStorefront()` works in all contexts with strict enforcement:
+```typescript
+// Client-side (browser)
+const sdk = storefront();
+// Server-side (requires cookies for user continuity)
+const sdk = storefront(cookies());
+// Root Layout (special exception with explicit flag)
+const sdk = storefront({ isRootLayout: true });
+// Server-side without cookies - throws helpful error to protect user sessions
+const sdk = storefront(); // ❌ Throws error in server contexts
 ```
-## Migration from Base SDK
+### Function Signatures
-**Before (Base SDK):**
 ```typescript
-const sdk = new StorefrontSDK({ storeId: "...", tokenStorage: ... });
-await sdk.auth.getAnonymousToken(); // Manual token creation
-const { data } = await sdk.catalog.listProducts();
+function storefront(): StorefrontSDK;
+function storefront(cookieStore: NextCookieStore): StorefrontSDK;
+function storefront(options: { isRootLayout: true }): StorefrontSDK;
+function storefront(cookieStore: NextCookieStore, options: { isRootLayout?: boolean }): StorefrontSDK;
 ```
-**After (NextJS SDK):**
+### `StorefrontSDKInitializer`
+Client-side initializer component (must be imported from `/client`):
 ```typescript
-const sdk = getStorefrontSDK(); // Environment detected automatically
-const { data } = await sdk.catalog.listProducts(); // Tokens created automatically!
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+<StorefrontSDKInitializer />
 ```
-## TypeScript Support
+No props needed - configuration comes from environment variables and your `lib/storefront.ts` file.
-Full TypeScript support with all types from the base SDK:
+## Error Handling
+All SDK methods return a consistent error structure:
 ```typescript
-import type {
-  StorefrontSDK,
-  NextJSSDKConfig,
-  Environment
-} from '@commercengine/storefront-sdk-nextjs';
+const { data, error, response } = await storefront(cookies()).catalog.listProducts();
+if (error) {
+  console.error("API Error:", error.message, error.code);
+  console.log("Status:", response.status);
+} else {
+  console.log("Products:", data.products);
+}
 ```
 ## Best Practices
-1. **✅ One-Line Setup**: `StorefrontSDKInitializer` in root layout is all you need
-2. **✅ Server Cookies**: Always pass `await cookies()` on server-side
-3. **✅ Error Handling**: Wrap API calls in try-catch
-4. **✅ Environment Variables**: Use Next.js env vars for configuration
-5. **⚡ Trust the Middleware**: No manual token management needed
+### ✅ Do's
+- **Set required environment variables**: `NEXT_PUBLIC_STORE_ID` and `NEXT_PUBLIC_API_KEY` are mandatory
+- **Create one lib/storefront.ts file**: Use `createStorefront()` to configure advanced options
+- **Initialize once**: Call `StorefrontSDKInitializer` only in your root layout
+- **Use `storefront(cookies())`**: Always pass cookies in server contexts
+- **Handle errors**: Always check the error property in responses
+- **Use Server Actions**: For authentication flows that need to persist tokens
+### ❌ Don'ts
+- **Don't call `cookies()` in Client Components**: It will throw an error
+- **Don't initialize multiple times**: The SDK handles singleton behavior
+- **Don't forget error handling**: API calls can fail for various reasons
+- **Don't skip environment variables**: Missing required variables will cause errors
+## Troubleshooting
+### Common Issues
+1. **"Server context requires cookies for user continuity!"**
+   ```typescript
+   // ❌ Wrong - server context without cookies (breaks user sessions)
+   storefront()
+   // ✅ Correct - server context with cookies
+   storefront(cookies())
+   // ✅ Root Layout exception
+   storefront({ isRootLayout: true })
+   ```
+2. **Missing Environment Variables**
+   ```bash
+   # Ensure your .env.local has the required variables:
+   NEXT_PUBLIC_STORE_ID=your-store-id
+   NEXT_PUBLIC_API_KEY=your-api-key
+   ```
+3. **"Cookie store passed in client environment"**
+   ```typescript
+   // ❌ Wrong - client component with cookies
+   storefront(cookies())
+   // ✅ Correct - client component without cookies
+   storefront()
+   ```
+4. **Server Actions and async cookies()**
+   ```typescript
+   // ✅ Correct - Server Actions need await cookies()
+   const sdk = storefront(await cookies());
+   // ✅ Server Components and API Routes use cookies() directly
+   const sdk = storefront(cookies());
+   ```
+## Migration Guide
+### From Core SDK
+```typescript
+// Before (core SDK)
+import { StorefrontSDK } from "@commercengine/storefront-sdk";
+const sdk = new StorefrontSDK({
+  storeId: "...",
+  tokenStorage: new BrowserTokenStorage()
+});
+// After (Next.js SDK)
+import { storefront } from "@/lib/storefront";
+const sdk = storefront(cookies());
+```
-## Why This Wrapper Exists
+## Why This Pattern?
+**The Perfect DX Pattern provides:**
+- **One Config File**: All advanced configuration in `lib/storefront.ts`
+- **Environment Variables**: Basic config (storeId, apiKey) via env vars
+- **Universal Import**: Same `storefront()` import everywhere
+- **Strict User Continuity**: Enforces cookie passing to protect user sessions and analytics
+- **Explicit Exceptions**: Clear patterns for special cases like Root Layout
+- **Zero Guesswork**: Helpful errors guide developers to correct patterns
+**Result: Production-ready e-commerce with bulletproof user session management!** 🛡️
+## API Reference
-**The base SDK is powerful but complex for Next.js:**
-- Manual token storage setup
-- Server/client environment handling
-- Cookie configuration for SSR
-- Token lifecycle management
+For complete API documentation of all available endpoints, visit [SDK DOCS REFERENCE](https://sdk-docs.commercengine.io/sdk/)
-**This wrapper makes it effortless:**
-- Zero configuration token management
-- Automatic environment detection
-- Cookie-based persistence works out of the box
-- One API that works everywhere
+The Next.js SDK provides access to all the same endpoints as the core SDK:
-**Result: Focus on your app, not SDK complexity!** 🚀
+- `sdk.auth.*` - Authentication and user management
+- `sdk.customer.*` - Customer profiles and preferences
+- `sdk.catalog.*` - Products, categories, and search
+- `sdk.cart.*` - Shopping cart management
+- `sdk.order.*` - Order creation and tracking
+- `sdk.shipping.*` - Shipping methods and rates
+- `sdk.helpers.*` - Countries, currencies, utilities
 ## License
-All rights reserved - Commerce Engine
+All Rights Reserved