brainerce 1.27.1 → 1.28.1

package/dist/index.js

@@ -37,7 +37,10 @@ __export(index_exports, {
   createWebhookHandler: () => createWebhookHandler,
   deriveSeoDescription: () => deriveSeoDescription,
   enableDevGuards: () => enableDevGuards,
+  formatMoney: () => formatMoney,
   formatPrice: () => formatPrice,
+  formatProductPrice: () => formatProductPrice,
+  formatVariantPrice: () => formatVariantPrice,
   getCartItemImage: () => getCartItemImage,
   getCartItemName: () => getCartItemName,
   getCartTotals: () => getCartTotals,
@@ -202,6 +205,26 @@ function encodePathSegment(value) {
   }
   return encodeURIComponent(normalized);
 }
+var MAX_RETRY_AFTER_MS = 6e4;
+function parseRetryAfterMs(response) {
+  const header = response.headers.get("retry-after");
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (!trimmed) return null;
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = parseInt(trimmed, 10);
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS);
+  }
+  const target = Date.parse(trimmed);
+  if (Number.isNaN(target)) return null;
+  const deltaMs = target - Date.now();
+  if (deltaMs <= 0) return 0;
+  return Math.min(deltaMs, MAX_RETRY_AFTER_MS);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var BrainerceClient = class {
   constructor(options) {
     this.customerToken = null;
@@ -635,7 +658,7 @@ var BrainerceClient = class {
   /**
    * Make a request to the Admin API (requires apiKey)
    */
-  async adminRequest(method, path, body, queryParams) {
+  async adminRequest(method, path, body, queryParams, responseType = "json") {
     if (!this.apiKey) {
       throw new BrainerceError(
         "This operation requires an API key. Initialize with apiKey instead of storeId.",
@@ -650,52 +673,64 @@ var BrainerceClient = class {
         }
       });
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const headers = {
-        Authorization: `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-        "X-SDK-Version": SDK_VERSION,
-        "ngrok-skip-browser-warning": "true"
-      };
-      if (this.origin) {
-        headers["Origin"] = this.origin;
-      }
-      if (this.locale) {
-        headers["Accept-Language"] = this.locale;
-      }
-      const response = await fetch(url.toString(), {
-        method,
-        headers,
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new BrainerceError(
-          errorData.message || `Request failed with status ${response.status}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return {};
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof BrainerceError) {
-        throw error;
-      }
-      if (error instanceof Error) {
-        if (error.name === "AbortError") {
-          throw new BrainerceError("Request timeout", 408);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "X-SDK-Version": SDK_VERSION,
+      "ngrok-skip-browser-warning": "true"
+    };
+    if (this.origin) {
+      headers["Origin"] = this.origin;
+    }
+    if (this.locale) {
+      headers["Accept-Language"] = this.locale;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url.toString(), {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.status === 429 && attempt === 0) {
+          const retryAfterMs = parseRetryAfterMs(response);
+          if (retryAfterMs !== null) {
+            await response.text().catch(() => void 0);
+            await sleep(retryAfterMs);
+            continue;
+          }
         }
-        throw new BrainerceError(error.message, 0);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          throw new BrainerceError(
+            errorData.message || `Request failed with status ${response.status}`,
+            response.status,
+            errorData
+          );
+        }
+        const text = await response.text();
+        if (responseType === "text") return text;
+        if (!text) return {};
+        return JSON.parse(text);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof BrainerceError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new BrainerceError("Request timeout", 408);
+          }
+          throw new BrainerceError(error.message, 0);
+        }
+        throw new BrainerceError("Unknown error occurred", 0);
       }
-      throw new BrainerceError("Unknown error occurred", 0);
     }
+    throw new BrainerceError("Rate limited (max retries exceeded)", 429);
   }
   /**
    * Make a request to the Vibe-Coded API (public, uses connectionId)
@@ -704,7 +739,7 @@ var BrainerceClient = class {
     if (!this.connectionId) {
       throw new BrainerceError("connectionId is required for vibe-coded requests", 400);
     }
-    const url = new URL(`${this.baseUrl}/api/vc/${this.connectionId}${path}`);
+    const url = new URL(`${this.baseUrl}/api/vc/${encodePathSegment(this.connectionId)}${path}`);
     if (queryParams) {
       Object.entries(queryParams).forEach(([key, value]) => {
         if (value !== void 0) {
@@ -712,70 +747,81 @@ var BrainerceClient = class {
         }
       });
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
-      const headers = {
-        "X-SDK-Version": SDK_VERSION,
-        "ngrok-skip-browser-warning": "true"
-      };
-      if (!isFormData) {
-        headers["Content-Type"] = "application/json";
-      }
-      if (this.origin) {
-        headers["Origin"] = this.origin;
-      }
-      if (this.locale) {
-        headers["Accept-Language"] = this.locale;
-      }
-      if (headerOverrides) {
-        Object.assign(headers, headerOverrides);
-      }
-      if (this.proxyMode && method !== "GET") {
-        headers["X-Requested-With"] = "brainerce";
-      }
-      if (this.customerToken) {
-        headers["Authorization"] = `Bearer ${this.customerToken}`;
-      }
-      const response = await fetch(url.toString(), {
-        method,
-        headers,
-        body: body ? isFormData ? body : JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        if (response.status === 401 && this.onAuthError) {
-          this.onAuthError({
-            message: errorData.message || "Unauthorized",
-            statusCode: 401,
-            path
-          });
+    const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
+    const headers = {
+      "X-SDK-Version": SDK_VERSION,
+      "ngrok-skip-browser-warning": "true"
+    };
+    if (!isFormData) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (this.origin) {
+      headers["Origin"] = this.origin;
+    }
+    if (this.locale) {
+      headers["Accept-Language"] = this.locale;
+    }
+    if (headerOverrides) {
+      Object.assign(headers, headerOverrides);
+    }
+    if (this.proxyMode && method !== "GET") {
+      headers["X-Requested-With"] = "brainerce";
+    }
+    if (this.customerToken) {
+      headers["Authorization"] = `Bearer ${this.customerToken}`;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url.toString(), {
+          method,
+          headers,
+          body: body ? isFormData ? body : JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.status === 429 && attempt === 0) {
+          const retryAfterMs = parseRetryAfterMs(response);
+          if (retryAfterMs !== null) {
+            await response.text().catch(() => void 0);
+            await sleep(retryAfterMs);
+            continue;
+          }
         }
-        throw new BrainerceError(
-          errorData.message || `Request failed with status ${response.status}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return {};
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof BrainerceError) {
-        throw error;
-      }
-      if (error instanceof Error) {
-        if (error.name === "AbortError") {
-          throw new BrainerceError("Request timeout", 408);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          if (response.status === 401 && this.onAuthError) {
+            this.onAuthError({
+              message: errorData.message || "Unauthorized",
+              statusCode: 401,
+              path
+            });
+          }
+          throw new BrainerceError(
+            errorData.message || `Request failed with status ${response.status}`,
+            response.status,
+            errorData
+          );
         }
-        throw new BrainerceError(error.message, 0);
+        const text = await response.text();
+        if (!text) return {};
+        return JSON.parse(text);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof BrainerceError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new BrainerceError("Request timeout", 408);
+          }
+          throw new BrainerceError(error.message, 0);
+        }
+        throw new BrainerceError("Unknown error occurred", 0);
       }
-      throw new BrainerceError("Unknown error occurred", 0);
     }
+    throw new BrainerceError("Rate limited (max retries exceeded)", 429);
   }
   /**
    * Make a request to the Storefront API (public, uses storeId)
@@ -784,7 +830,7 @@ var BrainerceClient = class {
     if (!this.storeId) {
       throw new BrainerceError("storeId is required for storefront requests", 400);
     }
-    const url = new URL(`${this.baseUrl}/stores/${this.storeId}${path}`);
+    const url = new URL(`${this.baseUrl}/stores/${encodePathSegment(this.storeId)}${path}`);
     if (queryParams) {
       Object.entries(queryParams).forEach(([key, value]) => {
         if (value !== void 0) {
@@ -792,67 +838,78 @@ var BrainerceClient = class {
         }
       });
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
-      const headers = {
-        "X-SDK-Version": SDK_VERSION,
-        "ngrok-skip-browser-warning": "true"
-      };
-      if (!isFormData) {
-        headers["Content-Type"] = "application/json";
-      }
-      if (this.origin) {
-        headers["Origin"] = this.origin;
-      }
-      if (this.locale) {
-        headers["Accept-Language"] = this.locale;
-      }
-      if (headerOverrides) {
-        Object.assign(headers, headerOverrides);
-      }
-      if (this.customerToken) {
-        headers["Authorization"] = `Bearer ${this.customerToken}`;
-      }
-      const response = await fetch(url.toString(), {
-        method,
-        headers,
-        body: body ? isFormData ? body : JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        if (response.status === 401 && this.onAuthError) {
-          this.onAuthError({
-            message: errorData.message || "Unauthorized",
-            statusCode: 401,
-            path
-          });
+    const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
+    const headers = {
+      "X-SDK-Version": SDK_VERSION,
+      "ngrok-skip-browser-warning": "true"
+    };
+    if (!isFormData) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (this.origin) {
+      headers["Origin"] = this.origin;
+    }
+    if (this.locale) {
+      headers["Accept-Language"] = this.locale;
+    }
+    if (headerOverrides) {
+      Object.assign(headers, headerOverrides);
+    }
+    if (this.customerToken) {
+      headers["Authorization"] = `Bearer ${this.customerToken}`;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url.toString(), {
+          method,
+          headers,
+          body: body ? isFormData ? body : JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.status === 429 && attempt === 0) {
+          const retryAfterMs = parseRetryAfterMs(response);
+          if (retryAfterMs !== null) {
+            await response.text().catch(() => void 0);
+            await sleep(retryAfterMs);
+            continue;
+          }
         }
-        throw new BrainerceError(
-          errorData.message || `Request failed with status ${response.status}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return {};
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof BrainerceError) {
-        throw error;
-      }
-      if (error instanceof Error) {
-        if (error.name === "AbortError") {
-          throw new BrainerceError("Request timeout", 408);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          if (response.status === 401 && this.onAuthError) {
+            this.onAuthError({
+              message: errorData.message || "Unauthorized",
+              statusCode: 401,
+              path
+            });
+          }
+          throw new BrainerceError(
+            errorData.message || `Request failed with status ${response.status}`,
+            response.status,
+            errorData
+          );
         }
-        throw new BrainerceError(error.message, 0);
+        const text = await response.text();
+        if (!text) return {};
+        return JSON.parse(text);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof BrainerceError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new BrainerceError("Request timeout", 408);
+          }
+          throw new BrainerceError(error.message, 0);
+        }
+        throw new BrainerceError("Unknown error occurred", 0);
       }
-      throw new BrainerceError("Unknown error occurred", 0);
     }
+    throw new BrainerceError("Rate limited (max retries exceeded)", 429);
   }
   /**
    * Smart request - uses storefront or admin API based on client mode
@@ -942,6 +999,7 @@ var BrainerceClient = class {
       // Admin-only params
       type: params?.type
     };
+    const queryParamsWithRegion = params?.regionId ? { ...queryParams, regionId: params.regionId } : queryParams;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -955,14 +1013,14 @@ var BrainerceClient = class {
         "GET",
         "/products",
         void 0,
-        queryParams
+        queryParamsWithRegion
       );
     }
     return this.adminRequest(
       "GET",
       "/api/v1/products",
       void 0,
-      queryParams
+      queryParamsWithRegion
     );
   }
   /**
@@ -971,10 +1029,11 @@ var BrainerceClient = class {
    */
   async getProduct(productId, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const queryParams = options?.regionId ? { regionId: options.regionId } : void 0;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}`,
+        `/products/${encodePathSegment(productId)}`,
         void 0,
         void 0,
         headerOverrides
@@ -983,13 +1042,18 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}`,
-        void 0,
+        `/products/${encodePathSegment(productId)}`,
         void 0,
+        queryParams,
         headerOverrides
       );
     }
