brainerce 1.27.0 → 1.28.0

package/dist/index.mjs

@@ -126,6 +126,35 @@ function getDirectionForLocale(locale) {
   const primary = locale.split("-")[0].toLowerCase();
   return RTL_LOCALES.has(primary) ? "rtl" : "ltr";
 }
+function encodePathSegment(value) {
+  let normalized = value;
+  try {
+    normalized = decodeURIComponent(value);
+  } catch {
+    normalized = 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;
@@ -341,7 +370,7 @@ var BrainerceClient = class {
            */
           getBySlug: async (slug, locale) => {
             const query = locale ? { locale } : void 0;
-            const path = `/content/pages/by-slug/${encodeURIComponent(slug)}`;
+            const path = `/content/pages/by-slug/${encodePathSegment(slug)}`;
             const onNotFound = (err) => {
               if (err instanceof BrainerceError && err.statusCode === 404) return null;
               throw err;
@@ -559,7 +588,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.",
@@ -574,52 +603,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)
@@ -628,7 +669,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) {
@@ -636,70 +677,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)
@@ -708,7 +760,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) {
@@ -716,67 +768,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
@@ -866,6 +929,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",
@@ -879,14 +943,14 @@ var BrainerceClient = class {
         "GET",
         "/products",
         void 0,
-        queryParams
+        queryParamsWithRegion
       );
     }
     return this.adminRequest(
       "GET",
       "/api/v1/products",
       void 0,
-      queryParams
+      queryParamsWithRegion
     );
   }
   /**
@@ -895,10 +959,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
@@ -907,13 +972,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
@@ -927,7 +997,7 @@ var BrainerceClient = class {
    */
   async getProductBySlug(slug, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
-    const encodedSlug = encodeURIComponent(slug);
+    const encodedSlug = encodePathSegment(slug);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -1031,7 +1101,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);
   }
@@ -1073,7 +1143,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
@@ -1101,7 +1171,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
     );
