@commercengine/storefront-sdk-nextjs 0.2.10 → 0.3.1

package/README.md

@@ -1,17 +1,19 @@
 # CommerceEngine Next.js SDK
 
-**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.
+Production-ready Next.js wrapper for the CommerceEngine Storefront SDK.
 
-Built on [`@commercengine/ssr-utils`](../ssr-utils) for robust server-side token management.
+Breaking changes from the previous wrapper API are documented in
+[MIGRATION.md](./MIGRATION.md).
 
-**✨ 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
+This package gives Next.js apps one configured storefront factory with two
+explicit access patterns:
+
+- `storefront.public()` for build-safe and public server reads
+- `storefront.session()` / `storefront.session(await cookies())` for live user
+  session flows
+
+It builds on [`@commercengine/ssr-utils`](../ssr-utils) for cookie-backed server
+storage, but the primary DX is the Next.js-specific `createStorefront()` API.
 
 ## Installation
 
@@ -23,82 +25,51 @@ pnpm add @commercengine/storefront-sdk-nextjs
 
 ## Quick Start
 
-### 1. Environment Variables (Required)
-
-Add your store configuration to `.env.local`:
+### 1. Add environment variables
 
 ```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"
+NEXT_PUBLIC_ENVIRONMENT=staging
 ```
 
-### 2. Create Your Storefront Configuration
-
-Create `lib/storefront.ts` in your project:
+### 2. Create `lib/storefront.ts`
 
 ```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");
-  },
+  logger: (msg, ...args) => console.log("[STOREFRONT]", msg, ...args),
 };
 
-// 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
+### 3. Initialize once in the root layout
 
 ```typescript
-// app/layout.tsx
 import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+import { storefront } from "@/lib/storefront";
+
+const { data: storeConfig } = await storefront.public().store.getStoreConfig();
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return (
     <html lang="en">
       <body>
         <StorefrontSDKInitializer />
+        <h1>{storeConfig?.store_config?.brand.name}</h1>
         {children}
       </body>
     </html>
@@ -106,349 +77,202 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-### 4. Use Anywhere with Universal Import
+### 4. Use the correct accessor
 
 ```typescript
-// Import your configured storefront everywhere
 import { storefront } from "@/lib/storefront";
-import { cookies } from "next/headers"; // Only for server contexts
-
-// ✅ Client Component - No cookies needed
-const products = await storefront().catalog.listProducts();
+import { cookies } from "next/headers";
 
-// ✅ Server Component, Server Action, or API Route - MUST pass cookies
-const products = await storefront(cookies()).catalog.listProducts();
+// Build/prerender-safe reads
+const publicSdk = storefront.public();
 
-// ✅ Root Layout - Special exception with explicit flag
-const products = await storefront({ isRootLayout: true }).catalog.listProducts();
+// Client Components
+const clientSessionSdk = storefront.session();
 
-// ✅ SSG/ISR (build contexts) - Automatic fallback to memory storage
-// (NEXT_BUILD_CACHE_TOKENS=true enables this)
-const products = await storefront().catalog.listProducts();
+// Server Components, Server Actions, Route Handlers
+const serverSessionSdk = storefront.session(await cookies());
 ```
 
-## Usage in Different Next.js Contexts
+## Mental Model
 
-### Client Components
+- `public()` is for public reads that should stay API-key-backed and never touch
+  session bootstrap, refresh, or token persistence.
+- `session()` is for live requests that operate on behalf of an anonymous or
+  authenticated user.
+- The server version of `session()` requires `cookies()` so request continuity
+  is explicit and session state can flow across server/client boundaries.
+
+That means:
 
-Client Components run in the browser and can persist tokens via cookies:
+- Root layouts use `storefront.public()`
+- SSG/ISR pages use `storefront.public()`
+- Client Components use `storefront.session()`
+- Server Components, Server Actions, and Route Handlers use
+  `storefront.session(await cookies())`
+
+## Usage Examples
+
+### Client Components
 
 ```typescript
-// components/ProductList.tsx
 "use client";
 
-import { useState, useEffect } from "react";
+import { useEffect, useState } from "react";
 import { storefront } from "@/lib/storefront";
 
 export default function ProductList() {
-  const [products, setProducts] = useState([]);
-  
+  const [products, setProducts] = useState<string[]>([]);
+
   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();
+    const sdk = storefront.session();
+
+    sdk.catalog.listProducts({ limit: 5 }).then(({ data }) => {
+      setProducts(data?.products.map((product) => product.name) ?? []);
+    });
   }, []);
-  
+
   return (
-    <div>
-      {products.map(product => (
-        <div key={product.id}>{product.name}</div>
+    <ul>
+      {products.map((name) => (
+        <li key={name}>{name}</li>
       ))}
-    </div>
+    </ul>
   );
 }
 ```
 
 ### Server Components
 
-Server Components run on the server and can read cookies:
+Use `public()` for public content and `session(await cookies())` when the read
+depends on live session state.
 
 ```typescript
-// app/products/page.tsx
 import { storefront } from "@/lib/storefront";
 import { cookies } from "next/headers";
 
-export default async function ProductsPage() {
-  const sdk = storefront(cookies());
-  
-  const { data: products } = await sdk.catalog.listProducts();
-  
-  return (
-    <div>
-      {products?.products.map(product => (
-        <div key={product.id}>{product.name}</div>
-      ))}
-    </div>
-  );
+export default async function CartPage() {
+  const sdk = storefront.session(await cookies());
+  const { data: cart } = await sdk.cart.getCart();
+
+  return <pre>{JSON.stringify(cart, null, 2)}</pre>;
 }
 ```
 
 ### Server Actions
 
-Server Actions can both read and write cookies, perfect for authentication:
-
 ```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());
-  
+export async function loginWithPassword(email: string, password: string) {
+  const sdk = storefront.session(await 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 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 }
-    );
+  if (error) {
+    return { success: false, error: error.message };
   }
-}
-```
-
-### Root Layout (Special Case)
-
-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
-// app/layout.tsx
-import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
-import { storefront } from "@/lib/storefront";
-
-// Root Layout requires explicit flag - no request context available
-const sdk = storefront({ isRootLayout: true });
-const { data: storeConfig } = await sdk.store.getStoreConfig();
 
-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>
-  );
+  return { success: true, user: data?.user ?? null };
 }
 ```
 
-## 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
-
-Create or update your `next.config.ts` (or `next.config.js`) to enable automatic token caching during builds:
+### Static Generation
 
 ```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 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;
