brainerce 2.0.2 → 2.2.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.1";
+var SDK_VERSION = "2.2.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -361,7 +361,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.
@@ -398,7 +398,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);
@@ -1132,6 +1132,45 @@ var _BrainerceClient = class _BrainerceClient {
   getStoreDirection(locale) {
     return getDirectionForLocale(locale ?? this.locale);
   }
+  /**
+   * Get what the merchant actually configured on this sales channel: store
+   * identity and multi-language setup, the channel's own settings (low-stock
+   * warning and threshold, reservation strategy and timeout, birthday and
+   * email-verification requirements, granted scopes) and which optional
+   * features are switched on (payment providers, social login, coupons,
+   * discount rules, shipping zones, downloadables, content, loyalty).
+   *
+   * Read this instead of hardcoding. A storefront with a hardcoded low-stock
+   * threshold shows the wrong badge on every store whose merchant chose a
+   * different one, and a storefront that renders a feature nobody enabled
+   * ships a control that silently does nothing.
+   *
+   * Only available in vibe-coded mode (`salesChannelId`). The payload belongs
+   * to one sales channel: `storeId` mode has no channel to read it from, and
+   * an `apiKey` addresses the store rather than any single channel.
+   *
+   * Call it once for the whole app and share the result. It is per channel,
+   * not per product, so fetching it on every page is wasted work.
+   *
+   * @example
+   * ```typescript
+   * const caps = await client.getStoreCapabilities();
+   *
+   * // Low stock: honour the switch before the number.
+   * const threshold = caps.connection.lowStockWarning
+   *   ? caps.connection.lowStockThreshold
+   *   : 0;
+   *
+   * if (caps.features.hasCoupons) renderCouponInput();
+   * if (caps.store.i18n?.enabled) renderLocaleSwitcher(caps.store.i18n.supportedLocales);
+   * ```
+   */
+  async getStoreCapabilities() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/capabilities");
+    }
+    throw new BrainerceError("getStoreCapabilities is only available in vibe-coded mode", 400);
+  }
   // -------------------- Analytics --------------------
   /**
    * Send a storefront analytics beacon (pageview or engagement).
@@ -1979,11 +2018,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
     );
   }
   /**
@@ -2959,14 +2996,20 @@ var _BrainerceClient = class _BrainerceClient {
     });
   }
   /**
-   * Get platform capabilities for coupon features.
-   * Use this to understand what features each platform supports.
+   * Get platform capabilities for coupon features, keyed by platform.
+   *
+   * ⛔ **Returns an empty object today.** Platform coupon capabilities moved
+   * into the standalone connector apps and are not re-exposed here yet, so the
+   * endpoint answers `{}` for every store. Treat a missing key as "unknown",
+   * never as "the platform lacks the feature", and do not index into a platform
+   * key without checking it exists first — there are none to find.
    *
    * @example
    * ```typescript
    * const capabilities = await client.getCouponPlatformCapabilities();
-   * if (!capabilities.SHOPIFY.supportsProductExclusions) {
-   *   console.log('Shopify does not support product exclusions');
+   * const meta = capabilities['GOOGLE'];
+   * if (meta && !meta.supportsProducts) {
+   *   console.log('This platform cannot target individual products');
    * }
    * ```
    */
