brainerce 1.58.0 → 1.59.0

package/dist/index.js

@@ -1999,6 +1999,98 @@ var _BrainerceClient = class _BrainerceClient {
   async createProduct(data) {
     return this.request("POST", "/api/v1/products", data);
   }
+  /**
+   * Create many products in one call.
+   *
+   * QUEUED, not immediate: this returns a job id straight away and the products
+   * appear over the following seconds or minutes. It does NOT return the
+   * created products — poll {@link getBulkCreateProductsStatus} with the
+   * returned `jobId`.
+   *
+   * Every field {@link createProduct} accepts is accepted per row, including
+   * variants, categories, brands, tags, images, translations and tax behaviour.
+   *
+   * At most 1000 products per call (500 is the comfortable size). For a
+   * 3,000-50,000 product catalog, send several calls carrying the same
+   * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+   * whole import.
+   *
+   * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+   * rather than duplicated, so re-sending a batch after a timeout cannot create
+   * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+   * return the original job instead of starting a second import.
+   *
+   * @example
+   * ```typescript
+   * const job = await client.bulkCreateProducts({
+   *   products: rows.map((r) => ({
+   *     name: r.title,
+   *     sku: r.sku,
+   *     externalId: r.supplier_id,
+   *     basePrice: Number(r.price),
+   *     type: 'SIMPLE',
+   *     categoryNames: [r.category],
+   *   })),
+   *   importId: 'supplier-catalog-2026-08-21',
+   * });
+   *
+   * let status = await client.getBulkCreateProductsStatus(job.jobId);
+   * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+   *   await new Promise((r) => setTimeout(r, 2000));
+   *   status = await client.getBulkCreateProductsStatus(job.jobId);
+   * }
+   * // `succeeded` is what was created; `skipped` already existed.
+   * console.log(status.succeeded, status.skipped, status.failed);
+   * ```
+   */
+  async bulkCreateProducts(data) {
+    return this.request("POST", "/api/v1/products/bulk", data);
+  }
+  /**
+   * Progress of one queued product import.
+   *
+   * Read the counters literally: `skipped` rows already existed and were NOT
+   * created, so `succeeded` alone is what this import added.
+   *
+   * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+   * that is not something to re-run; read the failures with
+   * {@link getBulkCreateProductsErrors}.
+   */
+  async getBulkCreateProductsStatus(jobId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}`
+    );
+  }
+  /**
+   * Aggregate progress across every batch that shared an `importId`.
+   *
+   * The status is the least-complete state across the chunks, and `finishedAt`
+   * stays null until all of them have finished — so a caller cannot mistake
+   * "the first 500 landed" for "the catalog is imported".
+   */
+  async getBulkCreateProductsImportStatus(importId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/import/${encodePathSegment(importId)}`
+    );
+  }
+  /**
+   * Per-row failures for a product import, paginated.
+   *
+   * Every failure is recorded — nothing is truncated — so walk the pages when
+   * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+   * array you submitted, so a failure maps back to the line of the source
+   * spreadsheet.
+   */
+  async getBulkCreateProductsErrors(jobId, options) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}/errors`,
+      void 0,
+      { page: options?.page, limit: options?.limit }
+    );
+  }
   /**
    * Update an existing product
    */
@@ -3265,11 +3357,18 @@ var _BrainerceClient = class _BrainerceClient {
    * @param options.redirectUrl - Where to send the browser once OAuth finishes —
    *   on success *and* on failure. Validated server-side against the sales
    *   channel's trusted origins, so what is accepted depends on the mode:
-   *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-   *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-   *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-   *     works — it is resolved against the channel's `domain` on the way back,
-   *     so the channel must have one registered.
+   *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+   *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+   *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+   *     `http://` target is refused even on the registered domain. You
+   *     therefore cannot complete social login from `localhost` against a LIVE
+   *     channel; use a TEST channel for that.
+   *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+   *     and port) against one of the channel's `allowedOrigins`, plus any
+   *     `localhost`/`127.0.0.1`/`[::1]` port.
+   *   - Either mode: a relative path (`/auth/callback`) also works — it is
+   *     resolved against the channel's `domain` on the way back, so the channel
+   *     must have one registered.
    *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
    *     No channel is bound to the request, so an absolute URL has no
    *     trusted-origin list to match (400 at this call) and a relative path has