-    return this.adminRequest("GET", `/api/v1/products/${productId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/${encodePathSegment(productId)}`,
+      void 0,
+      queryParams
+    );
   }
   /**
    * Get a single product by slug
@@ -1107,7 +1171,7 @@ var BrainerceClient = class {
    */
   async getProductAlternates(productId) {
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/${productId}/alternates`);
+      return this.storefrontRequest("GET", `/products/${encodePathSegment(productId)}/alternates`);
     }
     throw new BrainerceError("getProductAlternates is only available in storefront mode", 400);
   }
@@ -1149,7 +1213,7 @@ var BrainerceClient = class {
    * Update an existing product
    */
   async updateProduct(productId, data) {
-    return this.request("PATCH", `/api/v1/products/${productId}`, data);
+    return this.request("PATCH", `/api/v1/products/${encodePathSegment(productId)}`, data);
   }
   /**
    * Delete a product
@@ -1177,7 +1241,7 @@ var BrainerceClient = class {
     const queryParams = options?.platforms?.length ? { platforms: options.platforms.join(",") } : void 0;
     return this.request(
       "DELETE",
-      `/api/v1/products/${productId}`,
+      `/api/v1/products/${encodePathSegment(productId)}`,
       void 0,
       queryParams
     );
@@ -1192,7 +1256,10 @@ var BrainerceClient = class {
    * ```
    */
   async convertToVariable(productId) {
-    return this.request("PATCH", `/api/v1/products/${productId}/convert-to-variable`);
+    return this.request(
+      "PATCH",
+      `/api/v1/products/${encodePathSegment(productId)}/convert-to-variable`
+    );
   }
   /**
    * Convert a VARIABLE product to SIMPLE product
@@ -1205,7 +1272,10 @@ var BrainerceClient = class {
    * ```
    */
   async convertToSimple(productId) {
-    return this.request("PATCH", `/api/v1/products/${productId}/convert-to-simple`);
+    return this.request(
+      "PATCH",
+      `/api/v1/products/${encodePathSegment(productId)}/convert-to-simple`
+    );
   }
   /**
    * Publish a product to specific platforms
@@ -1217,9 +1287,13 @@ var BrainerceClient = class {
    * ```
    */
   async publishProduct(productId, platforms) {
-    return this.request("POST", `/api/v1/products/${productId}/publish`, {
-      platforms
-    });
+    return this.request(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/publish`,
+      {
+        platforms
+      }
+    );
   }
   // -------------------- Variants --------------------
   /**
@@ -1237,7 +1311,11 @@ var BrainerceClient = class {
    * ```
    */
   async createVariant(productId, data) {
-    return this.request("POST", `/api/v1/products/${productId}/variants`, data);
+    return this.request(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/variants`,
+      data
+    );
   }
   /**
    * Bulk save variants (create, update, delete in one operation)
@@ -1257,7 +1335,7 @@ var BrainerceClient = class {
   async bulkSaveVariants(productId, data) {
     return this.request(
       "POST",
-      `/api/v1/products/${productId}/variants/bulk`,
+      `/api/v1/products/${encodePathSegment(productId)}/variants/bulk`,
       data
     );
   }
@@ -1275,7 +1353,7 @@ var BrainerceClient = class {
   async updateVariant(productId, variantId, data) {
     return this.request(
       "PATCH",
-      `/api/v1/products/${productId}/variants/${variantId}`,
+      `/api/v1/products/${encodePathSegment(productId)}/variants/${encodePathSegment(variantId)}`,
       data
     );
   }
@@ -1288,7 +1366,10 @@ var BrainerceClient = class {
    * ```
    */
   async deleteVariant(productId, variantId) {
-    await this.request("DELETE", `/api/v1/products/${productId}/variants/${variantId}`);
+    await this.request(
+      "DELETE",
+      `/api/v1/products/${encodePathSegment(productId)}/variants/${encodePathSegment(variantId)}`
+    );
   }
   /**
    * Get inventory for a specific variant
@@ -1302,7 +1383,7 @@ var BrainerceClient = class {
   async getVariantInventory(productId, variantId) {
     return this.request(
       "GET",
-      `/api/v1/products/${productId}/variants/${variantId}/inventory`
+      `/api/v1/products/${encodePathSegment(productId)}/variants/${encodePathSegment(variantId)}/inventory`
     );
   }
   /**
@@ -1319,7 +1400,7 @@ var BrainerceClient = class {
   async updateVariantInventory(productId, variantId, data) {
     return this.request(
       "PATCH",
-      `/api/v1/products/${productId}/variants/${variantId}/inventory`,
+      `/api/v1/products/${encodePathSegment(productId)}/variants/${encodePathSegment(variantId)}/inventory`,
       data
     );
   }
@@ -1343,7 +1424,10 @@ var BrainerceClient = class {
    * Get a single order by ID
    */
   async getOrder(orderId) {
-    return this.withGuards(this.request("GET", `/api/v1/orders/${orderId}`), "order");
+    return this.withGuards(
+      this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}`),
+      "order"
+    );
   }
   /**
    * Create a new order
@@ -1356,7 +1440,7 @@ var BrainerceClient = class {
    * Update an order (e.g., change status)
    */
   async updateOrder(orderId, data) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}`, data);
+    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}`, data);
   }
   /**
    * Update order status
@@ -1367,7 +1451,9 @@ var BrainerceClient = class {
    * ```
    */
   async updateOrderStatus(orderId, status) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}/status`, { status });
+    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/status`, {
+      status
+    });
   }
   /**
    * Update order payment method
@@ -1379,9 +1465,13 @@ var BrainerceClient = class {
    * ```
    */
   async updatePaymentMethod(orderId, paymentMethod) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}/payment-method`, {
-      paymentMethod
-    });
+    return this.request(
+      "PATCH",
+      `/api/v1/orders/${encodePathSegment(orderId)}/payment-method`,
+      {
+        paymentMethod
+      }
+    );
   }
   /**
    * Update order notes
@@ -1392,7 +1482,9 @@ var BrainerceClient = class {
    * ```
    */
   async updateOrderNotes(orderId, notes) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}/notes`, { notes });
+    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/notes`, {
+      notes
+    });
   }
   /**
    * Get refunds for an order
@@ -1405,7 +1497,7 @@ var BrainerceClient = class {
    * ```
    */
   async getOrderRefunds(orderId) {
-    return this.request("GET", `/api/v1/orders/${orderId}/refunds`);
+    return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/refunds`);
   }
   /**
    * Create a refund for an order
@@ -1432,7 +1524,11 @@ var BrainerceClient = class {
    * ```
    */
   async createRefund(orderId, data) {
-    return this.request("POST", `/api/v1/orders/${orderId}/refunds`, data);
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/refunds`,
+      data
+    );
   }
   /**
    * Update order shipping address
@@ -1452,7 +1548,11 @@ var BrainerceClient = class {
    * ```
    */
   async updateOrderShipping(orderId, data) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}/shipping`, data);
+    return this.request(
+      "PATCH",
+      `/api/v1/orders/${encodePathSegment(orderId)}/shipping`,
+      data
+    );
   }
   /**
    * Cancel an order
@@ -1465,7 +1565,7 @@ var BrainerceClient = class {
    * ```
    */
   async cancelOrder(orderId) {
-    return this.request("POST", `/api/v1/orders/${orderId}/cancel`);
+    return this.request("POST", `/api/v1/orders/${encodePathSegment(orderId)}/cancel`);
   }
   /**
    * Fulfill an order (mark as shipped)
@@ -1481,7 +1581,11 @@ var BrainerceClient = class {
    * ```
    */
   async fulfillOrder(orderId, data) {
-    return this.request("POST", `/api/v1/orders/${orderId}/fulfill`, data || {});
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/fulfill`,
+      data || {}
+    );
   }
   /**
    * Sync draft orders from connected platforms
@@ -1506,7 +1610,11 @@ var BrainerceClient = class {
    * ```
    */
   async completeDraftOrder(orderId, data) {
-    return this.request("POST", `/api/v1/orders/${orderId}/complete-draft`, data || {});
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/complete-draft`,
+      data || {}
+    );
   }
   /**
    * Send invoice for a draft order
@@ -1523,7 +1631,7 @@ var BrainerceClient = class {
   async sendDraftInvoice(orderId, data) {
     return this.request(
       "POST",
-      `/api/v1/orders/${orderId}/send-invoice`,
+      `/api/v1/orders/${encodePathSegment(orderId)}/send-invoice`,
       data || {}
     );
   }
@@ -1536,7 +1644,7 @@ var BrainerceClient = class {
    * ```
    */
   async deleteDraftOrder(orderId) {
-    await this.request("DELETE", `/api/v1/orders/${orderId}/draft`);
+    await this.request("DELETE", `/api/v1/orders/${encodePathSegment(orderId)}/draft`);
   }
   /**
    * Update a draft order
@@ -1559,7 +1667,7 @@ var BrainerceClient = class {
    * ```
    */
   async updateDraftOrder(orderId, data) {
-    return this.request("PATCH", `/api/v1/orders/${orderId}/draft`, data);
+    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/draft`, data);
   }
   // -------------------- Inventory --------------------
   /**
@@ -1567,13 +1675,17 @@ var BrainerceClient = class {
    * This will sync inventory to all connected platforms
    */
   async updateInventory(productId, data) {
-    await this.request("PUT", `/api/v1/products/${productId}/inventory`, data);
+    await this.request(
+      "PUT",
+      `/api/v1/products/${encodePathSegment(productId)}/inventory`,
+      data
+    );
   }
   /**
    * Get current inventory for a product
    */
   async getInventory(productId) {
-    return this.request("GET", `/api/v1/inventory/${productId}`);
+    return this.request("GET", `/api/v1/inventory/${encodePathSegment(productId)}`);
   }
   /**
    * Edit inventory manually with reason for audit trail
@@ -1734,7 +1846,7 @@ var BrainerceClient = class {
    * Get the status of a sync job
    */
   async getSyncStatus(jobId) {
-    return this.request("GET", `/api/v1/sync/${jobId}`);
+    return this.request("GET", `/api/v1/sync/${encodePathSegment(jobId)}`);
   }
   // -------------------- Coupons --------------------
   /**
@@ -1756,7 +1868,7 @@ var BrainerceClient = class {
    * Get a single coupon by ID
    */
   async getCoupon(couponId) {
-    return this.request("GET", `/api/v1/coupons/${couponId}`);
+    return this.request("GET", `/api/v1/coupons/${encodePathSegment(couponId)}`);
   }
   /**
    * Create a new coupon.
@@ -1786,20 +1898,20 @@ var BrainerceClient = class {
    * Update an existing coupon
    */
   async updateCoupon(couponId, data) {
-    return this.request("PATCH", `/api/v1/coupons/${couponId}`, data);
+    return this.request("PATCH", `/api/v1/coupons/${encodePathSegment(couponId)}`, data);
   }
   /**
    * Delete a coupon
    */
   async deleteCoupon(couponId) {
-    await this.request("DELETE", `/api/v1/coupons/${couponId}`);
+    await this.request("DELETE", `/api/v1/coupons/${encodePathSegment(couponId)}`);
   }
   /**
    * Sync a coupon to all connected platforms.
    * Returns a sync job that can be tracked with getSyncStatus().
    */
   async syncCoupon(couponId) {
-    return this.request("POST", `/api/v1/coupons/${couponId}/sync`);
+    return this.request("POST", `/api/v1/coupons/${encodePathSegment(couponId)}/sync`);
   }
   /**
    * Publish a coupon to specific platforms.
@@ -1812,7 +1924,9 @@ var BrainerceClient = class {
    * ```
    */
   async publishCoupon(couponId, platforms) {
-    return this.request("POST", `/api/v1/coupons/${couponId}/publish`, { platforms });
+    return this.request("POST", `/api/v1/coupons/${encodePathSegment(couponId)}/publish`, {
+      platforms
+    });
   }
   /**
    * Get platform capabilities for coupon features.
@@ -1853,13 +1967,17 @@ var BrainerceClient = class {
    * Get a customer by ID
    */
   async getCustomer(customerId) {
-    return this.request("GET", `/api/v1/customers/${customerId}`);
+    return this.request("GET", `/api/v1/customers/${encodePathSegment(customerId)}`);
   }
   /**
    * Update a customer
    */
   async updateCustomer(customerId, data) {
-    return this.request("PATCH", `/api/v1/customers/${customerId}`, data);
+    return this.request(
+      "PATCH",
+      `/api/v1/customers/${encodePathSegment(customerId)}`,
+      data
+    );
   }
   /**
    * Get a customer by email
@@ -1867,56 +1985,84 @@ var BrainerceClient = class {
   async getCustomerByEmail(email) {
     return this.request("GET", "/api/v1/customers/by-email", void 0, { email });
   }
-  /**
-   * List a customer's saved payment methods (vaulted cards).
-   *
-   * Returns display-only metadata — last4, brand, expiry, default flag,
-   * status. The underlying provider token is encrypted at rest and
-   * NEVER returned through this API.
-   *
-   * Apps mode requires `customers:read` and `payments:read` scopes.
-   *
-   * @param storeId - The store this customer belongs to
-   * @param customerId - The customer's ID
-   * @returns Array of saved payment methods
-   *
-   * @example
-   * ```typescript
-   * const methods = await client.listSavedPaymentMethods(storeId, customerId);
-   * methods.forEach((m) => {
-   *   console.log(`${m.brand} ending in ${m.last4} (expires ${m.expMonth}/${m.expYear})`);
-   * });
-   * ```
-   */
-  async listSavedPaymentMethods(storeId, customerId) {
+  async listSavedPaymentMethods(customerIdOrStoreId, maybeCustomerId) {
+    const customerId = this.resolveSavedPaymentMethodsArgs(
+      "listSavedPaymentMethods",
+      customerIdOrStoreId,
+      maybeCustomerId
+    );
     return this.request(
       "GET",
-      `/api/stores/${storeId}/customers/${customerId}/payment-methods`
+      `/api/stores/${this.storeId}/customers/${encodePathSegment(customerId)}/payment-methods`
+    );
+  }
+  async removeSavedPaymentMethod(customerIdOrStoreId, paymentMethodIdOrCustomerId, maybePaymentMethodId) {
+    const { customerId, paymentMethodId } = this.resolveRemovePaymentMethodArgs(
+      customerIdOrStoreId,
+      paymentMethodIdOrCustomerId,
+      maybePaymentMethodId
+    );
+    return this.request(
+      "DELETE",
+      `/api/stores/${this.storeId}/customers/${encodePathSegment(customerId)}/payment-methods/${encodePathSegment(paymentMethodId)}`
     );
   }
   /**
-   * Remove a customer's saved payment method.
-   *
-   * Hard-deletes the row. The provider may still hold the underlying
-   * token internally — we don't issue a delete-at-provider call because
-   * not every provider supports it. From the platform's perspective the
-   * token is gone; subsequent charges will fail.
-   *
-   * Apps mode requires `customers:write` scope.
-   *
-   * @param storeId - The store this customer belongs to
-   * @param customerId - The customer's ID
-   * @param paymentMethodId - The saved payment method ID to remove
+   * Internal helper: normalize legacy `(storeId, customerId)` callers to the
+   * new `(customerId)` signature for `listSavedPaymentMethods`.
    *
-   * @example
-   * ```typescript
-   * await client.removeSavedPaymentMethod(storeId, customerId, methodId);
-   * ```
+   * Throws if the SDK instance has no `storeId` (these endpoints are
+   * storefront-scoped) and warns when the deprecated overload is detected.
    */
-  async removeSavedPaymentMethod(storeId, customerId, paymentMethodId) {
-    return this.request(
-      "DELETE",
-      `/api/stores/${storeId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+  resolveSavedPaymentMethodsArgs(methodName, customerIdOrStoreId, maybeCustomerId) {
+    if (!this.storeId) {
+      throw new BrainerceError(
+        `${methodName}: this method requires a storeId on the SDK instance. Pass \`storeId\` when constructing \`new BrainerceClient({ storeId })\`.`,
+        400
+      );
+    }
+    if (maybeCustomerId !== void 0) {
+      this.warnDeprecatedStoreIdArg(methodName, customerIdOrStoreId);
+      return maybeCustomerId;
+    }
+    return customerIdOrStoreId;
+  }
+  /**
+   * Internal helper: normalize legacy `(storeId, customerId, paymentMethodId)`
+   * callers to the new `(customerId, paymentMethodId)` signature.
+   */
+  resolveRemovePaymentMethodArgs(customerIdOrStoreId, paymentMethodIdOrCustomerId, maybePaymentMethodId) {
+    if (!this.storeId) {
+      throw new BrainerceError(
+        "removeSavedPaymentMethod: this method requires a storeId on the SDK instance. Pass `storeId` when constructing `new BrainerceClient({ storeId })`.",
+        400
+      );
+    }
+    if (maybePaymentMethodId !== void 0) {
+      this.warnDeprecatedStoreIdArg("removeSavedPaymentMethod", customerIdOrStoreId);
+      return {
+        customerId: paymentMethodIdOrCustomerId,
+        paymentMethodId: maybePaymentMethodId
+      };
+    }
+    return {
+      customerId: customerIdOrStoreId,
+      paymentMethodId: paymentMethodIdOrCustomerId
+    };
+  }
+  /**
+   * One-shot deprecation warning per (method, mismatch?) — verifies the
+   * caller-supplied storeId matches the SDK config and warns regardless.
+   */
+  warnDeprecatedStoreIdArg(methodName, suppliedStoreId) {
+    if (suppliedStoreId !== this.storeId) {
+      throw new BrainerceError(
+        `${methodName}: supplied storeId "${suppliedStoreId}" does not match the SDK instance storeId "${this.storeId}". Construct a new client per store.`,
+        400
+      );
+    }
+    console.warn(
+      `BrainerceClient.${methodName}: passing \`storeId\` is deprecated \u2014 it is now derived from the SDK config. Remove the leading argument; this overload will be removed in SDK 2.0.`
     );
   }
   /**
@@ -1975,12 +2121,33 @@ var BrainerceClient = class {
    * Request a password reset email for a customer
    * Works in vibe-coded, storefront, and admin mode
    *
+   * The `resetUrl` MUST be supplied explicitly in non-browser (SSR / Node)
+   * contexts — auto-deriving it from `window.location.origin` is impossible
+   * there and historically resulted in `undefined` being sent to the backend,
+   * which then bounced the email to a broken link. In browser contexts the
+   * origin is still used as a fallback but the SDK logs a one-time warning
+   * recommending an explicit value so server-rendered + proxied dashboards
+   * don't silently rely on the wrong host.
+   *
    * @param email - Customer email address
    * @param options - Optional settings
-   * @param options.resetUrl - Override the auto-detected reset URL (e.g. for BFF proxy callback)
+   * @param options.resetUrl - Reset URL the email links should point to.
+   *   Required outside the browser; recommended inside it.
    */
   async forgotPassword(email, options) {
-    const resetUrl = options?.resetUrl ?? (typeof window !== "undefined" ? `${window.location.origin}/reset-password` : void 0);
+    let resetUrl = options?.resetUrl;
+    if (!resetUrl) {
+      if (typeof window === "undefined") {
+        throw new BrainerceError(
+          'forgotPassword: `resetUrl` is required outside the browser. Pass `{ resetUrl: "https://your-site.example/reset-password" }` so the email links to the right host.',
+          400
+        );
+      }
+      console.warn(
+        "BrainerceClient.forgotPassword: deriving `resetUrl` from `window.location.origin` \u2014 pass `{ resetUrl }` explicitly to avoid wrong-host links behind proxies or in SSR."
+      );
+      resetUrl = `${window.location.origin}/reset-password`;
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/customers/forgot-password", {
         email,
@@ -2163,12 +2330,14 @@ var BrainerceClient = class {
    * // Redirect user to Google
    * window.location.href = authorizationUrl;
    *
-   * // On /auth/callback page — the backend handles code exchange and redirects with params:
+   * // On /auth/callback page — exchange the one-time auth_code for the JWT.
+   * // (The backend used to put the JWT directly in the redirect URL; that path
+   * // is deprecated because URL params leak into browser history and logs.)
    * const params = new URLSearchParams(window.location.search);
-   * if (params.get('oauth_success') === 'true') {
-   *   const token = params.get('token');
-   *   client.setCustomerToken(token);
-   *   // Also available: customer_id, customer_email, is_new
+   * if (params.get('oauth_success') === 'true' && params.get('auth_code')) {
+   *   const result = await client.exchangeOAuthCode(params.get('auth_code')!);
+   *   client.setCustomerToken(result.token);
+   *   // result.customer, result.isNewCustomer, result.redirectUrl, ...
    * } else if (params.get('oauth_error')) {
    *   // Show error
    * }
@@ -2186,7 +2355,7 @@ var BrainerceClient = class {
       params.set("redirectUrl", options.redirectUrl);
     }
     const queryString = params.toString();
-    const endpoint = `/oauth/${provider}/authorize${queryString ? `?${queryString}` : ""}`;
+    const endpoint = `/oauth/${encodePathSegment(provider)}/authorize${queryString ? `?${queryString}` : ""}`;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("GET", endpoint);
     }
@@ -2195,6 +2364,83 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("getOAuthAuthorizeUrl requires vibe-coded or storefront mode", 400);
   }
+  /**
+   * Exchange a one-time `auth_code` (returned in the post-OAuth redirect URL)
+   * for the customer JWT. Use this on the `/auth/callback` storefront page
+   * after reading `auth_code` from `window.location.search`.
+   *
+   * The code is single-use and expires 2 minutes after the OAuth callback
+   * issued it. A second call with the same code returns 400.
+   *
+   * This replaces the legacy flow where the JWT was placed directly in the
+   * redirect URL (`?token=...`). The legacy URL params still ship behind a
+   * server feature flag during the migration window, but they will be
+   * removed in the next major release — migrate now.
+   *
+   * @param authCode - The single-use code from the `?auth_code=` URL param.
+   *
+   * @example
+   * ```typescript
+   * const params = new URLSearchParams(window.location.search);
+   * const code = params.get('auth_code');
+   * if (code) {
+   *   const { token, customer, isNewCustomer, redirectUrl } =
+   *     await client.exchangeOAuthCode(code);
+   *   client.setCustomerToken(token);
+   * }
+   * ```
+   */
+  async exchangeOAuthCode(authCode) {
+    if (!authCode) {
+      throw new BrainerceError("authCode is required", 400);
+    }
+    const url = `${this.baseUrl}/api/oauth/customer/exchange`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const headers = {
+        "Content-Type": "application/json",
+        "X-SDK-Version": SDK_VERSION,
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
+      if (this.locale) {
+        headers["Accept-Language"] = this.locale;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ code: authCode }),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new BrainerceError(
+          errorData.message || `Request failed with status ${response.status}`,
+          response.status,
+          errorData
+        );
+      }
+      const text = await response.text();
+      if (!text) return {};
+      return JSON.parse(text);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof BrainerceError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BrainerceError("Request timeout", 408);
+        }
+        throw new BrainerceError(error.message, 0);
+      }
+      throw new BrainerceError("Unknown error occurred", 0);
+    }
+  }
   /**
    * Handle OAuth callback - exchange code for customer token (server-to-server)
    *
@@ -2215,7 +2461,7 @@ var BrainerceClient = class {
       throw new BrainerceError("provider is required (e.g., 'GOOGLE', 'FACEBOOK', 'GITHUB')", 400);
     }
     const params = new URLSearchParams({ code, state });
-    const endpoint = `/oauth/${provider}/callback?${params.toString()}`;
+    const endpoint = `/oauth/${encodePathSegment(provider)}/callback?${params.toString()}`;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("GET", endpoint);
     }
@@ -2259,7 +2505,7 @@ var BrainerceClient = class {
       params.set("redirectUrl", options.redirectUrl);
     }
     const queryString = params.toString();
-    const endpoint = `/oauth/${provider}/link${queryString ? `?${queryString}` : ""}`;
+    const endpoint = `/oauth/${encodePathSegment(provider)}/link${queryString ? `?${queryString}` : ""}`;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", endpoint);
     }
@@ -2288,10 +2534,16 @@ var BrainerceClient = class {
       throw new BrainerceError("Customer token is required. Call setCustomerToken() first.", 401);
     }
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("DELETE", `/oauth/${provider}/link`);
+      return this.vibeCodedRequest(
+        "DELETE",
+        `/oauth/${encodePathSegment(provider)}/link`
+      );
     }
     if (this.isStorefrontMode()) {
-      return this.storefrontRequest("DELETE", `/oauth/${provider}/link`);
+      return this.storefrontRequest(
+        "DELETE",
+        `/oauth/${encodePathSegment(provider)}/link`
+      );
     }
     throw new BrainerceError("unlinkOAuthProvider requires vibe-coded or storefront mode", 400);
   }
@@ -2358,7 +2610,10 @@ var BrainerceClient = class {
    * Get all addresses for a customer
    */
   async getCustomerAddresses(customerId) {
-    return this.request("GET", `/api/v1/customers/${customerId}/addresses`);
+    return this.request(
+      "GET",
+      `/api/v1/customers/${encodePathSegment(customerId)}/addresses`
+    );
   }
   /**
    * Add an address to a customer
@@ -2380,7 +2635,7 @@ var BrainerceClient = class {
   async addCustomerAddress(customerId, address) {
     return this.request(
       "POST",
-      `/api/v1/customers/${customerId}/addresses`,
+      `/api/v1/customers/${encodePathSegment(customerId)}/addresses`,
       address
     );
   }
@@ -2390,7 +2645,7 @@ var BrainerceClient = class {
   async updateCustomerAddress(customerId, addressId, address) {
     return this.request(
       "PATCH",
-      `/api/v1/customers/${customerId}/addresses/${addressId}`,
+      `/api/v1/customers/${encodePathSegment(customerId)}/addresses/${encodePathSegment(addressId)}`,
       address
     );
   }
@@ -2398,7 +2653,10 @@ var BrainerceClient = class {
    * Delete a customer address
    */
   async deleteCustomerAddress(customerId, addressId) {
-    await this.request("DELETE", `/api/v1/customers/${customerId}/addresses/${addressId}`);
+    await this.request(
+      "DELETE",
+      `/api/v1/customers/${encodePathSegment(customerId)}/addresses/${encodePathSegment(addressId)}`
+    );
   }
   /**
    * Get orders for a customer
@@ -2412,7 +2670,7 @@ var BrainerceClient = class {
   async getCustomerOrders(customerId, params) {
     return this.request(
       "GET",
-      `/api/v1/customers/${customerId}/orders`,
+      `/api/v1/customers/${encodePathSegment(customerId)}/orders`,
       void 0,
       { page: params?.page, limit: params?.limit }
     );
@@ -2484,12 +2742,18 @@ var BrainerceClient = class {
    */
   async getCartBySession(sessionToken) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/cart/session/${sessionToken}`);
+      return this.vibeCodedRequest("GET", `/cart/session/${encodePathSegment(sessionToken)}`);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/cart/session/${sessionToken}`);
+      return this.storefrontRequest(
+        "GET",
+        `/cart/session/${encodePathSegment(sessionToken)}`
+      );
     }