@@ -3092,7 +3135,7 @@ var _BrainerceClient = class _BrainerceClient {
       );
     }
     console.warn(
-      `BrainerceClient.${methodName}: passing \`storeId\` is deprecated \u2014 it is now derived from the SDK config. Remove the leading argument; this overload will be removed in SDK 2.0.`
+      `BrainerceClient.${methodName}: passing \`storeId\` is deprecated \u2014 it is now derived from the SDK config. Remove the leading argument; this overload will be removed in a future major version.`
     );
   }
   /**
@@ -5587,6 +5630,324 @@ var _BrainerceClient = class _BrainerceClient {
       "checkout"
     );
   }
+  /**
+   * Apply a gift card to a checkout.
+   *
+   * Merchants issue cards from the dashboard, so live codes exist and this field
+   * is worth building. There is still no way for a shopper to BUY a gift card —
+   * no product type, no purchase flow — so every card in circulation was issued
+   * by hand.
+   *
+   * Redemption is deliberately NOT gated on the store's gift-card switch: a
+   * store that turned the feature off still owes every card already in a
+   * customer's hand, so the field keeps working. Build it unconditionally.
+   *
+   * A gift card is a **means of payment, not a discount**. The order total does
+   * not change and tax stays calculated on the full value; what changes is
+   * `providerAmountDue`, the amount the payment provider will be charged.
+   *
+   * Render it as its own line — "Gift card −₪54.50" beside the total — and NOT
+   * by adding it to `discountAmount`. A shopper who sees stored value folded
+   * into a discount is being shown the wrong thing, and so is their receipt.
+   *
+   * Only as much of the card as the order still owes is applied, so a card
+   * larger than the basket leaves a balance on it for next time, and a smaller
+   * one leaves an amount for the provider to charge.
+   *
+   * @example
+   * const { amountApplied, providerAmountDue, tenderId } =
+   *   await client.applyGiftCard('checkout_123', 'A1B2-C3D4-E5F6-G7H8-J9K0');
+   * // total is unchanged; charge the provider providerAmountDue
+   */
+  async applyGiftCard(checkoutId, code) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        `/checkout/${encodePathSegment(checkoutId)}/gift-card`,
+        { code }
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        `/checkout/${encodePathSegment(checkoutId)}/gift-card`,
+        { code }
+      );
+    }
+    return this.adminRequest(
+      "POST",
+      `/api/v1/checkout/${encodePathSegment(checkoutId)}/gift-card`,
+      { code }
+    );
+  }
+  /**
+   * Remove a previously applied gift card from a checkout.
+   *
+   * Takes the `tenderId` returned by {@link applyGiftCard}, not the code — a
+   * checkout can carry more than one card, and the code is never echoed back.
+   *
+   * The held value goes straight back to the card. Nothing was ever debited
+   * while it was applied, so removing costs the shopper nothing.
+   */
+  async removeGiftCard(checkoutId, tenderId) {
+    const path = `/checkout/${encodePathSegment(checkoutId)}/gift-card/${encodePathSegment(tenderId)}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("DELETE", path);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("DELETE", path);
+    }
+    return this.adminRequest("DELETE", `/api/v1${path}`);
+  }
+  /**
+   * Check what is left on a gift card.
+   *
+   * Rate limited, and deliberately uninformative: a code that does not exist,
+   * one that has been disabled and one that has expired all return the SAME
+   * response — `{ balance: '0.00', usable: false }` — and take the same time to
+   * do it. Do not build UI that tries to tell those apart, because the API will
+   * not tell you, by design: a gift-card code is bearer value, and an endpoint
+   * that confirmed which codes were real would be a free way to find them.
+   *
+   * Show "we cannot use this code" and let the shopper re-enter it.
+   */
+  async checkGiftCardBalance(code) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", "/gift-cards/balance", { code });
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", "/gift-cards/balance", { code });
+    }
+    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 `Idempotency-Key` header to make a retry safe.
+   *
+   * Requires `gift_cards:issue`.
+   *
+   * @example
+   * ```typescript
+   * const card = await client.issueGiftCard({
+   *   amount: '200.00',
+   *   note: 'Compensation for order #1042',
+   *   recipientEmail: 'dana@example.com',
+   * });
+   * await sendToCustomer(card.plaintextCode); // your only chance
+   * ```
+   */
+  async issueGiftCard(data) {
+    return this.adminRequest("POST", "/api/v1/gift-cards", data);
+  }
+  /**
+   * 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.
+   *
+   * Requires `gift_cards:issue`.
+   */
+  async reissueGiftCard(giftCardId, note) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/reissue`,
+      { note }
+    );
+  }
+  /**
+   * 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.
+   *
+   * Requires `gift_cards:adjust`.
+   */
+  async adjustGiftCardBalance(giftCardId, delta, note) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/adjust`,
+      { delta, note }
+    );
+  }
+  /**
+   * 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) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/status`,
+      { status }
+    );
+  }
+  /**
+   * 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) {
+    return this.adminRequest("PATCH", "/api/v1/gift-cards/bulk/status", {
+      giftCardIds,
+      status
+    });
+  }
+  // ==========================================================================
+  // Donations
+  // ==========================================================================
+  /**
+   * Start a donation.
+   *
+   * A donation does not go through the cart. There is no line item, no
+   * quantity, no shipping and no order — a donor names an amount and pays it,
+   * which is a different shape of transaction from a purchase. Do not model a
+   * donation as a product; if you already have, the amount is the giveaway:
+   * you cannot let a donor type one.
+   *
+   * ⛔ A successful return is NOT a completed gift. You get back a PENDING
+   * donation and a provider intent to complete, exactly as with a checkout.
+   * The gift is only real once the provider's webhook confirms it, which is
+   * when the donation reads back as `PAID`. Show a thank-you that reflects
+   * that, and never send a receipt off the back of this call.
+   *
+   * Requires donations to be switched on for the store; a store that has not
+   * turned them on is rejected rather than silently accepting money.
+   *
+   * ```ts
+   * const donation = await brainerce.createDonation({
+   *   amount: 180,
+   *   feeCoverAmount: 6.3,        // offered as a checkbox; most donors accept
+   *   donorEmail: 'sarah@example.com',
+   *   donorName: 'Sarah Cohen',
+   *   tributeType: 'IN_MEMORY',
+   *   tributeName: 'Avraham Cohen',
+   *   returnPath: '/thank-you',
+   * });
+   * // → complete donation.payment with your provider, then poll getDonation()
+   * ```
+   */
+  async createDonation(input) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", "/donations", input);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", "/donations", input);
+    }
+    throw new Error(
+      "createDonation is a storefront call. Initialise the SDK with a salesChannelId or storeId \u2014 an admin apiKey cannot start a donation."
+    );
+  }
+  /**
+   * Read a donation back — for a thank-you page, and to see whether it is paid.
+   *
+   * Rate limited to 5 requests a minute, because an id that either resolves or
+   * 404s is a way to enumerate them. Poll it a handful of times after the donor
+   * returns from the provider; do not put it behind a 1-second interval.
+   *
+   * The payload is narrow on purpose: no failure reason, and `donorName` comes
+   * back `null` whenever the gift was marked anonymous — so you can render this
+   * straight onto a public page without leaking anything.
+   */
+  async getDonation(donationId) {
+    const path = `/donations/${encodePathSegment(donationId)}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", path);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", path);
+    }
+    throw new Error(
+      "getDonation is a storefront call. Initialise the SDK with a salesChannelId or storeId."
+    );
+  }
   /**
    * Set customer information on checkout
    *
@@ -5662,10 +6023,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).
@@ -5924,7 +6282,7 @@ 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).
@@ -7938,119 +8296,6 @@ var _BrainerceClient = class _BrainerceClient {
     }
     return this.storefrontRequest("GET", "/customers/me/cart");
   }
-  // -------------------- Custom API Integrations --------------------
-  // These methods require Admin mode (apiKey)
-  /**
-   * Get all Custom API integrations for a store
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * const integrations = await client.getCustomApiIntegrations();
-   * integrations.forEach(api => {
-   *   console.log(`${api.name}: ${api.status}`);
-   * });
-   * ```
-   */
-  async getCustomApiIntegrations() {
-    return this.adminRequest("GET", "/api/v1/custom-api");
-  }
-  /**
-   * Get a single Custom API integration by ID
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * const api = await client.getCustomApiIntegration('api_123');
-   * console.log(`API: ${api.name}, URL: ${api.baseUrl}`);
-   * ```
-   */
-  async getCustomApiIntegration(integrationId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/custom-api/${encodePathSegment(integrationId)}`
-    );
-  }
-  /**
-   * Create a new Custom API integration
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * const api = await client.createCustomApiIntegration({
-   *   name: 'My External API',
-   *   baseUrl: 'https://api.example.com',
-   *   authType: 'api_key',
-   *   credentials: {
-   *     apiKey: 'sk_123...',
-   *     headerName: 'X-API-Key',
-   *   },
-   *   syncDirection: 'bidirectional',
-   *   syncConfig: {
-   *     products: true,
-   *     orders: true,
-   *     inventory: true,
-   *   },
-   * });
-   * ```
-   */
-  async createCustomApiIntegration(data) {
-    return this.adminRequest("POST", "/api/v1/custom-api", data);
-  }
-  /**
-   * Update a Custom API integration
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * const api = await client.updateCustomApiIntegration('api_123', {
-   *   enabled: false,
-   *   syncConfig: { products: true, orders: false, inventory: true },
-   * });
-   * ```
-   */
-  async updateCustomApiIntegration(integrationId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/custom-api/${encodePathSegment(integrationId)}`,
-      data
-    );
-  }
-  /**
-   * Delete a Custom API integration
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * await client.deleteCustomApiIntegration('api_123');
-   * ```
-   */
-  async deleteCustomApiIntegration(integrationId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/custom-api/${encodePathSegment(integrationId)}`
-    );
-  }
-  /**
-   * Test connection to a Custom API
-   * Requires Admin mode (apiKey)
-   *
-   * @example
-   * ```typescript
-   * const result = await client.testCustomApiConnection('api_123');
-   * if (result.success) {
-   *   console.log(`Connection OK, latency: ${result.latency}ms`);
-   * } else {
-   *   console.error(`Connection failed: ${result.error}`);
-   * }
-   * ```
-   */
-  async testCustomApiConnection(integrationId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/custom-api/${encodePathSegment(integrationId)}/test`
-    );
-  }
   // -------------------- Inventory Reservations --------------------
   // These methods are only available in vibe-coded mode when reservation strategy
   // is set to ON_CART or ON_CHECKOUT
@@ -8690,12 +8935,18 @@ var _BrainerceClient = class _BrainerceClient {
    * ```typescript
    * const rate = await client.createZoneShippingRate('zone_123', {
    *   name: 'Standard Shipping',
-   *   type: 'flat',
-   *   price: 5.99,
-   *   minOrderValue: 0,
-   *   estimatedDays: '3-5',
+   *   type: 'FLAT_RATE',
+   *   rateConfig: { amount: 5.99 },
+   *   minDeliveryDays: 3,
+   *   maxDeliveryDays: 5,
    * });
    * ```
+   *
+   * The price lives in `rateConfig`, whose shape follows `type` — `FLAT_RATE`
+   * takes `{ amount }`, `WEIGHT_BASED` and `PRICE_BASED` take tier arrays, and
+   * `FREE` and `LOCAL_PICKUP` take none. Unknown top-level properties are
+   * rejected outright rather than ignored, so a stray `price` or
+   * `estimatedDays` fails the whole call with 400.
    */
   async createZoneShippingRate(zoneId, data) {
     return this.adminRequest(
@@ -8896,6 +9147,10 @@ var _BrainerceClient = class _BrainerceClient {
    *
    * Returns `appliesTax=false` when tax is disabled, the country is missing,
    * or no active rate covers it.
+   *
+   * The preview has no province, so it only sees country-level rates: a
+   * Canadian estimate shows the federal GST alone and the provincial PST/QST
+   * joins it at checkout. Render `note` so the buyer is not surprised.
    */
   async estimateTax(params) {
     const query = params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal };
@@ -8966,10 +9221,43 @@ var _BrainerceClient = class _BrainerceClient {
   /**
    * Get all tax rates for the store
    * Requires Admin mode (apiKey)
+   *
+   * A jurisdiction can need more than one rate. Canada is the common case: a
+   * country-level `GST` row plus a province-level `PST`/`QST` row, both with
+   * `stackable: true`, which the checkout charges together. Provinces on HST
+   * carry a single combined row with `stackable: false`.
    */
   async getTaxRates() {
     return this.adminRequest("GET", "/api/v1/tax/rates");
   }
+  /**
+   * List the country tax presets available to apply.
+   * Requires Admin mode (apiKey)
+   */
+  async getTaxPresets() {
+    return this.adminRequest("GET", "/api/v1/tax/presets");
+  }
+  /**
+   * Apply a country's whole tax table in one call, instead of creating a rate
+   * per province by hand. Requires Admin mode (apiKey).
+   *
+   * `CA` writes ten rates: federal GST 5% country-wide, one combined HST row
+   * each for ON/NB/NL/NS/PE, and PST/RST/QST for BC/SK/MB/QC charged on top of
+   * the GST. Alberta and the territories need no row — the GST covers them.
+   *
+   * Throws 409 when the store already has rates for that country; delete those
+   * first if you meant to replace them. Rates land in the Standard tax class.
+   *
+   * Brainerce does not register the store for GST/HST and does not file returns.
+   *
+   * @example
+   * ```typescript
+   * const { created } = await client.applyTaxPreset('CA'); // created === 10
+   * ```
+   */
+  async applyTaxPreset(presetKey) {
+    return this.adminRequest("POST", `/api/v1/tax/presets/${encodePathSegment(presetKey)}/apply`);
+  }
   /**
    * Get a single tax rate by ID
    * Requires Admin mode (apiKey)
@@ -9598,6 +9886,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
@@ -9607,11 +9916,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
@@ -9628,12 +9934,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
@@ -9650,12 +9952,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.
@@ -9676,42 +9974,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)
@@ -9720,7 +10005,7 @@ var _BrainerceClient = class _BrainerceClient {
   async getStoreInvitationByToken(token) {
     return this.request(
       "GET",
-      `/api/v1/store-invitations/${encodePathSegment(token)}`
+      `/api/store-invitations/${encodePathSegment(token)}`
     );
   }
   /**
@@ -9728,9 +10013,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
     );
   }
   /**
@@ -9747,7 +10032,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
@@ -9761,10 +10046,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) --------------------
@@ -9907,7 +10205,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
@@ -9917,12 +10215,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) --------------------
@@ -10397,9 +10711,7 @@ function validateDateAvailabilityConfig(config, fieldType, surface = "checkout")
       (k) => config[k] !== void 0
     );
     if (relativeKeys.length > 0) {
-      errors.push(
-        `${relativeKeys.join("/")} only apply to checkout fields, not ${surface} fields`
-      );
+      errors.push(`${relativeKeys.join("/")} only apply to checkout fields, not ${surface} fields`);
     }
   }
   if (config.blockedWeekdays) {
@@ -10422,7 +10734,9 @@ function validateDateAvailabilityConfig(config, fieldType, surface = "checkout")
     const windowsByWeekday = /* @__PURE__ */ new Map();
     for (const w of config.businessHours) {
       if (!Number.isInteger(w.weekday) || w.weekday < 0 || w.weekday > 6) {
-        errors.push(`businessHours.weekday must be an integer 0-6, got ${JSON.stringify(w.weekday)}`);
+        errors.push(
+          `businessHours.weekday must be an integer 0-6, got ${JSON.stringify(w.weekday)}`
+        );
         continue;
       }
       const openValid = TIME_RE.test(w.open);
@@ -10534,7 +10848,8 @@ function addCalendarDays(dateYYYYMMDD, days) {
 function parseDateFieldValue(raw, fieldType, timezone) {
   const str = raw instanceof Date ? Number.isNaN(raw.getTime()) ? "" : raw.toISOString() : typeof raw === "string" ? raw.trim() : "";
   const expected = fieldType === "DATE" ? "expected a calendar date in YYYY-MM-DD format" : "expected an ISO-8601 date/time such as 2026-08-13T13:00:00+03:00";
-  if (!str) return { status: "invalid", reason: `"${String(raw)}" is not a valid date \u2014 ${expected}` };
+  if (!str)
+    return { status: "invalid", reason: `"${String(raw)}" is not a valid date \u2014 ${expected}` };
   const dateOnly = DATE_ONLY_RE.exec(str);
   const dateTime = dateOnly ? null : DATE_TIME_RE.exec(str);
   const match = dateOnly ?? dateTime;
@@ -10623,7 +10938,14 @@ function timezoneOffsetMs(utcMillis, timezone) {
   }
   const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
   const hour = get("hour") === 24 ? 0 : get("hour");
-  const asIfUtc = Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second"));
+  const asIfUtc = Date.UTC(
+    get("year"),
+    get("month") - 1,
+    get("day"),
+    hour,
+    get("minute"),
+    get("second")
+  );
   return asIfUtc - Math.floor(utcMillis / 1e3) * 1e3;
 }
 function isCalendarDateAllowed(dateYYYYMMDD, config, clock) {