@unboundcx/sdk 4.5.0 → 4.6.1

package/README.md

@@ -14,6 +14,7 @@ The official JavaScript SDK for Unbound's comprehensive communication and AI pla
 - 🤖 **AI**: Generative AI chat, text-to-speech, and speech-to-text
 - 💾 **Data**: Object management with queries and relationships
 - 🔄 **Workflows**: Programmable workflow execution
+- 📄 **Documents**: Templates → PDF (`api.documents`); fax is a consumer, not the owner
 - 🔌 **Extensible**: Plugin system for transports and extensions
 - ⚡ **Performance**: Automatic transport optimization (NATS/Socket/HTTP)
 
@@ -174,6 +175,41 @@ await api.objects.updateById('contacts', 'contact-123', { name: 'Jane' });
 await api.objects.deleteById('contacts', 'contact-123');
 await api.objects.describe('contacts'); // Get schema
 await api.objects.list(); // List all object types
+
+// Skip trigger execution on a write (imports / bulk tools)
+await api.objects.updateById({
+  object: 'people',
+  id: '013…',
+  update: { leadScore: 200 },
+  skipTriggers: true,
+});
+```
+
+#### Triggers (`api.triggers`)
+
+```javascript
+await api.triggers.listObjects();
+await api.triggers.list({ objectName: 'people', status: 'enabled' });
+await api.triggers.create({
+  name: 'Hot lead',
+  objectName: 'people',
+  actions: ['update'],
+  recordFilter: { type: { op: 'eq', value: 'lead' } },
+  changeFilters: [
+    {
+      field: 'leadScore',
+      previous: { op: 'lt', value: 20 },
+      updated: { op: 'gt', value: 100 },
+    },
+  ],
+  actionType: 'workflow',
+  actionConfig: { workflowVersionId: '052…' },
+});
+await api.triggers.get('173…');
+await api.triggers.update('173…', { status: 'paused' });
+await api.triggers.setStatus('173…', 'enabled');
+await api.triggers.listFires('173…', { limit: 20 });
+await api.triggers.delete('173…');
 ```
 
 #### Live Queries (`api.objects.liveQuery`)
@@ -408,6 +444,45 @@ const fileUrl = api.storage.getFileUrl(files[0].storageId);
 await api.storage.deleteFile(files[0].storageId);
 ```
 
