@brainerce/mcp-server 3.1.0 → 3.4.0

package/dist/index.mjs

@@ -59,7 +59,7 @@ function getTypeQuickReference() {
 | OAuth | \`provider.name\` | \`provider\` | it IS the string: \`'GOOGLE' | 'FACEBOOK' | 'GITHUB'\` |
 | OAuth | \`oauth.url\` | \`oauth.authorizationUrl\` | |
 | Description | \`getDescriptionContent()\` | \`{ html } | { text } | null\` | check \`'html' in content\` before use |
-| \`smartGetCart()\` | always use \`.id\` | check \`'id' in cart\` | returns \`Cart | LocalCart\` |
+| \`smartGetCart()\` | N/A | \`cart.id\` | returns \`CartWithIncludes\` (extends \`Cart\`); pass \`{ include: [...] }\` for extras |
 | \`startGuestCheckout()\` | always use \`.checkoutId\` | check \`result.tracked\` | discriminated union |
 
 **Rules:**
@@ -67,8 +67,8 @@ function getTypeQuickReference() {
 - CartItem/CheckoutLineItem = **NESTED** (\`item.product.name\`, \`item.unitPrice\`)
 - OrderItem = **FLAT** (\`item.name\`, \`item.price\`, \`item.totalPrice\`, \`item.image\`)
 - Cart has NO \`.total\` \u2014 use \`getCartTotals(cart)\`
-- \`getCartTotals()\` only works with server \`Cart\`, NOT \`LocalCart\`
-- \`smartGetCart()\` returns \`Cart | LocalCart\` \u2014 check \`'id' in cart\` before using Cart fields
+- \`getCartTotals()\` works with server \`Cart\` (all carts are server-side now)
+- \`smartGetCart()\` returns \`CartWithIncludes\` \u2014 always a server cart; pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` for extras
 - \`startGuestCheckout()\` returns discriminated union \u2014 check \`result.tracked\` before \`.checkoutId\`
 - \`SetShippingAddressDto.email\` is **required** \u2014 always include email
 
@@ -196,7 +196,7 @@ async function startCheckout() {
 6. Select shipping method \u2192 \`selectShippingMethod()\`
 6b. (Optional) Set checkout custom fields \u2192 \`setCheckoutCustomFields()\` \u2014 surcharges auto-calculated
 7. Create payment intent \u2192 \`createPaymentIntent()\` \u2192 returns \`{ clientSecret, provider }\`
-8. Branch on \`provider\`: \`'stripe'\` \u2192 Stripe Elements, \`'grow'\` \u2192 iframe, \`'paypal'\` \u2192 PayPal Buttons
+8. Branch on the **\`clientSdk.renderType\`** returned by \`createPaymentIntent()\` \u2014 NEVER hard-code by provider name. Values: \`'sdk-widget'\` (Stripe, PayPal, Grow), \`'iframe'\` (Cardcom hosted or Brainerce-hosted embed \u2014 detect via URL path), \`'redirect'\`, \`'sandbox'\`, \`'embedded-fields'\` (reserved).
 9. **Order is created AUTOMATICALLY after payment succeeds (via webhook) \u2014 for ALL providers!**
 
 ### Checkout Page Component
@@ -299,8 +299,8 @@ function CheckoutPage() {
       </div>
     );
   }
-  if (paymentData.provider === 'grow') {
-    return <GrowPaymentForm paymentUrl={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
+  if (paymentData.clientSdk?.renderType === 'iframe') {
+    return <PaymentIframe clientSecret={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
   }
   if (paymentData.provider === 'paypal' && paypalClientId) {
     return <PayPalPaymentForm clientId={paypalClientId} orderId={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
@@ -356,26 +356,82 @@ function StripePaymentForm({ checkoutId }: { checkoutId: string }) {
 }
 \`\`\`
 
-### Grow Payment Form (Israeli stores \u2014 iframe based, no SDK needed)
+### Iframe-Based Providers (Cardcom, legacy Grow, etc.)
+
+When \`clientSdk.renderType === 'iframe'\`, the payment intent returns a \`clientSecret\` which is a URL to load in an iframe. There are TWO flavors of iframe rendering you must handle:
+
+**Flavor A \u2014 Brainerce-hosted embed (URL path contains \`/embed/\`):** The iframe loads a Brainerce-branded compact form (e.g. Cardcom OpenFields). Render it **INLINE** inside your checkout flow (next to the order summary) \u2014 NO modal, NO dark overlay. The embed page posts messages to resize itself and to request top-level navigation (e.g. for Bit express-pay buttons).
+
+**Flavor B \u2014 Provider-hosted page (any other URL):** The iframe loads a full provider-branded page with its own header/chrome. Render inside a **modal overlay** so it doesn't fight your checkout layout.
+
+Detect flavor by URL path \u2014 works across localhost/staging/prod without a domain list:
 
 \`\`\`typescript
-function GrowPaymentForm({ paymentUrl, checkoutId }: { paymentUrl: string; checkoutId: string }) {
-  const [iframeLoaded, setIframeLoaded] = useState(false);
+function PaymentIframe({ clientSecret, checkoutId }: { clientSecret: string; checkoutId: string }) {
+  const [height, setHeight] = useState(540); // default before resize message arrives
+  const isBrainerceEmbed = (() => {
+    try { return new URL(clientSecret).pathname.includes('/embed/'); }
+    catch { return false; }
+  })();
+
+  useEffect(() => {
+    function handleMessage(e: MessageEvent) {
+      const data = e.data as { type?: string; height?: number; url?: string };
+      if (data?.type === 'brainerce:resize' && typeof data.height === 'number') {
+        setHeight(data.height);
+      }
+      if (data?.type === 'brainerce:redirect' && typeof data.url === 'string') {
+        // Top-level navigation (e.g. Bit). ALWAYS validate against an allowlist
+        // before navigating \u2014 never trust the URL blindly.
+        if (isTrustedPaymentUrl(data.url)) { window.top!.location.href = data.url; }
+      }
+      if (data?.type === 'brainerce:payment-complete') {
+        // Payment done \u2014 redirect to confirmation page which verifies server-side
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      }
+    }
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, [checkoutId]);
+
+  if (isBrainerceEmbed) {
+    // Inline: part of the checkout flow, no overlay
+    return (
+      <div className="w-full">
+        <iframe
+          src={clientSecret}
+          style={{ width: '100%', height, border: 0, transition: 'height 0.2s ease-out' }}
+          title="Payment"
+          allow="payment"
+        />
+      </div>
+    );
+  }
+
+  // Provider-hosted page: modal overlay
   return (
-    <div className="w-full">
-      {!iframeLoaded && <div className="flex items-center justify-center py-12"><span>Loading payment form...</span></div>}
-      <iframe
-        src={paymentUrl}
-        onLoad={() => setIframeLoaded(true)}
-        style={{ width: '100%', minHeight: '600px', border: 'none', display: iframeLoaded ? 'block' : 'none' }}
-        allow="payment"
-      />
-      <p className="text-center text-sm text-gray-500 mt-4">
-        Having trouble? <a href={paymentUrl} target="_blank" rel="noopener noreferrer" className="text-blue-600 underline">Open payment in new tab</a>
-      </p>
+    <div className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 py-6 overflow-y-auto">
+      <div className="bg-white rounded-2xl shadow-2xl w-full max-w-4xl mx-4">
+        <iframe
+          src={clientSecret}
+          style={{ width: '100%', height: '90vh', minHeight: 700, border: 0 }}
+          title="Payment"
+          allow="payment"
+        />
+      </div>
     </div>
   );
 }
+
+// Allowlist of origins you trust for top-level payment redirects.
+function isTrustedPaymentUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    // Add your provider hostnames here. Example: Cardcom for Bit express-pay.
+    return u.hostname === 'cardcom.solutions' || u.hostname.endsWith('.cardcom.solutions');
+  } catch { return false; }
+}
 \`\`\`
 
 ### PayPal Payment Form
@@ -645,12 +701,23 @@ const growProvider = providers.find(p => p.provider === 'grow');
 const paypalProvider = providers.find(p => p.provider === 'paypal');
 \`\`\`
 
-Each provider has: \`id\`, \`provider\` ('stripe'|'grow'|'paypal'|'sandbox'), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+
+The payment intent returned from \`createPaymentIntent()\` includes a \`clientSdk\` object whose \`renderType\` tells you exactly how to render \u2014 **branch on THAT, not on the provider name**:
 
+- \`renderType: 'sdk-widget'\` \u2014 load \`clientSdk.scriptUrl\`, mount into \`<div id={clientSdk.containerId}>\`. Used by Stripe, PayPal, Grow. The SDK paints its own form in your DOM.
+- \`renderType: 'iframe'\` \u2014 render \`<iframe src={clientSecret}>\`. Two flavors detected by URL path:
+  - Path contains \`/embed/\` \u2192 Brainerce-hosted embed. Render **INLINE** (no modal). Listen for \`brainerce:resize\` / \`brainerce:redirect\` postMessages. Used by Cardcom (embedded mode).
+  - Any other URL \u2192 provider-hosted page. Render inside a **modal**. Used by Cardcom (hosted mode), legacy Grow iframe.
+- \`renderType: 'redirect'\` \u2014 \`window.location.href = URL\`. Customer completes payment off-site and returns via SuccessRedirectUrl.
+- \`renderType: 'sandbox'\` \u2014 show a "Complete Test Order" button; call \`completeGuestCheckout(checkoutId)\`. Orders are \`isTestOrder: true\`. Appears when \`sandboxPaymentsEnabled\` is true.
+- \`renderType: 'embedded-fields'\` \u2014 reserved for future Stripe-Elements-style pattern (PCI micro-iframes for card/CVV mounted directly into the merchant form). **No provider ships this today** \u2014 handle via a "not supported yet" fallback.
+
+Provider-specific install notes:
 - **Stripe:** \`npm install @stripe/stripe-js @stripe/react-stripe-js\` \u2014 \`loadStripe(publicKey, { stripeAccount })\`
-- **Grow:** No SDK \u2014 uses iframe with payment URL. Supports credit cards, Bit, Apple Pay, Google Pay.
 - **PayPal:** \`npm install @paypal/react-paypal-js\` \u2014 \`PayPalScriptProvider\` + \`PayPalButtons\`
-- **Sandbox:** No SDK needed \u2014 when \`sandboxPaymentsEnabled\` is true, \`getPaymentProviders()\` includes a sandbox provider with \`renderType: 'sandbox'\`. Show a "Complete Test Order" button. Call \`completeGuestCheckout(checkoutId)\` to finalize. Orders are marked \`isTestOrder: true\`.`;
+- **Grow:** No SDK needed \u2014 JS SDK loaded via \`clientSdk.scriptUrl\`. Supports credit cards, Bit, Apple Pay, Google Pay.
+- **Cardcom:** No SDK needed \u2014 rendering driven by \`renderType: 'iframe'\` + the inline/modal branch above. Supports credit cards, Bit (when terminal provisions it), installments, 3D Secure.`;
 }
 function getProductsSection(_currency) {
   return `## Products & Variants
@@ -681,10 +748,12 @@ When \`storeInfo.i18n.enabled\` is true, call \`client.setLocale(locale)\` once
 \`{ locale }\` params needed. Translated fields include: \`name\`,
 \`description\`, \`slug\`, \`seoTitle\`, \`seoDescription\`, plus
 \`categories[].name\`, \`brands[].name\`, \`tags[].name\`, \`variants[].name\`,
-\`productAttributeOptions[].attribute.name\`/\`attributeOption.name\`, and
-\`metafields[].value\`. No client-side overlay. See the full \`i18n\` section
-(\`get-sdk-docs\` topic \`i18n\`) for the \`[locale]\` route pattern, SDK setup,
-and the brand/tag badge examples.
+\`variant.attributes\` keys and values (so \`getVariantOptions()\` returns
+translated attribute/option names), \`productAttributeOptions[].attribute.name\`/
+\`attributeOption.name\`, \`metafields[].value\`, cart item product/variant names,
+and recommendation/bundle/bump product names. No client-side overlay. See the
+full \`i18n\` section (\`get-sdk-docs\` topic \`i18n\`) for the \`[locale]\` route
+pattern, SDK setup, and the brand/tag badge examples.
 
 ### Price Display (Use SDK Helper!)
 
@@ -821,6 +890,8 @@ const material = getProductMetafieldValue(product, 'material');
 
 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.
 
+Merchants can also flag a \`MetafieldDefinition\` as \`appliesToAllProducts: true\` \u2014 those fields are folded into every product's \`customizationFields\` array automatically by the backend. Client code does not need to merge or union anything: always render exactly what's in \`product.customizationFields\`.
+
 \`\`\`typescript
 import { getProductCustomizationFields } from 'brainerce';
 import type { ProductCustomizationField } from 'brainerce';
@@ -879,7 +950,7 @@ function getCartSection(_currency) {
 ### Smart Cart Methods (RECOMMENDED)
 
 \`\`\`typescript
-const cart = await client.smartGetCart();  // Returns Cart | LocalCart
+const cart = await client.smartGetCart();  // Returns CartWithIncludes (extends Cart)
 await client.smartAddToCart({
   productId: product.id,
   variantId: selectedVariant?.id,
@@ -1010,7 +1081,19 @@ const recs = (product as any).recommendations as ProductRecommendationsResponse
 
 ### Cart Page Features
 
-**Cross-sell recommendations** (existing products the customer might also want):
+**Consolidated include** (fetch recommendations, upgrades, and bundles in one request):
+\`\`\`typescript
+import type { CartWithIncludes } from 'brainerce';
+const cart = await client.getCart(cartId, {
+  include: ['recommendations', 'upgrades', 'bundles'],
+});
+// cart.recommendations \u2014 cross-sell recommendations
+// cart.upgrades \u2014 upgrade suggestions keyed by source product ID
+// cart.bundles \u2014 bundle offers
+// Also works with smartGetCart: client.smartGetCart({ include: ['recommendations', 'upgrades', 'bundles'] })
+\`\`\`
+
+**Cross-sell recommendations** (or fetch individually for targeted refresh):
 \`\`\`typescript
 import type { CartRecommendationsResponse } from 'brainerce';
 const cartRecs = await client.getCartRecommendations(cartId, 4);
@@ -1102,6 +1185,110 @@ Always check the flag before rendering: \`if (storeInfo?.upsell?.featureName !==
 ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`, \`variants?\` (when variant selection needed).
 OrderBump/CartBundleOffer: includes \`requiresVariantSelection\` (boolean) and \`lockedVariant?\` (\`{ id, name, attributes }\`).`;
 }
