brainerce 1.59.0 → 2.0.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.54.0";
+var SDK_VERSION = "2.0.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -272,6 +272,87 @@ var _BrainerceClient = class _BrainerceClient {
         );
       }
     };
+    // -------------------- Marketing signup (newsletter) --------------------
+    /**
+     * Email marketing signup for a storefront — a newsletter popup, a footer
+     * capture bar, an exit-intent modal.
+     *
+     * **Confirmed opt-in, always.** `subscribe()` creates the contact and mails
+     * them a confirmation link. The address is NOT subscribed and CANNOT receive
+     * a campaign until the recipient clicks that link. This is not a setting:
+     * consent has to come from the mailbox, or anyone could subscribe anyone.
+     *
+     * So do not render "You're subscribed!" on success — render "Check your
+     * email to confirm." The one is a lie until the click lands.
+     *
+     * The response is identical for a brand-new address, one that is already
+     * subscribed, and one suppressed after a bounce, so the form can't be used to
+     * probe who shops here. Show the same message for every success.
+     *
+     * Storefront (public) and vibe-coded modes only. Rate-limited server-side to
+     * 3 requests / 60s per IP, plus one confirmation email per address per 24h.
+     *
+     * **Where the discount goes.** A "10% off your first order" popup needs a
+     * coupon from the dashboard — create one with the `customer_first_order`
+     * condition and show the code after a successful call. Subscribing does not
+     * mint a code on its own.
+     *
+     * @example
+     * ```typescript
+     * // Newsletter popup — hidden honeypot input, Hebrew storefront
+     * await brainerce.marketing.subscribe({
+     *   email: 'jane@example.com',
+     *   locale: 'he',
+     *   source: 'popup',
+     *   honeypot: hiddenFieldValue,
+     * });
+     * // → show "בדקו את המייל שלכם כדי לאשר" — NOT "נרשמת בהצלחה"
+     * ```
+     */
+    this.marketing = {
+      subscribe: async (input) => {
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest(
+            "POST",
+            "/marketing/subscribe",
+            input
+          );
+        }
+        return this.storefrontRequest(
+          "POST",
+          "/marketing/subscribe",
+          input
+        );
+      }
+    };
+    // -------------------- Stock alerts --------------------
+    /**
+     * "Email me when this is back."
+     *
+     * ⛔ Not a newsletter signup, and must not be worded as one. It grants no
+     * marketing consent, creates no customer account, and the person is never
+     * mailed anything else as a result — exactly one message, about this item,
+     * with a link that stops it. Someone who unsubscribed from marketing can
+     * still use this, so do not gate it on consent.
+     *
+     * Show the affordance only on an item that is out of stock AND cannot be
+     * backordered. Every other case is silently ignored server-side — the
+     * response is uniform on purpose, so it cannot be used to read stock levels
+     * or test who is a customer — which means a button on an in-stock item looks
+     * like it worked and does nothing.
+     *
+     * Pass `variantId` on any product with variants. Without it the alert waits
+     * on the product as a whole, and a shopper who wanted the medium hears when
+     * the small comes back.
+     */
+    this.stockAlerts = {
+      subscribe: async (input) => {
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("POST", "/stock-alerts", input);
+        }
+        return this.storefrontRequest("POST", "/stock-alerts", input);
+      }
+    };
     // -------------------- Content (typed merchant content) --------------------
     /**
      * Typed merchant content store: FAQ, Footer, Header, Announcement,
@@ -480,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(
@@ -2314,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)
+   * Create a refund for an order.
    *
-   * @example
-   * ```typescript
-   * // Full refund
-   * const refund = await client.createRefund('order_123', {
-   *   type: 'full',
-   *   restockInventory: true,
-   *   notifyCustomer: true,
-   *   reason: 'Customer request',
-   * });
-   *
-   * // 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
     );
   }
   /**
@@ -2488,17 +2551,19 @@ 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
+   * Cancel an order.
    *
-   * @example
-   * ```typescript
-   * const order = await client.cancelOrder('order_123');
-   * console.log('Order status:', order.status); // 'cancelled'
-   * ```
+   * **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
@@ -2512,110 +2577,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 --------------------
   /**
@@ -2630,82 +2672,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
@@ -2737,9 +2788,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.
@@ -3046,6 +3098,11 @@ var _BrainerceClient = class _BrainerceClient {
    * Register a new customer with password (creates account)
    * Works in vibe-coded, storefront, and admin mode
    *
+   * `birthMonth`/`birthDay` are optional and must be sent together. When
+   * `getStoreInfo().requireBirthday` is true the merchant made the birthday
+   * mandatory on that sales channel, and a call without both fields is
+   * rejected with HTTP 400.
+   *
    * @example
    * ```typescript
    * const auth = await client.registerCustomer({
@@ -3053,6 +3110,8 @@ var _BrainerceClient = class _BrainerceClient {
    *   password: 'securepassword123',
    *   firstName: 'Jane',
    *   lastName: 'Doe',
+   *   birthMonth: 4, // optional, unless the channel requires a birthday
+   *   birthDay: 17,
    * });
    * ```
    */
