@brainerce/mcp-server 3.7.0 → 3.9.0

package/dist/bin/http.js

@@ -3,6 +3,7 @@
 
 // src/bin/http.ts
 var import_node_http = require("http");
+var import_node_crypto = require("crypto");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_sse = require("@modelcontextprotocol/sdk/server/sse.js");
 
@@ -1155,6 +1156,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.
@@ -1288,6 +1291,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
@@ -1615,6 +1620,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\`.
@@ -2016,19 +2023,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
@@ -2202,9 +2214,12 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const client = getServerClient();
   client.setLocale(locale);
   const product = await client.getProductBySlug(slug);
+  // NEVER feed raw HTML into <meta name="description"> \u2014 product.description
+  // is often rich-text HTML. Strip tags first, then truncate on a word
+  // boundary. See buildMetaDescription() in lib/seo.ts.
   return {
     title: product.seoTitle || product.name,
-    description: product.seoDescription || product.description?.slice(0, 160),
+    description: product.seoDescription || buildMetaDescription(product.description) || product.name,
   };
 }
 \`\`\`
@@ -2254,7 +2269,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
@@ -2320,11 +2345,25 @@ Because the backend already overlays everything, UI code is just:
 
 ### RTL handling
 
-For RTL locales (\`he\`, \`ar\`), set \`<html dir="rtl">\` in the root layout and
-let flexbox reverse automatically. Do NOT add \`flex-row-reverse\` on top of
-\`dir="rtl"\` \u2014 that's a double-swap. DO swap directional icons (chevrons,
-arrows) manually. Use logical CSS properties (\`ms-*\`/\`me-*\`) instead of
-\`ml-*\`/\`mr-*\`.
+Resolve direction with \`client.getStoreDirection(locale)\` \u2014 it returns
+\`'ltr' | 'rtl'\` for any BCP-47 tag (Arabic, Hebrew, Persian, Urdu, Yiddish
+today; future RTL locales added by the platform are picked up automatically).
+Do NOT maintain your own RTL locale set.
+
+\`\`\`tsx
+// app/[locale]/layout.tsx
+const dir = client.getStoreDirection(locale);
+return <html lang={locale} dir={dir}>...</html>;
+\`\`\`
+
+For static rendering, \`storeInfo.i18n.defaultDirection\` carries the store's
+default direction, and each entry in \`storeInfo.i18n.supportedLocaleObjects\`
+includes its own \`direction\`.
+
+Let flexbox reverse automatically once \`<html dir="rtl">\` is set. Do NOT add
+\`flex-row-reverse\` on top \u2014 that's a double-swap. DO swap directional icons
+(chevrons, arrows) manually. Use logical CSS properties (\`ms-*\`/\`me-*\`)
+instead of \`ml-*\`/\`mr-*\`.
 
 ### Language switcher
 
@@ -2342,7 +2381,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()
@@ -2350,6 +2391,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
@@ -2381,7 +2429,70 @@ 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.
+
+### 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);
+\`\`\`
+
+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)
@@ -2701,6 +2812,141 @@ and a \`newsletter\` form embedded in the footer), render each form from its
 own \`contactForms.get(key, locale)\` call. The \`formKey\` you pass to
 \`createInquiry\` must match.`;
 }