+function getProductCustomizationFieldsSection() {
+  return `## Product Customization Fields (buyer input on product page)
+
+Some products let the buyer personalize them before adding to cart \u2014 engraving text, a photo upload, a color pick, a multi-select add-on list. The merchant defines these fields in the Brainerce dashboard; the storefront renders them, collects values, uploads any images, and passes everything as \`metadata\` on add-to-cart.
+
+### Where the fields come from
+
+They arrive **embedded on the product response** \u2014 no extra API call:
+
+\`\`\`typescript
+import type { Product, ProductCustomizationField, MetafieldType } from 'brainerce';
+
+const product = await client.getProductBySlug(slug);
+const fields: ProductCustomizationField[] = product.customizationFields ?? [];
+// fields is sorted by position. If empty, render the product page normally.
+\`\`\`
+
+Each field has:
+\`\`\`typescript
+{
+  definitionId: string;
+  key: string;              // stable identifier \u2014 use this as the metadata key
+  name: string;             // display label (may be localized)
+  description?: string | null;
+  type: MetafieldType;      // 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' |
+                            // 'JSON' | 'URL' | 'COLOR' | 'DIMENSION' | 'WEIGHT' |
+                            // 'IMAGE' | 'GALLERY' | 'SELECT' | 'MULTI_SELECT'
+  required: boolean;
+  minLength?: number | null;       // chars for TEXT/TEXTAREA; array size for MULTI_SELECT
+  maxLength?: number | null;
+  minValue?: number | null;        // NUMBER / DIMENSION / WEIGHT
+  maxValue?: number | null;
+  enumValues?: string[];           // required for SELECT / MULTI_SELECT
+  defaultValue?: string | null;
+  position: number;
+}
+\`\`\`
+
+### Render one control per type
+
+| type            | Render as                                                  | Collected value              |
+| --------------- | ---------------------------------------------------------- | ---------------------------- |
+| \`TEXT\`        | \`<input type="text">\`                                    | \`string\`                   |
+| \`TEXTAREA\`    | \`<textarea>\`                                             | \`string\`                   |
+| \`NUMBER\`      | \`<input type="number">\`                                  | \`number\`                   |
+| \`BOOLEAN\`     | checkbox / switch                                          | \`boolean\`                  |
+| \`DATE\`        | \`<input type="date">\`                                    | \`string\` (YYYY-MM-DD)      |
+| \`DATETIME\`    | \`<input type="datetime-local">\`                          | \`string\` (ISO 8601)        |
+| \`URL\`         | \`<input type="url">\`                                     | \`string\`                   |
+| \`COLOR\`       | \`<input type="color">\`                                   | \`string\` (#RRGGBB)         |
+| \`SELECT\`      | \`<select>\` or radio group (use \`enumValues\`)           | \`string\` (in enumValues)   |
+| \`MULTI_SELECT\`| checkbox group (use \`enumValues\`)                        | \`string[]\` (every in enum) |
+| \`IMAGE\`       | file input + upload via \`uploadCustomizationFile\`        | \`string\` (URL)             |
+| \`GALLERY\`     | multi-file input + one upload per file                     | \`string[]\` (URLs)          |
+| \`JSON\`        | textarea; validate is parseable                            | \`string\` (JSON)            |
+
+### Upload buyer-submitted images
+
+\`IMAGE\` and \`GALLERY\` require uploading before add-to-cart:
+
+\`\`\`typescript
+const { url } = await client.uploadCustomizationFile(file);
+// Server rules: image/* only, max 5 MB, 10 uploads/min per IP.
+// Files are retained for at least 7 days; after that, if the cart never
+// became an order, they are automatically deleted.
+\`\`\`
+
+### Add to cart with customization metadata
+
+\`\`\`typescript
+// Collect values keyed by field.key \u2014 NOT by field.name or field.definitionId.
+const metadata: Record<string, unknown> = {
+  engraving_text: 'Happy Birthday!',       // TEXT
+  frame_color: 'Gold',                     // SELECT (must be in enumValues)
+  upload_photo: url,                       // IMAGE (URL from uploadCustomizationFile)
+  addons: ['Gift wrap'],                   // MULTI_SELECT (always an array)
+};
+
+await client.addToCart(cart.id, {
+  productId: product.id,
+  quantity: 1,
+  metadata,
+});
+\`\`\`
+
+Server validation (rejected with HTTP 400 on failure):
+- \`required: true\` \u2192 must be present and non-empty
+- \`TEXT\` / \`TEXTAREA\` \u2192 string; \`minLength\` / \`maxLength\` enforced as character count
+- \`NUMBER\` \u2192 \`minValue\` / \`maxValue\` enforced
+- \`SELECT\` \u2192 value must be one of \`enumValues\`
+- \`MULTI_SELECT\` \u2192 array; each element in \`enumValues\`; duplicates removed; \`minLength\` / \`maxLength\` enforced as array size
+- \`IMAGE\` / \`GALLERY\` \u2192 URL(s) must be from \`/customization-upload\` on this store
+
+### Order snapshot
+
+When the order is created, each line's customization values are snapshotted onto the order item with \`{ key, name, type, value }\` \u2014 so later edits to the field definition don't orphan old orders. The merchant dashboard shows the values on the order detail page.
+
+### Common mistakes
+
+- Passing values keyed by \`field.name\` instead of \`field.key\` \u2192 silently ignored (unknown key)
+- Sending a \`MULTI_SELECT\` as a string instead of \`string[]\` \u2192 HTTP 400
+- Using a raw external URL (not from \`/customization-upload\`) for \`IMAGE\` / \`GALLERY\` \u2192 HTTP 400
+- Assuming \`enumValues\` is present for all types \u2014 only \`SELECT\` / \`MULTI_SELECT\` require it`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -1358,7 +1545,50 @@ const { data: orders } = await client.getMyOrders({ page: 1, limit: 10 }); // Re
 // \u274C WRONG \u2014 these methods don't exist!
 client.getCustomerProfile();
 client.getCustomerOrders();
-\`\`\``;
+\`\`\`
+
+### Order history should show more than just totals
+
+A useful order card includes ALL of the following when the data is present. Each section is conditional \u2014 render nothing if the field is empty.
+
+| Section | Source field | Notes |
+|---|---|---|
+| Header (number, status badge, date, total) | \`order.orderNumber\`, \`order.status\`, \`order.createdAt\`, \`order.totalAmount\` | Always present. |
+| Line items | \`order.items[]\` | Render image, name, qty, price. |
+| **Per-item customizations** | \`order.items[i].customizations\` | Map of { label, value, type }. Render by \`type\` \u2014 see table below. |
+| **Status timeline** | \`order.statusHistory\` | \`OrderStatusChange[]\`: \`{ status, at, note? }\`. Render as a vertical list. |
+| **Shipping address** | \`order.shippingAddress\` | Standard \`OrderAddress\` shape. |
+| **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
+| **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
+| Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+
+#### Rendering \`order.items[i].customizations\` by type
+
+The map key is the metafield slug; the value is \`{ label, value, type }\`. Dispatch by \`type\`:
+
+| Type | Value | Render |
+|---|---|---|
+| \`TEXT\`, \`TEXTAREA\`, \`URL\`, \`NUMBER\`, \`SELECT\` | string | Plain text (\`URL\` \u2192 anchor). |
+| \`BOOLEAN\` | \`"yes"\` / \`"no"\` | \u2713 / \u2717 |
+| \`MULTI_SELECT\` | \`string[]\` | Comma-separated. |
+| \`IMAGE\` | asset URL (string) | Thumbnail linking to full-size asset. |
+| \`GALLERY\` | \`string[]\` of URLs | Grid of thumbnails. |
+| \`COLOR\` | hex string | Swatch + hex text. |
+| \`DATE\` | ISO-8601 | \`toLocaleDateString()\` |
+| \`DATETIME\` | ISO-8601 | \`toLocaleString()\` |
+| Unknown | any | Plain text (defensive default). |
+
+The storefront scaffolded by \`create-brainerce-store\` already implements this. See \`src/components/account/order-history.tsx\` + the sibling \`order-customizations.tsx\`, \`order-status-timeline.tsx\`, \`order-shipping-block.tsx\`, \`order-payment-block.tsx\` \u2014 mirror that structure.
+
+### Do NOT render
+
+These fields are NOT returned to buyers by \`/customers/me/orders\`. If you see them in older examples, ignore them \u2014 they are for merchant/admin views only.
+
+- \`order.accountId\`, \`order.storeId\`, \`order.customerId\` (already known on the request)
+- \`order.notes\` (internal merchant notes)
+- \`order.customFieldValues\` (order-level checkout fields \u2014 merchant concept; buyers see \`items[i].customizations\`)
+- \`order.appliedSurcharges\`, \`order.surchargeAmount\`, \`order.appliedRuleIds\`, \`order.downloadMeta\`, \`order.pickupLocationData\``;
 }
 function getOrderConfirmationSection() {
   return `## Order Confirmation Page (/order-confirmation) \u2014 REQUIRED!
@@ -1528,7 +1758,8 @@ overlay needed:
 - \`brands[].name\`
 - \`tags[].name\`
 - \`variants[].name\`
-- \`productAttributeOptions[].attribute.name\`, \`attributeOption.name\`/\`value\`
+- \`variant.attributes\` keys and values \u2014 \`getVariantOptions(variant)\` returns translated attribute names and option values automatically
+- \`productAttributeOptions[].attribute.name\`, \`attributeOption.name\`
 - \`metafields[].value\`
 
 **Taxonomy (\`getCategories\`, \`getBrands\`, \`getTags\`):**
@@ -1537,6 +1768,10 @@ overlay needed:
 **Cart:**
 - \`items[].product.name\`, \`items[].variant.name\`
 
+**Bundles & Order Bumps:**
+- \`bundleProduct.name\`, \`bundleProduct.slug\`, \`bumpProduct.name\`, \`bumpProduct.slug\`
+- Variant names inside bundles/bumps
+
 **Checkout:**
 - Line items: \`items[].product.name\`, \`items[].variant.name\`
 - Discount banners, nudges, badges
@@ -1621,6 +1856,265 @@ const admin = new BrainerceClient({ apiKey: 'brainerce_...' });
 // OAuth: getOAuthProviders(), configureOAuthProvider()
 \`\`\``;
 }
