@commercengine/storefront-sdk 0.1.0

package/dist/lib/client.d.ts

@@ -0,0 +1,146 @@
+import createClient from "openapi-fetch";
+/**
+ * Available API environments
+ */
+export declare enum Environment {
+    /**
+     * Staging environment
+     */
+    Staging = "staging",
+    /**
+     * Production environment
+     */
+    Production = "production"
+}
+import type { paths } from "../types/storefront";
+/**
+ * Configuration options for the StorefrontAPI client
+ */
+export interface StorefrontAPIConfig {
+    /**
+     * The store ID to use for API requests
+     */
+    storeId: string;
+    /**
+     * The environment to use (staging or production)
+     */
+    environment?: Environment;
+    /**
+     * Custom base URL (overrides environment-based URL 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;
+}
+/**
+ * Error response from the API
+ */
+export type ApiErrorResponse = {
+    message?: string;
+    success: boolean;
+    code?: string;
+    error?: Record<string, any>;
+};
+/**
+ * Base API client for Storefront API
+ */
+export declare class StorefrontAPIClient {
+    protected client: ReturnType<typeof createClient<paths>>;
+    protected config: StorefrontAPIConfig;
+    private headers;
+    private readonly baseUrl;
+    private isRefreshing;
+    /**
+     * Create a new StorefrontAPIClient
+     *
+     * @param config - Configuration for the API client
+     *
+     * @remarks
+     * This client implements a token refresh mechanism that will:
+     * 1. Automatically retry requests that fail with a 401 error
+     * 2. Refresh the token before retrying the request
+     * 3. If the token refresh fails, the original error will be thrown
+     *
+     * This behavior is inherited by all client classes that extend StorefrontAPIClient.
+     *
+     * When using the AuthClient, tokens can be stored persistently in:
+     * - Memory (default) - Tokens are lost when the page refreshes or app restarts
+     * - Browser localStorage - Tokens persist across page refreshes
+     * - Cookies - Tokens persist across page refreshes and can be read server-side
+     * - Next.js cookies API - For server-side components
+     */
+    constructor(config: StorefrontAPIConfig);
+    /**
+     * Constructs the base URL from the configuration
+     *
+     * @param config - The client configuration
+     * @returns The constructed base URL
+     */
+    private getBaseUrlFromConfig;
+    /**
+     * Get the base URL of the API
+     *
+     * @returns The base URL of the API
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the authorization header value
+     *
+     * @returns The Authorization header value or empty string if no token is set
+     */
+    getAuthorizationHeader(): string;
+    /**
+     * Set the authentication token
+     *
+     * @param token - The authentication token
+     */
+    setToken(token: string): void;
+    /**
+     * Clear the authentication token
+     */
+    clearToken(): void;
+    /**
+     * Set the X-Api-Key header
+     *
+     * @param apiKey - The API key to set
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Clear the X-Api-Key header
+     */
+    clearApiKey(): void;
+    /**
+     * Handle API errors
+     *
+     * @param error - Error object from OpenAPI-Fetch
+     * @throws Rethrows the error with additional context
+     */
+    protected handleError(error: any): Promise<never>;
+    /**
+     * Attempt to refresh the token
+     * This is a placeholder method that will be overridden by AuthClient
+     *
+     * @returns Promise that resolves to true if token was refreshed, false otherwise
+     */
+    protected attemptTokenRefresh(): Promise<boolean>;
+    /**
+     * Execute a request with automatic token refresh handling
+     * For AuthClient, this will attempt to refresh the token and retry once on 401 errors
+     * Base implementation just executes the request
+     *
+     * @param requestFn - Function that executes the API request
+     * @returns Promise with the API response
+     */
+    protected executeRequest<T>(requestFn: () => Promise<T>): Promise<T>;
+}

package/dist/lib/client.js

@@ -0,0 +1,239 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorefrontAPIClient = exports.Environment = void 0;
+const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+/**
+ * Available API environments
+ */
+var Environment;
+(function (Environment) {
+    /**
+     * Staging environment
+     */
+    Environment["Staging"] = "staging";
+    /**
+     * Production environment
+     */
+    Environment["Production"] = "production";
+})(Environment || (exports.Environment = Environment = {}));
+/**
+ * Base API client for Storefront API
+ */
+class StorefrontAPIClient {
+    /**
+     * Create a new StorefrontAPIClient
+     *
+     * @param config - Configuration for the API client
+     *
+     * @remarks
+     * This client implements a token refresh mechanism that will:
+     * 1. Automatically retry requests that fail with a 401 error
+     * 2. Refresh the token before retrying the request
+     * 3. If the token refresh fails, the original error will be thrown
+     *
+     * This behavior is inherited by all client classes that extend StorefrontAPIClient.
+     *
+     * When using the AuthClient, tokens can be stored persistently in:
+     * - Memory (default) - Tokens are lost when the page refreshes or app restarts
+     * - Browser localStorage - Tokens persist across page refreshes
+     * - Cookies - Tokens persist across page refreshes and can be read server-side
+     * - Next.js cookies API - For server-side components
+     */
+    constructor(config) {
+        this.isRefreshing = false;
+        this.config = config;
+        this.headers = {
+            "Content-Type": "application/json",
+        };
+        if (config.token) {
+            this.headers["Authorization"] = `Bearer ${config.token}`;
+        }
+        if (config.apiKey) {
+            this.headers["X-Api-Key"] = config.apiKey;
+        }
+        // Determine base URL from environment or use custom URL if provided
+        this.baseUrl = this.getBaseUrlFromConfig(config);
+        this.client = (0, openapi_fetch_1.default)({
+            baseUrl: this.baseUrl,
+            fetch: (input, init) => {
+                // Add timeout if configured
+                const timeoutSignal = config.timeout
+                    ? AbortSignal.timeout(config.timeout)
+                    : undefined;
+                // Merge headers
+                const headers = {
+                    ...this.headers,
+                    ...(init?.headers || {}),
+                };
+                return fetch(input, {
+                    ...init,
+                    headers,
+                    signal: timeoutSignal || init?.signal,
+                });
+            },
+        });
+    }
+    /**
+     * Constructs the base URL from the configuration
+     *
+     * @param config - The client configuration
+     * @returns The constructed base URL
+     */
+    getBaseUrlFromConfig(config) {
+        // If explicit baseUrl is provided, use it
+        if (config.baseUrl) {
+            return config.baseUrl;
+        }
+        // Otherwise construct URL based on environment and storeId
+        const env = config.environment || Environment.Production;
+        switch (env) {
+            case Environment.Staging:
+                return `https://staging.api.commercengine.io/api/v1/${config.storeId}/storefront`;
+            case Environment.Production:
+            default:
+                return `https://prod.api.commercengine.io/api/v1/${config.storeId}/storefront`;
+        }
+    }
+    /**
+     * Get the base URL of the API
+     *
+     * @returns The base URL of the API
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Get the authorization header value
+     *
+     * @returns The Authorization header value or empty string if no token is set
+     */
+    getAuthorizationHeader() {
+        return this.config.token ? `Bearer ${this.config.token}` : "";
+    }
+    /**
+     * Set the authentication token
+     *
+     * @param token - The authentication token
+     */
+    setToken(token) {
+        this.config.token = token;
+        this.headers["Authorization"] = `Bearer ${token}`;
+    }
+    /**
+     * Clear the authentication token
+     */
+    clearToken() {
+        this.config.token = undefined;
+        delete this.headers["Authorization"];
+    }
+    /**
+     * Set the X-Api-Key header
+     *
+     * @param apiKey - The API key to set
+     */
+    setApiKey(apiKey) {
+        this.config.apiKey = apiKey;
+        this.headers["X-Api-Key"] = apiKey;
+    }
+    /**
+     * Clear the X-Api-Key header
+     */
+    clearApiKey() {
+        this.config.apiKey = undefined;
+        delete this.headers["X-Api-Key"];
+    }
+    /**
+     * Handle API errors
+     *
+     * @param error - Error object from OpenAPI-Fetch
+     * @throws Rethrows the error with additional context
+     */
+    async handleError(error) {
+        // Extract status code and error data from OpenAPI-Fetch error response
+        const statusCode = error.status || (error.response?.status ? error.response.status : 500);
+        const errorData = error.data ||
+            error.response?.data || { message: error.message || "Unknown error" };
+        // If we have a 401 error and we're not already in a refresh operation,
+        // attempt to refresh the token
+        if (statusCode === 401 && !this.isRefreshing) {
+            try {
+                this.isRefreshing = true;
+                const refreshed = await this.attemptTokenRefresh();
+                if (refreshed) {
+                    // Token refreshed successfully - no need to throw error
+                    // The calling method should retry the request
+                    this.isRefreshing = false;
+                    throw new Error("Token refreshed, please retry the request");
+                }
+            }
+            catch (refreshError) {
+                // If refresh fails, continue to throw the original error
+            }
+            finally {
+                this.isRefreshing = false;
+            }
+        }
+        if (statusCode === 401) {
+            throw new Error("Unauthorized: Please check your authentication token");
+        }
+        else if (statusCode === 404) {
+            throw new Error("Resource not found");
+        }
+        else if (errorData?.message) {
+            throw new Error(`API Error (${statusCode}): ${errorData.message}`);
+        }
+        else {
+            throw new Error(`API Error (${statusCode})`);
+        }
+    }
+    /**
+     * Attempt to refresh the token
+     * This is a placeholder method that will be overridden by AuthClient
+     *
+     * @returns Promise that resolves to true if token was refreshed, false otherwise
+     */
+    async attemptTokenRefresh() {
+        // Base implementation does nothing
+        // Will be overridden by AuthClient
+        return false;
+    }
+    /**
+     * Execute a request with automatic token refresh handling
+     * For AuthClient, this will attempt to refresh the token and retry once on 401 errors
+     * Base implementation just executes the request
+     *
+     * @param requestFn - Function that executes the API request
+     * @returns Promise with the API response
+     */
+    async executeRequest(requestFn) {
+        try {
+            return await requestFn();
+        }
+        catch (error) {
+            // Handle 401 errors by attempting to refresh token
+            if (error &&
+                typeof error === "object" &&
+                "status" in error &&
+                error.status === 401) {
+                // Attempt to refresh the token
+                const refreshed = await this.attemptTokenRefresh();
+                if (refreshed) {
+                    // If token was refreshed, retry the request once
+                    return await requestFn();
+                }
+            }
+            // Check if the error is from handleError and is the special refresh token message
+            if (error instanceof Error &&
+                error.message === "Token refreshed, please retry the request") {
+                // If token was refreshed, retry the request once
+                return await requestFn();
+            }
+            // Otherwise, throw the error to be handled by the caller
+            throw error;
+        }
+    }
+}
+exports.StorefrontAPIClient = StorefrontAPIClient;