-    return this.adminRequest("GET", `/api/v1/cart/session/${sessionToken}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/cart/session/${encodePathSegment(sessionToken)}`
+    );
   }
   /**
    * Get a cart by customer ID (for authenticated users)
@@ -2502,9 +2766,9 @@ var BrainerceClient = class {
    */
   async getCartByCustomer(customerId) {
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/cart/customer/${customerId}`);
+      return this.storefrontRequest("GET", `/cart/customer/${encodePathSegment(customerId)}`);
     }
-    return this.adminRequest("GET", `/api/v1/cart/customer/${customerId}`);
+    return this.adminRequest("GET", `/api/v1/cart/customer/${encodePathSegment(customerId)}`);
   }
   /**
    * Get a cart by ID
@@ -2534,18 +2798,33 @@ var BrainerceClient = class {
     const queryParams = options?.include?.length ? { include: options.include.join(",") } : void 0;
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("GET", `/cart/${cartId}`, void 0, queryParams),
+        this.vibeCodedRequest(
+          "GET",
+          `/cart/${encodePathSegment(cartId)}`,
+          void 0,
+          queryParams
+        ),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("GET", `/cart/${cartId}`, void 0, queryParams),
+        this.storefrontRequest(
+          "GET",
+          `/cart/${encodePathSegment(cartId)}`,
+          void 0,
+          queryParams
+        ),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("GET", `/api/v1/cart/${cartId}`, void 0, queryParams),
+      this.adminRequest(
+        "GET",
+        `/api/v1/cart/${encodePathSegment(cartId)}`,
+        void 0,
+        queryParams
+      ),
       "cart"
     );
   }
@@ -2601,18 +2880,18 @@ var BrainerceClient = class {
     }
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/cart/${cartId}/items`, item),
+        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, item),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/cart/${cartId}/items`, item),
+        this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, item),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${cartId}/items`, item),
+      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/items`, item),
       "cart"
     );
   }
@@ -2639,18 +2918,30 @@ var BrainerceClient = class {
     }
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("PATCH", `/cart/${cartId}/items/${itemId}`, data),
+        this.vibeCodedRequest(
+          "PATCH",
+          `/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`,
+          data
+        ),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("PATCH", `/cart/${cartId}/items/${itemId}`, data),
+        this.storefrontRequest(
+          "PATCH",
+          `/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`,
+          data
+        ),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("PATCH", `/api/v1/cart/${cartId}/items/${itemId}`, data),
+      this.adminRequest(
+        "PATCH",
+        `/api/v1/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`,
+        data
+      ),
       "cart"
     );
   }
@@ -2677,18 +2968,27 @@ var BrainerceClient = class {
     }
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("DELETE", `/cart/${cartId}/items/${itemId}`),
+        this.vibeCodedRequest(
+          "DELETE",
+          `/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`
+        ),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("DELETE", `/cart/${cartId}/items/${itemId}`),
+        this.storefrontRequest(
+          "DELETE",
+          `/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`
+        ),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("DELETE", `/api/v1/cart/${cartId}/items/${itemId}`),
+      this.adminRequest(
+        "DELETE",
+        `/api/v1/cart/${encodePathSegment(cartId)}/items/${encodePathSegment(itemId)}`
+      ),
       "cart"
     );
   }
@@ -2709,13 +3009,16 @@ var BrainerceClient = class {
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
     if (this.isVibeCodedMode()) {
-      return this.withGuards(this.vibeCodedRequest("DELETE", `/cart/${cartId}`), "cart");
+      return this.withGuards(
+        this.vibeCodedRequest("DELETE", `/cart/${encodePathSegment(cartId)}`),
+        "cart"
+      );
     }
     if (this.storeId && !this.apiKey) {
-      await this.storefrontRequest("DELETE", `/cart/${cartId}/items`);
+      await this.storefrontRequest("DELETE", `/cart/${encodePathSegment(cartId)}/items`);
       return this.withGuards({}, "cart");
     }
-    await this.adminRequest("DELETE", `/api/v1/cart/${cartId}/items`);
+    await this.adminRequest("DELETE", `/api/v1/cart/${encodePathSegment(cartId)}/items`);
     return this.withGuards({}, "cart");
   }
   /**
@@ -2730,18 +3033,18 @@ var BrainerceClient = class {
   async applyCoupon(cartId, code) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/cart/${cartId}/coupon`, { code }),
