@commercengine/storefront-sdk 0.3.9 → 0.3.10

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { HelpersClient } from "./lib/helper";
 import { CustomerClient } from "./lib/customer";
 import { TokenStorage, MemoryTokenStorage, BrowserTokenStorage, CookieTokenStorage } from "./lib/middleware";
 import { type UserInfo } from "./lib/jwt-utils";
+import { ResponseUtils, type DebugLoggerFn } from "./lib/logger-utils";
 /**
  * Supported default headers that can be set at the SDK level
  * Only includes headers that are actually supported by API endpoints
@@ -75,6 +76,17 @@ export interface StorefrontSDKOptions {
      * Only supports headers that are actually available in the API
      */
     defaultHeaders?: SupportedDefaultHeaders;
+    /**
+     * Enable debug mode for detailed request/response logging
+     * When enabled, detailed debug information will be logged via the logger
+     * Note: Response objects are always included in ApiResult regardless of debug mode
+     */
+    debug?: boolean;
+    /**
+     * Custom logger function for debug information
+     * If not provided and debug is enabled, will use console.log
+     */
+    logger?: DebugLoggerFn;
 }
 /**
  * Main SDK class for the Storefront API
@@ -197,10 +209,11 @@ export declare class StorefrontSDK {
     getDefaultHeaders(): SupportedDefaultHeaders | undefined;
 }
 export default StorefrontSDK;
-export { StorefrontAPIClient, AuthClient, CartClient, CatalogClient, CustomerClient, HelpersClient, ShippingClient, OrderClient, };
+export { StorefrontAPIClient, AuthClient, CartClient, CatalogClient, CustomerClient, HelpersClient, ShippingClient, OrderClient, ResponseUtils, };
 export { Environment };
 export { TokenStorage, MemoryTokenStorage, BrowserTokenStorage, CookieTokenStorage, };
 export type { CookieTokenStorageOptions } from "./lib/middleware";
 export type { UserInfo } from "./lib/jwt-utils";
+export type { DebugLoggerFn } from "./lib/logger-utils";
 export type { components, operations, paths } from "./types/storefront";
 export type * from "./types/storefront-api-types";

package/dist/index.js

@@ -8,6 +8,7 @@ import { HelpersClient } from "./lib/helper";
 import { CustomerClient } from "./lib/customer";
 import { MemoryTokenStorage, BrowserTokenStorage, CookieTokenStorage, } from "./lib/middleware";
 import { extractUserInfoFromToken, getUserIdFromToken, isUserLoggedIn, isUserAnonymous, } from "./lib/jwt-utils";
+import { ResponseUtils, } from "./lib/logger-utils";
 /**
  * Main SDK class for the Storefront API
  */
@@ -59,6 +60,8 @@ export class StorefrontSDK {
             onTokensUpdated: options.onTokensUpdated,
             onTokensCleared: options.onTokensCleared,
             defaultHeaders: options.defaultHeaders,
+            debug: options.debug,
+            logger: options.logger,
         };
         this.catalog = new CatalogClient(config);
         this.cart = new CartClient(config);
