@commercengine/storefront-sdk 0.13.4 → 0.14.1

package/MIGRATION.md

@@ -0,0 +1,170 @@
+# Storefront SDK Migration Guide
+
+This guide covers the breaking changes introduced by the refactor that split
+the SDK into explicit public and session-aware surfaces.
+
+## Summary
+
+- `StorefrontSDK` was renamed to `SessionStorefrontSDK`
+- `StorefrontAPIClient` was renamed to `SessionStorefrontAPIClient`
+- `StorefrontSDKOptions` was renamed to `SessionStorefrontSDKOptions`
+- The default export was removed
+- `createStorefront()` is now the recommended entry point
+- `PublicStorefrontSDK` was added for strict API-key-backed public reads
+
+## Recommended Migration
+
+Move to the factory pattern:
+
+```typescript
+import {
+  BrowserTokenStorage,
+  Environment,
+  createStorefront,
+} from "@commercengine/storefront-sdk";
+
+export const storefront = createStorefront({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+  environment: Environment.Staging,
+  session: {
+    tokenStorage: new BrowserTokenStorage("myapp_"),
+  },
+});
+```
+
+Then use the explicit accessor that matches the request:
+
+```typescript
+const publicSdk = storefront.public();
+const sessionSdk = storefront.session();
+```
+
+## Before / After
+
+### Managed session SDK
+
+Before:
+
+```typescript
+import StorefrontSDK, {
+  BrowserTokenStorage,
+  Environment,
+} from "@commercengine/storefront-sdk";
+
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+  environment: Environment.Staging,
+  tokenStorage: new BrowserTokenStorage("myapp_"),
+});
+```
+
+After:
+
+```typescript
+import {
+  BrowserTokenStorage,
+  Environment,
+  createStorefront,
+} from "@commercengine/storefront-sdk";
+
+const storefront = createStorefront({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+  environment: Environment.Staging,
+  session: {
+    tokenStorage: new BrowserTokenStorage("myapp_"),
+  },
+});
+
+const sdk = storefront.session();
+```
+
+### Manual / stateless seeded tokens
+
+Before:
+
+```typescript
+import { StorefrontSDK } from "@commercengine/storefront-sdk";
+
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+  accessToken,
+  refreshToken,
+});
+```
+
+After:
+
+```typescript
+import { createStorefront } from "@commercengine/storefront-sdk";
+
+const storefront = createStorefront({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+});
+
+const sdk = storefront.session({
+  accessToken,
+  refreshToken,
+});
+```
+
+### Public build / prerender reads
+
+Before:
+
+```typescript
+import { StorefrontSDK } from "@commercengine/storefront-sdk";
+
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+});
+```
+
+After:
+
+```typescript
+import { createStorefront } from "@commercengine/storefront-sdk";
+
+const storefront = createStorefront({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+});
+
+const sdk = storefront.public();
+```
+
+## Advanced Direct Instantiation
+
+If you need direct class construction, use the explicit class names:
+
+```typescript
+import {
+  PublicStorefrontSDK,
+  SessionStorefrontSDK,
+} from "@commercengine/storefront-sdk";
+```
+
+The session SDK keeps the same managed/manual token behavior as before:
+
+- provide `tokenStorage` for managed mode
+- provide `accessToken` / `refreshToken` or call `setTokens()` for manual mode
+
+## Public vs Session Surface
+
+Use `public()` only for public reads that should never touch session bootstrap,
+refresh, token persistence, or token callbacks.
+
+Use `session()` for:
+
+- auth flows
+- cart operations
+- customer operations
+- order operations
+- payment operations
+- any request that should operate on behalf of an anonymous or authenticated
+  user session

package/README.md

@@ -2,6 +2,9 @@
 
 A powerful, type-safe TypeScript SDK for the CommerceEngine Storefront API. Built with modern JavaScript patterns, automatic token management, and comprehensive error handling.
 
+Breaking changes from the previous SDK surface are documented in
+[MIGRATION.md](./MIGRATION.md).
+
 **✨ Key Features:**
 - **100% Type Safe**: Every API endpoint is fully typed with TypeScript
 - **Automatic Token Management**: Built-in refresh token logic for seamless authentication
