@commercengine/storefront-sdk 0.3.0 → 0.3.2

package/dist/lib/helper.js

@@ -0,0 +1,40 @@
+import { StorefrontAPIClient } from "./client";
+/**
+ * Client for interacting with helper endpoints
+ */
+export class HelpersClient extends StorefrontAPIClient {
+    /**
+     * Get a list of countries
+     *
+     * @returns Promise with countries
+     */
+    async listCountries() {
+        return this.executeRequest(() => this.client.GET("/common/countries", {}));
+    }
+    /**
+     * - Get a list of states for a country
+     *
+     * @param pathParams - Path parameters
+     * @returns Promise with states
+     */
+    async listCountryStates(pathParams) {
+        return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/states", {
+            params: {
+                path: pathParams,
+            },
+        }));
+    }
+    /**
+     * Get pincodes for a country
+     *
+     * @param pathParams - Path parameters
+     * @returns Promise with pincodes
+     */
+    async listCountryPincodes(pathParams) {
+        return this.executeRequest(() => this.client.GET("/common/countries/{country_iso_code}/pincodes", {
+            params: {
+                path: pathParams,
+            },
+        }));
+    }
+}

package/dist/lib/jwt-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * JWT payload structure for storefront tokens
+ */
+export interface JwtPayload {
+    token_type: string;
+    exp: number;
+    iat: number;
+    jti: string;
+    ulid: string;
+    email: string | null;
+    phone: string | null;
+    username: string;
+    first_name: string | null;
+    last_name: string | null;
+    store_id: string;
+    is_logged_in: boolean;
+    customer_id: string | null;
+    customer_group_id: string | null;
+    anonymous_id: string;
+}
+/**
+ * User information extracted from JWT token
+ */
+export interface UserInfo {
+    id: string;
+    email: string | null;
+    phone: string | null;
+    username: string;
+    firstName: string | null;
+    lastName: string | null;
+    storeId: string;
+    isLoggedIn: boolean;
+    isAnonymous: boolean;
+    customerId: string | null;
+    customerGroupId: string | null;
+    anonymousId: string;
+    tokenExpiry: Date;
+    tokenIssuedAt: Date;
+}
+/**
+ * Decode and extract user information from a JWT token
+ *
+ * @param token - The JWT token to decode
+ * @returns User information or null if token is invalid
+ */
+export declare function extractUserInfoFromToken(token: string): UserInfo | null;
+/**
+ * Check if a JWT token is expired
+ *
+ * @param token - The JWT token to check
+ * @param bufferSeconds - Buffer time in seconds (default: 30)
+ * @returns True if token is expired or will expire within buffer time
+ */
+export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+/**
+ * Get the user ID from a JWT token
+ *
+ * @param token - The JWT token
+ * @returns User ID (ulid) or null if token is invalid
+ */
+export declare function getUserIdFromToken(token: string): string | null;
+/**
+ * Check if user is logged in based on JWT token
+ *
+ * @param token - The JWT token
+ * @returns True if user is logged in, false otherwise
+ */
+export declare function isUserLoggedIn(token: string): boolean;
+/**
+ * Check if user is anonymous based on JWT token
+ *
+ * @param token - The JWT token
+ * @returns True if user is anonymous, false otherwise
+ */
+export declare function isUserAnonymous(token: string): boolean;

package/dist/lib/jwt-utils.js

