@spree/sdk 0.6.6 → 0.6.8

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ErrorResponse, LoginCredentials, AuthTokens, RegisterParams, StoreStore, ProductListParams, PaginatedResponse, StoreProduct, ProductFiltersParams, ProductFiltersResponse, ListParams, StoreTaxonomy, TaxonListParams, StoreTaxon, StoreCountry, StoreCurrency, StoreLocale, StoreMarket, StoreOrder, CreateCartParams, UpdateOrderParams, AddLineItemParams, UpdateLineItemParams, StorePayment, StorePaymentMethod, CreatePaymentSessionParams, StorePaymentSession, UpdatePaymentSessionParams, CompletePaymentSessionParams, StoreShipment, StoreCustomer, StoreAddress, AddressParams, StoreCreditCard, StoreGiftCard, OrderListParams, CreatePaymentSetupSessionParams, StorePaymentSetupSession, CompletePaymentSetupSessionParams, StoreWishlist, StoreWishedItem } from './types/index.js';
+import { ErrorResponse, LoginCredentials, AuthTokens, RegisterParams, ProductListParams, PaginatedResponse, StoreProduct, ProductFiltersParams, ProductFiltersResponse, ListParams, StoreTaxonomy, TaxonListParams, StoreTaxon, ListResponse, StoreCountry, StoreCurrency, StoreLocale, StoreMarket, StoreOrder, CreateCartParams, UpdateOrderParams, AddLineItemParams, UpdateLineItemParams, StorePayment, StorePaymentMethod, CreatePaymentSessionParams, StorePaymentSession, UpdatePaymentSessionParams, CompletePaymentSessionParams, StoreShipment, StoreCustomer, StoreAddress, AddressParams, StoreCreditCard, StoreGiftCard, OrderListParams, CreatePaymentSetupSessionParams, StorePaymentSetupSession, CompletePaymentSetupSessionParams, StoreWishlist, StoreWishedItem } from './types/index.js';
 export { AdminCustomer, AdminLineItem, AdminMetafield, AdminOrder, AdminPrice, AdminProduct, AdminTaxon, AdminTaxonomy, AdminVariant, AvailabilityFilter, FilterOption, LocaleDefaults, OptionFilter, OptionFilterOption, PaginationMeta, PriceRangeFilter, ProductFilter, SortOption, StoreAsset, StoreBase, StoreCustomerReturn, StoreDigital, StoreDigitalLink, StoreExport, StoreGiftCardBatch, StoreImage, StoreImport, StoreImportRow, StoreInvitation, StoreLineItem, StoreMetafield, StoreNewsletterSubscriber, StoreOptionType, StoreOptionValue, StoreOrderPromotion, StorePaymentSource, StorePrice, StorePromotion, StoreRefund, StoreReimbursement, StoreReport, StoreReturnAuthorization, StoreReturnItem, StoreShippingMethod, StoreShippingRate, StoreState, StoreStockItem, StoreStockLocation, StoreStockMovement, StoreStockTransfer, StoreStoreCredit, StoreVariant, TaxonFilter, TaxonFilterOption } from './types/index.js';
 
 interface RetryConfig {
@@ -24,6 +24,8 @@ interface RequestOptions {
     currency?: string;
     /** Country ISO code for market resolution (e.g., 'US', 'DE') */
     country?: string;
+    /** Idempotency key for safe retries of mutating requests (max 255 characters) */
+    idempotencyKey?: string;
     /** Custom headers */
     headers?: Record<string, string>;
 }
@@ -56,12 +58,6 @@ declare class StoreClient {
          */
         refresh: (options: RequestOptions) => Promise<AuthTokens>;
     };
-    readonly store: {
-        /**
-         * Get current store information
-         */
-        get: (options?: RequestOptions) => Promise<StoreStore>;
-    };
     readonly products: {
         /**
          * List products
@@ -71,7 +67,7 @@ declare class StoreClient {
          * Get a product by ID or slug
          */
         get: (idOrSlug: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreProduct>;
         /**
          * Get available filters for products
@@ -88,7 +84,7 @@ declare class StoreClient {
          * Get a taxonomy by ID
          */
         get: (id: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreTaxonomy>;
     };
     readonly taxons: {
@@ -100,7 +96,7 @@ declare class StoreClient {
          * Get a taxon by ID or permalink
          */
         get: (idOrPermalink: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreTaxon>;
         /**
          * Nested resource: Products in a taxon
@@ -118,41 +114,33 @@ declare class StoreClient {
          * List countries available in the store
          * Each country includes currency and default_locale derived from its market
          */
-        list: (options?: RequestOptions) => Promise<{
-            data: StoreCountry[];
-        }>;
+        list: (options?: RequestOptions) => Promise<ListResponse<StoreCountry>>;
         /**
          * Get a country by ISO code
          * Use `?expand=states` to expand states for address forms
          * @param iso - ISO 3166-1 alpha-2 code (e.g., "US", "DE")
          */
         get: (iso: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreCountry>;
     };
     readonly currencies: {
         /**
          * List currencies supported by the store (derived from markets)
          */
-        list: (options?: RequestOptions) => Promise<{
-            data: StoreCurrency[];
-        }>;
+        list: (options?: RequestOptions) => Promise<ListResponse<StoreCurrency>>;
     };
     readonly locales: {
         /**
          * List locales supported by the store (derived from markets)
          */
-        list: (options?: RequestOptions) => Promise<{
-            data: StoreLocale[];
-        }>;
+        list: (options?: RequestOptions) => Promise<ListResponse<StoreLocale>>;
     };
     readonly markets: {
         /**
          * List all markets for the current store
          */
-        list: (options?: RequestOptions) => Promise<{
-            data: StoreMarket[];
-        }>;
+        list: (options?: RequestOptions) => Promise<ListResponse<StoreMarket>>;
         /**
          * Get a market by prefixed ID
          * @param id - Market prefixed ID (e.g., "mkt_k5nR8xLq")
@@ -171,16 +159,14 @@ declare class StoreClient {
              * List countries belonging to a market
              * @param marketId - Market prefixed ID
              */
-            list: (marketId: string, options?: RequestOptions) => Promise<{
-                data: StoreCountry[];
-            }>;
+            list: (marketId: string, options?: RequestOptions) => Promise<ListResponse<StoreCountry>>;
             /**
              * Get a country by ISO code within a market
              * @param marketId - Market prefixed ID
              * @param iso - Country ISO code (e.g., "DE")
              */
             get: (marketId: string, iso: string, params?: {
-                expand?: string;
+                expand?: string[];
             }, options?: RequestOptions) => Promise<StoreCountry>;
         };
     };
@@ -213,7 +199,7 @@ declare class StoreClient {
          * Get an order by ID or number
          */
         get: (idOrNumber: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreOrder>;
         /**
          * Update an order
@@ -266,10 +252,7 @@ declare class StoreClient {
             /**
              * List payments for an order
              */
-            list: (orderId: string, options?: RequestOptions) => Promise<{
-                data: StorePayment[];
-                meta: object;
-            }>;
+            list: (orderId: string, options?: RequestOptions) => Promise<PaginatedResponse<StorePayment>>;
             /**
              * Get a payment by ID
              */
@@ -282,7 +265,7 @@ declare class StoreClient {
             /**
              * List available payment methods for an order
              */
-            list: (orderId: string, options?: RequestOptions) => Promise<PaginatedResponse<StorePaymentMethod>>;
+            list: (orderId: string, options?: RequestOptions) => Promise<ListResponse<StorePaymentMethod>>;
         };
         /**
          * Nested resource: Payment sessions
@@ -329,9 +312,7 @@ declare class StoreClient {
             /**
              * List shipments for an order
              */
-            list: (orderId: string, options?: RequestOptions) => Promise<{
-                data: StoreShipment[];
-            }>;
+            list: (orderId: string, options?: RequestOptions) => Promise<ListResponse<StoreShipment>>;
             /**
              * Select a shipping rate for a shipment.
              * Returns the updated order with recalculated totals.
@@ -456,7 +437,7 @@ declare class StoreClient {
          * Get a wishlist by ID
          */
         get: (id: string, params?: {
-            expand?: string;
+            expand?: string[];
         }, options?: RequestOptions) => Promise<StoreWishlist>;
         /**
          * Create a wishlist
@@ -512,8 +493,8 @@ declare class AdminClient {
 interface SpreeClientConfig {
     /** Base URL of the Spree API (e.g., 'https://api.mystore.com') */
     baseUrl: string;
-    /** Publishable API key for Store API access */
-    publishableKey: string;
+    /** Publishable API key for Store API access (required for Store API) */
+    publishableKey?: string;
     /** Secret API key for Admin API access (optional) */
     secretKey?: string;
     /** Custom fetch implementation (optional, defaults to global fetch) */
@@ -546,4 +527,4 @@ declare class SpreeClient {
  */
 declare function createSpreeClient(config: SpreeClientConfig): SpreeClient;
 
-export { AddLineItemParams, AddressParams, AdminClient, AuthTokens, CompletePaymentSessionParams, CompletePaymentSetupSessionParams, CreateCartParams, CreatePaymentSessionParams, CreatePaymentSetupSessionParams, ErrorResponse, ListParams, LoginCredentials, OrderListParams, PaginatedResponse, ProductFiltersParams, ProductFiltersResponse, ProductListParams, RegisterParams, type RequestOptions, type RetryConfig, SpreeClient, type SpreeClientConfig, SpreeError, StoreAddress, StoreClient, StoreCountry, StoreCreditCard, StoreCurrency, StoreCustomer, StoreGiftCard, StoreLocale, StoreMarket, StoreOrder, StorePayment, StorePaymentMethod, StorePaymentSession, StorePaymentSetupSession, StoreProduct, StoreShipment, StoreStore, StoreTaxon, StoreTaxonomy, StoreWishedItem, StoreWishlist, TaxonListParams, UpdateLineItemParams, UpdateOrderParams, UpdatePaymentSessionParams, createSpreeClient };
+export { AddLineItemParams, AddressParams, AdminClient, AuthTokens, CompletePaymentSessionParams, CompletePaymentSetupSessionParams, CreateCartParams, CreatePaymentSessionParams, CreatePaymentSetupSessionParams, ErrorResponse, ListParams, ListResponse, LoginCredentials, OrderListParams, PaginatedResponse, ProductFiltersParams, ProductFiltersResponse, ProductListParams, RegisterParams, type RequestOptions, type RetryConfig, SpreeClient, type SpreeClientConfig, SpreeError, StoreAddress, StoreClient, StoreCountry, StoreCreditCard, StoreCurrency, StoreCustomer, StoreGiftCard, StoreLocale, StoreMarket, StoreOrder, StorePayment, StorePaymentMethod, StorePaymentSession, StorePaymentSetupSession, StoreProduct, StoreShipment, StoreTaxon, StoreTaxonomy, StoreWishedItem, StoreWishlist, TaxonListParams, UpdateLineItemParams, UpdateOrderParams, UpdatePaymentSessionParams, createSpreeClient };

package/dist/index.js

@@ -19,20 +19,23 @@ function calculateDelay(attempt, config) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function shouldRetryOnStatus(method, status, config) {
-  const isIdempotent = method === "GET" || method === "HEAD";
+function generateIdempotencyKey() {
+  return `spree-sdk-retry-${crypto.randomUUID()}`;
+}
+function shouldRetryOnStatus(method, status, config, hasIdempotencyKey) {
+  const isIdempotent = method === "GET" || method === "HEAD" || hasIdempotencyKey;
   if (isIdempotent) {
     return config.retryOnStatus.includes(status);
   }
   return status === 429;
 }
-function shouldRetryOnNetworkError(method, config) {
+function shouldRetryOnNetworkError(method, config, hasIdempotencyKey) {
   if (!config.retryOnNetworkError) return false;
-  return method === "GET" || method === "HEAD";
+  return method === "GET" || method === "HEAD" || hasIdempotencyKey;
 }
 function createRequestFn(config, basePath, auth, defaults) {
   return async function request(method, path, options = {}) {
-    const { token, orderToken, headers = {}, body, params } = options;
+    const { token, orderToken, idempotencyKey, headers = {}, body, params } = options;
     const locale = options.locale ?? defaults?.locale;
     const currency = options.currency ?? defaults?.currency;
     const country = options.country ?? defaults?.country;
@@ -48,14 +51,13 @@ function createRequestFn(config, basePath, auth, defaults) {
         }
       });
     }
-    if (orderToken) {
-      url.searchParams.set("order_token", orderToken);
-    }
     const requestHeaders = {
       "Content-Type": "application/json",
-      [auth.headerName]: auth.headerValue,
       ...headers
     };
+    if (auth.headerName && auth.headerValue) {
+      requestHeaders[auth.headerName] = auth.headerValue;
+    }
     if (token) {
       requestHeaders["Authorization"] = `Bearer ${token}`;
     }
@@ -71,6 +73,12 @@ function createRequestFn(config, basePath, auth, defaults) {
     if (country) {
       requestHeaders["x-spree-country"] = country;
     }
+    const isMutating = method !== "GET" && method !== "HEAD";
+    const effectiveIdempotencyKey = idempotencyKey ?? (isMutating && config.retryConfig ? generateIdempotencyKey() : void 0);
+    if (effectiveIdempotencyKey) {
+      requestHeaders["Idempotency-Key"] = effectiveIdempotencyKey;
+    }
+    const hasIdempotencyKey = !!effectiveIdempotencyKey;
     const maxAttempts = config.retryConfig ? config.retryConfig.maxRetries + 1 : 1;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       try {
@@ -81,7 +89,7 @@ function createRequestFn(config, basePath, auth, defaults) {
         });
         if (!response.ok) {
           const isLastAttempt = attempt >= maxAttempts - 1;
-          if (!isLastAttempt && config.retryConfig && shouldRetryOnStatus(method, response.status, config.retryConfig)) {
+          if (!isLastAttempt && config.retryConfig && shouldRetryOnStatus(method, response.status, config.retryConfig, hasIdempotencyKey)) {
             const retryAfter = response.headers.get("Retry-After");
             const delay = retryAfter ? Math.min(parseInt(retryAfter, 10) * 1e3, config.retryConfig.maxDelay) : calculateDelay(attempt, config.retryConfig);
             await sleep(delay);
@@ -99,7 +107,7 @@ function createRequestFn(config, basePath, auth, defaults) {
           throw error;
         }
         const isLastAttempt = attempt >= maxAttempts - 1;
-        if (!isLastAttempt && config.retryConfig && shouldRetryOnNetworkError(method, config.retryConfig)) {
+        if (!isLastAttempt && config.retryConfig && shouldRetryOnNetworkError(method, config.retryConfig, hasIdempotencyKey)) {
           const delay = calculateDelay(attempt, config.retryConfig);
           await sleep(delay);
           continue;
@@ -136,6 +144,10 @@ function transformListParams(params) {
 }
 
 // src/store-client.ts
+function expandParams(params) {
+  if (!params?.expand?.length) return void 0;
+  return { expand: params.expand.join(",") };
+}
 var StoreClient = class {
   request;
   constructor(request) {
@@ -159,15 +171,6 @@ var StoreClient = class {
     refresh: (options) => this.request("POST", "/auth/refresh", options)
   };
   // ============================================
-  // Store
-  // ============================================
-  store = {
-    /**
-     * Get current store information
-     */
-    get: (options) => this.request("GET", "/store", options)
-  };
-  // ============================================
   // Products
   // ============================================
   products = {
@@ -176,14 +179,14 @@ var StoreClient = class {
      */
     list: (params, options) => this.request("GET", "/products", {
       ...options,
-      params: params ? transformListParams(params) : void 0
+      params: transformListParams({ ...params })
     }),
     /**
      * Get a product by ID or slug
      */
     get: (idOrSlug, params, options) => this.request("GET", `/products/${idOrSlug}`, {
       ...options,
-      params
+      params: expandParams(params)
     }),
     /**
      * Get available filters for products
@@ -203,14 +206,14 @@ var StoreClient = class {
      */
     list: (params, options) => this.request("GET", "/taxonomies", {
       ...options,
-      params
+      params: transformListParams({ ...params })
     }),
     /**
      * Get a taxonomy by ID
      */
     get: (id, params, options) => this.request("GET", `/taxonomies/${id}`, {
       ...options,
-      params
+      params: expandParams(params)
     })
   };
   taxons = {
@@ -219,14 +222,14 @@ var StoreClient = class {
      */
     list: (params, options) => this.request("GET", "/taxons", {
       ...options,
-      params: params ? transformListParams(params) : void 0
+      params: transformListParams({ ...params })
     }),
     /**
      * Get a taxon by ID or permalink
      */
     get: (idOrPermalink, params, options) => this.request("GET", `/taxons/${idOrPermalink}`, {
       ...options,
-      params
+      params: expandParams(params)
     }),
     /**
      * Nested resource: Products in a taxon
@@ -241,7 +244,7 @@ var StoreClient = class {
         `/taxons/${taxonId}/products`,
         {
           ...options,
-          params: params ? transformListParams(params) : void 0
+          params: transformListParams({ ...params })
         }
       )
     }
@@ -262,7 +265,7 @@ var StoreClient = class {
      */
     get: (iso, params, options) => this.request("GET", `/countries/${iso}`, {
       ...options,
-      params
+      params: expandParams(params)
     })
   };
   currencies = {
@@ -319,7 +322,7 @@ var StoreClient = class {
       get: (marketId, iso, params, options) => this.request(
         "GET",
         `/markets/${marketId}/countries/${iso}`,
-        { ...options, params }
+        { ...options, params: expandParams(params) }
       )
     }
   };
@@ -356,7 +359,7 @@ var StoreClient = class {
      */
     get: (idOrNumber, params, options) => this.request("GET", `/orders/${idOrNumber}`, {
       ...options,
-      params
+      params: expandParams(params)
     }),
     /**
      * Update an order
@@ -574,7 +577,7 @@ var StoreClient = class {
       list: (params, options) => this.request(
         "GET",
         "/customer/addresses",
-        { ...options, params }
+        { ...options, params: transformListParams({ ...params }) }
       ),
       /**
        * Get an address by ID
@@ -616,7 +619,7 @@ var StoreClient = class {
       list: (params, options) => this.request(
         "GET",
         "/customer/credit_cards",
-        { ...options, params }
+        { ...options, params: transformListParams({ ...params }) }
       ),
       /**
        * Get a credit card by ID
@@ -638,7 +641,7 @@ var StoreClient = class {
       list: (params, options) => this.request(
         "GET",
         "/customer/gift_cards",
-        { ...options, params }
+        { ...options, params: transformListParams({ ...params }) }
       ),
       /**
        * Get a gift card by ID
@@ -654,7 +657,7 @@ var StoreClient = class {
        */
       list: (params, options) => this.request("GET", "/customer/orders", {
         ...options,
-        params: params ? transformListParams(params) : void 0
+        params: transformListParams({ ...params })
       })
     },
     /**
@@ -694,14 +697,14 @@ var StoreClient = class {
      */
     list: (params, options) => this.request("GET", "/wishlists", {
       ...options,
-      params
+      params: transformListParams({ ...params })
     }),
     /**
      * Get a wishlist by ID
      */
     get: (id, params, options) => this.request("GET", `/wishlists/${id}`, {
       ...options,
-      params
+      params: expandParams(params)
     }),
     /**
      * Create a wishlist
@@ -770,6 +773,9 @@ var SpreeClient = class {
   admin;
   _defaults;
   constructor(config) {
+    if (!config.publishableKey && !config.secretKey) {
+      throw new Error("SpreeClient requires at least one of publishableKey or secretKey");
+    }
     const baseUrl = config.baseUrl.replace(/\/$/, "");
     const fetchFn = config.fetch || fetch.bind(globalThis);
     this._defaults = {
@@ -793,7 +799,7 @@ var SpreeClient = class {
     const storeRequestFn = createRequestFn(
       requestConfig,
       "/api/v3/store",
-      { headerName: "x-spree-api-key", headerValue: config.publishableKey },
+      config.publishableKey ? { headerName: "x-spree-api-key", headerValue: config.publishableKey } : { headerName: "", headerValue: "" },
       this._defaults
     );
     const adminRequestFn = createRequestFn(