@@ -26,53 +29,54 @@ pnpm add @commercengine/storefront-sdk
 ## Quick Start
 
 ```typescript
-import StorefrontSDK, { Environment } from "@commercengine/storefront-sdk";
+import {
+  BrowserTokenStorage,
+  Environment,
+  createStorefront,
+} from "@commercengine/storefront-sdk";
 
-// Basic initialization
-const sdk = new StorefrontSDK({
+const storefront = createStorefront({
   storeId: "your-store-id",
   environment: Environment.Staging,
-  apiKey: "your-api-key", // Required for authentication
+  apiKey: "your-api-key",
+  session: {
+    tokenStorage: new BrowserTokenStorage("myapp_"),
+  },
 });
 
-// Get started with anonymous authentication
-const { data, error } = await sdk.auth.getAnonymousToken();
-if (error) {
-  console.log(error)
-} else {
-  accessToken = data.accessToken
-}
+// Public reads never touch session lifecycle
+const { data: products } = await storefront.public().catalog.listProducts();
+
+// User-scoped APIs can resolve user_id from the active session automatically
+const { data: wishlist } = await storefront.session().cart.getWishlist();
 ```
 
 ## Configuration Options
 
 The SDK supports extensive configuration to fit your needs:
 
-### Basic Configuration
+### Recommended Factory Pattern
 
 ```typescript
-const sdk = new StorefrontSDK({
+const storefront = createStorefront({
   // Required
   storeId: "your-store-id",
   
   // Environment (optional, defaults to Production)
   environment: Environment.Staging, // or Environment.Production
   
-  // API key for authentication (required for auth endpoints)
+  // API key for public and session-backed requests
   apiKey: "your-api-key",
 });
 ```
 
-### Advanced Configuration
+### Session Defaults
 
 ```typescript
-const sdk = new StorefrontSDK({
+const storefront = createStorefront({
   storeId: "your-store-id",
   environment: Environment.Production,
-  
-  // Token Management
-  accessToken: "initial-access-token",     // Initial access token
-  refreshToken: "initial-refresh-token",   // Initial refresh token (for automatic mode)
+  apiKey: "your-api-key",
   
   // Custom base URL (optional, overrides environment) - Not needed for most implementations
   baseUrl: "https://your-custom-api.example.com",
@@ -88,56 +92,111 @@ const sdk = new StorefrontSDK({
   // Debug and Logging
   debug: true,                             // Enable detailed request/response logging - Uses console.log by default
   logger: console.log,                     // Custom logger function - structure your logs any way you want. Also helpful to pipe logs into external services
+
+  session: {
+    // Token Management
+    accessToken: "initial-access-token",   // Initial access token
+    refreshToken: "initial-refresh-token", // Initial refresh token (for automatic mode)
+    tokenStorage: new BrowserTokenStorage("myapp_"),
+  },
+});
+```
+
+### Direct Session SDK (Advanced)
+
+If you only need the session-aware client directly, you can still instantiate it yourself:
+
+```typescript
+import {
+  BrowserTokenStorage,
+  Environment,
+  SessionStorefrontSDK,
+} from "@commercengine/storefront-sdk";
+
+const sdk = new SessionStorefrontSDK({
+  storeId: "your-store-id",
+  environment: Environment.Staging,
+  apiKey: "your-api-key",
+  tokenStorage: new BrowserTokenStorage("myapp_"),
 });
 ```
 
 ## Token Management
 
-The SDK offers two approaches to token management:
+The SDK supports three primary access patterns:
 
-### 1. Manual Token Management (Simple)
+### 1. Managed Sessions (Recommended)
 
-For basic use cases where you manage tokens yourself:
+Managed mode is enabled when you provide `tokenStorage`.
+The SDK can then:
+- Persist tokens
+- Refresh expired tokens
+- Bootstrap an anonymous session on the first token-required request
+- Resolve `user_id` automatically for user-scoped methods
 
 ```typescript
-const sdk = new StorefrontSDK({
+import {
+  BrowserTokenStorage,
+  SessionStorefrontSDK,
+} from "@commercengine/storefront-sdk";
+
+const sdk = new SessionStorefrontSDK({
   storeId: "your-store-id",
   apiKey: "your-api-key",
+  tokenStorage: new BrowserTokenStorage("myapp_"),
 });
+```
+
+### 2. Manual Sessions
+
+Manual mode is enabled when you set tokens directly (`accessToken` or `sdk.setTokens`) without `tokenStorage`.
+The SDK uses the token you provide but does not auto-refresh or auto-persist sessions.
 
