brainerce 1.44.1 → 1.46.0

package/README.md

@@ -32,28 +32,28 @@ yarn add brainerce
 
 Every Brainerce storefront must include **all mandatory features** below. Features auto-hide when the underlying capability is disabled, so build them all anyway — they'll appear the moment the store owner enables them.
 
-| Feature                                                 | SDK entry point                                                                                               | Mandatory   |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
-| Product list with search, filter, pagination            | `client.getProducts()`, `client.getSearchSuggestions(query)`                                                  | ✅          |
-| Product detail with variant picker, stock, price        | `client.getProductBySlug()` + helpers                                                                         | ✅          |
-| Buyer customization fields (engraving, uploads, select) | `product.customizationFields`, `client.uploadCustomizationFile()`                                             | ✅          |
-| Cart (add, update, remove, coupon, totals)              | `client.addToCart()`, `getCartTotals(cart)`                                                                   | ✅          |
-| Inventory reservation countdown                         | Cart expiry timestamp from `client.getCart()`                                                                 | ✅          |
-| Full checkout end-to-end with payment                   | `setShippingAddress → selectShippingMethod → getPaymentProviders → pay → handlePaymentSuccess → waitForOrder` | ✅          |
-| Order confirmation (clear cart + wait for real order)   | `client.handlePaymentSuccess()`, `client.waitForOrder()`                                                      | ✅          |
-| Register + email verification flow                      | `client.registerCustomer()`, `client.verifyEmail()`                                                           | ✅          |
-| Login + verification branch                             | `client.loginCustomer()`                                                                                      | ✅          |
-| Forgot / reset password                                 | `client.forgotPassword()`, `client.resetPassword()`                                                           | ✅          |
-| OAuth sign-in buttons + callback handler                | `client.getAvailableOAuthProviders()`                                                                         | ✅          |
-| Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                               | ✅          |
+| Feature                                                 | SDK entry point                                                                                                             | Mandatory   |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| Product list with search, filter, pagination            | `client.getProducts()`, `client.getSearchSuggestions(query)`                                                                | ✅          |
+| Product detail with variant picker, stock, price        | `client.getProductBySlug()` + helpers                                                                                       | ✅          |
+| Buyer customization fields (engraving, uploads, select) | `product.customizationFields`, `client.uploadCustomizationFile()`                                                           | ✅          |
+| Cart (add, update, remove, coupon, totals)              | `client.addToCart()`, `getCartTotals(cart)`                                                                                 | ✅          |
+| Inventory reservation countdown                         | Cart expiry timestamp from `client.getCart()`                                                                               | ✅          |
+| Full checkout end-to-end with payment                   | `setShippingAddress → selectShippingMethod → getPaymentProviders → pay → handlePaymentSuccess → waitForOrder`               | ✅          |
+| Order confirmation (clear cart + wait for real order)   | `client.handlePaymentSuccess()`, `client.waitForOrder()`                                                                    | ✅          |
+| Register + email verification flow                      | `client.registerCustomer()`, `client.verifyEmail()`                                                                         | ✅          |
+| Login + verification branch                             | `client.loginCustomer()`                                                                                                    | ✅          |
+| Forgot / reset password                                 | `client.forgotPassword()`, `client.resetPassword()`                                                                         | ✅          |
+| OAuth sign-in buttons + callback handler                | `client.getAvailableOAuthProviders()`                                                                                       | ✅          |
+| Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                                             | ✅          |
 | Loyalty & rewards (points balance + tiers + redeem)     | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`, `client.reportSocialShare()` | conditional |
-| Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
-| Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
-| Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                          | ✅          |
-| Site chrome (header + footer + announcement bar)        | `client.content.header.get()`, `client.content.footer.get()`, `client.content.announcement.list()`            | ✅          |
-| FAQ page                                                | `client.content.faq.get('main', locale)`                                                                      | conditional |
-| Static pages catch-all (`/pages/[slug]`)                | `client.content.page.getBySlug(slug, locale)`                                                                 | conditional |
-| Multi-language + RTL (when i18n enabled)                | `client.setLocale()`, `client.getStoreDirection(locale)`                                                      | conditional |
+| Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                                    | ✅          |
+| Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                                  | ✅          |
+| Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                                        | ✅          |
+| Site chrome (header + footer + announcement bar)        | `client.content.header.get()`, `client.content.footer.get()`, `client.content.announcement.list()`                          | ✅          |
+| FAQ page                                                | `client.content.faq.get('main', locale)`                                                                                    | conditional |
+| Static pages catch-all (`/pages/[slug]`)                | `client.content.page.getBySlug(slug, locale)`                                                                               | conditional |
+| Multi-language + RTL (when i18n enabled)                | `client.setLocale()`, `client.getStoreDirection(locale)`                                                                    | conditional |
 
 ---
 
@@ -874,6 +874,36 @@ console.log('Order created:', orderId);
 
 > **WARNING:** Do NOT use `submitGuestOrder()` for logged-in customers! Their orders won't be linked to their account and won't appear in their order history.
 
+### Address Autocomplete (optional, for the `line1` field)
+
+Turn the shipping address's `line1` input into a typeahead instead of free
+text. Suggestions come from Google Places; each resolved address is flagged
+`inZone` against the store's configured shipping zones — a soft signal for a
+warning banner, never a hard block.
+
+```typescript
+const sessionToken = crypto.randomUUID(); // one per address-entry attempt
+
+// Debounce (~300ms) as the shopper types
+const suggestions = await client.getAddressSuggestions('Rothschild 1', sessionToken);
+// [{ placeId: 'ChIJ...', description: 'Rothschild Blvd 1, Tel Aviv-Yafo' }, ...]
+
+// On picking a suggestion — reuse the SAME sessionToken to end the session
+const { address, inZone } = await client.getAddressDetails(suggestions[0].placeId, sessionToken);
+// address: { line1, city, region, postalCode, country, lat, lng, formattedAddress }
+
+await client.setShippingAddress(checkout.id, {
+  firstName: 'John',
+  lastName: 'Doe',
+  ...address,
+});
+
+if (!inZone) {
+  // Non-blocking: "This address is outside our regular delivery zones.
+  // You can still continue — we'll confirm delivery by phone."
+}
+```
+
 ---
 
 ## Cart (Unified for All Users)
@@ -1573,7 +1603,7 @@ await client.addToCart(cartId, {
 ```typescript
 // Works for CartItem, CheckoutLineItem, and OrderItem — same shape
 const summary = Object.values(item.customizations ?? {})
