@commercengine/storefront-sdk 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Storefront SDK
+
+TypeScript SDK for the CommerceEngine Storefront API.
+
+## Installation
+
+```bash
+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:
+
+```typescript
+import StorefrontSDK, { Environment } from "@commercengine/storefront-sdk";
+
+// Initialize with environment and store ID
+const sdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  environment: Environment.Staging, // or Environment.Production
+});
+
+// Or with a custom base URL (if needed)
+const customSdk = new StorefrontSDK({
+  storeId: "your-store-id",
+  baseUrl: "https://custom-api.example.com",
+});
+```
+
+### Authentication
+
+The SDK supports various authentication methods:
+
+```typescript
+// Anonymous authentication
+const { access_token, refresh_token, user } =
+  await sdk.auth.getAnonymousToken();
+
+// Phone login
+const { otp_token, otp_action } = await sdk.auth.loginWithPhone("9876543210");
+
+// Email login
+const { otp_token, otp_action } = await sdk.auth.loginWithEmail(
+  "user@example.com"
+);
+
+// Verify OTP
+const { user, access_token, refresh_token } = await sdk.auth.verifyOtp(
+  "123456",
+  otp_token,
+  "login"
+);
+
+// Password login
+const { user, access_token, refresh_token } = await sdk.auth.loginWithPassword({
+  email: "user@example.com",
+  password: "your-password",
+});
+
+// Registration
+const { user, access_token, refresh_token } = await sdk.auth.registerWithPhone({
+  phone: "9876543210",
+  email: "user@example.com",
+  first_name: "John",
+  last_name: "Doe",
+});
+
+// Token management
+sdk.setToken(access_token); // Set token for all clients
+sdk.clearToken(); // Clear token from all clients
+```
+
+### Using the API Clients
+
+The SDK provides dedicated clients for different API sections:
+
+```typescript
+// Catalog client example (product listing)
+const products = await sdk.catalog.listProducts();
+
+// Cart client example (add to cart)
+const cart = await sdk.cart.addToCart("product-id", 1);
+```
+
+## Advanced Configuration
+
+You can configure timeout and other options:
+
+```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
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { StorefrontAPIClient, Environment } from "./lib/client";
+import { CatalogClient } from "./lib/catalog";
+import { CartClient } from "./lib/cart";
+import { AuthClient } from "./lib/auth";
+/**
+ * SDK initialization options
+ */
+export interface StorefrontSDKOptions {
+    /**
+     * Store ID for the API requests
+     */
+    storeId: string;
+    /**
+     * Environment to use (defaults to Production)
+     */
+    environment?: Environment;
+    /**
+     * Custom base URL (overrides environment if provided)
+     */
+    baseUrl?: string;
+    /**
+     * Optional authentication token
+     */
+    token?: string;
+    /**
+     * X-Api-Key for anonymous authentication endpoints
+     * Required for initial authentication
+     */
+    apiKey?: string;
+    /**
+     * Optional timeout in milliseconds
+     */
+    timeout?: number;
+}
+/**
+ * Main SDK class for the Storefront API
+ */
+export declare class StorefrontSDK {
+    /**
+     * Client for catalog-related endpoints (products, categories, etc.)
+     */
+    readonly catalog: CatalogClient;
+    /**
+     * Client for cart-related endpoints
+     */
+    readonly cart: CartClient;
+    /**
+     * Client for authentication-related endpoints
+     */
+    readonly auth: AuthClient;
+    /**
+     * Create a new StorefrontSDK instance
+     *
+     * @param options - Configuration options for the SDK
+     */
+    constructor(options: StorefrontSDKOptions);
+    /**
+     * Set the authentication token for all clients
+     *
+     * @param token - The authentication token
+     */
+    setToken(token: string): void;
+    /**
+     * Clear the authentication token from all clients
+     */
+    clearToken(): void;
+    /**
+     * Set the API key for all clients
+     *
+     * @param apiKey - The API key to set
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Clear the API key from all clients
+     */
+    clearApiKey(): void;
+}
+export default StorefrontSDK;
+export { StorefrontAPIClient, CatalogClient, CartClient, AuthClient };
+export { Environment };

