Storefront SDK

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

npm install @commercengine/storefront-sdk

yarn add @commercengine/storefront-sdk

pnpm add @commercengine/storefront-sdk

Quick Start

import StorefrontSDK, { Environment } from "@commercengine/storefront-sdk";

// 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

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

const sdk = new StorefrontSDK({
  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)
  
  // 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
});

Token Management

The SDK offers two approaches to token management:

1. Manual Token Management (Simple)

For basic use cases where you manage tokens yourself:

const sdk = new StorefrontSDK({
  storeId: "your-store-id",
  apiKey: "your-api-key",
});

// Login and set tokens manually
const { data: loginData } = await sdk.auth.loginWithPassword({
  email: "[email protected]",
  password: "password",
});

if (loginData) {
  await sdk.setTokens(loginData.access_token);
}

2. Automatic Token Management (Recommended)

For production applications with automatic token refresh and persistence:

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

import { BrowserTokenStorage } from "@commercengine/storefront-sdk";

const tokenStorage = new BrowserTokenStorage("myapp_"); // Optional prefix

Cookies (for SSR or cross-tab sync)

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)

import { MemoryTokenStorage } from "@commercengine/storefront-sdk";

const tokenStorage = new MemoryTokenStorage();

Custom Storage

class CustomTokenStorage implements TokenStorage {
  async getAccessToken(): Promise<string | null> {
    // Your implementation
  }
  
  async setAccessToken(token: string): Promise<void> {
    // Your implementation
  }
  
  // ... implement other required methods
}

Authentication

Anonymous Authentication

// 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

// 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

const { data } = await sdk.auth.loginWithPassword({
  email: "[email protected]",
  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

// 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

// 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"
});

// 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

User Information & JWT Utilities

Extract user information from tokens with built-in utilities:

// 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();

Error Handling

All API calls return a consistent ApiResult<T> structure with full error information:

const { data, error, response } = await sdk.catalog.listProducts();

if (error) {
  console.error("API Error:", error.message, error.code);
  console.log("Status:", response.status);
} else {
  console.log("Success:", data);
}

Network Error Handling

const result = await sdk.catalog.getProduct({ product_id_or_slug: "invalid-id" });

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);
  }
}

Debug Mode

Enable detailed logging for development:

const sdk = new StorefrontSDK({
  storeId: "your-store-id",
  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:

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: Use NextJSTokenStorage for universal client/server token access
• Nuxt, SvelteKit: Use CookieTokenStorage for 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

Contributing

Version Management with Changeset

This project uses Changeset for version management and publishing. Here's how to contribute:

Creating Changes

When you make changes to the SDK, create a changeset to document them:

pnpm changeset

This will prompt you to:

• Select the type of change (patch/minor/major)
• Write a summary of what changed
• Create a markdown file in the .changeset/ folder

Version Types

• Patch (0.0.x): Bug fixes, documentation updates, internal refactoring
• Minor (0.x.0): New features, new API endpoints, backwards-compatible changes
• Major (x.0.0): Breaking changes, API modifications that affect existing code

Release Process

1. During Development: Create changesets for your changes

   pnpm changeset

2. Before Release: Consume changesets and update versions

   pnpm version

   This updates package.json, generates/updates CHANGELOG.md, and removes consumed changesets.

3. Publishing: Build and publish to npm

   pnpm release

Available Scripts

• pnpm changeset - Create a new changeset
• pnpm run version - Consume changesets and bump version
• pnpm run release - Build and publish to npm

The changeset workflow ensures proper semantic versioning, comprehensive changelogs, and coordinated releases.

License

All Rights Reserved