-```
-
-### SSG with generateStaticParams
-
-```typescript
-// app/products/[slug]/page.tsx
 import { storefront } from "@/lib/storefront";
 import { notFound } from "next/navigation";
 
-interface ProductPageProps {
+export default async function ProductPage({
+  params,
+}: {
   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 sdk = storefront.public();
+
   const { data, error } = await sdk.catalog.getProductDetail({
-    product_id_or_slug: slug
+    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>
-  );
+
+  return <h1>{data.product.name}</h1>;
 }
 
-// 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
-  }));
+  const sdk = storefront.public();
+  const { data } = await sdk.catalog.listProducts({ limit: 100 });
+
+  return (
+    data?.products.map((product) => ({
+      slug: product.slug || product.id,
+    })) ?? []
+  );
 }
 ```
 
-### Build Performance Benefits
-
-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
-
-## Authentication Patterns
+## Authentication Model
 
-> **⚠️ 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
+### `StorefrontSDKInitializer`
 
-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).
+`StorefrontSDKInitializer` is a client component that eagerly bootstraps the
+anonymous session once on first load by calling `ensureAccessToken()`.
 
 ```typescript
-// This works everywhere - creates anonymous token automatically
-const { data: products } = await storefront(cookies()).catalog.listProducts();
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+
+<StorefrontSDKInitializer />
 ```
 
-### Email/Password Login
+It accepts an optional `runtimeConfig` prop when you need client-only runtime
+overrides:
 
 ```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 };
-}
+<StorefrontSDKInitializer runtimeConfig={{ debug: true }} />
 ```
 
-### Phone/OTP Login
+### Where token-returning endpoints should run
 
-```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
-  });
-}
+Calls that create or replace tokens should run in places that can persist the
+resulting session cleanly:
 
-// 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 };
-}
-```
+- Client Components
+- Server Actions
+- Route Handlers
+
+Server Components are best used for reads against an already-established
+session, not for login/register/reset-password flows.
 
 ## API Reference
 
 ### `createStorefront(config?)`
 
-Creates a configured storefront function that works universally across all Next.js contexts.
+Creates the configured Next.js storefront factory.
 
 ```typescript
 import { createStorefront } from "@commercengine/storefront-sdk-nextjs";
 
 export const storefront = createStorefront({
   debug: true,
-  logger: (msg, ...args) => console.log('[DEBUG]', msg, ...args)
+  timeout: 15000,
 });
 ```
 
-**Parameters:**
-- `config` (optional): `StorefrontRuntimeConfig` - Advanced configuration options
+The returned type is:
 
-**Returns:**
-- Universal `storefront()` function that works in all Next.js contexts
+```typescript
+type NextJSStorefront = {
+  public: () => PublicStorefrontSDK;
+  session: {
+    (): SessionStorefrontSDK;
+    (cookieStore: NextCookieStore): SessionStorefrontSDK;
+  };
+};
+```
 
 ### `StorefrontRuntimeConfig`
 
@@ -456,15 +280,12 @@ 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;
@@ -475,167 +296,86 @@ interface StorefrontRuntimeConfig {
 }
 ```
 