+        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/coupon`, { code }),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/cart/${cartId}/coupon`, { code }),
+        this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/coupon`, { code }),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${cartId}/coupon`, { code }),
+      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/coupon`, { code }),
       "cart"
     );
   }
@@ -2756,18 +3059,18 @@ var BrainerceClient = class {
   async removeCoupon(cartId) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("DELETE", `/cart/${cartId}/coupon`),
+        this.vibeCodedRequest("DELETE", `/cart/${encodePathSegment(cartId)}/coupon`),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("DELETE", `/cart/${cartId}/coupon`),
+        this.storefrontRequest("DELETE", `/cart/${encodePathSegment(cartId)}/coupon`),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("DELETE", `/api/v1/cart/${cartId}/coupon`),
+      this.adminRequest("DELETE", `/api/v1/cart/${encodePathSegment(cartId)}/coupon`),
       "cart"
     );
   }
@@ -2792,18 +3095,18 @@ var BrainerceClient = class {
     }
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/cart/${cartId}/recalculate`),
+        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/recalculate`),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/cart/${cartId}/recalculate`),
+        this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/recalculate`),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${cartId}/recalculate`),
+      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/recalculate`),
       "cart"
     );
   }
@@ -2832,18 +3135,24 @@ var BrainerceClient = class {
     }
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/cart/${cartId}/refresh-snapshots`),
+        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/refresh-snapshots`),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/cart/${cartId}/refresh-snapshots`),
+        this.storefrontRequest(
+          "POST",
+          `/cart/${encodePathSegment(cartId)}/refresh-snapshots`
+        ),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${cartId}/refresh-snapshots`),
+      this.adminRequest(
+        "POST",
+        `/api/v1/cart/${encodePathSegment(cartId)}/refresh-snapshots`
+      ),
       "cart"
     );
   }
@@ -2872,10 +3181,10 @@ var BrainerceClient = class {
       );
     }
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/cart/${cartId}/link`);
+      return this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/link`);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/cart/${cartId}/link`);
+      return this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/link`);
     }
     throw new BrainerceError("linkCart is only available in vibe-coded or storefront mode", 400);
   }
@@ -2938,13 +3247,13 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/discount-badge`
+        `/products/${encodePathSegment(productId)}/discount-badge`
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/discount-badge`
+        `/products/${encodePathSegment(productId)}/discount-badge`
       );
     }
     throw new BrainerceError(
@@ -2968,10 +3277,13 @@ var BrainerceClient = class {
    */
   async getCartNudges(cartId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/cart/${cartId}/nudges`);
+      return this.vibeCodedRequest("GET", `/cart/${encodePathSegment(cartId)}/nudges`);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/cart/${cartId}/nudges`);
+      return this.storefrontRequest(
+        "GET",
+        `/cart/${encodePathSegment(cartId)}/nudges`
+      );
     }
     throw new BrainerceError("getCartNudges() requires vibe-coded or storefront mode", 400);
   }
@@ -2996,7 +3308,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/recommendations`,
+        `/products/${encodePathSegment(productId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3004,7 +3316,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/recommendations`,
+        `/products/${encodePathSegment(productId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3034,7 +3346,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/reviews`,
+        `/products/${encodePathSegment(productId)}/reviews`,
         void 0,
         queryParams
       );
@@ -3042,7 +3354,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/reviews`,
+        `/products/${encodePathSegment(productId)}/reviews`,
         void 0,
         queryParams
       );
@@ -3066,10 +3378,16 @@ var BrainerceClient = class {
    */
   async getMyProductReview(productId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/products/${productId}/reviews/me`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/${encodePathSegment(productId)}/reviews/me`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/${productId}/reviews/me`);
+      return this.storefrontRequest(
+        "GET",
+        `/products/${encodePathSegment(productId)}/reviews/me`
+      );
     }
     throw new BrainerceError("getMyProductReview() requires vibe-coded or storefront mode", 400);
   }
@@ -3093,10 +3411,18 @@ var BrainerceClient = class {
    */
   async submitProductReview(productId, input) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/products/${productId}/reviews`, input);
+      return this.vibeCodedRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/reviews`,
+        input
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/products/${productId}/reviews`, input);
+      return this.storefrontRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/reviews`,
+        input
+      );
     }
     throw new BrainerceError("submitProductReview() requires vibe-coded or storefront mode", 400);
   }
@@ -3109,14 +3435,14 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/products/${productId}/reviews/me`,
+        `/products/${encodePathSegment(productId)}/reviews/me`,
         input
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/products/${productId}/reviews/me`,
+        `/products/${encodePathSegment(productId)}/reviews/me`,
         input
       );
     }