+function getContentSection() {
+  return `## Content \u2014 typed merchant content store
+
+Brainerce ships a typed content store so merchants can edit site chrome, FAQ,
+static pages, and inline rich-text blocks in the dashboard \u2014 without
+re-prompting the AI that built their storefront. Every row has a \`type\` +
+\`key\` + typed \`data\` payload + free-form \`customFields\`.
+
+**Six content types.** Each one has a fixed \`data\` shape; the SDK's TypeScript
+generics keep them in lockstep:
+
+| Type           | Use for                                | \`data\` shape (abbreviated) |
+| -------------- | -------------------------------------- | --------------------------- |
+| \`FAQ\`         | Q/A accordions                         | \`{ items: { question, answer }[] }\` |
+| \`FOOTER\`      | Site footer (chrome)                   | \`{ columns, copyright?, social? }\` |
+| \`HEADER\`      | Top nav + logo + CTA (chrome)          | \`{ logo?, navItems, cta? }\` |
+| \`ANNOUNCEMENT\`| Banners; time-bound by \`startsAt/endsAt\` | \`{ message, severity, dismissible, ... }\` |
+| \`RICH_TEXT\`   | Free-form HTML blocks embedded inline  | \`{ html }\` |
+| \`PAGE\`        | Static pages with slug + SEO           | \`{ slug, title, html, seo? }\` |
+
+Run \`get-type-definitions\` with \`domain: 'content'\` for the full interfaces.
+
+### Default key
+
+Every type has \`'main'\` as its universal default key. \`client.content.faq.get()\`
+with no arguments resolves to \`key='main'\`. Topical keys (\`'shipping'\`,
+\`'holiday-2026'\`, \`'about'\`) are merchant-named.
+
+### Reading content (any SDK mode)
+
+Public reads work in vibe-coded mode, storefront mode, and admin mode. They
+return \`null\` on 404 \u2014 render hard-coded fallbacks so the page never crashes
+when the merchant hasn't seeded yet.
+
+\`\`\`ts
+// Single entry, default key 'main', resolved to a locale
+const faq = await client.content.faq.get('main', locale);
+if (faq) {
+  faq.data.items.forEach(({ question, answer }) => {
+    // Render question + sanitize(answer)
+  });
+}
+
+// All entries of a type
+const allFaqs = await client.content.faq.list(locale);
+
+// Page by URL slug \u2014 for app/[slug]/page.tsx
+const page = await client.content.page.getBySlug(slug, locale);
+if (!page) notFound();
+\`\`\`
+
+### Security \u2014 sanitize HTML before rendering
+
+\`FAQ.items[i].answer\`, \`RICH_TEXT.html\`, and \`PAGE.html\` carry
+MERCHANT-AUTHORED HTML. The server does NOT pre-sanitize \u2014 some merchants
+embed iframes (e.g. YouTube) which strict sanitizers would strip. ALWAYS
+sanitize on the storefront before injecting:
+
+\`\`\`ts
+// Recommended: isomorphic-dompurify
+import DOMPurify from 'isomorphic-dompurify';
+const safe = DOMPurify.sanitize(rawHtml);
+<div dangerouslySetInnerHTML={{ __html: safe }} />;
+\`\`\`
+
+Skipping this is XSS.
+
+### Custom fields
+
+Every Content row carries a free-form \`customFields: Record<string, string>\`.
+Merchants add arbitrary key-value extras (\`helpEmail\`, \`phoneNumber\`,
+\`foundedYear\`) that you can opt into reading:
+
+\`\`\`ts
+const faq = await client.content.faq.get('shipping');
+<a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+\`\`\`
+
+The shape is whatever the merchant entered. Read keys you expect; ignore the rest.
+
+### Locale resolution
+
+All public reads accept a \`locale\` argument. The server resolves
+\`translations[locale]\` server-side and returns the resolved \`data\` payload \u2014
+the storefront does NOT need to do its own overlay. Empty / missing translations
+fall through to the default-locale value.
+
+### Cache
+
+Public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`.
+Merchant edits propagate within ~5 minutes. Don't layer extra client-side
+caching beyond Next.js's default fetch cache.
+
+### Admin writes (apiKey mode)
+
+\`\`\`ts
+const adminClient = new BrainerceClient({ apiKey: process.env.BRAINERCE_API_KEY });
+
+// Create \u2014 always starts in DRAFT
+const faq = await adminClient.content.faq.create({
+  key: 'shipping',
+  name: 'Shipping FAQ',
+  data: { items: [{ question: 'How long?', answer: 'Most orders ship in 2 days.' }] },
+});
+
+// Update (data replaces wholesale; last-write-wins on the data field)
+await adminClient.content.update(faq.id, {
+  data: { items: [{ question: 'How long?', answer: 'Updated answer.' }] },
+});
+
+// Publish / unpublish
+await adminClient.content.publish(faq.id);
+await adminClient.content.unpublish(faq.id);
+
+// Hard delete
+await adminClient.content.remove(faq.id);
+\`\`\`
+
+Write operations throw if called from vibe-coded or storefront mode.
+
+### Reserved key convention
+
+\`'main'\` is reserved as the universal default. Don't use it for topical
+entries \u2014 pick a descriptive slug (\`'shipping'\`, \`'returns'\`, \`'about'\`,
+\`'holiday-2026'\`). The validation rule is \`^[a-z][a-z0-9-]*$\`, max 64 chars.
+
+### See also
+
+- \`get-business-flows\` with \`flow: 'content-bootstrap'\` for the full
+  layout / FAQ / page recipe.
+- \`get-required-features\` lists each Content surface (\`site-header\`,
+  \`site-footer\`, \`announcement-bar\`, \`faq-page\`, \`static-pages\`).
+- \`get-type-definitions\` with \`domain: 'content'\` for the TypeScript
+  interfaces.`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -2747,6 +2993,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getAdminApiSection();
     case "inquiries":
       return getContactInquiriesSection();
+    case "content":
+      return getContentSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -2835,10 +3083,14 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
-        getContactInquiriesSection()
+        getContactInquiriesSection(),
+        "",
+        "---",
+        "",
+        getContentSection()
       ].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, 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, all`;
   }
 }
 
@@ -2866,6 +3118,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "i18n",
     "admin",
     "inquiries",
+    "content",
     "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."),
@@ -2897,11 +3150,11 @@ 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.
   status: string;
   type: 'SIMPLE' | 'VARIABLE';
@@ -3017,6 +3270,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 {
@@ -3142,6 +3400,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;
@@ -3218,6 +3477,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
@@ -3236,6 +3496,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 ----
 
@@ -3293,6 +3555,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 {
@@ -3475,7 +3738,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
@@ -3858,6 +4121,245 @@ export interface ModifierValidationError {
 // The cart line then carries:
 //   cart.items[i].modifiers      \u2014 CartItemModifierLine[]
 //   cart.items[i].modifiersTotal \u2014 decimal string of the paid (non-free) deltas`;