-### Universal `storefront()` Function
+All core SDK types are re-exported from this package, so you can also import
+`UserInfo`, `SessionStorefrontSDKOptions`, `components`, `operations`, and more
+directly from `@commercengine/storefront-sdk-nextjs`.
 
-The function returned by `createStorefront()` works in all contexts with strict enforcement:
-
-```typescript
-// Client-side (browser)
-const sdk = storefront();
+## Best Practices
 
-// Server-side (requires cookies for user continuity)  
-const sdk = storefront(cookies());
+- Create one `lib/storefront.ts` file and reuse it everywhere.
+- Use `storefront.public()` for root layouts, static generation, and other
+  public reads.
+- Use `storefront.session(await cookies())` for server-side session reads.
+- Use `storefront.session()` in Client Components.
+- Mount `StorefrontSDKInitializer` once in the root layout.
+- Treat `public()` and `session()` as different semantics, not just different
+  runtimes.
 
-// Root Layout (special exception with explicit flag)
-const sdk = storefront({ isRootLayout: true });
+## Troubleshooting
 
-// Server-side without cookies - throws helpful error to protect user sessions
-const sdk = storefront(); // ❌ Throws error in server contexts
-```
+### "Server session access requires cookies"
 
-### Function Signatures
+You called `storefront.session()` on the server without `cookies()`.
 
 ```typescript
-function storefront(): StorefrontSDK;
-function storefront(cookieStore: NextCookieStore): StorefrontSDK;
-function storefront(options: { isRootLayout: true }): StorefrontSDK;
-function storefront(cookieStore: NextCookieStore, options: { isRootLayout?: boolean }): StorefrontSDK;
-```
+// Wrong on the server
+const sdk = storefront.session();
 
-### `StorefrontSDKInitializer`
+// Correct on the server
+const sdk = storefront.session(await cookies());
 
-Client-side initializer component (must be imported from `/client`):
-
-```typescript
-import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
-
-<StorefrontSDKInitializer />
+// Correct for public reads
+const publicSdk = storefront.public();
 ```
 
-No props needed - configuration comes from environment variables and your `lib/storefront.ts` file.
+### Root layout usage
 
-## Error Handling
+There is no special `isRootLayout` escape hatch anymore. Root layouts should use
+`storefront.public()` for public reads and `StorefrontSDKInitializer` to eager
+bootstrap the client session.
 
-All SDK methods return a consistent error structure:
+### Missing environment variables
 
-```typescript
-const { data, error, response } = await storefront(cookies()).catalog.listProducts();
+Make sure these are set:
 
-if (error) {
-  console.error("API Error:", error.message, error.code);
-  console.log("Status:", response.status);
-} else {
-  console.log("Products:", data.products);
-}
+```bash
+NEXT_PUBLIC_STORE_ID=your-store-id
+NEXT_PUBLIC_API_KEY=your-api-key
+NEXT_PUBLIC_ENVIRONMENT=staging
 ```
 
-## Best Practices
-
-### ✅ 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
+### From the previous Next.js wrapper API
 
 ```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());
+// Before
+storefront();
+storefront(await cookies());
+storefront({ isRootLayout: true });
+
+// After
+storefront.session();
+storefront.session(await cookies());
+storefront.public();
 ```
 
-## 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!** 🛡️
+### From direct core SDK usage
 
-## API Reference
-
-For complete API documentation of all available endpoints, visit [SDK DOCS REFERENCE](https://llm-docs.commercengine.io/sdk/)
-
-The Next.js SDK provides access to all the same endpoints as the core SDK:
+```typescript
+// Before
+import { SessionStorefrontSDK } from "@commercengine/storefront-sdk";
 
-- `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.payments.*` - Payment methods and processing
-- `sdk.store.*` - Store configuration
-- `sdk.helpers.*` - Countries, currencies, utilities
+// After
+import { SessionStorefrontSDK } from "@commercengine/storefront-sdk";
+```
 
-## Related Packages
+Or, for the recommended DX:
 
-- [`@commercengine/storefront-sdk`](../storefront-sdk) - Core Storefront SDK
+```typescript
+import { createStorefront } from "@commercengine/storefront-sdk-nextjs";
+```
 
 ## License
 
-All Rights Reserved
+All Rights Reserved