@@ -1116,7 +1186,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
@@ -1129,7 +1202,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
@@ -1141,9 +1217,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 --------------------
   /**
@@ -1161,7 +1241,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)
@@ -1181,7 +1265,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
     );
   }
@@ -1199,7 +1283,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
     );
   }
@@ -1212,7 +1296,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
@@ -1226,7 +1313,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`
     );
   }
   /**
@@ -1243,7 +1330,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
     );
   }
@@ -1267,7 +1354,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
@@ -1280,7 +1370,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
@@ -1291,7 +1381,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
@@ -1303,9 +1395,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
@@ -1316,7 +1412,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
@@ -1329,7 +1427,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
@@ -1356,7 +1454,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
@@ -1376,7 +1478,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
@@ -1389,7 +1495,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)
@@ -1405,7 +1511,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
@@ -1430,7 +1540,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
@@ -1447,7 +1561,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 || {}
     );
   }
@@ -1460,7 +1574,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
@@ -1483,7 +1597,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 --------------------
   /**
@@ -1491,13 +1605,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
@@ -1658,7 +1776,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 --------------------
   /**
@@ -1680,7 +1798,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.
@@ -1710,20 +1828,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.
@@ -1736,7 +1854,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.
@@ -1777,13 +1897,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
@@ -1791,56 +1915,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.`
     );
   }
   /**
@@ -1899,12 +2051,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,
@@ -2087,12 +2260,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
    * }
@@ -2110,7 +2285,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);
     }
@@ -2119,6 +2294,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)
    *
@@ -2139,7 +2391,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);
     }
@@ -2183,7 +2435,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);
     }
@@ -2212,10 +2464,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);
   }
@@ -2282,7 +2540,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
@@ -2304,7 +2565,7 @@ var BrainerceClient = class {
   async addCustomerAddress(customerId, address) {
     return this.request(
       "POST",
-      `/api/v1/customers/${customerId}/addresses`,
+      `/api/v1/customers/${encodePathSegment(customerId)}/addresses`,
       address
     );
   }
@@ -2314,7 +2575,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
     );
   }
@@ -2322,7 +2583,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
@@ -2336,7 +2600,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 }
     );
@@ -2408,12 +2672,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)
@@ -2426,9 +2696,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
@@ -2458,18 +2728,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"
     );
   }
@@ -2525,18 +2810,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"
     );
   }
@@ -2563,18 +2848,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"
     );
   }
@@ -2601,18 +2898,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"
     );
   }
@@ -2633,13 +2939,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");
   }
   /**
@@ -2654,18 +2963,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"
     );
   }
@@ -2680,18 +2989,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"
     );
   }
@@ -2716,18 +3025,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"
     );
   }
@@ -2756,18 +3065,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"
     );
   }
@@ -2796,10 +3111,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);
   }
@@ -2862,13 +3177,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(
@@ -2892,10 +3207,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);
   }
@@ -2920,7 +3238,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/recommendations`,
+        `/products/${encodePathSegment(productId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -2928,7 +3246,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/recommendations`,
+        `/products/${encodePathSegment(productId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -2958,7 +3276,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/reviews`,
+        `/products/${encodePathSegment(productId)}/reviews`,
         void 0,
         queryParams
       );
@@ -2966,7 +3284,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/reviews`,
+        `/products/${encodePathSegment(productId)}/reviews`,
         void 0,
         queryParams
       );
@@ -2990,10 +3308,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);
   }
@@ -3017,10 +3341,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);
   }
@@ -3033,14 +3365,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
       );
     }
@@ -3052,11 +3384,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);
@@ -3075,7 +3413,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
     );
@@ -3087,7 +3425,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
     );
@@ -3099,7 +3437,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
     );
@@ -3124,7 +3462,7 @@ var BrainerceClient = class {
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/cart/${cartId}/recommendations`,
+        `/cart/${encodePathSegment(cartId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3132,7 +3470,7 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/cart/${cartId}/recommendations`,
+        `/cart/${encodePathSegment(cartId)}/recommendations`,
         void 0,
         queryParams
       );
@@ -3159,10 +3497,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);
   }
@@ -3184,10 +3528,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);
   }
@@ -3199,10 +3549,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);
   }
@@ -3217,10 +3573,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);
   }
@@ -3233,10 +3589,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);
   }
@@ -3267,10 +3629,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);
   }
@@ -3283,10 +3649,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);
   }
@@ -3872,18 +4244,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"
     );
   }
@@ -3906,18 +4278,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"
     );
   }
@@ -3935,18 +4319,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"
     );
   }
@@ -3964,12 +4357,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.
@@ -4037,20 +4442,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
     );
   }
@@ -4068,19 +4473,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`
     );
   }
   /**
@@ -4095,24 +4500,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"
     );
   }
@@ -4151,18 +4568,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.
@@ -4184,20 +4613,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
     );
   }
@@ -4229,20 +4658,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
     );
   }
@@ -4261,17 +4690,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;
@@ -4289,18 +4718,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`
     );
   }
   /**
@@ -4323,20 +4752,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
     );
   }
@@ -4351,17 +4780,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();
@@ -4529,7 +4958,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.
@@ -4628,7 +5060,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);
@@ -4653,7 +5085,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);
       }
     }
@@ -5168,7 +5600,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;
@@ -5176,7 +5608,7 @@ var BrainerceClient = class {
     if (data.billingAddress) {
       checkout = await this.vibeCodedRequest(
         "PATCH",
-        `/checkout/${checkoutId}/billing-address`,
+        `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
         data.billingAddress
       );
     }
@@ -5210,7 +5642,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) {
@@ -5518,13 +5950,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(
@@ -5617,14 +6049,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
       );
     }
@@ -5645,11 +6077,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(
@@ -5702,7 +6140,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
@@ -5745,7 +6186,7 @@ var BrainerceClient = class {
   async updateCustomApiIntegration(integrationId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/custom-api/${integrationId}`,
+      `/api/v1/custom-api/${encodePathSegment(integrationId)}`,
       data
     );
   }
@@ -5759,7 +6200,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
@@ -5778,7 +6222,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 --------------------
@@ -5899,7 +6343,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
@@ -5922,14 +6369,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)
@@ -5945,7 +6396,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
@@ -5968,14 +6419,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)
@@ -5991,7 +6442,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
@@ -6013,14 +6464,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)
@@ -6041,7 +6492,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
@@ -6064,21 +6518,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
@@ -6096,7 +6557,7 @@ var BrainerceClient = class {
   async createAttributeOption(attributeId, data) {
     return this.adminRequest(
       "POST",
-      `/api/v1/attributes/${attributeId}/options`,
+      `/api/v1/attributes/${encodePathSegment(attributeId)}/options`,
       data
     );
   }
@@ -6107,7 +6568,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
     );
   }
@@ -6118,7 +6579,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) --------------------
@@ -6147,7 +6608,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
     );
@@ -6162,7 +6623,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)}`
     );
   }
   /**
@@ -6184,7 +6645,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'`
@@ -6194,7 +6659,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
     );
   }
@@ -6205,7 +6670,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).
@@ -6229,7 +6697,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
     );
   }
@@ -6240,7 +6708,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
     );
   }
@@ -6252,7 +6720,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)}`
     );
   }
   /**
@@ -6271,7 +6739,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 }
     );
   }
@@ -6292,7 +6760,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
     );
   }
@@ -6305,7 +6773,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
     );
   }
@@ -6316,7 +6784,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) --------------------
@@ -6338,7 +6806,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
@@ -6361,21 +6832,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
@@ -6395,7 +6873,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
     );
   }
@@ -6406,7 +6884,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
     );
   }
@@ -6415,7 +6893,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)
@@ -6431,7 +7051,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
@@ -6456,14 +7076,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)
@@ -6519,7 +7143,7 @@ var BrainerceClient = class {
   async getMetafieldDefinition(definitionId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/metafield-definitions/${definitionId}`
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}`
     );
   }
   /**
@@ -6546,7 +7170,7 @@ var BrainerceClient = class {
   async updateMetafieldDefinition(definitionId, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/metafield-definitions/${definitionId}`,
+      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}`,
       data
     );
   }
@@ -6555,7 +7179,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.
@@ -6579,7 +7206,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
     );
   }
@@ -6598,7 +7225,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 }
     );
   }
@@ -6606,7 +7233,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 }
     );
   }
@@ -6614,7 +7241,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 }
     );
   }
@@ -6622,7 +7249,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 }
     );
   }
@@ -6630,7 +7257,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 }
     );
   }
@@ -6638,7 +7265,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 }
     );
   }
@@ -6646,7 +7273,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 }
     );
   }
@@ -6654,7 +7281,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 }
     );
   }
@@ -6680,7 +7307,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
     );
   }
@@ -6693,7 +7320,7 @@ var BrainerceClient = class {
   async getProductMetafields(productId) {
     return this.adminRequest(
       "GET",
-      `/api/v1/products/${productId}/metafields`
+      `/api/v1/products/${encodePathSegment(productId)}/metafields`
     );
   }
   /**
@@ -6710,7 +7337,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
     );
   }
@@ -6721,7 +7348,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) --------------------
@@ -6732,7 +7359,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`
     );
   }
   /**
@@ -6743,7 +7370,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 }
     );
   }
@@ -6823,26 +7450,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.
@@ -6856,7 +7490,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
@@ -6867,13 +7504,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
     );
   }
@@ -6895,7 +7535,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
     );
   }
@@ -6904,7 +7570,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
@@ -6913,7 +7582,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`
     );
   }
   /**
@@ -6923,7 +7592,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)}`
     );
   }
   /**
@@ -6931,14 +7600,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)
@@ -6971,7 +7646,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) --------------------
@@ -7004,7 +7679,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
@@ -7028,14 +7706,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
@@ -7044,7 +7729,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 || {}
     );
   }
@@ -7065,9 +7750,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)
@@ -7088,7 +7777,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
     );
   }
@@ -7099,7 +7788,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) --------------------
@@ -7116,7 +7805,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
@@ -7142,7 +7834,7 @@ var BrainerceClient = class {
   async updateOAuthProvider(provider, data) {
     return this.adminRequest(
       "PATCH",
-      `/api/v1/oauth-providers/${provider}`,
+      `/api/v1/oauth-providers/${encodePathSegment(provider)}`,
       data
     );
   }
@@ -7151,7 +7843,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 {
@@ -7248,7 +7943,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) {
@@ -7367,7 +8062,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;