package/dist/index.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Environment = exports.AuthClient = exports.CartClient = exports.CatalogClient = exports.StorefrontAPIClient = exports.StorefrontSDK = void 0;
+const client_1 = require("./lib/client");
+Object.defineProperty(exports, "StorefrontAPIClient", { enumerable: true, get: function () { return client_1.StorefrontAPIClient; } });
+Object.defineProperty(exports, "Environment", { enumerable: true, get: function () { return client_1.Environment; } });
+const catalog_1 = require("./lib/catalog");
+Object.defineProperty(exports, "CatalogClient", { enumerable: true, get: function () { return catalog_1.CatalogClient; } });
+const cart_1 = require("./lib/cart");
+Object.defineProperty(exports, "CartClient", { enumerable: true, get: function () { return cart_1.CartClient; } });
+const auth_1 = require("./lib/auth");
+Object.defineProperty(exports, "AuthClient", { enumerable: true, get: function () { return auth_1.AuthClient; } });
+/**
+ * Main SDK class for the Storefront API
+ */
+class StorefrontSDK {
+    /**
+     * Create a new StorefrontSDK instance
+     *
+     * @param options - Configuration options for the SDK
+     */
+    constructor(options) {
+        // Convert options to internal config format
+        const config = {
+            storeId: options.storeId,
+            environment: options.environment,
+            baseUrl: options.baseUrl,
+            token: options.token,
+            apiKey: options.apiKey,
+            timeout: options.timeout,
+        };
+        this.catalog = new catalog_1.CatalogClient(config);
+        this.cart = new cart_1.CartClient(config);
+        this.auth = new auth_1.AuthClient(config);
+    }
+    /**
+     * Set the authentication token for all clients
+     *
+     * @param token - The authentication token
+     */
+    setToken(token) {
+        this.catalog.setToken(token);
+        this.cart.setToken(token);
+        this.auth.setToken(token);
+    }
+    /**
+     * Clear the authentication token from all clients
+     */
+    clearToken() {
+        this.catalog.clearToken();
+        this.cart.clearToken();
+        this.auth.clearToken();
+    }
+    /**
+     * Set the API key for all clients
+     *
+     * @param apiKey - The API key to set
+     */
+    setApiKey(apiKey) {
+        this.catalog.setApiKey(apiKey);
+        this.cart.setApiKey(apiKey);
+        this.auth.setApiKey(apiKey);
+    }
+    /**
+     * Clear the API key from all clients
+     */
+    clearApiKey() {
+        this.catalog.clearApiKey();
+        this.cart.clearApiKey();
+        this.auth.clearApiKey();
+    }
+}
+exports.StorefrontSDK = StorefrontSDK;
+// Export the main SDK class
+exports.default = StorefrontSDK;

package/dist/lib/auth.d.ts