+var CONTENT_TYPES = `// ---- Content (typed merchant content store) ----
+// Brainerce ships a typed content store so merchants can edit FAQ, footer,
+// header, announcements, rich text, and static pages in the dashboard
+// without re-prompting the AI that built the storefront. Every row has a
+// 'type' + 'key' + typed 'data' payload + free-form 'customFields'.
+//
+// SECURITY (read carefully):
+//   RICH_TEXT.html, PAGE.html, and FAQ answers are MERCHANT-AUTHORED HTML.
+//   ALWAYS sanitize with isomorphic-dompurify (or equivalent) before
+//   injecting via dangerouslySetInnerHTML. The server does NOT pre-sanitize
+//   because some merchants embed iframes (e.g. YouTube) which strict
+//   sanitizers would strip; the storefront chooses the policy.
+//
+// 404 contract: client.content.<type>.get(key) returns null when no
+// PUBLISHED row exists. Always render a hard-coded fallback on null so
+// the page never crashes when the merchant hasn't seeded yet.
+//
+// Default key: every type has 'main' as its universal default. Pass no
+// argument to fetch the main entry; pass a custom key ('shipping',
+// 'holiday-2026', 'about') for topical entries.
+
+export type ContentType = 'FAQ' | 'FOOTER' | 'HEADER' | 'ANNOUNCEMENT' | 'RICH_TEXT' | 'PAGE';
+export type ContentStatus = 'DRAFT' | 'PUBLISHED';
+
+export interface FaqItem {
+  question: string;
+  /** Sanitized HTML \u2014 sanitize before rendering. */
+  answer: string;
+}
+export interface FaqContent { items: FaqItem[] }
+
+export interface FooterLink { label: string; url: string }
+export interface FooterColumn { title: string; links: FooterLink[] }
+export interface FooterSocialLink { platform: string; url: string } // 'instagram' | 'facebook' | 'x' | ...
+export interface FooterContent {
+  columns: FooterColumn[];
+  copyright?: string;
+  social?: FooterSocialLink[];
+}
+
+export interface HeaderLogo { src: string; alt: string }
+export interface HeaderNavItem { label: string; url: string }
+export interface HeaderCta { label: string; url: string }
+export interface HeaderContent {
+  logo?: HeaderLogo;
+  navItems: HeaderNavItem[];
+  cta?: HeaderCta;
+}
+
+export type AnnouncementSeverity = 'info' | 'warning' | 'success';
+export interface AnnouncementContent {
+  message: string;
+  severity: AnnouncementSeverity;
+  dismissible: boolean;
+  /** ISO 8601 \u2014 filter client-side. */
+  startsAt?: string;
+  endsAt?: string;
+  ctaLabel?: string;
+  ctaHref?: string;
+}
+
+export interface RichTextContent {
+  /** Raw HTML \u2014 sanitize before rendering. */
+  html: string;
+}
+
+export interface PageSeo {
+  title?: string;
+  description?: string;
+  ogImage?: string;
+}
+export interface PageContent {
+  /** URL slug, lower-kebab. */
+  slug: string;
+  title: string;
+  /** Raw HTML \u2014 sanitize before rendering. */
+  html: string;
+  seo?: PageSeo;
+}
+
+export interface ContentSummary {
+  id: string;
+  type: ContentType;
+  key: string;
+  name: string;
+  status: ContentStatus;
+  position: number;
+  updatedAt: string;
+}
+
+export interface Content<T extends ContentType = ContentType> extends ContentSummary {
+  type: T;
+  data: T extends 'FAQ' ? FaqContent
+      : T extends 'FOOTER' ? FooterContent
+      : T extends 'HEADER' ? HeaderContent
+      : T extends 'ANNOUNCEMENT' ? AnnouncementContent
+      : T extends 'RICH_TEXT' ? RichTextContent
+      : T extends 'PAGE' ? PageContent
+      : never;
+  /** Free-form merchant-defined extras. Read keys the merchant told you to expect. */
+  customFields: Record<string, string>;
+  salesChannelIds: string[];
+}
+
+// ---- SDK usage examples ----
+//
+// FAQ \u2014 render an accordion from the main FAQ (or a topical one):
+//   const faq = await client.content.faq.get('main', locale);  // 'shipping', 'returns', ...
+//   if (faq) {
+//     faq.data.items.forEach(({ question, answer }) => {
+//       // Render question + sanitize(answer) \u2014 never inject raw HTML.
+//     });
+//   }
+//
+// Footer \u2014 server component in root layout:
+//   const footer = await client.content.footer.get('main', locale);
+//   if (!footer) return <Fallback />;
+//   // Render footer.data.columns, footer.data.social, footer.data.copyright
+//
+// Header \u2014 same pattern as footer:
+//   const header = await client.content.header.get('main', locale);
+//
+// Announcement \u2014 multiple may be active; filter by date client-side:
+//   const announcements = await client.content.announcement.list(locale);
+//   const now = Date.now();
+//   const active = announcements.filter((a) => {
+//     const startOk = !a.data.startsAt || new Date(a.data.startsAt).getTime() <= now;
+//     const endOk = !a.data.endsAt || new Date(a.data.endsAt).getTime() >= now;
+//     return startOk && endOk;
+//   });
+//
+// Rich text \u2014 inline block anywhere on a page:
+//   const block = await client.content.richText.get('about-intro', locale);
+//   <div dangerouslySetInnerHTML={{ __html: sanitize(block.data.html) }} />
+//
+// Page \u2014 catch-all route by slug (e.g. /about, /terms, /privacy):
+//   // app/[slug]/page.tsx
+//   const page = await client.content.page.getBySlug(params.slug, locale);
+//   if (!page) notFound();
+//   // page.data.title, page.data.html, page.data.seo
+//   return <article dangerouslySetInnerHTML={{ __html: sanitize(page.data.html) }} />;
+//
+// Custom fields \u2014 every Content row carries a free-form Record<string, string>:
+//   const faq = await client.content.faq.get('shipping');
+//   <a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+//
+// Cache \u2014 public reads carry Cache-Control: public, max-age=300,
+// 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.
+
+// ---- 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)`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -3868,7 +4370,9 @@ var TYPES_BY_DOMAIN = {
   helpers: HELPERS_TYPES,
   inquiries: INQUIRIES_TYPES,
   reviews: REVIEWS_TYPES,
-  "modifier-groups": MODIFIER_GROUPS_TYPES
+  "modifier-groups": MODIFIER_GROUPS_TYPES,
+  content: CONTENT_TYPES,
+  regions: REGIONS_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -3899,9 +4403,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.'
+    '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) {
@@ -4448,8 +4955,10 @@ client.setLocale(locale);
 // order bumps, search suggestions, discount banners, nudges,
 // badges, order history.
 
-// For RTL locales (he, ar), set the document direction.
-// Framework-neutral: document.documentElement.setAttribute('dir', 'rtl');`,
+// For RTL direction, do not hardcode the locale list. Ask the SDK:
+//   const dir = client.getStoreDirection(currentLocale); // 'ltr' | 'rtl'
+//   document.documentElement.setAttribute('dir', dir);
+// (Or in React: <html dir={dir}>...</html>.)`,
   "order-history-full": `// Full "My Orders" account page. Render every piece of data the server
 // already returns \u2014 not just order number / total / status.
 //
@@ -5541,7 +6050,7 @@ var RULES = {
     body: `- NEVER hardcode currency, locale, or language strings. Read them from \`get-store-info\` / \`get-store-capabilities\` and use the configured values.
 - NEVER format prices with \`toFixed(2)\` or custom logic. Use \`formatPrice()\` from the SDK \u2014 it honors the store's currency and locale.
 - When the store has i18n enabled (\`capabilities.store.i18n.enabled === true\`), you MUST call \`client.setLocale(locale)\` at app init and include a language switcher. All SDK reads will then return localized content automatically.
-- For RTL locales (\`he\`, \`ar\`), set the document direction to RTL. Do not manually reverse flex layouts \u2014 the platform's CSS reversal handles it.`
+- For RTL direction, do NOT maintain a local list of RTL locales. Call \`client.getStoreDirection(locale)\` \u2014 it returns \`'ltr' | 'rtl'\` for any BCP-47 tag (covers Arabic, Hebrew, Persian, Urdu, Yiddish, and any future RTL locales the platform adds). Set \`<html dir={...}>\` from this value. The platform's CSS reversal handles flex layouts \u2014 do not manually swap them.`
   },
   types: {
     title: "Type safety",
@@ -5589,6 +6098,7 @@ var GET_BUSINESS_FLOWS_SCHEMA = {
     "cart-persistence",
     "inventory-reservation",
     "product-customization",
+    "content-bootstrap",
     "all"
   ]).describe('Which flow to retrieve. Use "all" to get every flow.')
 };
