brainerce 2.2.0 → 2.3.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.2.0";
+var SDK_VERSION = "2.3.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -926,10 +926,19 @@ var _BrainerceClient = class _BrainerceClient {
     this.customerToken = null;
   }
   // -------------------- Private Methods --------------------
+  /**
+   * Turn an `idempotencyKey` option into the header the backend reads.
+   *
+   * Returns `undefined` when there is no key, so the header is absent rather
+   * than empty — the interceptor rejects a present-but-blank key with a 400.
+   */
+  idempotencyHeaders(options) {
+    return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
+  }
   /**
    * Make a request to the Admin API (requires apiKey)
    */
-  async adminRequest(method, path, body, queryParams, responseType = "json") {
+  async adminRequest(method, path, body, queryParams, responseType = "json", extraHeaders) {
     if (!this.apiKey) {
       throw new BrainerceError(
         "This operation requires an API key. Initialize with apiKey instead of storeId.",
@@ -959,6 +968,11 @@ var _BrainerceClient = class _BrainerceClient {
     if (this.locale) {
       headers["Accept-Language"] = this.locale;
     }
+    if (extraHeaders) {
+      for (const [key, value] of Object.entries(extraHeaders)) {
+        if (value) headers[key] = value;
+      }
+    }
     for (let attempt = 0; attempt < 2; attempt++) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -2283,21 +2297,25 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * Publish a product to specific platforms
+   * Publish a product to specific platforms.
    *
-   * @example
-   * ```typescript
-   * const result = await client.publishProduct('prod_123', ['SHOPIFY', 'WOOCOMMERCE']);
-   * console.log('Publish results:', result.results);
-   * ```
+   * **Not callable.** The API-key `/v1` surface has no `products/:id/publish`
+   * route. Platform publishing for products exists only on the dashboard
+   * surface (`POST /api/products/:id/publish?storeId=`,
+   * `products.controller.ts:556`), which resolves the acting user from a
+   * dashboard session an API key does not carry. The generic trigger
+   * `POST /v1/sync` answers `501 Not Implemented` and points at per-resource
+   * publish endpoints — and products have none.
+   *
+   * {@link publishProductToSalesChannel} is a DIFFERENT operation: it controls
+   * visibility on a vibe-coded storefront, not a push to an external platform.
    */
   async publishProduct(productId, platforms) {
-    return this.request(
-      "POST",
-      `/api/v1/products/${encodePathSegment(productId)}/publish`,
-      {
-        platforms
-      }
+    void productId;
+    void platforms;
+    throw new BrainerceError(
+      "publishProduct is not a route on the API-key /v1 surface. There is no products/:id/publish endpoint to call, so nothing was published; publish the product to a platform from the Brainerce dashboard. Note that publishProductToSalesChannel is a different operation \u2014 it controls vibe-coded storefront visibility, not an external-platform push.",
+      400
     );
   }
   // -------------------- Variants --------------------
@@ -4292,6 +4310,9 @@ var _BrainerceClient = class _BrainerceClient {
    * flags reflect the live state. Call this on cart load if you want to
    * surface drift to the customer before they reach checkout.
    *
+   * **Storefront and vibe-coded modes only.** There is no admin (`apiKey`)
+   * route for this, so an admin-mode client throws instead of 404ing.
+   *
    * @example
    * ```typescript
    * const cart = await client.recalculateCart('cart_123');
@@ -4316,9 +4337,9 @@ var _BrainerceClient = class _BrainerceClient {
         "cart"
       );
     }
-    return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/recalculate`),
-      "cart"
+    throw new BrainerceError(
+      "recalculateCart is not a route on the API-key /v1 surface. There is no cart/:cartId/recalculate endpoint to call, so nothing was recalculated. Cart recalculation is a storefront operation \u2014 call it from a client constructed with `salesChannelId` (vibe-coded) or `storeId` (public storefront), where the route exists.",
+      400
     );
   }
   /**
@@ -4327,6 +4348,9 @@ var _BrainerceClient = class _BrainerceClient {
    * subsequent `createCheckout` call will then succeed (it would otherwise
    * throw `PRICE_DRIFT`).
    *
+   * **Storefront and vibe-coded modes only.** There is no admin (`apiKey`)
+   * route for this, so an admin-mode client throws instead of 404ing.
+   *
    * @example
    * ```typescript
    * try {
@@ -4361,12 +4385,9 @@ var _BrainerceClient = class _BrainerceClient {
         "cart"
       );
     }
-    return this.withGuards(
-      this.adminRequest(
-        "POST",
-        `/api/v1/cart/${encodePathSegment(cartId)}/refresh-snapshots`
-      ),
-      "cart"
+    throw new BrainerceError(
+      "refreshCartSnapshots is not a route on the API-key /v1 surface. There is no cart/:cartId/refresh-snapshots endpoint to call, so no price snapshots were refreshed. Snapshot refresh is a storefront operation \u2014 call it from a client constructed with `salesChannelId` (vibe-coded) or `storeId` (public storefront), where the route exists.",
+      400
     );
   }
   /**
@@ -5875,22 +5896,39 @@ var _BrainerceClient = class _BrainerceClient {
    * screen or database query can recover it.
    *
    * A `note` is required. Refused when gift cards are switched off for the
-   * store. Pass an `Idempotency-Key` header to make a retry safe.
+   * store.
+   *
+   * ⚠️ **Pass an `idempotencyKey`.** It is the ONLY recovery that exists here:
+   * re-sending the identical request with the same key inside 24 hours replays
+   * the cached response, code included. Without one, a retried timeout mints a
+   * SECOND card and a second real liability. The key is sent as the
+   * `Idempotency-Key` header; reuse the same value across retries of the same
+   * logical issue, never a fresh random one.
    *
    * Requires `gift_cards:issue`.
    *
    * @example
    * ```typescript
-   * const card = await client.issueGiftCard({
-   *   amount: '200.00',
-   *   note: 'Compensation for order #1042',
-   *   recipientEmail: 'dana@example.com',
-   * });
+   * const card = await client.issueGiftCard(
+   *   {
+   *     amount: '200.00',
+   *     note: 'Compensation for order #1042',
+   *     recipientEmail: 'dana@example.com',
+   *   },
+   *   { idempotencyKey: 'compensation-order-1042' }
+   * );
    * await sendToCustomer(card.plaintextCode); // your only chance
    * ```
    */
-  async issueGiftCard(data) {
-    return this.adminRequest("POST", "/api/v1/gift-cards", data);
+  async issueGiftCard(data, options) {
+    return this.adminRequest(
+      "POST",
+      "/api/v1/gift-cards",
+      data,
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
   }
   /**
    * Re-issue a gift card onto a new code.
@@ -5903,15 +5941,21 @@ var _BrainerceClient = class _BrainerceClient {
    * while a checkout holds value on the card. The original expiry carries
    * forward, so this cannot be used to restart an expiry clock.
    *
-   * The new code is returned exactly once, under the same rules as issuance.
+   * The new code is returned exactly once, under the same rules as issuance —
+   * so pass an `idempotencyKey` here for the same reason, and with the same
+   * force: a retried timeout without one revokes the replacement it just made
+   * and mints another.
    *
    * Requires `gift_cards:issue`.
    */
-  async reissueGiftCard(giftCardId, note) {
+  async reissueGiftCard(giftCardId, note, options) {
     return this.adminRequest(
       "POST",
       `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/reissue`,
-      { note }
+      { note },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
     );
   }
   /**
@@ -5924,13 +5968,19 @@ var _BrainerceClient = class _BrainerceClient {
    * A debit cannot take the balance below what live checkout holds have already
    * reserved; that refusal names the held amount so you can act on it.
    *
+   * Pass an `idempotencyKey`: an adjustment is a relative move, so a retried
+   * timeout without one applies the delta twice.
+   *
    * Requires `gift_cards:adjust`.
    */
-  async adjustGiftCardBalance(giftCardId, delta, note) {
+  async adjustGiftCardBalance(giftCardId, delta, note, options) {
     return this.adminRequest(
       "PATCH",
       `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/adjust`,
-      { delta, note }
+      { delta, note },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
     );
   }
   /**
@@ -5943,11 +5993,14 @@ var _BrainerceClient = class _BrainerceClient {
    *
    * Requires `gift_cards:write`.
    */
-  async setGiftCardStatus(giftCardId, status) {
+  async setGiftCardStatus(giftCardId, status, options) {
     return this.adminRequest(
       "PATCH",
       `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/status`,
-      { status }
+      { status },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
     );
   }
   /**
@@ -5963,11 +6016,15 @@ var _BrainerceClient = class _BrainerceClient {
    *
    * Requires `gift_cards:write`.
    */
-  async bulkSetGiftCardStatus(giftCardIds, status) {
-    return this.adminRequest("PATCH", "/api/v1/gift-cards/bulk/status", {
-      giftCardIds,
-      status
-    });
+  async bulkSetGiftCardStatus(giftCardIds, status, options) {
+    return this.adminRequest(
+      "PATCH",
+      "/api/v1/gift-cards/bulk/status",
+      { giftCardIds, status },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
   }
   // ==========================================================================
   // Donations
@@ -6376,6 +6433,9 @@ var _BrainerceClient = class _BrainerceClient {
   /**
    * Set delivery type on checkout (shipping or pickup).
    *
+   * **Storefront and vibe-coded modes only.** There is no admin (`apiKey`)
+   * route for this, so an admin-mode client throws instead of 404ing.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setDeliveryType('checkout_123', 'pickup');
@@ -6400,12 +6460,9 @@ var _BrainerceClient = class _BrainerceClient {
         }
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkout/${encodePathSegment(checkoutId)}/delivery-type`,
-      {
-        deliveryType
-      }
+    throw new BrainerceError(
+      "setDeliveryType is not a route on the API-key /v1 surface. There is no checkout/:checkoutId/delivery-type endpoint to call, so the delivery type was not changed. Set it from the storefront session that owns the checkout \u2014 a client constructed with `salesChannelId` (vibe-coded) or `storeId` (public storefront) \u2014 or from the Brainerce dashboard.",
+      400
     );
   }
   /**
@@ -6413,6 +6470,9 @@ var _BrainerceClient = class _BrainerceClient {
    * This sets the delivery type to "pickup", records customer info, and prepares for payment.
    * Equivalent to setShippingAddress + selectShippingMethod for delivery orders.
    *
+   * **Storefront and vibe-coded modes only.** There is no admin (`apiKey`)
+   * route for this, so an admin-mode client throws instead of 404ing.
+   *
    * @example
    * ```typescript
    * const checkout = await client.selectPickupLocation('checkout_123', {
@@ -6439,10 +6499,9 @@ var _BrainerceClient = class _BrainerceClient {
         data
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkout/${encodePathSegment(checkoutId)}/pickup-location`,
-      data
+    throw new BrainerceError(
+      "selectPickupLocation is not a route on the API-key /v1 surface. There is no checkout/:checkoutId/pickup-location endpoint to call, so no pickup location was selected. Select it from the storefront session that owns the checkout \u2014 a client constructed with `salesChannelId` (vibe-coded) or `storeId` (public storefront) \u2014 or from the Brainerce dashboard.",
+      400
     );
   }
   /**
@@ -7767,13 +7826,17 @@ var _BrainerceClient = class _BrainerceClient {
    * lifetime earned, the program's display config, earned milestone `badges`,
    * and the `paidMembership` subscription state (null for free members).
    * Requires customerToken. Only available in storefront mode. `program` is
-   * null when the store has no loyalty program.
+   * null when the store has no loyalty program. `pointsBalance` excludes points
+   * still inside the return window - those are in `pendingPoints`, and a panel
+   * that ignores them shows a shopper 0 the day they order.
    *
    * @example
    * ```typescript
    * client.setCustomerToken(auth.token);
    * const status = await client.getLoyaltyStatus();
    * if (status.enrolled) console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+   * // Points from an order just placed are in pendingPoints, NOT pointsBalance.
+   * if (status.pendingPoints > 0) console.log(`+${status.pendingPoints} on ${status.pendingPointsConfirmAt}`);
    * status.badges?.forEach((b) => console.log(`🏅 ${b.name}`));
    * if (status.paidMembership?.status === 'ACTIVE') showPremiumPerks(status.paidMembership.plan);
    * ```
@@ -8620,11 +8683,28 @@ var _BrainerceClient = class _BrainerceClient {
     return this.adminRequest("POST", "/api/v1/tags", data);
   }
   /**
-   * Update an existing tag
-   * Requires Admin mode (apiKey)
+   * Update an existing tag.
+   *
+   * **Not callable.** The API-key `/v1` surface serves `GET`, `POST` and
+   * `DELETE` on tags (`external-api.controller.ts:3276`, `:3310`, `:3331`) but
+   * no update verb — `PATCH /api/v1/tags/:id` 404'd silently. Tag editing lives
+   * only on the dashboard surface (`PATCH /api/stores/:storeId/tags/:id`,
+   * `tags.controller.ts:127`), which needs a `storeId` in the path that this
+   * signature does not carry, and resolves the acting user from a dashboard
+   * session an API key does not have.
+   *
+   * Edit the tag in the Brainerce dashboard. {@link deleteTag} +
+   * {@link createTag} is NOT an equivalent workaround: it drops the tag's
+   * product assignments, and `CreateTagDto` has no `translations` field, so any
+   * per-locale names are lost too.
    */
   async updateTag(tagId, data) {
-    return this.adminRequest("PATCH", `/api/v1/tags/${encodePathSegment(tagId)}`, data);
+    void tagId;
+    void data;
+    throw new BrainerceError(
+      "updateTag is not a route on the API-key /v1 surface. Tags are served there for read, create and delete only, so the tag was not changed; edit it in the Brainerce dashboard. Deleting and recreating the tag is not equivalent \u2014 it drops the product assignments and the translations.",
+      400
+    );
   }
   /**
    * Delete a tag
@@ -8722,24 +8802,41 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * Update an attribute option
-   * Requires Admin mode (apiKey)
+   * Update an attribute option.
+   *
+   * **Not callable.** The API-key `/v1` surface serves attribute options for
+   * list and create only (`external-api.controller.ts:3517`, `:3543`); there is
+   * no per-option route, so this 404'd silently. Editing an option lives on the
+   * dashboard surface (`PUT /api/stores/:storeId/attributes/:id/options/:optionId`,
+   * `attributes.controller.ts:132` — note it is `PUT` there, not `PATCH`), which
+   * needs a path `storeId` this signature does not carry.
+   *
+   * Edit the option in the Brainerce dashboard.
    */
   async updateAttributeOption(attributeId, optionId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/attributes/${encodePathSegment(attributeId)}/options/${encodePathSegment(optionId)}`,
-      data
+    void attributeId;
+    void optionId;
+    void data;
+    throw new BrainerceError(
+      "updateAttributeOption is not a route on the API-key /v1 surface. Attribute options are served there for list and create only, so the option was not changed; edit it in the Brainerce dashboard.",
+      400
     );
   }
   /**
-   * Delete an attribute option
-   * Requires Admin mode (apiKey)
+   * Delete an attribute option.
+   *
+   * **Not callable.** Same gap as {@link updateAttributeOption}: the `/v1`
+   * surface has no per-option route. Deleting an option lives on the dashboard
+   * surface (`DELETE /api/stores/:storeId/attributes/:id/options/:optionId`,
+   * `attributes.controller.ts:145`), which needs a path `storeId` this signature
+   * does not carry.
    */
   async deleteAttributeOption(attributeId, optionId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/attributes/${encodePathSegment(attributeId)}/options/${encodePathSegment(optionId)}`
+    void attributeId;
+    void optionId;
+    throw new BrainerceError(
+      "deleteAttributeOption is not a route on the API-key /v1 surface. Attribute options are served there for list and create only, so nothing was deleted; delete the option in the Brainerce dashboard.",
+      400
     );
   }
   // -------------------- Modifier Groups (Admin) --------------------
@@ -9562,25 +9659,48 @@ var _BrainerceClient = class _BrainerceClient {
   // Products/Coupons. When no publishes exist for an entity, it remains
   // visible to all vibe-coded sites of the store (legacy default).
   /**
-   * Publish a metafield definition to a vibe-coded site (admin mode).
-   * @example
-   * ```typescript
-   * await client.publishMetafieldDefinitionToVibeCodedSite('def_123', 'conn_456');
-   * ```
+   * Publish a metafield definition to a sales channel (admin mode).
+   *
+   * **Not callable.** This asked for `publish-vibe-coded`, which is a
+   * deprecated backend alias, not the canonical route. The canonical spelling
+   * is `publish-sales-channel`, and the `/v1` surface serves it for products
+   * (`external-api.controller.ts:862`), coupons (`:947`), customers (`:1548`),
+   * categories (`:3039`), brands (`:3211`) and tags (`:3349`) — but NOT for
+   * metafield definitions. Both spellings 404 there.
+   *
+   * The operation exists only on the dashboard surface
+   * (`POST /api/stores/:storeId/metafield-definitions/:id/publish-sales-channel`,
+   * `metafields.controller.ts:190`), which needs a path `storeId` this signature
+   * does not carry.
+   *
+   * Publish the definition to a sales channel from the Brainerce dashboard. A
+   * definition with no publishes stays visible to every sales channel of the
+   * store, so leaving it unpublished is the permissive default, not a lockout.
    */
   async publishMetafieldDefinitionToVibeCodedSite(definitionId, vibeCodedConnectionId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+    void definitionId;
+    void vibeCodedConnectionId;
+    throw new BrainerceError(
+      "publishMetafieldDefinitionToVibeCodedSite is not a route on the API-key /v1 surface. Per-sales-channel publishing is served there for products, coupons, customers, categories, brands and tags, but not for metafield definitions, so nothing was published; publish it in the Brainerce dashboard. A definition with no publishes remains visible to every sales channel of the store.",
+      400
     );
   }
-  /** Unpublish a metafield definition from a vibe-coded site (admin mode). */
+  /**
+   * Unpublish a metafield definition from a sales channel (admin mode).
+   *
+   * **Not callable.** Same gap as
+   * {@link publishMetafieldDefinitionToVibeCodedSite} — the `/v1` surface
+   * carries no per-sales-channel routes for metafield definitions under either
+   * the canonical `unpublish-sales-channel` spelling or the deprecated
+   * `unpublish-vibe-coded` alias. The dashboard route is
+   * `metafields.controller.ts:217`.
+   */
   async unpublishMetafieldDefinitionFromVibeCodedSite(definitionId, vibeCodedConnectionId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+    void definitionId;
+    void vibeCodedConnectionId;
+    throw new BrainerceError(
+      "unpublishMetafieldDefinitionFromVibeCodedSite is not a route on the API-key /v1 surface. Per-sales-channel publishing is served there for products, coupons, customers, categories, brands and tags, but not for metafield definitions, so nothing was unpublished; unpublish it in the Brainerce dashboard.",
+      400
     );
   }
   /**
@@ -9726,10 +9846,11 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setDefinitionProducts(definitionId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/metafield-definitions/${encodePathSegment(definitionId)}/products`,
-      data
+    void definitionId;
+    void data;
+    throw new BrainerceError(
+      "setDefinitionProducts is not a route on the API-key /v1 surface. There is no metafield-definitions/:id/products endpoint to call, so the definition's product list was not changed; set it in the Brainerce dashboard.",
+      400
     );
   }
   // -------------------- Metafields: Product Values --------------------
@@ -9775,24 +9896,41 @@ var _BrainerceClient = class _BrainerceClient {
   // -------------------- Product Customization Fields (Admin) --------------------
   /**
    * Get customization fields assigned to a product.
-   * Requires Admin mode (apiKey).
+   *
+   * **Not callable.** The API-key `/v1` surface has no
+   * `metafield-definitions/products/:productId/customization-fields` route, so
+   * this 404'd silently. It exists only on the dashboard surface
+   * (`GET /api/stores/:storeId/metafield-definitions/products/:productId/customization-fields`,
+   * `metafields.controller.ts:277`), which needs a path `storeId` this signature
+   * does not carry.
+   *
+   * {@link getProductMetafields} is the closest working call — it returns the
+   * metafield VALUES stored on a product over
+   * `GET /api/v1/products/:productId/metafields`, not the customer-input field
+   * definitions attached to it.
    */
   async getProductCustomizationFields(productId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/metafield-definitions/products/${encodePathSegment(productId)}/customization-fields`
+    void productId;
+    throw new BrainerceError(
+      "getProductCustomizationFields is not a route on the API-key /v1 surface. There is no metafield-definitions/products/:productId/customization-fields endpoint to call; read the assignments in the Brainerce dashboard. getProductMetafields returns the product's stored metafield values, which is a different thing.",
+      400
     );
   }
   /**
    * Set customization fields for a product (replaces all existing assignments).
-   * Only definitions marked as `isCustomerInput: true` can be assigned.
-   * Requires Admin mode (apiKey).
+   *
+   * **Not callable.** Same gap as {@link getProductCustomizationFields}: the
+   * `/v1` surface carries no customization-field routes. The dashboard route is
+   * `PATCH /api/stores/:storeId/metafield-definitions/products/:productId/customization-fields`
+   * (`metafields.controller.ts:298`), which needs a path `storeId` this
+   * signature does not carry.
    */
   async setProductCustomizationFields(productId, definitionIds) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/metafield-definitions/products/${encodePathSegment(productId)}/customization-fields`,
-      { definitionIds }
+    void productId;
+    void definitionIds;
+    throw new BrainerceError(
+      "setProductCustomizationFields is not a route on the API-key /v1 surface. There is no metafield-definitions/products/:productId/customization-fields endpoint to call, so the assignments were not changed; set them in the Brainerce dashboard.",
+      400
     );
   }
   /**
@@ -11187,6 +11325,7 @@ function buildProductJsonLd(product, opts) {
   const inv = product.inventory;
   const availability = !inv ? "https://schema.org/InStock" : inv.inStock ?? (inv.available ?? 0) > 0 ? "https://schema.org/InStock" : inv.canPurchase ? "https://schema.org/BackOrder" : "https://schema.org/OutOfStock";
   const isVariable = product.type === "VARIABLE" && product.priceMin && product.priceMax;
+  const omitOffer = product.type === "KIT";
   const itemCondition = "https://schema.org/NewCondition";
   const shippingDetails = (opts.shipping ?? []).filter((z) => z.amount !== null).map((z) => ({
     "@type": "OfferShippingDetails",
@@ -11249,7 +11388,7 @@ function buildProductJsonLd(product, opts) {
     ...product.gtin ? { gtin: product.gtin } : {},
     ...product.mpn ? { mpn: product.mpn } : {},
     ...brand ? { brand: { "@type": "Brand", name: brand } } : {},
-    offers: offer,
+    ...omitOffer ? {} : { offers: offer },
     // Google policy: never emit an empty/zero rating block. bestRating /
     // worstRating make the 1-5 scale explicit so aggregators can't misread
     // a 4.8 on an assumed 0-10 scale.