@brainerce/mcp-server 3.8.0 → 3.9.0

package/dist/index.mjs

@@ -1147,6 +1147,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.
@@ -1280,6 +1282,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
@@ -1607,6 +1611,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\`.
@@ -2008,19 +2014,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
@@ -2249,7 +2260,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
@@ -2351,7 +2372,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()
@@ -2359,6 +2382,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
@@ -2390,7 +2420,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)
@@ -3048,11 +3141,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';
@@ -3168,6 +3261,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 {
@@ -3293,6 +3391,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;
@@ -3369,6 +3468,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
@@ -3387,6 +3487,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 ----
 
@@ -3444,6 +3546,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 {
@@ -3626,7 +3729,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
@@ -4159,6 +4262,95 @@ 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.
+
+// ---- 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,
@@ -4170,7 +4362,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") {
@@ -4201,10 +4394,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) {
@@ -5994,11 +6189,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.`
@@ -6480,7 +6680,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)"}`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.8.0",
+  "version": "3.9.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"