@@ -227,7 +230,7 @@ export class StorefrontSDK {
 // Export the main SDK class
 export default StorefrontSDK;
 // Export individual clients for advanced usage
-export { StorefrontAPIClient, AuthClient, CartClient, CatalogClient, CustomerClient, HelpersClient, ShippingClient, OrderClient, };
+export { StorefrontAPIClient, AuthClient, CartClient, CatalogClient, CustomerClient, HelpersClient, ShippingClient, OrderClient, ResponseUtils, };
 // Export environment enum
 export { Environment };
 // Export token storage types

package/dist/lib/client.js

@@ -1,6 +1,7 @@
 import createClient from "openapi-fetch";
 import { createDefaultAuthMiddleware } from "./middleware";
 import { getPathnameFromUrl, isAnonymousAuthEndpoint } from "./auth-utils";
+import { createDebugMiddleware } from "./logger-utils";
 /**
  * Available API environments
  */
@@ -81,6 +82,11 @@ export class StorefrontAPIClient {
         if (this.config.timeout) {
             this.setupTimeoutMiddleware();
         }
+        // Set up debug middleware if enabled
+        if (this.config.debug) {
+            const debugMiddleware = createDebugMiddleware(this.config.logger);
+            this.client.use(debugMiddleware);
+        }
     }
     /**
      * Set up timeout middleware
@@ -215,21 +221,39 @@ export class StorefrontAPIClient {
      */
     async executeRequest(apiCall) {
         try {
-            const { data, error } = await apiCall();
+            const { data, error, response } = await apiCall();
+            // Debug logging is now handled by middleware
             // openapi-fetch returns error for 4xx/5xx, data for 2xx
             if (error) {
-                return { data: null, error };
+                return {
+                    data: null,
+                    error,
+                    response,
+                };
             }
             // If response has content, return it directly
             if (data && data.content !== undefined) {
-                return { data: data.content, error: null };
+                return {
+                    data: data.content,
+                    error: null,
+                    response,
+                };
             }
             // If no content, return the response object (with message, success, etc.)
-            return { data: data, error: null };
+            return {
+                data: data,
+                error: null,
+                response,
+            };
         }
         catch (err) {
             // This handles network errors or other unexpected errors
-            return {
+            // Network errors don't have Response objects, so we create a mock response
+            const mockResponse = new Response(null, {
+                status: 0,
+                statusText: "Network Error",
+            });
+            const errorResult = {
                 data: null,
                 error: {
                     success: false,
@@ -237,7 +261,10 @@ export class StorefrontAPIClient {
                     message: "Network error occurred",
                     error: err,
                 },
+                response: mockResponse,
             };
+            // Network errors are logged by middleware if debug is enabled
+            return errorResult;
         }
     }
     /**

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

@@ -0,0 +1,88 @@
+import type { Middleware } from "openapi-fetch";
+/**
+ * Debug logger function interface
+ */
+export interface DebugLoggerFn {
+    (level: "info" | "warn" | "error", message: string, data?: any): void;
+}
+/**
+ * Response utilities for debugging and working with Response objects
+ */
+export declare class ResponseUtils {
+    /**
+     * Get response headers as a plain object
+     */
+    static getHeaders(response: Response): Record<string, string>;
+    /**
+     * Get specific header value
+     */
+    static getHeader(response: Response, name: string): string | null;
+    /**
+     * Check if response was successful
+     */
+    static isSuccess(response: Response): boolean;
+    /**
+     * Get response metadata
+     */
+    static getMetadata(response: Response): {
+        status: number;
+        statusText: string;
+        ok: boolean;
+        url: string;
+        redirected: boolean;
+        type: ResponseType;
+        headers: {
+            [k: string]: string;
+        };
+    };
+    /**
+     * Clone and read response as text (useful for debugging)
+     * Note: This can only be called once per response
+     */
+    static getText(response: Response): Promise<string>;
+    /**
+     * Clone and read response as JSON (useful for debugging)
+     * Note: This can only be called once per response
+     */
+    static getJSON(response: Response): Promise<any>;
+    /**
+     * Format response information for debugging
+     */
+    static format(response: Response): string;
+}
+/**
+ * Debug logging utilities
+ */
+export declare class DebugLogger {
+    private logger;
+    private responseTextCache;
+    constructor(logger?: DebugLoggerFn);
+    /**
+     * Log debug information about API request
+     */
+    logRequest(request: Request, requestBody?: any): void;
+    /**
+     * Log debug information about API response
+     */
+    logResponse(response: Response, responseBody?: any): Promise<void>;
+    /**
+     * Log error information
+     */
+    logError(message: string, error: any): void;
+    /**
+     * Get cached response text for a URL (if available)
+     */
+    getCachedResponseText(url: string): string | null;
+    /**
+     * Clear cached response texts
+     */
+    clearCache(): void;
+}
+/**
+ * Extract request body for logging
+ */
+export declare function extractRequestBody(request: Request): Promise<any>;
+/**
+ * Create debug middleware for openapi-fetch (internal use)
+ */
+export declare function createDebugMiddleware(logger?: DebugLoggerFn): Middleware;

package/dist/lib/logger-utils.js

@@ -0,0 +1,211 @@
+/**
+ * Response utilities for debugging and working with Response objects
+ */
+export class ResponseUtils {
+    /**
+     * Get response headers as a plain object
+     */
+    static getHeaders(response) {
+        return Object.fromEntries(response.headers.entries());
+    }
+    /**
+     * Get specific header value
+     */
+    static getHeader(response, name) {
+        return response.headers.get(name);
+    }
+    /**
+     * Check if response was successful
+     */
+    static isSuccess(response) {
+        return response.ok;
+    }
+    /**
+     * Get response metadata
+     */
+    static getMetadata(response) {
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            ok: response.ok,
+            url: response.url,
+            redirected: response.redirected,
+            type: response.type,
+            headers: Object.fromEntries(response.headers.entries()),
+        };
+    }
+    /**
+     * Clone and read response as text (useful for debugging)
+     * Note: This can only be called once per response
+     */
+    static async getText(response) {
+        const cloned = response.clone();
+        return await cloned.text();
+    }
+    /**
+     * Clone and read response as JSON (useful for debugging)
+     * Note: This can only be called once per response
+     */
+    static async getJSON(response) {
+        const cloned = response.clone();
+        return await cloned.json();
+    }
+    /**
+     * Format response information for debugging
+     */
+    static format(response) {
+        const metadata = this.getMetadata(response);
+        return `${metadata.status} ${metadata.statusText} - ${metadata.url}`;
+    }
+}
+/**
+ * Debug logging utilities
+ */
+export class DebugLogger {
+    logger;
+    responseTextCache = new Map();
+    constructor(logger) {
+        this.logger =
+            logger ||
+                ((level, message, data) => {
+                    console.log(`[${level.toUpperCase()}]`, message);
+                    if (data)
+                        console.log(data);
+                });
+    }
+    /**
+     * Log debug information about API request
+     */
+    logRequest(request, requestBody) {
+        this.logger("info", "API Request Debug Info", {
+            method: request.method,
+            url: request.url,
+            headers: Object.fromEntries(request.headers.entries()),
+            body: requestBody,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Log debug information about API response
+     */
+    async logResponse(response, responseBody) {
+        // Cache response text for later use by ResponseUtils
+        if (responseBody && typeof responseBody === "string") {
+            this.responseTextCache.set(response.url, responseBody);
+        }
+        // Log response metadata
+        this.logger("info", "API Response Debug Info", {
+            url: response.url,
+            status: response.status,
+            statusText: response.statusText,
+            ok: response.ok,
+            headers: Object.fromEntries(response.headers.entries()),
+            redirected: response.redirected,
+            type: response.type,
+            timestamp: new Date().toISOString(),
+        });
+        // Log response body if available
+        if (responseBody) {
+            this.logger("info", "API Response Data", {
+                data: responseBody,
+                contentType: response.headers.get("content-type"),
+                contentLength: response.headers.get("content-length"),
+            });
+        }
+    }
+    /**
+     * Log error information
+     */
+    logError(message, error) {
+        this.logger("error", message, error);
+    }
+    /**
+     * Get cached response text for a URL (if available)
+     */
+    getCachedResponseText(url) {
+        return this.responseTextCache.get(url) || null;
+    }
+    /**
+     * Clear cached response texts
+     */
+    clearCache() {
+        this.responseTextCache.clear();
+    }
+}
+/**
+ * Extract request body for logging
+ */
+export async function extractRequestBody(request) {
+    if (request.method === "GET" || request.method === "HEAD") {
+        return null;
+    }
+    try {
+        const clonedRequest = request.clone();
+        const contentType = request.headers.get("content-type")?.toLowerCase();
+        if (contentType?.startsWith("application/json")) {
+            return await clonedRequest.json();
+        }
+        else if (contentType?.startsWith("multipart/form-data")) {
+            return "[FormData - cannot display]";
+        }
+        else if (contentType?.startsWith("text/")) {
+            return await clonedRequest.text();
+        }
+        return "[Request body - unknown format]";
+    }
+    catch (error) {
+        return "[Request body unavailable]";
+    }
+}
+/**
+ * Create debug middleware for openapi-fetch (internal use)
+ */
+export function createDebugMiddleware(logger) {
+    const debugLogger = new DebugLogger(logger);
+    return {
+        async onRequest({ request }) {
+            // Log request information
+            const requestBody = await extractRequestBody(request);
+            debugLogger.logRequest(request, requestBody);
+            return request;
+        },
+        async onResponse({ response }) {
+            // Clone response to read body without consuming it
+            const cloned = response.clone();
+            let responseBody = null;
+            try {
+                const contentType = response.headers.get("content-type")?.toLowerCase();
+                if (contentType?.startsWith("application/json")) {
+                    responseBody = await cloned.json();
+                }
+                else if (contentType?.startsWith("text/")) {
+                    responseBody = await cloned.text();
+                }
+            }
+            catch (error) {
+                // Ignore body reading errors
+            }
+            // Log response information
+            await debugLogger.logResponse(response, responseBody);
+            return response;
+        },
+        async onError({ error, request }) {
+            // Log error information with request context
+            debugLogger.logError("API Request Failed", {
+                error: {
+                    name: error instanceof Error ? error.name : "Unknown",
+                    message: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack : undefined,
+                },
+                request: {
+                    method: request.method,
+                    url: request.url,
+                    headers: Object.fromEntries(request.headers.entries()),
+                },
+                timestamp: new Date().toISOString(),
+            });
+            // Re-throw the error to maintain normal error handling
+            throw error;
+        },
+    };
+}

package/dist/types/storefront-api-types.d.ts

@@ -2,9 +2,11 @@ import type { paths } from './storefront';
 export type ApiResult<T> = {
     data: T;
     error: null;
+    response: Response;
 } | {
     data: null;
     error: ApiErrorResponse;
+    response: Response;
 };
 export type ApiErrorResponse = {
     success?: boolean;

package/package.json

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