+#### Documents (`api.documents`)
+
+Generic templates → PDF. Implementation: `services/documents.js`.
+`this.documents = new DocumentsService(this)`.
+
+```javascript
+const created = await api.documents.templates.create({
+  name: 'Fax cover',
+  engine: 'generative', // or 'overlay' + sourcePdfStorageId
+  uses: ['fax'], // omit / [] = every surface
+});
+await api.documents.templates.list({ status: 'published', use: 'fax' });
+await api.documents.templates.update(created.id, { draftSchemaJson, draftLayoutJson });
+await api.documents.templates.publish(created.id);
+
+const doc = await api.documents.generate({
+  templateId: created.id,
+  data: { fromCompany: 'Acme', subject: 'Hello' },
+});
+// { id, storageId, pageCount, pageSize }
+
+await api.fax.send({
+  faxMailboxId,
+  toNumber,
+  fromNumber,
+  storageId: doc.storageId,
+  coverStorageId, // optional; API concatenates cover then body
+  paperSize: doc.pageSize,
+});
+
+const pages = await api.documents.inspect({ storageId: doc.storageId });
+```
+
+There is no `api.fax.generateFromTemplate`. Preview: `api.documents.preview({ templateId, data })`.
+
+Published SDK versions older than this branch may not have `documents` or
+`fax.send({ coverStorageId })`. The client falls back to `_fetch('/documents/…')`
+and `_fetch('/fax/send')`.
+
 #### Workflows (`api.workflows`)
 
 ```javascript

package/index.js

@@ -27,7 +27,9 @@ import { EngagementMetricsService } from './services/engagementMetrics.js';
 import { TaskRouterService } from './services/taskRouter.js';
 import { KnowledgeBaseService } from './services/knowledgeBase.js';
 import { FaxService } from './services/fax.js';
+import { DocumentsService } from './services/documents.js';
 import { PermissionsService } from './services/permissions.js';
+import { TriggersService } from './services/triggers.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -96,7 +98,9 @@ class UnboundSDK extends BaseSDK {
     this.taskRouter = new TaskRouterService(this);
     this.knowledgeBase = new KnowledgeBaseService(this);
     this.fax = new FaxService(this);
+    this.documents = new DocumentsService(this);
     this.permissions = new PermissionsService(this);
+    this.triggers = new TriggersService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
   "main": "index.js",
   "type": "module",
@@ -61,6 +61,9 @@
     "./schemas/layouts": {
       "import": "./schemas/layouts/index.js"
     },
+    "./schemas/workflows": {
+      "import": "./schemas/workflows/index.js"
+    },
     "./schemas/*": {
       "import": "./schemas/*.js"
     }

package/schemas/workflows/capabilities.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+
+// Replaces the ad hoc mechanisms cataloged in design-schema-first.md §2
+// (hardcoded `type === 'sendEmail'`/`type === 'sayIntent'` branches in
+// `update/workflowItemSettings.js`, the separate hand-synced
+// DATA_PRODUCER_TYPES registry, the redundant simulate+button dual
+// mechanism, the dead `fieldType:'timeControl'` marker) with declared flags
+// on the module itself. The whole `capabilities` object is OPTIONAL on
+// ModuleSpec — absent means "legacy inferred behavior": every
+// currently-shipping module keeps working exactly as today with zero flags
+// set (design-incremental-risk.md §2's additive constraint). Execution
+// (actually wiring these flags into the backend cascades) is explicitly
+// out of scope for this phase — declaring the flag is authoring-time only.
+
+const DynamicPortSyncSpec = z.object({
+  triggerField: z.string().min(1),
+  portId: z.string().min(1),
+});
+
+const SpawnsChildItemsSpec = z.object({
+  arrayField: z.string().min(1),
+  childType: z.string().min(1),
+  parentLinkField: z.string().min(1),
+});
+
+const DataProducerSpec = z.object({
+  fieldsResolverKey: z.string().min(1),
+});
+
+// Unifies the redundant dual mechanism found live in lookup.js/webHook.js/
+// timeControl.js — a top-level `simulate:{enabled,endpoint}` block *and* a
+// `fieldType:'button', button:{action:'simulate', settingsFields:[...]}`
+// layout control, both present for the same "Run Test" feature in the same
+// file — into one declared shape.
+const SimulatableSpec = z.object({
+  endpoint: z.string().min(1),
+  settingsFields: z.array(z.string()).default([]),
+});
+
+// Formalizes the escape hatch scriptPage.js/timeControl.js already use ad
+// hoc via string-match on `module.type` in EditPanel.svelte — the panel
+// looks THIS up going forward, never string-matches `type` again.
+const CustomEditorSpec = z.object({
+  componentKey: z.string().min(1),
+});
+
+export const CapabilitiesSpec = z.object({
+  deletable: z.boolean().default(true),               // replaces isDeletable
+  hiddenFromPicker: z.boolean().default(false),        // replaces isHiddenFromList
+  dynamicPorts: z.array(DynamicPortSyncSpec).nullable().default(null),
+  spawnsChildItems: SpawnsChildItemsSpec.nullable().default(null),
+  outputVariables: z.array(z.string()).default([]),               // was outputVariableFields
+  excludedFromVariableExtraction: z.array(z.string()).default([]), // was excludeKeysFromVariableExtraction
+  dataProducer: DataProducerSpec.nullable().default(null),         // kills DATA_PRODUCER_TYPES as a separate file
+  simulatable: SimulatableSpec.nullable().default(null),
+  customEditor: CustomEditorSpec.nullable().default(null),
+}).passthrough();

package/schemas/workflows/editEntry.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+// Every fieldType literal observed across constants/workflows/*.js
+// (verified via grep against all 29 files, not the idealized §2 list).
+// Exported as a plain const rather than baked into a closed zod enum so
+// validateModuleSpec stays permissive of any future fieldType a module
+// author adds — lint.js is where "is this fieldType one we actually
+// render" opinions live (e.g. rejecting 'switch').
+export const KNOWN_FIELD_TYPES = [
+  'input', 'select', 'selectDynamic', 'textArea', 'code', 'codeEditor',
+  'checkbox', 'switch', 'button', 'routingPicker', 'timeControl', 'spacer',
+];
+
+const ButtonSpec = z.object({
+  label: z.string().optional(),
+  icon: z.string().optional(),
+  style: z.string().optional(),
+  action: z.string().optional(),
+  modalTitle: z.string().optional(),
+  settingsFields: z.array(z.string()).optional(),
+}).passthrough();
+
+// select/selectDynamic config kept open (record) rather than a closed
+// shape: static `{options:[{name,value}]}` and dynamic
+// `{url,response,clearable,searchable,fetchOptions,...}` forms coexist
+// per-field, plus module-specific extras (lookup.js's
+// describeObject/dependsOn cascade, sendEmail.js's `{{settings.x}}`
+// templated `url`, webHook.js's `display.relatedObject`/`relatedKey`
+// divergence). Structural typing of this shape is deliberately deferred —
+// same call the layouts schema package made for `componentConfig`.
+const SelectConfigSpec = z.record(z.unknown());
+
+// `edit[].field` is the one contract this whole package must never change
+// the shape of: it is the exact dotted/bracketed JSON-path string the
+// JSON_SET-style query builder in
+// app1-api/.../customHandlers/update/workflowItemSettings.js consumes
+// (`settings.<ns>.*` / `phone.*` / `messaging.*`, 'delete' array sentinel).
+// This schema shape-checks it (non-empty string) and never parses/rewrites
+// it.
+export const EditEntrySpec = z.object({
+  field: z.string().min(1),
+  label: z.string().optional(),
+  helpText: z.string().optional(),
+  required: z.boolean().optional(),
+  placeholder: z.string().optional(),
+  fieldType: z.string().min(1),
+  fieldTypeSub: z.string().optional(),
+  value: z.string().optional(),
+  format: z.string().optional(),
+  select: SelectConfigSpec.optional(),
+  textArea: z.record(z.unknown()).optional(),
+  code: z.record(z.unknown()).optional(),
+  codeEditor: z.record(z.unknown()).optional(),
+  button: ButtonSpec.optional(),
+  routingPicker: z.record(z.unknown()).optional(),
+  variableSources: z.array(z.unknown()).optional(),
+  templateIdField: z.string().optional(),
+  emojiPicker: z.boolean().optional(),
+}).passthrough();

package/schemas/workflows/index.js

@@ -0,0 +1,9 @@
+export * from './primitives.js';
+export * from './port.js';
+export * from './capabilities.js';
+export * from './editEntry.js';
+export * from './layout.js';
+export * from './settingsSchema.js';
+export * from './moduleSpec.js';
+export { validateModuleSpec } from './validate.js';
+export { lintModuleSpec } from './lint.js';

package/schemas/workflows/layout.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { HeaderSpec } from '../layouts/primitives.js';
+import { Conditional, InfoSpec, RepeatingSpec } from './primitives.js';
+import { EditEntrySpec } from './editEntry.js';
+
+// Column display metadata — the read-only mirror of an edit entry. `value`
+// is the dotted/bracketed path read for display; it may intentionally
+// diverge from `edit.field` (webHook.js's `relatedObject`/`relatedKey`
+// pattern, maps.md module-defs §3 — a legitimate divergence, contrast with
+// the buggy field/default mismatches lint.js catches).
+const FieldDisplaySpec = z.object({
+  type: z.string().optional(),
+  label: z.string().optional(),
+  value: z.string().optional(),
+  format: z.string().optional(),
+  fieldType: z.string().optional(),
+  relatedObject: z.string().optional(),
+  relatedKey: z.string().optional(),
+}).passthrough();
+
+export const ModuleColumn = z.object({
+  type: z.string().optional(),
+  object: z.enum(['workflowItems', 'workflowItemSettings']).optional(),
+  conditional: Conditional.optional(),
+  display: FieldDisplaySpec.optional(),
+  // array form = composite/multi-field column (sendEmail.js's conditional
+  // Value columns switching on templateVariables[].type, scriptPage.js's
+  // Row 2 richText/text type-switch)
+  edit: z.union([EditEntrySpec, z.array(EditEntrySpec)]).optional(),
+}).passthrough();
+
+export const ModuleRow = z.object({
+  // row-level repeating exists (bot.js dataCollectionFields) alongside
+  // section-level repeating — both forms seen live, modeled independently
+  // rather than assuming one supersedes the other.
+  repeating: RepeatingSpec.optional(),
+  columns: z.array(ModuleColumn).default([]),
+}).passthrough();
+
+// `label` (plain section header text) and `tabLabel` (groups this section
+// under a tab whose anchor is an earlier section's own id/label string
+// match) are two distinct, coexisting mechanisms — maps.md module-defs §3's
+// "tabbing model is inconsistent and undeclared as a concept" finding.
+// Both modeled as-is; unifying them into one first-class `tabs` concept is
+// out of scope for this schema pass (tracked in design-schema-first.md §3).
+export const ModuleSection = z.object({
+  id: z.string().min(1),
+  label: z.string().optional(),
+  tabLabel: z.string().optional(),
+  header: HeaderSpec.partial().optional(),
+  conditional: Conditional.optional(),
+  info: InfoSpec.optional(),
+  repeating: RepeatingSpec.optional(),
+  showCollapse: z.boolean().optional(),
+  autoCollapse: z.boolean().optional(),
+  rows: z.array(ModuleRow).default([]),
+}).passthrough();
+
+export const ModuleLayoutSpec = z.object({
+  sections: z.array(ModuleSection).default([]),
+}).passthrough();

package/schemas/workflows/lint.js

@@ -0,0 +1,89 @@
+// Extra, opinionated authoring rules beyond structural validity
+// (validate.js). These are the checks design-schema-first.md §2 argues
+// "would have caught every authoring bug found in the audit at commit
+// time" — run them in CI against every module constants file, not just at
+// runtime.
+
+// Walks settings.layout.sections -> rows -> columns -> edit (single or
+// array form) and returns a flat list of {entry, path} for every edit
+// entry declared, regardless of nesting depth. Repeating sections/rows
+// (their `field`/`edit.field` strings containing literal `{{index}}`) walk
+// the same as any other row — the lint rules below operate on the string
+// shape, not on resolved values.
+function collectEditEntries(spec) {
+  const entries = [];
+  const sections = spec?.settings?.layout?.sections || [];
+  sections.forEach((section, sIdx) => {
+    (section.rows || []).forEach((row, rIdx) => {
+      (row.columns || []).forEach((column, cIdx) => {
+        const edit = column.edit;
+        if (!edit) return;
+        const isArray = Array.isArray(edit);
+        const list = isArray ? edit : [edit];
+        list.forEach((entry, eIdx) => {
+          const editPath = isArray ? `edit[${eIdx}]` : 'edit';
+          entries.push({
+            entry,
+            path: `settings.layout.sections[${sIdx}].rows[${rIdx}].columns[${cIdx}].${editPath}`,
+          });
+        });
+      });
+    });
+  });
+  return entries;
+}
+
+export function lintModuleSpec(spec) {
+  const errors = [];
+  const entries = collectEditEntries(spec);
+
+  // Rule: category must be provided. The registry cross-check (does this
+  // category match workflows.js's grouping) happens api-side — this rule
+  // only enforces that the module declares one at all.
+  if (!spec?.category) {
+    errors.push({
+      rule: 'category-required',
+      path: 'category',
+      message: 'category must be provided (registry cross-check happens api-side)',
+    });
+  }
+
+  // Rule: boolean widget must be 'checkbox'. 'switch' has no renderer at
+  // all today — peopleCompanyLink.js's "Create If Not Found" field is
+  // configured but silently unsettable through the UI (maps.md
+  // module-defs §4.11, edit-panel §3/§4.3).
+  entries.forEach(({ entry, path }) => {
+    if (entry.fieldType === 'switch') {
+      errors.push({
+        rule: 'boolean-widget-checkbox',
+        path: `${path}.fieldType`,
+        message: `fieldType 'switch' has no renderer — use 'checkbox' (field: ${entry.field})`,
+      });
+    }
+  });
+
+  // Rule: every edit[].field's settings.<ns> root must match the module's
+  // declared settingsSchema.namespace. Only checked once a module has
+  // opted into settingsSchema (additive: unmigrated modules with no
+  // settingsSchema skip this rule entirely — they simply aren't covered
+  // yet, not "passing"). Fields addressing 'description' (workflowItems)
+  // or the phone.*/messaging.* dual-addressing channel are exempt — they
+  // never sit under 'settings.' at all.
+  const namespace = spec?.settingsSchema?.namespace;
+  if (namespace) {
+    entries.forEach(({ entry, path }) => {
+      const { field } = entry;
+      if (typeof field !== 'string' || !field.startsWith('settings.')) return;
+      const ns = field.slice('settings.'.length).split(/[.[]/)[0];
+      if (ns !== namespace) {
+        errors.push({
+          rule: 'settings-namespace-match',
+          path: `${path}.field`,
+          message: `field '${field}' writes to settings.${ns}, but settingsSchema.namespace is '${namespace}' — this field silently no-ops (aBRouting bug class, maps.md module-defs §4.3)`,
+        });
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/schemas/workflows/moduleSpec.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { PortSpec } from './port.js';
+import { CapabilitiesSpec } from './capabilities.js';
+import { SettingsSchemaSpec } from './settingsSchema.js';
+import { ModuleLayoutSpec } from './layout.js';
+
+// Top-level shape. DEVIATION from design-schema-first.md §2's idealized
+// sketch, which shows `layout:{sections}` and `settingsSchema` as flat
+// siblings of `capabilities` at the module's top level: verified against
+// all 29 real files in
+// app1-api/src/services/objects/constants/workflows/*.js (wait.js, say.js,
+// sendEmail.js, aBRouting.js, …), the layout tree and every module's own
+// default-state object live NESTED inside one `settings` key
+// (`module.settings.layout.sections`, `module.settings.<namespace>`) — not
+// as top-level siblings. Modeling the idealized flat shape here would fail
+// every existing module file, violating the "untouched modules must load
+// exactly as before" constraint. `capabilities`/`settingsSchema`/
+// `moduleSchemaVersion` are genuinely new, additive top-level keys — no
+// module ships them today; `settings.layout`/`settings.<ns>` are the real,
+// unchanged existing tree these new keys sit alongside.
+export const ModuleSpec = z.object({
+  // Identity
+  type: z.string().min(1),
+  // Cross-checked against the workflows.js registry api-side
+  // (design-schema-first.md §2) — kept optional/permissive here so this
+  // schema alone never rejects a real file for a missing category;
+  // lintModuleSpec is where "category must be provided" is enforced.
+  category: z.enum(['ai', 'engagement', 'data', 'actions', 'routing']).optional(),
+  moduleSchemaVersion: z.number().int().positive().optional(),
+
+  // Presentation
+  label: z.string().min(1),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  iconBgColor: z.string().optional(),
+  iconTextColor: z.string().optional(),
+  labelBgColor: z.string().optional(),
+  labelTextColor: z.string().optional(),
+  descriptionBgColor: z.string().optional(),
+  descriptionTextColor: z.string().optional(),
+
+  // Canvas contract
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+  ports: z.array(PortSpec).default([]),
+  editWidth: z.string().optional(),
+
+  // start.js / sayIntent.js's sayIntentOption sub-type only set these
+  // explicitly — every other module omits both, relying on the implicit
+  // default (maps.md module-defs §3). `capabilities.deletable`/
+  // `hiddenFromPicker` are the new declared equivalents; these legacy keys
+  // are kept typed (not just passthrough) since they still drive real
+  // behavior today and a migrated module may set both during the soak
+  // period.
+  isDeletable: z.boolean().optional(),
+  isHiddenFromList: z.boolean().optional(),
+
+  // New, additive-only (see DEVIATION note above)
+  capabilities: CapabilitiesSpec.optional(),
+  settingsSchema: SettingsSchemaSpec.optional(),
+
+  // Legacy pre-capabilities metadata, still real and still read by the
+  // backend today (maps.md module-defs §2): `outputVariableFields`
+  // (documentProcessing.js, summary.js), `excludeKeysFromVariableExtraction`
+  // (selectResult.js), `subModules` (sayIntent.js), `simulate`
+  // (lookup.js/timeControl.js/webHook.js). `capabilities.outputVariables`/
+  // `excludedFromVariableExtraction`/`dataProducer`/`simulatable` are meant
+  // to supersede these one module at a time — kept typed here (not left to
+  // bare passthrough) so both shapes can be inspected side by side during
+  // migration.
+  outputVariableFields: z.array(z.string()).optional(),
+  excludeKeysFromVariableExtraction: z.array(z.string()).optional(),
+  subModules: z.array(z.unknown()).optional(),
+  simulate: z.object({
+    enabled: z.boolean().optional(),
+    endpoint: z.string().optional(),
+  }).passthrough().optional(),
+
+  // The real, load-bearing tree — see DEVIATION note above. `settings`
+  // itself is passthrough because every module's own namespace key
+  // (`wait: {...}`, `email: {...}`, `abRoute: {...}`, …) sits here as a
+  // sibling of `layout`, and there is deliberately no closed list of valid
+  // namespace keys at this layer — `settingsSchema.namespace` is the
+  // declared source of truth for the ones that opt in.
+  settings: z.object({
+    layout: ModuleLayoutSpec.optional(),
+  }).passthrough().optional(),
+}).passthrough();

package/schemas/workflows/port.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+export const PortDirection = z.enum(['in', 'out']);
+
+// Mirrors the workflowItemPorts table (maps.md canvas §2) and the `ports: []`
+// literals in every constants/workflows/*.js file. Real files never declare
+// an explicit port `id` — ports are addressed by direction+label today
+// (label-string routing into `getNextModule.js`, flagged as a separate,
+// out-of-scope correctness workstream by design-schema-first.md §5.2/
+// design-incremental-risk.md §5) — kept optional here, not required, so
+// every existing module's ports[] validates unchanged.
+export const PortSpec = z.object({
+  id: z.string().optional(),
+  direction: PortDirection,
+  label: z.string().optional(),
+  isHidden: z.boolean().default(false),
+  isMultiple: z.boolean().default(false),
+  isLocked: z.boolean().default(false),
+  isConnectionDeletable: z.boolean().default(true),
+  bgColor: z.string().optional(),
+  textColor: z.string().optional(),
+}).passthrough();

package/schemas/workflows/primitives.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+// Conditional visibility expression for workflow module layout sections/
+// columns. Normalizes the two shapes found across
+// app1-api/src/services/objects/constants/workflows/*.js (maps.md
+// module-defs §3/§4.12): the implicit-equals shorthand `{field, value}`
+// used by ~28 of 29 modules, and the one explicit-operator occurrence
+// (sendEmail.js:554-557, `operator: 'not_empty'`, no `value` key at all).
+// `operator` defaults to 'equals' via preprocessing so every existing
+// layout's `{field, value}` shape parses unchanged — this is
+// authoring-time normalization only, never a change to how the client
+// evaluates the condition.
+export const ConditionOperator = z.enum(['equals', 'not_empty']);
+
+export const Conditional = z.preprocess(
+  (v) => (v && typeof v === 'object' && !('operator' in v) ? { ...v, operator: 'equals' } : v),
+  z.object({
+    field: z.string().min(1),
+    operator: ConditionOperator.default('equals'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+  }).refine(
+    (v) => v.operator === 'not_empty' || v.value !== undefined,
+    { message: 'value is required unless operator is not_empty', path: ['value'] },
+  ),
+);
+
+// `info: {type,message}` banner block seen on ~half the modules
+// (wait.js has none; sendEmail.js/selectResult.js/lookup.js do).
+export const InfoSpec = z.object({
+  type: z.string().min(1),
+  message: z.string().min(1),
+}).passthrough();
+
+// Repeating section/row config — real occurrences: section-level
+// (scriptPage.js x4, sendEmail.js templateVariables, lookup.js/webHook.js
+// conditions, setVariable.js, sayIntent.js) and row-level (bot.js
+// dataCollectionFields). `field` is the array-typed settings path the
+// "+ Add" button pushes a new element into.
+export const RepeatingSpec = z.object({
+  enabled: z.boolean().default(true),
+  field: z.string().min(1),
+  object: z.enum(['workflowItems', 'workflowItemSettings']).optional(),
+  newLabel: z.string().optional(),
+}).passthrough();

package/schemas/workflows/settingsSchema.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+// Declares WHERE a module's behavior fields live instead of leaving it to
+// convention (design-schema-first.md §2). `namespace` must match the first
+// path segment after `settings.` on every `settings.<ns>.*` edit field this
+// module declares — see lint.js's settings-namespace-match rule, which is
+// exactly what would mechanically catch aBRouting.js's live field/default
+// mismatch (`edit.field: 'settings.points.unit'` writes a key nothing
+// reads; the module's real default state lives under `settings.abRoute.*`,
+// which is never editable through the UI at all — maps.md module-defs
+// §4.3) and update.js's copy-pasted-and-never-renamed defaults (§4.2) at
+// commit time, not after the bug ships.
+//
+// Optional on ModuleSpec as a whole — a module with no settingsSchema is
+// simply not yet opted into this check (legacy/unmigrated), per the
+// additive constraint in design-incremental-risk.md §2. `phone.*`/
+// `messaging.*` dual-channel fields (say/sayGather/sayIntent/bot/
+// selectResult, maps.md module-defs §2) are exempt from the namespace
+// check entirely — that's a documented, separate addressing channel, not a
+// `settings.<ns>` deviation, and its collapse into `settings` is explicitly
+// deferred (design-schema-first.md §1).
+//
+// `defaults` mirrors the module's own default-state object (e.g.
+// wait.js's bottom-level `wait: {unit,value}`, unwrapped — NOT
+// `{wait: {unit,value}}` again) purely for documentation/tooling; it is not
+// re-injected into `settings.<ns>` at runtime by anything in this package.
+export const SettingsSchemaSpec = z.object({
+  namespace: z.string().min(1),
+  defaults: z.record(z.unknown()).default({}),
+}).passthrough();

package/schemas/workflows/validate.js

@@ -0,0 +1,18 @@
+import { ModuleSpec } from './moduleSpec.js';
+
+// Structural validity only — "is this a well-formed ModuleSpec". Opinions
+// about authoring quality (missing category, banned fieldTypes, field/
+// namespace mismatches) live in lintModuleSpec, which every module also
+// passing validateModuleSpec should additionally pass before being
+// considered fully migrated.
+export function validateModuleSpec(spec) {
+  const result = ModuleSpec.safeParse(spec);
+  if (result.success) {
+    return { valid: true, errors: [], data: result.data };
+  }
+  return {
+    valid: false,
+    errors: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
+    data: null,
+  };
+}