@@ -4106,7 +4205,9 @@ var _BrainerceClient = class _BrainerceClient {
    * try {
    *   await client.createCheckout(cartId);
    * } catch (err) {
-   *   if (err.code === 'PRICE_DRIFT') {
+   *   // BrainerceError.details is the whole response body — the code lives
+   *   // there, NOT on the error object itself.
+   *   if ((err as BrainerceError).details?.code === 'PRICE_DRIFT') {
    *     // ask user to confirm new prices, then:
    *     await client.refreshCartSnapshots(cartId);
    *     await client.createCheckout(cartId);
@@ -5944,6 +6045,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Get applicable custom field definitions for a checkout.
    * Returns fields filtered by visibility conditions (delivery type, products in cart).
    * Use these to render dynamic input fields in the checkout flow.
+   *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
    */
   async getCheckoutCustomFields(checkoutId) {
     if (this.isVibeCodedMode()) {
@@ -5958,15 +6062,18 @@ var _BrainerceClient = class _BrainerceClient {
         `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
-    return this.adminRequest(
-      "GET",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`
+    throw new BrainerceError(
+      "getCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
    * Set checkout custom field values and recalculate surcharges.
    * The checkout total is automatically updated to include surcharges.
    *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomFields(checkoutId, {
@@ -5994,10 +6101,9 @@ var _BrainerceClient = class _BrainerceClient {
         data
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`,
-      data
+    throw new BrainerceError(
+      "setCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
@@ -8263,8 +8369,9 @@ var _BrainerceClient = class _BrainerceClient {
   //         /api/stores/:storeId/products/:productId/modifier-groups[/:attachmentId]
   //
   // Server-side validation failures arrive as a structured 400 envelope:
-  //   { code: 'MODIFIER_VALIDATION_FAILED', errors: ModifierValidationError[] }
-  // surfaced via BrainerceError.details.
+  //   { code: 'MODIFIER_VALIDATION_FAILED', message, details: { errors: [...] } }
+  // BrainerceError.details holds the WHOLE body, so the issue list is
+  // `err.details.details.errors` — see ModifierValidationFailedError.
   /**
    * List modifier groups in a store, paginated.
    * Requires Admin mode (apiKey).
@@ -9316,27 +9423,36 @@ var _BrainerceClient = class _BrainerceClient {
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
-  // These account-level methods are deprecated. Use Store Team Management methods instead.
+  // Account-level team methods. These are the ONLY team endpoints reachable with
+  // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
+  // `inviteStoreMember`, `updateStoreMember`, ...) sit behind
+  // `DashboardOnlyGuard`, which rejects api_key principals by design — so they
+  // return 403 from the SDK, not 404, and "fixing" their path would not help.
+  // Do not migrate SDK code onto them.
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamMembers() {
     return this.adminRequest("GET", "/api/v1/team/members");
   }
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamInvitations() {
     return this.adminRequest("GET", "/api/v1/team/invitations");
   }
   /**
-   * @deprecated Use `inviteStoreMember(storeId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async inviteTeamMember(data) {
     return this.adminRequest("POST", "/api/v1/team/invitations", data);
   }
   /**
-   * @deprecated Use `resendStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async resendTeamInvitation(invitationId) {
     return this.adminRequest(
@@ -9345,7 +9461,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async revokeTeamInvitation(invitationId) {
     await this.adminRequest(
@@ -9354,7 +9471,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async updateTeamMemberRole(memberId, data) {
     return this.adminRequest(
@@ -9364,7 +9482,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async removeTeamMember(memberId) {
     await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);

package/dist/index.mjs

@@ -1911,6 +1911,98 @@ var _BrainerceClient = class _BrainerceClient {
   async createProduct(data) {
     return this.request("POST", "/api/v1/products", data);
   }
+  /**
+   * Create many products in one call.
+   *
+   * QUEUED, not immediate: this returns a job id straight away and the products
+   * appear over the following seconds or minutes. It does NOT return the
+   * created products — poll {@link getBulkCreateProductsStatus} with the
+   * returned `jobId`.
+   *
+   * Every field {@link createProduct} accepts is accepted per row, including
+   * variants, categories, brands, tags, images, translations and tax behaviour.
+   *
+   * At most 1000 products per call (500 is the comfortable size). For a
+   * 3,000-50,000 product catalog, send several calls carrying the same
+   * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+   * whole import.
+   *
+   * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+   * rather than duplicated, so re-sending a batch after a timeout cannot create
+   * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+   * return the original job instead of starting a second import.
+   *
+   * @example
+   * ```typescript
+   * const job = await client.bulkCreateProducts({
+   *   products: rows.map((r) => ({
+   *     name: r.title,
+   *     sku: r.sku,
+   *     externalId: r.supplier_id,
+   *     basePrice: Number(r.price),
+   *     type: 'SIMPLE',
+   *     categoryNames: [r.category],
+   *   })),
+   *   importId: 'supplier-catalog-2026-08-21',
+   * });
+   *
+   * let status = await client.getBulkCreateProductsStatus(job.jobId);
+   * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+   *   await new Promise((r) => setTimeout(r, 2000));
+   *   status = await client.getBulkCreateProductsStatus(job.jobId);
+   * }
+   * // `succeeded` is what was created; `skipped` already existed.
+   * console.log(status.succeeded, status.skipped, status.failed);
+   * ```
+   */
+  async bulkCreateProducts(data) {
+    return this.request("POST", "/api/v1/products/bulk", data);
+  }
+  /**
+   * Progress of one queued product import.
+   *
+   * Read the counters literally: `skipped` rows already existed and were NOT
+   * created, so `succeeded` alone is what this import added.
+   *
+   * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+   * that is not something to re-run; read the failures with
+   * {@link getBulkCreateProductsErrors}.
+   */
+  async getBulkCreateProductsStatus(jobId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}`
+    );
+  }
+  /**
+   * Aggregate progress across every batch that shared an `importId`.
+   *
+   * The status is the least-complete state across the chunks, and `finishedAt`
+   * stays null until all of them have finished — so a caller cannot mistake
+   * "the first 500 landed" for "the catalog is imported".
+   */
+  async getBulkCreateProductsImportStatus(importId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/import/${encodePathSegment(importId)}`
+    );
+  }
+  /**
+   * Per-row failures for a product import, paginated.
+   *
+   * Every failure is recorded — nothing is truncated — so walk the pages when
+   * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+   * array you submitted, so a failure maps back to the line of the source
+   * spreadsheet.
+   */
+  async getBulkCreateProductsErrors(jobId, options) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}/errors`,
+      void 0,
+      { page: options?.page, limit: options?.limit }
+    );
+  }
   /**
    * Update an existing product
    */
@@ -3177,11 +3269,18 @@ var _BrainerceClient = class _BrainerceClient {
    * @param options.redirectUrl - Where to send the browser once OAuth finishes —
    *   on success *and* on failure. Validated server-side against the sales
    *   channel's trusted origins, so what is accepted depends on the mode:
-   *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-   *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-   *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-   *     works — it is resolved against the channel's `domain` on the way back,
-   *     so the channel must have one registered.
+   *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+   *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+   *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+   *     `http://` target is refused even on the registered domain. You
+   *     therefore cannot complete social login from `localhost` against a LIVE
+   *     channel; use a TEST channel for that.
+   *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+   *     and port) against one of the channel's `allowedOrigins`, plus any
+   *     `localhost`/`127.0.0.1`/`[::1]` port.
+   *   - Either mode: a relative path (`/auth/callback`) also works — it is
+   *     resolved against the channel's `domain` on the way back, so the channel
+   *     must have one registered.
    *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
    *     No channel is bound to the request, so an absolute URL has no
    *     trusted-origin list to match (400 at this call) and a relative path has
@@ -4018,7 +4117,9 @@ var _BrainerceClient = class _BrainerceClient {
    * try {
    *   await client.createCheckout(cartId);
    * } catch (err) {
-   *   if (err.code === 'PRICE_DRIFT') {
+   *   // BrainerceError.details is the whole response body — the code lives
+   *   // there, NOT on the error object itself.
+   *   if ((err as BrainerceError).details?.code === 'PRICE_DRIFT') {
    *     // ask user to confirm new prices, then:
    *     await client.refreshCartSnapshots(cartId);
    *     await client.createCheckout(cartId);
@@ -5856,6 +5957,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Get applicable custom field definitions for a checkout.
    * Returns fields filtered by visibility conditions (delivery type, products in cart).
    * Use these to render dynamic input fields in the checkout flow.
+   *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
    */
   async getCheckoutCustomFields(checkoutId) {
     if (this.isVibeCodedMode()) {
@@ -5870,15 +5974,18 @@ var _BrainerceClient = class _BrainerceClient {
         `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
-    return this.adminRequest(
-      "GET",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`
+    throw new BrainerceError(
+      "getCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
    * Set checkout custom field values and recalculate surcharges.
    * The checkout total is automatically updated to include surcharges.
    *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomFields(checkoutId, {
@@ -5906,10 +6013,9 @@ var _BrainerceClient = class _BrainerceClient {
         data
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`,
-      data
+    throw new BrainerceError(
+      "setCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
@@ -8175,8 +8281,9 @@ var _BrainerceClient = class _BrainerceClient {
   //         /api/stores/:storeId/products/:productId/modifier-groups[/:attachmentId]
   //
   // Server-side validation failures arrive as a structured 400 envelope:
-  //   { code: 'MODIFIER_VALIDATION_FAILED', errors: ModifierValidationError[] }
-  // surfaced via BrainerceError.details.
+  //   { code: 'MODIFIER_VALIDATION_FAILED', message, details: { errors: [...] } }
+  // BrainerceError.details holds the WHOLE body, so the issue list is
+  // `err.details.details.errors` — see ModifierValidationFailedError.
   /**
    * List modifier groups in a store, paginated.
    * Requires Admin mode (apiKey).
@@ -9228,27 +9335,36 @@ var _BrainerceClient = class _BrainerceClient {
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
-  // These account-level methods are deprecated. Use Store Team Management methods instead.
+  // Account-level team methods. These are the ONLY team endpoints reachable with
+  // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
+  // `inviteStoreMember`, `updateStoreMember`, ...) sit behind
+  // `DashboardOnlyGuard`, which rejects api_key principals by design — so they
+  // return 403 from the SDK, not 404, and "fixing" their path would not help.
+  // Do not migrate SDK code onto them.
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamMembers() {
     return this.adminRequest("GET", "/api/v1/team/members");
   }
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamInvitations() {
     return this.adminRequest("GET", "/api/v1/team/invitations");
   }
   /**
-   * @deprecated Use `inviteStoreMember(storeId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async inviteTeamMember(data) {
     return this.adminRequest("POST", "/api/v1/team/invitations", data);
   }
   /**
-   * @deprecated Use `resendStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async resendTeamInvitation(invitationId) {
     return this.adminRequest(
@@ -9257,7 +9373,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async revokeTeamInvitation(invitationId) {
     await this.adminRequest(
@@ -9266,7 +9383,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async updateTeamMemberRole(memberId, data) {
     return this.adminRequest(
@@ -9276,7 +9394,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async removeTeamMember(memberId) {
     await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",