@@ -0,0 +1,84 @@
+import { decodeJwt } from "jose";
+/**
+ * Decode and extract user information from a JWT token
+ *
+ * @param token - The JWT token to decode
+ * @returns User information or null if token is invalid
+ */
+export function extractUserInfoFromToken(token) {
+    try {
+        const payload = decodeJwt(token);
+        return {
+            id: payload.ulid,
+            email: payload.email,
+            phone: payload.phone,
+            username: payload.username,
+            firstName: payload.first_name,
+            lastName: payload.last_name,
+            storeId: payload.store_id,
+            isLoggedIn: payload.is_logged_in,
+            isAnonymous: !payload.is_logged_in,
+            customerId: payload.customer_id,
+            customerGroupId: payload.customer_group_id,
+            anonymousId: payload.anonymous_id,
+            tokenExpiry: new Date(payload.exp * 1000),
+            tokenIssuedAt: new Date(payload.iat * 1000),
+        };
+    }
+    catch (error) {
+        console.warn("Failed to decode JWT token:", error);
+        return null;
+    }
+}
+/**
+ * Check if a JWT token is expired
+ *
+ * @param token - The JWT token to check
+ * @param bufferSeconds - Buffer time in seconds (default: 30)
+ * @returns True if token is expired or will expire within buffer time
+ */
+export function isTokenExpired(token, bufferSeconds = 30) {
+    try {
+        const payload = decodeJwt(token);
+        if (!payload.exp)
+            return true;
+        const currentTime = Math.floor(Date.now() / 1000);
+        const expiryTime = payload.exp;
+        // Consider token expired if it expires within the buffer time
+        return currentTime >= (expiryTime - bufferSeconds);
+    }
+    catch (error) {
+        console.warn("Failed to decode JWT token:", error);
+        return true; // Treat invalid tokens as expired
+    }
+}
+/**
+ * Get the user ID from a JWT token
+ *
+ * @param token - The JWT token
+ * @returns User ID (ulid) or null if token is invalid
+ */
+export function getUserIdFromToken(token) {
+    const userInfo = extractUserInfoFromToken(token);
+    return userInfo?.id || null;
+}
+/**
+ * Check if user is logged in based on JWT token
+ *
+ * @param token - The JWT token
+ * @returns True if user is logged in, false otherwise
+ */
+export function isUserLoggedIn(token) {
+    const userInfo = extractUserInfoFromToken(token);
+    return userInfo?.isLoggedIn || false;
+}
+/**
+ * Check if user is anonymous based on JWT token
+ *
+ * @param token - The JWT token
+ * @returns True if user is anonymous, false otherwise
+ */
+export function isUserAnonymous(token) {
+    const userInfo = extractUserInfoFromToken(token);
+    return userInfo?.isAnonymous || true;
+}

package/dist/lib/middleware.d.ts