-  .map(c => `${c.label}: ${Array.isArray(c.value) ? c.value.join(', ') : c.value}`)
+  .map((c) => `${c.label}: ${Array.isArray(c.value) ? c.value.join(', ') : c.value}`)
   .join(' | ');
 // e.g. "Frame color: Gold | Add-ons: Gift wrap, Engraving"
 ```
@@ -2262,11 +2292,11 @@ interface Checkout {
   subtotal: string;
   discountAmount: string;
   shippingAmount: string;
-  taxAmount: string;          // "0" in inclusive (VAT) mode — see taxBreakdown.totalTax
+  taxAmount: string; // "0" in inclusive (VAT) mode — see taxBreakdown.totalTax
   taxBreakdown?: TaxBreakdown | null; // { totalTax, pricesIncludeTax, breakdown[] }
   total: string;
   couponCode?: string | null;
-  notes?: string | null;      // Order note from setCheckoutCustomer/setShippingAddress
+  notes?: string | null; // Order note from setCheckoutCustomer/setShippingAddress
   items: CheckoutLineItem[];
   itemCount: number;
   availableShippingRates?: ShippingRate[];
@@ -2404,12 +2434,12 @@ const checkoutId = checkout.id;
 Use this method to get ALL enabled payment providers and build dynamic UI.
 
 **Primary vs. additive methods (Shopify-parity).** Each provider carries a
-`methodType`. A `CREDIT_CARD` provider is the *primary* card processor — the
+`methodType`. A `CREDIT_CARD` provider is the _primary_ card processor — the
 single method that settles the order (`defaultProvider`, `isAdditive: false`,
-`presentation: 'card_form'`). Everything else is *additive* (`isAdditive: true`),
+`presentation: 'card_form'`). Everything else is _additive_ (`isAdditive: true`),
 e.g. PayPal is a `'WALLET'` with `presentation: 'express_button'`. Render additive
 methods as accelerated-checkout **express buttons above the card form** — they sit
-*alongside* the primary, never replace it. (Exception: a wallet-only store has no
+_alongside_ the primary, never replace it. (Exception: a wallet-only store has no
 card processor, so its wallet becomes the `defaultProvider` and stands alone.)
 
 ```typescript
@@ -2967,8 +2997,9 @@ const rewards = await client.getAvailableRewards();
 // Redeem → spends points, returns a one-time coupon code to apply to the cart.
 // `discountType` tells you how to interpret `discountValue` (currency amount
 // for FIXED_DISCOUNT, 0-100 percent for PERCENT_DISCOUNT).
-const { couponCode, discountType, discountValue, pointsBalance } =
-  await client.redeemLoyaltyReward(rewards[0].id);
+const { couponCode, discountType, discountValue, pointsBalance } = await client.redeemLoyaltyReward(
+  rewards[0].id
+);
 await client.applyCoupon(cartId, couponCode);
 
 // Self-reported social share — grants the SOCIAL_SHARE bonus if configured