@@ -5688,11 +6198,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.`
@@ -5779,6 +6294,76 @@ Server-side guardrails that WILL reject bad requests (so validate client-side to
 - More than 10 uploads per IP per minute \u2192 429.
 
 Never render customization fields without also wiring the upload + metadata flow \u2014 a form that submits nothing is worse than no form at all.`
+  },
+  "content-bootstrap": {
+    title: "Content Bootstrap \u2014 site chrome & static content",
+    body: `Every Brainerce storefront should render merchant-defined site chrome (header, footer, announcements, FAQ, static pages) from the Content API. The merchant edits these in the Brainerce dashboard; storefronts pick up changes within ~5 minutes (public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`).
+
+1. **Fetch chrome at the root layout** (server component if Next.js). All three return \`null\` on 404 \u2014 render hard-coded fallbacks so the page never crashes when the merchant hasn't seeded yet.
+   \`\`\`ts
+   const [header, footer, announcements] = await Promise.all([
+     client.content.header.get('main', locale),
+     client.content.footer.get('main', locale),
+     client.content.announcement.list(locale),
+   ]);
+   \`\`\`
+
+2. **FAQ \u2014 fetch lazily on the FAQ page.** Default key is \`'main'\`; pass a topical key (\`'shipping'\`, \`'returns'\`) for sub-FAQs.
+   \`\`\`ts
+   const faq = await client.content.faq.get('main', locale);
+   if (faq) {
+     faq.data.items.forEach(({ question, answer }) => {
+       // sanitize(answer) \u2014 see step 4
+     });
+   }
+   \`\`\`
+
+3. **Static pages \u2014 catch-all route by slug:**
+   \`\`\`tsx
+   // app/[slug]/page.tsx
+   export default async function Page({ params }) {
+     const page = await client.content.page.getBySlug(params.slug, locale);
+     if (!page) notFound();
+     return (
+       <article dangerouslySetInnerHTML={{ __html: sanitize(page.data.html) }} />
+     );
+   }
+   \`\`\`
+
+4. **SECURITY \u2014 sanitize HTML before rendering.** \`FAQ.items[i].answer\`, \`PAGE.html\`, and \`RICH_TEXT.html\` are merchant-authored HTML. The server does NOT pre-sanitize because some merchants embed iframes (e.g. YouTube). Always sanitize at the edge of your render:
+   \`\`\`ts
+   import DOMPurify from 'isomorphic-dompurify';
+   const safe = DOMPurify.sanitize(rawHtml);
+   <div dangerouslySetInnerHTML={{ __html: safe }} />;
+   \`\`\`
+   Skipping this is XSS.
+
+5. **Announcements \u2014 multiple may be active; filter by date client-side:**
+   \`\`\`ts
+   const now = Date.now();
+   const visible = announcements.filter((a) => {
+     const startOk = !a.data.startsAt || new Date(a.data.startsAt).getTime() <= now;
+     const endOk = !a.data.endsAt || new Date(a.data.endsAt).getTime() >= now;
+     return startOk && endOk;
+   });
+   \`\`\`
+
+6. **RTL direction \u2014 call \`client.getStoreDirection(locale)\`:**
+   \`\`\`tsx
+   const dir = client.getStoreDirection(locale);
+   <html lang={locale} dir={dir}>...</html>
+   \`\`\`
+   Do NOT maintain a local RTL locale set \u2014 the SDK helper covers Arabic / Hebrew / Persian / Urdu / Yiddish today and picks up any future RTL locale automatically.
+
+7. **Custom fields \u2014 every Content row has free-form \`customFields: Record<string, string>\`.** Read keys the merchant told you to expect:
+   \`\`\`ts
+   const faq = await client.content.faq.get('shipping');
+   <a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+   \`\`\`
+
+8. **Cache:** public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`. Don't add extra client-side caching beyond Next.js's default fetch cache \u2014 merchants expect their edits to appear within ~5 minutes.
+
+**Translations.** All public reads accept a \`locale\` argument; the server resolves \`translations[locale]\` server-side. Empty / missing overlays fall through to the default-locale value. The storefront does NOT need to do its own per-field overlay \u2014 call with the active locale and render what comes back.`
   }
 };
 var FLOW_ORDER = [
@@ -5790,7 +6375,8 @@ var FLOW_ORDER = [
   "order-confirmation",
   "cart-persistence",
   "inventory-reservation",
-  "product-customization"
+  "product-customization",
+  "content-bootstrap"
 ];
 async function handleGetBusinessFlows(args) {
   const header = "# Brainerce Business Flows\n\nThese sequences are framework-neutral and non-negotiable. Your framework and file layout are your choice \u2014 the order of SDK calls and the error handling is not.";
@@ -6002,11 +6588,57 @@ var FEATURES = [
   {
     id: "i18n",
     title: "Serve multiple languages with a language switcher",
-    description: "When i18n is enabled, the experience routes by locale, sets the SDK locale (client.setLocale), includes a language switcher in the header, and renders RTL locales (he, ar) with the correct document direction.",
-    sdk: "client.setLocale(locale). Read supported locales from get-store-capabilities.store.i18n.",
+    description: "When i18n is enabled, the experience routes by locale, sets the SDK locale (client.setLocale), includes a language switcher in the header, and renders the correct document direction by reading client.getStoreDirection(locale) \u2014 do not hardcode an RTL locale set.",
+    sdk: "client.setLocale(locale). client.getStoreDirection(locale) for <html dir>. Read supported locales from get-store-capabilities.store.i18n.",
     mandatory: "conditional",
     capabilityFlag: "i18n",
     whenDisabledNote: "This store is single-language. Do not build the language switcher."
+  },
+  {
+    id: "site-header",
+    title: "Site header from merchant content (logo + nav + CTA)",
+    description: 'Fetch client.content.header.get("main", locale) in the root layout. Returns null when the merchant has not seeded yet \u2014 render a hard-coded fallback so the page never crashes. Renders header.data.logo, header.data.navItems[], header.data.cta if present.',
+    sdk: 'client.content.header.get("main", locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "mandatory"
+  },
+  {
+    id: "site-footer",
+    title: "Site footer from merchant content (columns + social + copyright)",
+    description: 'Fetch client.content.footer.get("main", locale) in the root layout. Returns null when unseeded \u2014 render a hard-coded fallback. Render footer.data.columns[].links, footer.data.social[], footer.data.copyright.',
+    sdk: 'client.content.footer.get("main", locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "mandatory"
+  },
+  {
+    id: "announcement-bar",
+    title: "Announcement bar at the top of every page",
+    description: "Fetch client.content.announcement.list(locale) in the root layout. Filter by data.startsAt / data.endsAt client-side. Render a dismissible bar when data.dismissible=true. Build the UI anyway \u2014 it auto-hides when no announcements exist.",
+    sdk: "client.content.announcement.list(locale)",
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "Store has no published Content rows yet. Build the announcement bar anyway \u2014 it auto-hides on empty."
+  },
+  {
+    id: "faq-page",
+    title: "FAQ page rendered from merchant content",
+    description: 'Build /faq as an accordion fed by client.content.faq.get("main", locale). For topical FAQs, use a key parameter (shipping, returns, ...). Always sanitize answer HTML before injecting via dangerouslySetInnerHTML. Build the page anyway \u2014 it auto-hides or 404s when no FAQ rows exist.',
+    sdk: 'client.content.faq.get("main", locale), client.content.faq.list(locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "No FAQ content yet. Build /faq anyway \u2014 it auto-hides on empty."
+  },
+  {
+    id: "static-pages",
+    title: "Static pages from merchant content (About, Terms, Privacy, \u2026)",
+    description: "Mount a catch-all app/[slug]/page.tsx route. Inside, call client.content.page.getBySlug(params.slug, locale). On null \u2192 notFound(). On hit, sanitize page.data.html before injecting via dangerouslySetInnerHTML. Generate <Metadata> from page.data.seo. Build the route anyway \u2014 it 404s on unknown slugs.",
+    sdk: "client.content.page.getBySlug(slug, locale), client.content.page.list(locale)",
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "No static pages yet. Build the catch-all route anyway \u2014 it 404s on unknown slugs."
   }
 ];
 function isFeatureActive(feature, caps) {
@@ -6057,6 +6689,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(
     `- Email verification: ${caps.connection.requireEmailVerification ? "required" : "not required (still build the verify-email flow)"}`
   );
@@ -6385,14 +7020,149 @@ function createServer() {
 
 // src/bin/http.ts
 var PORT = parseInt(process.env.PORT || "3100", 10);
-var CORS_ORIGIN = process.env.CORS_ORIGIN || "*";
 var SSE_KEEPALIVE_MS = 1e4;
 var SESSION_MAX_AGE_MS = 4 * 60 * 60 * 1e3;
+var NODE_ENV = process.env.NODE_ENV || "development";
+var IS_DEV = NODE_ENV === "development";
+var AUTH_TOKENS = (process.env.MCP_AUTH_TOKENS || "").split(",").map((t) => t.trim()).filter((t) => t.length > 0).map((t) => Buffer.from(t, "utf8"));
+if (AUTH_TOKENS.length === 0 && !IS_DEV) {
+  console.error(
+    "FATAL: MCP_AUTH_TOKENS is not set. The MCP HTTP server must run with at least one Bearer token in non-development environments.\nMint a token (e.g., `mcp_<random>`) via the dashboard and add it (comma-separated) to MCP_AUTH_TOKENS."
+  );
+  process.exit(1);
+}
+if (AUTH_TOKENS.length === 0 && IS_DEV) {
+  console.warn(
+    "WARN: MCP_AUTH_TOKENS is not set. Running in development mode \u2014 any non-empty Bearer token will be accepted."
+  );
+}
+var ALLOWED_ORIGINS = (process.env.MCP_ALLOWED_ORIGINS || "").split(",").map((o) => o.trim()).filter((o) => o.length > 0);
+var LOCALHOST_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/;
+var RATE_LIMIT_WINDOW_MS = parseInt(process.env.MCP_RATE_LIMIT_WINDOW_MS || "60000", 10);
+var RATE_LIMIT_MAX = parseInt(process.env.MCP_RATE_LIMIT_MAX || "60", 10);
+var rateBuckets = /* @__PURE__ */ new Map();
+var MAX_BODY_BYTES = parseInt(process.env.MCP_MAX_BODY_BYTES || String(100 * 1024), 10);
+function safeEqual(a, b) {
+  if (a.length !== b.length) {
+    const max = Math.max(a.length, b.length);
+    const ax = Buffer.alloc(max);
+    const bx = Buffer.alloc(max);
+    a.copy(ax);
+    b.copy(bx);
+    (0, import_node_crypto.timingSafeEqual)(ax, bx);
+    return false;
+  }
+  return (0, import_node_crypto.timingSafeEqual)(a, b);
+}
+function authenticate(req, res) {
+  const header = req.headers["authorization"];
+  if (typeof header !== "string" || !header.toLowerCase().startsWith("bearer ")) {
+    writeJson(res, 401, {
+      error: "Missing or malformed Authorization header. Expected: Bearer <token>."
+    });
+    return false;
+  }
+  const presented = header.slice(7).trim();
+  if (presented.length === 0) {
+    writeJson(res, 401, { error: "Empty Bearer token." });
+    return false;
+  }
+  if (AUTH_TOKENS.length === 0 && IS_DEV) {
+    return true;
+  }
+  const presentedBuf = Buffer.from(presented, "utf8");
+  let matched = false;
+  for (const token of AUTH_TOKENS) {
+    if (safeEqual(presentedBuf, token)) {
+      matched = true;
+    }
+  }
+  if (!matched) {
+    writeJson(res, 401, { error: "Invalid Bearer token." });
+    return false;
+  }
+  return true;
+}
+function clientIp(req) {
+  const xff = req.headers["x-forwarded-for"];
+  if (typeof xff === "string" && xff.length > 0) {
+    return xff.split(",")[0].trim();
+  }
+  return req.socket.remoteAddress || "unknown";
+}
+function rateLimit(req, res) {
+  const ip = clientIp(req);
+  const now = Date.now();
+  const bucket = rateBuckets.get(ip);
+  if (!bucket || bucket.resetAt <= now) {
+    rateBuckets.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+    return true;
+  }
+  if (bucket.count >= RATE_LIMIT_MAX) {
+    const retryAfter = Math.max(1, Math.ceil((bucket.resetAt - now) / 1e3));
+    res.setHeader("Retry-After", String(retryAfter));
+    writeJson(res, 429, { error: "Rate limit exceeded. Try again later." });
+    return false;
+  }
+  bucket.count += 1;
+  return true;
+}
+var rateLimitGcTimer = setInterval(
+  () => {
+    const now = Date.now();
+    for (const [ip, bucket] of rateBuckets) {
+      if (bucket.resetAt <= now) rateBuckets.delete(ip);
+    }
+  },
+  5 * 60 * 1e3
+);
+rateLimitGcTimer.unref();
+function resolveCorsOrigin(origin) {
+  if (!origin) return null;
+  if (ALLOWED_ORIGINS.includes(origin)) return origin;
+  if (IS_DEV && LOCALHOST_ORIGIN_RE.test(origin)) return origin;
+  return null;
+}
+function setCors(req, res) {
+  const origin = typeof req.headers.origin === "string" ? req.headers.origin : void 0;
+  const allowed = resolveCorsOrigin(origin);
+  if (allowed) {
+    res.setHeader("Access-Control-Allow-Origin", allowed);
+    res.setHeader("Vary", "Origin");
+  }
+  res.setHeader("Access-Control-Allow-Credentials", "false");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+  res.setHeader(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Accept, Authorization, Mcp-Session-Id"
+  );
+  res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+}
+function writeJson(res, status, body) {
+  if (res.headersSent) return;
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
 function parseBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    req.on("data", (chunk) => chunks.push(chunk));
+    let total = 0;
+    let aborted = false;
+    req.on("data", (chunk) => {
+      if (aborted) return;
+      total += chunk.length;
+      if (total > MAX_BODY_BYTES) {
+        aborted = true;
+        const err = new Error("Request body exceeds maximum allowed size");
+        err.statusCode = 413;
+        reject(err);
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
     req.on("end", () => {
+      if (aborted) return;
       if (chunks.length === 0) return resolve(void 0);
       try {
         resolve(JSON.parse(Buffer.concat(chunks).toString()));
@@ -6429,14 +7199,8 @@ async function main() {
     5 * 60 * 1e3
   );
   cleanupTimer.unref();
-  function setCors(res) {
-    res.setHeader("Access-Control-Allow-Origin", CORS_ORIGIN);
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Mcp-Session-Id");
-    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-  }
   const httpServer = (0, import_node_http.createServer)(async (req, res) => {
-    setCors(res);
+    setCors(req, res);
     if (req.method === "OPTIONS") {
       res.writeHead(204);
       res.end();
@@ -6453,6 +7217,8 @@ async function main() {
       );
       return;
     }
+    if (!rateLimit(req, res)) return;
+    if (!authenticate(req, res)) return;
     if (req.url === "/mcp") {
       try {
         const server = createServer();
@@ -6465,8 +7231,7 @@ async function main() {
       } catch (error) {
         console.error("MCP request error:", error);
         if (!res.headersSent) {
-          res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Internal server error" }));
+          writeJson(res, 500, { error: "Internal server error" });
         }
       }
       return;
@@ -6507,8 +7272,7 @@ async function main() {
       } catch (error) {
         console.error("SSE connection error:", error);
         if (!res.headersSent) {
-          res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Internal server error" }));
+          writeJson(res, 500, { error: "Internal server error" });
         }
       }
       return;
@@ -6517,8 +7281,7 @@ async function main() {
       const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
       const sessionId = url.searchParams.get("sessionId");
       if (!sessionId || !sseSessions.has(sessionId)) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Invalid or missing sessionId" }));
+        writeJson(res, 400, { error: "Invalid or missing sessionId" });
         return;
       }
       try {
@@ -6526,20 +7289,23 @@ async function main() {
         const body = await parseBody(req);
         await session.transport.handlePostMessage(req, res, body);
       } catch (error) {
-        console.error("SSE message error:", error);
+        const status = error && typeof error === "object" && "statusCode" in error ? error.statusCode || 500 : 500;
+        if (status !== 500) {
+          console.warn("SSE message rejected:", error.message);
+        } else {
+          console.error("SSE message error:", error);
+        }
         if (!res.headersSent) {
-          res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Internal server error" }));
+          writeJson(res, status, {
+            error: status === 413 ? "Payload too large" : "Internal server error"
+          });
         }
       }
       return;
     }
-    res.writeHead(404, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({
-        error: "Not found. Use /mcp (Streamable HTTP), /sse (legacy SSE), or /health."
-      })
-    );
+    writeJson(res, 404, {
+      error: "Not found. Use /mcp (Streamable HTTP), /sse (legacy SSE), or /health."
+    });
   });
   function shutdown(signal) {
     console.info(`
@@ -6567,6 +7333,16 @@ ${signal} received \u2014 shutting down gracefully...`);
     console.info(`  Streamable HTTP: http://localhost:${PORT}/mcp`);
     console.info(`  Legacy SSE:      http://localhost:${PORT}/sse`);
     console.info(`  Health check:    http://localhost:${PORT}/health`);
+    console.info(
+      `  Auth tokens:     ${AUTH_TOKENS.length} configured${AUTH_TOKENS.length === 0 && IS_DEV ? " (dev: any non-empty Bearer accepted)" : ""}`
+    );
+    console.info(
+      `  CORS:            ${ALLOWED_ORIGINS.length} allow-listed origin(s)${IS_DEV ? " + localhost (dev)" : ""}`
+    );
+    console.info(
+      `  Rate limit:      ${RATE_LIMIT_MAX} req / ${Math.round(RATE_LIMIT_WINDOW_MS / 1e3)}s per IP`
+    );
+    console.info(`  Max body:        ${MAX_BODY_BYTES} bytes`);
   });
 }
 main().catch((error) => {