brainerce 1.63.0 → 2.0.2

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.60.0";
+var SDK_VERSION = "2.0.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -561,7 +561,7 @@ var _BrainerceClient = class _BrainerceClient {
      */
     this.blog = /* @__PURE__ */ (() => {
       const publicBase = "/blog/posts";
-      const adminBase = "/blog/posts";
+      const adminBase = "/api/blog/posts";
       const requireAdmin = (action) => {
         if (this.isVibeCodedMode() || this.storeId && !this.apiKey) {
           throw new BrainerceError(
@@ -674,7 +674,7 @@ var _BrainerceClient = class _BrainerceClient {
     }
     if (!options.salesChannelId && options.connectionId) {
       console.warn(
-        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` will be removed in SDK 2.0."
+        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` is a permanent backward-compat alias and is not scheduled for removal."
       );
     }
     if (options.apiKey && typeof window !== "undefined") {
@@ -2395,115 +2395,97 @@ var _BrainerceClient = class _BrainerceClient {
     return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}`, data);
   }
   /**
-   * Update order status
+   * Update order status.
+   *
+   * **Not callable — use {@link updateOrder} instead.** Status changes do work
+   * over the API key, just by a different route.
+   *
+   * @deprecated Call `updateOrder(orderId, { status })`.
    *
    * @example
    * ```typescript
-   * const order = await client.updateOrderStatus('order_123', 'shipped');
+   * const order = await client.updateOrder('order_123', { status: 'SHIPPED' });
    * ```
    */
   async updateOrderStatus(orderId, status) {
-    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/status`, {
-      status
-    });
+    void orderId;
+    void status;
+    throw new BrainerceError(
+      "updateOrderStatus is not a route on the API-key /v1 surface. Status changes go through updateOrder instead: updateOrder(orderId, { status }) PATCHes /api/v1/orders/:id and ends up in the same service call.",
+      400
+    );
   }
   /**
-   * Update order payment method
-   * Note: Only WooCommerce supports syncing payment method changes back to platform
+   * Update order payment method.
    *
-   * @example
-   * ```typescript
-   * const order = await client.updatePaymentMethod('order_123', 'credit_card');
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no payment-method route,
+   * so this throws in every mode. Change the payment method from the
+   * dashboard until the route ships.
    */
   async updatePaymentMethod(orderId, paymentMethod) {
-    return this.request(
-      "PATCH",
-      `/api/v1/orders/${encodePathSegment(orderId)}/payment-method`,
-      {
-        paymentMethod
-      }
+    void orderId;
+    void paymentMethod;
+    throw new BrainerceError(
+      "updatePaymentMethod is not a route on the API-key /v1 surface. There is no orders/:id/payment-method endpoint to call; change the payment method from the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Update order notes
+   * Update order notes.
    *
-   * @example
-   * ```typescript
-   * const order = await client.updateOrderNotes('order_123', 'Customer requested gift wrapping');
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no order-notes route, so
+   * this throws in every mode. Edit notes from the dashboard until the route
+   * ships.
    */
   async updateOrderNotes(orderId, notes) {
-    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/notes`, {
-      notes
-    });
+    void orderId;
+    void notes;
+    throw new BrainerceError(
+      "updateOrderNotes is not a route on the API-key /v1 surface. There is no orders/:id/notes endpoint to call; edit the note from the Brainerce dashboard.",
+      400
+    );
   }
   /**
-   * Get refunds for an order
-   * Returns refunds from the source platform (Shopify/WooCommerce only)
+   * Get refunds for an order.
    *
-   * @example
-   * ```typescript
-   * const refunds = await client.getOrderRefunds('order_123');
-   * console.log('Total refunds:', refunds.length);
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no refunds route, so this
+   * throws in every mode. Read refunds from the dashboard until the route
+   * ships.
    */
   async getOrderRefunds(orderId) {
-    return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/refunds`);
+    void orderId;
+    throw new BrainerceError(
+      "getOrderRefunds is not a route on the API-key /v1 surface. There is no orders/:id/refunds endpoint to call; view refunds in the Brainerce dashboard.",
+      400
+    );
   }
   /**
-   * Create a refund for an order
-   * Creates refund on the source platform (Shopify/WooCommerce only)
-   *
-   * @example
-   * ```typescript
-   * // Full refund
-   * const refund = await client.createRefund('order_123', {
-   *   type: 'full',
-   *   restockInventory: true,
-   *   notifyCustomer: true,
-   *   reason: 'Customer request',
-   * });
+   * Create a refund for an order.
    *
-   * // Partial refund
-   * const partialRefund = await client.createRefund('order_123', {
-   *   type: 'partial',
-   *   items: [
-   *     { lineItemId: 'item_456', quantity: 1 },
-   *   ],
-   *   restockInventory: true,
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no refunds route, so this
+   * throws in every mode. Refund from the dashboard until the route ships.
    */
   async createRefund(orderId, data) {
-    return this.request(
-      "POST",
-      `/api/v1/orders/${encodePathSegment(orderId)}/refunds`,
-      data
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "createRefund is not a route on the API-key /v1 surface. There is no orders/:id/refunds endpoint to call, so no refund was issued; refund the order from the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Update order shipping address
-   * Syncs to source platform (Shopify/WooCommerce only)
+   * Update order shipping address.
    *
-   * @example
-   * ```typescript
-   * const order = await client.updateOrderShipping('order_123', {
-   *   firstName: 'John',
-   *   lastName: 'Doe',
-   *   line1: '456 New Address',
-   *   city: 'Los Angeles',
-   *   state: 'CA',
-   *   country: 'US',
-   *   postalCode: '90001',
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no order-shipping route,
+   * so this throws in every mode. Correct the address from the dashboard
+   * until the route ships.
    */
   async updateOrderShipping(orderId, data) {
-    return this.request(
-      "PATCH",
-      `/api/v1/orders/${encodePathSegment(orderId)}/shipping`,
-      data
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "updateOrderShipping is not a route on the API-key /v1 surface. There is no orders/:id/shipping endpoint to call, so the address was not changed; edit it in the Brainerce dashboard.",
+      400
     );
   }
   /**
@@ -2569,17 +2551,49 @@ var _BrainerceClient = class _BrainerceClient {
     return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments`);
   }
   /**
-   * Cancel an order
-   * Works for Shopify and WooCommerce orders that haven't been fulfilled
+   * Buy a return label the merchant sends to their customer to print.
+   *
+   * Requires admin mode (`apiKey`) with `FULFILL_ORDERS` permission — it
+   * spends the store's carrier balance, same as {@link createShippingLabel}.
+   *
+   * Unlike {@link createShippingLabel}, this is **not** on the API-key `/v1`
+   * surface — it calls the internal `/api/orders/:id/shipments/return-label`
+   * route, which takes `storeId` explicitly rather than resolving it from the
+   * key. There is no `rateId` in the body: a return is quoted and bought in
+   * one call at the shipping app, because the carrier fixes a shipment as a
+   * return when it is created and will not amend it afterwards.
    *
    * @example
    * ```typescript
-   * const order = await client.cancelOrder('order_123');
-   * console.log('Order status:', order.status); // 'cancelled'
+   * const label = await client.createReturnLabel('store_abc', 'order_abc', {
+   *   reason: 'Wrong size',
+   *   returnForShipmentId: 'shp_original123',
+   * });
+   * console.log('Return label URL:', label.labelUrl);
    * ```
    */
+  async createReturnLabel(storeId, orderId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/orders/${encodePathSegment(orderId)}/shipments/return-label`,
+      data,
+      { storeId }
+    );
+  }
+  /**
+   * Cancel an order.
+   *
+   * **Not callable.** The API-key `/v1` surface has no cancel route, so this
+   * throws in every mode. A status move to cancelled may be reachable through
+   * {@link updateOrder} depending on what the order's state machine allows;
+   * otherwise cancel from the dashboard.
+   */
   async cancelOrder(orderId) {
-    return this.request("POST", `/api/v1/orders/${encodePathSegment(orderId)}/cancel`);
+    void orderId;
+    throw new BrainerceError(
+      "cancelOrder is not a route on the API-key /v1 surface. There is no orders/:id/cancel endpoint to call, so the order was not cancelled. Try updateOrder(orderId, { status }) for a plain status move, or cancel from the Brainerce dashboard.",
+      400
+    );
   }
   /**
    * Fulfill an order (mark as shipped), or correct the tracking of an order
@@ -2593,110 +2607,87 @@ var _BrainerceClient = class _BrainerceClient {
    * ship date is not rewritten, and no fulfilment event fires. That is the way
    * to fix a mistyped tracking number.
    *
-   * @example
-   * ```typescript
-   * // First fulfilment — emails the shopper by default.
-   * await client.fulfillOrder('order_123', {
-   *   trackingNumber: '1Z999AA10123456784',
-   *   trackingCompany: 'UPS',
-   *   trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784',
-   *   notifyCustomer: true,
-   * });
-   *
-   * // Correction — silent unless you opt back in.
-   * await client.fulfillOrder('order_123', {
-   *   trackingNumber: '1Z999AA10123456785',
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no fulfil route, so this
+   * throws in every mode. To ship an order over the API today, buy a label
+   * with {@link createShippingLabel} — the carrier's webhooks then move the
+   * shipment through in-transit and delivered on their own. Otherwise fulfil
+   * from the dashboard.
    */
   async fulfillOrder(orderId, data) {
-    return this.request(
-      "POST",
-      `/api/v1/orders/${encodePathSegment(orderId)}/fulfill`,
-      data || {}
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "fulfillOrder is not a route on the API-key /v1 surface. There is no orders/:id/fulfill endpoint to call, so nothing was fulfilled and no shipped email went out. Use createShippingLabel to ship over the API, or fulfil from the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Sync draft orders from connected platforms
+   * Sync draft orders from connected platforms.
    *
-   * @example
-   * ```typescript
-   * const result = await client.syncDraftOrders();
-   * console.log('Draft orders synced');
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no draft-order routes at
+   * all, so this throws in every mode. {@link triggerSync} covers a general
+   * platform sync; draft orders are managed from the dashboard.
    */
   async syncDraftOrders() {
-    return this.request("POST", "/api/v1/orders/sync-drafts");
+    throw new BrainerceError(
+      "syncDraftOrders is not a route on the API-key /v1 surface. There is no orders/sync-drafts endpoint to call, so nothing was synced. Use triggerSync for a platform sync, or work with drafts in the Brainerce dashboard.",
+      400
+    );
   }
   /**
-   * Complete a draft order (convert to regular order)
+   * Complete a draft order (convert to regular order).
    *
-   * @example
-   * ```typescript
-   * const order = await client.completeDraftOrder('draft_123', {
-   *   paymentPending: false,
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no draft-order routes at
+   * all, so this throws in every mode. Complete drafts from the dashboard.
    */
   async completeDraftOrder(orderId, data) {
-    return this.request(
-      "POST",
-      `/api/v1/orders/${encodePathSegment(orderId)}/complete-draft`,
-      data || {}
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "completeDraftOrder is not a route on the API-key /v1 surface. There is no orders/:id/complete-draft endpoint to call, so the draft was not converted; complete it in the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Send invoice for a draft order
+   * Send invoice for a draft order.
    *
-   * @example
-   * ```typescript
-   * await client.sendDraftInvoice('draft_123', {
-   *   to: 'customer@example.com',
-   *   subject: 'Your Invoice',
-   *   customMessage: 'Thank you for your order!',
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no draft-order routes at
+   * all, so this throws in every mode. Send the invoice from the dashboard.
    */
   async sendDraftInvoice(orderId, data) {
-    return this.request(
-      "POST",
-      `/api/v1/orders/${encodePathSegment(orderId)}/send-invoice`,
-      data || {}
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "sendDraftInvoice is not a route on the API-key /v1 surface. There is no orders/:id/send-invoice endpoint to call, so no invoice was sent; send it from the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Delete a draft order
+   * Delete a draft order.
    *
-   * @example
-   * ```typescript
-   * await client.deleteDraftOrder('draft_123');
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no draft-order routes at
+   * all, so this throws in every mode. Delete drafts from the dashboard.
    */
   async deleteDraftOrder(orderId) {
-    await this.request("DELETE", `/api/v1/orders/${encodePathSegment(orderId)}/draft`);
+    void orderId;
+    throw new BrainerceError(
+      "deleteDraftOrder is not a route on the API-key /v1 surface. There is no orders/:id/draft endpoint to call, so nothing was deleted; delete the draft in the Brainerce dashboard.",
+      400
+    );
   }
   /**
-   * Update a draft order
+   * Update a draft order.
    *
-   * @example
-   * ```typescript
-   * const order = await client.updateDraftOrder('draft_123', {
-   *   note: 'Updated customer note',
-   *   email: 'newemail@example.com',
-   *   shippingAddress: {
-   *     firstName: 'John',
-   *     lastName: 'Doe',
-   *     address1: '123 Main St',
-   *     city: 'New York',
-   *     province: 'NY',
-   *     country: 'US',
-   *     zip: '10001',
-   *   },
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no draft-order routes at
+   * all, so this throws in every mode. Edit drafts from the dashboard.
    */
   async updateDraftOrder(orderId, data) {
-    return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}/draft`, data);
+    void orderId;
+    void data;
+    throw new BrainerceError(
+      "updateDraftOrder is not a route on the API-key /v1 surface. There is no orders/:id/draft endpoint to call, so the draft was not changed; edit it in the Brainerce dashboard.",
+      400
+    );
   }
   // -------------------- Inventory --------------------
   /**
@@ -2711,82 +2702,91 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * Get current inventory for a product
+   * Get current inventory for a product.
+   *
+   * **Admin mode only** — the API key needs the `inventory:read` scope.
+   *
+   * This used to request `/api/v1/inventory/:productId`, which does not
+   * exist and 404'd silently. The live route is product-scoped:
+   * `GET /api/v1/products/:id/inventory`. A product with no inventory row
+   * reads back as all zeroes rather than 404ing.
    */
   async getInventory(productId) {
-    return this.request("GET", `/api/v1/inventory/${encodePathSegment(productId)}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/${encodePathSegment(productId)}/inventory`
+    );
   }
   /**
-   * Edit inventory manually with reason for audit trail
+   * Edit inventory manually with a reason for the audit trail.
    *
-   * @example
-   * ```typescript
-   * const inventory = await client.editInventory({
-   *   productId: 'prod_123',
-   *   newTotal: 100,
-   *   reason: 'Restocked from warehouse',
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface carries no `inventory`
+   * namespace, so this throws in every mode.
+   *
+   * {@link updateInventory} is the closest working call: it sets the same
+   * absolute stock level over `PUT /api/v1/products/:id/inventory`, but the
+   * reason is not yours to choose — the server records a generic
+   * "Updated via External API" against the audit trail. If the reason text
+   * matters, make the edit from the dashboard.
    */
   async editInventory(data) {
-    return this.request("POST", "/api/v1/inventory/edit", data);
+    void data;
+    throw new BrainerceError(
+      "editInventory is not a route on the API-key /v1 surface. There is no inventory/edit endpoint to call, so stock was not changed. Use updateInventory(productId, { quantity }) to set the same level, though it records a generic audit reason. Edit from the dashboard when the reason text matters.",
+      400
+    );
   }
   /**
-   * Get inventory sync status for all products in the store
+   * Get inventory sync status for all products in the store.
    *
-   * @example
-   * ```typescript
-   * const status = await client.getInventorySyncStatus();
-   * console.log(`${status.pending} products pending sync`);
-   * console.log(`Last sync: ${status.lastSyncAt}`);
-   * ```
+   * **Not callable.** The API-key `/v1` surface carries no `inventory`
+   * namespace, so this throws in every mode. Sync state is visible in the
+   * dashboard; {@link getSyncStatus} covers platform sync jobs.
    */
   async getInventorySyncStatus() {
-    return this.request("GET", "/api/v1/inventory/sync-status");
+    throw new BrainerceError(
+      "getInventorySyncStatus is not a route on the API-key /v1 surface. There is no inventory/sync-status endpoint to call; check inventory sync state in the Brainerce dashboard.",
+      400
+    );
   }
   /**
-   * Get inventory for multiple products at once
+   * Get inventory for multiple products at once.
    *
-   * @example
-   * ```typescript
-   * const inventories = await client.getBulkInventory(['prod_123', 'prod_456', 'prod_789']);
-   * inventories.forEach(inv => {
-   *   console.log(`${inv.productId}: ${inv.available} available`);
-   * });
-   * ```
+   * **Not callable.** The API-key `/v1` surface carries no `inventory`
+   * namespace, so this throws in every mode. There is no bulk stock read on
+   * the API key today: fall back to {@link getInventory} per product, or read
+   * the stock that {@link getProducts} already returns on each product.
    */
   async getBulkInventory(productIds) {
-    return this.request("POST", "/api/v1/inventory/bulk", { productIds });
+    void productIds;
+    throw new BrainerceError(
+      "getBulkInventory is not a route on the API-key /v1 surface. There is no inventory/bulk endpoint to call; read stock per product with getInventory, or off the products returned by getProducts.",
+      400
+    );
   }
   /**
-   * Reconcile inventory between Brainerce and connected platforms
-   * Detects and optionally fixes discrepancies
-   *
-   * @example
-   * ```typescript
-   * // Reconcile single product (dry run)
-   * const result = await client.reconcileInventory({ productId: 'prod_123' });
+   * Reconcile inventory between Brainerce and connected platforms.
+   * Detects and optionally fixes discrepancies.
    *
-   * // Reconcile all products with auto-fix
-   * const summary = await client.reconcileInventory({ autoFix: true });
-   * console.log(`Reconciled ${summary.reconciled} products`);
-   * ```
+   * **Not callable.** The API-key `/v1` surface carries no `inventory`
+   * namespace, so this throws in every mode, `autoFix` included. Reconcile
+   * from the dashboard.
    */
   async reconcileInventory(options) {
-    const queryParams = {};
-    if (options?.productId) queryParams.productId = options.productId;
-    if (options?.autoFix) queryParams.autoFix = "true";
-    return this.request(
-      "POST",
-      "/api/v1/inventory/reconcile",
-      void 0,
-      queryParams
+    void options;
+    throw new BrainerceError(
+      "reconcileInventory is not a route on the API-key /v1 surface. There is no inventory/reconcile endpoint to call, so nothing was reconciled or fixed; run reconciliation from the Brainerce dashboard.",
+      400
     );
   }
   /**
    * Check stock availability for one or more items before adding to cart or checkout
    * Use this to validate stock before operations that might fail due to insufficient inventory
    *
+   * **Vibe-coded or storefront mode only.** There is no stock-check route on
+   * the API-key `/v1` surface; in admin mode this throws. The same applies to
+   * {@link checkCartStock}, which routes through here.
+   *
    * @example
    * ```typescript
    * // Check if items are available before adding to cart
@@ -2818,9 +2818,10 @@ var _BrainerceClient = class _BrainerceClient {
         { items }
       );
     }
-    return this.request("POST", "/api/v1/inventory/check-availability", {
-      items
-    });
+    throw new BrainerceError(
+      "checkStockAvailability is only available in vibe-coded or storefront mode. The API-key /v1 surface has no inventory/check-availability route; read stock per product with getInventory instead.",
+      400
+    );
   }
   /**
    * Check stock availability for cart items before checkout.
@@ -3157,49 +3158,43 @@ var _BrainerceClient = class _BrainerceClient {
    * 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.
+   * The reset link's host is chosen by the server, not by the caller: it is
+   * derived from the sales channel's own domain, falling back to the backend's
+   * configured frontend URL, and the request is rejected if neither resolves.
+   *
+   * The SDK used to send a `resetUrl` in the request body. The backend
+   * deliberately removed that field: any caller could submit an arbitrary URL
+   * and have it emailed, from a Brainerce-domained sender, to the address
+   * holder — a phishing-link injection. `ForgotPasswordDto` now declares
+   * `email` and nothing else, and the API's global validation pipe runs with
+   * `whitelist` + `forbidNonWhitelisted`, so a body carrying `resetUrl` fails
+   * the whole call with `400 property resetUrl should not exist`. Only `email`
+   * is sent.
+   *
+   * The endpoint always answers 200 so it cannot be used to enumerate
+   * accounts; the mail is only sent when a matching customer exists.
    *
    * @param email - Customer email address
-   * @param options - Optional settings
-   * @param options.resetUrl - Reset URL the email links should point to.
-   *   Required outside the browser; recommended inside it.
+   * @param options - Accepted for source compatibility only. Ignored.
    */
   async forgotPassword(email, options) {
-    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`;
-    }
+    void options;
+    const body = { email };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", "/customers/forgot-password", {
-        email,
-        resetUrl
-      });
+      return this.vibeCodedRequest("POST", "/customers/forgot-password", body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", "/customers/forgot-password", {
-        email,
-        resetUrl
-      });
+      return this.storefrontRequest(
+        "POST",
+        "/customers/forgot-password",
+        body
+      );
     }
-    return this.adminRequest("POST", "/api/v1/customers/forgot-password", {
-      email,
-      resetUrl
-    });
+    return this.adminRequest(
+      "POST",
+      "/api/v1/customers/forgot-password",
+      body
+    );
   }
   /**
    * Reset customer password using a reset token received via email
@@ -10020,6 +10015,156 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/oauth-providers/${encodePathSegment(provider)}`
     );
   }
+  // -------------------- Translations (Admin) --------------------
+  // These methods require Admin mode (apiKey) with a scope-bearing key —
+  // `products:read`/`products:write` cover most entity types via
+  // StorePermissionGuard's STORE_PERMISSION_TO_SCOPE mapping (VIEW_PRODUCTS /
+  // EDIT_PRODUCTS). Routes: /api/stores/:storeId/translations/...
+  //
+  // Reads and writes the SAME `translations` JSON blob the dashboard editor
+  // uses — this is not a separate translation system, it's API-key access to
+  // the dashboard's own persistence path. Use it for bulk-importing
+  // pre-translated content or automating locale coverage without a human in
+  // the dashboard.
+  /**
+   * Get translation completeness across every translatable entity type, for
+   * one or more locales. Useful as a pre-flight before a bulk import to see
+   * which entity types/locales still need coverage.
+   * Requires Admin mode (apiKey).
+   *
+   * @param storeId - Store to inspect.
+   * @param locales - BCP-47 locale codes to check (e.g. `['he', 'fr']`). Omit
+   *   or pass an empty array to get rows with `total` populated but no
+   *   locale breakdown.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getTranslationStatus('store_123', ['he', 'fr']);
+   * const blogHe = status.find((s) => s.entityType === 'blogPost' && s.locale === 'he');
+   * console.log(`${blogHe?.missing} blog posts still need Hebrew`);
+   * ```
+   */
+  async getTranslationStatus(storeId, locales) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/status`,
+      void 0,
+      locales && locales.length > 0 ? { locales: locales.join(",") } : void 0
+    );
+  }
+  /**
+   * Get every persisted translation for a single entity, keyed by locale.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.getTranslations('store_123', 'product', 'prod_abc');
+   * console.log(translations.he?.name); // Hebrew product name, if set
+   * ```
+   */
+  async getTranslations(storeId, entityType, entityId) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}`
+    );
+  }
+  /**
+   * Set/update one locale's translation for an entity. Only the fields valid
+   * for `entityType` are persisted (e.g. `title`/`excerpt`/`content` for
+   * `blogPost`, `name`/`description` for `category`) — fields outside that
+   * entity's allowlist are silently ignored server-side, and omitted fields
+   * leave any existing translation for them untouched (this is a merge, not
+   * a replace, of the locale's fields).
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @example
+   * ```typescript
+   * // Bulk-import a pre-translated blog post
+   * await client.setTranslation('store_123', 'blogPost', 'post_abc', 'fr', {
+   *   title: 'Le titre en français',
+   *   excerpt: "L'extrait en français",
+   *   content: '<p>Le contenu en français</p>',
+   * });
+   * ```
+   */
+  async setTranslation(storeId, entityType, entityId, locale, fields) {
+    return this.adminRequest(
+      "PUT",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`,
+      fields
+    );
+  }
+  /**
+   * Delete one locale's translation for an entity. The entity's base
+   * (default-locale) fields are unaffected.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   */
+  async deleteTranslation(storeId, entityType, entityId, locale) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`
+    );
+  }
+  /**
+   * AI-translate a single entity into one target locale and persist the
+   * result inline (synchronous — the response already reflects the write).
+   * Only fields that are still empty for `targetLocale` are filled; existing
+   * translated values are never overwritten.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param sourceFields - Optional override of the source-language text to
+   *   translate from (e.g. unsaved edits from an open editor), instead of the
+   *   entity's persisted base fields. Keys outside the entity's translatable
+   *   field set are ignored.
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.aiTranslateSingle('store_123', {
+   *   entityType: 'product',
+   *   entityId: 'prod_abc',
+   *   targetLocale: 'he',
+   * });
+   * ```
+   */
+  async aiTranslateSingle(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate-single`,
+      input
+    );
+  }
+  /**
+   * Bulk AI-translate — enqueues a background job per entity (and, for
+   * `entityType: 'attribute'`, one per attribute option too) rather than
+   * translating inline. Returns the number of jobs queued, not the finished
+   * translations; poll `getTranslationStatus` or `getTranslations` to see
+   * results land.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param entityIds - Optional explicit ids to translate. Omit to target
+   *   every entity of `entityType` in the store that isn't already fully
+   *   translated for `targetLocale`.
+   *
+   * @example
+   * ```typescript
+   * // Translate every blog post missing French coverage
+   * const { queued } = await client.aiTranslateBulk('store_123', {
+   *   entityType: 'blogPost',
+   *   targetLocale: 'fr',
+   * });
+   * ```
+   */
+  async aiTranslateBulk(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate`,
+      input
+    );
+  }
 };
 /**
  * Fields present on `getAddressDetails().address` that the address endpoints