+function getContactInquiriesSection() {
+  return `## Contact Inquiries & Forms (optional)
+
+Accept messages from one or more contact forms on your storefront. The merchant
+configures everything in the Brainerce dashboard under **Customers \u2192 Contact
+Forms**; submissions land in **Customers \u2192 Inquiries** and both sides receive
+email notifications.
+
+**IMPORTANT for AI code generators:** the merchant OWNS the form shape. Do not
+hardcode labels, placeholders, help text, the submit button, or the success
+message. Render from the schema returned by \`contactForms.get()\` so the
+storefront reflects whatever the merchant configures \u2014 including new fields
+they add later, translations they add later, and the success message they
+write. This is the difference between "a contact form" and "THE merchant's
+contact form."
+
+### Two integration paths
+
+1. **Simple (legacy)** \u2014 pass \`{ name, email, subject, message }\` and submit.
+   Works out of the box, no dashboard setup needed. Backed by a lazily-seeded
+   default form keyed \`"main"\` with five built-in fields (\`name\`, \`email\`,
+   \`phone\`, \`subject\`, \`message\`). Choose this only for throwaway demos.
+2. **Flexible (recommended, default in \`npx create-brainerce-store\`)** \u2014
+   merchants can configure multiple forms per store (e.g. \`main\`,
+   \`newsletter\`, \`whatsapp_prechat\`), add custom fields (TEXT, TEXTAREA,
+   EMAIL, PHONE, NUMBER, SELECT, MULTI_SELECT, CHECKBOX, URL, DATE), translate
+   everything per locale, hide any non-essential built-in. Fetch the schema
+   with \`contactForms.get(formKey, locale)\` and render dynamically.
+
+### Simple path (legacy shape)
+
+\`\`\`typescript
+import type { CreateInquiryInput, CreateInquiryResponse } from 'brainerce';
+
+const result = await brainerce.createInquiry({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  subject: 'Question about shipping',
+  message: 'Hi, do you ship internationally?',
+  phone: '+1-555-0100',           // optional
+  customerId: customer?.id,        // optional \u2014 link to logged-in customer
+  metadata: { page: '/contact' },  // optional
+});
+// \u2192 { id, status: 'NEW', createdAt }
+\`\`\`
+
+### Flexible path \u2014 end-to-end contract
+
+**Endpoints:**
+
+| Method | Path                                                              | Returns                        |
+| ------ | ----------------------------------------------------------------- | ------------------------------ |
+| GET    | \`/stores/:storeId/contact-forms\`                                 | \`ContactFormSummary[]\`         |
+| GET    | \`/stores/:storeId/contact-forms/:formKey?locale=xx\`              | \`ContactFormPublic\`            |
+| POST   | \`/stores/:storeId/inquiries\`                                     | \`CreateInquiryResponse\`        |
+
+All three are public (no API key). The SDK wraps them so you never call them
+directly \u2014 use \`brainerce.contactForms.list()\`, \`brainerce.contactForms.get()\`,
+and \`brainerce.createInquiry()\`.
+
+\`\`\`typescript
+import type { ContactFormPublic } from 'brainerce';
+
+// List active forms (optional \u2014 if you want a form picker or route-per-form setup)
+const forms = await brainerce.contactForms.list();
+// \u2192 [{ key: 'main', name: 'Contact us', isDefault: true }, ...]
+
+// Fetch one form's schema \u2014 server pre-resolves translations for the locale
+// and strips every field the merchant marked isVisible=false.
+const form = await brainerce.contactForms.get('main', 'en');
+// \u2192 {
+//     id, key, name, description?, submitButton, successMessage,
+//     fields: [{ key, type, label, placeholder?, helpText?, isRequired,
+//                enumValues?, validation?, defaultValue? }, ...]
+//   }
+
+// Submit a keyed payload. Unknown keys are stripped, required fields are
+// enforced, and every value is validated against \`validation\` server-side.
+await brainerce.createInquiry({
+  formKey: 'main',
+  fields: {
+    email: 'jane@example.com',       // built-in keys
+    message: 'Hi...',
+    // ...any custom keys the merchant added via the dashboard
+  },
+  locale: 'en',                          // stored on the inquiry \u2014 lets staff filter by language
+  sourceMetadata: { page: '/contact' },  // arbitrary provenance (UTM, referrer, etc.)
+});
+\`\`\`
+
+Both shapes go to the same POST endpoint and may be mixed; \`fields\` wins when
+both provide the same key. Unknown keys (not defined on the form schema) are
+stripped server-side.
+
+### Dynamic rendering \u2014 reference implementation
+
+Render every field type the merchant can pick. Keep this as a \`<DynamicField>\`
+component so the form is fully driven by \`schema.fields\`.
+
+\`\`\`tsx
+import type { ContactFormPublic, ContactFormPublicField } from 'brainerce';
+
+type FieldValue = string | string[] | boolean;
+
+function defaultValueFor(f: ContactFormPublicField): FieldValue {
+  if (f.type === 'CHECKBOX') return false;
+  if (f.type === 'MULTI_SELECT') return [];
+  return f.defaultValue ?? '';
+}
+
+function isEmpty(v: FieldValue): boolean {
+  if (typeof v === 'string') return v.trim().length === 0;
+  if (Array.isArray(v)) return v.length === 0;
+  return v === false;
+}
+
+function DynamicField({
+  field,
+  value,
+  onChange,
+}: {
+  field: ContactFormPublicField;
+  value: FieldValue;
+  onChange: (v: FieldValue) => void;
+}) {
+  const id = \`contact-\${field.key}\`;
+  const { minLength, maxLength, min, max, pattern } = field.validation ?? {};
+  const strVal = typeof value === 'string' ? value : '';
+
+  // Label \u2014 USE \`field.label\`, NEVER hardcode. Falls back to the key.
+  const label = (
+    <label htmlFor={id} className="mb-1.5 block text-sm font-medium">
+      {field.label}
+      {field.isRequired && <span aria-hidden className="text-red-500"> *</span>}
+    </label>
+  );
+  const help = field.helpText ? <p className="mt-1 text-xs opacity-70">{field.helpText}</p> : null;
+
+  switch (field.type) {
+    case 'TEXTAREA':
+      return (<div>{label}<textarea id={id} required={field.isRequired} maxLength={maxLength} minLength={minLength} rows={6} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'EMAIL':
+      return (<div>{label}<input id={id} type="email" required={field.isRequired} autoComplete="email" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'PHONE':
+      return (<div>{label}<input id={id} type="tel" required={field.isRequired} autoComplete="tel" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'URL':
+      return (<div>{label}<input id={id} type="url" required={field.isRequired} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'NUMBER':
+      return (<div>{label}<input id={id} type="number" required={field.isRequired} min={min} max={max} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'DATE':
+      return (<div>{label}<input id={id} type="date" required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+    case 'SELECT':
+      return (<div>{label}<select id={id} required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)}><option value="">\u2014</option>{field.enumValues?.map((o) => (<option key={o.value} value={o.value}>{o.label}</option>))}</select>{help}</div>);
+    case 'MULTI_SELECT': {
+      const arr = Array.isArray(value) ? value : [];
+      return (<div>{label}<div>{field.enumValues?.map((o) => { const checked = arr.includes(o.value); return (<label key={o.value}><input type="checkbox" checked={checked} onChange={(e) => onChange(e.target.checked ? [...arr, o.value] : arr.filter((v) => v !== o.value))} /><span>{o.label}</span></label>); })}</div>{help}</div>);
+    }
+    case 'CHECKBOX':
+      return (<div><label htmlFor={id}><input id={id} type="checkbox" required={field.isRequired} checked={value === true} onChange={(e) => onChange(e.target.checked)} /><span>{field.label}</span></label>{help}</div>);
+    case 'TEXT':
+    default:
+      return (<div>{label}<input id={id} type="text" required={field.isRequired} maxLength={maxLength} minLength={minLength} pattern={pattern} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+  }
+}
+
+export function ContactPage() {
+  const [schema, setSchema] = useState<ContactFormPublic | null>(null);
+  const [values, setValues] = useState<Record<string, FieldValue>>({});
+  const [honeypot, setHoneypot] = useState('');
+  const [sent, setSent] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  // Read the current locale from the <html lang> attribute (or your own i18n context).
+  const locale = typeof document !== 'undefined' ? document.documentElement.lang || undefined : undefined;
+
+  useEffect(() => {
+    brainerce.contactForms.get('main', locale).then((form) => {
+      setSchema(form);
+      const initial: Record<string, FieldValue> = {};
+      for (const f of form.fields) initial[f.key] = defaultValueFor(f);
+      setValues(initial);
+    });
+  }, [locale]);
+
+  if (!schema) return null;
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (loading) return;
+    if (honeypot.trim().length > 0) { setSent(true); return; } // bot \u2192 silent success
+
+    setLoading(true);
+    try {
+      const payload: Record<string, unknown> = {};
+      for (const f of schema.fields) {
+        const raw = values[f.key];
+        if (isEmpty(raw)) continue;
+        payload[f.key] = typeof raw === 'string' ? raw.trim() : raw;
+      }
+      await brainerce.createInquiry({ formKey: schema.key, fields: payload, locale });
+      setSent(true);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (sent) {
+    // RENDER THE MERCHANT'S success message \u2014 do not hardcode.
+    return <div>{schema.successMessage}</div>;
+  }
+
+  return (
+    <form onSubmit={onSubmit} noValidate>
+      <h1>{schema.name}</h1>
+      {schema.description && <p>{schema.description}</p>}
+
+      {/* Honeypot \u2014 must be visually hidden from humans, not from bots */}
+      <div aria-hidden style={{ position: 'absolute', left: '-10000px', width: 0, height: 0, overflow: 'hidden' }}>
+        <label htmlFor="contact-honeypot">Leave this field empty</label>
+        <input id="contact-honeypot" type="text" tabIndex={-1} autoComplete="off"
+          value={honeypot} onChange={(e) => setHoneypot(e.target.value)} />
+      </div>
+
+      {schema.fields.map((field) => (
+        <DynamicField key={field.key} field={field}
+          value={values[field.key] ?? defaultValueFor(field)}
+          onChange={(v) => setValues((p) => ({ ...p, [field.key]: v }))} />
+      ))}
+
+      <button type="submit" disabled={loading}>
+        {loading ? '\u2026' : schema.submitButton}
+      </button>
+    </form>
+  );
+}
+\`\`\`
+
+### Rules
+
+- **Rate limit:** 3 submissions / 60s per IP \u2014 show a friendly "try again later" message on HTTP 429.
+- **Honeypot:** always render a hidden field named \`honeypot\` and **never send** it. Bots fill every input; the server rejects submissions carrying a non-empty \`honeypot\`.
+- **Built-in keys:** \`name\`, \`email\`, \`phone\`, \`subject\`, \`message\` always exist on the default form; the legacy \`createInquiry\` shape keeps working forever.
+- **Max values:** each field value is capped at 10 000 chars server-side. Validate client-side before submitting using \`field.validation.maxLength\`.
+- **Required fields:** respect \`field.isRequired\`. The server validates too, but show \`required\` on the input for browser-level UX.
+- **Validation:** when \`field.validation.pattern\` is present, pass it as the input's \`pattern\` attribute; the server also enforces it. Likewise \`minLength\`/\`maxLength\`/\`min\`/\`max\`.
+- **Enum values:** SELECT and MULTI_SELECT always return \`enumValues\` (non-empty array). Render from \`enumValues\`, never a hardcoded list.
+- **Visibility:** the server strips fields with \`isVisible=false\`, so \`schema.fields\` only contains things to render.
+- **Origin check:** the endpoint validates \`Origin\` against the store's allowed origins. Test from your real storefront URL, not \`file://\` or localhost unless the merchant added it to allowed origins.
+- **Locale handling:** always pass \`locale\` to \`contactForms.get()\` and to \`createInquiry()\`. The staff inbox filters inquiries by language. Omit to fall back to the store's default language.
+- **Success message:** render \`schema.successMessage\` as-is. (Variable interpolation like \`{{customerName}}\` is not yet wired; any such placeholders currently render literally. Safe to use plain text.)
+- **Caching:** the schema GET is safe to cache per \`{storeId, formKey, locale}\`. 60 s feels live without hammering the API.
+
+### Multiple forms
+
+If the merchant set up more than one form (e.g. a \`main\` form on \`/contact\`
+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 getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -1647,6 +2141,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getDiscountsSection();
     case "recommendations":
       return getRecommendationsSection();
+    case "product-customization-fields":
+      return getProductCustomizationFieldsSection();
     case "tax":
       return getTaxDisplaySection(cur);
     case "i18n":
@@ -1657,6 +2153,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getTypeQuickReference();
     case "admin":
       return getAdminApiSection();
+    case "inquiries":
+      return getContactInquiriesSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -1721,6 +2219,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductCustomizationFieldsSection(),
+        "",
+        "---",
+        "",
         getTaxDisplaySection(cur),
         "",
         "---",
@@ -1729,10 +2231,14 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
-        getAdminApiSection()
+        getAdminApiSection(),
+        "",
+        "---",
+        "",
+        getContactInquiriesSection()
       ].join("\n");
     default:
-      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, tax, i18n, critical-rules, type-reference, admin, 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, all`;
   }
 }
 
