brainerce 2.0.0 → 2.1.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.0.3";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -674,7 +674,7 @@ var _BrainerceClient = class _BrainerceClient {
     }
     if (!options.salesChannelId && options.connectionId) {
       console.warn(
-        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` will be removed in SDK 2.0."
+        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` is a permanent backward-compat alias and is not scheduled for removal."
       );
     }
     if (options.apiKey && typeof window !== "undefined") {
@@ -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).
@@ -2550,6 +2589,36 @@ var _BrainerceClient = class _BrainerceClient {
   async getOrderShipments(orderId) {
     return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments`);
   }
+  /**
+   * Buy a return label the merchant sends to their customer to print.
+   *
+   * Requires admin mode (`apiKey`) with `FULFILL_ORDERS` permission — it
+   * spends the store's carrier balance, same as {@link createShippingLabel}.
+   *
+   * Unlike {@link createShippingLabel}, this is **not** on the API-key `/v1`
+   * surface — it calls the internal `/api/orders/:id/shipments/return-label`
+   * route, which takes `storeId` explicitly rather than resolving it from the
+   * key. There is no `rateId` in the body: a return is quoted and bought in
+   * one call at the shipping app, because the carrier fixes a shipment as a
+   * return when it is created and will not amend it afterwards.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createReturnLabel('store_abc', 'order_abc', {
+   *   reason: 'Wrong size',
+   *   returnForShipmentId: 'shp_original123',
+   * });
+   * console.log('Return label URL:', label.labelUrl);
+   * ```
+   */
+  async createReturnLabel(storeId, orderId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/orders/${encodePathSegment(orderId)}/shipments/return-label`,
+      data,
+      { storeId }
+    );
+  }
   /**
    * Cancel an order.
    *
@@ -2929,14 +2998,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');
    * }
    * ```
    */
@@ -3062,7 +3137,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.`
     );
   }
   /**
@@ -5557,6 +5632,164 @@ 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 });
+  }
+  // ==========================================================================
+  // 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
    *
@@ -7908,119 +8141,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
@@ -8660,12 +8780,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(
@@ -8866,6 +8992,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 };
@@ -8936,10 +9066,46 @@ 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)
@@ -9985,6 +10151,156 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/oauth-providers/${encodePathSegment(provider)}`
     );
   }
+  // -------------------- Translations (Admin) --------------------
+  // These methods require Admin mode (apiKey) with a scope-bearing key —
+  // `products:read`/`products:write` cover most entity types via
+  // StorePermissionGuard's STORE_PERMISSION_TO_SCOPE mapping (VIEW_PRODUCTS /
+  // EDIT_PRODUCTS). Routes: /api/stores/:storeId/translations/...
+  //
+  // Reads and writes the SAME `translations` JSON blob the dashboard editor
+  // uses — this is not a separate translation system, it's API-key access to
+  // the dashboard's own persistence path. Use it for bulk-importing
+  // pre-translated content or automating locale coverage without a human in
+  // the dashboard.
+  /**
+   * Get translation completeness across every translatable entity type, for
+   * one or more locales. Useful as a pre-flight before a bulk import to see
+   * which entity types/locales still need coverage.
+   * Requires Admin mode (apiKey).
+   *
+   * @param storeId - Store to inspect.
+   * @param locales - BCP-47 locale codes to check (e.g. `['he', 'fr']`). Omit
+   *   or pass an empty array to get rows with `total` populated but no
+   *   locale breakdown.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getTranslationStatus('store_123', ['he', 'fr']);
+   * const blogHe = status.find((s) => s.entityType === 'blogPost' && s.locale === 'he');
+   * console.log(`${blogHe?.missing} blog posts still need Hebrew`);
+   * ```
+   */
+  async getTranslationStatus(storeId, locales) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/status`,
+      void 0,
+      locales && locales.length > 0 ? { locales: locales.join(",") } : void 0
+    );
+  }
+  /**
+   * Get every persisted translation for a single entity, keyed by locale.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.getTranslations('store_123', 'product', 'prod_abc');
+   * console.log(translations.he?.name); // Hebrew product name, if set
+   * ```
+   */
+  async getTranslations(storeId, entityType, entityId) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}`
+    );
+  }
+  /**
+   * Set/update one locale's translation for an entity. Only the fields valid
+   * for `entityType` are persisted (e.g. `title`/`excerpt`/`content` for
+   * `blogPost`, `name`/`description` for `category`) — fields outside that
+   * entity's allowlist are silently ignored server-side, and omitted fields
+   * leave any existing translation for them untouched (this is a merge, not
+   * a replace, of the locale's fields).
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @example
+   * ```typescript
+   * // Bulk-import a pre-translated blog post
+   * await client.setTranslation('store_123', 'blogPost', 'post_abc', 'fr', {
+   *   title: 'Le titre en français',
+   *   excerpt: "L'extrait en français",
+   *   content: '<p>Le contenu en français</p>',
+   * });
+   * ```
+   */
+  async setTranslation(storeId, entityType, entityId, locale, fields) {
+    return this.adminRequest(
+      "PUT",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`,
+      fields
+    );
+  }
+  /**
+   * Delete one locale's translation for an entity. The entity's base
+   * (default-locale) fields are unaffected.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   */
+  async deleteTranslation(storeId, entityType, entityId, locale) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`
+    );
+  }
+  /**
+   * AI-translate a single entity into one target locale and persist the
+   * result inline (synchronous — the response already reflects the write).
+   * Only fields that are still empty for `targetLocale` are filled; existing
+   * translated values are never overwritten.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param sourceFields - Optional override of the source-language text to
+   *   translate from (e.g. unsaved edits from an open editor), instead of the
+   *   entity's persisted base fields. Keys outside the entity's translatable
+   *   field set are ignored.
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.aiTranslateSingle('store_123', {
+   *   entityType: 'product',
+   *   entityId: 'prod_abc',
+   *   targetLocale: 'he',
+   * });
+   * ```
+   */
+  async aiTranslateSingle(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate-single`,
+      input
+    );
+  }
+  /**
+   * Bulk AI-translate — enqueues a background job per entity (and, for
+   * `entityType: 'attribute'`, one per attribute option too) rather than
+   * translating inline. Returns the number of jobs queued, not the finished
+   * translations; poll `getTranslationStatus` or `getTranslations` to see
+   * results land.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param entityIds - Optional explicit ids to translate. Omit to target
+   *   every entity of `entityType` in the store that isn't already fully
+   *   translated for `targetLocale`.
+   *
+   * @example
+   * ```typescript
+   * // Translate every blog post missing French coverage
+   * const { queued } = await client.aiTranslateBulk('store_123', {
+   *   entityType: 'blogPost',
+   *   targetLocale: 'fr',
+   * });
+   * ```
+   */
+  async aiTranslateBulk(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate`,
+      input
+    );
+  }
 };
 /**
  * Fields present on `getAddressDetails().address` that the address endpoints
@@ -10217,9 +10533,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) {
@@ -10242,7 +10556,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);
@@ -10354,7 +10670,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;
@@ -10443,7 +10760,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) {