brainerce 2.5.0 → 2.7.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.5.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 --------------------
@@ -2505,8 +2666,13 @@ var _BrainerceClient = class _BrainerceClient {
    *
    * 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, and the same slot
-   * listed twice.
+   * 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
@@ -3111,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(

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.5.0";
+var SDK_VERSION = "2.7.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -292,10 +292,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
@@ -323,6 +327,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 --------------------
@@ -2416,8 +2577,13 @@ var _BrainerceClient = class _BrainerceClient {
    *
    * 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, and the same slot
-   * listed twice.
+   * 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
@@ -3022,6 +3188,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(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "2.5.0",
+  "version": "2.7.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",