@@ -3069,49 +3128,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
@@ -4331,16 +4384,27 @@ var _BrainerceClient = class _BrainerceClient {
    * List visible reviews for a product (storefront / sales-channel modes).
    * Reviews that the merchant has hidden are excluded.
    *
+   * Each review carries `images` — the photos its author attached, already
+   * filtered to the ones shoppers are allowed to see. Always an array.
+   *
+   * Ordering defaults to `photos_first`: reviews carrying photos lead, newest-first
+   * within each group. Pass `sort: 'newest'` for plain chronological order. On a
+   * store with no review photos the two are identical.
+   *
    * @example
    * ```typescript
    * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
-   * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+   * data.forEach(r => {
+   *   console.log(r.rating, r.body, r.verifiedPurchase);
+   *   r.images.forEach(img => console.log(img.thumbnailUrl ?? img.url));
+   * });
    * ```
    */
   async listProductReviews(productId, params) {
     const queryParams = {};
     if (params?.page) queryParams.page = params.page;
     if (params?.limit) queryParams.limit = params.limit;
+    if (params?.sort) queryParams.sort = params.sort;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -4498,6 +4562,37 @@ var _BrainerceClient = class _BrainerceClient {
       storeId ? { storeId } : void 0
     );
   }
+  /**
+   * Admin: hide ONE photo on a review, leaving the review and its other photos
+   * visible. Requires an API key with `reviews:write`.
+   */
+  async hideProductReviewImage(imageId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("hideProductReviewImage() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/review-images/${encodePathSegment(imageId)}/hide`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
+  /**
+   * Admin: show one review photo. This is also the approve action — a photo that
+   * has never been approved carries no `approvedAt`, and showing it stamps one, so
+   * stores using review-photo approval need no separate verb.
+   */
+  async showProductReviewImage(imageId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("showProductReviewImage() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/review-images/${encodePathSegment(imageId)}/show`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
   /** Admin: unhide a previously hidden review. */
   async showProductReview(reviewId, storeId) {
     if (!this.apiKey) {
@@ -7153,11 +7248,20 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * Update the current customer's profile (requires customerToken)
-   * Only available in storefront mode
+   * Update the current customer's profile (requires customerToken).
+   * Only available in storefront and vibe-coded mode.
    *
-   * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
-   * birthday gift; they must be provided together.
+   * `birthMonth`/`birthDay` (1-12 / 1-31) power the loyalty birthday gift.
+   * Month and day only, never a year, for privacy. Send both or neither, and
+   * the day has to exist in the month: anything else is rejected with HTTP 400.
+   * Send `null` for both to REMOVE a stored birthday. Leaving the keys out is a
+   * different request and keeps the stored value, so a profile form whose
+   * fields the shopper cleared has to send nulls, not omit them.
+   *
+   * The saved values now come back on the returned `CustomerProfile`, on
+   * `getMyProfile()` and on every customer read type, so a profile form can
+   * re-render the birthday it just saved. Before this, no API returned the two
+   * fields at all and the form always came back blank.
    */
   async updateMyProfile(data) {
     if (!this.customerToken && !this.proxyMode) {
@@ -9334,6 +9438,68 @@ var _BrainerceClient = class _BrainerceClient {
     }
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
+  /**
+   * Upload one photo to attach to a product review.
+   *
+   * Available in storefront and vibe-coded modes, and — unlike
+   * `uploadCustomizationFile` — it REQUIRES a logged-in customer who has actually
+   * bought the product. Call `setCustomerToken(...)` first. That is the same bar as
+   * writing the review itself, checked here so an ineligible shopper is told before
+   * they wait for the upload rather than after.
+   *
+   * Returns a storage `key`. Collect the keys and pass them as `imageKeys` when you
+   * submit or update the review — the `url` is for a local preview only, and sending
+   * it back instead of the key will be rejected.
+   *
+   * Server rules:
+   * - `image/jpeg|png|webp|gif` only, cross-checked against the file's real bytes.
+   * - Max 5 MB and 40 megapixels per file.
+   * - Throttled to 10 uploads / minute → HTTP 429.
+   * - 403 when the store has review photos turned off, or the customer has not
+   *   bought the product; 400 once the review is already at its photo cap.
+   * - EXIF is stripped (so GPS coordinates never reach the storefront) while the
+   *   orientation tag is applied first, so phone photos stay upright.
+   * - A photo uploaded but never attached to a submitted review is reclaimed after
+   *   7 days.
+   *
+   * Read `photos` from `getMyProductReview()` for the store's live limits rather
+   * than hard-coding them.
+   *
+   * @example
+   * ```ts
+   * const { photos } = await client.getMyProductReview(productId);
+   * if (photos.enabled) {
+   *   const uploads = await Promise.all(
+   *     [...fileInput.files].slice(0, photos.maxPerReview)
+   *       .map(f => client.uploadReviewPhoto(productId, f))
+   *   );
+   *   await client.submitProductReview(productId, {
+   *     rating: 5,
+   *     body: 'Arrived beautifully wrapped.',
+   *     imageKeys: uploads.map(u => u.key),
+   *   });
+   * }
+   * ```
+   */
+  async uploadReviewPhoto(productId, file) {
+    const formData = new FormData();
+    formData.append("file", file);
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/review-photo`,
+        formData
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/review-photo`,
+        formData
+      );
+    }
+    throw new Error("uploadReviewPhoto requires storefront or vibe-coded mode");
+  }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
   // Account-level team methods. These are the ONLY team endpoints reachable with
   // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
@@ -10021,7 +10187,7 @@ var DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\
 var MIN_OFFSET_MINUTES = -12 * 60;
 var MAX_OFFSET_MINUTES = 14 * 60;
 var VALID_OFFSET_MINUTE_PARTS = [0, 30, 45];
-function validateDateAvailabilityConfig(config, fieldType) {
+function validateDateAvailabilityConfig(config, fieldType, surface = "checkout") {
   const errors = [];
   if (!config) return errors;
   if (config.minDate !== void 0 && !DATE_RE.test(config.minDate)) {
@@ -10033,6 +10199,29 @@ function validateDateAvailabilityConfig(config, fieldType) {
   if (config.minDate && config.maxDate && DATE_RE.test(config.minDate) && DATE_RE.test(config.maxDate) && config.minDate > config.maxDate) {
     errors.push("minDate must be on or before maxDate");
   }
+  if (config.leadTimeMinutes !== void 0) {
+    if (!Number.isInteger(config.leadTimeMinutes) || config.leadTimeMinutes < 0) {
+      errors.push("leadTimeMinutes must be a non-negative integer");
+    }
+  }
+  if (config.maxDaysAhead !== void 0) {
+    if (!Number.isInteger(config.maxDaysAhead) || config.maxDaysAhead < 1) {
+      errors.push("maxDaysAhead must be a positive integer");
+    }
+  }
+  if (config.cutoffTime !== void 0 && !TIME_RE.test(config.cutoffTime)) {
+    errors.push("cutoffTime must be in HH:mm format");
+  }
+  if (surface !== "checkout") {
+    const relativeKeys = ["leadTimeMinutes", "cutoffTime", "maxDaysAhead"].filter(
+      (k) => config[k] !== void 0
+    );
+    if (relativeKeys.length > 0) {
+      errors.push(
+        `${relativeKeys.join("/")} only apply to checkout fields, not ${surface} fields`
+      );
+    }
+  }
   if (config.blockedWeekdays) {
     for (const d of config.blockedWeekdays) {
       if (!Number.isInteger(d) || d < 0 || d > 6) {
@@ -10050,22 +10239,37 @@ function validateDateAvailabilityConfig(config, fieldType) {
     }
   }
   if (config.businessHours) {
-    const seenWeekdays = /* @__PURE__ */ new Set();
+    const windowsByWeekday = /* @__PURE__ */ new Map();
     for (const w of config.businessHours) {
       if (!Number.isInteger(w.weekday) || w.weekday < 0 || w.weekday > 6) {
         errors.push(`businessHours.weekday must be an integer 0-6, got ${JSON.stringify(w.weekday)}`);
         continue;
       }
-      if (seenWeekdays.has(w.weekday)) {
-        errors.push(`businessHours has more than one window for weekday ${w.weekday}`);
-      }
-      seenWeekdays.add(w.weekday);
       const openValid = TIME_RE.test(w.open);
       const closeValid = TIME_RE.test(w.close);
       if (!openValid) errors.push(`businessHours.open must be HH:mm, got "${w.open}"`);
       if (!closeValid) errors.push(`businessHours.close must be HH:mm, got "${w.close}"`);
-      if (openValid && closeValid && w.open >= w.close) {
+      if (!openValid || !closeValid) continue;
+      if (w.open >= w.close) {
         errors.push(`businessHours for weekday ${w.weekday}: open must be before close`);
+        continue;
+      }
+      const forDay = windowsByWeekday.get(w.weekday);
+      if (forDay) forDay.push(w);
+      else windowsByWeekday.set(w.weekday, [w]);
+    }
+    const weekdaysWithWindows = Array.from(windowsByWeekday.keys()).sort((a, b) => a - b);
+    for (const weekday of weekdaysWithWindows) {
+      const sorted = [...windowsByWeekday.get(weekday) ?? []].sort(
+        (a, b) => a.open < b.open ? -1 : a.open > b.open ? 1 : 0
+      );
+      for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i].open < sorted[i - 1].close) {
+          errors.push(
+            `businessHours for weekday ${weekday}: ${sorted[i - 1].open}-${sorted[i - 1].close} overlaps ${sorted[i].open}-${sorted[i].close}`
+          );
+          break;
+        }
       }
     }
   }
@@ -10121,6 +10325,32 @@ function resolveStoreLocalParts(instant, timezone) {
     weekday: WEEKDAY_TO_INDEX[get("weekday")] ?? instant.getUTCDay()
   };
 }
+function resolveRelativeBounds(config, clock) {
+  if (!config || !clock) return {};
+  const leadMinutes = typeof config.leadTimeMinutes === "number" && Number.isFinite(config.leadTimeMinutes) ? Math.max(0, Math.floor(config.leadTimeMinutes)) : 0;
+  const cutoff = typeof config.cutoffTime === "string" && TIME_RE.test(config.cutoffTime) ? config.cutoffTime : null;
+  const daysAhead = typeof config.maxDaysAhead === "number" && Number.isFinite(config.maxDaysAhead) && config.maxDaysAhead >= 1 ? Math.floor(config.maxDaysAhead) : null;
+  if (leadMinutes === 0 && !cutoff && daysAhead === null) return {};
+  const now = clock.now ?? /* @__PURE__ */ new Date();
+  const nowLocal = resolveStoreLocalParts(now, clock.timezone);
+  const bounds = {};
+  if (leadMinutes > 0 || cutoff) {
+    const earliestInstant = new Date(now.getTime() + leadMinutes * 6e4);
+    let earliestDate = resolveStoreLocalParts(earliestInstant, clock.timezone).dateYYYYMMDD;
+    if (cutoff && nowLocal.hhmm >= cutoff) earliestDate = addCalendarDays(earliestDate, 1);
+    bounds.earliestDate = earliestDate;
+    if (leadMinutes > 0) bounds.earliestInstant = earliestInstant;
+  }
+  if (daysAhead !== null) {
+    bounds.latestDate = addCalendarDays(nowLocal.dateYYYYMMDD, daysAhead);
+  }
+  return bounds;
+}
+function addCalendarDays(dateYYYYMMDD, days) {
+  const [year, month, day] = dateYYYYMMDD.split("-").map(Number);
+  const shifted = new Date(Date.UTC(year, month - 1, day + days));
+  return `${shifted.getUTCFullYear()}-${pad2(shifted.getUTCMonth() + 1)}-${pad2(shifted.getUTCDate())}`;
+}
 function parseDateFieldValue(raw, fieldType, timezone) {
   const str = raw instanceof Date ? Number.isNaN(raw.getTime()) ? "" : raw.toISOString() : typeof raw === "string" ? raw.trim() : "";
   const expected = fieldType === "DATE" ? "expected a calendar date in YYYY-MM-DD format" : "expected an ISO-8601 date/time such as 2026-08-13T13:00:00+03:00";
@@ -10216,19 +10446,30 @@ function timezoneOffsetMs(utcMillis, timezone) {
   const asIfUtc = Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second"));
   return asIfUtc - Math.floor(utcMillis / 1e3) * 1e3;
 }
-function isCalendarDateAllowed(dateYYYYMMDD, config) {
+function isCalendarDateAllowed(dateYYYYMMDD, config, clock) {
   if (!config) return true;
   if (config.minDate && dateYYYYMMDD < config.minDate) return false;
   if (config.maxDate && dateYYYYMMDD > config.maxDate) return false;
+  if (relativeBoundFailure(dateYYYYMMDD, config, clock)) return false;
   if (config.blockedDates?.includes(dateYYYYMMDD)) return false;
   if (config.blockedWeekdays?.length) {
     if (config.blockedWeekdays.includes(weekdayOfDateString(dateYYYYMMDD))) return false;
   }
   return true;
 }
-function computeAvailableSlots(config, dateYYYYMMDD) {
+function relativeBoundFailure(dateYYYYMMDD, config, clock) {
+  const bounds = resolveRelativeBounds(config, clock);
+  if (bounds.earliestDate && dateYYYYMMDD < bounds.earliestDate) {
+    return `the earliest available date is ${bounds.earliestDate}`;
+  }
+  if (bounds.latestDate && dateYYYYMMDD > bounds.latestDate) {
+    return `the latest available date is ${bounds.latestDate}`;
+  }
+  return null;
+}
+function computeAvailableSlots(config, dateYYYYMMDD, clock) {
   if (!config) return [];
-  if (!isCalendarDateAllowed(dateYYYYMMDD, config)) return [];
+  if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) return [];
   if (!config.businessHours?.length || !config.slotDurationMinutes) return [];
   const weekday = weekdayOfDateString(dateYYYYMMDD);
   const windows = config.businessHours.filter((w) => w.weekday === weekday);
@@ -10241,27 +10482,47 @@ function computeAvailableSlots(config, dateYYYYMMDD) {
       slots.push(minutesToHHMM(t));
     }
   }
-  return slots;
+  const ordered = Array.from(new Set(slots)).sort();
+  const { earliestInstant } = resolveRelativeBounds(config, clock);
+  if (!earliestInstant || !clock) return ordered;
+  return ordered.filter((hhmm) => {
+    const [hour, minute] = hhmm.split(":").map(Number);
+    const start = instantFromStoreLocal(dateYYYYMMDD, hour, minute, 0, 0, clock.timezone);
+    return start.getTime() >= earliestInstant.getTime();
+  });
 }
-function getBusinessHoursForDate(config, dateYYYYMMDD) {
+function getBusinessHoursForDate(config, dateYYYYMMDD, clock) {
   if (!config?.businessHours?.length) return [];
-  if (!isCalendarDateAllowed(dateYYYYMMDD, config)) return [];
+  if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) return [];
   const weekday = weekdayOfDateString(dateYYYYMMDD);
   return config.businessHours.filter((w) => w.weekday === weekday);
 }
-function isDateValueAllowed(instant, config, fieldType, timezone) {
+function isDateValueAllowed(instant, config, fieldType, timezone, now) {
   if (!config) return { allowed: true };
+  const clock = { timezone, now };
   if (fieldType === "DATE") {
     const dateYYYYMMDD = `${instant.getUTCFullYear()}-${pad2(instant.getUTCMonth() + 1)}-${pad2(instant.getUTCDate())}`;
-    if (!isCalendarDateAllowed(dateYYYYMMDD, config)) {
+    const relative2 = relativeBoundFailure(dateYYYYMMDD, config, clock);
+    if (relative2) return { allowed: false, reason: relative2 };
+    if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) {
       return { allowed: false, reason: "date is outside the allowed range" };
     }
     return { allowed: true };
   }
   const local = resolveStoreLocalParts(instant, timezone);
-  if (!isCalendarDateAllowed(local.dateYYYYMMDD, config)) {
+  const relative = relativeBoundFailure(local.dateYYYYMMDD, config, clock);
+  if (relative) return { allowed: false, reason: relative };
+  if (!isCalendarDateAllowed(local.dateYYYYMMDD, config, clock)) {
     return { allowed: false, reason: "date is outside the allowed range" };
   }
+  const { earliestInstant } = resolveRelativeBounds(config, clock);
+  if (earliestInstant && instant.getTime() < earliestInstant.getTime()) {
+    const earliestLocal = resolveStoreLocalParts(earliestInstant, timezone);
+    return {
+      allowed: false,
+      reason: `the earliest available time is ${earliestLocal.dateYYYYMMDD} ${earliestLocal.hhmm}`
+    };
+  }
   if (!config.businessHours?.length) {
     return { allowed: true };
   }
@@ -10270,7 +10531,7 @@ function isDateValueAllowed(instant, config, fieldType, timezone) {
     return { allowed: false, reason: "no business hours are configured for this day" };
   }
   if (config.slotDurationMinutes) {
-    const slots = computeAvailableSlots(config, local.dateYYYYMMDD);
+    const slots = computeAvailableSlots(config, local.dateYYYYMMDD, clock);
     if (!slots.includes(local.hhmm)) {
       return { allowed: false, reason: "time does not match an available slot" };
     }
@@ -10900,6 +11161,7 @@ export {
   jsonLdScriptProps,
   parseDateFieldValue,
   parseWebhookEvent,
+  resolveRelativeBounds,
   resolveStoreLocalParts,
   safePaymentRedirect,
   stripHtml2 as stripHtml,