@commercengine/storefront-sdk 0.6.1 → 0.8.0

package/dist/index.cjs

@@ -39,7 +39,6 @@ __export(index_exports, {
   Environment: () => Environment,
   HelpersClient: () => HelpersClient,
   MemoryTokenStorage: () => MemoryTokenStorage,
-  NextJSTokenStorage: () => NextJSTokenStorage,
   OrderClient: () => OrderClient,
   ResponseUtils: () => ResponseUtils,
   ShippingClient: () => ShippingClient,
@@ -261,118 +260,24 @@ var CookieTokenStorage = class {
     document.cookie = cookieString;
   }
 };
-var NextJSTokenStorage = class {
-  accessTokenKey;
-  refreshTokenKey;
-  options;
-  constructor(options = {}) {
-    const prefix = options.prefix || "storefront_";
-    this.accessTokenKey = `${prefix}access_token`;
-    this.refreshTokenKey = `${prefix}refresh_token`;
-    this.options = {
-      maxAge: options.maxAge || 30 * 24 * 60 * 60,
-      // 30 days default
-      path: options.path || "/",
-      domain: options.domain,
-      secure: options.secure ?? (typeof window !== "undefined" && window.location?.protocol === "https:"),
-      sameSite: options.sameSite || "Lax"
-    };
-  }
-  async getAccessToken() {
-    return await this.getCookie(this.accessTokenKey);
-  }
-  async setAccessToken(token) {
-    await this.setCookie(this.accessTokenKey, token);
-  }
-  async getRefreshToken() {
-    return await this.getCookie(this.refreshTokenKey);
-  }
-  async setRefreshToken(token) {
-    await this.setCookie(this.refreshTokenKey, token);
-  }
-  async clearTokens() {
-    await this.deleteCookie(this.accessTokenKey);
-    await this.deleteCookie(this.refreshTokenKey);
-  }
-  async getCookie(name) {
-    if (typeof window !== "undefined") {
-      const value = `; ${document.cookie}`;
-      const parts = value.split(`; ${name}=`);
-      if (parts.length === 2) {
-        const cookieValue = parts.pop()?.split(";").shift();
-        return cookieValue ? decodeURIComponent(cookieValue) : null;
-      }
-      return null;
-    } else {
-      try {
-        const { cookies } = require("next/headers");
-        const cookieStore = await cookies();
-        return cookieStore.get(name)?.value || null;
-      } catch {
-        return null;
-      }
-    }
-  }
-  async setCookie(name, value) {
-    if (typeof window !== "undefined") {
-      const encodedValue = encodeURIComponent(value);
-      let cookieString = `${name}=${encodedValue}`;
-      if (this.options.maxAge) {
-        cookieString += `; Max-Age=${this.options.maxAge}`;
-      }
-      if (this.options.path) {
-        cookieString += `; Path=${this.options.path}`;
-      }
-      if (this.options.domain) {
-        cookieString += `; Domain=${this.options.domain}`;
-      }
-      if (this.options.secure) {
-        cookieString += `; Secure`;
-      }
-      if (this.options.sameSite) {
-        cookieString += `; SameSite=${this.options.sameSite}`;
-      }
-      document.cookie = cookieString;
-    } else {
-      try {
-        const { cookies } = require("next/headers");
-        const cookieStore = await cookies();
-        cookieStore.set(name, value, {
-          maxAge: this.options.maxAge,
-          path: this.options.path,
-          domain: this.options.domain,
-          secure: this.options.secure,
-          sameSite: this.options.sameSite?.toLowerCase()
-        });
-      } catch {
-        console.warn(`Could not set cookie ${name} on server side`);
-      }
-    }
-  }
-  async deleteCookie(name) {
-    if (typeof window !== "undefined") {
-      let cookieString = `${name}=; Max-Age=0`;
-      if (this.options.path) {
-        cookieString += `; Path=${this.options.path}`;
-      }
-      if (this.options.domain) {
-        cookieString += `; Domain=${this.options.domain}`;
-      }
-      document.cookie = cookieString;
-    } else {
-      try {
-        const { cookies } = require("next/headers");
-        const cookieStore = await cookies();
-        cookieStore.delete(name);
-      } catch {
-        console.warn(`Could not remove cookie ${name} on server side`);
-      }
-    }
-  }
-};
 function createAuthMiddleware(config) {
   let isRefreshing = false;
   let refreshPromise = null;
+  let hasAssessedTokens = false;
+  const assessTokenStateOnce = async () => {
+    if (hasAssessedTokens) return;
+    hasAssessedTokens = true;
+    try {
+      const accessToken = await config.tokenStorage.getAccessToken();
+      const refreshToken = await config.tokenStorage.getRefreshToken();
+      if (!accessToken && refreshToken) {
+        await config.tokenStorage.clearTokens();
+        console.info("Cleaned up orphaned refresh token");
+      }
+    } catch (error) {
+      console.warn("Token state assessment failed:", error);
+    }
+  };
   const refreshTokens = async () => {
     if (isRefreshing && refreshPromise) {
       return refreshPromise;
@@ -449,17 +354,55 @@ function createAuthMiddleware(config) {
   return {
     async onRequest({ request }) {
       const pathname = getPathnameFromUrl(request.url);
+      await assessTokenStateOnce();
       if (isAnonymousAuthEndpoint(pathname)) {
         if (config.apiKey) {
           request.headers.set("X-Api-Key", config.apiKey);
         }
         const existingToken = await config.tokenStorage.getAccessToken();
+        if (existingToken && !isTokenExpired(existingToken) && isUserLoggedIn(existingToken)) {
+          return new Response(
+            JSON.stringify({
+              message: "Cannot create anonymous session while authenticated",
+              success: false,
+              code: "USER_ALREADY_AUTHENTICATED"
+            }),
+            {
+              status: 400,
+              headers: { "Content-Type": "application/json" }
+            }
+          );
+        }
         if (existingToken) {
           request.headers.set("Authorization", `Bearer ${existingToken}`);
         }
         return request;
       }
       let accessToken = await config.tokenStorage.getAccessToken();
+      if (!accessToken) {
+        try {
+          const response = await fetch(`${config.baseUrl}/auth/anonymous`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              ...config.apiKey && { "X-Api-Key": config.apiKey }
+            }
+          });
+          if (response.ok) {
+            const data = await response.json();
+            const tokens = data.content;
+            if (tokens?.access_token && tokens?.refresh_token) {
+              await config.tokenStorage.setAccessToken(tokens.access_token);
+              await config.tokenStorage.setRefreshToken(tokens.refresh_token);
+              accessToken = tokens.access_token;
+              config.onTokensUpdated?.(tokens.access_token, tokens.refresh_token);
+              console.info("Automatically created anonymous session for first API request");
+            }
+          }
+        } catch (error) {
+          console.warn("Failed to automatically create anonymous tokens:", error);
+        }
+      }
       if (accessToken && isTokenExpired(accessToken)) {
         try {
           await refreshTokens();
@@ -1020,6 +963,50 @@ var CatalogClient = class extends StorefrontAPIClient {
    * @param options - Optional query parameters
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with products and pagination info
+   *
+   * @example
+   * ```typescript
+   * // Basic product listing
+   * const { data, error } = await sdk.catalog.listProducts();
+   *
+   * if (error) {
+   *   console.error("Failed to list products:", error);
+   *   return;
+   * }
+   *
+   * console.log("Products found:", data.products?.length || 0);
+   * console.log("Pagination:", data.pagination);
+   *
+   * // With filtering and pagination
+   * const { data: filteredData, error: filteredError } = await sdk.catalog.listProducts({
+   *   page: 1,
+   *   limit: 20,
+   *   sort_by: JSON.stringify({ "created_at": "desc" }),
+   *   category_slug: ["electronics", "smartphones"]
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.catalog.listProducts(
+   *   {
+   *     page: 1,
+   *     limit: 20,
+   *     sort_by: JSON.stringify({ "created_at": "desc" }),
+   *     category_slug: ["electronics", "smartphones"]
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (filteredError) {
+   *   console.error("Failed to get filtered products:", filteredError);
+   *   return;
+   * }
+   *
+   * filteredData.products?.forEach(product => {
+   *   console.log(`Product: ${product.name} - ${product.price}`);
+   * });
+   * ```
    */
   async listProducts(options, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1038,6 +1025,46 @@ var CatalogClient = class extends StorefrontAPIClient {
    * @param options - Optional query parameters
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with skus and pagination info
+   *
+   * @example
+   * ```typescript
+   * // Basic SKU listing
+   * const { data, error } = await sdk.catalog.listSkus();
+   *
+   * if (error) {
+   *   console.error("Failed to list SKUs:", error);
+   *   return;
+   * }
+   *
+   * console.log("SKUs found:", data.skus?.length || 0);
+   * console.log("Pagination:", data.pagination);
+   *
+   * // With pagination
+   * const { data: skuData, error: skuError } = await sdk.catalog.listSkus({
+   *   page: 1,
+   *   limit: 50
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.catalog.listSkus(
+   *   {
+   *     page: 1,
+   *     limit: 50
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (skuError) {
+   *   console.error("Failed to get SKUs:", skuError);
+   *   return;
+   * }
+   *
+   * skuData.skus?.forEach(sku => {
+   *   console.log(`SKU: ${sku.sku} - Price: ${sku.price}`);
+   * });
+   * ```
    */
   async listSkus(options, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1056,6 +1083,43 @@ var CatalogClient = class extends StorefrontAPIClient {
    * @param pathParams - The path parameters (product ID or slug)
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with product details
+   *
+   * @example
+   * ```typescript
+   * // Get product by ID
+   * const { data, error } = await sdk.catalog.getProductDetail(
+   *   { product_id_or_slug: "prod_123" }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to get product details:", error);
+   *   return;
+   * }
+   *
+   * console.log("Product:", data.product.name);
+   * console.log("Price:", data.product.price);
+   * console.log("Description:", data.product.description);
+   *
+   * // Get product by slug
+   * const { data: slugData, error: slugError } = await sdk.catalog.getProductDetail({
+   *   product_id_or_slug: "detox-candy"
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.catalog.getProductDetail(
+   *   { product_id_or_slug: "detox-candy" },
+   *   {
+   *     "x-customer-group-id": "premium_customers" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (slugError) {
+   *   console.error("Failed to get product by slug:", slugError);
+   *   return;
+   * }
+   *
+   * console.log("Product with custom pricing:", slugData.product.price);
+   * ```
    */
   async getProductDetail(pathParams, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1069,11 +1133,37 @@ var CatalogClient = class extends StorefrontAPIClient {
     );
   }
   /**
-   * List variants for a specific product
+   * List all variants for a specific product
    *
    * @param pathParams - The path parameters (product ID)
    * @param headers - Optional header parameters (customer_group_id, etc.)
-   * @returns Promise with variants
+   * @returns Promise with product variants and pagination info
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.catalog.listProductVariants(
+   *   { product_id: "prod_123" }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to list product variants:", error);
+   *   return;
+   * }
+   *
+   * console.log("Variants found:", data.variants?.length || 0);
+   *
+   * data.variants?.forEach(variant => {
+   *   console.log(`Variant: ${variant.name} - SKU: ${variant.sku} - Price: ${variant.price}`);
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.catalog.listProductVariants(
+   *   { product_id: "prod_123" },
+   *   {
+   *     "x-customer-group-id": "wholesale_customers" // Override default SDK config
+   *   }
+   * );
+   * ```
    */
   async listProductVariants(pathParams, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1087,11 +1177,31 @@ var CatalogClient = class extends StorefrontAPIClient {
     );
   }
   /**
-   * Get details for a specific variant
+   * Get details for a specific product variant
    *
    * @param pathParams - The path parameters (product ID and variant ID)
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with variant details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.catalog.getVariantDetail(
+   *   {
+   *     product_id: "prod_123",
+   *     variant_id: "var_456"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to get variant details:", error);
+   *   return;
+   * }
+   *
+   * console.log("Variant:", data.variant.name);
+   * console.log("SKU:", data.variant.sku);
+   * console.log("Price:", data.variant.price);
+   * console.log("Stock:", data.variant.stock);
+   * ```
    */
   async getVariantDetail(pathParams, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1105,24 +1215,77 @@ var CatalogClient = class extends StorefrontAPIClient {
     );
   }
   /**
-   * List all categories
+   * List all product categories
    *
    * @param options - Optional query parameters
    * @returns Promise with categories and pagination info
+   *
+   * @example
+   * ```typescript
+   * // Basic category listing
+   * const { data, error } = await sdk.catalog.listCategories();
+   *
+   * if (error) {
+   *   console.error("Failed to list categories:", error);
+   *   return;
+   * }
+   *
+   * console.log("Categories found:", data.categories?.length || 0);
+   *
+   * data.categories?.forEach(category => {
+   *   console.log(`Category: ${category.name} - ${category.description}`);
+   * });
+   *
+   * // With pagination
+   * const { data: catData, error: catError } = await sdk.catalog.listCategories({
+   *   page: 1,
+   *   limit: 10
+   * });
+   * ```
    */
   async listCategories(options) {
     return this.executeRequest(
       () => this.client.GET("/catalog/categories", {
-        params: { query: options }
+        params: {
+          query: options
+        }
       })
     );
   }
   /**
-   * List reviews for a specific product
+   * List all reviews for a specific product
    *
    * @param pathParams - The path parameters (product ID)
    * @param queryParams - Optional query parameters
-   * @returns Promise with reviews and pagination info
+   * @returns Promise with product reviews and pagination info
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.catalog.listProductReviews(
+   *   { product_id: "prod_123" }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to list product reviews:", error);
+   *   return;
+   * }
+   *
+   * console.log("Reviews found:", data.reviews?.length || 0);
+   *
+   * data.reviews?.forEach(review => {
+   *   console.log(`Review by ${review.customer_name}: ${review.rating}/5`);
+   *   console.log("Comment:", review.comment);
+   * });
+   *
+   * // With pagination
+   * const { data: reviewData, error: reviewError } = await sdk.catalog.listProductReviews(
+   *   { product_id: "prod_123" },
+   *   {
+   *     page: 1,
+   *     limit: 5
+   *   }
+   * );
+   * ```
    */
   async listProductReviews(pathParams, queryParams) {
     return this.executeRequest(
@@ -1135,11 +1298,33 @@ var CatalogClient = class extends StorefrontAPIClient {
     );
   }
   /**
-   * Create a review for a specific product
+   * Create a product review
    *
    * @param pathParams - The path parameters (product ID)
-   * @param formData - The review data
-   * @returns Promise that resolves when the review is created
+   * @param formData - The review data including rating, comment, and optional images
+   * @returns Promise with review creation response
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.catalog.createProductReview(
+   *   { product_id: "prod_123" },
+   *   {
+   *     rating: 5,
+   *     comment: "Excellent product! Highly recommended.",
+   *     images: [
+   *       new File(["image data"], "review1.jpg", { type: "image/jpeg" }),
+   *       new File(["image data"], "review2.jpg", { type: "image/jpeg" })
+   *     ]
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to create review:", error);
+   *   return;
+   * }
+   *
+   * console.log("Review created successfully:", data.message);
+   * ```
    */
   async createProductReview(pathParams, formData) {
     return this.executeRequest(
@@ -1167,24 +1352,103 @@ var CatalogClient = class extends StorefrontAPIClient {
   /**
    * Search for products
    *
-   * @param searchData - The search parameters
-   * @returns Promise with search results, facet distribution, facet stats, and pagination
+   * @param searchData - The search query and filters
+   * @param headers - Optional header parameters (customer_group_id, etc.)
+   * @returns Promise with search results including products, facets, and pagination
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.catalog.searchProducts({
+   *   query: "smartphone",
+   *   filters: {
+   *     category: ["electronics", "mobile"],
+   *     price_range: { min: 100, max: 1000 },
+   *     brand: ["Apple", "Samsung"] // facet names depend on product configuration
+   *   },
+   *   page: 1,
+   *   limit: 20
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to search products:", error);
+   *   return;
+   * }
+   *
+   * console.log("Search results:", data.skus?.length || 0, "products found");
+   * console.log("Facet distribution:", data.facet_distribution);
+   * console.log("Price range:", data.facet_stats.price_range);
+   *
+   * data.skus?.forEach(sku => {
+   *   console.log(`Found: ${sku.name} - ${sku.price}`);
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.catalog.searchProducts(
+   *   {
+   *     query: "laptop",
+   *     filters: { category: ["computers"] }
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   * ```
    */
   async searchProducts(searchData, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
     return this.executeRequest(
       () => this.client.POST("/catalog/products/search", {
-        body: searchData,
-        header: mergedHeaders
+        params: {
+          header: mergedHeaders
+        },
+        body: searchData
       })
     );
   }
   /**
    * List cross-sell products
    *
-   * @param options - Optional query parameters
+   * @param options - Optional query parameters for filtering and pagination
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with cross-sell products
+   * @example
+   * ```typescript
+   * // Basic usage - get cross-sell products for cart items
+   * const { data, error } = await sdk.catalog.listCrossSellProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE", "prod_01H9ABC67890FGHIJ"]
+   * });
+   *
+   * // Advanced usage with pagination and custom sorting
+   * const { data, error } = await sdk.catalog.listCrossSellProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE"],
+   *   page: 1,
+   *   limit: 10,
+   *   sort_by: '{"price":"asc"}'
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data, error } = await sdk.catalog.listCrossSellProducts(
+   *   {
+   *     product_id: ["prod_01H9XYZ12345ABCDE"],
+   *     page: 1,
+   *     limit: 10
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to get cross-sell products:", error.message);
+   * } else {
+   *   console.log("Cross-sell products found:", data.content.products.length);
+   *   console.log("Pagination:", data.content.pagination);
+   *
+   *   data.content.products.forEach(product => {
+   *     console.log(`Product: ${product.name} - ${product.price}`);
+   *   });
+   * }
+   * ```
    */
   async listCrossSellProducts(options, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1200,9 +1464,47 @@ var CatalogClient = class extends StorefrontAPIClient {
   /**
    * List up-sell products
    *
-   * @param options - Optional query parameters
+   * @param options - Optional query parameters for filtering and pagination
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with up-sell products
+   * @example
+   * ```typescript
+   * // Basic usage - get up-sell products for cart items
+   * const { data, error } = await sdk.catalog.listUpSellProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE"]
+   * });
+   *
+   * // Advanced usage with pagination and custom sorting
+   * const { data, error } = await sdk.catalog.listUpSellProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE"],
+   *   page: 1,
+   *   limit: 15,
+   *   sort_by: '{"relevance":"desc"}'
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data, error } = await sdk.catalog.listUpSellProducts(
+   *   {
+   *     product_id: ["prod_01H9XYZ12345ABCDE"],
+   *     page: 1,
+   *     limit: 15
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to get up-sell products:", error.message);
+   * } else {
+   *   console.log("Up-sell products found:", data.content.products.length);
+   *   console.log("Pagination:", data.content.pagination);
+   *
+   *   data.content.products.forEach(product => {
+   *     console.log(`Up-sell: ${product.name} - ${product.price}`);
+   *   });
+   * }
+   * ```
    */
   async listUpSellProducts(options, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1218,9 +1520,47 @@ var CatalogClient = class extends StorefrontAPIClient {
   /**
    * List similar products
    *
-   * @param options - Optional query parameters
+   * @param options - Optional query parameters for filtering and pagination
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with similar products
+   * @example
+   * ```typescript
+   * // Basic usage - get similar products for a specific product
+   * const { data, error } = await sdk.catalog.listSimilarProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE"]
+   * });
+   *
+   * // Advanced usage with pagination and custom sorting
+   * const { data, error } = await sdk.catalog.listSimilarProducts({
+   *   product_id: ["prod_01H9XYZ12345ABCDE"],
+   *   page: 1,
+   *   limit: 20,
+   *     sort_by: '{"relevance":"desc"}'
+   * });
+   *
+   * // Override customer group ID for this specific request
+   * const { data, error } = await sdk.catalog.listSimilarProducts(
+   *   {
+   *     product_id: ["prod_01H9XYZ12345ABCDE"],
+   *     page: 1,
+   *     limit: 20
+   *   },
+   *   {
+   *     "x-customer-group-id": "01H9XYZ12345USERID" // Override default SDK config
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to get similar products:", error.message);
+   * } else {
+   *   console.log("Similar products found:", data.content.products.length);
+   *   console.log("Pagination:", data.content.pagination);
+   *
+   *   data.content.products.forEach(product => {
+   *     console.log(`Similar: ${product.name} - ${product.price}`);
+   *   });
+   * }
+   * ```
    */
   async listSimilarProducts(options, headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1242,6 +1582,33 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param payload - Object containing the items to add to the cart
    * @returns Promise with the created cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.createCart({
+   *   items: [
+   *     {
+   *       product_id: "01H9XYZ12345ABCDE",
+   *       variant_id: null,
+   *       quantity: 2
+   *     },
+   *     {
+   *       product_id: "01H9ABC67890FGHIJ",
+   *       variant_id: "01H9XYZ67890KLMNO",
+   *       quantity: 1
+   *     }
+   *   ],
+   *   metadata: {
+   *     "source": "web",
+   *     "campaign": "summer_sale"
+   *   }
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to create cart:", error.message);
+   * } else {
+   *   console.log("Cart created:", data.cart.id);
+   * }
+   * ```
    */
   async createCart(payload) {
     return this.executeRequest(
@@ -1255,6 +1622,20 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with cart details
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.getCart({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get cart:", error.message);
+   * } else {
+   *   const cart = data.cart;
+   *   console.log("Cart total:", cart.total_amount);
+   *   console.log("Items count:", cart.items.length);
+   * }
+   * ```
    */
   async getCart(cartId) {
     return this.executeRequest(
@@ -1270,6 +1651,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise that resolves when the cart is deleted
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.deleteCart({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to delete cart:", error.message);
+   * } else {
+   *   console.log("Cart deleted:", data.message);
+   * }
+   * ```
    */
   async deleteCart(cartId) {
     return this.executeRequest(
@@ -1286,6 +1679,34 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The cart id
    * @param body - The body of the request
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * // Add item to cart
+   * const { data, error } = await sdk.cart.addDeleteCartItem(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     product_id: "01H9XYZ12345ABCDE",
+   *     variant_id: null,
+   *     quantity: 3
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update cart:", error.message);
+   * } else {
+   *   console.log("Cart updated:", data.cart.items.length);
+   * }
+   *
+   * // Remove item from cart (set quantity to 0)
+   * const { data: removeData, error: removeError } = await sdk.cart.addDeleteCartItem(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     product_id: "01H9XYZ12345ABCDE",
+   *     variant_id: null,
+   *     quantity: 0
+   *   }
+   * );
+   * ```
    */
   async addDeleteCartItem(cartId, body) {
     return this.executeRequest(
@@ -1302,6 +1723,19 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param userId - The ID of the user
    * @returns Promise with cart details
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.getUserCart({
+   *   user_id: "01H9USER12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get user cart:", error.message);
+   * } else {
+   *   console.log("User cart ID:", data.cart.id);
+   *   console.log("Cart value:", data.cart.subtotal_amount);
+   * }
+   * ```
    */
   async getUserCart(userId) {
     return this.executeRequest(
@@ -1317,6 +1751,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param userId - The ID of the user
    * @returns Promise that resolves when the cart is deleted
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.deleteUserCart({
+   *   user_id: "01H9USER12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to delete user cart:", error.message);
+   * } else {
+   *   console.log("User cart cleared:", data.message);
+   * }
+   * ```
    */
   async deleteUserCart(userId) {
     return this.executeRequest(
@@ -1334,6 +1780,62 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param addressData - The address data
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * // For registered users with saved addresses
+   * const { data, error } = await sdk.cart.updateCartAddress(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     billing_address_id: "01H9ADDR12345BILL",
+   *     shipping_address_id: "01H9ADDR12345SHIP"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update cart address:", error.message);
+   * } else {
+   *   console.log("Addresses updated:", data.message);
+   * }
+   *
+   * // For guest checkout with new addresses
+   * const { data: guestData, error: guestError } = await sdk.cart.updateCartAddress(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     billing_address: {
+   *       first_name: "John",
+   *       last_name: "Doe",
+   *       email: "john@example.com",
+   *       phone: "9876543210",
+   *       country_code: "+91",
+   *       address_line1: "123 Main Street",
+   *       address_line2: "Apt 4B",
+   *       city: "Mumbai",
+   *       state: "Maharashtra",
+   *       pincode: "400001",
+   *       country: "India",
+   *       landmark: "Near Station",
+   *       tax_identification_number: null,
+   *       business_name: null
+   *     },
+   *     shipping_address: {
+   *       first_name: "John",
+   *       last_name: "Doe",
+   *       email: "john@example.com",
+   *       phone: "9876543210",
+   *       country_code: "+91",
+   *       address_line1: "456 Oak Avenue",
+   *       address_line2: null,
+   *       city: "Pune",
+   *       state: "Maharashtra",
+   *       pincode: "411001",
+   *       country: "India",
+   *       landmark: "Near Mall",
+   *       tax_identification_number: null,
+   *       business_name: null
+   *     }
+   *   }
+   * );
+   * ```
    */
   async updateCartAddress(cartId, addressData) {
     return this.executeRequest(
@@ -1351,6 +1853,20 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param couponCode - The coupon code
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.applyCoupon(
+   *   { id: "01H9CART12345ABCDE" },
+   *   { coupon_code: "FLAT100OFF" }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to apply coupon:", error.message);
+   * } else {
+   *   console.log("Coupon applied, new total:", data.cart.total_amount);
+   *   console.log("Discount amount:", data.cart.coupon_discount_amount);
+   * }
+   * ```
    */
   async applyCoupon(cartId, couponCode) {
     return this.executeRequest(
@@ -1367,6 +1883,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.removeCoupon({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to remove coupon:", error.message);
+   * } else {
+   *   console.log("Coupon removed, new total:", data.cart.total_amount);
+   * }
+   * ```
    */
   async removeCoupon(cartId) {
     return this.executeRequest(
@@ -1384,6 +1912,20 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param points - The number of points to redeem
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.redeemLoyaltyPoints(
+   *   { id: "01H9CART12345ABCDE" },
+   *   { points: 500 }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to redeem loyalty points:", error.message);
+   * } else {
+   *   console.log("Points redeemed, new total:", data.cart.total_amount);
+   *   console.log("Points discount:", data.cart.loyalty_points_discount_amount);
+   * }
+   * ```
    */
   async redeemLoyaltyPoints(cartId, points) {
     return this.executeRequest(
@@ -1400,6 +1942,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.removeLoyaltyPoints({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to remove loyalty points:", error.message);
+   * } else {
+   *   console.log("Loyalty points removed, new total:", data.cart.total_amount);
+   * }
+   * ```
    */
   async removeLoyaltyPoints(cartId) {
     return this.executeRequest(
@@ -1417,6 +1971,23 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param body - The body of the request
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.updateShippingMethod(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     shipping_method_id: "01H9SHIP12345FAST",
+   *     estimated_delivery_date: "2024-01-15"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update shipping method:", error.message);
+   * } else {
+   *   console.log("Shipping method updated:", data.cart.shipping_method?.name);
+   *   console.log("Shipping cost:", data.cart.shipping_cost);
+   * }
+   * ```
    */
   async updateShippingMethod(cartId, body) {
     return this.executeRequest(
@@ -1434,6 +2005,20 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param body - The body of the request
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.redeemCreditBalance(
+   *   { id: "01H9CART12345ABCDE" },
+   *   { amount: 250.00 }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to redeem credit balance:", error.message);
+   * } else {
+   *   console.log("Credit applied, new total:", data.cart.total_amount);
+   *   console.log("Credit discount:", data.cart.credit_balance_discount_amount);
+   * }
+   * ```
    */
   async redeemCreditBalance(cartId, body) {
     return this.executeRequest(
@@ -1450,6 +2035,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.removeCreditBalance({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to remove credit balance:", error.message);
+   * } else {
+   *   console.log("Credit balance removed, new total:", data.cart.total_amount);
+   * }
+   * ```
    */
   async removeCreditBalance(cartId) {
     return this.executeRequest(
@@ -1467,6 +2064,23 @@ var CartClient = class extends StorefrontAPIClient {
    * @param cartId - The ID of the cart
    * @param body - The body of the request
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.redeemGiftCard(
+   *   { id: "01H9CART12345ABCDE" },
+   *   {
+   *     gift_card_code: "GIFT2024-ABCD-1234",
+   *     amount: 100.00
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to redeem gift card:", error.message);
+   * } else {
+   *   console.log("Gift card applied, new total:", data.cart.total_amount);
+   *   console.log("Gift card discount:", data.cart.gift_card_discount_amount);
+   * }
+   * ```
    */
   async redeemGiftCard(cartId, body) {
     return this.executeRequest(
@@ -1483,6 +2097,18 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with updated cart
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.removeGiftCard({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to remove gift card:", error.message);
+   * } else {
+   *   console.log("Gift card removed, new total:", data.cart.total_amount);
+   * }
+   * ```
    */
   async removeGiftCard(cartId) {
     return this.executeRequest(
@@ -1499,6 +2125,22 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param userId - The ID of the user
    * @returns Promise with wishlist items
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.getWishlist({
+   *   user_id: "01H9USER12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get wishlist:", error.message);
+   * } else {
+   *   const products = data.products;
+   *   console.log("Wishlist items:", products.length);
+   *   products.forEach(product => {
+   *     console.log("Product:", product.name, "Price:", product.price);
+   *   });
+   * }
+   * ```
    */
   async getWishlist(userId) {
     return this.executeRequest(
@@ -1515,6 +2157,23 @@ var CartClient = class extends StorefrontAPIClient {
    * @param userId - The ID of the user
    * @param itemId - The ID of the item
    * @returns Promise with updated wishlist
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.addToWishlist(
+   *   { user_id: "01H9USER12345ABCDE" },
+   *   {
+   *     product_id: "01F3Z7KG06J4ACWH1C4926KJEC",
+   *     variant_id: null
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to add to wishlist:", error.message);
+   * } else {
+   *   const products = data.products;
+   *   console.log("Item added to wishlist, total items:", products.length);
+   * }
+   * ```
    */
   async addToWishlist(userId, itemId) {
     return this.executeRequest(
@@ -1530,8 +2189,25 @@ var CartClient = class extends StorefrontAPIClient {
    * Remove item from wishlist
    *
    * @param userId - The ID of the user
-   * @param itemId - The ID of the item
+   * @param body - The body containing product details to remove
    * @returns Promise with updated wishlist
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.removeFromWishlist(
+   *   { user_id: "01H9USER12345ABCDE" },
+   *   {
+   *     product_id: "01F3Z7KG06J4ACWH1C4926KJEC",
+   *     variant_id: null
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to remove from wishlist:", error.message);
+   * } else {
+   *   const products = data.products;
+   *   console.log("Item removed from wishlist, remaining items:", products.length);
+   * }
+   * ```
    */
   async removeFromWishlist(userId, body) {
     return this.executeRequest(
@@ -1548,6 +2224,26 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with all available coupons
+   * @example
+   * ```typescript
+   * // Get all available coupons
+   * const { data, error } = await sdk.cart.getAvailableCoupons();
+   *
+   * if (error) {
+   *   console.error("Failed to get available coupons:", error.message);
+   * } else {
+   *   const coupons = data.coupons || [];
+   *   console.log("Available coupons:", coupons.length);
+   *   coupons.forEach(coupon => {
+   *     console.log("Coupon:", coupon.code, "Discount:", coupon.discount_amount);
+   *   });
+   * }
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.cart.getAvailableCoupons({
+   *   "x-customer-group-id": "01H9GROUP12345ABC" // Override default SDK config
+   * });
+   * ```
    */
   async getAvailableCoupons(headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1564,6 +2260,26 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param headers - Optional header parameters (customer_group_id, etc.)
    * @returns Promise with all available promotions
+   * @example
+   * ```typescript
+   * // Get all available promotions
+   * const { data, error } = await sdk.cart.getAvailablePromotions();
+   *
+   * if (error) {
+   *   console.error("Failed to get available promotions:", error.message);
+   * } else {
+   *   const promotions = data.promotions || [];
+   *   console.log("Available promotions:", promotions.length);
+   *   promotions.forEach(promotion => {
+   *     console.log("Promotion:", promotion.name, "Type:", promotion.promotion_type);
+   *   });
+   * }
+   *
+   * // Override customer group ID for this specific request
+   * const { data: overrideData, error: overrideError } = await sdk.cart.getAvailablePromotions({
+   *   "x-customer-group-id": "01H9GROUP12345ABC" // Override default SDK config
+   * });
+   * ```
    */
   async getAvailablePromotions(headers) {
     const mergedHeaders = this.mergeHeaders(headers);
@@ -1580,6 +2296,29 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with evaluated promotions
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.evaluatePromotions({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to evaluate promotions:", error.message);
+   * } else {
+   *   const applicable = data.applicable_promotions || [];
+   *   const inapplicable = data.inapplicable_promotions || [];
+   *
+   *   console.log("Applicable promotions:", applicable.length);
+   *   applicable.forEach(promo => {
+   *     console.log(`- ${promo.name}: ${promo.savings_message}`);
+   *   });
+   *
+   *   console.log("Inapplicable promotions:", inapplicable.length);
+   *   inapplicable.forEach(promo => {
+   *     console.log(`- ${promo.name}: ${promo.reason}`);
+   *   });
+   * }
+   * ```
    */
   async evaluatePromotions(cartId) {
     return this.executeRequest(
@@ -1595,6 +2334,29 @@ var CartClient = class extends StorefrontAPIClient {
    *
    * @param cartId - The ID of the cart
    * @returns Promise with evaluated coupons
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.cart.evaluateCoupons({
+   *   id: "01H9CART12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to evaluate coupons:", error.message);
+   * } else {
+   *   const applicable = data.applicable_coupons || [];
+   *   const inapplicable = data.inapplicable_coupons || [];
+   *
+   *   console.log("Applicable coupons:", applicable.length);
+   *   applicable.forEach(coupon => {
+   *     console.log(`- ${coupon.code}: Save $${coupon.estimated_discount}`);
+   *   });
+   *
+   *   console.log("Inapplicable coupons:", inapplicable.length);
+   *   inapplicable.forEach(coupon => {
+   *     console.log(`- ${coupon.code}: ${coupon.reason}`);
+   *   });
+   * }
+   * ```
    */
   async evaluateCoupons(cartId) {
     return this.executeRequest(
@@ -1611,19 +2373,45 @@ var CartClient = class extends StorefrontAPIClient {
 var AuthClient = class extends StorefrontAPIClient {
   /**
    * Get anonymous token for guest users
+   *
+   * @example
+   * ```typescript
+   * // Get token for guest browsing
+   * const { data, error } = await sdk.auth.getAnonymousToken();
+   *
+   * if (error) {
+   *   console.error("Failed to get anonymous token:", error.message);
+   * } else {
+   *   console.log("Anonymous token:", data.access_token);
+   *   // Store token or proceed with guest operations
+   * }
+   * ```
    */
   async getAnonymousToken() {
-    return this.executeRequest(
-      () => this.client.POST("/auth/anonymous")
-    );
+    return this.executeRequest(() => this.client.POST("/auth/anonymous"));
   }
   /**
    * 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 
+   * @param body - Login request body containing phone number and options
+   * @returns Promise with OTP token and action
+   * @example
+   * ```typescript
+   * // Login with phone number
+   * const { data, error } = await sdk.auth.loginWithPhone({
+   *   phoneNumber: "9876543210",
+   *   countryCode: "+91",
+   *   registerIfNotExists: true
+   * });
+   *
+   * if (error) {
+   *   console.error("Login failed:", error.message);
+   * } else {
+   *   console.log("OTP sent. Token:", data.otpToken);
+   *   console.log("Action:", data.action); // "login" or "register"
+   *   // Redirect user to OTP verification screen
+   * }
+   * ```
    */
   async loginWithPhone(body) {
     return this.executeRequest(
@@ -1635,10 +2423,24 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Login with WhatsApp
    *
-   * @param phoneNumber - Phone number (without country code)
-   * @param countryCode - Country code (defaults to +91)
-   * @param registerIfNotExists - Whether to register if user doesn't exist
+   * @param body - Login request body containing phone number and options
    * @returns Promise with OTP token and action
+   * @example
+   * ```typescript
+   * // Login with WhatsApp number
+   * const { data, error } = await sdk.auth.loginWithWhatsApp({
+   *   phone: "9876543210",
+   *   country_code: "+91",
+   *   register_if_not_exists: true
+   * });
+   *
+   * if (error) {
+   *   console.error("WhatsApp login failed:", error.message);
+   * } else {
+   *   console.log("OTP sent to WhatsApp. Token:", data.otp_token);
+   *   console.log("Action:", data.otp_action); // "login" or "register"
+   * }
+   * ```
    */
   async loginWithWhatsApp(body) {
     return this.executeRequest(
@@ -1650,9 +2452,24 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Login with email
    *
-   * @param email - Email address
-   * @param registerIfNotExists - Whether to register if user doesn't exist
+   * @param body - Login request body containing email and options
    * @returns Promise with OTP token and action
+   * @example
+   * ```typescript
+   * // Login with email address
+   * const { data, error } = await sdk.auth.loginWithEmail({
+   *   email: "customer@example.com",
+   *   registerIfNotExists: true
+   * });
+   *
+   * if (error) {
+   *   console.error("Email login failed:", error.message);
+   * } else {
+   *   console.log("OTP sent to email. Token:", data.otpToken);
+   *   console.log("Action:", data.action); // "login" or "register"
+   *   // Show OTP input form
+   * }
+   * ```
    */
   async loginWithEmail(body) {
     return this.executeRequest(
@@ -1664,8 +2481,23 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Login with password
    *
-   * @param credentials - Login credentials
+   * @param body - Login credentials containing email/phone and password
    * @returns Promise with user info and tokens
+   * @example
+   * ```typescript
+   * // Login with email and password
+   * const { data, error } = await sdk.auth.loginWithPassword({
+   *   email: "customer@example.com",
+   *   password: "securePassword123"
+   * });
+   *
+   * if (error) {
+   *   console.error("Password login failed:", error.message);
+   * } else {
+   *   console.log("Login successful:", data.user.email);
+   *   console.log("Access token:", data.access_token);
+   * }
+   * ```
    */
   async loginWithPassword(body) {
     return this.executeRequest(
@@ -1677,8 +2509,22 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Forgot password
    *
-   * @param email - Email address
-   * @returns Promise with user info and tokens
+   * @param body - Request body containing email address
+   * @returns Promise with password reset information
+   * @example
+   * ```typescript
+   * // Send password reset email
+   * const { data, error } = await sdk.auth.forgotPassword({
+   *   email: "customer@example.com"
+   * });
+   *
+   * if (error) {
+   *   console.error("Password reset failed:", error.message);
+   * } else {
+   *   console.log("Reset email sent successfully");
+   *   // Show confirmation message to user
+   * }
+   * ```
    */
   async forgotPassword(body) {
     return this.executeRequest(
@@ -1690,8 +2536,24 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Reset password
    *
-   * @param email - Email address
-   * @returns Promise with user info and tokens
+   * @param body - Reset password request body containing new password and OTP token
+   * @returns Promise with new access and refresh tokens
+   * @example
+   * ```typescript
+   * // Reset password with OTP token from forgot password flow
+   * const { data, error } = await sdk.auth.resetPassword({
+   *   new_password: "newSecurePassword123",
+   *   confirm_password: "newSecurePassword123",
+   *   otp_token: "abc123otptoken"
+   * });
+   *
+   * if (error) {
+   *   console.error("Password reset failed:", error.message);
+   * } else {
+   *   console.log("Password reset successful");
+   *   console.log("New access token:", data.access_token);
+   * }
+   * ```
    */
   async resetPassword(body) {
     return this.executeRequest(
@@ -1703,10 +2565,24 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Change password
    *
-   * @param oldPassword - Old password
-   * @param newPassword - New password
-   * @param newPasswordConfirmation - New password confirmation
-   * @returns Promise with new access token and refresh token
+   * @param body - Change password request body containing old and new passwords
+   * @returns Promise with new access and refresh tokens
+   * @example
+   * ```typescript
+   * // Change user's password
+   * const { data, error } = await sdk.auth.changePassword({
+   *   old_password: "currentPassword123",
+   *   new_password: "newSecurePassword456",
+   *   confirm_password: "newSecurePassword456"
+   * });
+   *
+   * if (error) {
+   *   console.error("Password change failed:", error.message);
+   * } else {
+   *   console.log("Password changed successfully");
+   *   console.log("New access token:", data.access_token);
+   * }
+   * ```
    */
   async changePassword(body) {
     return this.executeRequest(
@@ -1718,10 +2594,25 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Verify OTP
    *
-   * @param otp - One-time password
-   * @param otpToken - OTP token from login request
-   * @param otpAction - OTP action from login request
+   * @param body - OTP verification data including code and tokens
    * @returns Promise with user info and tokens
+   * @example
+   * ```typescript
+   * // Verify OTP after login attempt
+   * const { data, error } = await sdk.auth.verifyOtp({
+   *   otp: "1234",
+   *   otpToken: "56895455",
+   *   otpAction: "login" // or "register"
+   * });
+   *
+   * if (error) {
+   *   console.error("OTP verification failed:", error.message);
+   *   // Show error message, allow retry
+   * } else {
+   *   console.log("Login successful:", data.user.email);
+   *   console.log("User ID:", data.user.id);
+   * }
+   * ```
    */
   async verifyOtp(body) {
     return this.executeRequest(
@@ -1733,8 +2624,27 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Register with phone
    *
-   * @param options - Registration details
+   * @param body - Registration details including phone number and user information
    * @returns Promise with user info and tokens
+   * @example
+   * ```typescript
+   * // Register a new user with phone number
+   * const { data, error } = await sdk.auth.registerWithPhone({
+   *   phone: "9876543210",
+   *   country_code: "+91",
+   *   first_name: "John",
+   *   last_name: "Doe",
+   *   email: "john.doe@example.com"
+   * });
+   *
+   * if (error) {
+   *   console.error("Phone registration failed:", error.message);
+   * } else {
+   *   console.log("Registration successful:", data.user.first_name);
+   *   console.log("User ID:", data.user.id);
+   *   console.log("Access token:", data.access_token);
+   * }
+   * ```
    */
   async registerWithPhone(body) {
     return this.executeRequest(
@@ -1746,8 +2656,26 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Register with email
    *
-   * @param options - Registration details
+   * @param body - Registration details including email and user information
    * @returns Promise with user info and tokens
+   * @example
+   * ```typescript
+   * // Register a new user with email address
+   * const { data, error } = await sdk.auth.registerWithEmail({
+   *   email: "jane.smith@example.com",
+   *   first_name: "Jane",
+   *   last_name: "Smith",
+   *   phone: "9876543210"
+   * });
+   *
+   * if (error) {
+   *   console.error("Email registration failed:", error.message);
+   * } else {
+   *   console.log("Registration successful:", data.user.email);
+   *   console.log("User ID:", data.user.id);
+   *   console.log("Access token:", data.access_token);
+   * }
+   * ```
    */
   async registerWithEmail(body) {
     return this.executeRequest(
@@ -1758,8 +2686,24 @@ var AuthClient = class extends StorefrontAPIClient {
   }
   /**
    * Refresh the access token using a refresh token
-   * @param refreshToken - The refresh token to use for refreshing the access token
+   * @param body - Request body containing the refresh token
    * @returns Promise with the new access token and refresh token
+   * @example
+   * ```typescript
+   * // Refresh access token when it expires
+   * const { data, error } = await sdk.auth.refreshToken({
+   *   refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+   * });
+   *
+   * if (error) {
+   *   console.error("Token refresh failed:", error.message);
+   *   // Redirect to login
+   * } else {
+   *   console.log("Token refreshed successfully");
+   *   console.log("New access token:", data.access_token);
+   *   console.log("New refresh token:", data.refresh_token);
+   * }
+   * ```
    */
   async refreshToken(body) {
     return this.executeRequest(
@@ -1772,17 +2716,43 @@ var AuthClient = class extends StorefrontAPIClient {
    * Logout
    *
    * @returns Promise that resolves when logout is complete
+   * @example
+   * ```typescript
+   * // Logout current user
+   * const { data, error } = await sdk.auth.logout();
+   *
+   * if (error) {
+   *   console.error("Logout failed:", error.message);
+   * } else {
+   *   console.log("Logout successful");
+   *   console.log("Session ended for user:", data.user.email);
+   * }
+   * ```
    */
   async logout() {
-    return this.executeRequest(
-      () => this.client.POST("/auth/logout")
-    );
+    return this.executeRequest(() => this.client.POST("/auth/logout"));
   }
   /**
    * Get user details
    *
-   * @param userId - User ID
+   * @param pathParams - Path parameters containing user ID
    * @returns Promise with user details
+   * @example
+   * ```typescript
+   * // Get details for a specific user
+   * const { data, error } = await sdk.auth.getUserDetails({
+   *   id: "01H9XYZ12345USERID"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get user details:", error.message);
+   * } else {
+   *   console.log("User details:", data.user);
+   *   console.log("Email:", data.user.email);
+   *   console.log("Phone:", data.user.phoneNumber);
+   *   console.log("Created:", data.user.createdAt);
+   * }
+   * ```
    */
   async getUserDetails(pathParams) {
     return this.executeRequest(
@@ -1796,8 +2766,29 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Update user details
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @param body - Updated user information
+   * @returns Promise with updated user details
+   * @example
+   * ```typescript
+   * // Update user profile information
+   * const { data, error } = await sdk.auth.updateUserDetails(
+   *   { id: "01H9XYZ12345USERID" },
+   *   {
+   *     first_name: "John",
+   *     last_name: "Doe",
+   *     email: "john.doe@example.com",
+   *     phone: "9876543210",
+   *     country_code: "+91"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update user:", error.message);
+   * } else {
+   *   console.log("User updated successfully:", data.user.first_name);
+   * }
+   * ```
    */
   async updateUserDetails(pathParams, body) {
     return this.executeRequest(
@@ -1812,8 +2803,25 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Add profile image
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @param formData - Form data containing the image file
+   * @returns Promise with profile image URL
+   * @example
+   * ```typescript
+   * // Add profile image for a user
+   * const imageFile = document.getElementById('file-input').files[0];
+   * const { data, error } = await sdk.auth.addProfileImage(
+   *   { id: "01H9XYZ12345USERID" },
+   *   { image: imageFile }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to add profile image:", error.message);
+   * } else {
+   *   console.log("Profile image added successfully");
+   *   console.log("Image URL:", data.profile_image_url);
+   * }
+   * ```
    */
   async addProfileImage(pathParams, formData) {
     return this.executeRequest(
@@ -1837,8 +2845,25 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Update profile image
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @param formData - Form data containing the new image file
+   * @returns Promise with updated profile image URL
+   * @example
+   * ```typescript
+   * // Update existing profile image
+   * const newImageFile = document.getElementById('file-input').files[0];
+   * const { data, error } = await sdk.auth.updateProfileImage(
+   *   { id: "01H9XYZ12345USERID" },
+   *   { image: newImageFile }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update profile image:", error.message);
+   * } else {
+   *   console.log("Profile image updated successfully");
+   *   console.log("New image URL:", data.profile_image_url);
+   * }
+   * ```
    */
   async updateProfileImage(pathParams, formData) {
     return this.executeRequest(
@@ -1862,8 +2887,22 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Delete profile image
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @returns Promise with deletion confirmation
+   * @example
+   * ```typescript
+   * // Delete user's profile image
+   * const { data, error } = await sdk.auth.deleteProfileImage({
+   *   id: "01H9XYZ12345USERID"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to delete profile image:", error.message);
+   * } else {
+   *   console.log("Profile image deleted successfully");
+   *   console.log("Success:", data.success);
+   * }
+   * ```
    */
   async deleteProfileImage(pathParams) {
     return this.executeRequest(
@@ -1877,8 +2916,21 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Get profile image
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @returns Promise with profile image URL
+   * @example
+   * ```typescript
+   * // Get user's profile image URL
+   * const { data, error } = await sdk.auth.getProfileImage({
+   *   id: "01H9XYZ12345USERID"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get profile image:", error.message);
+   * } else {
+   *   console.log("Profile image URL:", data.profile_image_url);
+   * }
+   * ```
    */
   async getProfileImage(pathParams) {
     return this.executeRequest(
@@ -1892,8 +2944,22 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Deactivate user account
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @returns Promise with deactivation confirmation
+   * @example
+   * ```typescript
+   * // Deactivate a user account
+   * const { data, error } = await sdk.auth.deactivateUserAccount({
+   *   id: "01H9XYZ12345USERID"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to deactivate account:", error.message);
+   * } else {
+   *   console.log("Account deactivated successfully");
+   *   console.log("Success:", data.success);
+   * }
+   * ```
    */
   async deactivateUserAccount(pathParams) {
     return this.executeRequest(
@@ -1907,8 +2973,21 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Get user notification preferences
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @returns Promise with user's notification preferences
+   * @example
+   * ```typescript
+   * // Get user's notification preferences
+   * const { data, error } = await sdk.auth.getUserNotificationPreferences({
+   *   id: "01H9XYZ12345USERID"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get preferences:", error.message);
+   * } else {
+   *   console.log("Notification preferences:", data.notification_preferences);
+   * }
+   * ```
    */
   async getUserNotificationPreferences(pathParams) {
     return this.executeRequest(
@@ -1922,8 +3001,27 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Update user notification preferences
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @param body - Updated notification preferences
+   * @returns Promise with updated notification preferences
+   * @example
+   * ```typescript
+   * // Update user's notification preferences
+   * const { data, error } = await sdk.auth.updateUserNotificationPreferences(
+   *   { id: "01H9XYZ12345USERID" },
+   *   {
+   *     email_notifications: true,
+   *     sms_notifications: false,
+   *     push_notifications: true
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update preferences:", error.message);
+   * } else {
+   *   console.log("Preferences updated successfully");
+   * }
+   * ```
    */
   async updateUserNotificationPreferences(pathParams, body) {
     return this.executeRequest(
@@ -1938,8 +3036,27 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Create user notification preference
    *
-   * @param userId - User ID
-   * @returns Promise with user details
+   * @param pathParams - Path parameters containing user ID
+   * @param body - Notification preferences to create
+   * @returns Promise with created notification preferences
+   * @example
+   * ```typescript
+   * // Create notification preferences for a user
+   * const { data, error } = await sdk.auth.createUserNotificationPreference(
+   *   { id: "01H9XYZ12345USERID" },
+   *   {
+   *     email_notifications: true,
+   *     sms_notifications: true,
+   *     push_notifications: false
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to create preferences:", error.message);
+   * } else {
+   *   console.log("Preferences created successfully");
+   * }
+   * ```
    */
   async createUserNotificationPreference(pathParams, body) {
     return this.executeRequest(
@@ -1953,9 +3070,25 @@ var AuthClient = class extends StorefrontAPIClient {
   }
   /**
    * Generate OTP
-   * 
-   * @param body - OTP generation body
-   * @returns Promise with OTP generation response
+   *
+   * @param body - OTP generation body (phone or email)
+   * @returns Promise with OTP token and action
+   * @example
+   * ```typescript
+   * // Generate OTP for phone number
+   * const { data, error } = await sdk.auth.generateOtp({
+   *   phone: "9876543210",
+   *   country_code: "+91"
+   * });
+   *
+   * if (error) {
+   *   console.error("OTP generation failed:", error.message);
+   * } else {
+   *   console.log("OTP sent successfully");
+   *   console.log("OTP token:", data.otp_token);
+   *   console.log("Action:", data.otp_action);
+   * }
+   * ```
    */
   async generateOtp(body) {
     return this.executeRequest(
@@ -1967,8 +3100,23 @@ var AuthClient = class extends StorefrontAPIClient {
   /**
    * Check whether email or phone is already verified
    *
-   * @param body - OTP generation body
-   * @returns Promise with OTP generation response
+   * @param body - Request body containing phone numbers or email addresses to verify
+   * @returns Promise with verification status for provided contacts
+   * @example
+   * ```typescript
+   * // Check verification status for multiple contacts
+   * const { data, error } = await sdk.auth.checkEmailOrPhoneIsVerified({
+   *   phone: ["9876543210", "9123456789"],
+   *   email: ["user1@example.com", "user2@example.com"]
+   * });
+   *
+   * if (error) {
+   *   console.error("Verification check failed:", error.message);
+   * } else {
+   *   console.log("Verified phones:", data.verified_phone);
+   *   console.log("Verified emails:", data.verified_email);
+   * }
+   * ```
    */
   async checkEmailOrPhoneIsVerified(body) {
     return this.executeRequest(
@@ -1986,6 +3134,20 @@ var OrderClient = class extends StorefrontAPIClient {
    *
    * @param orderNumber - Order number
    * @returns Promise with order details
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.getOrderDetails({
+   *   order_number: "ORD-2024-001"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get order details:", error.message);
+   * } else {
+   *   console.log("Order details:", data.content.order);
+   *   console.log("Order status:", data.content.order.status);
+   *   console.log("Total amount:", data.content.order.total_amount);
+   * }
+   * ```
    */
   async getOrderDetails(pathParams) {
     return this.executeRequest(
@@ -1999,10 +3161,42 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * Create order
    *
-   * @param cartId - Cart ID
-   * @param paymentGateway - Payment gateway
-   * @param paymentGatewayParams - Params for the selected payment gateway
+   * @param body - Order creation request body
    * @returns Promise with order details
+   * @example
+   * ```typescript
+   * // Example with PayU payment gateway
+   * const { data, error } = await sdk.order.createOrder({
+   *   cart_id: "cart_01H9XYZ12345ABCDE",
+   *   payment_gateway: "PAYU",
+   *   payment_gateway_params: {
+   *     payment_gateway: "PAYU",
+   *     furl: "https://yourapp.com/payment/failure",
+   *     surl: "https://yourapp.com/payment/success"
+   *   }
+   * });
+   *
+   * // Example with Juspay payment gateway
+   * const { data, error } = await sdk.order.createOrder({
+   *   cart_id: "cart_01H9XYZ12345ABCDE",
+   *   payment_gateway: "JUSPAY",
+   *   payment_gateway_params: {
+   *     payment_gateway: "JUSPAY",
+   *     action: "paymentPage",
+   *     integration_type: "hyper-checkout",
+   *     return_url: "https://yourapp.com/payment/return",
+   *     gateway_reference_id: "juspay_gateway_ref_123"
+   *   }
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to create order:", error.message);
+   * } else {
+   *   console.log("Order created:", data.content.order.id);
+   *   console.log("Payment required:", data.content.payment_required);
+   *   console.log("Payment info:", data.content.payment_info);
+   * }
+   * ```
    */
   async createOrder(body) {
     return this.executeRequest(
@@ -2014,8 +3208,35 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * List all orders
    *
-   * @param queryParams - Query parameters
-   * @returns Promise with order details
+   * @param queryParams - Query parameters for filtering and pagination
+   * @returns Promise with order list
+   * @example
+   * ```typescript
+   * // Basic usage - only required parameter
+   * const { data, error } = await sdk.order.listOrders({
+   *   user_id: "user_01H9XYZ12345ABCDE"
+   * });
+   *
+   * // Advanced usage with optional parameters
+   * const { data, error } = await sdk.order.listOrders({
+   *   user_id: "user_01H9XYZ12345ABCDE",
+   *   page: 1,
+   *   limit: 20,
+   *   sort_by: '{"created_at":"desc"}',
+   *   status: ["confirmed", "shipped", "delivered"]
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to list orders:", error.message);
+   * } else {
+   *   console.log("Orders found:", data.content.orders?.length || 0);
+   *   console.log("Pagination:", data.content.pagination);
+   *
+   *   data.content.orders?.forEach(order => {
+   *     console.log(`Order ${order.order_number}: ${order.status}`);
+   *   });
+   * }
+   * ```
    */
   async listOrders(queryParams) {
     return this.executeRequest(
@@ -2031,6 +3252,19 @@ var OrderClient = class extends StorefrontAPIClient {
    *
    * @param orderNumber - Order number
    * @returns Promise with payment status
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.getPaymentStatus("ORD-2024-001");
+   *
+   * if (error) {
+   *   console.error("Failed to get payment status:", error.message);
+   * } else {
+   *   console.log("Payment status:", data.content.status);
+   *   console.log("Amount paid:", data.content.amount_paid);
+   *   console.log("Amount unpaid:", data.content.amount_unpaid);
+   *   console.log("Retry available:", data.content.is_retry_available);
+   * }
+   * ```
    */
   async getPaymentStatus(orderNumber) {
     return this.executeRequest(
@@ -2044,8 +3278,26 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * Get all shipments for an order
    *
-   * @param orderNumber - Order number
+   * @param pathParams - Order number path parameters
    * @returns Promise with shipments
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.listOrderShipments({
+   *   order_number: "ORD-2024-001"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get order shipments:", error.message);
+   * } else {
+   *   console.log("Shipments found:", data.content.shipments?.length || 0);
+   *
+   *   data.content.shipments?.forEach(shipment => {
+   *     console.log(`Shipment ${shipment.id}: ${shipment.status}`);
+   *     console.log("Tracking number:", shipment.tracking_number);
+   *     console.log("Carrier:", shipment.carrier);
+   *   });
+   * }
+   * ```
    */
   async listOrderShipments(pathParams) {
     return this.executeRequest(
@@ -2059,8 +3311,27 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * List order payments
    *
-   * @param orderNumber - Order number
+   * @param pathParams - Order number path parameters
    * @returns Promise with payments
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.listOrderPayments({
+   *   order_number: "ORD-2024-001"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get order payments:", error.message);
+   * } else {
+   *   console.log("Payments found:", data.content.payments?.length || 0);
+   *
+   *   data.content.payments?.forEach(payment => {
+   *     console.log(`Payment ${payment.id}: ${payment.status}`);
+   *     console.log("Amount:", payment.amount);
+   *     console.log("Gateway:", payment.payment_gateway);
+   *     console.log("Transaction ID:", payment.transaction_id);
+   *   });
+   * }
+   * ```
    */
   async listOrderPayments(pathParams) {
     return this.executeRequest(
@@ -2074,8 +3345,27 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * List order refunds
    *
-   * @param orderNumber - Order number
+   * @param pathParams - Order number path parameters
    * @returns Promise with refunds
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.listOrderRefunds({
+   *   order_number: "ORD-2024-001"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get order refunds:", error.message);
+   * } else {
+   *   console.log("Refunds found:", data.content.refunds?.length || 0);
+   *
+   *   data.content.refunds?.forEach(refund => {
+   *     console.log(`Refund ${refund.id}: ${refund.status}`);
+   *     console.log("Amount:", refund.amount);
+   *     console.log("Reason:", refund.reason);
+   *     console.log("Processed at:", refund.processed_at);
+   *   });
+   * }
+   * ```
    */
   async listOrderRefunds(pathParams) {
     return this.executeRequest(
@@ -2089,8 +3379,28 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * Cancel an order
    *
-   * @param orderNumber - Order number
+   * @param pathParams - Order number path parameters
+   * @param body - Cancellation request body
    * @returns Promise with order details
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.order.cancelOrder(
+   *   { order_number: "ORD-2024-001" },
+   *   {
+   *     cancellation_reason: "Customer requested cancellation",
+   *     refund_mode: "original_payment_mode",
+   *     feedback: "Customer changed their mind about the purchase"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to cancel order:", error.message);
+   * } else {
+   *   console.log("Order cancelled successfully");
+   *   console.log("Updated order status:", data.content.order?.status);
+   *   console.log("Cancellation reason:", data.content.order?.cancellation_reason);
+   * }
+   * ```
    */
   async cancelOrder(pathParams, body) {
     return this.executeRequest(
@@ -2105,8 +3415,45 @@ var OrderClient = class extends StorefrontAPIClient {
   /**
    * Retry payment for an order
    *
-   * @param orderNumber - Order number
-   * @returns Promise with order details
+   * @param pathParams - Order number path parameters
+   * @param body - Payment retry request body
+   * @returns Promise with payment information
+   * @example
+   * ```typescript
+   * // Example with PayU payment gateway
+   * const { data, error } = await sdk.order.retryOrderPayment(
+   *   { order_number: "ORD-2024-001" },
+   *   {
+   *     payment_gateway_params: {
+   *       payment_gateway: "PAYU",
+   *       furl: "https://yourapp.com/payment/failure",
+   *       surl: "https://yourapp.com/payment/success"
+   *     }
+   *   }
+   * );
+   *
+   * // Example with Juspay payment gateway
+   * const { data, error } = await sdk.order.retryOrderPayment(
+   *   { order_number: "ORD-2024-001" },
+   *   {
+   *     payment_gateway_params: {
+   *       payment_gateway: "JUSPAY",
+   *       action: "paymentPage",
+   *       integration_type: "hyper-checkout",
+   *       return_url: "https://yourapp.com/payment/return",
+   *       gateway_reference_id: "juspay_gateway_ref_123"
+   *     }
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to retry payment:", error.message);
+   * } else {
+   *   console.log("Payment retry initiated");
+   *   console.log("Payment info:", data.content.payment_info);
+   *   console.log("Transaction ID:", data.content.payment_info.transaction_id);
+   * }
+   * ```
    */
   async retryOrderPayment(pathParams, body) {
     return this.executeRequest(
@@ -2127,6 +3474,31 @@ var ShippingClient = class extends StorefrontAPIClient {
    *
    * @param body - Shipping methods body
    * @returns Promise with shipping options
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.shipping.getShippingMethods({
+   *   delivery_pincode: "400001",
+   *   cart_id: "cart_01H9XYZ12345ABCDE"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get shipping methods:", error.message);
+   * } else {
+   *   console.log("Is serviceable:", data.content.is_serviceable);
+   *   console.log("Available shipping methods:", data.content.shipping_methods?.length || 0);
+   *
+   *   data.content.shipping_methods?.forEach(method => {
+   *     console.log(`Method: ${method.name} (${method.shipping_type})`);
+   *     console.log(`Shipping cost: ${method.shipping_amount}`);
+   *     console.log(`Estimated delivery: ${method.estimated_delivery_days} days`);
+   *
+   *     method.courier_companies?.forEach(courier => {
+   *       console.log(`  - ${courier.name}: ${courier.shipping_amount} (${courier.mode})`);
+   *       console.log(`    Rating: ${courier.rating}/5, Recommended: ${courier.is_recommended}`);
+   *     });
+   *   });
+   * }
+   * ```
    */
   async getShippingMethods(body) {
     return this.executeRequest(
@@ -2140,6 +3512,24 @@ var ShippingClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with pincode deliverability result
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.shipping.checkPincodeDeliverability({
+   *   pincode: "400001"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to check pincode serviceability:", error.message);
+   * } else {
+   *   console.log("Pincode serviceable:", data.content.is_serviceable);
+   *
+   *   if (data.content.is_serviceable) {
+   *     console.log("Delivery is available to this pincode");
+   *   } else {
+   *     console.log("Delivery is not available to this pincode");
+   *   }
+   * }
+   * ```
    */
   async checkPincodeDeliverability(pathParams) {
     return this.executeRequest(
@@ -2158,17 +3548,64 @@ var HelpersClient = class extends StorefrontAPIClient {
    * Get a list of countries
    *
    * @returns Promise with countries
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.helpers.listCountries();
+   *
+   * if (error) {
+   *   console.error("Failed to get countries:", error);
+   *   return;
+   * }
+   *
+   * console.log("Countries found:", data.countries?.length || 0);
+   *
+   * data.countries?.forEach(country => {
+   *   console.log(`Country: ${country.name} (${country.iso_code})`);
+   *   console.log("Phone code:", country.phone_code);
+   *   console.log("Currency:", country.currency?.code);
+   * });
+   * ```
    */
   async listCountries() {
-    return this.executeRequest(
-      () => this.client.GET("/common/countries", {})
-    );
+    return this.executeRequest(() => this.client.GET("/common/countries", {}));
   }
   /**
-   * - Get a list of states for a country
+   * Get a list of states for a country
    *
    * @param pathParams - Path parameters
    * @returns Promise with states
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.helpers.listCountryStates({
+   *   country_iso_code: "IN"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get states:", error);
+   *   return;
+   * }
+   *
+   * console.log("States found:", data.states?.length || 0);
+   *
+   * data.states?.forEach(state => {
+   *   console.log(`State: ${state.name} (${state.iso_code})`);
+   *   console.log("Type:", state.type);
+   * });
+   *
+   * // Get states for different country
+   * const { data: usStates, error: usError } = await sdk.helpers.listCountryStates({
+   *   country_iso_code: "US"
+   * });
+   *
+   * if (usError) {
+   *   console.error("Failed to get US states:", usError);
+   *   return;
+   * }
+   *
+   * console.log("US States:", usStates.states?.map(s => s.name).join(", "));
+   * ```
    */
   async listCountryStates(pathParams) {
     return this.executeRequest(
@@ -2184,6 +3621,38 @@ var HelpersClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with pincodes
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.helpers.listCountryPincodes({
+   *   country_iso_code: "IN"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get pincodes:", error);
+   *   return;
+   * }
+   *
+   * console.log("Pincodes found:", data.pincodes?.length || 0);
+   *
+   * data.pincodes?.forEach(pincode => {
+   *   console.log(`Pincode: ${pincode.pincode} - ${pincode.city}, ${pincode.state}`);
+   *   console.log("District:", pincode.district);
+   *   console.log("Area:", pincode.area);
+   * });
+   *
+   * // Get pincodes for different country
+   * const { data: usPincodes, error: usError } = await sdk.helpers.listCountryPincodes({
+   *   country_iso_code: "US"
+   * });
+   *
+   * if (usError) {
+   *   console.error("Failed to get US pincodes:", usError);
+   *   return;
+   * }
+   *
+   * console.log("US Pincodes:", usPincodes.pincodes?.map(p => p.pincode).join(", "));
+   * ```
    */
   async listCountryPincodes(pathParams) {
     return this.executeRequest(
@@ -2203,6 +3672,24 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param body - Customer creation body
    * @returns Promise with customer details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.createCustomer({
+   *   first_name: "John",
+   *   last_name: "Doe",
+   *   email: "john.doe@example.com",
+   *   phone: "+1234567890",
+   *   password: "securePassword123"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to create customer:", error);
+   *   return;
+   * }
+   *
+   * console.log("Customer created:", data.customer_detail);
+   * ```
    */
   async createCustomer(body) {
     return this.executeRequest(
@@ -2216,6 +3703,20 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with customer details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.getCustomer({
+   *   id: "customer_123"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get customer:", error);
+   *   return;
+   * }
+   *
+   * console.log("Customer details:", data.customer_detail);
+   * ```
    */
   async getCustomer(pathParams) {
     return this.executeRequest(
@@ -2232,6 +3733,25 @@ var CustomerClient = class extends StorefrontAPIClient {
    * @param pathParams - Path parameters
    * @param body - Customer update body
    * @returns Promise with customer details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.updateCustomer(
+   *   { id: "customer_123" },
+   *   {
+   *     first_name: "John",
+   *     last_name: "Smith",
+   *     email: "john.smith@example.com"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update customer:", error);
+   *   return;
+   * }
+   *
+   * console.log("Customer updated:", data.customer_detail);
+   * ```
    */
   async updateCustomer(pathParams, body) {
     return this.executeRequest(
@@ -2248,6 +3768,28 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with addresses
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.listAddresses({
+   *   user_id: "user_456"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to list addresses:", error);
+   *   return;
+   * }
+   *
+   * console.log("Addresses:", data.addresses);
+   * console.log("Pagination:", data.pagination);
+   *
+   * // With pagination
+   * const { data: page2, error: page2Error } = await sdk.customer.listAddresses({
+   *   user_id: "user_456",
+   *   page: 2,
+   *   limit: 10
+   * });
+   * ```
    */
   async listAddresses(pathParams) {
     return this.executeRequest(
@@ -2264,6 +3806,30 @@ var CustomerClient = class extends StorefrontAPIClient {
    * @param pathParams - Path parameters
    * @param body - Address creation body
    * @returns Promise with address details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.createAddress(
+   *   { user_id: "user_456" },
+   *   {
+   *     address_line1: "123 Main Street",
+   *     address_line2: "Apt 4B",
+   *     city: "New York",
+   *     state: "NY",
+   *     country: "US",
+   *     pincode: "10001",
+   *     is_default_billing: true,
+   *     is_default_shipping: false
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to create address:", error);
+   *   return;
+   * }
+   *
+   * console.log("Address created:", data.address);
+   * ```
    */
   async createAddress(pathParams, body) {
     return this.executeRequest(
@@ -2280,6 +3846,21 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with address details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.getAddress({
+   *   user_id: "user_456",
+   *   address_id: "addr_789"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get address:", error);
+   *   return;
+   * }
+   *
+   * console.log("Address details:", data.address);
+   * ```
    */
   async getAddress(pathParams) {
     return this.executeRequest(
@@ -2296,6 +3877,29 @@ var CustomerClient = class extends StorefrontAPIClient {
    * @param pathParams - Path parameters
    * @param body - Address update body
    * @returns Promise with address details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.updateAddress(
+   *   {
+   *     user_id: "user_456",
+   *     address_id: "addr_789"
+   *   },
+   *   {
+   *     address_line1: "456 Oak Avenue",
+   *     city: "Los Angeles",
+   *     state: "CA",
+   *     pincode: "90210"
+   *   }
+   * );
+   *
+   * if (error) {
+   *   console.error("Failed to update address:", error);
+   *   return;
+   * }
+   *
+   * console.log("Address updated:", data.address);
+   * ```
    */
   async updateAddress(pathParams, body) {
     return this.executeRequest(
@@ -2311,7 +3915,22 @@ var CustomerClient = class extends StorefrontAPIClient {
    * Delete an address for a customer
    *
    * @param pathParams - Path parameters
-   * @returns Promise with address details
+   * @returns Promise with deletion response
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.deleteAddress({
+   *   user_id: "user_456",
+   *   address_id: "addr_789"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to delete address:", error);
+   *   return;
+   * }
+   *
+   * console.log("Address deleted:", data.message);
+   * ```
    */
   async deleteAddress(pathParams) {
     return this.executeRequest(
@@ -2327,6 +3946,21 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with loyalty details
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.getLoyaltyDetails({
+   *   user_id: "user_456"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get loyalty details:", error);
+   *   return;
+   * }
+   *
+   * console.log("Loyalty info:", data.loyalty);
+   * console.log("Points balance:", data.loyalty_point_balance);
+   * ```
    */
   async getLoyaltyDetails(pathParams) {
     return this.executeRequest(
@@ -2342,6 +3976,28 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with loyalty points activity
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.listLoyaltyPointsActivity({
+   *   user_id: "user_456"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get loyalty activity:", error);
+   *   return;
+   * }
+   *
+   * console.log("Loyalty activity:", data.loyalty_points_activity);
+   *
+   * // With pagination and sorting
+   * const { data: sortedData, error: sortedError } = await sdk.customer.listLoyaltyPointsActivity({
+   *   user_id: "user_456",
+   *   page: 1,
+   *   limit: 20,
+   *   sort_by: JSON.stringify({ "created_at": "desc" })
+   * });
+   * ```
    */
   async listLoyaltyPointsActivity(pathParams) {
     return this.executeRequest(
@@ -2357,6 +4013,21 @@ var CustomerClient = class extends StorefrontAPIClient {
    *
    * @param pathParams - Path parameters
    * @returns Promise with reviews
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.customer.listCustomerReviews({
+   *   user_id: "user_456"
+   * });
+   *
+   * if (error) {
+   *   console.error("Failed to get customer reviews:", error);
+   *   return;
+   * }
+   *
+   * console.log("Customer reviews:", data.reviews);
+   * console.log("Ready for review:", data.ready_for_review);
+   * ```
    */
   async listCustomerReviews(pathParams) {
     return this.executeRequest(
@@ -2373,6 +4044,25 @@ var CustomerClient = class extends StorefrontAPIClient {
 var StoreConfigClient = class extends StorefrontAPIClient {
   /**
    * Get store config
+   *
+   * @returns Promise with store configuration data
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await sdk.storeConfig.getStoreConfig();
+   *
+   * if (error) {
+   *   console.error('Failed to get store config:', error.message);
+   *   return;
+   * }
+   *
+   * // Access store configuration data
+   * const storeConfig = data.store_config;
+   * console.log('Store brand:', storeConfig.brand.name);
+   * console.log('Currency:', storeConfig.currency.code);
+   * console.log('KYC enabled:', storeConfig.is_kyc_enabled);
+   * console.log('Customer groups enabled:', storeConfig.is_customer_group_enabled);
+   * ```
    */
   async getStoreConfig() {
     return this.executeRequest(() => this.client.GET("/store/config"));
@@ -2611,7 +4301,6 @@ var index_default = StorefrontSDK;
   Environment,
   HelpersClient,
   MemoryTokenStorage,
-  NextJSTokenStorage,
   OrderClient,
   ResponseUtils,
   ShippingClient,