brainerce 2.0.2 → 2.1.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.1";
+var SDK_VERSION = "2.0.3";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -1221,6 +1221,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).
@@ -3048,14 +3087,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');
    * }
    * ```
    */
@@ -3181,7 +3226,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.`
     );
   }
   /**
@@ -5676,6 +5721,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
    *
@@ -8027,119 +8230,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
@@ -8779,12 +8869,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(
@@ -8985,6 +9081,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 };
@@ -9055,10 +9155,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)
@@ -10486,9 +10622,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) {
@@ -10511,7 +10645,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);
@@ -10623,7 +10759,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;
@@ -10712,7 +10849,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) {