@brainerce/mcp-server 3.2.0 → 3.4.0

package/dist/index.js

@@ -1888,6 +1888,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";
@@ -1926,6 +2185,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",
@@ -2002,10 +2263,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, product-customization-fields, 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`;
   }
 }
 
@@ -2031,6 +2296,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "type-reference",
     "i18n",
     "admin",
+    "inquiries",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   connectionId: import_zod.z.string().optional().describe("Vibe-coded connection ID (starts with vc_). Used to personalize setup code."),
@@ -2691,6 +2957,102 @@ interface CartBundleOffer {
   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,
@@ -2698,7 +3060,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") {
@@ -2719,7 +3082,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: import_zod2.z.enum(["products", "cart", "checkout", "orders", "customers", "payments", "helpers", "all"]).describe(
+  domain: import_zod2.z.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.'
   )
 };