brainerce 1.28.1 → 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

package/dist/index.d.ts

@@ -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

package/dist/index.js

@@ -7054,6 +7054,44 @@ var BrainerceClient = class {
     const code = country.toUpperCase();
     return regions.find((r) => r.countries.includes(code)) ?? regions.find((r) => r.isDefault) ?? 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).
+   */
+  async getAutoRegion(country) {
+    return this.storefrontRequest(
+      "GET",
+      "/regions/auto",
+      void 0,
+      country ? { country } : void 0
+    );
+  }
+  /**
+   * 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.
+   */
+  async estimateTax(params) {
+    return this.storefrontRequest(
+      "GET",
+      "/tax/estimate",
+      void 0,
+      params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal }
+    );
+  }
   // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
   /**
    * List the store's tax classes (public, no apiKey — storeId mode). Storefront-