@brainerce/mcp-server 3.9.0 → 3.11.0

package/dist/index.mjs

@@ -703,7 +703,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**:
 
@@ -2362,6 +2362,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+)
 
@@ -2445,6 +2506,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
@@ -2475,6 +2550,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.
@@ -2938,6 +3026,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";
@@ -2976,6 +3204,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":
@@ -2986,6 +3218,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",
@@ -3070,6 +3306,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getMultilingualSeoSection(),
+        "",
+        "---",
+        "",
         getAdminApiSection(),
         "",
         "---",
@@ -3078,10 +3318,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`;
   }
 }
 
@@ -3110,6 +3358,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "admin",
     "inquiries",
     "content",
+    "storefront-bot",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3147,6 +3396,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;
@@ -3190,6 +3445,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;
@@ -4319,6 +4578,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
@@ -4350,7 +4618,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "description": "Framework-agnostic domain knowledge API for Brainerce. Provides SDK docs, types, business flows, critical rules, and store capabilities to AI tools like Lovable, Cursor, Bolt, v0, and Claude Code. Does NOT provide framework-specific boilerplate — clients build in whatever framework fits.",
   "bin": {
     "brainerce-mcp": "dist/bin/stdio.js"