brainerce 2.1.0 → 2.3.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.3";
+var SDK_VERSION = "2.3.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -450,7 +450,7 @@ var _BrainerceClient = class _BrainerceClient {
      * 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/v1/content/...` with
+     *     `remove`): admin mode only — they call `/api/content/...` with
      *     the API key. Calling from storefront / vibe-coded mode throws.
      *
      * **Default key:** every type has `'main'` as its universal default key.
@@ -487,7 +487,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.content = (() => {
       const DEFAULT_KEY = "main";
       const publicGetPath = (type, key) => `/content/${encodeURIComponent(type)}/${encodeURIComponent(key)}`;
-      const adminBase = () => "/api/v1/content";
+      const adminBase = () => "/api/content";
       const publicGet = async (type, key, locale) => {
         const query = locale ? { locale } : void 0;
         const path = publicGetPath(type, key);
@@ -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);
@@ -2107,11 +2121,9 @@ var _BrainerceClient = class _BrainerceClient {
         queryParams
       );
     }
-    return this.adminRequest(
-      "GET",
-      "/api/v1/search/suggestions",
-      void 0,
-      queryParams
+    throw new BrainerceError(
+      "getSearchSuggestions is a storefront API. There is no admin suggestions endpoint \u2014 construct the client with `salesChannelId` or `storeId` to use it, or call getProducts({ search }) in admin mode.",
+      400
     );
   }
   /**
@@ -2285,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 --------------------
@@ -4294,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');
@@ -4318,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
     );
   }
   /**
@@ -4329,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 {
@@ -4363,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
     );
   }
   /**
@@ -5812,6 +5831,202 @@ var _BrainerceClient = class _BrainerceClient {
     return this.adminRequest("POST", "/api/v1/gift-cards/balance", { code });
   }
   // ==========================================================================
+  // Gift cards — administration (API key only)
+  //
+  // Full programmatic management, unlike Shopify, which requires you to ask
+  // their support for the equivalent scope. The gate here is the SCOPE the
+  // merchant granted your key, so the separation matters: `gift_cards:issue`
+  // mints stored value and `gift_cards:adjust` rewrites a balance, and neither
+  // is implied by `gift_cards:read`. Ask for the least your integration needs.
+  //
+  // Every call reaches the same service the dashboard uses, so the rules hold
+  // identically: a note is mandatory on anything that moves value, a debit
+  // cannot cross what live checkout holds have reserved, and there is no delete
+  // anywhere — the ledger is append-only.
+  // ==========================================================================
+  /**
+   * List gift cards.
+   *
+   * `search` matches the LAST FOUR of a code or part of a recipient email. It
+   * cannot match a full code: only an HMAC is stored, so there is nothing to
+   * search against.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async listGiftCards(params) {
+    const q = new URLSearchParams();
+    if (params?.page) q.set("page", String(params.page));
+    if (params?.limit) q.set("limit", String(params.limit));
+    if (params?.filter) q.set("filter", params.filter);
+    if (params?.search) q.set("search", params.search);
+    const qs = q.toString();
+    return this.adminRequest(
+      "GET",
+      `/api/v1/gift-cards${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * Outstanding gift card liability, per currency.
+   *
+   * This is the month-end number. Read `byCurrency` if the store sells in more
+   * than one — currencies are never summed together.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async getGiftCardLiability() {
+    return this.adminRequest("GET", "/api/v1/gift-cards/liability");
+  }
+  /**
+   * One gift card with its full ledger.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async getGiftCard(giftCardId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}`
+    );
+  }
+  /**
+   * Issue a gift card.
+   *
+   * ⚠️ **The code comes back exactly once.** It is stored only as an HMAC, so
+   * this response is the only time it exists in readable form anywhere. Persist
+   * it or deliver it before you discard the response — no later call, dashboard
+   * screen or database query can recover it.
+   *
+   * A `note` is required. Refused when gift cards are switched off for the
+   * 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',
+   *   },
+   *   { idempotencyKey: 'compensation-order-1042' }
+   * );
+   * await sendToCustomer(card.plaintextCode); // your only chance
+   * ```
+   */
+  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.
+   *
+   * The answer to a customer losing their code. Mints a new code, moves the
+   * WHOLE balance to it, and REVOKES the old card.
+   *
+   * **This is not a resend.** The old code stops working the moment this
+   * returns — if the customer still holds a printed card, it dies. Refused
+   * 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 —
+   * 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, options) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/reissue`,
+      { note },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
+  /**
+   * Adjust a gift card balance.
+   *
+   * `delta` is a SIGNED decimal string: `"25.00"` adds, `"-25.00"` takes away.
+   * The `note` is required and is written to the ledger permanently — it is the
+   * row a finance review reads a year from now.
+   *
+   * 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, options) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/adjust`,
+      { delta, note },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
+  /**
+   * Enable, disable or revoke one gift card.
+   *
+   * Deliberately does NOT touch live holds: a checkout that already reserved
+   * value settles normally, because pulling it out from under a shopper
+   * mid-payment would strand a provider charge already in flight. Disabling
+   * stops NEW holds, which is what "off" actually means.
+   *
+   * Requires `gift_cards:write`.
+   */
+  async setGiftCardStatus(giftCardId, status, options) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/status`,
+      { status },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
+  /**
+   * Disable or reactivate many gift cards at once.
+   *
+   * `REVOKED` is not accepted here — it belongs to re-issue, which moves the
+   * balance to a replacement first. Revoking in bulk would strand balances with
+   * nowhere to go. Cards already revoked are skipped, so the returned count is
+   * the honest one and may be lower than the ids you sent.
+   *
+   * There is no bulk delete, here or anywhere: the ledger is append-only and a
+   * card may carry a statutory retention life.
+   *
+   * Requires `gift_cards:write`.
+   */
+  async bulkSetGiftCardStatus(giftCardIds, status, options) {
+    return this.adminRequest(
+      "PATCH",
+      "/api/v1/gift-cards/bulk/status",
+      { giftCardIds, status },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
+  // ==========================================================================
   // Donations
   // ==========================================================================
   /**
@@ -5954,10 +6169,7 @@ var _BrainerceClient = class _BrainerceClient {
         "/checkouts/shipping-destinations"
       );
     }
-    return this.adminRequest(
-      "GET",
-      "/api/v1/checkouts/shipping-destinations"
-    );
+    return this.adminRequest("GET", "/api/checkouts/shipping-destinations");
   }
   /**
    * Set shipping address on checkout (includes customer email).
@@ -6216,11 +6428,14 @@ var _BrainerceClient = class _BrainerceClient {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest("GET", "/pickup-locations");
     }
-    return this.adminRequest("GET", "/api/v1/checkouts/pickup-locations");
+    return this.adminRequest("GET", "/api/checkouts/pickup-locations");
   }
   /**
    * 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');
@@ -6245,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
     );
   }
   /**
@@ -6258,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', {
@@ -6284,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
     );
   }
   /**
@@ -7612,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);
    * ```
