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

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

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 (26) hide show

package/README.md +610 -108
package/dist/client.cjs +430 -0
package/dist/client.d.cts +138 -0
package/dist/client.d.ts +138 -0
package/dist/client.js +398 -0
package/dist/index.cjs +163 -89
package/dist/index.d.cts +9 -18
package/dist/index.d.ts +9 -18
package/dist/index.js +162 -87
package/dist/middleware.cjs +66 -0
package/dist/middleware.d.cts +38 -0
package/dist/middleware.d.ts +38 -0
package/dist/middleware.js +39 -0
package/dist/server-D-pFrx8J.d.cts +105 -0
package/dist/server-DaDfTjsO.d.cts +103 -0
package/dist/server-DaDfTjsO.d.ts +103 -0
package/dist/server-DjlQVC11.d.ts +105 -0
package/dist/server.cjs +416 -0
package/dist/server.d.cts +4 -0
package/dist/server.d.ts +4 -0
package/dist/server.js +385 -0
package/dist/storefront.cjs +402 -0
package/dist/storefront.d.cts +40 -0
package/dist/storefront.d.ts +40 -0
package/dist/storefront.js +376 -0
package/package.json +18 -8

package/README.md CHANGED Viewed

@@ -1,12 +1,14 @@
-# @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. Handles the complexities of Next.js runtime environments, automatic token management, and cookie-based authentication across all contexts.
 **✨ 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
+- **🎯 Universal API** - Single `storefront()` function works everywhere
+- **🔥 Automatic Tokens** - Creates and manages tokens automatically
+- **🧠 Smart Environment Detection** - Detects Server vs Client contexts
+- **🍪 Cookie-based State** - Shared authentication via Next.js cookies
+- **⚡ Request Isolation** - Proper per-request SDK instances on server
+- **🛠 Zero Configuration** - Works with environment variables out of the box
 ## Installation
@@ -18,20 +20,32 @@ pnpm add @commercengine/storefront-sdk-nextjs
 ## Quick Start
-### 1. Initialize in your root layout
+### 1. Environment Variables
+Add your store configuration to `.env.local`:
+```bash
+NEXT_PUBLIC_STORE_ID=your-store-id
+NEXT_PUBLIC_ENVIRONMENT=staging  # or "production"
+NEXT_PUBLIC_API_KEY=your-api-key
+```
+### 2. Initialize in Root Layout
 ```typescript
 // app/layout.tsx
-import { StorefrontSDKInitializer, Environment } from '@commercengine/storefront-sdk-nextjs';
+import { Environment, StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html>
+    <html lang="en">
       <body>
-        <StorefrontSDKInitializer
+        <StorefrontSDKInitializer
           config={{
-            storeId: process.env.NEXT_PUBLIC_STORE_ID!,
-            environment: Environment.Production,
+            storeId: process.env.NEXT_PUBLIC_STORE_ID || "",
+            environment: process.env.NEXT_PUBLIC_ENVIRONMENT === "production"
+              ? Environment.Production
+              : Environment.Staging,
             apiKey: process.env.NEXT_PUBLIC_API_KEY,
           }}
         />
@@ -42,87 +56,270 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
-### 2. Use anywhere - tokens created automatically!
+### 3. Use Anywhere with the Universal API
 ```typescript
