@brainerce/mcp-server 3.8.0 → 3.11.0

package/dist/bin/stdio.js

@@ -709,7 +709,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**:
 
@@ -1153,6 +1153,8 @@ const material = getProductMetafieldValue(product, 'material');
 
 **Metafield fields:** \`definitionName\` (display label), \`definitionKey\` (lookup key), \`value\`, \`type\` (IMAGE, GALLERY, URL, COLOR, BOOLEAN, DATE, DATETIME, TEXT, TEXTAREA, NUMBER, DIMENSION, WEIGHT, JSON)
 
+**Translations:** When the store has i18n enabled and \`client.setLocale()\` is active, both the \`definitionName\` (the merchant-authored label like "Warranty Info" / "\u05DE\u05D9\u05D3\u05E2 \u05D0\u05D7\u05E8\u05D9\u05D5\u05EA") **and** free-text \`value\` come back already translated. No per-call locale param needed.
+
 ### Product Customization Fields (Customer Input)
 
 Some products allow customers to provide input at purchase time (e.g., text on a cake, upload a logo). Check \`product.customizationFields\` and render input fields accordingly.
@@ -1286,6 +1288,8 @@ await client.removeCoupon(cartId);
 const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
 \`\`\`
 
+> **Region-restricted coupons:** a coupon may carry \`regionIds\`. If the buyer's checkout region isn't in that list, \`applyCoupon\` / \`applyCheckoutCoupon\` reject the code even when everything else matches. Empty/omitted \`regionIds\` = valid in all regions.
+
 **On the checkout page** (after checkout session exists \u2014 ALWAYS use this when checkoutId is available):
 \`\`\`typescript
 // Applies to cart AND updates checkout totals in one call
@@ -1613,6 +1617,8 @@ const groups: ModifierGroup[] = product.modifierGroups ?? [];
 
 **Money fields are strings.** \`priceDelta\` is \`"5.00"\` (or \`"-2.00"\` for downsell modifiers \u2014 see below). Use \`parseFloat()\` for display arithmetic; never compute the line total client-side \u2014 the server runs the free-allocation policy and returns the final \`unitPrice\` snapshot on the cart line.
 
+**Translations are automatic.** Both \`group.name\`/\`group.description\` and each \`modifier.name\`/\`modifier.description\` are overlay-resolved by the server on every read. Call \`client.setLocale('he')\` once and the modifier picker renders in Hebrew with no extra code (\`"\u05EA\u05D5\u05E1\u05E4\u05D5\u05EA"\` / \`"\u05D6\u05D9\u05EA\u05D9\u05DD"\`). See the \`i18n\` topic for the full multi-language flow.
+
 ### Render: SINGLE \u2192 radio, MULTIPLE \u2192 checkbox
 
 Walk \`groups\` and pick the input type by \`selectionType\`. Sort modifiers by \`position\`.
@@ -2014,19 +2020,24 @@ window.location.href = authorizationUrl;
 \`\`\`typescript
 const params = new URLSearchParams(window.location.search);
 if (params.get('oauth_success') === 'true') {
-  const token = params.get('token');
-  if (token) {
-    client.setCustomerToken(token);
-    localStorage.setItem('customerToken', token);
-    // Optional: read customer_id, customer_email, is_new from params
+  // Single-use auth_code is exchanged for the JWT via POST \u2014 keeps the JWT
+  // out of the URL (browser history, CDN logs, Referer header).
+  const code = params.get('auth_code');
+  if (code) {
+    const result = await client.exchangeOAuthCode(code);
+    client.setCustomerToken(result.token);
+    localStorage.setItem('customerToken', result.token);
+    // Optional: result.customer, result.isNewCustomer, result.redirectUrl
     // Link guest cart: await client.linkCart(cartId);
-    window.location.href = '/account';
+    window.location.href = result.redirectUrl || '/account';
   }
 } else if (params.get('oauth_error')) {
   // Show error: params.get('oauth_error')
 }
 \`\`\`
 
+> The legacy redirect format placed the JWT directly in the URL as \`?token=\`. That format is still emitted for backward compatibility, but it will be removed in the next major release \u2014 migrate to \`auth_code\` + \`exchangeOAuthCode()\` now.
+
 ### Account Page (/account) \u2014 uses getMyProfile() and getMyOrders()
 
 \`\`\`typescript
@@ -2255,7 +2266,17 @@ overlay needed:
 - \`variants[].name\`
 - \`variant.attributes\` keys and values \u2014 \`getVariantOptions(variant)\` returns translated attribute names and option values automatically
 - \`productAttributeOptions[].attribute.name\`, \`attributeOption.name\`
-- \`metafields[].value\`
+- \`metafields[].value\` (the free-text values customers submit)
+- \`metafields[].definition.name\`, \`metafields[].definition.description\` (the merchant-authored custom-field labels \u2014 "Warranty Info" / "\u05DE\u05D9\u05D3\u05E2 \u05D0\u05D7\u05E8\u05D9\u05D5\u05EA")
+- \`modifierGroups[].name\`, \`modifierGroups[].description\` (the group label shown on the PDP \u2014 e.g. "Toppings" / "\u05EA\u05D5\u05E1\u05E4\u05D5\u05EA")
+- \`modifierGroups[].modifiers[].name\`, \`modifierGroups[].modifiers[].description\` (each individual modifier \u2014 e.g. "Olives" / "\u05D6\u05D9\u05EA\u05D9\u05DD")
+
+**Promotional surfaces:**
+- \`cart.bundles[].name\`, \`cart.bundles[].description\` (the bundle's own merchant-typed label, e.g. "Lunch Combo" / "\u05D0\u05E8\u05D5\u05D7\u05EA \u05E6\u05D4\u05E8\u05D9\u05D9\u05DD")
+- \`cart.bundles[].offeredProducts[].name\`, \`.slug\` (each product inside the bundle \u2014 fetched fresh from \`Product.translations\`)
+- \`checkout.bumps[].title\`, \`checkout.bumps[].description\` (the bump headline shown at checkout \u2014 falls back to the translated product name when merchant didn't override)
+- \`checkout.bumps[].bumpProduct.name\`, \`.slug\` (the underlying product)
+- Discount-rule names/descriptions (when surfaced as banner text via \`displayConfig\`)
 
 **Taxonomy (\`getCategories\`, \`getBrands\`, \`getTags\`):**
 - \`name\` on each item
@@ -2347,6 +2368,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+)
 
@@ -2357,7 +2439,9 @@ const admin = new BrainerceClient({ apiKey: 'brainerce_...' });
 
 // Taxonomy: listCategories(), listBrands(), listTags(), listAttributes()
 // Shipping: listShippingZones(), createZoneShippingRate()
-// Tax: getTaxRates(), createTaxRate()
+// Tax: getTaxRates(), createTaxRate() \u2014 a rate may target a tax class via taxClassId
+// Tax classes: getTaxClasses(), createTaxClass(), assignTaxClass(), mergeTaxClasses() (scope tax-classes:*)
+// Regions: getRegions(), createRegion(), setDefaultRegion(), updateRegionPaymentProviders() (scope regions:*)
 // Metafields: getMetafieldDefinitions(), setProductMetafield()
 // Team: getTeamMembers(), inviteTeamMember()
 // Email: getEmailTemplates(), createEmailTemplate()
@@ -2365,6 +2449,13 @@ const admin = new BrainerceClient({ apiKey: 'brainerce_...' });
 // OAuth: getOAuthProviders(), configureOAuthProvider()
 \`\`\`
 
+Store-level team management (\`inviteStoreMember\`, \`updateStoreMember\`) is the
+canonical replacement for the deprecated account-level helpers above. The
+invite accepts an optional \`salesChannelIds\` (vibe-coded \`connectionId\`s,
+\`vc_*\`) to restrict a member to specific channels \u2014 omit or pass \`[]\` for all
+channels. Use \`updateStoreMemberSalesChannels(storeId, memberId, { salesChannelIds })\`
+to change that scope later.
+
 ### Per-Channel Publishing
 
 Categories, tags, brands, and metafield definitions are gated to specific
@@ -2396,7 +2487,97 @@ calls fail with \`404 Not Found\`.
 
 The vibe-coded read endpoints (used by storefront SDK calls in \`connectionId\`
 mode) automatically filter by these junction tables, so storefronts never see
-entities that weren't published to their site.`;
+entities that weren't published to their site.
+
+### Tax classes (differential tax rates)
+
+Charge different rates for different product types. A \`TaxRate\` may target a
+class via \`taxClassId\`; a rate with \`taxClassId: null\` is the **Standard
+fallback**. Checkout resolves each line's class **variant \u2192 product \u2192 category
+\u2192 store default \u2192 null**, then picks the matching rate (Standard if none).
+\`rate\` is a whole percentage (\`7.25\` = 7.25%). Requires the
+\`tax-classes:read\` / \`tax-classes:write\` scopes.
+
+\`\`\`typescript
+const food = await admin.createTaxClass({ name: 'Food', slug: 'food' });
+await admin.assignTaxClass(food.id, { productIds: ['prod_1'], categoryIds: ['cat_food'] });
+
+// class-specific rate \u2014 only food lines use it; everything else uses Standard
+await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClassId: food.id });
+
+// delete is blocked (409) while dependents exist \u2014 merge moves FKs then deletes:
+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
+providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
+\`detectRegion\` is a pure client-side helper to map a buyer's country to a
+region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
+checkout with a region (recorded for reporting + provider scoping; currency
+follows the cart until FX price conversion lands).
+
+\`\`\`typescript
+const eu = await admin.createRegion({
+  name: 'EU', currency: 'EUR', countries: ['DE', 'FR'],
+  taxInclusive: true, paymentProviderIds: ['app_inst_stripe'],
+});
+await admin.setDefaultRegion(eu.id);
+
+const { data: regions } = await admin.getRegions();
+const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
+\`\`\`
+
+Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
+active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
+Pair with \`detectRegion\` to pick the buyer's region for currency display.
+
+\`\`\`typescript
+const store = new BrainerceClient({ storeId: 'store_123' });
+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.
+
+\`\`\`typescript
+await admin.createShippingZone({
+  name: 'EU Express', countries: ['DE', 'FR', 'IT'], regionIds: [eu.id],
+});
+\`\`\``;
 }
 function getContactInquiriesSection() {
   return `## Contact Inquiries & Forms (optional)
@@ -2851,6 +3032,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";
@@ -2889,6 +3210,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":
@@ -2899,6 +3224,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",
@@ -2983,6 +3312,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getMultilingualSeoSection(),
+        "",
+        "---",
+        "",
         getAdminApiSection(),
         "",
         "---",
@@ -2991,10 +3324,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`;
   }
 }
 