@@ -3128,11 +3454,17 @@ var BrainerceClient = class {
    */
   async deleteMyProductReview(productId) {
     if (this.isVibeCodedMode()) {
-      await this.vibeCodedRequest("DELETE", `/products/${productId}/reviews/me`);
+      await this.vibeCodedRequest(
+        "DELETE",
+        `/products/${encodePathSegment(productId)}/reviews/me`
+      );
       return;
     }
     if (this.storeId && !this.apiKey) {
-      await this.storefrontRequest("DELETE", `/products/${productId}/reviews/me`);
+      await this.storefrontRequest(
+        "DELETE",
+        `/products/${encodePathSegment(productId)}/reviews/me`
+      );
       return;
     }
     throw new BrainerceError("deleteMyProductReview() requires vibe-coded or storefront mode", 400);
@@ -3151,7 +3483,7 @@ var BrainerceClient = class {
     if (params?.visibility) queryParams.visibility = params.visibility;
     return this.adminRequest(
       "GET",
-      `/api/v1/products/${productId}/reviews`,
+      `/api/v1/products/${encodePathSegment(productId)}/reviews`,
       void 0,
       queryParams
     );
@@ -3163,7 +3495,7 @@ var BrainerceClient = class {
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/reviews/${reviewId}/hide`,
+      `/api/v1/reviews/${encodePathSegment(reviewId)}/hide`,
       void 0,
       storeId ? { storeId } : void 0
     );
@@ -3175,7 +3507,7 @@ var BrainerceClient = class {
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/reviews/${reviewId}/show`,
+      `/api/v1/reviews/${encodePathSegment(reviewId)}/show`,
       void 0,
       storeId ? { storeId } : void 0
     );
@@ -3200,7 +3532,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/cart/${cartId}/recommendations`,
+        `/cart/${encodePathSegment(cartId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3208,7 +3540,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/cart/${cartId}/recommendations`,
+        `/cart/${encodePathSegment(cartId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3235,10 +3567,16 @@ var BrainerceClient = class {
    */
   async getCartUpgrades(cartId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/cart/${cartId}/upgrades`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/cart/${encodePathSegment(cartId)}/upgrades`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/cart/${cartId}/upgrades`);
+      return this.storefrontRequest(
+        "GET",
+        `/cart/${encodePathSegment(cartId)}/upgrades`
+      );
     }
     throw new BrainerceError("getCartUpgrades() requires vibe-coded or storefront mode", 400);
   }
@@ -3260,10 +3598,16 @@ var BrainerceClient = class {
    */
   async getCartBundles(cartId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/cart/${cartId}/bundles`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/cart/${encodePathSegment(cartId)}/bundles`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/cart/${cartId}/bundles`);
+      return this.storefrontRequest(
+        "GET",
+        `/cart/${encodePathSegment(cartId)}/bundles`
+      );
     }
     throw new BrainerceError("getCartBundles() requires vibe-coded or storefront mode", 400);
   }
@@ -3275,10 +3619,16 @@ var BrainerceClient = class {
    */
   async getCheckoutBumps(checkoutId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/checkout/${checkoutId}/bumps`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/checkout/${encodePathSegment(checkoutId)}/bumps`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/checkout/${checkoutId}/bumps`);
+      return this.storefrontRequest(
+        "GET",
+        `/checkout/${encodePathSegment(checkoutId)}/bumps`
+      );
     }
     throw new BrainerceError("getCheckoutBumps() requires vibe-coded or storefront mode", 400);
   }
@@ -3293,10 +3643,10 @@ var BrainerceClient = class {
   async addOrderBump(cartId, bumpConfigId, variantId) {
     const body = { bumpConfigId, ...variantId && { variantId } };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/cart/${cartId}/bump`, body);
+      return this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/bump`, body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/cart/${cartId}/bump`, body);
+      return this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/bump`, body);
     }
     throw new BrainerceError("addOrderBump() requires vibe-coded or storefront mode", 400);
   }
@@ -3309,10 +3659,16 @@ var BrainerceClient = class {
    */
   async removeOrderBump(cartId, bumpConfigId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+      return this.vibeCodedRequest(
+        "DELETE",
+        `/cart/${encodePathSegment(cartId)}/bump/${encodePathSegment(bumpConfigId)}`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+      return this.storefrontRequest(
+        "DELETE",
+        `/cart/${encodePathSegment(cartId)}/bump/${encodePathSegment(bumpConfigId)}`
+      );
     }
     throw new BrainerceError("removeOrderBump() requires vibe-coded or storefront mode", 400);
   }
@@ -3343,10 +3699,14 @@ var BrainerceClient = class {
       ...variantSelections && Object.keys(variantSelections).length > 0 ? { variantSelections } : {}
     };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/cart/${cartId}/bundle`, body);
+      return this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/bundle`, body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/cart/${cartId}/bundle`, body);
+      return this.storefrontRequest(
+        "POST",
+        `/cart/${encodePathSegment(cartId)}/bundle`,
+        body
+      );
     }
     throw new BrainerceError("addBundleToCart() requires vibe-coded or storefront mode", 400);
   }
@@ -3359,10 +3719,16 @@ var BrainerceClient = class {
    */
   async removeBundleFromCart(cartId, bundleOfferId) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("DELETE", `/cart/${cartId}/bundle/${bundleOfferId}`);
+      return this.vibeCodedRequest(
+        "DELETE",
+        `/cart/${encodePathSegment(cartId)}/bundle/${encodePathSegment(bundleOfferId)}`
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("DELETE", `/cart/${cartId}/bundle/${bundleOfferId}`);
+      return this.storefrontRequest(
+        "DELETE",
+        `/cart/${encodePathSegment(cartId)}/bundle/${encodePathSegment(bundleOfferId)}`
+      );
     }
     throw new BrainerceError("removeBundleFromCart() requires vibe-coded or storefront mode", 400);
   }
@@ -3948,18 +4314,18 @@ var BrainerceClient = class {
   async getCheckout(checkoutId) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("GET", `/checkout/${checkoutId}`),
+        this.vibeCodedRequest("GET", `/checkout/${encodePathSegment(checkoutId)}`),
         "checkout"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("GET", `/checkout/${checkoutId}`),
+        this.storefrontRequest("GET", `/checkout/${encodePathSegment(checkoutId)}`),
         "checkout"
       );
     }
     return this.withGuards(
-      this.adminRequest("GET", `/api/v1/checkout/${checkoutId}`),
+      this.adminRequest("GET", `/api/v1/checkout/${encodePathSegment(checkoutId)}`),
       "checkout"
     );
   }
@@ -3982,18 +4348,30 @@ var BrainerceClient = class {
   async applyCheckoutCoupon(checkoutId, code) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        this.vibeCodedRequest(
+          "POST",
+          `/checkout/${encodePathSegment(checkoutId)}/coupon`,
+          { code }
+        ),
         "checkout"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        this.storefrontRequest(
+          "POST",
+          `/checkout/${encodePathSegment(checkoutId)}/coupon`,
+          { code }
+        ),
         "checkout"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/checkout/${checkoutId}/coupon`, { code }),
+      this.adminRequest(
+        "POST",
+        `/api/v1/checkout/${encodePathSegment(checkoutId)}/coupon`,
+        { code }
+      ),
       "checkout"
     );
   }
@@ -4011,18 +4389,27 @@ var BrainerceClient = class {
   async removeCheckoutCoupon(checkoutId) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        this.vibeCodedRequest(
+          "DELETE",
+          `/checkout/${encodePathSegment(checkoutId)}/coupon`
+        ),
         "checkout"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        this.storefrontRequest(
+          "DELETE",
+          `/checkout/${encodePathSegment(checkoutId)}/coupon`
+        ),
         "checkout"
       );
     }
     return this.withGuards(
-      this.adminRequest("DELETE", `/api/v1/checkout/${checkoutId}/coupon`),
+      this.adminRequest(
+        "DELETE",
+        `/api/v1/checkout/${encodePathSegment(checkoutId)}/coupon`
+      ),
       "checkout"
     );
   }
@@ -4040,12 +4427,24 @@ var BrainerceClient = class {
    */
   async setCheckoutCustomer(checkoutId, data) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("PATCH", `/checkout/${checkoutId}/customer`, data);
+      return this.vibeCodedRequest(
+        "PATCH",
+        `/checkout/${encodePathSegment(checkoutId)}/customer`,
+        data
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("PATCH", `/checkout/${checkoutId}/customer`, data);
+      return this.storefrontRequest(
+        "PATCH",
+        `/checkout/${encodePathSegment(checkoutId)}/customer`,
+        data
+      );
     }
-    return this.adminRequest("PATCH", `/api/v1/checkout/${checkoutId}/customer`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/customer`,
+      data
+    );
   }
   /**
    * Get available shipping destinations for this store.
@@ -4113,20 +4512,20 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/shipping-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
         address
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/checkout/${checkoutId}/shipping-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
         address
       );
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/checkout/${checkoutId}/shipping-address`,
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
       address
     );
   }
@@ -4144,19 +4543,19 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       const result = await this.vibeCodedRequest(
         "GET",
-        `/checkout/${checkoutId}/shipping-rates`
+        `/checkout/${encodePathSegment(checkoutId)}/shipping-rates`
       );
       return result.rates;
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/checkout/${checkoutId}/shipping-rates`
+        `/checkout/${encodePathSegment(checkoutId)}/shipping-rates`
       );
     }
     return this.adminRequest(
       "GET",
-      `/api/v1/checkout/${checkoutId}/shipping-rates`
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/shipping-rates`
     );
   }
   /**
@@ -4171,24 +4570,36 @@ var BrainerceClient = class {
   async selectShippingMethod(checkoutId, shippingRateId) {
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("PATCH", `/checkout/${checkoutId}/shipping-method`, {
-          shippingMethodId: shippingRateId
-        }),
+        this.vibeCodedRequest(
+          "PATCH",
+          `/checkout/${encodePathSegment(checkoutId)}/shipping-method`,
+          {
+            shippingRateId
+          }
+        ),
         "checkout"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("PATCH", `/checkout/${checkoutId}/shipping-method`, {
-          shippingRateId
-        }),
+        this.storefrontRequest(
+          "PATCH",
+          `/checkout/${encodePathSegment(checkoutId)}/shipping-method`,
+          {
+            shippingRateId
+          }
+        ),
         "checkout"
       );
     }
     return this.withGuards(
-      this.adminRequest("PATCH", `/api/v1/checkout/${checkoutId}/shipping-method`, {
-        shippingRateId
-      }),
+      this.adminRequest(
+        "PATCH",
+        `/api/v1/checkout/${encodePathSegment(checkoutId)}/shipping-method`,
+        {
+          shippingRateId
+        }
+      ),
       "checkout"
     );
   }
@@ -4227,18 +4638,30 @@ var BrainerceClient = class {
    */
   async setDeliveryType(checkoutId, deliveryType) {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("PATCH", `/checkout/${checkoutId}/delivery-type`, {
-        deliveryType
-      });
+      return this.vibeCodedRequest(
+        "PATCH",
+        `/checkout/${encodePathSegment(checkoutId)}/delivery-type`,
+        {
+          deliveryType
+        }
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("PATCH", `/checkout/${checkoutId}/delivery-type`, {
-        deliveryType
-      });
+      return this.storefrontRequest(
+        "PATCH",
+        `/checkout/${encodePathSegment(checkoutId)}/delivery-type`,
+        {
+          deliveryType
+        }
+      );
     }
-    return this.adminRequest("PATCH", `/api/v1/checkout/${checkoutId}/delivery-type`, {
-      deliveryType
-    });
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/delivery-type`,
+      {
+        deliveryType
+      }
+    );
   }
   /**
    * Select a pickup location for checkout.
@@ -4260,20 +4683,20 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/pickup-location`,
+        `/checkout/${encodePathSegment(checkoutId)}/pickup-location`,
         data
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/checkout/${checkoutId}/pickup-location`,
+        `/checkout/${encodePathSegment(checkoutId)}/pickup-location`,
         data
       );
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/checkout/${checkoutId}/pickup-location`,
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/pickup-location`,
       data
     );
   }
@@ -4305,20 +4728,20 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/billing-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
         address
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/checkout/${checkoutId}/billing-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
         address
       );
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/checkout/${checkoutId}/billing-address`,
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/billing-address`,
       address
     );
   }
@@ -4337,17 +4760,17 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       result = await this.vibeCodedRequest(
         "POST",
-        `/checkout/${checkoutId}/complete`
+        `/checkout/${encodePathSegment(checkoutId)}/complete`
       );
     } else if (this.storeId && !this.apiKey) {
       result = await this.storefrontRequest(
         "POST",
-        `/checkout/${checkoutId}/complete`
+        `/checkout/${encodePathSegment(checkoutId)}/complete`
       );
     } else {
       result = await this.adminRequest(
         "POST",
-        `/api/v1/checkout/${checkoutId}/complete`
+        `/api/v1/checkout/${encodePathSegment(checkoutId)}/complete`
       );
     }
     this.customerCartId = null;
@@ -4365,18 +4788,18 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/checkout/${checkoutId}/custom-fields`
+        `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/checkout/${checkoutId}/custom-fields`
+        `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
     return this.adminRequest(
       "GET",
-      `/api/v1/checkouts/${checkoutId}/custom-fields`
+      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`
     );
   }
   /**
@@ -4399,20 +4822,20 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/custom-fields`,
+        `/checkout/${encodePathSegment(checkoutId)}/custom-fields`,
         data
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/checkout/${checkoutId}/custom-fields`,
+        `/checkout/${encodePathSegment(checkoutId)}/custom-fields`,
         data
       );
     }
     return this.adminRequest(
       "PATCH",
-      `/api/v1/checkouts/${checkoutId}/custom-fields`,
+      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`,
       data
     );
   }
@@ -4427,17 +4850,17 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       result = await this.vibeCodedRequest(
         "DELETE",
-        `/checkout/${checkoutId}`
+        `/checkout/${encodePathSegment(checkoutId)}`
       );
     } else if (this.storeId && !this.apiKey) {
       result = await this.storefrontRequest(
         "DELETE",
-        `/checkout/${checkoutId}`
+        `/checkout/${encodePathSegment(checkoutId)}`
       );
     } else {
       result = await this.adminRequest(
         "DELETE",
-        `/api/v1/checkout/${checkoutId}`
+        `/api/v1/checkout/${encodePathSegment(checkoutId)}`
       );
     }
     this.clearActiveCheckoutStorage();
@@ -4605,7 +5028,10 @@ var BrainerceClient = class {
         400
       );
     }
-    return this.vibeCodedRequest("GET", `/checkout/${checkoutId}/payment-status`);
+    return this.vibeCodedRequest(
+      "GET",
+      `/checkout/${encodePathSegment(checkoutId)}/payment-status`
+    );
   }
   /**
    * Confirm a client-side SDK payment from the frontend.
@@ -4704,7 +5130,7 @@ var BrainerceClient = class {
     const startTime = Date.now();
     let attempts = 0;
     let currentDelay = initialDelayMs;
-    const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    const sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     while (Date.now() - startTime < maxWaitMs) {
       attempts++;
       const status = await this.getPaymentStatus(checkoutId);
@@ -4729,7 +5155,7 @@ var BrainerceClient = class {
       const remainingTime = maxWaitMs - (Date.now() - startTime);
       const sleepTime = Math.min(currentDelay, remainingTime, 8e3);
       if (sleepTime > 0) {
-        await sleep(sleepTime);
+        await sleep2(sleepTime);
         currentDelay = Math.min(currentDelay * 2, 8e3);
       }
     }
@@ -5244,7 +5670,7 @@ var BrainerceClient = class {
     if (data.shippingAddress) {
       const result = await this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/shipping-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
         data.shippingAddress
       );
       checkout = result.checkout;
@@ -5252,7 +5678,7 @@ var BrainerceClient = class {
     if (data.billingAddress) {
       checkout = await this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/billing-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
         data.billingAddress
       );
     }
@@ -5286,7 +5712,7 @@ var BrainerceClient = class {
   async completeGuestCheckout(checkoutId, options) {
     const result = await this.vibeCodedRequest(
       "POST",
-      `/checkout/${checkoutId}/complete`,
+      `/checkout/${encodePathSegment(checkoutId)}/complete`,
       {}
     );
     if (options?.clearCartOnSuccess !== false) {
@@ -5594,13 +6020,13 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/customers/me/orders/${orderId}/downloads${qs}`
+        `/customers/me/orders/${encodePathSegment(orderId)}/downloads${qs}`
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/customers/me/orders/${orderId}/downloads${qs}`
+        `/customers/me/orders/${encodePathSegment(orderId)}/downloads${qs}`
       );
     }
     throw new BrainerceError(
@@ -5693,14 +6119,14 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
-        `/customers/me/addresses/${addressId}`,
+        `/customers/me/addresses/${encodePathSegment(addressId)}`,
         data
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
-        `/customers/me/addresses/${addressId}`,
+        `/customers/me/addresses/${encodePathSegment(addressId)}`,
         data
       );
     }
@@ -5721,11 +6147,17 @@ var BrainerceClient = class {
       );
     }
     if (this.isVibeCodedMode()) {
-      await this.vibeCodedRequest("DELETE", `/customers/me/addresses/${addressId}`);
+      await this.vibeCodedRequest(
+        "DELETE",
+        `/customers/me/addresses/${encodePathSegment(addressId)}`
+      );
       return;
     }
     if (this.storeId && !this.apiKey) {
-      await this.storefrontRequest("DELETE", `/customers/me/addresses/${addressId}`);
+      await this.storefrontRequest(
+        "DELETE",
+        `/customers/me/addresses/${encodePathSegment(addressId)}`
+      );
       return;
     }
     throw new BrainerceError(
@@ -5778,7 +6210,10 @@ var BrainerceClient = class {
    * ```
    */
   async getCustomApiIntegration(integrationId) {
-    return this.adminRequest("GET", `/api/v1/custom-api/${integrationId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/custom-api/${encodePathSegment(integrationId)}`
+    );
   }
   /**
    * Create a new Custom API integration
@@ -5821,7 +6256,7 @@ var BrainerceClient = class {
   async updateCustomApiIntegration(integrationId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/custom-api/${integrationId}`,
+      `/api/v1/custom-api/${encodePathSegment(integrationId)}`,
       data
     );
   }
@@ -5835,7 +6270,10 @@ var BrainerceClient = class {
    * ```
    */
   async deleteCustomApiIntegration(integrationId) {
-    await this.adminRequest("DELETE", `/api/v1/custom-api/${integrationId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/custom-api/${encodePathSegment(integrationId)}`
+    );
   }
   /**
    * Test connection to a Custom API
@@ -5854,7 +6292,7 @@ var BrainerceClient = class {
   async testCustomApiConnection(integrationId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/custom-api/${integrationId}/test`
+      `/api/v1/custom-api/${encodePathSegment(integrationId)}/test`
     );
   }
   // -------------------- Inventory Reservations --------------------
@@ -5975,7 +6413,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getCategory(categoryId) {
-    return this.adminRequest("GET", `/api/v1/categories/${categoryId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/categories/${encodePathSegment(categoryId)}`
+    );
   }
   /**
    * Create a new category
@@ -5998,14 +6439,18 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateCategory(categoryId, data) {
-    return this.adminRequest("PATCH", `/api/v1/categories/${categoryId}`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/categories/${encodePathSegment(categoryId)}`,
+      data
+    );
   }
   /**
    * Delete a category
    * Requires Admin mode (apiKey)
    */
   async deleteCategory(categoryId) {
-    await this.adminRequest("DELETE", `/api/v1/categories/${categoryId}`);
+    await this.adminRequest("DELETE", `/api/v1/categories/${encodePathSegment(categoryId)}`);
   }
   // -------------------- Taxonomy: Brands (Admin) --------------------
   // These methods require Admin mode (apiKey)