@@ -8465,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
@@ -8567,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) --------------------
@@ -9190,10 +9442,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async applyTaxPreset(presetKey) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/tax/presets/${encodePathSegment(presetKey)}/apply`
-    );
+    return this.adminRequest("POST", `/api/v1/tax/presets/${encodePathSegment(presetKey)}/apply`);
   }
   /**
    * Get a single tax rate by ID
@@ -9410,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
     );
   }
   /**
@@ -9574,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 --------------------
@@ -9623,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
     );
   }
   /**
@@ -9823,6 +10113,27 @@ var _BrainerceClient = class _BrainerceClient {
   }
   // -------------------- Store Team Management (Admin) --------------------
   // Store-level team management. Each store has its own team with roles and permissions.
+  /**
+   * Every store-level team operation is dashboard-only.
+   *
+   * `store-team.controller.ts:53` carries `DashboardOnlyGuard`, which rejects
+   * `api_key` and `app_installation` principals outright, so no SDK caller can
+   * reach these however the URL is spelled. They additionally pointed at
+   * `/api/v1/stores/:storeId/team*`, and `@Controller('v1')`
+   * (external-api.controller.ts:181) has no `stores` root — so what they
+   * actually returned was a 404, not the 403 you would expect from the guard.
+   *
+   * Throwing beats either status code: a 404 reads as "wrong id" and a 403 as
+   * "missing permission", and both send the caller looking for a fix that does
+   * not exist. Use the account-level `getTeamMembers()` family, or the
+   * dashboard.
+   */
+  dashboardOnlyTeamOperation(operation) {
+    throw new BrainerceError(
+      `${operation} is a dashboard-only operation. Store-level team management sits behind DashboardOnlyGuard, which rejects API-key principals, so there is no SDK path to it in any mode. Use the account-level team methods (getTeamMembers, inviteTeamMember, ...) or the Brainerce dashboard.`,
+      403
+    );
+  }
   /**
    * Get the team for a specific store (members + pending invitations)
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
@@ -9832,11 +10143,8 @@ var _BrainerceClient = class _BrainerceClient {
    * const { members, invitations } = await client.getStoreTeam('store_id');
    * ```
    */
