@appinternalleads/ui 0.2.0 → 0.4.0

package/src/agent/validate.ts

@@ -0,0 +1,269 @@
+import { ONBOARDING_PRESETS, ONBOARDING_VALIDATORS } from '../components/onboarding/presets';
+import { presetsOf, resolveConfig } from '../components/onboarding/shared/contract';
+import { shapeIssues } from '../components/onboarding/shared/shape';
+import { formErrors, initialDraft, receiptLines, valuesOf } from '../components/onboarding/receipt-printer/engine';
+import type { ReceiptPrinterSettings } from '../components/onboarding/receipt-printer/contract';
+import { describeComponent, isAgentComponent, manifestOf, nonCopyKeys, AGENT_COMPONENTS } from './catalog';
+import type { ClassicManifest } from './classic';
+import type { NewManifest } from './manifests';
+import { checkCopy, checkFields, checkOwners, checkRefs, withDefaults } from './spec';
+import type { FieldSpec } from './types';
+import {
+  RENDER_SCHEMA, type AgentCapability, type RenderCheck, type RenderIssue, type RenderPreview, type RenderRequest, type Section,
+} from './types';
+
+/**
+ * **`validateRenderRequest` — the one check an agent's request goes through.** Every layer that can
+ * stop the component, in order, each reported with its own `layer`:
+ *
+ * 1. `schema` — the envelope, unknown sections, **unknown keys** anywhere (never silently dropped).
+ * 2. `shape` / `data` / `copy` / `configuration` — each section against the capability: kinds,
+ *    required data (never filled from a case study), ranges, formats, enums, references, owners,
+ *    copy placeholders and lengths, button actions.
+ * 3. `shape` / `semantic` — the component's own render-time kind check and validator, on the config
+ *    the request resolves to.
+ * 4. `interaction` — what the component would refuse on submit (Receipt Printer's Print).
+ *
+ * `valid: true` means the component renders what was asked and, where it has a submit, accepts it.
+ */
+
+const ENVELOPE = ['schema', 'component', 'preset', 'data', 'copy', 'behavior', 'presentation', 'actions'];
+const AGENT_ACTIONS = ['post-message', 'succeed', 'fail'];
+const isObj = (v: unknown): v is Record<string, unknown> => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+
+/** What a valid request resolves to — the package's business, not the agent's. */
+export type ResolvedRender =
+  | { family: 'new'; component: string; config: Record<string, unknown>; initial?: Record<string, unknown>; actions?: Record<string, unknown> }
+  | { family: 'classic'; component: string; props: Record<string, unknown> };
+
+type Sections = { data: Record<string, unknown>; copy: Record<string, unknown>; behavior: Record<string, unknown>; presentation: Record<string, unknown> };
+
+/* ── New components: sections → the component's config ────────────────────────────────────── */
+
+function copyBaseline(m: NewManifest, preset: string | undefined, cap: AgentCapability, copy: Record<string, unknown>) {
+  const resolved = resolveConfig(ONBOARDING_PRESETS[m.component], preset as never) as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [k, spec] of Object.entries(cap.copy)) {
+    const given = copy[k];
+    /* Without a preset the copy is the component's own defaults; a preset brings that case study's words. */
+    const start = preset !== undefined ? resolved[k] ?? spec.default : spec.default;
+    out[k] = spec.type === 'text-map' && isObj(given) ? { ...(start as object), ...given } : given ?? start;
+  }
+  return out;
+}
+
+function newConfig(m: NewManifest, s: Sections, preset: string | undefined, cap: AgentCapability): Record<string, unknown> {
+  const config: Record<string, unknown> = copyBaseline(m, preset, cap, s.copy);
+  const put = (section: 'data' | 'behavior' | 'presentation', values: Record<string, unknown>) => {
+    for (const [k, v] of Object.entries(values)) config[m.rename?.[section]?.[k] ?? k] = v;
+  };
+  const presentationStart = resolveConfig(ONBOARDING_PRESETS[m.component], preset as never) as Record<string, unknown>;
+  put('presentation', withDefaults(m.presentation, { ...Object.fromEntries(Object.keys(m.presentation).map(k => [k, presentationStart[k]])), ...s.presentation }));
+  put('behavior', withDefaults(m.behavior, s.behavior));
+  put('data', withDefaults(m.data, s.data));
+  /* "None" reaches the component as unset: every one of these keys reads null and undefined alike, and its presets may never have said null. */
+  for (const [k, v] of Object.entries(config)) if (v === null && !(k in cap.copy) && m.data[k]?.type !== 'json') config[k] = undefined;
+  /* Nothing a preset holds that is not copy may reach the component: every other key is set, or cleared. */
+  for (const k of nonCopyKeys(m)) if (!(k in config)) config[k] = undefined;
+  return adjust(m, config);
+}
+
+/** The few places the component's config differs from the request's plain values. */
+function adjust(m: NewManifest, c: Record<string, unknown>): Record<string, unknown> {
+  switch (m.component) {
+    case 'budget-tracker':
+      if (!Array.isArray(c.periods) || !(c.periods as unknown[]).length) c.periods = [c.period];
+      return c;
+    case 'seat-allocation': {
+      const first = (ONBOARDING_PRESETS['seat-allocation'].base as { groups: { type: string; icon: string }[] }).groups[0]!;
+      c.groups = (c.groups as Record<string, unknown>[]).map(g => ({ type: first.type, icon: first.icon, detail: '', ...g }));
+      return c;
+    }
+    case 'carousel': {
+      c.slides = (c.slides as Record<string, unknown>[]).map(sl => ({ type: c.type, icon: c.icon, ...sl }));
+      return c;
+    }
+    case 'completion':
+      c.stats = (c.stats as Record<string, unknown>[]).map(st => ({ unit: '', ...st }));
+      c.demoSkipped = [];
+      return c;
+    case 'fallback':
+      c.samples = {};
+      return c;
+    case 'activity-heatmap':
+      c.sample = [];
+      return c;
+    default:
+      return c;
+  }
+}
+
+/** Where a config path (a validator's, a shape check's) lives in the request. */
+function requestPath(m: NewManifest, cap: AgentCapability, path: string): { path: string; section: RenderIssue['section'] } {
+  const top = /^[A-Za-z_]+/.exec(path)?.[0] ?? '';
+  const rest = path.slice(top.length);
+  for (const section of ['data', 'behavior', 'presentation'] as const) {
+    const back = Object.entries(m.rename?.[section] ?? {}).find(([, to]) => to === top)?.[0];
+    const key = back ?? top;
+    if (key in m[section]) return { path: `${section}.${key}${rest}`, section };
+  }
+  if (top in cap.copy) return { path: `copy.${top}${rest}`, section: 'copy' };
+  return { path: path || 'request', section: 'request' };
+}
+
+/** `fields.0.value` (a form error key) → `data.fields[0].value`. */
+const formPath = (k: string) => `data.${k.replace(/\.(\d+)(?=\.|$)/g, '[$1]')}`;
+
+function interaction(m: NewManifest, config: Record<string, unknown>): RenderIssue[] {
+  if (m.component === 'receipt-printer') {
+    const c = config as unknown as ReceiptPrinterSettings;
+    return Object.entries(formErrors(initialDraft(c), c)).map(([k, message]) => ({
+      path: formPath(k), code: 'INTERACTION', layer: 'interaction', section: 'data', message: `${message} (Print would refuse it.)`,
+    }));
+  }
+  if (m.component === 'budget-tracker') {
+    try { new Intl.NumberFormat('en-US', { style: 'currency', currency: String(config.currency) }); } catch {
+      return [{ path: 'data.currency', code: 'ENUM', layer: 'data', section: 'data', message: `"${String(config.currency)}" is not a currency code this platform can format.` }];
+    }
+  }
+  return [];
+}
+
+/* ── Preview ──────────────────────────────────────────────────────────────────────────────── */
+
+/* The words a person would read: not ids, keys, codes or kinds (which the component uses but does not show as written). */
+const HIDDEN = new Set(['id', 'key', 'kind', 'idColumn']);
+function strings(v: unknown, out: string[] = []): string[] {
+  if (typeof v === 'string') { if (v.trim()) out.push(v); }
+  else if (Array.isArray(v)) v.forEach(x => strings(x, out));
+  else if (isObj(v)) Object.entries(v).forEach(([k, x]) => { if (!HIDDEN.has(k)) strings(x, out); });
+  return out;
+}
+function visible(specs: Record<string, FieldSpec>, v: Record<string, unknown>, out: string[] = []): string[] {
+  for (const [k, spec] of Object.entries(specs)) {
+    const x = v?.[k];
+    if (x === undefined || x === null || HIDDEN.has(k) || spec.ref || (spec.type === 'text' && (spec.enum || spec.pattern || spec.format))) continue;
+    if (spec.type === 'text' && typeof x === 'string') { if (x.trim()) out.push(x); }
+    else if (spec.type === 'list' && Array.isArray(x)) x.forEach(i => (spec.item.type === 'object' ? visible(spec.item.fields, i as Record<string, unknown>, out) : spec.item.type === 'text' ? typeof i === 'string' && out.push(i) : strings(i, out)));
+    else if (spec.type === 'object' && isObj(x)) visible(spec.fields, x, out);
+    else if (spec.type === 'json' || spec.type === 'map') strings(x, out);
+  }
+  return out;
+}
+
+function newPreview(m: NewManifest, config: Record<string, unknown>, data: Record<string, unknown>): string[] {
+  if (m.component === 'receipt-printer') {
+    const c = config as unknown as ReceiptPrinterSettings;
+    const l = receiptLines(valuesOf(initialDraft(c)), c);
+    return [
+      c.title, c.subtitle, l.title, l.meta,
+      ...l.details.map(d => `${d.label}: ${d.value}`),
+      ...l.items.map(it => `${it.line} ${it.amount}`),
+      `${l.paymentLabel} ${l.paymentMethod}`, `${l.totalLabel} ${l.total}`, l.message, c.printLabel,
+    ].filter(Boolean);
+  }
+  return [String(config.title ?? ''), String(config.subtitle ?? ''), ...visible(m.data, data)].filter(Boolean).slice(0, 60);
+}
+
+/* ── The check ────────────────────────────────────────────────────────────────────────────── */
+
+function run(input: unknown): { issues: RenderIssue[]; request?: RenderRequest; resolved?: ResolvedRender; preview?: RenderPreview } {
+  const issues: RenderIssue[] = [];
+  const req = (m: string, path = 'request', code: RenderIssue['code'] = 'BAD_SCHEMA', expected?: RenderIssue['expected']) =>
+    issues.push({ path, code, layer: 'schema', section: 'request', message: m, ...(expected ? { expected } : {}) });
+
+  if (!isObj(input)) { req('A render request is an object: { schema: "render/1", component, data, copy?, behavior?, presentation?, actions?, preset? }.'); return { issues }; }
+  if (input.schema !== RENDER_SCHEMA) req(`schema must be "${RENDER_SCHEMA}".`, 'schema', 'BAD_SCHEMA', RENDER_SCHEMA);
+  for (const k of Object.keys(input)) if (!ENVELOPE.includes(k)) req(`A render request has no "${k}". It takes: ${ENVELOPE.join(', ')}.`, k, 'UNKNOWN_KEY', ENVELOPE);
+  const id = input.component;
+  if (!isAgentComponent(id)) { req(`"${String(id)}" is not an agent component. Use one of: ${AGENT_COMPONENTS.join(', ')}.`, 'component', 'UNKNOWN_COMPONENT', [...AGENT_COMPONENTS]); return { issues }; }
+  const m = manifestOf(id)!;
+  const cap = describeComponent(id)!;
+
+  const section = (k: 'data' | 'copy' | 'behavior' | 'presentation' | 'actions', required = false) => {
+    const v = input[k];
+    if (v === undefined) { if (required) req(`${k} is required — the component's runtime data. Nothing is filled in from examples.`, k, 'REQUIRED'); return {}; }
+    if (!isObj(v)) { issues.push({ path: k, code: 'TYPE', layer: 'shape', section: k === 'actions' ? 'actions' : k, message: `${k} must be an object.` }); return {}; }
+    return v;
+  };
+  const s: Sections = { data: section('data', true), copy: section('copy'), behavior: section('behavior'), presentation: section('presentation') };
+  const actions = section('actions');
+  const preset = input.preset;
+  if (preset !== undefined && !cap.presets.some(p => p.preset === preset)) {
+    req(`preset "${String(preset)}" is not a case study of ${id}.`, 'preset', 'UNKNOWN_PRESET', cap.presets.map(p => p.preset));
+  }
+
+  for (const sec of ['data', 'behavior', 'presentation'] as const) {
+    const ctx = { section: sec as Section, issues };
+    checkOwners(m[sec], s[sec], sec, ctx);
+    checkFields(m[sec], s[sec], sec, ctx);
+  }
+  checkCopy(cap.copy, s.copy, { section: 'copy', issues });
+  for (const [button, a] of Object.entries(actions)) {
+    const path = `actions.${button}`;
+    if (!cap.actionButtons.includes(button)) { issues.push({ path, code: 'INVALID_ACTION', layer: 'configuration', section: 'actions', message: `${id} has no button "${button}".`, expected: cap.actionButtons }); continue; }
+    const type = isObj(a) ? a.type : undefined;
+    if (type === 'webhook' || type === 'link') issues.push({ path, code: 'NOT_ALLOWED', layer: 'configuration', section: 'actions', message: `A ${type} is the host's to configure — an agent may use ${AGENT_ACTIONS.join(', ')}.`, expected: AGENT_ACTIONS });
+    else if (typeof type !== 'string' || !AGENT_ACTIONS.includes(type)) issues.push({ path, code: 'INVALID_ACTION', layer: 'configuration', section: 'actions', message: `${path}.type must be one of ${AGENT_ACTIONS.join(', ')}.`, expected: AGENT_ACTIONS });
+    else if (isObj(a)) for (const k of Object.keys(a)) if (k !== 'type' && !(type === 'fail' && k === 'message')) issues.push({ path: `${path}.${k}`, code: 'UNKNOWN_KEY', layer: 'schema', section: 'actions', message: `${path} has no "${k}".` });
+  }
+  if (issues.length) return { issues };
+
+  /* References, once every value has its kind: an id names a real row, a currency an offered one. */
+  const root = { data: withDefaults(m.data, s.data), behavior: withDefaults(m.behavior, s.behavior), presentation: withDefaults(m.presentation, s.presentation) };
+  for (const sec of ['data', 'behavior', 'presentation'] as const) checkRefs(m[sec], s[sec], sec, root, { section: sec, issues });
+  if (issues.length) return { issues };
+
+  const request: RenderRequest = {
+    schema: RENDER_SCHEMA, component: id, ...(preset !== undefined ? { preset: preset as string } : {}),
+    data: root.data, copy: s.copy, behavior: root.behavior, presentation: root.presentation,
+    ...(Object.keys(actions).length ? { actions: actions as RenderRequest['actions'] } : {}),
+  };
+
+  if (m.family === 'classic') {
+    const built = (m as ClassicManifest).build({ data: root.data, copy: s.copy, behavior: root.behavior, presentation: root.presentation });
+    for (const i of built.issues) issues.push({ ...i, layer: i.code === 'UNKNOWN_KEY' ? 'schema' : i.code === 'SEMANTIC' ? 'semantic' : 'data' });
+    if (issues.length) return { issues };
+    return { issues, request, resolved: { family: 'classic', component: id, props: built.props }, preview: { component: id, visibleText: built.preview } };
+  }
+
+  const nm = m as NewManifest;
+  const config = newConfig(nm, s, preset as string | undefined, cap);
+  const presets = ONBOARDING_PRESETS[nm.component];
+  for (const i of shapeIssues(presets, config)) {
+    const where = requestPath(nm, cap, i.path);
+    issues.push({ path: where.path, code: 'TYPE', layer: 'shape', section: where.section, message: `${where.path} ${i.message}` });
+  }
+  for (const i of ONBOARDING_VALIDATORS[nm.component](config)) {
+    const where = requestPath(nm, cap, i.path);
+    issues.push({ path: where.path, code: 'SEMANTIC', layer: 'semantic', section: where.section, message: i.message });
+  }
+  if (issues.length) return { issues };
+  issues.push(...interaction(nm, config));
+  if (issues.length) return { issues };
+
+  const initial = nm.component === 'completion' && (root.data.skipped as unknown[]).length ? { mode: 'partial' } : undefined;
+  return {
+    issues, request,
+    resolved: { family: 'new', component: id, config, ...(initial ? { initial } : {}), ...(Object.keys(actions).length ? { actions } : {}) },
+    preview: { component: id, visibleText: newPreview(nm, config, root.data) },
+  };
+}
+
+/** Check a `render/1` request. Never throws. */
+export function validateRenderRequest(input: unknown): RenderCheck {
+  try {
+    const r = run(input);
+    return r.issues.length || !r.request || !r.preview ? { valid: false, issues: r.issues } : { valid: true, issues: [], request: r.request, preview: r.preview };
+  } catch (e) {
+    return { valid: false, issues: [{ path: 'request', code: 'BAD_SCHEMA', layer: 'schema', section: 'request', message: `The request could not be read (${(e as Error).message}).` }] };
+  }
+}
+
+/** A valid request as the package will render it. `undefined` for an invalid one — check it first. */
+export function resolveRenderRequest(input: unknown): ResolvedRender | undefined {
+  try { const r = run(input); return r.issues.length ? undefined : r.resolved; } catch { return undefined; }
+}
+
+/** The case studies a request may start its copy from — for the `preset` key. */
+export const presetsFor = (id: string) => (isAgentComponent(id) && manifestOf(id)!.family === 'new' ? presetsOf(ONBOARDING_PRESETS[id as NewManifest['component']]) : []);