@@ -0,0 +1,83 @@
+import type { Middleware } from "openapi-fetch";
+/**
+ * Token storage interface for the auth middleware
+ */
+export interface TokenStorage {
+    getAccessToken(): Promise<string | null>;
+    setAccessToken(token: string): Promise<void>;
+    getRefreshToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * Simple in-memory token storage implementation
+ */
+export declare class MemoryTokenStorage implements TokenStorage {
+    private accessToken;
+    private refreshToken;
+    getAccessToken(): Promise<string | null>;
+    setAccessToken(token: string): Promise<void>;
+    getRefreshToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * Browser localStorage token storage implementation
+ */
+export declare class BrowserTokenStorage implements TokenStorage {
+    private accessTokenKey;
+    private refreshTokenKey;
+    constructor(prefix?: string);
+    getAccessToken(): Promise<string | null>;
+    setAccessToken(token: string): Promise<void>;
+    getRefreshToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * Configuration for the auth middleware
+ */
+export interface AuthMiddlewareConfig {
+    /**
+     * Token storage implementation
+     */
+    tokenStorage: TokenStorage;
+    /**
+     * API key for anonymous endpoints
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the API (used for refresh token endpoint)
+     */
+    baseUrl: string;
+    /**
+     * Function to refresh tokens
+     * Should make a call to /auth/refresh-token endpoint
+     */
+    refreshTokenFn?: (refreshToken: string) => Promise<{
+        access_token: string;
+        refresh_token: string;
+    }>;
+    /**
+     * Callback when tokens are updated (login/refresh)
+     */
+    onTokensUpdated?: (accessToken: string, refreshToken: string) => void;
+    /**
+     * Callback when tokens are cleared (logout/error)
+     */
+    onTokensCleared?: () => void;
+}
+/**
+ * Create authentication middleware for openapi-fetch
+ */
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): Middleware;
+/**
+ * Helper function to create auth middleware with sensible defaults
+ */
+export declare function createDefaultAuthMiddleware(options: {
+    apiKey?: string;
+    baseUrl: string;
+    tokenStorage?: TokenStorage;
+    onTokensUpdated?: (accessToken: string, refreshToken: string) => void;
+    onTokensCleared?: () => void;
+}): Middleware;

package/dist/lib/middleware.js

@@ -0,0 +1,248 @@
+import { isTokenExpired } from "./jwt-utils";
+import { getPathnameFromUrl, isAnonymousAuthEndpoint, isTokenReturningEndpoint, isLogoutEndpoint } from "./auth-utils";
+/**
+ * Simple in-memory token storage implementation
+ */
+export class MemoryTokenStorage {
+    accessToken = null;
+    refreshToken = null;
+    async getAccessToken() {
+        return this.accessToken;
+    }
+    async setAccessToken(token) {
+        this.accessToken = token;
+    }
+    async getRefreshToken() {
+        return this.refreshToken;
+    }
+    async setRefreshToken(token) {
+        this.refreshToken = token;
+    }
+    async clearTokens() {
+        this.accessToken = null;
+        this.refreshToken = null;
+    }
+}
+/**
+ * Browser localStorage token storage implementation
+ */
+export class BrowserTokenStorage {
+    accessTokenKey;
+    refreshTokenKey;
+    constructor(prefix = "storefront_") {
+        this.accessTokenKey = `${prefix}access_token`;
+        this.refreshTokenKey = `${prefix}refresh_token`;
+    }
+    async getAccessToken() {
+        if (typeof localStorage === "undefined")
+            return null;
+        return localStorage.getItem(this.accessTokenKey);
+    }
+    async setAccessToken(token) {
+        if (typeof localStorage !== "undefined") {
+            localStorage.setItem(this.accessTokenKey, token);
+        }
+    }
+    async getRefreshToken() {
+        if (typeof localStorage === "undefined")
+            return null;
+        return localStorage.getItem(this.refreshTokenKey);
+    }
+    async setRefreshToken(token) {
+        if (typeof localStorage !== "undefined") {
+            localStorage.setItem(this.refreshTokenKey, token);
+        }
+    }
+    async clearTokens() {
+        if (typeof localStorage !== "undefined") {
+            localStorage.removeItem(this.accessTokenKey);
+            localStorage.removeItem(this.refreshTokenKey);
+        }
+    }
+}
+/**
+ * Create authentication middleware for openapi-fetch
+ */
+export function createAuthMiddleware(config) {
+    let isRefreshing = false;
+    let refreshPromise = null;
+    const refreshTokens = async () => {
+        if (isRefreshing && refreshPromise) {
+            return refreshPromise;
+        }
+        isRefreshing = true;
+        refreshPromise = (async () => {
+            try {
+                const refreshToken = await config.tokenStorage.getRefreshToken();
+                let newTokens;
+                if (refreshToken && !isTokenExpired(refreshToken)) {
+                    // Try normal refresh token flow first (only if refresh token is not expired)
+                    if (config.refreshTokenFn) {
+                        // Use provided refresh function
+                        newTokens = await config.refreshTokenFn(refreshToken);
+                    }
+                    else {
+                        // Default refresh implementation
+                        const response = await fetch(`${config.baseUrl}/auth/refresh-token`, {
+                            method: "POST",
+                            headers: {
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify({ refresh_token: refreshToken }),
+                        });
+                        if (!response.ok) {
+                            throw new Error(`Token refresh failed: ${response.status}`);
+                        }
+                        const data = await response.json();
+                        newTokens = data.content;
+                    }
+                }
+                else {
+                    // No refresh token available OR refresh token is expired - try anonymous token fallback
+                    // This handles cases where:
+                    // 1. SDK was initialized with just an access token
+                    // 2. Refresh token has expired
+                    const currentAccessToken = await config.tokenStorage.getAccessToken();
+                    if (!currentAccessToken) {
+                        throw new Error("No tokens available for refresh");
+                    }
+                    const reason = refreshToken
+                        ? "refresh token expired"
+                        : "no refresh token available";
+                    // Get new anonymous tokens while preserving user_id
+                    const response = await fetch(`${config.baseUrl}/auth/anonymous`, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            ...(config.apiKey && { "X-Api-Key": config.apiKey }),
+                            "Authorization": `Bearer ${currentAccessToken}`, // For user_id continuity
+                        },
+                    });
+                    if (!response.ok) {
+                        throw new Error(`Anonymous token fallback failed: ${response.status}`);
+                    }
+                    const data = await response.json();
+                    newTokens = data.content;
+                    console.info(`Token refreshed via anonymous fallback (${reason}) - user may need to re-authenticate for privileged operations`);
+                }
+                // Store new tokens
+                await config.tokenStorage.setAccessToken(newTokens.access_token);
+                await config.tokenStorage.setRefreshToken(newTokens.refresh_token);
+                // Notify callback
+                config.onTokensUpdated?.(newTokens.access_token, newTokens.refresh_token);
+            }
+            catch (error) {
+                console.error("Token refresh failed:", error);
+                // Clear tokens on refresh failure
+                await config.tokenStorage.clearTokens();
+                config.onTokensCleared?.();
+                throw error;
+            }
+            finally {
+                isRefreshing = false;
+                refreshPromise = null;
+            }
+        })();
+        return refreshPromise;
+    };
+    return {
+        async onRequest({ request }) {
+            const pathname = getPathnameFromUrl(request.url);
+            // Handle anonymous auth endpoint - use API key
+            if (isAnonymousAuthEndpoint(pathname)) {
+                if (config.apiKey) {
+                    request.headers.set("X-Api-Key", config.apiKey);
+                }
+                // Also send existing access token if available (even if expired)
+                // This helps the server maintain anonymous user continuity
+                const existingToken = await config.tokenStorage.getAccessToken();
+                if (existingToken) {
+                    request.headers.set("Authorization", `Bearer ${existingToken}`);
+                }
+                return request;
+            }
+            // For all other endpoints, use access token
+            let accessToken = await config.tokenStorage.getAccessToken();
+            // Check if token needs refresh
+            if (accessToken && isTokenExpired(accessToken)) {
+                try {
+                    await refreshTokens();
+                    accessToken = await config.tokenStorage.getAccessToken();
+                }
+                catch (error) {
+                    // If refresh fails, continue with expired token
+                    // The server will return 401 and we'll handle it in onResponse
+                }
+            }
+            // Add Authorization header if we have a token
+            if (accessToken) {
+                request.headers.set("Authorization", `Bearer ${accessToken}`);
+            }
+            return request;
+        },
+        async onResponse({ request, response }) {
+            const pathname = getPathnameFromUrl(request.url);
+            // Handle successful responses that return tokens
+            if (response.ok) {
+                if (isTokenReturningEndpoint(pathname) || isAnonymousAuthEndpoint(pathname)) {
+                    try {
+                        const data = await response.clone().json();
+                        const content = data.content;
+                        if (content?.access_token && content?.refresh_token) {
+                            await config.tokenStorage.setAccessToken(content.access_token);
+                            await config.tokenStorage.setRefreshToken(content.refresh_token);
+                            config.onTokensUpdated?.(content.access_token, content.refresh_token);
+                        }
+                    }
+                    catch (error) {
+                        console.warn("Failed to extract tokens from response:", error);
+                    }
+                }
+                else if (isLogoutEndpoint(pathname)) {
+                    // Clear tokens on successful logout
+                    await config.tokenStorage.clearTokens();
+                    config.onTokensCleared?.();
+                }
+            }
+            // Handle 401 responses - only retry if token was expired
+            if (response.status === 401 && !isAnonymousAuthEndpoint(pathname)) {
+                const currentToken = await config.tokenStorage.getAccessToken();
+                // Only attempt refresh if we have a token and it's expired
+                // This prevents infinite retries for privilege-related 401s
+                if (currentToken && isTokenExpired(currentToken, 0)) {
+                    try {
+                        await refreshTokens();
+                        // Retry the original request with new token
+                        const newToken = await config.tokenStorage.getAccessToken();
+                        if (newToken) {
+                            const retryRequest = request.clone();
+                            retryRequest.headers.set("Authorization", `Bearer ${newToken}`);
+                            return fetch(retryRequest);
+                        }
+                    }
+                    catch (error) {
+                        // If refresh fails, let the original 401 response through
+                        console.warn("Token refresh failed on 401 response:", error);
+                    }
+                }
+            }
+            return response;
+        },
+    };
+}
+/**
+ * Helper function to create auth middleware with sensible defaults
+ */
+export function createDefaultAuthMiddleware(options) {
+    const tokenStorage = options.tokenStorage ||
+        (typeof localStorage !== "undefined"
+            ? new BrowserTokenStorage()
+            : new MemoryTokenStorage());
+    return createAuthMiddleware({
+        tokenStorage,
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        onTokensUpdated: options.onTokensUpdated,
+        onTokensCleared: options.onTokensCleared,
+    });
+}

package/dist/lib/order.d.ts

@@ -0,0 +1,72 @@
+import type { ApiResult, CancelOrderBody, CancelOrderContent, CancelOrderPathParams, CreateOrderBody, CreateOrderContent, GetOrderDetailContent, GetOrderDetailPathParams, GetPaymentStatusContent, ListOrderPaymentsContent, ListOrderPaymentsPathParams, ListOrderRefundsContent, ListOrderRefundsPathParams, ListOrdersContent, ListOrderShipmentsContent, ListOrderShipmentsPathParams, ListOrdersQuery, RetryOrderPaymentBody, RetryOrderPaymentContent, RetryOrderPaymentPathParams } from "../types/storefront-api-types";
+import { StorefrontAPIClient } from "./client";
+/**
+ * Client for interacting with order endpoints
+ */
+export declare class OrderClient extends StorefrontAPIClient {
+    /**
+     * Get order details
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with order details
+     */
+    getOrderDetails(pathParams: GetOrderDetailPathParams): Promise<ApiResult<GetOrderDetailContent>>;
+    /**
+     * Create order
+     *
+     * @param cartId - Cart ID
+     * @param paymentGateway - Payment gateway
+     * @param paymentGatewayParams - Params for the selected payment gateway
+     * @returns Promise with order details
+     */
+    createOrder(body: CreateOrderBody): Promise<ApiResult<CreateOrderContent>>;
+    /**
+     * List all orders
+     *
+     * @param queryParams - Query parameters
+     * @returns Promise with order details
+     */
+    listOrders(queryParams: ListOrdersQuery): Promise<ApiResult<ListOrdersContent>>;
+    /**
+     * Get payment status for an order
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with payment status
+     */
+    getPaymentStatus(orderNumber: string): Promise<ApiResult<GetPaymentStatusContent>>;
+    /**
+     * Get all shipments for an order
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with shipments
+     */
+    listOrderShipments(pathParams: ListOrderShipmentsPathParams): Promise<ApiResult<ListOrderShipmentsContent>>;
+    /**
+     * List order payments
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with payments
+     */
+    listOrderPayments(pathParams: ListOrderPaymentsPathParams): Promise<ApiResult<ListOrderPaymentsContent>>;
+    /**
+     * List order refunds
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with refunds
+     */
+    listOrderRefunds(pathParams: ListOrderRefundsPathParams): Promise<ApiResult<ListOrderRefundsContent>>;
+    /**
+     * Cancel an order
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with order details
+     */
+    cancelOrder(pathParams: CancelOrderPathParams, body: CancelOrderBody): Promise<ApiResult<CancelOrderContent>>;
+    /**
+     * Retry payment for an order
+     *
+     * @param orderNumber - Order number
+     * @returns Promise with order details
+     */
+    retryOrderPayment(pathParams: RetryOrderPaymentPathParams, body: RetryOrderPaymentBody): Promise<ApiResult<RetryOrderPaymentContent>>;
+}