brainerce 2.4.0 → 2.7.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.0";
+var SDK_VERSION = "2.7.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -381,10 +381,14 @@ var _BrainerceClient = class _BrainerceClient {
      * 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.
+     * **Where the discount goes.** Configure the newsletter welcome offer and the
+     * platform issues the coupon itself: read it with `marketing.getBenefit()`,
+     * show those terms beside the field, and stop there.
+     *
+     * ⛔ DO NOT SHOW A CODE AFTER THIS CALL RESOLVES. No coupon exists yet. It is
+     * minted when the recipient clicks the confirmation link, and it is mailed to
+     * them at that moment — a code rendered here is a code that was never issued.
+     * Say "check your email", the same as for the subscription itself.
      *
      * @example
      * ```typescript
@@ -412,6 +416,163 @@ var _BrainerceClient = class _BrainerceClient {
           "/marketing/subscribe",
           input
         );
+      },
+      /**
+       * The welcome offer to render beside the signup field, or `null` when this
+       * store offers none.
+       *
+       * Show the discount, how long the coupon lasts, any minimum order, whether
+       * it is first-order only, and the merchant's own headline and terms. Then
+       * post to `marketing.subscribe()` and tell the shopper to check their
+       * inbox.
+       *
+       * ⛔ THE COUPON DOES NOT EXIST YET at any point in that sequence. It is
+       * created when the recipient clicks the confirmation link in their email,
+       * and it is mailed to them there. Rendering a code on this screen renders a
+       * code nobody was issued.
+       *
+       * ⛔ Takes no email address and returns nothing about any individual, on
+       * purpose. There is no "has this person already claimed" call, because an
+       * unauthenticated one would be an oracle for who shops here. If you need to
+       * discourage a repeat signup, say the offer is one per address; do not try
+       * to detect it.
+       *
+       * `null` is the common case on a store that never set this up, so handle it
+       * rather than assuming the object. Cache it per page load: it belongs to
+       * the store, not to the visitor.
+       *
+       * Storefront (public) and vibe-coded modes.
+       *
+       * @param locale - Storefront locale, e.g. `"he"`. Picks the language of the
+       *   headline and terms; falls back to the store language when omitted.
+       *
+       * @example
+       * ```typescript
+       * const offer = await brainerce.marketing.getBenefit('he');
+       * if (offer) {
+       *   // "10% הנחה על ההזמנה הראשונה"
+       *   render(offer.headline ?? defaultHeadline(offer), offer.terms);
+       * }
+       * await brainerce.marketing.subscribe({ email, locale: 'he', honeypot });
+       * // → "בדקו את המייל שלכם" — never a coupon code
+       * ```
+       */
+      getBenefit: async (locale) => {
+        const query = locale ? { locale } : void 0;
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest(
+            "GET",
+            "/newsletter-benefit",
+            void 0,
+            query
+          );
+        }
+        return this.storefrontRequest(
+          "GET",
+          "/newsletter-benefit",
+          void 0,
+          query
+        );
+      }
+    };
+    // -------------------- Newsletter signup benefit (Admin) --------------------
+    /**
+     * Manage the newsletter welcome offer: the terms merchants configure, and the
+     * benefits that offer has produced.
+     *
+     * Admin mode (`apiKey`) only, on the `coupons:read` / `coupons:write` scopes.
+     * The benefit IS a coupon feature — it mints a Coupon row and the coupon
+     * machinery enforces it — so it carries no scope of its own.
+     *
+     * ⛔ THERE IS NO "ISSUE A BENEFIT TO THIS ADDRESS" CALL, and there will not
+     * be one. A benefit exists because someone submitted the signup form AND
+     * clicked the confirmation link; handing one out directly would skip the
+     * consent the double opt-in exists to collect and break the one-per-address
+     * guarantee that the grant's unique constraint provides. `resend` re-sends a
+     * code that already exists; it never creates one.
+     */
+    this.newsletterBenefit = {
+      /**
+       * The store's configuration, or `null` when none was ever saved.
+       *
+       * `null` and `{ enabled: false }` are different: never configured, versus
+       * configured and switched off. Both mean "offer nothing" to a storefront.
+       */
+      getSettings: async () => {
+        return this.adminRequest(
+          "GET",
+          "/api/v1/newsletter-benefit/settings"
+        );
+      },
+      /**
+       * Create or replace the offer.
+       *
+       * ⛔ A FULL REPLACEMENT, not a patch. Every field is written, so a field you
+       * omit is cleared rather than kept.
+       *
+       * Saving never rewrites a promise already made: signups still waiting for a
+       * confirmation click keep the terms they were shown, and coupons already
+       * issued are untouched. Switching `enabled` off stops new offers and leaves
+       * every issued coupon working until it expires.
+       *
+       * @example
+       * ```typescript
+       * await brainerce.newsletterBenefit.updateSettings({
+       *   enabled: true,
+       *   discountType: 'PERCENTAGE',
+       *   discountValue: 10,
+       *   minimumOrderAmount: 200,
+       *   combinesWithOther: false,
+       *   validityDays: 7,
+       *   eligibilityTtlHours: 168,
+       *   firstOrderOnly: true,
+       *   content: { he: { headline: '10% הנחה על ההזמנה הראשונה' } },
+       * });
+       * ```
+       */
+      updateSettings: async (input) => {
+        return this.adminRequest(
+          "PUT",
+          "/api/v1/newsletter-benefit/settings",
+          input
+        );
+      },
+      /**
+       * Issued benefits, newest first, as `{ data, meta }`.
+       *
+       * ⛔ NO EMAIL FILTER — the API refuses the parameter. Filter the page you
+       * get back rather than asking the server about one address.
+       */
+      listGrants: async (params = {}) => {
+        return this.adminRequest(
+          "GET",
+          "/api/v1/newsletter-benefit/grants",
+          void 0,
+          {
+            page: params.page,
+            limit: params.limit,
+            status: params.status,
+            from: params.from,
+            to: params.to
+          }
+        );
+      },
+      /**
+       * Re-send one benefit that went astray.
+       *
+       * ⛔ SENDS THE SAME CODE. It never mints a second coupon, so a support
+       * ticket cannot become two discounts. For a benefit whose issuance failed
+       * before any coupon existed, this retries the issuance and mails the result.
+       *
+       * Rejects a signup that has not been confirmed and one that lapsed before a
+       * coupon was minted: there is nothing to re-send in either case, and
+       * nothing that may be created.
+       */
+      resend: async (grantId) => {
+        return this.adminRequest(
+          "POST",
+          `/api/v1/newsletter-benefit/grants/${encodePathSegment(grantId)}/resend`
+        );
       }
     };
     // -------------------- Stock alerts --------------------
@@ -448,10 +609,20 @@ var _BrainerceClient = class _BrainerceClient {
      * Rich Text, and Page.
      *
      * Works in all three SDK modes (vibe-coded, storefront, admin):
-     *   - **Public reads** (`get`, `list`, `getBySlug`): work in any mode.
-     *   - **Write operations** (`create`, `update`, `publish`, `unpublish`,
-     *     `remove`): admin mode only — they call `/api/content/...` with
-     *     the API key. Calling from storefront / vibe-coded mode throws.
+     *   - **Public reads** (`get`, `list`, `getBySlug`): storefront and
+     *     vibe-coded mode. There is no admin equivalent of a by-key/by-slug
+     *     read — in admin mode they throw and point you at `listAdmin()` /
+     *     `findById()`.
+     *   - **Admin reads** (`listAdmin`, `findById`) and **writes** (`create`,
+     *     `update`, `publish`, `unpublish`, `remove`): admin mode only — they
+     *     call `/api/content/...` with the API key. Calling from storefront /
+     *     vibe-coded mode throws.
+     *
+     * **⚠️ Every admin method takes an explicit `storeId`.** Admin mode has no
+     * ambient store (`storeId` is only set in storefront mode), and the routes
+     * are store-scoped: omitting it is rejected fail-closed by the store scope
+     * guard (`403 STORE_SCOPE_REQUIRED`). Pass the id of the store your API key
+     * is bound to — naming any other store is rejected as cross-tenant.
      *
      * **Default key:** every type has `'main'` as its universal default key.
      * Pass no argument to fetch the main entry; pass a custom key (e.g.
@@ -476,12 +647,15 @@ var _BrainerceClient = class _BrainerceClient {
      *   });
      * }
      *
-     * // Admin — create a shipping FAQ in DRAFT
-     * await client.content.faq.create({
-     *   key: 'shipping',
-     *   name: 'Shipping FAQ',
-     *   data: { items: [{ question: '…', answer: '…' }] },
-     * });
+     * // Admin — create a shipping FAQ in DRAFT (storeId is required)
+     * await client.content.faq.create(
+     *   {
+     *     key: 'shipping',
+     *     name: 'Shipping FAQ',
+     *     data: { items: [{ question: '…', answer: '…' }] },
+     *   },
+     *   'store_123'
+     * );
      * ```
      */
     this.content = (() => {
@@ -502,7 +676,7 @@ var _BrainerceClient = class _BrainerceClient {
           return this.storefrontRequest("GET", path, void 0, query).catch(onNotFound);
         }
         throw new BrainerceError(
-          "content.<type>.get(key) is a public-read API. In admin mode, call client.content.list({ type }) and filter by key, or use client.content.findById(id).",
+          "content.<type>.get(key) is a public-read API. In admin mode, call client.content.listAdmin({ storeId, type: '" + type + "' }) and filter by key, or client.content.findById(id, storeId) if you already hold the id.",
           400
         );
       };
@@ -515,9 +689,9 @@ var _BrainerceClient = class _BrainerceClient {
         if (this.storeId && !this.apiKey) {
           return this.storefrontRequest("GET", "/content", void 0, query);
         }
-        return this.adminRequest(
-          "GET",
-          `${adminBase()}?type=${encodeURIComponent(type)}`
+        throw new BrainerceError(
+          "content.<type>.list() is a public-read API. In admin mode, call client.content.listAdmin({ storeId, type: '" + type + "' }).",
+          400
         );
       };
       const requireAdmin = (action) => {
@@ -528,32 +702,59 @@ var _BrainerceClient = class _BrainerceClient {
           );
         }
       };
-      const createByType = async (type, input) => {
+      const requireStoreId = (action, storeId) => {
+        if (!storeId) {
+          throw new BrainerceError(
+            `client.content.${action}() requires a storeId. Admin mode has no ambient store \u2014 pass the id of the store your API key is bound to.`,
+            400
+          );
+        }
+        return { storeId };
+      };
+      const createByType = async (type, input, storeId) => {
         requireAdmin("create");
-        return this.adminRequest("POST", adminBase(), { ...input, type });
+        return this.adminRequest(
+          "POST",
+          adminBase(),
+          { ...input, type },
+          requireStoreId("create", storeId)
+        );
       };
-      const updateById = async (id, input) => {
+      const updateById = async (id, input, storeId) => {
         requireAdmin("update");
         return this.adminRequest(
           "PATCH",
           `${adminBase()}/${encodeURIComponent(id)}`,
-          input
+          input,
+          requireStoreId("update", storeId)
         );
       };
-      const publishById = async (id) => {
+      const publishById = async (id, storeId) => {
         requireAdmin("publish");
-        return this.adminRequest("POST", `${adminBase()}/${encodeURIComponent(id)}/publish`);
+        return this.adminRequest(
+          "POST",
+          `${adminBase()}/${encodeURIComponent(id)}/publish`,
+          void 0,
+          requireStoreId("publish", storeId)
+        );
       };
-      const unpublishById = async (id) => {
+      const unpublishById = async (id, storeId) => {
         requireAdmin("unpublish");
         return this.adminRequest(
           "POST",
-          `${adminBase()}/${encodeURIComponent(id)}/unpublish`
+          `${adminBase()}/${encodeURIComponent(id)}/unpublish`,
+          void 0,
+          requireStoreId("unpublish", storeId)
         );
       };
-      const removeById = async (id) => {
+      const removeById = async (id, storeId) => {
         requireAdmin("remove");
-        await this.adminRequest("DELETE", `${adminBase()}/${encodeURIComponent(id)}`);
+        await this.adminRequest(
+          "DELETE",
+          `${adminBase()}/${encodeURIComponent(id)}`,
+          void 0,
+          requireStoreId("remove", storeId)
+        );
       };
       function makeNamespace(type) {
         return {
@@ -563,10 +764,17 @@ var _BrainerceClient = class _BrainerceClient {
            * hasn't seeded yet.
            */
           get: (key = DEFAULT_KEY, locale) => publicGet(type, key, locale),
-          /** List all PUBLISHED entries of this type. */
+          /**
+           * List all PUBLISHED entries of this type (storefront / vibe-coded
+           * mode). In admin mode this throws — use
+           * `client.content.listAdmin({ storeId, type })`.
+           */
           list: (locale) => publicList(type, locale),
-          /** Create a new entry in DRAFT (admin mode). */
-          create: (input) => createByType(type, input)
+          /**
+           * Create a new entry in DRAFT (admin mode).
+           * `storeId` is required — see the namespace docs above.
+           */
+          create: (input, storeId) => createByType(type, input, storeId)
         };
       }
       return {
@@ -606,30 +814,78 @@ var _BrainerceClient = class _BrainerceClient {
           }
         },
         // ---------- Admin operations (cross-type) ----------
-        /** Find a single row by its admin id (admin mode). */
-        findById: async (id) => {
+        /**
+         * Find a single row by its admin id (admin mode).
+         *
+         * @example
+         * ```typescript
+         * const row = await client.content.findById('cnt_123', 'store_123');
+         * ```
+         */
+        findById: async (id, storeId) => {
           requireAdmin("findById");
-          return this.adminRequest("GET", `${adminBase()}/${encodeURIComponent(id)}`);
-        },
-        /** List rows in admin mode with optional filters. */
-        listAdmin: async (filters) => {
-          requireAdmin("listAdmin");
-          const params = new URLSearchParams();
-          if (filters?.type) params.set("type", filters.type);
-          if (filters?.status) params.set("status", filters.status);
-          const qs = params.toString();
           return this.adminRequest(
             "GET",
-            qs ? `${adminBase()}?${qs}` : adminBase()
+            `${adminBase()}/${encodeURIComponent(id)}`,
+            void 0,
+            requireStoreId("findById", storeId)
           );
         },
-        /** Replace `data` (and optional metadata) on an existing row. */
+        /**
+         * List rows in admin mode. `storeId` is required; `type` and `status`
+         * are optional filters.
+         *
+         * @example
+         * ```typescript
+         * const faqs = await client.content.listAdmin({
+         *   storeId: 'store_123',
+         *   type: 'FAQ',
+         *   status: 'DRAFT',
+         * });
+         * ```
+         */
+        listAdmin: async (filters) => {
+          requireAdmin("listAdmin");
+          const query = requireStoreId("listAdmin", filters?.storeId);
+          if (filters.type) query.type = filters.type;
+          if (filters.status) query.status = filters.status;
+          return this.adminRequest("GET", adminBase(), void 0, query);
+        },
+        /**
+         * Replace `data` (and optional metadata) on an existing row.
+         *
+         * @example
+         * ```typescript
+         * await client.content.update('cnt_123', { name: 'Shipping FAQ' }, 'store_123');
+         * ```
+         */
         update: updateById,
-        /** Transition status DRAFT → PUBLISHED. */
+        /**
+         * Transition status DRAFT → PUBLISHED.
+         *
+         * @example
+         * ```typescript
+         * await client.content.publish('cnt_123', 'store_123');
+         * ```
+         */
         publish: publishById,
-        /** Transition status PUBLISHED → DRAFT. */
+        /**
+         * Transition status PUBLISHED → DRAFT.
+         *
+         * @example
+         * ```typescript
+         * await client.content.unpublish('cnt_123', 'store_123');
+         * ```
+         */
         unpublish: unpublishById,
-        /** Hard delete the row. Admin mode only. */
+        /**
+         * Hard delete the row. Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * await client.content.remove('cnt_123', 'store_123');
+         * ```
+         */
         remove: removeById
       };
     })();
@@ -637,15 +893,26 @@ var _BrainerceClient = class _BrainerceClient {
     /**
      * Read and manage blog posts.
      *
+     * **⚠️ Every admin call takes an explicit `storeId`.** Admin mode has no
+     * ambient store (`storeId` is only set in storefront mode) and the admin
+     * routes are store-scoped: omitting it is rejected fail-closed by the store
+     * scope guard (`403 STORE_SCOPE_REQUIRED`). Pass the id of the store your
+     * API key is bound to — naming any other store is rejected as cross-tenant.
+     *
+     * Admin lookups are **by id**, not by slug (`getPost(slug)` is a public read
+     * and throws in admin mode — use `findById(id, storeId)`).
+     *
      * ```typescript
      * // Storefront / vibe-coded: list published posts
      * const { data: posts } = await brainerce.blog.getPosts({ category: 'news' });
      *
-     * // Fetch one by slug
+     * // Fetch one by slug (storefront / vibe-coded)
      * const post = await brainerce.blog.getPost('my-first-post');
      *
-     * // Admin: create a draft
-     * const draft = await brainerce.blog.create({ title: 'Hello World' });
+     * // Admin: list, read one, and create a draft
+     * const all = await brainerce.blog.getPosts({}, 'store_123');
+     * const one = await brainerce.blog.findById('post_123', 'store_123');
+     * const draft = await brainerce.blog.create({ title: 'Hello World' }, 'store_123');
      * ```
      */
     this.blog = /* @__PURE__ */ (() => {
@@ -666,12 +933,30 @@ var _BrainerceClient = class _BrainerceClient {
       const buildQuery = (params) => Object.fromEntries(
         Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)])
       );
+      const requireStoreId = (action, storeId) => {
+        if (!storeId) {
+          throw new BrainerceError(
+            `client.blog.${action}() requires a storeId in admin mode. Admin mode has no ambient store \u2014 pass the id of the store your API key is bound to.`,
+            400
+          );
+        }
+        return storeId;
+      };
       return {
         /**
-         * List published posts. Works in all modes.
-         * Filters: `category`, `tag`, `page`, `limit`.
+         * List posts. Filters: `category`, `tag`, `page`, `limit`.
+         *
+         * Storefront / vibe-coded mode lists PUBLISHED posts and ignores
+         * `storeId` (the store is already in the base URL). Admin mode lists
+         * drafts too and REQUIRES `storeId`.
+         *
+         * @example
+         * ```typescript
+         * const { data } = await client.blog.getPosts({ category: 'news' });      // storefront
+         * const { data } = await client.blog.getPosts({}, 'store_123');           // admin
+         * ```
          */
-        getPosts: (params = {}) => {
+        getPosts: (params = {}, storeId) => {
           const query = buildQuery(params);
           if (this.isVibeCodedMode()) {
             return this.vibeCodedRequest(
@@ -693,12 +978,23 @@ var _BrainerceClient = class _BrainerceClient {
             "GET",
             adminBase,
             void 0,
-            query
+            {
+              ...query,
+              storeId: requireStoreId("getPosts", storeId)
+            }
           );
         },
         /**
-         * Fetch one published post by its slug. Returns `null` on 404.
-         * Works in all modes.
+         * Fetch one PUBLISHED post by its slug. Returns `null` on 404.
+         *
+         * Storefront / vibe-coded mode only — the admin API has no by-slug
+         * lookup (`GET /api/blog/posts/:id` is by id), so this throws in admin
+         * mode rather than issuing a request that can only 404.
+         *
+         * @example
+         * ```typescript
+         * const post = await client.blog.getPost('my-first-post');
+         * ```
          */
         getPost: (slug) => {
           const path = `${publicBase}/${encodeURIComponent(slug)}`;
@@ -708,42 +1004,111 @@ var _BrainerceClient = class _BrainerceClient {
           if (this.storeId && !this.apiKey) {
             return this.storefrontRequest("GET", path).catch(onNotFound);
           }
-          return this.adminRequest("GET", path).catch(onNotFound);
+          throw new BrainerceError(
+            "client.blog.getPost(slug) is a public-read API. In admin mode, look a post up by id with client.blog.findById(id, storeId), or find it with client.blog.getPosts({}, storeId).",
+            400
+          );
+        },
+        /**
+         * Fetch one post by its admin id — drafts included. Admin mode only.
+         * Returns `null` on 404.
+         *
+         * @example
+         * ```typescript
+         * const post = await client.blog.findById('post_123', 'store_123');
+         * ```
+         */
+        findById: (id, storeId) => {
+          requireAdmin("findById");
+          return this.adminRequest(
+            "GET",
+            `${adminBase}/${encodeURIComponent(id)}`,
+            void 0,
+            { storeId: requireStoreId("findById", storeId) }
+          ).catch(onNotFound);
         },
-        /** Create a blog post in DRAFT status. Admin mode only. */
-        create: (input) => {
+        /**
+         * Create a blog post in DRAFT status. Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * const draft = await client.blog.create({ title: 'Hello World' }, 'store_123');
+         * ```
+         */
+        create: (input, storeId) => {
           requireAdmin("create");
-          return this.adminRequest("POST", adminBase, input);
+          return this.adminRequest("POST", adminBase, input, {
+            storeId: requireStoreId("create", storeId)
+          });
         },
-        /** Update a blog post by ID. Admin mode only. */
-        update: (id, input) => {
+        /**
+         * Update a blog post by ID. Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * await client.blog.update('post_123', { title: 'Renamed' }, 'store_123');
+         * ```
+         */
+        update: (id, input, storeId) => {
           requireAdmin("update");
           return this.adminRequest(
             "PATCH",
             `${adminBase}/${encodeURIComponent(id)}`,
-            input
+            input,
+            { storeId: requireStoreId("update", storeId) }
           );
         },
-        /** Transition status → PUBLISHED (sets publishedAt = now if unset). Admin mode only. */
-        publish: (id) => {
+        /**
+         * Transition status → PUBLISHED (sets publishedAt = now if unset).
+         * Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * await client.blog.publish('post_123', 'store_123');
+         * ```
+         */
+        publish: (id, storeId) => {
           requireAdmin("publish");
           return this.adminRequest(
             "POST",
-            `${adminBase}/${encodeURIComponent(id)}/publish`
+            `${adminBase}/${encodeURIComponent(id)}/publish`,
+            void 0,
+            { storeId: requireStoreId("publish", storeId) }
           );
         },
-        /** Transition status PUBLISHED → DRAFT. Admin mode only. */
-        unpublish: (id) => {
+        /**
+         * Transition status PUBLISHED → DRAFT. Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * await client.blog.unpublish('post_123', 'store_123');
+         * ```
+         */
+        unpublish: (id, storeId) => {
           requireAdmin("unpublish");
           return this.adminRequest(
             "POST",
-            `${adminBase}/${encodeURIComponent(id)}/unpublish`
+            `${adminBase}/${encodeURIComponent(id)}/unpublish`,
+            void 0,
+            { storeId: requireStoreId("unpublish", storeId) }
           );
         },
-        /** Hard-delete a blog post. Admin mode only. */
-        remove: async (id) => {
+        /**
+         * Hard-delete a blog post. Admin mode only.
+         *
+         * @example
+         * ```typescript
+         * await client.blog.remove('post_123', 'store_123');
+         * ```
+         */
+        remove: async (id, storeId) => {
           requireAdmin("remove");
-          await this.adminRequest("DELETE", `${adminBase}/${encodeURIComponent(id)}`);
+          await this.adminRequest(
+            "DELETE",
+            `${adminBase}/${encodeURIComponent(id)}`,
+            void 0,
+            { storeId: requireStoreId("remove", storeId) }
+          );
         }
       };
     })();
@@ -2270,6 +2635,64 @@ var _BrainerceClient = class _BrainerceClient {
    * console.log('Product type:', product.type); // 'VARIABLE'
    * ```
    */
+  /**
+   * Read a kit's contents, with its resolved price and how many can be sold.
+   *
+   * A KIT is one purchasable product assembled from other catalog products. It
+   * holds no inventory of its own: `available` is whichever component runs out
+   * first. Outside `FIXED` pricing the product row's `basePrice` is a
+   * placeholder, so use the `price` returned here.
+   *
+   * Safe to call for any product — a non-KIT returns an empty, unsellable
+   * shape rather than throwing, so callers need not branch on product type.
+   *
+   * @example
+   * ```typescript
+   * const kit = await client.getKitComponents('prod_123');
+   * console.log(kit.price, kit.available, kit.components.length);
+   * ```
+   */
+  async getKitComponents(productId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/${encodePathSegment(productId)}/kit-components`
+    );
+  }
+  /**
+   * Replace a kit's contents, and optionally how it is priced.
+   *
+   * A full replace, not a patch: send the list you want the kit to end up with.
+   * Omit `pricingMode` to leave the kit's current mode untouched.
+   *
+   * Rejected: a product that is not a KIT, a component from another store, a
+   * component that is itself a KIT, a VARIABLE component with no variant
+   * pinned, a variant that does not belong to its product, the same slot
+   * listed twice, and a component whose product or pinned variant is not
+   * published.
+   *
+   * That last one is checked over the WHOLE list you send, not just the rows
+   * you changed. Once a product already inside a kit is unpublished, no edit
+   * to that kit saves until you publish it again or drop it from the list.
+   *
+   * @example
+   * ```typescript
+   * await client.setKitComponents('prod_123', {
+   *   components: [
+   *     { componentProductId: 'prod_bottle', quantity: 1 },
+   *     { componentProductId: 'prod_glass', quantity: 2 },
+   *   ],
+   *   pricingMode: 'SUM_MINUS_PERCENT',
+   *   discountValue: 10,
+   * });
+   * ```
+   */
+  async setKitComponents(productId, body) {
+    return this.request(
+      "PUT",
+      `/api/v1/products/${encodePathSegment(productId)}/kit-components`,
+      body
+    );
+  }
   async convertToVariable(productId) {
     return this.request(
       "PATCH",
@@ -2854,6 +3277,13 @@ var _BrainerceClient = class _BrainerceClient {
    * 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.
+   *
+   * The response carries the whole {@link ProductInventoryResponse} — the
+   * `InventoryItem` id, `trackingMode`, `backorderMode`, `backorderLimit`,
+   * `lowStockThreshold`, `lastInventorySyncAt` and `updatedAt` alongside the
+   * three counters. It always did; only the three counters were declared.
+   * On the all-zeroes no-row branch everything but the counters is absent,
+   * so test `id` rather than expecting a 404.
    */
   async getInventory(productId) {
     return this.adminRequest(
@@ -10045,71 +10475,88 @@ var _BrainerceClient = class _BrainerceClient {
     }
     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`,
-  // `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.
+  // -------------------- Team Management (Admin) - NOT REACHABLE BY API KEY --------------------
+  // ⛔ These seven used to be documented as "the ONLY team endpoints reachable
+  // with a `brainerce_*` API key". That was wrong, and every one of them 403s.
+  //
+  // The routes exist and the guards admit an api_key, but admission is not the
+  // same as success. `external-api.controller.ts` hands `TeamService` a synthetic
+  // principal — `SYSTEM_USER_ID = 'api-key-user'` (`:171`, used at `:4572`,
+  // `:4586`, `:4607`, ...) — and every TeamService method opens with
+  // `verifyAccountAccess` / `verifyAccountOwner`, which is an
+  // `accountUser.findFirst({ where: { userId, ... } })`. No `AccountUser` row has
+  // `userId = 'api-key-user'` anywhere; the sentinel is row-less by construction.
+  // So the lookup misses and every call throws `Access denied to this account`.
+  //
+  // The store-level equivalents (`getStoreTeam`, `inviteStoreMember`, ...) sit
+  // behind `DashboardOnlyGuard`, which rejects api_key principals by design. So
+  // BOTH families are dashboard-only and there is no API-key path to team
+  // management at all.
+  //
+  // ⛔ Do NOT "fix" this by letting api_key through. Team membership is
+  // ACCOUNT-scoped and `inviteMember` grants `Role.ACCOUNT_OWNER`, i.e. ownership
+  // of every store on the account. An API key is bound to exactly ONE store, so
+  // admitting it here converts a single-store credential into account ownership.
+  // That is a privilege-escalation primitive, not a missing feature.
+  //
+  // These throw rather than return a 403 from the wire, so the failure names its
+  // own cause instead of arriving as a bare status code. Same treatment as
+  // `createDonation` above. Agents: use the dashboard, or the `team:*` tools on
+  // the admin MCP server, which are OAuth-authenticated and store-scoped.
+  /** The message every team method throws. One string so they cannot drift. */
+  teamIsDashboardOnly(method) {
+    throw new Error(
+      `${method} is not available with an API key. Team management is account-scoped and every route rejects the api_key principal, so this call can only fail. Manage team members in the dashboard, or use the store-scoped team tools on the admin MCP server (OAuth), which are bound to a single store.`
+    );
+  }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and `getStoreTeam` is dashboard-only. Use the dashboard.
    */
   async getTeamMembers() {
-    return this.adminRequest("GET", "/api/v1/team/members");
+    return this.teamIsDashboardOnly("getTeamMembers");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and `getStoreTeam` is dashboard-only. Use the dashboard.
    */
   async getTeamInvitations() {
-    return this.adminRequest("GET", "/api/v1/team/invitations");
+    return this.teamIsDashboardOnly("getTeamInvitations");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and the store-level route is dashboard-only. Use the dashboard.
    */
-  async inviteTeamMember(data) {
-    return this.adminRequest("POST", "/api/v1/team/invitations", data);
+  async inviteTeamMember(_data) {
+    return this.teamIsDashboardOnly("inviteTeamMember");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and the store-level route is dashboard-only. Use the dashboard.
    */
-  async resendTeamInvitation(invitationId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/team/invitations/${encodePathSegment(invitationId)}/resend`
-    );
+  async resendTeamInvitation(_invitationId) {
+    return this.teamIsDashboardOnly("resendTeamInvitation");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and the store-level route is dashboard-only. Use the dashboard.
    */
-  async revokeTeamInvitation(invitationId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/team/invitations/${encodePathSegment(invitationId)}`
-    );
+  async revokeTeamInvitation(_invitationId) {
+    return this.teamIsDashboardOnly("revokeTeamInvitation");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and the store-level route is dashboard-only. Use the dashboard.
    */
-  async updateTeamMemberRole(memberId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/team/members/${encodePathSegment(memberId)}/role`,
-      data
-    );
+  async updateTeamMemberRole(_memberId, _data) {
+    return this.teamIsDashboardOnly("updateTeamMemberRole");
   }
   /**
-   * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
-   * is dashboard-only (403 for api_key). Keep using this until one ships.
+   * @deprecated Retiring, but this ALWAYS throws: `/v1/team/*` rejects the
+   * api_key principal and the store-level route is dashboard-only. Use the dashboard.
    */
-  async removeTeamMember(memberId) {
-    await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);
+  async removeTeamMember(_memberId) {
+    return this.teamIsDashboardOnly("removeTeamMember");
   }
   // -------------------- Store Team Management (Admin) --------------------
   // Store-level team management. Each store has its own team with roles and permissions.