@@ -0,0 +1,261 @@
+import { StorefrontAPIClient, StorefrontAPIConfig } from "./client";
+import type { components } from "../types/storefront";
+/**
+ * Client for interacting with authentication endpoints
+ */
+export declare class AuthClient extends StorefrontAPIClient {
+    private tokenStorage;
+    private autoRefreshTimer;
+    constructor(config: StorefrontAPIConfig, tokenStorage?: TokenStorage);
+    setToken(token: string): void;
+    protected setRefreshToken(token: string): void;
+    clearToken(): void;
+    private setupAutoRefresh;
+    private clearAutoRefresh;
+    private handleTokenRefresh;
+    private getTokenExpiry;
+    /**
+     * Get an anonymous user token
+     *
+     * @param options - Options for anonymous authentication
+     * @returns Promise with user info and tokens
+     */
+    getAnonymousToken(options?: {
+        apiKey?: string;
+    }): Promise<{
+        user: components["schemas"]["AnonymousUser"];
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Login with phone number
+     *
+     * @param phoneNumber - Phone number (without country code)
+     * @param countryCode - Country code (defaults to +91)
+     * @param registerIfNotExists - Whether to register if user doesn't exist
+     * @returns Promise with OTP token and action
+     */
+    loginWithPhone(phoneNumber: string, countryCode?: string, registerIfNotExists?: boolean): Promise<{
+        otp_token: string;
+        otp_action: string;
+    }>;
+    /**
+     * Login with email
+     *
+     * @param email - Email address
+     * @param registerIfNotExists - Whether to register if user doesn't exist
+     * @returns Promise with OTP token and action
+     */
+    loginWithEmail(email: string, registerIfNotExists?: boolean): Promise<{
+        otp_token: string;
+        otp_action: string;
+    }>;
+    /**
+     * Login with password
+     *
+     * @param options - Login credentials
+     * @returns Promise with user info and tokens
+     */
+    loginWithPassword(options: {
+        email?: string;
+        phone?: string;
+        country_code?: string;
+        password: string;
+    }): Promise<{
+        user: components["schemas"]["User"];
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Verify OTP
+     *
+     * @param otp - One-time password
+     * @param otpToken - OTP token from login request
+     * @param otpAction - OTP action from login request
+     * @returns Promise with user info and tokens
+     */
+    verifyOtp(otp: string, otpToken: string, otpAction: "login" | "register" | "reset-password" | "verify-phone" | "verify-email" | "update-phone" | "update-email"): Promise<{
+        user?: components["schemas"]["User"];
+        access_token?: string;
+        refresh_token?: string;
+    }>;
+    /**
+     * Register with phone
+     *
+     * @param options - Registration details
+     * @returns Promise with user info and tokens
+     */
+    registerWithPhone(options: {
+        country_code?: string;
+        phone: string;
+        first_name: string;
+        last_name?: string;
+        email: string;
+        otp_token?: string;
+    }): Promise<{
+        user: components["schemas"]["User"];
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Register with email
+     *
+     * @param options - Registration details
+     * @returns Promise with user info and tokens
+     */
+    registerWithEmail(options: {
+        email: string;
+        first_name: string;
+        last_name?: string;
+        phone: string;
+        otp_token?: string;
+    }): Promise<{
+        user: components["schemas"]["User"];
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Refresh token
+     *
+     * @param refreshToken - Refresh token
+     * @returns Promise with new tokens
+     */
+    refreshToken(refreshToken: string): Promise<{
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Logout
+     *
+     * @returns Promise that resolves when logout is complete
+     */
+    logout(): Promise<void>;
+    /**
+     * Override the base client's attemptTokenRefresh method
+     * to implement token refresh for 401 errors
+     *
+     * @returns Promise that resolves to true if token was refreshed, false otherwise
+     */
+    protected attemptTokenRefresh(): Promise<boolean>;
+    /**
+     * Execute a request with automatic token refresh handling
+     * This wraps any API call in logic that will catch authentication errors,
+     * attempt to refresh the token, and retry the request once
+     *
+     * @param requestFn - Function that executes the API request
+     * @returns Promise with the API response
+     */
+    executeWithTokenRefresh<T>(requestFn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Interface for token storage implementations
+ */
+export interface TokenStorage {
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string): void;
+    clearTokens(): void;
+}
+/**
+ * Default in-memory implementation of token storage
+ */
+export declare class MemoryTokenStorage implements TokenStorage {
+    private accessToken;
+    private refreshToken;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string): void;
+    clearTokens(): void;
+}
+/**
+ * Browser storage implementation using localStorage
+ */
+export declare class BrowserTokenStorage implements TokenStorage {
+    private accessTokenKey;
+    private refreshTokenKey;
+    constructor(prefix?: string);
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string): void;
+    clearTokens(): void;
+}
+/**
+ * Cookie-based token storage for browser or server environments
+ */
+export declare class CookieTokenStorage implements TokenStorage {
+    private accessTokenKey;
+    private refreshTokenKey;
+    private cookieOptions;
+    constructor(prefix?: string, cookieOptions?: {
+        path: string;
+        secure: boolean;
+        sameSite: string;
+        maxAge: number;
+    });
+    /**
+     * Get access token from cookies
+     * Works in both browser and Next.js server components
+     */
+    getAccessToken(): string | null;
+    /**
+     * Set access token in cookies
+     * Works in browser environment
+     */
+    setAccessToken(token: string): void;
+    /**
+     * Get refresh token from cookies
+     * Works in both browser and Next.js server components
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Set refresh token in cookies
+     * Works in browser environment
+     */
+    setRefreshToken(token: string): void;
+    /**
+     * Clear all tokens from cookies
+     */
+    clearTokens(): void;
+}
+/**
+ * Next.js specific cookie storage implementation
+ * Works with the Next.js cookies API
+ */
+export declare class NextCookieTokenStorage implements TokenStorage {
+    private accessTokenKey;
+    private refreshTokenKey;
+    private cookieStore;
+    constructor(cookieStore: any, prefix?: string);
+    /**
+     * Get access token from Next.js cookies
+     */
+    getAccessToken(): string | null;
+    /**
+     * Set access token in Next.js cookies
+     */
+    setAccessToken(token: string): void;
+    /**
+     * Get refresh token from Next.js cookies
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Set refresh token in Next.js cookies
+     */
+    setRefreshToken(token: string): void;
+    /**
+     * Clear all tokens from Next.js cookies
+     */
+    clearTokens(): void;
+}
+/**
+ * Helper to create a token storage instance based on environment
+ * Automatically selects the best storage method based on context
+ */
+export declare function createTokenStorage(options?: {
+    prefix?: string;
+    cookieStore?: any;
+    useLocalStorage?: boolean;
+}): TokenStorage;