brainerce 1.28.0 → 1.30.0

package/dist/bot/index.mjs

@@ -0,0 +1,505 @@
+// src/bot/widget.ts
+var DEFAULT_BASE_URL = "https://api.brainerce.com";
+var RTL_LOCALES = /* @__PURE__ */ new Set(["he", "ar"]);
+var CHROME = {
+  en: {
+    online: "Online",
+    placeholder: "Ask anything\u2026",
+    error: "Something went wrong \u2014 please try again.",
+    leaveMessage: "Leave a message for the team",
+    yourEmail: "Your email",
+    yourMessage: "Your message",
+    send: "Send",
+    sent: "Thanks! The team will get back to you by email.",
+    close: "Close"
+  },
+  he: {
+    online: "\u05DE\u05D7\u05D5\u05D1\u05E8",
+    placeholder: "\u05E9\u05D0\u05DC\u05D5 \u05D0\u05D5\u05EA\u05D9 \u05D4\u05DB\u05DC\u2026",
+    error: "\u05DE\u05E9\u05D4\u05D5 \u05D4\u05E9\u05EA\u05D1\u05E9 \u2014 \u05E0\u05E1\u05D5 \u05E9\u05D5\u05D1.",
+    leaveMessage: "\u05D4\u05E9\u05D0\u05D9\u05E8\u05D5 \u05D4\u05D5\u05D3\u05E2\u05D4 \u05DC\u05E6\u05D5\u05D5\u05EA",
+    yourEmail: "\u05D4\u05D0\u05D9\u05DE\u05D9\u05D9\u05DC \u05E9\u05DC\u05DB\u05DD",
+    yourMessage: "\u05D4\u05D4\u05D5\u05D3\u05E2\u05D4 \u05E9\u05DC\u05DB\u05DD",
+    send: "\u05E9\u05DC\u05D9\u05D7\u05D4",
+    sent: "\u05EA\u05D5\u05D3\u05D4! \u05D4\u05E6\u05D5\u05D5\u05EA \u05D9\u05D7\u05D6\u05D5\u05E8 \u05D0\u05DC\u05D9\u05DB\u05DD \u05D1\u05DE\u05D9\u05D9\u05DC.",
+    close: "\u05E1\u05D2\u05D9\u05E8\u05D4"
+  }
+};
+function randomId(prefix) {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const b64 = btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return `${prefix}${b64}`;
+}
+var BrainerceBot = class _BrainerceBot {
+  constructor(options) {
+    this.settings = { enabled: false };
+    this.locale = "en";
+    this.sessionId = null;
+    this.conversationId = null;
+    this.busy = false;
+    this.opened = false;
+    this.destroyed = false;
+    this.connectionId = options.connectionId;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.storageKey = `brainerce-bot:${this.connectionId}`;
+  }
+  /** Boot the widget. Resolves to null when the bot is disabled server-side. */
+  static async mount(options) {
+    if (!options?.connectionId) {
+      console.warn("[BrainerceBot] connectionId is required");
+      return null;
+    }
+    const bot = new _BrainerceBot(options);
+    const ok = await bot.boot(options.target ?? document.body);
+    return ok ? bot : null;
+  }
+  destroy() {
+    this.destroyed = true;
+    this.host?.remove();
+  }
+  // ---------------------------------------------------------------------------
+  async boot(target) {
+    try {
+      const res = await fetch(
+        `${this.baseUrl}/api/storefront-bot/${encodeURIComponent(this.connectionId)}/settings`
+      );
+      if (!res.ok) return false;
+      this.settings = await res.json();
+    } catch {
+      return false;
+    }
+    if (!this.settings.enabled) return false;
+    this.locale = this.settings.languages?.[0] ?? "en";
+    this.restoreIds();
+    this.render(target);
+    if (this.settings.displayMode === "auto_open") {
+      setTimeout(() => !this.destroyed && this.open(), 3e3);
+    }
+    return true;
+  }
+  t(key) {
+    return (CHROME[this.locale] ?? CHROME.en)[key] ?? CHROME.en[key] ?? key;
+  }
+  restoreIds() {
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        this.sessionId = parsed.sessionId ?? null;
+        this.conversationId = parsed.conversationId ?? null;
+      }
+    } catch {
+    }
+  }
+  persistIds() {
+    try {
+      localStorage.setItem(
+        this.storageKey,
+        JSON.stringify({ sessionId: this.sessionId, conversationId: this.conversationId })
+      );
+    } catch {
+    }
+  }
+  // --------------------------------------------------------------------------
+  // Rendering
+  // --------------------------------------------------------------------------
+  render(target) {
+    const accent = this.settings.accentColor || "#6366F1";
+    const dir = RTL_LOCALES.has(this.locale) ? "rtl" : "ltr";
+    const radius = this.settings.bubbleShape === "square" ? "8px" : "16px";
+    const side = this.settings.position === "start" ? "left" : "right";
+    const sideRtlAware = dir === "rtl" ? side === "left" ? "right" : "left" : side;
+    this.host = document.createElement("div");
+    this.host.setAttribute("data-brainerce-bot", this.connectionId);
+    this.root = this.host.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = `
+      :host { all: initial; }
+      * { box-sizing: border-box; font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+      .bb-root { position: fixed; bottom: 20px; ${sideRtlAware}: 20px; z-index: 2147483000; direction: ${dir}; }
+      .bb-launcher {
+        width: 56px; height: 56px; border: none; cursor: pointer; display: flex;
+        align-items: center; justify-content: center; color: #fff; background: ${accent};
+        border-radius: ${this.settings.bubbleShape === "square" ? "14px" : "9999px"};
+        box-shadow: 0 8px 24px rgba(0,0,0,.22); transition: transform .15s ease;
+        overflow: hidden; padding: 0;
+      }
+      .bb-launcher:hover { transform: scale(1.06); }
+      .bb-launcher img { width: 100%; height: 100%; object-fit: cover; }
+      .bb-window {
+        position: absolute; bottom: 70px; ${sideRtlAware}: 0; width: 360px; max-width: calc(100vw - 32px);
+        height: 540px; max-height: calc(100vh - 110px); display: none; flex-direction: column;
+        background: #fff; border-radius: 16px; overflow: hidden;
+        box-shadow: 0 16px 48px rgba(0,0,0,.24); border: 1px solid rgba(0,0,0,.06);
+      }
+      .bb-window.open { display: flex; }
+      .bb-header { display: flex; align-items: center; gap: 10px; padding: 12px 14px; background: ${accent}; color: #fff; }
+      .bb-avatar { width: 34px; height: 34px; border-radius: 9999px; background: rgba(255,255,255,.25);
+        display: flex; align-items: center; justify-content: center; font-weight: 600; overflow: hidden; flex-shrink: 0; }
+      .bb-avatar img { width: 100%; height: 100%; object-fit: cover; }
+      .bb-head-main { flex: 1; min-width: 0; }
+      .bb-name { font-size: 14px; font-weight: 600; line-height: 1.2; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+      .bb-status { font-size: 11px; opacity: .9; display: flex; align-items: center; gap: 5px; }
+      .bb-dot { width: 6px; height: 6px; border-radius: 9999px; background: #34d399; }
+      .bb-iconbtn { background: none; border: none; color: #fff; cursor: pointer; opacity: .85; font-size: 16px; padding: 4px; }
+      .bb-iconbtn:hover { opacity: 1; }
+      .bb-messages { flex: 1; overflow-y: auto; padding: 14px; background: #f7f7f9; display: flex; flex-direction: column; gap: 8px; }
+      .bb-msg { max-width: 80%; padding: 9px 12px; border-radius: ${radius}; font-size: 13.5px; line-height: 1.45; white-space: pre-wrap; word-break: break-word; }
+      .bb-msg.bot { align-self: flex-start; background: #fff; border: 1px solid rgba(0,0,0,.07); border-end-start-radius: 4px; }
+      .bb-msg.user { align-self: flex-end; background: ${accent}; color: #fff; border-end-end-radius: 4px; }
+      .bb-msg.err { align-self: flex-start; background: #fef2f2; color: #b91c1c; border: 1px solid #fecaca; }
+      .bb-typing { align-self: flex-start; font-size: 11.5px; color: #6b7280; padding: 2px 4px; }
+      .bb-card { align-self: flex-start; width: 230px; background: #fff; border: 1px solid rgba(0,0,0,.08);
+        border-radius: 12px; overflow: hidden; text-decoration: none; color: inherit; display: block; }
+      .bb-card img { width: 100%; height: 120px; object-fit: cover; display: block; background: #eee; }
+      .bb-card-body { padding: 9px 11px; }
+      .bb-card-title { font-size: 13px; font-weight: 600; margin: 0 0 3px; }
+      .bb-card-price { font-size: 13px; color: ${accent}; font-weight: 600; }
+      .bb-chips { display: flex; flex-wrap: wrap; gap: 6px; padding: 0 14px 10px; background: #f7f7f9; }
+      .bb-chip { border: 1px solid ${accent}; color: ${accent}; background: #fff; border-radius: 9999px;
+        font-size: 12px; padding: 5px 11px; cursor: pointer; }
+      .bb-inputrow { display: flex; gap: 8px; padding: 10px 12px; border-top: 1px solid rgba(0,0,0,.07); background: #fff; }
+      .bb-input { flex: 1; border: none; outline: none; font-size: 13.5px; background: #f1f1f4; border-radius: 9999px; padding: 9px 14px; }
+      .bb-send { border: none; background: ${accent}; color: #fff; width: 36px; height: 36px; border-radius: 9999px; cursor: pointer; font-size: 15px; flex-shrink: 0; }
+      .bb-send:disabled { opacity: .5; cursor: default; }
+      .bb-esc { padding: 12px 14px; background: #fff; border-top: 1px solid rgba(0,0,0,.07); display: none; flex-direction: column; gap: 8px; }
+      .bb-esc.open { display: flex; }
+      .bb-esc input, .bb-esc textarea { border: 1px solid rgba(0,0,0,.12); border-radius: 8px; padding: 8px 10px; font-size: 13px; outline: none; resize: none; }
+      .bb-esc button { border: none; background: ${accent}; color: #fff; border-radius: 8px; padding: 8px; font-size: 13px; cursor: pointer; }
+      .bb-esc-note { font-size: 12px; color: #047857; }
+    `;
+    this.root.appendChild(style);
+    const rootEl = document.createElement("div");
+    rootEl.className = "bb-root";
+    this.root.appendChild(rootEl);
+    this.windowEl = document.createElement("div");
+    this.windowEl.className = "bb-window";
+    rootEl.appendChild(this.windowEl);
+    const name = this.settings.displayName || "Assistant";
+    const header = document.createElement("div");
+    header.className = "bb-header";
+    const avatar = document.createElement("span");
+    avatar.className = "bb-avatar";
+    if (this.settings.avatarUrl && isSafeUrl(this.settings.avatarUrl)) {
+      const img = document.createElement("img");
+      img.src = this.settings.avatarUrl;
+      img.alt = "";
+      avatar.appendChild(img);
+    } else {
+      avatar.textContent = name.charAt(0).toUpperCase();
+    }
+    const headMain = document.createElement("span");
+    headMain.className = "bb-head-main";
+    const nameEl = document.createElement("span");
+    nameEl.className = "bb-name";
+    nameEl.textContent = name;
+    const statusEl = document.createElement("span");
+    statusEl.className = "bb-status";
+    const dot = document.createElement("span");
+    dot.className = "bb-dot";
+    statusEl.appendChild(dot);
+    statusEl.appendChild(document.createTextNode(this.t("online")));
+    headMain.appendChild(nameEl);
+    headMain.appendChild(statusEl);
+    const escBtn = document.createElement("button");
+    escBtn.className = "bb-iconbtn";
+    escBtn.dataset.act = "esc";
+    escBtn.title = this.t("leaveMessage");
+    escBtn.textContent = "\u2709";
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "bb-iconbtn";
+    closeBtn.dataset.act = "close";
+    closeBtn.title = this.t("close");
+    closeBtn.textContent = "\u2715";
+    header.appendChild(avatar);
+    header.appendChild(headMain);
+    header.appendChild(escBtn);
+    header.appendChild(closeBtn);
+    this.windowEl.appendChild(header);
+    header.querySelector('[data-act="close"]')?.addEventListener("click", () => this.close());
+    header.querySelector('[data-act="esc"]')?.addEventListener("click", () => this.toggleEscalation());
+    this.messagesEl = document.createElement("div");
+    this.messagesEl.className = "bb-messages";
+    this.windowEl.appendChild(this.messagesEl);
+    this.chipsEl = document.createElement("div");
+    this.chipsEl.className = "bb-chips";
+    for (const q of this.settings.starterQuestions ?? []) {
+      const chip = document.createElement("button");
+      chip.className = "bb-chip";
+      chip.textContent = q;
+      chip.addEventListener("click", () => this.send(q));
+      this.chipsEl.appendChild(chip);
+    }
+    this.windowEl.appendChild(this.chipsEl);
+    const esc = document.createElement("div");
+    esc.className = "bb-esc";
+    const escEmail = document.createElement("input");
+    escEmail.type = "email";
+    escEmail.name = "email";
+    escEmail.placeholder = this.t("yourEmail");
+    const escMsg = document.createElement("textarea");
+    escMsg.name = "message";
+    escMsg.rows = 2;
+    escMsg.placeholder = this.t("yourMessage");
+    const escSend = document.createElement("button");
+    escSend.type = "button";
+    escSend.textContent = this.t("send");
+    esc.appendChild(escEmail);
+    esc.appendChild(escMsg);
+    esc.appendChild(escSend);
+    esc.querySelector("button")?.addEventListener("click", () => this.submitEscalation(esc));
+    this.windowEl.appendChild(esc);
+    const inputRow = document.createElement("div");
+    inputRow.className = "bb-inputrow";
+    this.inputEl = document.createElement("input");
+    this.inputEl.className = "bb-input";
+    this.inputEl.placeholder = this.t("placeholder");
+    this.inputEl.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") this.send(this.inputEl?.value ?? "");
+    });
+    const sendBtn = document.createElement("button");
+    sendBtn.className = "bb-send";
+    sendBtn.textContent = "\u27A4";
+    sendBtn.addEventListener("click", () => this.send(this.inputEl?.value ?? ""));
+    inputRow.appendChild(this.inputEl);
+    inputRow.appendChild(sendBtn);
+    this.windowEl.appendChild(inputRow);
+    const launcher = document.createElement("button");
+    launcher.className = "bb-launcher";
+    launcher.setAttribute("aria-label", name);
+    if (this.settings.avatarUrl && isSafeUrl(this.settings.avatarUrl)) {
+      const img = document.createElement("img");
+      img.src = this.settings.avatarUrl;
+      img.alt = "";
+      launcher.appendChild(img);
+    } else {
+      launcher.textContent = "\u{1F4AC}";
+    }
+    launcher.addEventListener("click", () => this.opened ? this.close() : this.open());
+    rootEl.appendChild(launcher);
+    target.appendChild(this.host);
+  }
+  open() {
+    if (!this.windowEl || this.opened) return;
+    this.opened = true;
+    this.windowEl.classList.add("open");
+    if (this.messagesEl && this.messagesEl.childElementCount === 0) {
+      void this.primeThread();
+    }
+    this.inputEl?.focus();
+  }
+  close() {
+    this.opened = false;
+    this.windowEl?.classList.remove("open");
+  }
+  /** First open: restore the server thread, or show the greeting. */
+  async primeThread() {
+    if (this.conversationId && this.sessionId) {
+      try {
+        const res = await fetch(
+          `${this.baseUrl}/api/storefront-bot/${encodeURIComponent(this.connectionId)}/conversations/${encodeURIComponent(this.conversationId)}?limit=50`,
+          { headers: { "X-Bot-Session": this.sessionId } }
+        );
+        if (res.ok) {
+          const data = await res.json();
+          for (const m of data.data) {
+            this.appendMessage(m.role === "assistant" ? "bot" : "user", m.content);
+          }
+          if (data.data.length > 0) {
+            this.chipsEl?.remove();
+            return;
+          }
+        } else {
+          this.conversationId = null;
+          this.sessionId = null;
+          this.persistIds();
+        }
+      } catch {
+      }
+    }
+    if (this.settings.greeting) this.appendMessage("bot", this.settings.greeting);
+  }
+  // --------------------------------------------------------------------------
+  // The chat turn
+  // --------------------------------------------------------------------------
+  async send(text) {
+    const message = text.trim();
+    if (!message || this.busy) return;
+    this.busy = true;
+    if (this.inputEl) this.inputEl.value = "";
+    this.chipsEl?.remove();
+    this.appendMessage("user", message);
+    const typing = this.appendTyping();
+    let botBubble = null;
+    try {
+      const res = await fetch(
+        `${this.baseUrl}/api/storefront-bot/${encodeURIComponent(this.connectionId)}/chat`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            message,
+            turnId: randomId("trn_"),
+            ...this.conversationId ? { conversationId: this.conversationId } : {},
+            ...this.sessionId ? { anonymousSessionId: this.sessionId } : {},
+            locale: this.locale
+          })
+        }
+      );
+      if (!res.ok || !res.body) {
+        throw new Error(`chat failed (${res.status})`);
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      for (; ; ) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buffer.indexOf("\n\n")) >= 0) {
+          const raw = buffer.slice(0, idx);
+          buffer = buffer.slice(idx + 2);
+          if (!raw.startsWith("data: ")) continue;
+          let frame;
+          try {
+            frame = JSON.parse(raw.slice(6));
+          } catch {
+            continue;
+          }
+          botBubble = this.handleFrame(frame, typing, botBubble);
+        }
+      }
+    } catch {
+      this.appendMessage("err", this.t("error"));
+    } finally {
+      typing.remove();
+      this.busy = false;
+    }
+  }
+  handleFrame(frame, typing, botBubble) {
+    switch (frame.type) {
+      case "connected":
+        this.conversationId = frame.conversationId || this.conversationId;
+        this.sessionId = frame.anonymousSessionId || this.sessionId;
+        this.persistIds();
+        return botBubble;
+      case "token": {
+        if (!botBubble) {
+          typing.remove();
+          botBubble = this.appendMessage("bot", "");
+        }
+        botBubble.textContent = (botBubble.textContent ?? "") + frame.text;
+        this.scrollDown();
+        return botBubble;
+      }
+      case "tool":
+        typing.textContent = frame.status === "running" ? "\u22EF" : "";
+        return botBubble;
+      case "card":
+        this.appendCard(frame.card);
+        return botBubble;
+      case "error":
+        this.appendMessage("err", frame.message || this.t("error"));
+        return botBubble;
+      case "done":
+      default:
+        return botBubble;
+    }
+  }
+  // --------------------------------------------------------------------------
+  // Escalation + attribution
+  // --------------------------------------------------------------------------
+  toggleEscalation() {
+    this.root?.querySelector(".bb-esc")?.classList.toggle("open");
+  }
+  async submitEscalation(form) {
+    const email = form.querySelector('input[name="email"]')?.value.trim();
+    const message = form.querySelector('textarea[name="message"]')?.value.trim();
+    if (!email || !message || !this.conversationId || !this.sessionId) return;
+    try {
+      const res = await fetch(
+        `${this.baseUrl}/api/storefront-bot/${encodeURIComponent(this.connectionId)}/escalate`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            email,
+            message,
+            conversationId: this.conversationId,
+            anonymousSessionId: this.sessionId,
+            locale: this.locale
+          })
+        }
+      );
+      if (res.ok) {
+        const note = document.createElement("span");
+        note.className = "bb-esc-note";
+        note.textContent = this.t("sent");
+        form.replaceChildren(note);
+      }
+    } catch {
+    }
+  }
+  appendCard(card) {
+    if (!this.messagesEl) return;
+    const a = document.createElement("a");
+    a.className = "bb-card";
+    a.href = isSafeUrl(card.url) ? card.url : "#";
+    if (card.imageUrl && isSafeUrl(card.imageUrl)) {
+      const img = document.createElement("img");
+      img.src = card.imageUrl;
+      img.alt = "";
+      a.appendChild(img);
+    }
+    const body = document.createElement("span");
+    body.className = "bb-card-body";
+    const title = document.createElement("p");
+    title.className = "bb-card-title";
+    title.textContent = card.title;
+    const priceEl = document.createElement("span");
+    priceEl.className = "bb-card-price";
+    priceEl.textContent = card.price.formatted;
+    body.appendChild(title);
+    body.appendChild(priceEl);
+    a.appendChild(body);
+    a.addEventListener("click", () => {
+      try {
+        navigator.sendBeacon?.(
+          `${this.baseUrl}/api/storefront-bot/attribution/click`,
+          new Blob([JSON.stringify({ botRef: card.botRef })], { type: "application/json" })
+        );
+      } catch {
+      }
+    });
+    this.messagesEl.appendChild(a);
+    this.scrollDown();
+  }
+  // --------------------------------------------------------------------------
+  appendMessage(kind, text) {
+    const el = document.createElement("div");
+    el.className = `bb-msg ${kind}`;
+    el.textContent = text;
+    this.messagesEl?.appendChild(el);
+    this.scrollDown();
+    return el;
+  }
+  appendTyping() {
+    const el = document.createElement("div");
+    el.className = "bb-typing";
+    el.textContent = "\u22EF";
+    this.messagesEl?.appendChild(el);
+    this.scrollDown();
+    return el;
+  }
+  scrollDown() {
+    if (this.messagesEl) this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
+  }
+};
+function isSafeUrl(url) {
+  return /^\/(?!\/)/.test(url) || /^https?:\/\//i.test(url);
+}
+export {
+  BrainerceBot
+};

