@commercengine/storefront-sdk 0.3.11 → 0.3.12

package/README.md

@@ -1,6 +1,13 @@
 # Storefront SDK
 
-TypeScript SDK for the CommerceEngine Storefront API.
+A powerful, type-safe TypeScript SDK for the CommerceEngine Storefront API. Built with modern JavaScript patterns, automatic token management, and comprehensive error handling.
+
+**✨ Key Features:**
+- **100% Type Safe**: Every API endpoint is fully typed with TypeScript
+- **Automatic Token Management**: Built-in refresh token logic for seamless authentication
+- **Universal Compatibility**: Works in browser, Node.js, and hybrid rendering environments
+- **Production Ready**: Implements all API best practices out of the box
+- **Zero Configuration**: Works with sensible defaults, extensive customization available
 
 ## Installation
 
@@ -8,104 +15,398 @@ TypeScript SDK for the CommerceEngine Storefront API.
 npm install @commercengine/storefront-sdk
 ```
 
-Or with yarn:
-
 ```bash
 yarn add @commercengine/storefront-sdk
 ```
 
-Or with pnpm:
-
 ```bash
 pnpm add @commercengine/storefront-sdk
 ```
 
-## Usage
-
-### Initializing the SDK
-
-You can initialize the SDK in just a few lines:
+## Quick Start
 
 ```typescript
 import StorefrontSDK, { Environment } from "@commercengine/storefront-sdk";
 
-// Initialize with environment and store ID
+// Basic initialization
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  environment: Environment.Staging,
+  apiKey: "your-api-key", // Required for authentication
+});
+
+// Get started with anonymous authentication
+const { data, error } = await sdk.auth.getAnonymousToken();
+if (error) {
+  console.log(error)
+} else {
+  accessToken = data.accessToken
+}
+```
+
+## Configuration Options
+
+The SDK supports extensive configuration to fit your needs:
+
+### Basic Configuration
+
+```typescript
 const sdk = new StorefrontSDK({
+  // Required
   storeId: "your-store-id",
+  
+  // Environment (optional, defaults to Production)
   environment: Environment.Staging, // or Environment.Production
+  
+  // API key for authentication (required for auth endpoints)
+  apiKey: "your-api-key",
 });
+```
+
+### Advanced Configuration
 
-// Or with a custom base URL (if needed)
-const customSdk = new StorefrontSDK({
+```typescript
+const sdk = new StorefrontSDK({
   storeId: "your-store-id",
-  baseUrl: "https://custom-api.example.com",
+  environment: Environment.Production,
+  
+  // Token Management
+  accessToken: "initial-access-token",     // Initial access token
+  refreshToken: "initial-refresh-token",   // Initial refresh token (for automatic mode)
+  
+  // Custom base URL (optional, overrides environment) - Not needed for most implementations
+  baseUrl: "https://your-custom-api.example.com",
+  
+  // Request Configuration
+  timeout: 10000,                          // Request timeout in milliseconds
+  
+  // Default Headers (auto applied to all applicable requests)
+  defaultHeaders: {
+    customer_group_id: "01JHS28V83KDWTRBXXJQRTEKA0", // For pricing and promotions
+  },
+  
+  // 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
 });
 ```
 
-### Authentication
+## Token Management
+
+The SDK offers two approaches to token management:
+
+### 1. Manual Token Management (Simple)
 
-The SDK supports various authentication methods:
+For basic use cases where you manage tokens yourself:
 
 ```typescript
-// Anonymous authentication
-const { access_token, refresh_token, user } =
-  await sdk.auth.getAnonymousToken();
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  apiKey: "your-api-key",
+});
 
-// Phone login
-const { otp_token, otp_action } = await sdk.auth.loginWithPhone("9876543210");
+// Login and set tokens manually
+const { data: loginData } = await sdk.auth.loginWithPassword({
+  email: "user@example.com",
+  password: "password",
+});
 