@@ -3023,6 +3364,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."),
@@ -3054,12 +3396,18 @@ interface Product {
   description?: string | null;
   descriptionFormat?: 'text' | 'html' | 'markdown' | null;
   sku: string;
-  basePrice: string;   // Use parseFloat() for calculations
-  salePrice?: string | null;
+  basePrice: string;   // For VARIABLE products: MIN(variants.price). For SIMPLE: the parent price. parseFloat() for math.
+  salePrice?: string | null;  // For VARIABLE: MIN(variants.salePrice WHERE NOT NULL) \u2014 null iff no variant is on sale (WC is_on_sale() semantic). For SIMPLE: the parent sale price. Reliable "on sale?" check: product.salePrice !== null.
   costPrice?: string | null;
-  priceMin?: string | null;  // Lowest variant price (VARIABLE products). Use for catalog/JSON-LD range display.
-  priceMax?: string | null;  // Highest variant price (VARIABLE products).
+  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;
@@ -3103,6 +3451,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;
@@ -3174,6 +3526,11 @@ interface ProductQueryParams {
   metafields?: Record<string, string | string[]>;
   sortBy?: 'name' | 'price' | 'createdAt';
   sortOrder?: 'asc' | 'desc';
+  // PRD \xA722: resolve DISPLAY prices for this region. When set + valid, each
+  // product/variant gains resolvedPrice/resolvedCurrency/priceSource (additive;
+  // basePrice/salePrice untouched). Absent/invalid region \u2192 nothing attached.
+  // Display-only. Ignored in vibe-coded (vc_*) mode (storefront/admin paths only).
+  regionId?: string;
 }
 
 interface SearchSuggestions {
@@ -3299,6 +3656,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3375,6 +3733,7 @@ interface CreateCheckoutDto {
   cartId: string;
   customerId?: string;
   selectedItemIds?: string[];  // Partial checkout
+  regionId?: string;           // multi-region: associate the checkout with a region (must belong to the store; 400 if unknown)
 }
 
 // startGuestCheckout() return type \u2014 DISCRIMINATED UNION
@@ -3393,6 +3752,8 @@ interface TaxBreakdownItem {
   name: string;
   rate: number;    // decimal: 0.17 = 17%
   amount: number;
+  taxClassId?: string | null;   // rate's tax class (null = Standard)
+  taxClassSlug?: string | null; // class slug for attribution (null = Standard)
 }`;
 var ORDERS_TYPES = `// ---- Orders ----
 
@@ -3450,6 +3811,7 @@ interface OrderItem {
   // Snapshot of buyer-submitted customization values captured at checkout.
   // Keyed by metafield slug. \`value\` is string[] for MULTI_SELECT / GALLERY, string otherwise.
   customizations?: Record<string, { label: string; value: string | string[]; type: string }>;
+  taxClassSlug?: string; // frozen slug of the line's resolved tax class (omitted = Standard fallback)
 }
 
 interface OrderCustomer {
@@ -3632,7 +3994,7 @@ function formatPrice(priceString: string | number | undefined | null, options?:
 function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice'>): number;
 function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount' | 'priceMin' | 'priceVaries'>): {
   price: number; originalPrice: number; isOnSale: boolean; discountAmount: number; discountPercent: number;
-}; // Falls back to priceMin when basePrice=0 (VARIABLE products)
+}; // For VARIABLE products, basePrice/salePrice are pre-aggregated (MIN of variants) \u2014 the helper just reads them. Use this whenever you need an "on sale?" badge or a "X% off" label.
 function getVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice'>, productBasePrice: string): number;
 
 // Cart helpers
@@ -4165,6 +4527,122 @@ export interface Content<T extends ContentType = ContentType> extends ContentSum
 // stale-while-revalidate=60. Storefront changes propagate within ~5 min
 // of the merchant publishing. Do not add extra client-side caching
 // beyond Next.js's default fetch cache.`;
+var REGIONS_TYPES = `// ---- Regions & Tax Classes (Admin mode, apiKey) ----
+// storeId is derived from the API key \u2014 never pass it on admin calls.
+
+// ---- Regions ---- (scopes: regions:read / regions:write)
+// A region binds countries \u2192 currency + tax-display mode + payment providers.
+interface Region {
+  id: string;
+  accountId: string;
+  storeId: string;
+  name: string;
+  slug: string;
+  currency: string;          // ISO 4217, e.g. "EUR"
+  countries: string[];       // ISO 3166-1 alpha-2, e.g. ["DE","FR"]
+  taxInclusive: boolean;     // show prices tax-inclusive in this region?
+  automaticTaxes: boolean;
+  isDefault: boolean;        // fallback when buyer's country maps to no region
+  isActive: boolean;
+  paymentProviders?: RegionPaymentProvider[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface RegionPaymentProvider {
+  id: string;
+  regionId: string;
+  appInstallationId: string;
+  isEnabled: boolean;
+  createdAt: string;
+}
+
+interface CreateRegionDto {
+  name: string;
+  currency: string;            // ISO 4217
+  countries: string[];         // ISO 3166-1 alpha-2
+  taxInclusive?: boolean;
+  automaticTaxes?: boolean;
+  isDefault?: boolean;
+  paymentProviderIds?: string[]; // AppInstallation IDs to enable here
+}
+interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean }
+
+// client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
+//   \u2192 region whose countries includes the code, else the default region, else null.
+// Pass the resolved regionId to createCheckout to associate the checkout with a
+// region (recorded for reporting + provider scoping; currency follows the cart
+// until FX price conversion lands).
+//
+// Storefront (public, no apiKey \u2014 storeId mode):
+interface PublicRegion {
+  id: string; name: string; slug: string; currency: string;
+  countries: string[]; taxInclusive: boolean; isDefault: boolean;
+}
+interface PublicRegionDetail extends PublicRegion {
+  paymentProviders: Array<{ id: string; appId: string; name: string | null }>;
+}
+// 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
+// taxClassId; a rate with taxClassId=null is the Standard fallback. Per-line
+// resolution: variant \u2192 product \u2192 category \u2192 store default \u2192 null.
+interface TaxClass {
+  id: string;
+  accountId: string;
+  storeId: string;
+  name: string;
+  slug: string;              // kebab-case, unique per store
+  description?: string | null;
+  isDefault: boolean;        // auto-applied to products without an explicit class
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateTaxClassDto { name: string; slug: string; description?: string; isDefault?: boolean }
+type UpdateTaxClassDto = Partial<CreateTaxClassDto>;
+// Bulk-assign a class to entities:
+interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; categoryIds?: string[] }
+
+// TaxRate / CreateTaxRateDto carry an optional taxClassId (null = Standard).
+// rate is a WHOLE PERCENTAGE (7.25 = 7.25%).
+//
+// SDK methods (admin):
+//   Regions:     getRegions(), getRegion(id), createRegion(dto), updateRegion(id, dto),
+//                deleteRegion(id), setDefaultRegion(id), updateRegionPaymentProviders(id, ids),
+//                addRegionCountries(id, codes), removeRegionCountry(id, code),
+//                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)
+//
+// 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,
@@ -4176,7 +4654,8 @@ var TYPES_BY_DOMAIN = {
   inquiries: INQUIRIES_TYPES,
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
-  content: CONTENT_TYPES
+  content: CONTENT_TYPES,
+  regions: REGIONS_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4207,10 +4686,12 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "helpers",
     "inquiries",
     "reviews",
+    "modifier-groups",
     "content",
+    "regions",
     "all"
   ]).describe(
-    'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page.'
+    'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
   )
 };
 async function handleGetTypeDefinitions(args) {
@@ -6000,11 +6481,16 @@ Build both steps EVEN IF the store has no email provider configured today \u2014
    });
    window.location.href = authorizationUrl; // full-page redirect, NOT a popup
    \`\`\`
-3. **On the callback page** the URL contains \`token\` + \`oauth_success\` (or \`oauth_error\`) query params. Extract and apply the token:
+3. **On the callback page** the URL contains \`auth_code\` + \`oauth_success\` (or \`oauth_error\`) query params. Exchange the single-use code for the JWT \u2014 never read the token from the URL:
    \`\`\`ts
-   const token = new URLSearchParams(location.search).get('token');
-   if (token) client.setCustomerToken(token); // then redirect to account
+   const params = new URLSearchParams(location.search);
+   const code = params.get('auth_code');
+   if (code) {
+     const result = await client.exchangeOAuthCode(code);
+     client.setCustomerToken(result.token); // then redirect to account
+   }
    \`\`\`
+   The legacy \`?token=\` URL param is still emitted for backward compatibility but will be removed in the next major release \u2014 migrate to \`auth_code\` now.
 4. **On \`oauth_error\`:** redirect to login with an error message.
 
 Build the OAuth button region AND the callback handler even when no providers are configured. They auto-hide.`
@@ -6486,7 +6972,9 @@ function renderCapabilitiesSummary(caps) {
   );
   lines.push(`- Downloadable products: ${caps.features.hasDownloadableProducts ? "yes" : "no"}`);
   lines.push(`- Checkout custom fields: ${caps.features.hasCheckoutCustomFields ? "yes" : "no"}`);
-  lines.push(`- Content (FAQ/footer/header/announcements/pages): ${caps.features.hasContent ? "seeded" : "none \u2014 build chrome UI with fallbacks"}`);
+  lines.push(
+    `- Content (FAQ/footer/header/announcements/pages): ${caps.features.hasContent ? "seeded" : "none \u2014 build chrome UI with fallbacks"}`
+  );
   lines.push(
     `- Email verification: ${caps.connection.requireEmailVerification ? "required" : "not required (still build the verify-email flow)"}`
   );