brainerce 1.63.0 → 2.0.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.60.0";
+var SDK_VERSION = "2.0.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -650,7 +650,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(
@@ -2484,115 +2484,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
     );
   }
   /**
@@ -2658,17 +2640,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
@@ -2682,110 +2666,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 --------------------
   /**
@@ -2800,82 +2761,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
+   * 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 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
@@ -2907,9 +2877,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.
@@ -3246,49 +3217,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