-// Login and set tokens manually
-const { data: loginData } = await sdk.auth.loginWithPassword({
+```typescript
+const storefront = createStorefront({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+});
+
+const sdk = storefront.session();
+
+const { data } = await sdk.auth.loginWithPassword({
   email: "user@example.com",
   password: "password",
 });
 
-if (loginData) {
-  await sdk.setTokens(loginData.access_token);
+if (data) {
+  await sdk.setTokens(data.access_token, data.refresh_token);
 }
 ```
 
-### 2. Automatic Token Management (Recommended)
+For stateless/token-seeded requests, create a one-off session client:
 
-For production applications with automatic token refresh and persistence:
+```typescript
+const sdk = storefront.session({
+  accessToken: "existing-access-token",
+  refreshToken: "existing-refresh-token",
+});
+```
+
+### 3. Public Client
+
+Use `storefront.public()` when a flow should stay API-key-backed and never
+participate in session bootstrap, refresh, or token persistence.
+
+## Session Helpers (`sdk.session`)
+
+Use `sdk.session` when you need explicit control over passive vs active session reads.
+
+- `peek*` methods are passive reads and never mint/refresh.
+- `ensure*` methods can mint/refresh in managed mode.
 
 ```typescript
-import StorefrontSDK, { BrowserTokenStorage } from "@commercengine/storefront-sdk";
+// Passive read (no side effects)
+const userId = await sdk.session.peekUserId();
 
-const sdk = new StorefrontSDK({
-  storeId: "your-store-id",
-  apiKey: "your-api-key",
-  
-  // Enable automatic token management
-  tokenStorage: new BrowserTokenStorage("myapp_"), // Prefix for localStorage keys
-  
-  // Optional callbacks
-  onTokensUpdated: (accessToken, refreshToken) => {
-    console.log("Tokens updated!");
-  },
-  onTokensCleared: () => {
-    console.log("User logged out");
-  },
-});
+// Active resolution (may mint or refresh in managed mode)
+const resolvedUserId = await sdk.session.ensureUserId();
 ```
 
 ### Token Storage Options
@@ -187,9 +246,11 @@ class CustomTokenStorage implements TokenStorage {
 
 ## Authentication
 
+If you use managed sessions (`tokenStorage`), you usually do not need to call anonymous auth manually. The SDK can bootstrap anonymous sessions automatically on token-required requests.
+
 ### Anonymous Authentication
 ```typescript
-// Get anonymous token for guest users
+// Optional: manually create an anonymous session
 const { data } = await sdk.auth.getAnonymousToken();
 if (data) {
   await sdk.setTokens(data.access_token, data.refresh_token);
@@ -248,8 +309,8 @@ sdk.cart.*     // Cart management, coupons, promotions
 sdk.order.*    // Order creation, tracking, history
 
 // Supporting Services  
-sdk.shipping.* // Shipping methods, rates, tracking
 sdk.helpers.*  // Countries, currencies, utilities
+sdk.store.*    // Store config and health endpoints
 ```
 
 ### Example Usage
@@ -286,10 +347,10 @@ const { data: cart } = await sdk.cart.createCart({
 
 ## User Information & JWT Utilities
 
-Extract user information from tokens with built-in utilities:
+The top-level getters are passive lookups. They never mint or refresh a session:
 
 ```typescript
-// Get current user info
+// Passive reads from the current token
 const userInfo = await sdk.getUserInfo();
 console.log(userInfo?.userId, userInfo?.email, userInfo?.customerId);
 
@@ -303,6 +364,21 @@ const customerId = await sdk.getCustomerId();
 const customerGroupId = await sdk.getCustomerGroupId();
 ```
 
+Use `sdk.session.ensure*` for active resolution:
+
+```typescript
+const userId = await sdk.session.ensureUserId();
+const accessToken = await sdk.session.ensureAccessToken();
+```
+
+For user-scoped APIs, `user_id` can be omitted and resolved automatically in managed mode:
+
+```typescript
+await sdk.cart.getWishlist();
+await sdk.customer.listAddresses();
+await sdk.order.listOrders({ page: 1, limit: 20 });
+```
+
 ## Error Handling
 
 All API calls return a consistent `ApiResult<T>` structure with full error information:
@@ -341,7 +417,7 @@ if (result.error) {
 Enable detailed logging for development:
 
 ```typescript
-const sdk = new StorefrontSDK({
+const sdk = new SessionStorefrontSDK({
   storeId: "your-store-id",
   debug: true,
   // Optional: Pass a custom logger 
@@ -391,8 +467,8 @@ The SDK works seamlessly across all JavaScript environments:
 - **Background jobs**: Reliable token management for long-running processes
 
 ### Hybrid Rendering (SSR/SSG)
-- **Next.js**: Use `NextJSTokenStorage` for universal client/server token access
-- **Nuxt, SvelteKit**: Use `CookieTokenStorage` for seamless client/server token handoff
+- **Next.js, Nuxt, SvelteKit, Remix**: Use request-aware cookie-backed storage
+- **CookieTokenStorage**: Useful for browser cookie persistence
 - **Cookie-based storage**: Maintains sessions across server/client boundaries
 - **Hydration-safe**: No client/server state mismatches