@@ -6021,7 +6466,7 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getBrand(brandId) {
-    return this.adminRequest("GET", `/api/v1/brands/${brandId}`);
+    return this.adminRequest("GET", `/api/v1/brands/${encodePathSegment(brandId)}`);
   }
   /**
    * Create a new brand
@@ -6044,14 +6489,14 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateBrand(brandId, data) {
-    return this.adminRequest("PATCH", `/api/v1/brands/${brandId}`, data);
+    return this.adminRequest("PATCH", `/api/v1/brands/${encodePathSegment(brandId)}`, data);
   }
   /**
    * Delete a brand
    * Requires Admin mode (apiKey)
    */
   async deleteBrand(brandId) {
-    await this.adminRequest("DELETE", `/api/v1/brands/${brandId}`);
+    await this.adminRequest("DELETE", `/api/v1/brands/${encodePathSegment(brandId)}`);
   }
   // -------------------- Taxonomy: Tags (Admin) --------------------
   // These methods require Admin mode (apiKey)
@@ -6067,7 +6512,7 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getTag(tagId) {
-    return this.adminRequest("GET", `/api/v1/tags/${tagId}`);
+    return this.adminRequest("GET", `/api/v1/tags/${encodePathSegment(tagId)}`);
   }
   /**
    * Create a new tag
@@ -6089,14 +6534,14 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateTag(tagId, data) {
-    return this.adminRequest("PATCH", `/api/v1/tags/${tagId}`, data);
+    return this.adminRequest("PATCH", `/api/v1/tags/${encodePathSegment(tagId)}`, data);
   }
   /**
    * Delete a tag
    * Requires Admin mode (apiKey)
    */
   async deleteTag(tagId) {
-    await this.adminRequest("DELETE", `/api/v1/tags/${tagId}`);
+    await this.adminRequest("DELETE", `/api/v1/tags/${encodePathSegment(tagId)}`);
   }
   // -------------------- Taxonomy: Attributes (Admin) --------------------
   // These methods require Admin mode (apiKey)
@@ -6117,7 +6562,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getAttribute(attributeId) {
-    return this.adminRequest("GET", `/api/v1/attributes/${attributeId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/attributes/${encodePathSegment(attributeId)}`
+    );
   }
   /**
    * Create a new attribute
@@ -6140,21 +6588,28 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateAttribute(attributeId, data) {
-    return this.adminRequest("PATCH", `/api/v1/attributes/${attributeId}`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/attributes/${encodePathSegment(attributeId)}`,
+      data
+    );
   }
   /**
    * Delete an attribute
    * Requires Admin mode (apiKey)
    */
   async deleteAttribute(attributeId) {
-    await this.adminRequest("DELETE", `/api/v1/attributes/${attributeId}`);
+    await this.adminRequest("DELETE", `/api/v1/attributes/${encodePathSegment(attributeId)}`);
   }
   /**
    * Get all options for an attribute
    * Requires Admin mode (apiKey)
    */
   async getAttributeOptions(attributeId) {
-    return this.adminRequest("GET", `/api/v1/attributes/${attributeId}/options`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/attributes/${encodePathSegment(attributeId)}/options`
+    );
   }
   /**
    * Create a new option for an attribute
@@ -6172,7 +6627,7 @@ var BrainerceClient = class {
   async createAttributeOption(attributeId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/attributes/${attributeId}/options`,
+      `/api/v1/attributes/${encodePathSegment(attributeId)}/options`,
       data
     );
   }
@@ -6183,7 +6638,7 @@ var BrainerceClient = class {
   async updateAttributeOption(attributeId, optionId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/attributes/${attributeId}/options/${optionId}`,
+      `/api/v1/attributes/${encodePathSegment(attributeId)}/options/${encodePathSegment(optionId)}`,
       data
     );
   }
@@ -6194,7 +6649,7 @@ var BrainerceClient = class {
   async deleteAttributeOption(attributeId, optionId) {
     await this.adminRequest(
       "DELETE",
-      `/api/v1/attributes/${attributeId}/options/${optionId}`
+      `/api/v1/attributes/${encodePathSegment(attributeId)}/options/${encodePathSegment(optionId)}`
     );
   }
   // -------------------- Modifier Groups (Admin) --------------------
@@ -6223,7 +6678,7 @@ var BrainerceClient = class {
   async listModifierGroups(storeId, params) {
     return this.adminRequest(
       "GET",
-      `/api/stores/${storeId}/modifier-groups`,
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups`,
       void 0,
       params
     );
@@ -6238,7 +6693,7 @@ var BrainerceClient = class {
   async getModifierGroup(storeId, groupId) {
     return this.adminRequest(
       "GET",
-      `/api/stores/${storeId}/modifier-groups/${groupId}`
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}`
     );
   }
   /**
@@ -6260,7 +6715,11 @@ var BrainerceClient = class {
    * ```
    */
   async createModifierGroup(storeId, data) {
-    return this.adminRequest("POST", `/api/stores/${storeId}/modifier-groups`, data);
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups`,
+      data
+    );
   }
   /**
    * Update a modifier group's metadata or selection rules. Pass `status: 'archived'`
@@ -6270,7 +6729,7 @@ var BrainerceClient = class {
   async updateModifierGroup(storeId, groupId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/stores/${storeId}/modifier-groups/${groupId}`,
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}`,
       data
     );
   }
@@ -6281,7 +6740,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey).
    */
   async deleteModifierGroup(storeId, groupId) {
-    await this.adminRequest("DELETE", `/api/stores/${storeId}/modifier-groups/${groupId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}`
+    );
   }
   /**
    * Create a modifier inside a group (e.g., "Olives" inside the "Toppings" group).
@@ -6305,7 +6767,7 @@ var BrainerceClient = class {
   async createModifier(storeId, groupId, data) {
     return this.adminRequest(
       "POST",
-      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers`,
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}/modifiers`,
       data
     );
   }
@@ -6316,7 +6778,7 @@ var BrainerceClient = class {
   async updateModifier(storeId, groupId, modifierId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}`,
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}/modifiers/${encodePathSegment(modifierId)}`,
       data
     );
   }
@@ -6328,7 +6790,7 @@ var BrainerceClient = class {
   async deleteModifier(storeId, groupId, modifierId) {
     await this.adminRequest(
       "DELETE",
-      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}`
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}/modifiers/${encodePathSegment(modifierId)}`
     );
   }
   /**
@@ -6347,7 +6809,7 @@ var BrainerceClient = class {
   async toggleModifierAvailability(storeId, groupId, modifierId, available) {
     return this.adminRequest(
       "POST",
-      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}/availability-toggle`,
+      `/api/stores/${encodePathSegment(storeId)}/modifier-groups/${encodePathSegment(groupId)}/modifiers/${encodePathSegment(modifierId)}/availability-toggle`,
       { available }
     );
   }