-  async getStoreTeam(storeId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team`
-    );
+  async getStoreTeam(_storeId) {
+    return this.dashboardOnlyTeamOperation("getStoreTeam");
   }
   /**
    * Invite a new member to a store
@@ -9853,12 +10161,8 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async inviteStoreMember(storeId, data) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invite`,
-      data
-    );
+  async inviteStoreMember(_storeId, _data) {
+    return this.dashboardOnlyTeamOperation("inviteStoreMember");
   }
   /**
    * Update a store team member's role and/or permissions
@@ -9875,12 +10179,8 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async updateStoreMember(storeId, memberId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`,
-      data
-    );
+  async updateStoreMember(_storeId, _memberId, _data) {
+    return this.dashboardOnlyTeamOperation("updateStoreMember");
   }
   /**
    * Replace the set of vibe-coded sales channels a store member is restricted to.
@@ -9901,42 +10201,29 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async updateStoreMemberSalesChannels(storeId, memberId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}/sales-channels`,
-      data
-    );
+  async updateStoreMemberSalesChannels(_storeId, _memberId, _data) {
+    return this.dashboardOnlyTeamOperation("updateStoreMemberSalesChannels");
   }
   /**
    * Remove a member from a store team
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async removeStoreMember(storeId, memberId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`
-    );
+  async removeStoreMember(_storeId, _memberId) {
+    return this.dashboardOnlyTeamOperation("removeStoreMember");
   }
   /**
    * Resend a store invitation email
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async resendStoreInvitation(storeId, invitationId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}/resend`
-    );
+  async resendStoreInvitation(_storeId, _invitationId) {
+    return this.dashboardOnlyTeamOperation("resendStoreInvitation");
   }
   /**
    * Revoke a store invitation
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async revokeStoreInvitation(storeId, invitationId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}`
-    );
+  async revokeStoreInvitation(_storeId, _invitationId) {
+    return this.dashboardOnlyTeamOperation("revokeStoreInvitation");
   }
   /**
    * Get public invitation details by token (no auth required)
@@ -9945,7 +10232,7 @@ var _BrainerceClient = class _BrainerceClient {
   async getStoreInvitationByToken(token) {
     return this.request(
       "GET",
-      `/api/v1/store-invitations/${encodePathSegment(token)}`
+      `/api/store-invitations/${encodePathSegment(token)}`
     );
   }
   /**
@@ -9953,9 +10240,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Requires Admin mode (apiKey)
    */
   async acceptStoreInvitation(token) {
-    await this.adminRequest(
-      "POST",
-      `/api/v1/store-invitations/${encodePathSegment(token)}/accept`
+    throw new BrainerceError(
+      "acceptStoreInvitation requires a dashboard session belonging to the invited user: the invitation is matched against the email address of that user, which an API key does not have. Send the invitee to the invitation link instead.",
+      403
     );
   }
   /**
@@ -9972,7 +10259,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async getMyStores() {
-    return this.adminRequest("GET", "/api/v1/me/stores");
+    return this.dashboardOnlyUserContext("getMyStores");
   }
   /**
    * Get the current user's resolved permissions for a specific store
@@ -9986,10 +10273,23 @@ var _BrainerceClient = class _BrainerceClient {
    * }
    * ```
    */
-  async getMyStorePermissions(storeId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/me/stores/${encodePathSegment(storeId)}/permissions`
+  async getMyStorePermissions(_storeId) {
+    return this.dashboardOnlyUserContext("getMyStorePermissions");
+  }
+  /**
+   * `/me/*` answers "who am I and what can I reach", which only a real user can
+   * ask. `UserContextController` (store-team.controller.ts:246) is guarded by
+   * `DashboardOnlyGuard` for a load-bearing reason its own G16 comment spells
+   * out: both routes resolve access purely from `@CurrentUserId()`, which is
+   * `undefined` for an api_key principal, so the store filter would be stripped
+   * and every store on the platform returned. The guard is the control. These
+   * also pointed at `/api/v1/me/*`, which no controller serves, so the observed
+   * failure was a 404 rather than the guard's 403.
+   */
+  dashboardOnlyUserContext(operation) {
+    throw new BrainerceError(
+      `${operation} resolves the CURRENT USER, so it requires a dashboard session and is rejected for API-key principals by design. An API key is already scoped to one store: read it with getStore(), and read the permissions of a member from getStoreTeam() in the dashboard.`,
+      403
     );
   }
   // -------------------- Email Settings & Templates (Admin) --------------------
@@ -10132,7 +10432,7 @@ var _BrainerceClient = class _BrainerceClient {
    * Requires Admin mode (apiKey)
    */
   async getSyncConflicts() {
-    return this.adminRequest("GET", "/api/v1/sync-conflicts");
+    return this.syncConflictsNotImplemented("getSyncConflicts");
   }
   /**
    * Resolve a sync conflict
@@ -10142,12 +10442,28 @@ var _BrainerceClient = class _BrainerceClient {
    * @param resolution - 'MERGE' to link to existing product, 'CREATE_NEW' to create new product
    */
   async resolveSyncConflict(conflictId, resolution) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/sync-conflicts/${encodePathSegment(conflictId)}/resolve`,
-      {
-        resolution
-      }
+    void conflictId;
+    void resolution;
+    return this.syncConflictsNotImplemented("resolveSyncConflict");
+  }
+  /**
+   * Sync conflicts were never implemented on the server.
+   *
+   * There is no `sync-conflict` route anywhere in the backend — not under
+   * `@Controller('v1')`, not on any other controller. These two methods have
+   * called a URL that has never existed, and `SyncConflict` /
+   * `SyncConflictResolution` / `ResolveSyncConflictDto` are exported types with
+   * no producer. The METAFIELD conflict siblings below are real
+   * (external-api.controller.ts:4788, :4802) and are easy to mistake for these.
+   *
+   * Kept as throwing stubs rather than deleted: removing exported methods from a
+   * published package is a breaking change, and a caller who has been swallowing
+   * a 404 deserves to be told why.
+   */
+  syncConflictsNotImplemented(operation) {
+    throw new BrainerceError(
+      `${operation} is not implemented: the platform exposes no sync-conflict endpoint. If you are looking for metafield sync conflicts, use getMetafieldConflicts() / resolveMetafieldConflict().`,
+      501
     );
   }
   // -------------------- Metafield Conflicts (Admin) --------------------
@@ -11009,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",
@@ -11071,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.