@@ -1752,11 +2258,13 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "product-customization-fields",
     "tax",
     "critical-rules",
     "type-reference",
     "i18n",
     "admin",
+    "inquiries",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   connectionId: z.string().optional().describe("Vibe-coded connection ID (starts with vc_). Used to personalize setup code."),
@@ -1796,6 +2304,7 @@ interface Product {
   brands?: Array<{ id: string; name: string }>;
   tags?: string[];
   metafields?: ProductMetafield[];
+  customizationFields?: ProductCustomizationField[];  // Buyer input fields \u2014 render on PDP, send values in cart metadata. Account-wide fields (MetafieldDefinition.appliesToAllProducts=true) are folded in here automatically; no client-side merging.
   productAttributeOptions?: Array<{
     id: string;
     attributeId: string;
@@ -1854,6 +2363,32 @@ interface ProductMetafield {
   variantId?: string | null;
 }
 
+// Metafield type enum \u2014 used by ProductCustomizationField.type
+type MetafieldType =
+  | 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME'
+  | 'URL' | 'COLOR' | 'DIMENSION' | 'WEIGHT' | 'JSON'
+  | 'IMAGE' | 'GALLERY'
+  | 'SELECT' | 'MULTI_SELECT';
+
+// Customer-facing input assigned per product. Render on the PDP in the order of \`position\`.
+// Submit values keyed by \`key\` inside AddToCartDto.metadata.
+// Upload files via \`uploadCustomizationFile()\` first, then place the returned \`url\` in metadata.
+interface ProductCustomizationField {
+  definitionId: string;
+  name: string;                 // Label to show buyers
+  key: string;                  // Use as metadata key in AddToCartDto.metadata
+  description?: string | null;  // Help text
+  type: MetafieldType;
+  required: boolean;
+  minLength?: number | null;    // TEXT/TEXTAREA char bounds; MULTI_SELECT array bounds
+  maxLength?: number | null;
+  minValue?: number | null;     // NUMBER bounds
+  maxValue?: number | null;
+  enumValues?: string[];        // REQUIRED for SELECT / MULTI_SELECT
+  defaultValue?: string | null;
+  position: number;             // Render order
+}
+
 interface ProductQueryParams {
   page?: number;
   limit?: number;
@@ -1937,6 +2472,7 @@ interface CartItem {
     sku?: string | null;
     image?: ProductImage | string | null;
   } | null;
+  metadata?: Record<string, unknown> | null;  // Buyer-submitted customization values, keyed by ProductCustomizationField.key
   createdAt: string;
   updatedAt: string;
 }
@@ -2001,6 +2537,9 @@ interface Checkout {
   taxAmount: string;
   taxBreakdown?: TaxBreakdown | null;
   total: string;
+  surchargeAmount: string;
+  appliedSurcharges?: Array<{ key: string; name: string; value: unknown; amount: string }> | null;
+  customFieldValues?: Record<string, unknown> | null;
   couponCode?: string | null;
   lineItems: CheckoutLineItem[];  // Use THIS for order summary, NOT cart.items!
   itemCount: number;
@@ -2019,6 +2558,7 @@ interface CheckoutLineItem {
   discountAmount: string;
   product: { id: string; name: string; sku: string; images?: ProductImage[]; };
   variant?: { id: string; name?: string | null; sku?: string | null; image?: ProductImage | string | null; } | null;
+  metadata?: Record<string, unknown> | null;  // Copied from CartItem.metadata \u2014 buyer customization values
 }
 
 interface CheckoutAddress {
@@ -2100,6 +2640,27 @@ interface Order {
   billingAddress?: OrderAddress;
   hasDownloads?: boolean;
   createdAt: string;
+
+  // Payment + fulfillment
+  paymentMethod?: string | null;
+  financialStatus?: string | null;       // "pending" | "paid" | "refunded" | "partially_refunded" | "voided"
+  fulfillmentStatus?: string | null;     // "unfulfilled" | "partial" | "fulfilled"
+
+  // Tracking
+  trackingNumber?: string | null;
+  trackingUrl?: string | null;
+  carrier?: string | null;
+  shippedAt?: string | null;             // ISO-8601
+  deliveredAt?: string | null;           // ISO-8601
+
+  // Timeline of status transitions, chronological
+  statusHistory?: OrderStatusChange[] | null;
+}
+
+interface OrderStatusChange {
+  status: OrderStatus;
+  at: string;                            // ISO-8601
+  note?: string | null;
 }
 
 // \u26A0\uFE0F OrderItem is FLAT \u2014 unlike CartItem which is NESTED
@@ -2113,6 +2674,9 @@ interface OrderItem {
   unitPrice?: string;    // alias
   totalPrice?: string;
   image?: string;        // FLAT: item.image (NOT nested)
+  // 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 }>;
 }
 
 interface OrderCustomer {
@@ -2334,7 +2898,129 @@ interface ProductRecommendationsResponse {
 }
 interface CartRecommendationsResponse {
   recommendations: ProductRecommendation[];
+}
+
+// Cart include types (for consolidated getCart requests)
+type CartIncludeOption = 'recommendations' | 'upgrades' | 'bundles';
+interface CartIncludeOptions {
+  include?: CartIncludeOption[];
+}
+interface CartWithIncludes extends Cart {
+  recommendations?: { recommendations: ProductRecommendation[] };
+  upgrades?: { upgrades: Record<string, CartUpgradeSuggestion> };
+  bundles?: { bundles: CartBundleOffer[] };
+}
+interface CartUpgradeSuggestion {
+  targetProduct: ProductRecommendation;
+  priceDelta: string;
+  deltaPercent: number;
+}
+interface CartBundleOffer {
+  id: string;
+  bundleProduct: ProductRecommendation;
+  originalPrice: string;
+  discountedPrice: string;
+  discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
+  discountValue: number;
+  requiresVariantSelection: boolean;
+  lockedVariant?: { id: string; name?: string };
 }`;
+var INQUIRIES_TYPES = `// ---- Contact Inquiries & Forms ----
+
+// Two shapes \u2014 legacy and flexible. The two may be mixed; \`fields\` wins on key collision.
+interface CreateInquiryInput {
+  // Legacy shape (still supported forever, backed by default "main" form)
+  name?: string;                                // max 120 chars (if provided)
+  email?: string;                               // must be valid email if provided
+  subject?: string;                             // max 200 chars
+  message?: string;                             // max 10000 chars
+  phone?: string;
+
+  // Flexible shape
+  formKey?: string;                             // defaults to "main"; merchant-defined keys e.g. "newsletter"
+  fields?: Record<string, unknown>;             // bag of values keyed by field key (built-in or custom)
+  locale?: string;                              // e.g. "en", "he" \u2014 stored on the inquiry
+  sourceMetadata?: Record<string, unknown>;     // arbitrary context (e.g. { page: '/contact', campaign: 'fall-2026' })
+
+  // Shared
+  customerId?: string;                          // link to logged-in customer
+  metadata?: Record<string, unknown>;           // deprecated alias of sourceMetadata
+}
+
+interface CreateInquiryResponse {
+  id: string;
+  status: 'NEW';
+  createdAt: string;                            // ISO datetime
+}
+
+// ---- Form schema (for dynamic rendering) ----
+
+type ContactFormFieldType =
+  | 'TEXT' | 'TEXTAREA' | 'EMAIL' | 'PHONE' | 'NUMBER'
+  | 'SELECT' | 'MULTI_SELECT' | 'CHECKBOX' | 'URL' | 'DATE';
+
+interface ContactFormFieldValidation {
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  pattern?: string;                             // regex string
+  patternMessage?: string;
+}
+
+interface ContactFormPublicField {
+  key: string;                                  // stable identifier, e.g. "email", "company"
+  type: ContactFormFieldType;
+  label: string;                                // already localized for the requested locale
+  placeholder?: string;                         // already localized
+  helpText?: string;                            // already localized
+  isRequired: boolean;
+  enumValues?: { value: string; label: string }[]; // present (non-empty) for SELECT / MULTI_SELECT
+  validation?: ContactFormFieldValidation;
+  defaultValue?: string;
+}
+
+interface ContactFormPublic {
+  id: string;
+  key: string;                                  // e.g. "main", "newsletter"
+  name: string;                                 // already localized \u2014 use as form heading
+  description?: string;                         // already localized \u2014 use as subtitle
+  submitButton: string;                         // already localized \u2014 use as submit label
+  successMessage: string;                       // already localized \u2014 render after submit succeeds
+  fields: ContactFormPublicField[];             // in display order; hidden fields already filtered out
+}
+
+interface ContactFormSummary {
+  key: string;
+  name: string;
+  isDefault: boolean;
+}
+
+// Field-type \u2192 HTML mapping for dynamic rendering
+// ------------------------------------------------------------------
+//   TEXT          \u2192 <input type="text" ... pattern?={validation.pattern}>
+//   TEXTAREA      \u2192 <textarea rows={6} ...>
+//   EMAIL         \u2192 <input type="email" autoComplete="email" ...>
+//   PHONE         \u2192 <input type="tel" autoComplete="tel" ...>
+//   NUMBER        \u2192 <input type="number" min={validation.min} max={validation.max}>
+//   URL           \u2192 <input type="url" ...>
+//   DATE          \u2192 <input type="date" ...>  (value is ISO yyyy-MM-dd)
+//   SELECT        \u2192 <select>{enumValues.map(...)}</select>  \u2014 always rendered from enumValues
+//   MULTI_SELECT  \u2192 multiple <input type="checkbox">, value is string[]
+//   CHECKBOX      \u2192 single <input type="checkbox">, value is boolean
+// ------------------------------------------------------------------
+
+// SDK methods
+//   await brainerce.createInquiry(input)              \u2192 POST /stores/{storeId}/inquiries
+//   await brainerce.contactForms.list()               \u2192 GET  /stores/{storeId}/contact-forms
+//   await brainerce.contactForms.get(key?, locale?)   \u2192 GET  /stores/{storeId}/contact-forms/{key}?locale={locale}
+//
+// Rules
+// - Rate limit: 3 submissions / 60s per IP \u2014 handle 429 responses gracefully
+// - Honeypot: always render an invisible field named \`honeypot\` and never send it
+// - Always pass \`locale\` \u2014 inbox filters inquiries by language, and schema labels come back translated
+// - Render \`schema.name\` / \`description\` / \`submitButton\` / \`successMessage\` directly \u2014 do NOT hardcode copy
+// - Unknown field keys are stripped server-side \u2014 safe to send extras during dev`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -2342,7 +3028,8 @@ var TYPES_BY_DOMAIN = {
   orders: ORDERS_TYPES,
   customers: CUSTOMERS_TYPES,
   payments: PAYMENTS_TYPES,
-  helpers: HELPERS_TYPES
+  helpers: HELPERS_TYPES,
+  inquiries: INQUIRIES_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -2363,7 +3050,17 @@ var AVAILABLE_DOMAINS = Object.keys(TYPES_BY_DOMAIN);
 var GET_TYPE_DEFINITIONS_NAME = "get-type-definitions";
 var GET_TYPE_DEFINITIONS_DESCRIPTION = "Get TypeScript type definitions from the Brainerce SDK, segmented by domain. Use this when you need to understand the exact shape of objects like Product, Cart, Checkout, Order, etc.";
 var GET_TYPE_DEFINITIONS_SCHEMA = {
-  domain: z2.enum(["products", "cart", "checkout", "orders", "customers", "payments", "helpers", "all"]).describe(
+  domain: z2.enum([
+    "products",
+    "cart",
+    "checkout",
+    "orders",
+    "customers",
+    "payments",
+    "helpers",
+    "inquiries",
+    "all"
+  ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse.'
   )
 };
@@ -2397,7 +3094,8 @@ var GET_CODE_EXAMPLE_SCHEMA = {
     "coupon-apply-and-remove",
     "reservation-countdown",
     "search-autocomplete-debounce",
-    "i18n-set-locale"
+    "i18n-set-locale",
+    "order-history-full"
   ]).describe("The SDK operation to get a snippet for.")
 };
 var SNIPPETS = {
@@ -2492,23 +3190,51 @@ const checkout = await client.getCheckout(checkoutId);
   "checkout-payment-providers": `// Fetch configured payment providers for this checkout.
 import { client } from './brainerce';
 
-const providers = await client.getPaymentProviders(checkoutId);
-// providers = [{ provider, name, renderType, config }, ...]
-// renderType tells you how to render:
-//   'stripe-elements' \u2014 render Stripe Elements form and call stripe.confirmCardPayment
-//   'redirect'         \u2014 render a button that navigates to provider.authorizationUrl
-//   'paypal'           \u2014 render PayPal SDK button
-//   'sandbox'          \u2014 render a "complete test order" button (no real charge)
-
-// Pick the first configured provider by default (or let the user pick if
-// multiple are configured).
-const active = providers[0];
+const { providers, hasPayments, defaultProvider } = await client.getPaymentProviders();
+// each provider: { id, provider, name, publicKey, supportedMethods, testMode, isDefault, clientSdk? }
+//
+// After createPaymentIntent, the response carries a clientSdk.renderType that
+// tells your UI how to render the payment step. The 5 possible values:
+//
+//   'sdk-widget'       \u2014 Load the provider's JS SDK (scriptUrl), then mount
+//                        into a <div id={containerId}>. Used by Stripe,
+//                        PayPal, Grow. The SDK paints its own form inside
+//                        your DOM. You control layout/placement.
+//
+//   'iframe'           \u2014 Render <iframe src={clientSecret}>. Two flavors:
+//                          a) URL path contains "/embed/" \u2192 Brainerce-hosted
+//                             embed page. Render INLINE in your checkout
+//                             flow. Listen for postMessage:
+//                             - 'brainerce:resize' \u2192 update iframe height
+//                             - 'brainerce:redirect' \u2192 validated top-level
+//                               navigation (e.g. Bit express-pay)
+//                          b) Any other URL \u2192 provider-hosted page. Render
+//                             inside a modal overlay (it carries its own
+//                             branding/chrome).
+//
+//   'redirect'         \u2014 Full-page navigate: window.location.href = URL.
+//                        Customer leaves your site, pays on provider page,
+//                        returns via SuccessRedirectUrl.
+//
+//   'sandbox'          \u2014 Test mode. Render a "Complete Test Order" button;
+//                        call completeGuestCheckout(checkoutId). Orders are
+//                        flagged isTestOrder: true. No real charge.
+//
+//   'embedded-fields'  \u2014 (Reserved \u2014 not yet shipped in any provider.) PCI
+//                        micro-iframes for sensitive fields (card number,
+//                        CVV) mounted directly into the merchant form. Full
+//                        control of surrounding layout, like Stripe
+//                        Elements. Requires the provider to ship a client
+//                        SDK that exposes mount points.
+//
+// Always branch on clientSdk.renderType \u2014 NEVER hard-code by provider name.
+// New providers can be added without storefront changes.
 
-// If providers is empty, NO payment provider is configured and customers
-// cannot pay. Display a clear error \u2014 do not try to fake a checkout.
 if (providers.length === 0) {
   throw new Error('No payment provider configured for this store');
-}`,
+}
+
+const active = providers[0];`,
   "checkout-stripe-confirm": `// Stripe confirm flow. Requires @stripe/stripe-js and @stripe/react-stripe-js
 // (or the vanilla Stripe.js browser SDK).
 import { loadStripe } from '@stripe/stripe-js';
@@ -2722,12 +3448,82 @@ const locale = 'he'; // e.g., from the /[locale] route segment
 client.setLocale(locale);
 
 // ALL content comes back translated: products, categories, brands,
-// tags, variants, metafields, cart items, checkout line items,
-// recommendations, search suggestions, discount banners, nudges,
+// tags, variants (name + attributes keys/values), metafields,
+// cart items, checkout line items, recommendations, bundles,
+// 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');`
+// Framework-neutral: document.documentElement.setAttribute('dir', 'rtl');`,
+  "order-history-full": `// Full "My Orders" account page. Render every piece of data the server
+// already returns \u2014 not just order number / total / status.
+//
+// Data you get from client.getMyOrders() (already on the wire today):
+//   - items[].customizations          \u2014 buyer's custom-field entries
+//   - statusHistory                   \u2014 status timeline
+//   - shippingAddress                 \u2014 name + address lines + country
+//   - trackingNumber / trackingUrl / carrier / shippedAt / deliveredAt
+//   - paymentMethod / financialStatus / fulfillmentStatus
+//   - appliedDiscounts                \u2014 shaped buyer-facing view
+//   - hasDownloads                    \u2014 call /orders/:id/downloads to fetch
+//
+// Do NOT render: accountId, storeId, customerId, notes, customFieldValues
+// (merchant-internal, order-level), appliedRuleIds, appliedSurcharges,
+// surchargeAmount, downloadMeta (raw), pickupLocationData. The backend
+// does not return these to buyers \u2014 if you see them in a type, they're
+// an oversight; still skip them.
+import { client } from './brainerce';
+import type { Order, OrderItem, OrderStatusChange } from 'brainerce';
+
+const { data: orders } = await client.getMyOrders({ page: 1, limit: 10 });
+
+for (const order of orders) {
+  // Line items + per-item customizations
+  for (const item of order.items) {
+    // item.image, item.productName, item.quantity, item.price
+    if (item.customizations) {
+      for (const [fieldId, entry] of Object.entries(item.customizations)) {
+        // entry = { label, value, type }
+        // Type-aware render (see account-page section in get-sdk-docs):
+        //   TEXT / TEXTAREA / URL / NUMBER / SELECT        \u2014 plain text
+        //   BOOLEAN                                         \u2014 \u2713 / \u2717
+        //   MULTI_SELECT                                    \u2014 comma-separated
+        //   IMAGE                                           \u2014 <img src={value}>
+        //   GALLERY                                         \u2014 wrap grid of <img>
+        //   COLOR                                           \u2014 swatch + hex
+        //   DATE / DATETIME                                 \u2014 localized format
+      }
+    }
+  }
+
+  // Status timeline \u2014 skip silently when null/empty
+  if (order.statusHistory?.length) {
+    for (const entry of order.statusHistory as OrderStatusChange[]) {
+      // entry = { status, at, note? }
+      // Render a dot + localized status label + new Date(entry.at).toLocaleString()
+    }
+  }
+
+  // Shipping + tracking
+  if (order.shippingAddress) {
+    // Render firstName lastName \xB7 line1 \xB7 line2 \xB7 city, region \xB7 postalCode \xB7 country
+  }
+  if (order.trackingNumber) {
+    // Render carrier \xB7 trackingNumber, shippedAt/deliveredAt dates,
+    // and an anchor to order.trackingUrl when present.
+  }
+
+  // Payment
+  if (order.paymentMethod || order.financialStatus) {
+    // paymentMethod: 'card' | 'paypal' | 'bank_transfer' | 'cash_on_delivery' | ...
+    // financialStatus: 'pending' | 'paid' | 'refunded' | 'partially_refunded' | 'voided'
+    // Map financialStatus \u2192 a colored badge.
+  }
+}
+
+// All sections above are conditional. Absent data = section not rendered \u2014
+// never show empty placeholders. The create-brainerce-store template's
+// src/components/account/order-history.tsx is the reference implementation.`
 };
 async function handleGetCodeExample(args) {
   const snippet = SNIPPETS[args.operation];
@@ -3193,7 +3989,7 @@ var RULES = {
 - All prices are STRINGS in the SDK. \`parseFloat\` them before math or comparisons.
 - CartItem and CheckoutLineItem are NESTED (\`item.product.name\`, \`item.unitPrice\`). OrderItem is FLAT (\`item.name\`, \`item.price\`). They are not interchangeable.
 - Cart has no \`.total\` field \u2014 call \`getCartTotals(cart)\` to get \`{ subtotal, tax, shipping, discount, total }\`.
-- \`smartGetCart()\` returns a discriminated union (\`Cart | LocalCart\`). Check \`'id' in cart\` before using server-only fields.
+- \`smartGetCart()\` returns \`CartWithIncludes\` (extends \`Cart\`). Pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` to fetch extras in one request.
 - \`startGuestCheckout()\` is also a discriminated union. Check \`result.tracked\` before reading \`result.checkoutId\`.`
   }
 };
@@ -3231,6 +4027,7 @@ var GET_BUSINESS_FLOWS_SCHEMA = {
     "order-confirmation",
     "cart-persistence",
     "inventory-reservation",
+    "product-customization",
     "all"
   ]).describe('Which flow to retrieve. Use "all" to get every flow.')
 };
@@ -3350,7 +4147,7 @@ Build the OAuth button region AND the callback handler even when no providers ar
 - **Reads:** \`client.getCart()\` returns the current cart. Call it on mount in your cart UI and on any page that shows a cart count (header).
 - **Writes:** use \`client.addToCart\`, \`client.updateCartItem\`, \`client.removeCartItem\`, \`client.applyCoupon\`, \`client.removeCoupon\`. After each mutation the SDK returns the updated cart.
 - **Totals:** call \`getCartTotals(cart)\` \u2014 do NOT read \`cart.total\`. The helper understands taxes, shipping, and discounts.
-- **\`smartGetCart()\`** returns \`Cart | LocalCart\` (guest users have no server cart until they add an item). Check \`'id' in cart\` before using server-only fields.
+- **\`smartGetCart()\`** returns \`CartWithIncludes\` (extends \`Cart\`). All carts are server-side. Pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` to fetch extras in one request.
 - **NEVER mutate cart state outside SDK helpers.** Any hand-rolled cart update risks desync with the reservation timer and the checkout flow.`
   },
   "inventory-reservation": {
@@ -3364,6 +4161,54 @@ Build the OAuth button region AND the callback handler even when no providers ar
 - **On the cart page:** show per-item availability \u2014 items that can no longer be purchased (because their reservation expired or the stock dropped) should display an "out of stock" badge and the "proceed to checkout" action should be disabled until they are removed.
 
 The reservation strategy (\`HARD\` vs \`SOFT\`) is exposed via \`get-store-capabilities\`. A HARD reservation means the stock is physically held; a SOFT reservation just tracks intent. Your UI behaves identically either way \u2014 the SDK hides the difference.`
+  },
+  "product-customization": {
+    title: "Product customization (buyer input)",
+    body: `Products can ship with \`customizationFields: ProductCustomizationField[]\` \u2014 buyer-filled inputs (engraving text, uploaded photo, pick-a-color, etc.). If you ignore them, merchants lose the data they need to fulfill the order.
+
+1. **Read the fields** from the product payload. Sort by \`position\`. If the array is empty, nothing to render.
+2. **Render one control per field** based on \`type\`:
+   - \`TEXT\` / \`URL\` / \`COLOR\` / \`DIMENSION\` / \`WEIGHT\` \u2192 \`<input type="text">\` (honour \`minLength\`/\`maxLength\`)
+   - \`TEXTAREA\` \u2192 \`<textarea>\`
+   - \`NUMBER\` \u2192 \`<input type="number">\` (honour \`minValue\`/\`maxValue\`)
+   - \`BOOLEAN\` \u2192 checkbox (value \`true\`/\`false\`)
+   - \`DATE\` \u2192 \`<input type="date">\` (ISO \`YYYY-MM-DD\`)
+   - \`DATETIME\` \u2192 \`<input type="datetime-local">\` (ISO timestamp)
+   - \`SELECT\` \u2192 \`<select>\` populated from \`enumValues\` (value = one string)
+   - \`MULTI_SELECT\` \u2192 checkbox group from \`enumValues\` (value = \`string[]\`)
+   - \`IMAGE\` \u2192 file input + preview (value = one URL string)
+   - \`GALLERY\` \u2192 multi-file input (value = \`string[]\` of URLs)
+   - \`JSON\` \u2192 advanced; render an admin-style editor or skip unless you control the data
+3. **For IMAGE / GALLERY types: upload FIRST, then attach the URL.** Call \`client.uploadCustomizationFile(file)\` \u2014 it returns \`{ url }\`. Put that \`url\` string into the field value. NEVER put a \`File\` object in cart metadata.
+4. **Enforce \`required: true\` client-side** before add-to-cart \u2014 show a red hint, block submit. The server re-validates; you want the user to fix it before the request fails.
+5. **Add to cart with metadata keyed by \`field.key\`:**
+   \`\`\`ts
+   await client.addToCart({
+     productId,
+     quantity: 1,
+     metadata: {
+       engraving_text: 'For Mom',
+       frame_color: 'Gold',
+       upload_photo: photoUrl,      // from uploadCustomizationFile()
+       addons: ['Gift wrap'],       // MULTI_SELECT
+     },
+   });
+   \`\`\`
+6. **On cart / checkout UIs, surface the metadata.** \`CartItem.metadata\` and \`CheckoutLineItem.metadata\` carry the values the buyer submitted. Show them in the line-item row so the buyer can verify before paying (especially uploaded image thumbnails).
+7. **After the order is placed, values live on \`OrderItem.customizations\`** \u2014 a \`Record<string, { label, value, type }>\` keyed by field key. Definitions may be renamed/deleted after the order; the snapshot preserves what the buyer saw at purchase time.
+
+**Apply-to-all fields.** A merchant can flag a \`MetafieldDefinition\` with \`appliesToAllProducts: true\` \u2014 the backend then includes it in every product's \`customizationFields\` array automatically, including products created after the flag was set. Your client code reads \`product.customizationFields\` as-is and never merges or unions anything \u2014 just render what's there.
+
+Server-side guardrails that WILL reject bad requests (so validate client-side to avoid round-trips):
+- Unknown keys \u2192 rejected. Only use keys that appear in \`product.customizationFields\`.
+- Missing \`required\` fields \u2192 rejected.
+- \`SELECT\` value not in \`enumValues\` \u2192 rejected.
+- \`MULTI_SELECT\` value not \`string[]\` OR containing values outside \`enumValues\` \u2192 rejected.
+- \`IMAGE\` / \`GALLERY\` values must be URLs returned from \`/customization-upload\` on this store \u2014 pasting an external URL is rejected.
+- Upload > 5MB or non-image MIME \u2192 rejected by upload endpoint.
+- 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.`
   }
 };
 var FLOW_ORDER = [
@@ -3374,7 +4219,8 @@ var FLOW_ORDER = [
   "oauth",
   "order-confirmation",
   "cart-persistence",
-  "inventory-reservation"
+  "inventory-reservation",
+  "product-customization"
 ];
 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.";
@@ -3439,6 +4285,14 @@ var FEATURES = [
     sdk: "client.getProductBySlug(slug). Helpers: getProductPriceInfo, getVariantPrice, getStockStatus, getVariantOptions, getProductSwatches, getDescriptionContent, getProductMetafieldValue.",
     mandatory: "mandatory"
   },
+  {
+    id: "product-customization-fields",
+    title: "Render buyer-input customization fields on the product page",
+    description: "When a product ships with `customizationFields` (engraving text, uploaded photo, picked color, date, select / multi-select), render one control per field sorted by `position`. Enforce required + enumValues + min/max client-side. For IMAGE / GALLERY, upload via client.uploadCustomizationFile() and place the returned URL in the value. Submit all values keyed by `field.key` inside addToCart({ metadata }). Show the metadata on cart / checkout rows so the buyer can verify. Build the UI anyway \u2014 it auto-hides when a product has no customization fields. NOTE: merchants can flag a definition with `appliesToAllProducts: true`; the backend folds those into every product's `customizationFields` array automatically \u2014 the client never merges or unions anything, just reads `product.customizationFields` as-is.",
+    sdk: "product.customizationFields, client.uploadCustomizationFile(file), client.addToCart({ productId, quantity, metadata })",
+    flowRef: "product-customization",
+    mandatory: "mandatory"
+  },
   {
     id: "cart",
     title: "Manage a cart with quantity, removal, and totals",