-// ✅ Client Component - Just works
-'use client';
-import { getStorefrontSDK } from '@commercengine/storefront-sdk-nextjs';
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { cookies } from "next/headers";
-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();
+// Server Component, Server Action, or API Route
+const products = await storefront(cookies()).catalog.listProducts();
+```
+## Usage in Different Next.js Contexts
+### Server Components
+Server Components run on the server and can **read** cookies but cannot **write** them. Each request gets its own SDK instance with independent token management.
-  return <button onClick={handleAddToCart}>Add to Cart</button>;
+```typescript
+// app/products/page.tsx
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { cookies } from "next/headers";
+export default async function ProductsPage() {
+  const sdk = storefront(cookies());
+  // This will generate a new anonymous token for this request
+  // Note: Token cannot be persisted (cookies are read-only in Server Components)
+  const { data: products } = await sdk.catalog.listProducts();
+  return (
+    <div>
+      {products?.products.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
 }
 ```
+### Client Components
+Client Components run in the browser and can both read and write cookies, enabling persistent authentication.
 ```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 "@commercengine/storefront-sdk-nextjs";
-export async function addToCartAction(productId: string) {
-  const sdk = getStorefrontSDK(await cookies()); // Cookies needed on server
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
+  useEffect(() => {
+    async function loadProducts() {
+      const sdk = storefront(); // No cookies() needed on client-side
+      // This will create and persist tokens via cookies
+      const { data } = await sdk.catalog.listProducts();
+      if (data) setProducts(data.products);
+    }
+    loadProducts();
+  }, []);
-  // Tokens automatically managed across server/client boundary! 🎉
-  const { data } = await sdk.cart.addToCart({
+  return (
+    <div>
+      {products.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+### Server Actions
+Server Actions run on the server and can both read and write cookies, making them perfect for authentication flows.
+```typescript
+// app/actions.ts
+"use server";
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { cookies } from "next/headers";
+export async function loginWithEmail(email: string, password: string) {
+  const sdk = storefront(cookies());
+  // This will create and persist tokens via cookies
+  const { data, error } = await sdk.auth.loginWithPassword({ email, password });
+  if (data) {
+    // Tokens are automatically saved to cookies by the SDK
+    return { success: true, user: data.user };
+  }
+  return { success: false, error: error?.message };
+}
+export async function addToCart(productId: string, quantity: number) {
+  const sdk = storefront(cookies());
+  // Uses existing authentication from cookies
+  const { data } = await sdk.cart.addItem({
     product_id: productId,
-    quantity: 1,
+    quantity
   });
-  return { success: true };
+  return data;
 }
 ```
+### API Routes
+API Routes work identically to Server Actions - they can read and write cookies.
 ```typescript
-// ✅ Server Component - Cookies required
-import { cookies } from 'next/headers';
-import { getStorefrontSDK } from '@commercengine/storefront-sdk-nextjs';
+// app/api/products/route.ts
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+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 }
+    );
+  }
+}
-export default async function ProductPage({ params }: { params: { id: string } }) {
-  const sdk = getStorefrontSDK(await cookies());
+## Authentication Patterns
+### Anonymous Users
+The SDK automatically creates anonymous tokens when needed:
+```typescript
+// This works in any context - creates anonymous token automatically
+const { data: products } = await storefront(cookies()).catalog.listProducts();
+```
+### Email/Password Login
+```typescript
+// Server Action
+"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 };
+}
+```
+### Phone/OTP Login
+```typescript
+// Server Action - Step 1: Send OTP
+export async function sendOTP(phone: string, country_code: string) {
+  const sdk = storefront(cookies());
-  // Anonymous tokens work perfectly for public data! 🎉
-  const { data: product } = await sdk.catalog.getProduct({
-    product_id_or_slug: params.id
+  return await sdk.auth.loginWithPhone({
+    phone,
+    country_code,
+    register_if_not_exists: true
   });
+}
-  return <div>{product?.name}</div>;
+// Server Action - Step 2: Verify OTP
+export async function verifyOTP(otp: string, otp_token: string, otp_action: string) {
+  const sdk = storefront(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 };
 }
 ```
+## Token Management & Cookie Behavior
+### How It Works
+1. **Server Components**: Generate tokens but can't persist them (read-only cookies)
+2. **Client Components**: Generate and persist tokens via `document.cookie`
+3. **Server Actions/API Routes**: Generate and persist tokens via Next.js `cookies()`
+4. **Shared State**: All contexts read from the same cookie storage
+### Cookie Configuration
+The SDK uses secure cookies with sensible defaults:
+```typescript
+// Advanced cookie configuration (optional)
+<StorefrontSDKInitializer
+  config={{
+    storeId: "your-store-id",
+    apiKey: "your-api-key",
+    tokenStorageOptions: {
+      prefix: "ce_",               // Cookie name prefix
+      maxAge: 30 * 24 * 60 * 60,   // 30 days
+      path: "/",
+      secure: true,                // HTTPS only (auto-detected)
+      sameSite: "Lax",
+    }
+  }}
+/>
+```
 ## API Reference
-### `getStorefrontSDK()`
+### `storefront()`
-**Smart function** that works everywhere:
+**Universal function** that works in all Next.js contexts:
 ```typescript
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { cookies } from "next/headers";
 // ✅ Client-side (browser)
-const sdk = getStorefrontSDK();
+const sdk = storefront();
 // ✅ Server-side (requires cookies for token persistence)
-const sdk = getStorefrontSDK(await cookies());
+const sdk = storefront(cookies());
 // ❌ Server-side without cookies (helpful error message)
-const sdk = getStorefrontSDK(); // Throws clear error with instructions
+const sdk = storefront(); // Throws clear error with instructions
 ```
 ### `StorefrontSDKInitializer`
-**Lightweight initializer** (recommended for most apps):
+**Client-side initializer** component (must be imported from `/client`):
 ```typescript
+import { Environment, StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
 <StorefrontSDKInitializer
   config={{
     storeId: "your-store-id",
@@ -131,109 +328,414 @@ const sdk = getStorefrontSDK(); // Throws clear error with instructions
     // Optional: Advanced configuration
     tokenStorageOptions: {
-      prefix: "ce_", // Cookie prefix (default)
-      maxAge: 30 * 24 * 60 * 60, // 30 days
-      secure: true, // Auto-detected from environment
+      prefix: "ce_",               // Cookie prefix (default)
+      maxAge: 30 * 24 * 60 * 60,   // 30 days
+      secure: true,                // Auto-detected from environment
       sameSite: "Lax",
     },
   }}
 />
 ```
-## Automatic Token Management 🤖
+## Error Handling
+All SDK methods return a consistent error structure:
+```typescript
+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);
+}
+```
+## Static Site Generation (SSG) & Build-Time Optimization
-The SDK now handles tokens **completely automatically**:
+The SDK provides powerful build-time optimizations for SSG/ISR that dramatically reduce API calls during the build process through intelligent token caching.
-### ✅ What Happens Automatically:
+### Automatic Build-Time Token Caching
-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
+Enable automatic token caching during production builds:
-### ✅ Zero Configuration Needed:
+```typescript
+// 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
+      NEXT_BUILD_CACHE_TOKENS: process.env.NEXT_BUILD_CACHE_TOKENS ?? (isBuild ? 'true' : 'false'),
+    },
+  };
+};
+export default nextConfig;
+```
+### SSG with generateStaticParams
+Create static product pages during build:
 ```typescript
-// This just works - no token setup required!
-const sdk = getStorefrontSDK();
-const { data } = await sdk.catalog.listProducts(); // ✨ Tokens created automatically
+// app/products/[slug]/page.tsx
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+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
+  // Get product detail by slug or ID
+  const { data, error } = await sdk.catalog.getProductDetail({
+    product_id_or_slug: slug
+  });
+  if (error || !data) {
+    notFound();
+  }
+  const { product } = data;
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>SKU: {product.sku}</p>
+      <p>Type: {product.product_type}</p>
+      <p>Description: {product.short_description}</p>
+    </div>
+  );
+}
+// Generate static params from real API data
+export async function generateStaticParams() {
+  const sdk = storefront(); // No cookies() - uses build-time storage
+  const { data: productsData, error } = await sdk.catalog.listProducts({
+    limit: 100 // Generate pages for first 100 products
+  });
+  if (error || !productsData) {
+    console.error("Error fetching products for static generation:", error);
+    return [];
+  }
+  return productsData.products.map(product => ({
+    slug: product.slug || product.id
+  }));
+}
 ```
-## Error Messages
+### SSG Test Page Example
+Create a page that makes multiple API calls during build to test token reuse:
+```typescript
+// app/ssg-test/page.tsx
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
-### Server Environment Detection
+export default async function SSGTestPage() {
+  const sdk = storefront(); // No cookies() - uses build-time storage
+  // Make multiple API calls - token will be created once and reused
+  const { data: products, error: productsError } = await sdk.catalog.listProducts({
+    limit: 10
+  });
+  const { data: categories, error: categoriesError } = await sdk.catalog.listCategories({
+    nested_level: 1
+  });
+  const { data: anonymousToken, error: tokenError } = await sdk.auth.getAnonymousToken();
+  const buildTime = new Date().toISOString();
+  return (
+    <div>
+      <h1>SSG Test Page</h1>
+      <p><strong>Built at:</strong> {buildTime}</p>
+      <div>
+        <h2>Build-time API Results:</h2>
+        <div>
+          <h3>Products Call:</h3>
+          {productsError ? (
+            <p style={{ color: 'red' }}>Error: {productsError.message}</p>
+          ) : (
+            <p>✅ Success: Found {products?.products?.length || 0} products</p>
+          )}
+        </div>
+        <div>
+          <h3>Categories Call:</h3>
+          {categoriesError ? (
+            <p style={{ color: 'red' }}>Error: {categoriesError.message}</p>
+          ) : (
+            <p>✅ Success: Found {categories?.categories?.length || 0} categories</p>
+          )}
+        </div>
+        <div>
+          <h3>Anonymous Token Call:</h3>
+          {tokenError ? (
+            <p style={{ color: 'red' }}>Error: {tokenError.message}</p>
+          ) : (
+            <p>✅ Success: User ID {anonymousToken?.user?.id}</p>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
 ```
-🚨 Server Environment Detected!
-You're calling getStorefrontSDK() on the server without cookies.
-Please pass the Next.js cookie store:
+### Build Performance Benefits
-✅ Correct usage:
-import { cookies } from 'next/headers';
+With token caching enabled, you'll see dramatic performance improvements:
-// Server Actions & Route Handlers
-const sdk = getStorefrontSDK(await cookies());
+**Without Caching:**
+- 🔴 Each page creates its own token
+- 🔴 100 pages = 100+ anonymous token API calls
+- 🔴 Slower builds, higher API usage
-// API Routes (Next.js 12)
-const sdk = getStorefrontSDK(cookies());
+**With Caching:**
+- ✅ Token created once and reused across all pages
+- ✅ 100 pages = ~3 anonymous token API calls total
+- ✅ Faster builds, dramatically lower API usage
-❌ Your current usage:
-const sdk = getStorefrontSDK(); // Missing cookies!
+### Build Logs to Monitor
+When build caching is working, you'll see these logs:
+```
+🚀 [BuildCache] Using BuildCachingMemoryTokenStorage with key: store:staging
+🟡 [BuildCache] No cached token found for key: store:staging
+🟠 [BuildCache] Caching new access token for key: store:staging
+🔵 [BuildCache] Using instance token for key: store:staging
+🟢 [BuildCache] Using cached token for key: store:staging
 ```
-## Migration from Base SDK
+**Key Indicators:**
+- ✅ Only 1-3 "Automatically created anonymous session" messages
+- ✅ Many "Using instance token" or "Using cached token" messages
+- ✅ Minimal "Caching new access token" messages
+### Manual Override
+You can manually control build caching:
+```bash
+# Enable caching for this build
+NEXT_BUILD_CACHE_TOKENS=true pnpm build
+# Disable caching for this build
+NEXT_BUILD_CACHE_TOKENS=false pnpm build
+```
+## Best Practices
+### ✅ Do's
+- **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
+- **Environment variables**: Store sensitive config in environment variables
+### ❌ 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 rely on Server Component token persistence**: They can't write cookies
+## Troubleshooting
+### Common Issues
+1. **"Cookie store passed in client environment"**
+   ```typescript
+   // ❌ Wrong
+   storefront(cookies()) // in client component
+   // ✅ Correct
+   storefront() // in client component
+   ```
+2. **"SDK not initialized"**
+   ```typescript
+   // Make sure StorefrontSDKInitializer is in your root layout
+   <StorefrontSDKInitializer config={{ ... }} />
+   ```
+3. **"Cookies can only be modified in Server Action"**
+   This is expected behavior. Server Components can't persist tokens, but they can still make API calls with per-request tokens.
+4. **Server Environment Detection Error**
+   ```
+   🚨 Server Environment Detected!
+   You're calling storefront() on the server without cookies.
+   Please pass the Next.js cookie store:
+   ✅ Correct usage:
+   import { cookies } from 'next/headers';
+   const sdk = storefront(cookies());
+   ❌ Your current usage:
+   const sdk = storefront(); // Missing cookies!
+   ```
+### Debug Mode
+Enable detailed logging during development:
+```typescript
+<StorefrontSDKInitializer
+  config={{
+    storeId: "your-store-id",
+    apiKey: "your-api-key",
+    debug: true, // Enable debug logging
+  }}
+/>
+```
+## Migration Guide
+### From Core SDK
-**Before (Base SDK):**
 ```typescript
-const sdk = new StorefrontSDK({ storeId: "...", tokenStorage: ... });
+// Before (core SDK)
+import { StorefrontSDK } from "@commercengine/storefront-sdk";
+const sdk = new StorefrontSDK({
+  storeId: "...",
+  tokenStorage: new BrowserTokenStorage()
+});
 await sdk.auth.getAnonymousToken(); // Manual token creation
-const { data } = await sdk.catalog.listProducts();
+// After (Next.js SDK)
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+const sdk = storefront(cookies()); // Automatic token management
 ```
-**After (NextJS SDK):**
+### From Previous Next.js SDK Version
 ```typescript
-const sdk = getStorefrontSDK(); // Environment detected automatically
-const { data } = await sdk.catalog.listProducts(); // Tokens created automatically!
+// Before (old pattern)
+import { getStorefrontSDK } from "@commercengine/storefront-sdk-nextjs";
+const sdk = getStorefrontSDK(cookies());
+// After (new universal pattern)
+import { storefront } from "@commercengine/storefront-sdk-nextjs";
+const sdk = storefront(cookies());
 ```
 ## TypeScript Support
-Full TypeScript support with all types from the base SDK:
+The SDK provides complete TypeScript support with auto-generated types:
 ```typescript
 import type {
   StorefrontSDK,
+  ApiResult,
+  UserInfo,
   NextJSSDKConfig,
   Environment
-} from '@commercengine/storefront-sdk-nextjs';
+} from "@commercengine/storefront-sdk-nextjs";
+// All API responses are properly typed
+const { data }: ApiResult<ProductListResponse> = await storefront(cookies()).catalog.listProducts();
+// IntelliSense works for all nested properties
+console.log(data?.products[0].name);
 ```
-## Best Practices
+## User Information
+Get current user information from tokens:
+```typescript
+const sdk = storefront(cookies());
+const userInfo = await sdk.getUserInfo();
+const isLoggedIn = await sdk.isLoggedIn();
+const isAnonymous = await sdk.isAnonymous();
+const userId = await sdk.getUserId();
+const customerId = await sdk.getCustomerId();
+```
+## Advanced Usage
+### Custom Token Storage
+```typescript
+import { TokenStorage } from "@commercengine/storefront-sdk-nextjs";
-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
+class RedisTokenStorage implements TokenStorage {
+  async getAccessToken(): Promise<string | null> {
+    // Your Redis implementation
+  }
+  async setAccessToken(token: string): Promise<void> {
+    // Your Redis implementation
+  }
+  // ... implement other methods
+}
+// Use with the core SDK directly if needed
+import { StorefrontSDK } from "@commercengine/storefront-sdk-nextjs";
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+  tokenStorage: new RedisTokenStorage(),
+});
+```
 ## Why This Wrapper Exists
-**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
+**The core SDK is powerful but complex for Next.js:**
+- Manual token storage setup and configuration
+- Server/client runtime environment handling
+- Cookie configuration for SSR/SSG
+- Request isolation and per-request instances
+- Next.js-specific execution model complexities
+**This wrapper handles it all automatically:**
+- Universal `storefront()` API that works everywhere
+- Request-scoped server instances with React cache
+- Cookie-based token persistence across boundaries
+- Environment detection and configuration
+- Build-time optimizations for SSG/ISR
+**Result: Production-ready e-commerce with zero complexity!** 🚀
+## API Reference
+For complete API documentation of all available endpoints, visit [docs.commercengine.io/api-reference](https://docs.commercengine.io/api-reference)
-**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