@@ -6368,7 +6830,7 @@ var BrainerceClient = class {
   async attachModifierGroup(storeId, productId, data) {
     return this.adminRequest(
       "POST",
-      `/api/stores/${storeId}/products/${productId}/modifier-groups`,
+      `/api/stores/${encodePathSegment(storeId)}/products/${encodePathSegment(productId)}/modifier-groups`,
       data
     );
   }
@@ -6381,7 +6843,7 @@ var BrainerceClient = class {
   async updateAttachment(storeId, productId, attachmentId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/stores/${storeId}/products/${productId}/modifier-groups/${attachmentId}`,
+      `/api/stores/${encodePathSegment(storeId)}/products/${encodePathSegment(productId)}/modifier-groups/${encodePathSegment(attachmentId)}`,
       data
     );
   }
@@ -6392,7 +6854,7 @@ var BrainerceClient = class {
   async detachModifierGroup(storeId, productId, attachmentId) {
     await this.adminRequest(
       "DELETE",
-      `/api/stores/${storeId}/products/${productId}/modifier-groups/${attachmentId}`
+      `/api/stores/${encodePathSegment(storeId)}/products/${encodePathSegment(productId)}/modifier-groups/${encodePathSegment(attachmentId)}`
     );
   }
   // -------------------- Shipping: Zones and Rates (Admin) --------------------
@@ -6414,7 +6876,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getShippingZone(zoneId) {
-    return this.adminRequest("GET", `/api/v1/shipping/zones/${zoneId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}`
+    );
   }
   /**
    * Create a new shipping zone
@@ -6437,21 +6902,28 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateShippingZone(zoneId, data) {
-    return this.adminRequest("PATCH", `/api/v1/shipping/zones/${zoneId}`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}`,
+      data
+    );
   }
   /**
    * Delete a shipping zone
    * Requires Admin mode (apiKey)
    */
   async deleteShippingZone(zoneId) {
-    await this.adminRequest("DELETE", `/api/v1/shipping/zones/${zoneId}`);
+    await this.adminRequest("DELETE", `/api/v1/shipping/zones/${encodePathSegment(zoneId)}`);
   }
   /**
    * Get all shipping rates for a zone
    * Requires Admin mode (apiKey)
    */
   async getZoneShippingRates(zoneId) {
-    return this.adminRequest("GET", `/api/v1/shipping/zones/${zoneId}/rates`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}/rates`
+    );
   }
   /**
    * Create a new shipping rate for a zone
@@ -6471,7 +6943,7 @@ var BrainerceClient = class {
   async createZoneShippingRate(zoneId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/shipping/zones/${zoneId}/rates`,
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}/rates`,
       data
     );
   }
@@ -6482,7 +6954,7 @@ var BrainerceClient = class {
   async updateZoneShippingRate(zoneId, rateId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/shipping/zones/${zoneId}/rates/${rateId}`,
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}/rates/${encodePathSegment(rateId)}`,
       data
     );
   }
@@ -6491,7 +6963,149 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async deleteZoneShippingRate(zoneId, rateId) {
-    await this.adminRequest("DELETE", `/api/v1/shipping/zones/${zoneId}/rates/${rateId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/shipping/zones/${encodePathSegment(zoneId)}/rates/${encodePathSegment(rateId)}`
+    );
+  }
+  // -------------------- Regions (Admin mode, apiKey) --------------------
+  // Multi-region commerce. storeId is derived from the api_key — do not pass it.
+  // Requires the `regions:read` / `regions:write` scopes on the key.
+  /** List the store's regions (paginated). */
+  async getRegions() {
+    return this.adminRequest("GET", "/api/v1/regions");
+  }
+  async getRegion(regionId) {
+    return this.adminRequest("GET", `/api/v1/regions/${encodePathSegment(regionId)}`);
+  }
+  async createRegion(data) {
+    return this.adminRequest("POST", "/api/v1/regions", data);
+  }
+  async updateRegion(regionId, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/regions/${encodePathSegment(regionId)}`,
+      data
+    );
+  }
+  async deleteRegion(regionId) {
+    await this.adminRequest("DELETE", `/api/v1/regions/${encodePathSegment(regionId)}`);
+  }
+  async setDefaultRegion(regionId) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/regions/${encodePathSegment(regionId)}/set-default`
+    );
+  }
+  /** Replace the region's enabled payment providers (AppInstallation IDs). */
+  async updateRegionPaymentProviders(regionId, providerIds) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/regions/${encodePathSegment(regionId)}/payment-providers`,
+      { providerIds }
+    );
+  }
+  async addRegionCountries(regionId, countries) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/regions/${encodePathSegment(regionId)}/countries`,
+      { countries }
+    );
+  }
+  async removeRegionCountry(regionId, countryCode) {
+    return this.adminRequest(
+      "DELETE",
+      `/api/v1/regions/${encodePathSegment(regionId)}/countries/${encodePathSegment(countryCode)}`
+    );
+  }
+  /** Installed payment providers compatible with this region's countries. */
+  async getRegionCompatibleProviders(regionId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
+    );
+  }
+  // -------------------- Regions (Storefront mode, public — no apiKey) --------------------
+  // storeId-based, no auth. Call these from a storefront to detect the buyer's
+  // region (story S1), then pair with detectRegion(). Admin/api-key callers use
+  // getRegions()/getRegion() instead.
+  /**
+   * List the store's ACTIVE regions (public, no apiKey). Requires storeId mode.
+   * Returns only storefront-safe fields (no internal flags). Default region first.
+   */
+  async getStoreRegions() {
+    return this.storefrontRequest("GET", "/regions");
+  }
+  /**
+   * Get one active public region plus its enabled payment providers (public).
+   * Requires storeId mode. Throws 404 if the region is inactive or not found.
+   */
+  async getStoreRegion(regionId) {
+    return this.storefrontRequest(
+      "GET",
+      `/regions/${encodePathSegment(regionId)}`
+    );
+  }
+  /**
+   * Client-side region detection — no network call. Returns the region whose
+   * `countries` includes `country`, else the default region, else null.
+   */
+  detectRegion(country, regions) {
+    const code = country.toUpperCase();
+    return regions.find((r) => r.countries.includes(code)) ?? regions.find((r) => r.isDefault) ?? null;
+  }
+  // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
+  /**
+   * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
+   * safe fields only (id/name/slug/description/isDefault) for transparency UIs
+   * such as a "9% VAT" badge. Admin/api-key callers use getTaxClasses().
+   */
+  async getStoreTaxClasses() {
+    return this.storefrontRequest("GET", "/tax-classes");
+  }
+  // -------------------- Tax Classes (Admin mode, apiKey) --------------------
+  // Requires the `tax-classes:read` / `tax-classes:write` scopes on the key.
+  /** List the store's tax classes. */
+  async getTaxClasses() {
+    return this.adminRequest("GET", "/api/v1/tax-classes");
+  }
+  /** Get a tax class with its dependent counts (products/variants/categories/rates). */
+  async getTaxClass(id) {
+    return this.adminRequest("GET", `/api/v1/tax-classes/${encodePathSegment(id)}`);
+  }
+  async createTaxClass(data) {
+    return this.adminRequest("POST", "/api/v1/tax-classes", data);
+  }
+  async updateTaxClass(id, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/tax-classes/${encodePathSegment(id)}`,
+      data
+    );
+  }
+  async deleteTaxClass(id) {
+    await this.adminRequest("DELETE", `/api/v1/tax-classes/${encodePathSegment(id)}`);
+  }
+  async setDefaultTaxClass(id) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/tax-classes/${encodePathSegment(id)}/set-default`
+    );
+  }
+  /** Bulk-assign this tax class to products / variants / categories. */
+  async assignTaxClass(id, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/tax-classes/${encodePathSegment(id)}/assign`,
+      data
+    );
+  }
+  /** Merge this tax class into another, moving all FKs, then delete it. */
+  async mergeTaxClasses(id, targetId) {
+    await this.adminRequest(
+      "POST",
+      `/api/v1/tax-classes/${encodePathSegment(id)}/merge-into/${encodePathSegment(targetId)}`
+    );
   }
   // -------------------- Tax: Rates --------------------
   // These methods require Admin mode (apiKey)
@@ -6507,7 +7121,7 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getTaxRate(rateId) {
-    return this.adminRequest("GET", `/api/v1/tax/rates/${rateId}`);
+    return this.adminRequest("GET", `/api/v1/tax/rates/${encodePathSegment(rateId)}`);
   }
   /**
    * Create a new tax rate
@@ -6532,14 +7146,18 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateTaxRate(rateId, data) {
-    return this.adminRequest("PATCH", `/api/v1/tax/rates/${rateId}`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/tax/rates/${encodePathSegment(rateId)}`,
+      data
+    );
   }
   /**
    * Delete a tax rate
    * Requires Admin mode (apiKey)
    */
   async deleteTaxRate(rateId) {
-    await this.adminRequest("DELETE", `/api/v1/tax/rates/${rateId}`);
+    await this.adminRequest("DELETE", `/api/v1/tax/rates/${encodePathSegment(rateId)}`);
   }
   // -------------------- Metafields: Definitions --------------------
   // These methods require Admin mode (apiKey)