-// Email login
-const { otp_token, otp_action } = await sdk.auth.loginWithEmail(
-  "user@example.com"
-);
+if (loginData) {
+  await sdk.setTokens(loginData.access_token);
+}
+```
 
-// Verify OTP
-const { user, access_token, refresh_token } = await sdk.auth.verifyOtp(
-  "123456",
-  otp_token,
-  "login"
-);
+### 2. Automatic Token Management (Recommended)
 
-// Password login
-const { user, access_token, refresh_token } = await sdk.auth.loginWithPassword({
-  email: "user@example.com",
-  password: "your-password",
+For production applications with automatic token refresh and persistence:
+
+```typescript
+import StorefrontSDK, { BrowserTokenStorage } from "@commercengine/storefront-sdk";
+
+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");
+  },
+});
+```
+
+### Token Storage Options
+
+Choose the storage method that fits your environment:
+
+#### Browser localStorage
+```typescript
+import { BrowserTokenStorage } from "@commercengine/storefront-sdk";
+
+const tokenStorage = new BrowserTokenStorage("myapp_"); // Optional prefix
+```
+
+#### Cookies (for SSR or cross-tab sync)
+```typescript
+import { CookieTokenStorage } from "@commercengine/storefront-sdk";
+
+const tokenStorage = new CookieTokenStorage({
+  prefix: "myapp_",
+  maxAge: 7 * 24 * 60 * 60, // 7 days
+  secure: true,
+  sameSite: "Lax",
 });
+```
+
+#### Memory (for server-side or temporary storage)
+```typescript
+import { MemoryTokenStorage } from "@commercengine/storefront-sdk";
+
+const tokenStorage = new MemoryTokenStorage();
+```
+
+#### Custom Storage
+```typescript
+class CustomTokenStorage implements TokenStorage {
+  async getAccessToken(): Promise<string | null> {
+    // Your implementation
+  }
+  
+  async setAccessToken(token: string): Promise<void> {
+    // Your implementation
+  }
+  
+  // ... implement other required methods
+}
+```
 
-// Registration
-const { user, access_token, refresh_token } = await sdk.auth.registerWithPhone({
+## Authentication
+
+### Anonymous Authentication
+```typescript
+// Get anonymous token for guest users
+const { data } = await sdk.auth.getAnonymousToken();
+if (data) {
+  await sdk.setTokens(data.access_token, data.refresh_token);
+}
+```
+
+### Phone/Email Authentication
+```typescript
+// Step 1: Initiate login
+const { data: otpData } = await sdk.auth.loginWithPhone({
   phone: "9876543210",
+  country_code: "+91",
+  register_if_not_exists: true,
+});
+
+// Step 2: Verify OTP
+if (otpData) {
+  const { data: authData } = await sdk.auth.verifyOtp({
+    otp: "123456",
+    otp_token: otpData.otp_token,
+    otp_action: otpData.otp_action,
+  });
+  
+  if (authData) {
+    await sdk.setTokens(authData.access_token, authData.refresh_token);
+  }
+}
+```
+
+### Password Authentication
+```typescript
+const { data } = await sdk.auth.loginWithPassword({
   email: "user@example.com",
-  first_name: "John",
-  last_name: "Doe",
+  password: "your-password",
+});
+
+if (data) {
+  await sdk.setTokens(data.access_token, data.refresh_token);
+}
+```
+
+## API Clients & Complete Type Safety
+
+The SDK provides **complete access to every CommerceEngine API endpoint** with full TypeScript support. All clients are automatically generated from the OpenAPI specification, ensuring 100% accuracy and type safety.
+
+### Available Clients
+
+```typescript
+// Authentication & User Management
+sdk.auth.*     // Login, registration, OTP, password management
+sdk.customer.* // Customer profiles, addresses, preferences
+
+// E-commerce Core
+sdk.catalog.*  // Products, categories, search, variants
+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
+```
+
+### Example Usage
+
+```typescript
+// Every method is fully typed - IntelliSense shows all available parameters
+const { data: products } = await sdk.catalog.listProducts({
+  query: {
+    page: 1,
+    limit: 20,
+    category_id: "electronics",
+    sort: "price_asc",
+  }
+});
+
+// Get product details
+const { data: product } = await sdk.catalog.getProduct({
+  product_id_or_slug: "product-id"
 });
 