package/dist/index.d.mts

@@ -3807,6 +3807,35 @@ interface PublicRegionPaymentProvider {
 interface PublicRegionDetail extends PublicRegion {
     paymentProviders: PublicRegionPaymentProvider[];
 }
+/**
+ * Server-side region resolution for a buyer country (storefront seam).
+ * `matched=true` → the country was explicitly listed by a region. `false` →
+ * fell back to the default region (or `region=null` when no default exists).
+ */
+interface AutoRegionResponse {
+    region: PublicRegion | null;
+    matched: boolean;
+    /** Upper-cased ISO-3166-1 alpha-2. Empty string when caller omitted `country`. */
+    country: string;
+}
+/**
+ * Non-binding tax preview for PDP / PLP / cart. The authoritative calculation
+ * still runs at checkout against the full shipping address (state / postal /
+ * per-class). Render with an "Estimate" affordance.
+ */
+interface TaxEstimateResponse {
+    appliesTax: boolean;
+    /** Percent — e.g. 18 for 18%. `null` when no matching rule. */
+    rate: number | null;
+    rateName: string | null;
+    /** Tax portion of `subtotal` at the store's `pricesIncludeTax` mode. */
+    estimatedTax: number;
+    pricesIncludeTax: boolean;
+    /** Store currency — the cart / order currency, unchanged by FX display overlay. */
+    currency: string;
+    /** Disclaimer copy — always present to surface the "preview, not binding" nature. */
+    note: string;
+}
 interface CreateRegionDto {
     name: string;
     /** ISO 4217 */
@@ -8616,6 +8645,33 @@ declare class BrainerceClient {
      * `countries` includes `country`, else the default region, else null.
      */
     detectRegion(country: string, regions: Array<Region | PublicRegion>): Region | PublicRegion | null;
+    /**
+     * Server-side region resolution in one round trip (storefront seam). Pair
+     * with the country your edge runtime extracts — Cloudflare `CF-IPCountry`,
+     * Vercel `request.geo?.country`, Fastly `client-geo-country`, etc.
+     *
+     * Brainerce does NOT derive the country from the request IP server-side
+     * because the storefront server is what reaches the backend (not the end-
+     * customer). The storefront must extract + forward the country.
+     *
+     * Returns `{ region, matched, country }` — `matched=true` means the country
+     * was explicitly listed by a region; `false` means we fell back to the
+     * default region (or `region=null` if no default exists either).
+     */
+    getAutoRegion(country?: string): Promise<AutoRegionResponse>;
+    /**
+     * Non-binding tax preview for PDP / PLP / cart. Pass the buyer's country
+     * (from your edge runtime — same source as `getAutoRegion`) and the current
+     * items subtotal in the store currency. The authoritative tax still runs
+     * at checkout — render with an "Estimate" affordance.
+     *
+     * Returns `appliesTax=false` when tax is disabled, the country is missing,
+     * or no active rate covers it.
+     */
+    estimateTax(params: {
+        country?: string;
+        subtotal: number;
+    }): Promise<TaxEstimateResponse>;
     /**
      * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
      * safe fields only (id/name/slug/description/isDefault) for transparency UIs
@@ -9245,4 +9301,41 @@ declare function isAllowedPaymentUrl(url: string, options?: PaymentUrlOptions):
  */
 declare function safePaymentRedirect(url: string, options?: PaymentUrlOptions): void;
 
-export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };
+interface FormatProductPriceOptions {
+    /**
+     * BCP-47 locale for `Intl.NumberFormat`. Controls number grouping and
+     * currency-symbol placement. Defaults to the browser locale (client) or
+     * `"en"` (SSR / Node).
+     */
+    locale?: string;
+    /**
+     * When the product has both a regular price and a sale price, which one to
+     * format. Defaults to `"sale-if-available"` — i.e. prefer the discounted
+     * price when set, fall back to the regular price. Pass `"base"` to always
+     * format the regular price (useful for crossed-out display alongside sale).
+     */
+    prefer?: 'sale-if-available' | 'base';
+    /**
+     * Fallback ISO 4217 currency to use when a product has no
+     * `displayCurrency` (i.e. the read wasn't region-scoped or the buyer is in
+     * the default region). Usually the store's `currency` from `getStoreInfo()`.
+     * If omitted, the helper returns just the numeric amount (no symbol).
+     */
+    storeCurrency?: string;
+}
+/**
+ * Format a product's price for display. Picks the region-converted
+ * `displayPrice` / `displayCurrency` when present (set by the backend when
+ * the read was region-scoped); otherwise falls back to the canonical
+ * `basePrice` / `salePrice` in the store currency.
+ *
+ * Returns a localized string like `"€97.76"` or `"₪399.00"`. Returns `null`
+ * when no price is available (e.g. a draft product with no base price yet).
+ */
+declare function formatProductPrice(product: Pick<Product, 'basePrice' | 'salePrice' | 'displayPrice' | 'displaySalePrice' | 'displayCurrency'>, options?: FormatProductPriceOptions): string | null;
+/** Same as `formatProductPrice` but for a `ProductVariant`. */
+declare function formatVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice' | 'displayPrice' | 'displaySalePrice' | 'displayCurrency'>, options?: FormatProductPriceOptions): string | null;
+/** Format any numeric amount as currency. Useful for cart totals, fees, etc. */
+declare function formatMoney(amount: number, currency: string, locale?: string): string;
+
+export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };