@brainerce/mcp-server 3.8.0 → 3.9.0

package/dist/index.js

@@ -1179,6 +1179,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.
@@ -1312,6 +1314,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
@@ -1639,6 +1643,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\`.
@@ -2040,19 +2046,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
@@ -2281,7 +2292,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
@@ -2383,7 +2404,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()
@@ -2391,6 +2414,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
@@ -2422,7 +2452,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)
@@ -3080,11 +3173,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';
@@ -3200,6 +3293,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 {
@@ -3325,6 +3423,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;
@@ -3401,6 +3500,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
@@ -3419,6 +3519,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 ----
 
@@ -3476,6 +3578,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 {
@@ -3658,7 +3761,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
@@ -4191,6 +4294,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,
@@ -4202,7 +4394,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") {
@@ -4233,10 +4426,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) {
@@ -6026,11 +6221,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.`
@@ -6512,7 +6712,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)"}`
   );