@@ -3545,8 +3576,8 @@ client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
 const params = new URLSearchParams(window.location.search);
 client.trackEvent({
   path: window.location.pathname,
-  utmSource:   params.get('utm_source')   ?? undefined,
-  utmMedium:   params.get('utm_medium')   ?? undefined,
+  utmSource: params.get('utm_source') ?? undefined,
+  utmMedium: params.get('utm_medium') ?? undefined,
   utmCampaign: params.get('utm_campaign') ?? undefined,
   screenWidth: window.innerWidth,
   lang: navigator.language,
@@ -3577,6 +3608,94 @@ const admin = new BrainerceClient({
 });
 ```
 
+### Product Management
+
+```typescript
+import type { Product, CreateProductDto, UpdateProductDto } from 'brainerce';
+
+// Create a simple product
+const product: Product = await client.createProduct({
+  name: 'Classic T-Shirt',
+  slug: 'classic-t-shirt', // Optional — auto-generated from name if omitted
+  sku: 'TSH-001',
+  description: 'Soft cotton tee.',
+  basePrice: 29.99,
+  salePrice: 24.99, // Optional
+  costPrice: 12.0, // Optional, internal — never synced to platforms
+  status: 'active', // 'active' | 'draft' (default: 'active')
+  type: 'SIMPLE', // 'SIMPLE' | 'VARIABLE' (default: 'SIMPLE')
+  categories: ['cat_id'], // Existing category IDs
+  categoryNames: ['Apparel'], // Or assign/auto-create by name — merged with `categories`
+  brands: ['brand_id'],
+  tags: ['sale', 'summer'],
+  images: [
+    {
+      url: 'https://cdn.example.com/tshirt.jpg',
+      position: 0,
+      isMain: true,
+      alt: 'Classic T-Shirt',
+    },
+  ],
+
+  // Cross-platform identifiers (Google Shopping / Facebook Catalog / TikTok).
+  // Provide gtin when the product has one; otherwise mpn + brand.
+  gtin: '012345678905', // EAN/UPC/ISBN — validated (GS1 mod-10 checksum)
+  mpn: 'MFR-TSH-001', // Manufacturer Part Number — used only when gtin is absent
+
+  // Google Merchant Center sale_price_effective_date — bounds when `salePrice`
+  // is actually active. Set both together, or omit both (sale always active).
+  salePriceStartsAt: '2026-06-01T00:00:00Z',
+  salePriceEndsAt: '2026-06-30T23:59:59Z',
+
+  // Shipping weight & dimensions — used for accurate shipping-cost
+  // calculation and Google Shopping's shipping_weight/shipping_length/etc.
+  shippingWeightValue: 0.3,
+  shippingWeightUnit: 'kg', // 'kg' | 'lb' | 'g' | 'oz'
+  shippingLengthValue: 30,
+  shippingWidthValue: 20,
+  shippingHeightValue: 2,
+  shippingDimensionUnit: 'cm', // 'cm' | 'in' — shared by length/width/height
+});
+
+// Update a product — every field is optional; only send what changed.
+// Pass `null` on gtin/mpn/salePriceStartsAt/salePriceEndsAt/shipping* to clear them.
+const updated: Product = await client.updateProduct('prod_123', {
+  salePrice: null, // End the sale
+  salePriceStartsAt: null,
+  salePriceEndsAt: null,
+} satisfies UpdateProductDto);
+
+// Delete a product (optionally also delete from synced platforms)
+await client.deleteProduct('prod_123', { platforms: ['SHOPIFY'] });
+
+// VARIABLE products: create the product with type: 'VARIABLE', then add variants
+const variableProduct = await client.createProduct({
+  name: 'Hoodie',
+  basePrice: 0,
+  type: 'VARIABLE',
+});
+await client.bulkSaveVariants(variableProduct.id, {
+  variants: [
+    {
+      sku: 'HOOD-S-BLK',
+      attributes: { Size: 'S', Color: 'Black' },
+      price: 49.99,
+      stock: 20,
+      isEnabled: true,
+    },
+    {
+      sku: 'HOOD-M-BLK',
+      attributes: { Size: 'M', Color: 'Black' },
+      price: 49.99,
+      stock: 15,
+      isEnabled: true,
+    },
+  ],
+});
+```
+
+**GTIN vs MPN:** these are two different identifiers, not interchangeable — GTIN (EAN/UPC/ISBN) is a universal barcode; MPN is manufacturer-specific and only meaningful paired with a brand. Provide GTIN when the product has one; otherwise brand + MPN. A product typically needs one or the other, not both.
+
 ### Taxonomy Management
 
 ```typescript
@@ -3698,6 +3817,37 @@ const euZone = await client.createShippingZone({
   regionIds: ['reg_eu'],
 });
 
+// Polygon zone ("draw on map") — a hand-drawn delivery area. GeoJSON
+// Polygon/MultiPolygon, [lng, lat] ring coordinates. Independent of
+// `countries`/`regions`/`postalCodes`: a zone matches if the address
+// satisfies *either* coverage, so both may be set on the same zone (this
+// example omits `countries` since the polygon is its only coverage).
+const polygonZone = await client.createShippingZone({
+  name: 'Tel Aviv Metro',
+  countries: [],
+  geometry: {
+    type: 'Polygon',
+    coordinates: [
+      [
+        [34.75, 32.05],
+        [34.75, 32.1],
+        [34.82, 32.1],
+        [34.82, 32.05],
+        [34.75, 32.05],
+      ],
+    ],
+  },
+});
+
+// Restrict a zone to specific sales channels — `SalesChannel.id` or the
+// public `vc_*` connectionId. Empty/omitted = every channel; a non-empty
+// list hides the zone unless the checkout came from one of them.
+const mobileOnlyZone = await client.createShippingZone({
+  name: 'US Domestic (mobile app only)',
+  countries: ['US'],
+  salesChannelIds: ['vc_abc123'],
+});
+
 // Shipping Rates
 const rates = await client.getZoneShippingRates('zone_id');
 await client.createZoneShippingRate('zone_id', {
@@ -3720,9 +3870,9 @@ const label = await admin.createShippingLabel(orderId, {
   shippoRateObjectId: 'rate_8f123456789abcdef', // Shippo rate.object_id from checkout rates
 });
 
-console.log(label.labelUrl);       // PDF label URL for printing
+console.log(label.labelUrl); // PDF label URL for printing
 console.log(label.trackingNumber); // Auto-populated on the order
-console.log(label.carrier);        // e.g. 'USPS', 'UPS', 'FedEx'
+console.log(label.carrier); // e.g. 'USPS', 'UPS', 'FedEx'
 ```
 
 The `trackingNumber` is stored on the `Order` automatically — customers see it in their
@@ -4047,6 +4197,43 @@ const preview = await client.previewEmailTemplate('template_id', {
 });
 ```
 
+### Storefront Bot Settings
+
+Requires an API key with the `bot-settings:read` / `bot-settings:write` scopes.
+
+```typescript
+// Every connection on the store + its current (or default) settings
+const { connections, settings } = await client.getBotSettings();
+
+// PATCH semantics — only the fields you pass are changed
+await client.updateBotSettings({
+  salesChannelId: connections[0].salesChannelId,
+  enabled: true,
+  displayName: 'Maya',
+  personaJson: {
+    greeting: 'Hi! Looking for something specific?',
+    tone: 'friendly', // 'friendly' | 'formal' | 'playful' | 'concise'
+    starterQuestions: ['What sizes do you carry?', "What's your return policy?"],
+    avoidTopics: 'Do not discuss competitor pricing or make medical claims.',
+    customInstructions: 'Always mention free shipping over $75.',
+    capabilities: { productQa: true, recommendations: true, returns: false },
+  },
+});
+```
+
+### Storefront Bot Conversations
+
+Studio inbox transcripts + on-demand summarization. Requires the `bot-conversations:read` / `bot-conversations:write` scopes.
+
+```typescript
+const { data: conversations } = await client.listBotConversations({ limit: 20 });
+const transcript = await client.getBotConversation(conversations[0].id);
+
+// Persists a summary on the conversation; short threads (10 or fewer messages)
+// are a no-op — { summarized: false, summary: null } — no credits charged.
+const { summarized, summary } = await client.summarizeBotConversation(conversations[0].id);
+```
+
 ### Sync Conflict Resolution
 
 ```typescript
@@ -5129,7 +5316,7 @@ const forms = await brainerce.contactForms.list();
 
 ## Storefront Bot (AI chat widget)
 
-Add the store's AI shopping assistant with one line. All configuration (name, avatar, colors, greeting, starter questions, guardrails) lives in the merchant dashboard — the widget renders nothing until the bot is switched Live there.
+Add the store's AI shopping assistant with one line. Configuration (name, avatar, colors, greeting, starter questions, guardrails) is normally set in the merchant dashboard — the widget renders nothing until the bot is switched Live there. Those same settings are also readable/writable via `client.getBotSettings()` / `client.updateBotSettings()`, and conversation transcripts + summarization via `client.listBotConversations()` / `client.summarizeBotConversation()` — see [Storefront Bot Settings](#storefront-bot-settings) and [Storefront Bot Conversations](#storefront-bot-conversations) in the Admin API Reference.
 
 ```html
 <!-- zero-code embed: keep the tag exactly this bare (no integrity/crossorigin) -->