@brainerce/mcp-server 3.9.0 → 3.11.1

package/dist/index.js

@@ -186,7 +186,26 @@ import {
   getDescriptionContent, isHtmlDescription,
   getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
-\`\`\``;
+\`\`\`
+
+### Available features \u2014 request each topic for full docs
+
+| Topic | What it covers |
+|-------|----------------|
+| \`products\` | Catalog listing, search, PDP, variants, swatches, stock, attributes |
+| \`cart\` | Guest + logged-in cart, add/remove/update, reservations |
+| \`checkout\` | Guest + customer checkout, shipping, address |
+| \`payment\` | Payment providers, intents, status polling, confirmation |
+| \`auth\` | Customer sign-up, login, OAuth, email verification |
+| \`discounts\` | Coupons, banners, nudges |
+| \`recommendations\` | Cross-sell / upsell grids |
+| \`reviews\` | Product reviews & ratings |
+| \`inventory\` | Stock badges, reservation countdown |
+| \`inquiries\` | Contact / custom forms |
+| \`i18n\` | Multi-language, RTL |
+| \`admin\` | Server-to-server admin API (products, orders, customers) |
+| \`storefront-bot\` | **AI chat widget** \u2014 add Brainerce's AI shopping assistant to any page with one script tag or \`BrainerceBot.mount()\`. Answers product questions, shows recommendation cards, handles cart adds, opens escalation form. |
+| \`content\` | Blog, articles, static pages |`;
 }
 function getCheckoutFlowSection(_currency) {
   return `## \u26A0\uFE0F CHECKOUT FLOW (CRITICAL \u2014 READ CAREFULLY!)
@@ -735,7 +754,7 @@ const growProvider = providers.find(p => p.provider === 'grow');
 const paypalProvider = providers.find(p => p.provider === 'paypal');
 \`\`\`
 
-Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'morning'\`, \`'takbull'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
 
 The payment intent returned from \`createPaymentIntent()\` includes a \`clientSdk\` object whose \`renderType\` tells you exactly how to render \u2014 **branch on THAT, not on the provider name**:
 
@@ -1908,8 +1927,8 @@ function getTaxDisplaySection(_currency) {
 | Product Page | \u274C No | "Price excludes tax" (optional note) |
 | Cart Page | \u26A0\uFE0F "Calculated at checkout" | No address yet |
 | Checkout (before address) | \u26A0\uFE0F "Enter address to calculate" | Waiting for location |
-| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` |
-| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` |
+| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` (0 in VAT mode \u2192 \`checkout.taxBreakdown.totalTax\`) |
+| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` (0 in VAT mode \u2192 \`order.taxBreakdown.totalTax\`) |
 
 ### Cart Page \u2014 Partial Display
 
@@ -1961,7 +1980,13 @@ const totals = getCartTotals(cart);
     <div className="flex justify-between text-green-600"><span>Discount</span><span>-{formatPrice(order.discountAmount, { currency: order.currency })}</span></div>
   )}
   <div className="flex justify-between"><span>Shipping</span><span>{formatPrice(order.shippingAmount, { currency: order.currency })}</span></div>
-  <div className="flex justify-between"><span>Tax</span><span>{formatPrice(order.taxAmount, { currency: order.currency })}</span></div>
+  {/* Inclusive (VAT) stores keep taxAmount="0" \u2014 the real VAT is on taxBreakdown.totalTax. */}
+  {(() => {
+    const tax = parseFloat(order.taxAmount || '0') || order.taxBreakdown?.totalTax || 0;
+    if (tax <= 0) return null;
+    const incl = order.taxBreakdown?.pricesIncludeTax;
+    return <div className="flex justify-between"><span>{incl ? 'Tax (incl.)' : 'Tax'}</span><span>{formatPrice(tax, { currency: order.currency })}</span></div>;
+  })()}
   <div className="flex justify-between font-bold text-lg border-t pt-2"><span>Total Paid</span><span>{formatPrice(order.totalAmount, { currency: order.currency })}</span></div>
 </div>
 \`\`\``;
@@ -2090,7 +2115,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
-| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
 
@@ -2394,6 +2419,67 @@ Read \`storeInfo.i18n.supportedLocales\` and render a switcher in the header
 that navigates to \`/{otherLocale}/{currentPathWithoutLocale}\`. The middleware
 handles the canonical redirect when the user picks the default locale.`;
 }
+function getMultilingualSeoSection() {
+  return `## Multilingual SEO
+
+### Slugs per locale (IMPORTANT)
+
+Brainerce stores per-locale slugs in \`Product.translations[locale].slug\`.
+The API exposes them as \`product.localeSlugs\` \u2014 a flat \`Record<string, string>\`.
+
+\`\`\`typescript
+// product.localeSlugs = { he: '\u05DE\u05D6\u05E8\u05DF-\u05D9\u05D5\u05D2\u05D4', en: 'yoga-mattress', ar: '\u062D\u0635\u064A\u0631\u0629-\u064A\u0648\u063A\u0627' }
+const locSlug = product.localeSlugs?.[locale] ?? product.slug;
+\`\`\`
+
+Use AI translation (\`translateEntities\` / the AI Translate button in the admin) to populate
+locale-specific slugs automatically. Until translated, all locales fall back to the base slug
+(which Google still accepts \u2014 it resolves to the correct locale content via Accept-Language).
+
+### hreflang tags
+
+Every product page in a multi-locale store MUST emit bidirectional hreflang tags or Google
+ignores them entirely. The scaffolded template generates them automatically when
+\`NEXT_PUBLIC_BRAINERCE_LOCALES=he,en\` is set.
+
+\`\`\`html
+<!-- Example output for /en/products/yoga-mattress -->
+<link rel="alternate" hreflang="he"      href="https://store.com/products/\u05DE\u05D6\u05E8\u05DF-\u05D9\u05D5\u05D2\u05D4" />
+<link rel="alternate" hreflang="en"      href="https://store.com/en/products/yoga-mattress" />
+<link rel="alternate" hreflang="x-default" href="https://store.com/products/\u05DE\u05D6\u05E8\u05DF-\u05D9\u05D5\u05D2\u05D4" />
+\`\`\`
+
+If building a custom storefront, add to \`generateMetadata()\`:
+\`\`\`typescript
+alternates: {
+  canonical: locale === defaultLoc ? \`/products/\${slug}\` : \`/\${locale}/products/\${slug}\`,
+  languages: {
+    he: \`\${baseUrl}/products/\${localeSlugs.he ?? baseSlug}\`,
+    en: \`\${baseUrl}/en/products/\${localeSlugs.en ?? baseSlug}\`,
+    'x-default': \`\${baseUrl}/products/\${localeSlugs[defaultLoc] ?? baseSlug}\`,
+  },
+},
+\`\`\`
+
+### URL structure
+
+Google-recommended for headless storefronts:
+- Default locale: \`/products/\u05DE\u05D6\u05E8\u05DF-\u05D9\u05D5\u05D2\u05D4\` (no prefix)
+- Other locales:  \`/en/products/yoga-mattress\` (prefixed)
+- \u274C Never: \`?locale=he\` query params (Google rates these as "Not recommended")
+
+### Sitemap
+
+The scaffolded \`sitemap.ts\` generates per-locale entries automatically:
+\`\`\`
+/products/\u05DE\u05D6\u05E8\u05DF-\u05D9\u05D5\u05D2\u05D4         (he \u2014 default, no prefix)
+/en/products/yoga-mattress  (en)
+/ar/products/\u062D\u0635\u064A\u0631\u0629-\u064A\u0648\u063A\u0627    (ar)
+\`\`\`
+
+Hebrew, Arabic, and other non-Latin slugs are fully supported \u2014 Google recommends
+using the audience's language in URLs and indexes non-ASCII characters correctly.`;
+}
 function getAdminApiSection() {
   return `## Admin API (v0.19.0+)
 
@@ -2477,6 +2563,20 @@ await admin.mergeTaxClasses(food.id, standardClassId);
 Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
 the store's classes (storefront-safe fields only) for a transparency badge.
 
+For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
+subtotal })\` returns the tax portion at the Standard rate for the buyer's
+country. **Non-binding** \u2014 the authoritative tax still runs at checkout with
+the full shipping address (state / postal / per-class). Always render with an
+"Estimate" affordance.
+
+\`\`\`typescript
+const { estimatedTax, rate, currency, note } = await store.estimateTax({
+  country: 'IT', subtotal: 100,
+});
+// \u2192 { appliesTax: true, rate: 22, estimatedTax: 22, currency: 'EUR',
+//     note: 'Estimate \u2014 final tax calculated at checkout\u2026' }
+\`\`\`
+
 ### Regions (multi-currency / per-region providers)
 
 A region binds countries \u2192 currency + tax-display mode + enabled payment
@@ -2507,6 +2607,19 @@ const { data: regions } = await store.getStoreRegions();
 const region = await store.getStoreRegion(regions[0].id);
 \`\`\`
 
+For a single round trip, \`getAutoRegion(country)\` resolves a buyer's country
+to a region server-side. Brainerce does NOT derive the country from the request
+IP (the storefront server is what reaches the backend, not the end-customer) \u2014
+your storefront extracts the country from its edge runtime (Cloudflare
+\`CF-IPCountry\`, Vercel \`request.geo?.country\`, Fastly \`client-geo-country\`,
+etc.) and forwards it. Returns \`matched=true\` on explicit country hit, \`false\`
+when falling back to the default region.
+
+\`\`\`typescript
+const country = headers.get('cf-ipcountry') ?? 'US';
+const { region, matched } = await store.getAutoRegion(country);
+\`\`\`
+
 A shipping zone can be limited to regions via \`regionIds\` \u2014 the zone is then
 only offered to checkouts that resolved to one of those regions. Empty/omitted =
 available for any region (default); each id must belong to the same store.
@@ -2970,6 +3083,146 @@ entries \u2014 pick a descriptive slug (\`'shipping'\`, \`'returns'\`, \`'about'
 - \`get-type-definitions\` with \`domain: 'content'\` for the TypeScript
   interfaces.`;
 }
+function getBlogSection() {
+  return `## Blog
+
+Merchants write and schedule blog posts in **Content \u2192 Blog** in the dashboard.
+Storefronts choose their own URL scheme \u2014 render posts at \`/blog/[slug]\`,
+\`/articles/[slug]\`, or whatever fits the brand.
+
+Public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`.
+
+**Scheduling:** A post is visible once \`status === 'PUBLISHED'\` and
+\`publishedAt <= now()\`. Set a future \`publishedAt\` while publishing to
+schedule \u2014 no cron needed; visibility is computed at query time.
+
+### Reading posts (any SDK mode)
+
+\`\`\`typescript
+// List published posts
+const { data: posts, meta } = await client.blog.getPosts({ page: 1, limit: 10 });
+
+// Filter by category or tag
+const { data: news } = await client.blog.getPosts({ category: 'news' });
+const { data: tips } = await client.blog.getPosts({ tag: 'tutorial' });
+
+// Fetch one by slug (returns null on 404)
+const post = await client.blog.getPost('my-first-post');
+if (post) {
+  console.log(post.title);     // string
+  console.log(post.content);   // HTML string from rich-text editor
+  console.log(post.excerpt);   // optional short summary
+  console.log(post.tags);      // string[]
+  console.log(post.coverImageUrl, post.coverImageAlt);
+  console.log(post.publishedAt); // ISO 8601 or undefined
+}
+\`\`\`
+
+### BlogPost fields
+
+| Field             | Type        | Notes                                 |
+| ----------------- | ----------- | ------------------------------------- |
+| \`id\`            | string      |                                       |
+| \`title\`         | string      |                                       |
+| \`slug\`          | string      | Unique per store, URL-safe            |
+| \`category\`      | string?     | Free-form (e.g. \`'news'\`)           |
+| \`content\`       | string      | HTML from rich-text editor            |
+| \`excerpt\`       | string?     | Short summary for listing cards       |
+| \`coverImageUrl\` | string?     |                                       |
+| \`coverImageAlt\` | string?     |                                       |
+| \`author\`        | string?     |                                       |
+| \`tags\`          | string[]    |                                       |
+| \`publishedAt\`   | string?     | ISO 8601; null = publish immediately  |
+| \`seoTitle\`      | string?     |                                       |
+| \`seoDescription\`| string?     |                                       |
+| \`ogImageUrl\`    | string?     |                                       |
+
+### Rendering blog content
+
+\`\`\`tsx
+// app/blog/[slug]/page.tsx
+import DOMPurify from 'isomorphic-dompurify';
+
+const post = await brainerce.blog.getPost(params.slug);
+if (!post) notFound();
+
+// Always sanitize before rendering HTML \u2014 treat external-origin content as untrusted
+const safeHtml = DOMPurify.sanitize(post.content);
+return <div dangerouslySetInnerHTML={{ __html: safeHtml }} className="prose" />;
+\`\`\`
+
+The \`content\` field is HTML produced by the Lexical rich-text editor.
+**Always sanitize with DOMPurify (or equivalent) before rendering via
+\`dangerouslySetInnerHTML\`** \u2014 even though the content originates from your
+own editor, defense-in-depth prevents any stored-XSS path if content is ever
+migrated or imported from an external source.
+Apply a \`prose\` class (Tailwind Typography) for automatic styling.
+
+### REST endpoints
+
+| Method | Path | Returns |
+|--------|------|---------|
+| GET | \`/api/stores/:storeId/blog/posts\` | \`BlogPostListResponse\` |
+| GET | \`/api/stores/:storeId/blog/posts/:slug\` | \`BlogPost\` or 404 |
+| GET | \`/api/vc/:connectionId/blog/posts\` | Same, channel-scoped |
+| GET | \`/api/vc/:connectionId/blog/posts/:slug\` | \`BlogPost\` or 404 |
+`;
+}
+function getStorefrontBotSection(connectionId) {
+  return `## Storefront Bot (AI chat widget)
+
+The store's AI shopping assistant. ALL configuration (name, avatar, colors,
+greeting, starter questions, capabilities, guardrails) lives in the merchant
+dashboard \u2014 the embed never decides behavior, and the widget renders nothing
+until the merchant switches the bot Live.
+
+### Zero-code embed (any site)
+
+\`\`\`html
+<script src="https://cdn.brainerce.com/bot.js" data-connection-id="${connectionId}" defer></script>
+\`\`\`
+
+Keep the tag exactly this bare \u2014 do NOT add \`integrity\` or \`crossorigin\`
+(the bootstrap is intentionally mutable; it is origin-pinned by CSP instead).
+
+### SDK mount (React / Next.js / any bundler)
+
+\`\`\`ts
+import { BrainerceBot } from 'brainerce/bot';
+
+// client-side only (e.g. in a useEffect) \u2014 mounts a floating chat bubble
+const bot = await BrainerceBot.mount({ connectionId: '${connectionId}' });
+bot?.destroy(); // optional teardown
+\`\`\`
+
+\`mount\` resolves to \`null\` when the bot is disabled (FREE plan, switched
+off, or unconfigured) \u2014 safe to call unconditionally. Options: \`connectionId\`
+(required), \`baseUrl\` (API origin override), \`target\` (mount element),
+\`onAddToCart\` (\`({ productId, variantId, quantity }) => boolean | Promise<boolean>\`
+\u2014 route the widget's cart adds through the site's own cart; \`variantId\` is
+null for simple products; return false to fall back to the product page).
+
+Behavior: persists an anonymous session in localStorage, restores the
+conversation on revisit, streams answers, and shows product recommendation
+cards (image, price, add-to-cart / view). Multi-variant products get an
+in-card variant picker; shoppers can also ask the assistant to add an item
+and it goes through the same cart chain. Zero-result searches feed the
+merchant's "unmet demand" analytics. Aside from shopper-initiated cart adds,
+the bot is read-only.
+
+Add-to-cart resolution chain: \`onAddToCart\` option \u2192 cancelable
+\`brainerce:bot:add-to-cart\` CustomEvent on window
+(\`detail: { productId, variantId, quantity, connectionId }\`; call
+preventDefault() after handling) \u2192 navigate to the product page.
+
+Rules:
+- Mount once per page; do not pass any visual config \u2014 the dashboard owns it.
+- Do not wrap or restyle the widget; it renders in its own Shadow DOM.
+- Product card links expect the conventional \`/products/<slug>\` route.
+- Wire \`onAddToCart\` to the site's cart (see the cart section) so the header
+  count updates when the bot adds items.
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3008,6 +3261,10 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getTaxDisplaySection(cur);
     case "i18n":
       return getI18nSection();
+    case "multilingual-seo":
+    case "hreflang":
+    case "seo-i18n":
+      return getMultilingualSeoSection();
     case "critical-rules":
       return getCriticalRulesSection() + "\n\n" + getTypeQuickReference();
     case "type-reference":
@@ -3018,6 +3275,10 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getContactInquiriesSection();
     case "content":
       return getContentSection();
+    case "blog":
+      return getBlogSection();
+    case "storefront-bot":
+      return getStorefrontBotSection(cid);
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3102,6 +3363,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getMultilingualSeoSection(),
+        "",
+        "---",
+        "",
         getAdminApiSection(),
         "",
         "---",
@@ -3110,10 +3375,18 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
-        getContentSection()
+        getContentSection(),
+        "",
+        "---",
+        "",
+        getBlogSection(),
+        "",
+        "---",
+        "",
+        getStorefrontBotSection(cid)
       ].join("\n");
     default:
-      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, product-customization-fields, tax, i18n, critical-rules, type-reference, admin, inquiries, content, all`;
+      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, product-customization-fields, tax, i18n, critical-rules, type-reference, admin, inquiries, content, blog, all`;
   }
 }
 
@@ -3142,6 +3415,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "admin",
     "inquiries",
     "content",
+    "storefront-bot",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3179,6 +3453,12 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
+  displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
+  displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
+  displayPriceMax?: string;     // priceMax \xD7 rate (VARIABLE products).
+  displayCurrency?: string;     // ISO 4217 of the region \u2014 e.g. "EUR".
   status: string;
   type: 'SIMPLE' | 'VARIABLE';
   isDownloadable?: boolean;
@@ -3222,6 +3502,10 @@ interface ProductVariant {
   name?: string | null;
   price?: string | null;
   salePrice?: string | null;
+  // FX DISPLAY overlay (PRD \xA723) \u2014 same semantics as on the parent Product.
+  displayPrice?: string;
+  displaySalePrice?: string;
+  displayCurrency?: string;
   attributes?: Record<string, string> | null;
   options?: Array<{ name: string; value: string }>;
   inventory?: InventoryInfo | null;
@@ -3534,6 +3818,8 @@ interface Order {
   totalAmount: string;   // ALWAYS use this, not .total
   total?: string;        // optional alias
   currency?: string;
+  taxAmount?: string | null;       // 0 in inclusive (VAT) mode \u2014 read taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null;  // carries the included VAT when prices include tax
   customer?: OrderCustomer | null;
   items: OrderItem[];
   itemCount?: number;
@@ -4351,6 +4637,15 @@ interface PublicRegionDetail extends PublicRegion {
 }
 // getStoreRegions(): { data: PublicRegion[] }  \u2014 active regions, default first.
 // getStoreRegion(regionId): PublicRegionDetail  \u2014 one region + its providers.
+interface AutoRegionResponse {
+  region: PublicRegion | null;
+  matched: boolean;  // true=country was in a region's list; false=fell back to default
+  country: string;   // upper-cased ISO-3166-1 alpha-2; '' when caller omitted it
+}
+// getAutoRegion(country): AutoRegionResponse  \u2014 server-side resolution in one
+//   round trip. Pair with the country your edge runtime extracts
+//   (CF-IPCountry / request.geo.country / etc.) \u2014 Brainerce does NOT derive the
+//   country from the request IP server-side (storefront != end-customer).
 
 // ---- Tax Classes ---- (scopes: tax-classes:read / tax-classes:write)
 // Charge differential rates by product type. A TaxRate may target a class via
@@ -4382,7 +4677,25 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                getRegionCompatibleProviders(id), detectRegion(country, regions)
 //   Tax classes: getTaxClasses(), getTaxClass(id), createTaxClass(dto), updateTaxClass(id, dto),
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
-//                mergeTaxClasses(id, targetId)`;
+//                mergeTaxClasses(id, targetId)
+//
+// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+//   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
+//   getStoreTaxClasses(), estimateTax({ country?, subtotal })
+//
+// estimateTax returns:
+interface TaxEstimateResponse {
+  appliesTax: boolean;
+  rate: number | null;        // percent (18 = 18%) \u2014 null when no matching rule
+  rateName: string | null;
+  estimatedTax: number;       // tax portion of subtotal in store currency
+  pricesIncludeTax: boolean;
+  currency: string;           // store currency (cart/order currency)
+  note: string;               // disclaimer \u2014 preview is non-binding
+}
+// Non-binding by design: the authoritative tax runs at checkout against the
+// full shipping address. The country comes from your edge runtime
+// (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,