@@ -6595,7 +7213,7 @@ var BrainerceClient = class {
   async getMetafieldDefinition(definitionId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/metafield-definitions/${definitionId}`
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}`
     );
   }
   /**
@@ -6622,7 +7240,7 @@ var BrainerceClient = class {
   async updateMetafieldDefinition(definitionId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/metafield-definitions/${definitionId}`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}`,
       data
     );
   }
@@ -6631,7 +7249,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async deleteMetafieldDefinition(definitionId) {
-    await this.adminRequest("DELETE", `/api/v1/metafield-definitions/${definitionId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}`
+    );
   }
   /**
    * Replace the platform publishing configuration on a metafield definition.
@@ -6655,7 +7276,7 @@ var BrainerceClient = class {
   async setMetafieldPlatforms(definitionId, data) {
     return this.adminRequest(
       "PUT",
-      `/api/v1/metafield-definitions/${definitionId}/platforms`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/platforms`,
       data
     );
   }
@@ -6674,7 +7295,7 @@ var BrainerceClient = class {
   async publishMetafieldDefinitionToVibeCodedSite(definitionId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/metafield-definitions/${definitionId}/publish-vibe-coded`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/publish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6682,7 +7303,7 @@ var BrainerceClient = class {
   async unpublishMetafieldDefinitionFromVibeCodedSite(definitionId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/metafield-definitions/${definitionId}/unpublish-vibe-coded`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/unpublish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6690,7 +7311,7 @@ var BrainerceClient = class {
   async publishCategoryToVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${categoryId}/publish-vibe-coded`,
+      `/api/v1/categories/${encodePathSegment(categoryId)}/publish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6698,7 +7319,7 @@ var BrainerceClient = class {
   async unpublishCategoryFromVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${categoryId}/unpublish-vibe-coded`,
+      `/api/v1/categories/${encodePathSegment(categoryId)}/unpublish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6706,7 +7327,7 @@ var BrainerceClient = class {
   async publishTagToVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${tagId}/publish-vibe-coded`,
+      `/api/v1/tags/${encodePathSegment(tagId)}/publish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6714,7 +7335,7 @@ var BrainerceClient = class {
   async unpublishTagFromVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${tagId}/unpublish-vibe-coded`,
+      `/api/v1/tags/${encodePathSegment(tagId)}/unpublish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6722,7 +7343,7 @@ var BrainerceClient = class {
   async publishBrandToVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${brandId}/publish-vibe-coded`,
+      `/api/v1/brands/${encodePathSegment(brandId)}/publish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6730,7 +7351,7 @@ var BrainerceClient = class {
   async unpublishBrandFromVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${brandId}/unpublish-vibe-coded`,
+      `/api/v1/brands/${encodePathSegment(brandId)}/unpublish-vibe-coded`,
       { vibeCodedConnectionId }
     );
   }
@@ -6756,7 +7377,7 @@ var BrainerceClient = class {
   async setDefinitionProducts(definitionId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/metafield-definitions/${definitionId}/products`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/products`,
       data
     );
   }
@@ -6769,7 +7390,7 @@ var BrainerceClient = class {
   async getProductMetafields(productId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/products/${productId}/metafields`
+      `/api/v1/products/${encodePathSegment(productId)}/metafields`
     );
   }
   /**
@@ -6786,7 +7407,7 @@ var BrainerceClient = class {
   async setProductMetafield(productId, definitionId, data) {
     return this.adminRequest(
       "PUT",
-      `/api/v1/products/${productId}/metafields/${definitionId}`,
+      `/api/v1/products/${encodePathSegment(productId)}/metafields/${encodePathSegment(definitionId)}`,
       data
     );
   }
@@ -6797,7 +7418,7 @@ var BrainerceClient = class {
   async deleteProductMetafield(productId, definitionId) {
     await this.adminRequest(
       "DELETE",
-      `/api/v1/products/${productId}/metafields/${definitionId}`
+      `/api/v1/products/${encodePathSegment(productId)}/metafields/${encodePathSegment(definitionId)}`
     );
   }
   // -------------------- Product Customization Fields (Admin) --------------------
@@ -6808,7 +7429,7 @@ var BrainerceClient = class {
   async getProductCustomizationFields(productId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/metafield-definitions/products/${productId}/customization-fields`
+      `/api/v1/metafield-definitions/products/${encodePathSegment(productId)}/customization-fields`
     );
   }
   /**
@@ -6819,7 +7440,7 @@ var BrainerceClient = class {
   async setProductCustomizationFields(productId, definitionIds) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/metafield-definitions/products/${productId}/customization-fields`,
+      `/api/v1/metafield-definitions/products/${encodePathSegment(productId)}/customization-fields`,
       { definitionIds }
     );
   }
@@ -6899,26 +7520,33 @@ var BrainerceClient = class {
   async resendTeamInvitation(invitationId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/team/invitations/${invitationId}/resend`
+      `/api/v1/team/invitations/${encodePathSegment(invitationId)}/resend`
     );
   }
   /**
    * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
    */
   async revokeTeamInvitation(invitationId) {
-    await this.adminRequest("DELETE", `/api/v1/team/invitations/${invitationId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/team/invitations/${encodePathSegment(invitationId)}`
+    );
   }
   /**
    * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
    */
   async updateTeamMemberRole(memberId, data) {
-    return this.adminRequest("PATCH", `/api/v1/team/members/${memberId}/role`, data);
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/team/members/${encodePathSegment(memberId)}/role`,
+      data
+    );
   }
   /**
    * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
    */
   async removeTeamMember(memberId) {
-    await this.adminRequest("DELETE", `/api/v1/team/members/${memberId}`);
+    await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);
   }
   // -------------------- Store Team Management (Admin) --------------------
   // Store-level team management. Each store has its own team with roles and permissions.
@@ -6932,7 +7560,10 @@ var BrainerceClient = class {
    * ```
    */
   async getStoreTeam(storeId) {
-    return this.adminRequest("GET", `/api/v1/stores/${storeId}/team`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/stores/${encodePathSegment(storeId)}/team`
+    );
   }
   /**
    * Invite a new member to a store
@@ -6943,13 +7574,16 @@ var BrainerceClient = class {
    * const invitation = await client.inviteStoreMember('store_id', {
    *   email: 'newmember@example.com',
    *   role: 'MANAGER', // 'MANAGER' | 'STAFF' | 'VIEWER'
+   *   // Optional: restrict to specific vibe-coded channels (connectionId, vc_*).
+   *   // Omit or pass [] for unrestricted access to all channels.
+   *   salesChannelIds: ['vc_abc123', 'vc_def456'],
    * });
    * ```
    */
   async inviteStoreMember(storeId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/stores/${storeId}/team/invite`,
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/invite`,
       data
     );
   }
@@ -6971,7 +7605,33 @@ var BrainerceClient = class {
   async updateStoreMember(storeId, memberId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/stores/${storeId}/team/${memberId}`,
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`,
+      data
+    );
+  }
+  /**
+   * Replace the set of vibe-coded sales channels a store member is restricted to.
+   * Channels are identified by their public `connectionId` (`vc_*` format). Pass
+   * an empty array to clear all restrictions (member becomes unrestricted).
+   * Requires Admin mode (apiKey) and MANAGE_TEAM permission
+   *
+   * @example
+   * ```typescript
+   * // Restrict to two vibe-coded channels
+   * await client.updateStoreMemberSalesChannels('store_id', 'member_id', {
+   *   salesChannelIds: ['vc_abc123', 'vc_def456'],
+   * });
+   *
+   * // Clear all restrictions (unrestricted access)
+   * await client.updateStoreMemberSalesChannels('store_id', 'member_id', {
+   *   salesChannelIds: [],
+   * });
+   * ```
+   */
+  async updateStoreMemberSalesChannels(storeId, memberId, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}/sales-channels`,
       data
     );
   }
@@ -6980,7 +7640,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
   async removeStoreMember(storeId, memberId) {
-    await this.adminRequest("DELETE", `/api/v1/stores/${storeId}/team/${memberId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`
+    );
   }
   /**
    * Resend a store invitation email
@@ -6989,7 +7652,7 @@ var BrainerceClient = class {
   async resendStoreInvitation(storeId, invitationId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/stores/${storeId}/team/invitations/${invitationId}/resend`
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}/resend`
     );
   }
   /**
@@ -6999,7 +7662,7 @@ var BrainerceClient = class {
   async revokeStoreInvitation(storeId, invitationId) {
     await this.adminRequest(
       "DELETE",
-      `/api/v1/stores/${storeId}/team/invitations/${invitationId}`
+      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}`
     );
   }
   /**
@@ -7007,14 +7670,20 @@ var BrainerceClient = class {
    * Used on the invitation acceptance page
    */
   async getStoreInvitationByToken(token) {
-    return this.request("GET", `/api/v1/store-invitations/${token}`);
+    return this.request(
+      "GET",
+      `/api/v1/store-invitations/${encodePathSegment(token)}`
+    );
   }
   /**
    * Accept a store invitation
    * Requires Admin mode (apiKey)
    */
   async acceptStoreInvitation(token) {
-    await this.adminRequest("POST", `/api/v1/store-invitations/${token}/accept`);
+    await this.adminRequest(
+      "POST",
+      `/api/v1/store-invitations/${encodePathSegment(token)}/accept`
+    );
   }
   /**
    * Get all stores accessible to the current user (owned + member of)
@@ -7047,7 +7716,7 @@ var BrainerceClient = class {
   async getMyStorePermissions(storeId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/me/stores/${storeId}/permissions`
+      `/api/v1/me/stores/${encodePathSegment(storeId)}/permissions`
     );
   }
   // -------------------- Email Settings & Templates (Admin) --------------------
@@ -7080,7 +7749,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getEmailTemplate(templateId) {
-    return this.adminRequest("GET", `/api/v1/email/templates/${templateId}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/email/templates/${encodePathSegment(templateId)}`
+    );
   }
   /**
    * Create a new email template
@@ -7104,14 +7776,21 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async updateEmailTemplate(templateId, data) {
-    return this.adminRequest("PUT", `/api/v1/email/templates/${templateId}`, data);
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/email/templates/${encodePathSegment(templateId)}`,
+      data
+    );
   }
   /**
    * Delete an email template
    * Requires Admin mode (apiKey)
    */
   async deleteEmailTemplate(templateId) {
-    await this.adminRequest("DELETE", `/api/v1/email/templates/${templateId}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/email/templates/${encodePathSegment(templateId)}`
+    );
   }
   /**
    * Preview an email template with sample data
@@ -7120,7 +7799,7 @@ var BrainerceClient = class {
   async previewEmailTemplate(templateId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/email/templates/${templateId}/preview`,
+      `/api/v1/email/templates/${encodePathSegment(templateId)}/preview`,
       data || {}
     );
   }
@@ -7141,9 +7820,13 @@ var BrainerceClient = class {
    * @param resolution - 'MERGE' to link to existing product, 'CREATE_NEW' to create new product
    */
   async resolveSyncConflict(conflictId, resolution) {
-    return this.adminRequest("POST", `/api/v1/sync-conflicts/${conflictId}/resolve`, {
-      resolution
-    });
+    return this.adminRequest(
+      "POST",
+      `/api/v1/sync-conflicts/${encodePathSegment(conflictId)}/resolve`,
+      {
+        resolution
+      }
+    );
   }
   // -------------------- Metafield Conflicts (Admin) --------------------
   // These methods require Admin mode (apiKey)
@@ -7164,7 +7847,7 @@ var BrainerceClient = class {
   async resolveMetafieldConflict(conflictId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/metafield-conflicts/${conflictId}/resolve`,
+      `/api/v1/metafield-conflicts/${encodePathSegment(conflictId)}/resolve`,
       data
     );
   }
@@ -7175,7 +7858,7 @@ var BrainerceClient = class {
   async ignoreMetafieldConflict(conflictId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/metafield-conflicts/${conflictId}/ignore`
+      `/api/v1/metafield-conflicts/${encodePathSegment(conflictId)}/ignore`
     );
   }
   // -------------------- OAuth Provider Configuration (Admin) --------------------
@@ -7192,7 +7875,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async getOAuthProvider(provider) {
-    return this.adminRequest("GET", `/api/v1/oauth-providers/${provider}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/oauth-providers/${encodePathSegment(provider)}`
+    );
   }
   /**
    * Configure an OAuth provider for customer login
@@ -7218,7 +7904,7 @@ var BrainerceClient = class {
   async updateOAuthProvider(provider, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/oauth-providers/${provider}`,
+      `/api/v1/oauth-providers/${encodePathSegment(provider)}`,
       data
     );
   }
@@ -7227,7 +7913,10 @@ var BrainerceClient = class {
    * Requires Admin mode (apiKey)
    */
   async deleteOAuthProvider(provider) {
-    await this.adminRequest("DELETE", `/api/v1/oauth-providers/${provider}`);
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/oauth-providers/${encodePathSegment(provider)}`
+    );
   }
 };
 var BrainerceError = class extends Error {
@@ -7324,7 +8013,7 @@ var ALLOWED_PAYMENT_HOSTS = [
   // Brainerce-hosted payment embeds (backend payment-embed proxy at
   // `/api/payment/embed/...` that fronts provider apps' embed shells —
   // e.g. cardcom-payments OpenFields wrapper). The match also covers
-  // subdomains like `api.brainerce.com`, `staging.brainerce.com`.
+  // every brainerce.com subdomain (api., docs., …).
   "brainerce.com"
 ];
 function isAllowedPaymentUrl(url, options) {
@@ -7352,6 +8041,55 @@ function safePaymentRedirect(url, options) {
   }
 }
 
+// src/format-price.ts
+var DEFAULT_LOCALE = "en";
+function formatProductPrice(product, options = {}) {
+  const { locale = DEFAULT_LOCALE, prefer = "sale-if-available", storeCurrency } = options;
+  const usingDisplay = product.displayPrice != null;
+  const currency = usingDisplay ? product.displayCurrency : storeCurrency;
+  const baseAmount = usingDisplay ? product.displayPrice : product.basePrice;
+  const saleAmount = usingDisplay ? product.displaySalePrice : product.salePrice;
+  const amount = prefer === "sale-if-available" && saleAmount != null && saleAmount !== "" ? saleAmount : baseAmount;
+  if (amount == null || amount === "") return null;
+  const parsed = parseFloat(amount);
+  if (Number.isNaN(parsed)) return null;
+  return formatAmount(parsed, currency, locale);
+}
+function formatVariantPrice(variant, options = {}) {
+  const { locale = DEFAULT_LOCALE, prefer = "sale-if-available", storeCurrency } = options;
+  const usingDisplay = variant.displayPrice != null;
+  const currency = usingDisplay ? variant.displayCurrency : storeCurrency;
+  const baseAmount = usingDisplay ? variant.displayPrice : variant.price;
+  const saleAmount = usingDisplay ? variant.displaySalePrice : variant.salePrice;
+  const amount = prefer === "sale-if-available" && saleAmount != null && saleAmount !== "" ? saleAmount : baseAmount;
+  if (amount == null || amount === "") return null;
+  const parsed = parseFloat(amount);
+  if (Number.isNaN(parsed)) return null;
+  return formatAmount(parsed, currency, locale);
+}
+function formatMoney(amount, currency, locale = DEFAULT_LOCALE) {
+  return formatAmount(amount, currency, locale);
+}
+function formatAmount(amount, currency, locale) {
+  if (!currency) {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2
+    }).format(amount);
+  }
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency
+    }).format(amount);
+  } catch {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2
+    }).format(amount);
+  }
+}
+
 // src/types.ts
 function isHtmlDescription(product) {
   if (product?.descriptionFormat === "html") return true;
@@ -7443,7 +8181,9 @@ function getProductPriceInfo(product) {
   if (!product) {
     return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
   }
-  const resolvedBasePrice = parseFloat(product.basePrice) === 0 && product.priceMin ? product.priceMin : product.basePrice;
+  const parsedBase = parseFloat(product.basePrice);
+  const baseIsUsable = typeof product.basePrice === "string" && product.basePrice.length > 0 && !isNaN(parsedBase) && parsedBase > 0;
+  const resolvedBasePrice = !baseIsUsable && product.priceMin ? product.priceMin : product.basePrice;
   if (product.discount) {
     const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
     const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
@@ -7491,7 +8231,7 @@ function getCartTotals(cart, shippingPrice) {
   const subtotal = parseFloat(cart.subtotal) || 0;
   const discount = parseFloat(cart.discountAmount) || 0;
   const shipping = typeof shippingPrice === "string" ? parseFloat(shippingPrice) || 0 : shippingPrice || 0;
-  const total = subtotal - discount + shipping;
+  const total = Math.max(0, subtotal - discount + shipping);
   return { subtotal, discount, shipping, total };
 }
 function getCartItemName(item) {
@@ -7599,7 +8339,10 @@ function isCouponApplicableToProduct(coupon, productId) {
   createWebhookHandler,
   deriveSeoDescription,
   enableDevGuards,
+  formatMoney,
   formatPrice,
+  formatProductPrice,
+  formatVariantPrice,
   getCartItemImage,
   getCartItemName,
   getCartTotals,