-// Token management
-sdk.setToken(access_token); // Set token for all clients
-sdk.clearToken(); // Clear token from all clients
+// Create a cart with full type checking
+const { data: cart } = await sdk.cart.createCart({
+  items: [
+    {
+      product_id: "product-id",
+      quantity: 2,
+      variant_id: "variant-id",
+    }
+  ]
+});
+```
+
+> **📚 API Reference**: For complete endpoint documentation, parameters, and response schemas, visit [docs.commercengine.io/api-reference](https://docs.commercengine.io/api-reference)
+
+## User Information & JWT Utilities
+
+Extract user information from tokens with built-in utilities:
+
+```typescript
+// Get current user info
+const userInfo = await sdk.getUserInfo();
+console.log(userInfo?.userId, userInfo?.email, userInfo?.customerId);
+
+// Check authentication status
+const isLoggedIn = await sdk.isLoggedIn();
+const isAnonymous = await sdk.isAnonymous();
+
+// Get specific user data
+const userId = await sdk.getUserId();
+const customerId = await sdk.getCustomerId();
+const customerGroupId = await sdk.getCustomerGroupId();
 ```
 
-### Using the API Clients
+## Error Handling
+
+All API calls return a consistent `ApiResult<T>` structure with full error information:
+
+```typescript
+const { data, error, response } = await sdk.catalog.listProducts();
 
-The SDK provides dedicated clients for different API sections:
+if (error) {
+  console.error("API Error:", error.message, error.code);
+  console.log("Status:", response.status);
+} else {
+  console.log("Success:", data);
+}
+```
 
+### Network Error Handling
 ```typescript
-// Catalog client example (product listing)
-const products = await sdk.catalog.listProducts();
+const result = await sdk.catalog.getProduct({ product_id_or_slug: "invalid-id" });
 
-// Cart client example (add to cart)
-const cart = await sdk.cart.addToCart("product-id", 1);
+if (result.error) {
+  switch (result.error.code) {
+    case "NETWORK_ERROR":
+      console.log("Network connection failed");
+      break;
+    case "UNAUTHORIZED":
+      console.log("Authentication required");
+      break;
+    default:
+      console.log("API Error:", result.error.message);
+  }
+}
 ```
 
-## Advanced Configuration
+## Debug Mode
 
-You can configure timeout and other options:
+Enable detailed logging for development:
 
 ```typescript
 const sdk = new StorefrontSDK({
   storeId: "your-store-id",
-  environment: Environment.Production,
-  timeout: 5000, // 5 second timeout
-  token: "existing-token", // Initialize with an existing token
+  debug: true,
+  // Optional: Pass a custom logger 
+  logger: (message, data) => {
+    console.log(`[SDK Debug] ${message}`, data);
+  },
 });
 ```
+
+Debug mode logs:
+- Request URLs, methods, headers, and bodies
+- Response status, headers, and bodies  
+- Token refresh attempts and results
+- Network errors and retry attempts
+
+## TypeScript Support
+
+The SDK is built with TypeScript-first design:
+
+```typescript
+import type { 
+  ApiResult, 
+  UserInfo, 
+  DebugLoggerFn,
+  SupportedDefaultHeaders 
+} from "@commercengine/storefront-sdk";
+
+// All API responses are properly typed
+const { data }: ApiResult<ProductListResponse> = await sdk.catalog.listProducts();
+
+// IntelliSense works for all nested properties
+console.log(data?.products[0].name);
+```
+
+## Universal Compatibility
+
+The SDK works seamlessly across all JavaScript environments:
+
+### Client-Side Applications
+- **React, Vue, Angular**: Use `BrowserTokenStorage` for persistent sessions
+- **Automatic token refresh**: Handles token expiry transparently
+- **Cross-tab synchronization**: With `CookieTokenStorage`
+
+### Server-Side Applications  
+- **Node.js, Bun, Deno**: Use `MemoryTokenStorage` or custom storage
+- **API routes**: Perfect for Next.js API routes, Express middleware
+- **Background jobs**: Reliable token management for long-running processes
+
+### Hybrid Rendering (SSR/SSG)
+- **Next.js, Nuxt, SvelteKit**: Seamless client/server token handoff
+- **Cookie-based storage**: Maintains sessions across server/client boundaries
+- **Hydration-safe**: No client/server state mismatches
+
+## Best Practices Built-In
+
+The SDK implements CommerceEngine API best practices automatically:
+
+- ✅ **Automatic token refresh** before expiry
+- ✅ **Proper error handling** for all edge cases  
+- ✅ **Request retries** for transient failures
+- ✅ **Rate limiting compliance** with proper backoff
+- ✅ **Security headers** and CSRF protection
+- ✅ **Timeout handling** with configurable limits
+- ✅ **Memory leak prevention** with proper cleanup
+
+## License
+
+This project is licensed under the MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercengine/storefront-sdk",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "TypeScript SDK for the Storefront API",
   "type": "module",
   "main": "dist/index.js",