@friggframework/core 2.0.0--canary.696.5d9f1be.0 → 2.0.0--canary.698.b1a2d30.0

package/integrations/data-defined/renderers/html.js

@@ -0,0 +1,129 @@
+/**
+ * Safe, self-contained HTML for a preview pane. Every piece of data goes through `esc`, links are http(s) only, styles
+ * are inline attributes and there is no script, no `<style>`, no event handler and no external resource, so a pane can
+ * show a vendor's record next to the definition's chrome without that record being able to do anything.
+ */
+const { str, safeUrl, toneOf } = require('./common');
+
+const esc = (v) => str(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+const FONT = "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif";
+
+/** How each host frames what it shows. `generic` is for hosts with no look of their own (a phone app, Zendesk, Shopify…). */
+const HOSTS = {
+    hubspot: { label: 'HubSpot card', frame: `${FONT};background:#fff;border:1px solid #cbd6e2;border-radius:3px;max-width:420px;color:#33475b;font-size:14px;box-shadow:0 1px 2px rgba(0,0,0,.08)`, head: 'background:#f5f8fa;border-bottom:1px solid #cbd6e2;padding:8px 14px;font-size:12px;color:#516f90;font-weight:600', body: 'padding:14px', accent: '#ff7a59' },
+    slack: { label: 'Slack message', frame: `${FONT};background:#fff;border:1px solid #e0e0e0;border-radius:8px;max-width:560px;color:#1d1c1d;font-size:15px`, head: 'padding:8px 14px 0;font-size:13px;color:#616061', body: 'padding:6px 14px 12px', accent: '#4a154b' },
+    generic: { label: 'Preview', frame: `${FONT};background:#fff;border:1px solid #d9dde3;border-radius:6px;max-width:480px;color:#1f2937;font-size:14px`, head: 'background:#f3f4f6;border-bottom:1px solid #d9dde3;padding:8px 14px;font-size:12px;color:#6b7280;font-weight:600', body: 'padding:14px', accent: '#2563eb' },
+};
+const hostOf = (h) => HOSTS[h] || HOSTS.generic;
+const TONE = { positive: 'background:#e6f4ea;color:#1e6b34', warning: 'background:#fff4d6;color:#8a5a00', critical: 'background:#fde8e6;color:#a4261b', neutral: 'background:#eceff3;color:#44505f' };
+
+/** The view tree as HTML, without the host frame. */
+function viewToHtmlBody(view, host = 'generic') {
+    const H = hostOf(host);
+    const go = (v) => {
+        if (!v || typeof v !== 'object') return '';
+        const p = v.props || {};
+        const kids = () => (v.children || []).map(go).join('');
+        switch (v.component) {
+            case 'Stack': return `<div style="display:flex;flex-direction:column;gap:10px">${kids()}</div>`;
+            case 'Heading': return `<h3 style="margin:0;font-size:16px;font-weight:700">${esc(p.text)}</h3>`;
+            case 'Text': return `<p style="margin:0;line-height:1.4">${esc(p.text)}</p>`;
+            case 'KeyValue': return `<dl style="margin:0;display:grid;grid-template-columns:max-content 1fr;gap:4px 14px">${(Array.isArray(p.items) ? p.items : []).map((it) => `<dt style="color:#6b7280">${esc(it?.label)}</dt><dd style="margin:0">${esc(it?.value) || '—'}</dd>`).join('')}</dl>`;
+            case 'List': return `<ul style="margin:0;padding-left:18px">${(Array.isArray(p.items) ? p.items : []).map((it) => `<li>${esc(it?.title)}${it?.meta ? ` <span style="color:#6b7280;font-size:12px">${esc(it.meta)}</span>` : ''}</li>`).join('')}</ul>`;
+            case 'Table': return `<table style="border-collapse:collapse;width:100%"><thead><tr>${(Array.isArray(p.columns) ? p.columns : []).map((c) => `<th style="text-align:left;border-bottom:1px solid #d9dde3;padding:4px 8px;font-size:12px;color:#6b7280">${esc(c)}</th>`).join('')}</tr></thead><tbody>${(Array.isArray(p.rows) ? p.rows : []).map((r) => `<tr>${(Array.isArray(r) ? r : []).map((c) => `<td style="border-bottom:1px solid #eef0f3;padding:4px 8px">${esc(c)}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+            case 'Badge': return `<span style="display:inline-block;align-self:flex-start;padding:2px 8px;border-radius:10px;font-size:12px;font-weight:600;${TONE[toneOf(p.tone)]}">${esc(p.text)}</span>`;
+            case 'Empty': return `<p style="margin:0;color:#6b7280;font-style:italic">${esc(p.text)}</p>`;
+            case 'Divider': return '<hr style="border:0;border-top:1px solid #e5e7eb;margin:2px 0">';
+            case 'Button': return buttonHtml({ label: p.label, action: p.action, primary: p.style === 'primary', accent: H.accent });
+            default: return kids();
+        }
+    };
+    return go(view);
+}
+
+/** A button in a preview does nothing (no script), but says what it would do: a link for open_url, a `data-` marker for a workflow. */
+function buttonHtml({ label, action, primary, accent }) {
+    const style = `display:inline-block;align-self:flex-start;padding:6px 14px;border-radius:4px;font-size:14px;font-weight:600;text-decoration:none;cursor:default;${primary ? `background:${accent};color:#fff;border:1px solid ${accent}` : `background:#fff;color:${accent};border:1px solid ${accent}`}`;
+    if (action?.type === 'open_url') {
+        const url = safeUrl(action.url);
+        if (url) return `<a href="${esc(url)}" target="_blank" rel="noopener noreferrer" style="${style}">${esc(label || 'Open')}</a>`;
+    }
+    const wf = action?.type === 'userAction' ? ` data-workflow="${esc(action.workflow)}" title="${esc(`Runs the "${action.workflow}" workflow`)}"` : '';
+    return `<button type="button"${wf} style="${style}">${esc(label || 'Open')}</button>`;
+}
+
+/** The framed preview: a head line saying what this is and where it appears, then the body. */
+function frame(host, title, bodyHtml) {
+    const H = hostOf(host);
+    return `<div data-preview-host="${esc(host in HOSTS ? host : 'generic')}" style="${H.frame}"><div style="${H.head}">${esc(title || H.label)}</div><div style="${H.body}">${bodyHtml}</div></div>`;
+}
+
+/**
+ * @param {object|null} view
+ * @param {{ host?: string, title?: string }} [opts]
+ */
+function viewToHtml(view, { host = 'generic', title } = {}) {
+    const body = view ? viewToHtmlBody(view, host) : `<p style="margin:0;color:#6b7280;font-style:italic">Nothing to show for this record.</p>`;
+    return frame(host, title, body);
+}
+
+// ---- Slack: mrkdwn and Block Kit as HTML, so a posted message previews as it will look, not as a data dump ----
+
+/** Slack mrkdwn (already Slack-encoded: `&amp;`, `<url|label>`) to HTML. Only `* _ ~ \`` and links are interpreted. */
+function mrkdwnToHtml(text) {
+    const parts = str(text).split(/(<[^<>\n]*>)/);
+    const out = parts.map((seg) => {
+        const tok = /^<([^<>\n]*)>$/.exec(seg);
+        if (tok) {
+            // the target is Slack-encoded like the rest (`&amp;` in a query string): decode it once, then esc() it as an attribute
+            const [rawTarget, label] = tok[1].split('|');
+            const target = rawTarget.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+            if (/^https?:\/\//i.test(target)) { const url = safeUrl(target); return url ? `<a href="${esc(url)}" target="_blank" rel="noopener noreferrer" style="color:#1264a3">${esc(label || target)}</a>` : esc(label || ''); }
+            if (target.startsWith('!')) return `<span style="background:#fff3cd">@${esc(label || target.slice(1).split('^')[0])}</span>`;
+            if (target.startsWith('@')) return `<span style="background:#e8f5fa;color:#1264a3">@${esc(label || target.slice(1))}</span>`;
+            if (target.startsWith('#')) return `<span style="color:#1264a3">#${esc(label || target.slice(1))}</span>`;
+            return esc(label || '');
+        }
+        // decode Slack's three entities once, then escape for HTML, then emphasis on the escaped text
+        const raw = seg.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+        return esc(raw)
+            .replace(/`([^`\n]+)`/g, '<code style="background:#f4f4f4;border:1px solid #e0e0e0;border-radius:3px;padding:0 3px">$1</code>')
+            .replace(/(^|[\s(])\*([^*\n]+)\*(?=$|[\s).,!?:;])/g, '$1<strong>$2</strong>')
+            .replace(/(^|[\s(])_([^_\n]+)_(?=$|[\s).,!?:;])/g, '$1<em>$2</em>')
+            .replace(/(^|[\s(])~([^~\n]+)~(?=$|[\s).,!?:;])/g, '$1<del>$2</del>');
+    }).join('');
+    return out.replace(/\n/g, '<br>');
+}
+
+const textOf = (t) => (t && t.type === 'mrkdwn' ? mrkdwnToHtml(t.text) : esc(t?.text));
+
+function slackBlocksToHtml(blocks) {
+    return (Array.isArray(blocks) ? blocks : []).map((b) => {
+        switch (b?.type) {
+            case 'header': return `<div style="font-size:18px;font-weight:700;margin:6px 0">${esc(b.text?.text)}</div>`;
+            case 'section': return `<div style="margin:4px 0">${b.text ? `<div>${textOf(b.text)}</div>` : ''}${Array.isArray(b.fields) ? `<div style="display:grid;grid-template-columns:1fr 1fr;gap:6px 14px;margin-top:4px">${b.fields.map((f) => `<div>${textOf(f)}</div>`).join('')}</div>` : ''}</div>`;
+            case 'context': return `<div style="color:#616061;font-size:12px;margin:4px 0">${(b.elements || []).map(textOf).join(' ')}</div>`;
+            case 'divider': return '<hr style="border:0;border-top:1px solid #e0e0e0;margin:8px 0">';
+            case 'actions': return `<div style="display:flex;flex-wrap:wrap;gap:8px;margin:6px 0">${(b.elements || []).map((e) => (e.url
+                ? buttonHtml({ label: e.text?.text, action: { type: 'open_url', url: e.url }, accent: '#1264a3' })
+                : buttonHtml({ label: e.text?.text, action: { type: 'userAction', workflow: safeWorkflow(e.value) }, primary: e.style === 'primary', accent: e.style === 'primary' ? '#007a5a' : '#1264a3' }))).join('')}</div>`;
+            default: return `<div style="color:#616061;font-size:12px">(${esc(b?.type || 'unknown')} block)</div>`;
+        }
+    }).join('');
+}
+function safeWorkflow(value) { try { const w = JSON.parse(value)?.workflow; return typeof w === 'string' ? w : ''; } catch (_) { return ''; } }
+
+/** A Slack message as the channel will show it: who posts it, where, then the blocks (or the text). */
+function slackMessageToHtml({ channel, text, blocks, appName = 'Your integration' }) {
+    const to = channel ? esc(channel) : '<em>(channel not chosen yet)</em>';
+    const body = Array.isArray(blocks) && blocks.length ? slackBlocksToHtml(blocks) : `<div>${mrkdwnToHtml(text)}</div>`;
+    return `<div data-preview-host="slack" style="${HOSTS.slack.frame}"><div style="${HOSTS.slack.head}"><strong style="color:#1d1c1d">${esc(appName)}</strong> <span style="background:#e8e8e8;border-radius:3px;padding:0 4px;font-size:11px">APP</span> to ${to}</div><div style="${HOSTS.slack.body}">${body}</div></div>`;
+}
+
+/** Any other outbound call: what it is and what it carries. The values are escaped, and objects are shown as JSON. */
+function callToHtml({ module, capability, args }) {
+    const rows = Object.entries(args || {}).map(([k, v]) => `<dt style="color:#6b7280">${esc(k)}</dt><dd style="margin:0;white-space:pre-wrap;word-break:break-word">${esc(typeof v === 'string' ? v : JSON.stringify(v, null, 2))}</dd>`).join('');
+    return frame('generic', `Would call ${module} · ${capability}`, `<dl style="margin:0;display:grid;grid-template-columns:max-content 1fr;gap:4px 14px">${rows}</dl>`);
+}
+
+module.exports = { viewToHtml, viewToHtmlBody, slackBlocksToHtml, slackMessageToHtml, mrkdwnToHtml, callToHtml, esc, HOSTS };

package/integrations/data-defined/renderers/hubspot.js

@@ -0,0 +1,54 @@
+/**
+ * Resolved view tree -> a JSON description of HubSpot UI-extension components (`@hubspot/ui-extensions` names). Data,
+ * not React: a thin card deployed once maps `{ type, props, children }` onto `React.createElement(components[type], ...)`
+ * and routes `props.action` to the actions endpoint, so a changed card is a publish, not a card deploy.
+ *
+ * A node is `{ type, props?, children? }`; a child is a string (text) or a node. Strings are text, never markup.
+ */
+const { str, safeUrl, toneOf } = require('./common');
+
+/** The component names this emits, so the card can fail closed on one it does not know. */
+const HUBSPOT_COMPONENTS = ['Flex', 'Heading', 'Text', 'List', 'Tag', 'Button', 'EmptyState', 'DescriptionList', 'DescriptionListItem', 'Divider', 'Table', 'TableHead', 'TableBody', 'TableRow', 'TableHeader', 'TableCell'];
+const TAG_VARIANT = { positive: 'success', warning: 'warning', critical: 'error', neutral: 'default' };
+
+const node = (type, props, children) => ({ type, ...(props && Object.keys(props).length ? { props } : {}), ...(children && children.length ? { children } : {}) });
+
+/**
+ * @param {object|null} view
+ * @param {{ integrationId?: string, surface?: string }} [opts]  carried on a button's `action`, so the card can post it back
+ * @returns {object|null}
+ */
+function viewToHubSpot(view, { integrationId, surface } = {}) {
+    const go = (v) => {
+        if (!v || typeof v !== 'object') return null;
+        const p = v.props || {};
+        const kids = () => (v.children || []).map(go).filter(Boolean);
+        switch (v.component) {
+            case 'Stack': return node('Flex', { direction: 'column', gap: 'sm' }, kids());
+            case 'Heading': return node('Heading', {}, [str(p.text)]);
+            case 'Text': return node('Text', {}, [str(p.text)]);
+            case 'KeyValue': return node('DescriptionList', { direction: 'row' }, (Array.isArray(p.items) ? p.items : []).map((it) => node('DescriptionListItem', { label: str(it?.label) }, [node('Text', {}, [str(it?.value) || '—'])])));
+            case 'List': return node('List', { variant: 'unordered' }, (Array.isArray(p.items) ? p.items : []).map((it) => node('Flex', { direction: 'column', gap: 'flush' }, [node('Text', { format: { fontWeight: 'demibold' } }, [str(it?.title)]), ...(it?.meta ? [node('Text', { variant: 'microcopy' }, [str(it.meta)])] : [])])));
+            case 'Table': return node('Table', {}, [
+                node('TableHead', {}, [node('TableRow', {}, (Array.isArray(p.columns) ? p.columns : []).map((c) => node('TableHeader', {}, [str(c)])))]),
+                node('TableBody', {}, (Array.isArray(p.rows) ? p.rows : []).map((r) => node('TableRow', {}, (Array.isArray(r) ? r : []).map((c) => node('TableCell', {}, [str(c)]))))),
+            ]);
+            case 'Badge': return node('Tag', { variant: TAG_VARIANT[toneOf(p.tone)] }, [str(p.text)]);
+            case 'Empty': return node('EmptyState', { title: str(p.text), layout: 'vertical' });
+            case 'Divider': return node('Divider', { distance: 'sm' });
+            case 'Button': {
+                const a = p.action;
+                const variant = p.style === 'primary' ? 'primary' : p.style === 'danger' ? 'destructive' : 'secondary';
+                let action;
+                if (a?.type === 'userAction' && typeof a.workflow === 'string') action = { type: 'userAction', workflow: a.workflow, surface, ...(integrationId ? { integrationId: String(integrationId) } : {}), ...(a.input ? { input: a.input } : {}) };
+                else if (a?.type === 'open_url' && safeUrl(a.url)) action = { type: 'open_url', url: safeUrl(a.url) };
+                // A button with no usable action still renders (disabled), so the card matches the definition.
+                return node('Button', { variant, ...(action ? { action } : { disabled: true }) }, [str(p.label) || 'Open']);
+            }
+            default: return kids().length === 1 ? kids()[0] : node('Flex', { direction: 'column', gap: 'sm' }, kids());
+        }
+    };
+    return go(view);
+}
+
+module.exports = { viewToHubSpot, HUBSPOT_COMPONENTS };

package/integrations/data-defined/renderers/preview.js

@@ -0,0 +1,154 @@
+/**
+ * Previews: what an integration will show inside the apps it connects, rendered from the current settings and sample
+ * or real records. Same code path as production for everything that decides the content (queries, view resolution,
+ * the interpreter and its steps); the only thing swapped is where a capability call goes.
+ *
+ *   previewSurface   a UI surface (a HubSpot card, a Slack message menu...) -> view + html (+ slack blocks / hubspot tree)
+ *   previewWorkflow  dry-run a workflow: every outbound call is RECORDED with the args it would send, none is made
+ */
+const { makePorts, renderSurface, runWorkflow, recordOf } = require('../runtime');
+const { isBuiltin } = require('../steps');
+const { viewToSlack } = require('./slack');
+const { viewToHubSpot } = require('./hubspot');
+const { viewToHtml, slackMessageToHtml, callToHtml, slackBlocksToHtml, esc, HOSTS } = require('./html');
+
+class DryRunError extends Error { constructor(what) { super(`dry run: ${what} was not performed`); this.name = 'DryRunError'; } }
+
+const clone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+
+/** A plausible empty record for a manifest object: ids are filled (a step that checks `$.steps.x.id exists` proceeds), the rest is empty of its type. */
+function sampleObject(manifest, name) {
+    const o = manifest?.objects?.[name];
+    const out = {};
+    for (const f of o?.fields || []) {
+        const keys = String(f.name).split('.');
+        let cur = out;
+        keys.slice(0, -1).forEach((k) => { cur = (cur[k] = cur[k] && typeof cur[k] === 'object' ? cur[k] : {}); });
+        const empty = f.type === 'id' ? `preview-${name}-${f.name}` : f.type === 'number' ? 0 : f.type === 'boolean' ? false : f.type === 'json' ? {} : f.type === 'array' ? [] : '';
+        cur[keys[keys.length - 1]] = empty;
+    }
+    return out;
+}
+function sampleOutput(manifest, cap) {
+    const o = String(cap?.output || '');
+    if (o.endsWith('[]')) return [];
+    if (/^page</.test(o)) return { results: [] };
+    return o && manifest?.objects?.[o] ? sampleObject(manifest, o) : {};
+}
+
+/**
+ * Ports for previews. `ports.call` answers from `fixtures` (key "<module key>.<capability>", a value or a function of
+ * the args), else from the manifest's own output shape, and records the call. The real `callApi` the base ports would
+ * use throws, so a call that somehow bypassed the recorder fails loudly instead of reaching an API.
+ *
+ * @param {{ def, manifests, fixtures?: object, store?: Map }} p  fixtures.store pre-seeds the link store (keys as the real store's)
+ * @returns {{ ports, calls: object[], refusing: object }}  `refusing`: the unwrapped ports, whose call() always throws (kept so a test can prove it)
+ */
+function recordingPorts({ def, manifests, fixtures = {}, store }) {
+    const calls = [];
+    const rows = store || new Map(Object.entries(clone(fixtures.store) || {}));
+    const mem = {
+        get: async (k) => rows.get(k) ?? null,
+        put: async (k, v) => { rows.set(k, v); },
+        claim: async (k, v) => { if (rows.has(k)) return false; rows.set(k, v); return true; },
+        release: async (k) => { rows.delete(k); },
+    };
+    const base = makePorts({
+        def, manifests, store: mem,
+        callApi: async (moduleKey, method) => { throw new DryRunError(`${moduleKey}.${method}`); },
+        runCode: async (ref, args) => answer('code', ref, 'code', args, fixtures[`code:${ref}`], {}),
+    });
+    const ports = { ...base }; // the seam below replaces call() on this copy; `base` keeps the one that reaches callApi
+    const manifestFor = (key) => manifests[def.modules[key]?.module];
+    async function answer(module, capability, kind, args, fixture, fallback) {
+        const call = { module, capability, kind, args: clone(args) };
+        calls.push(call);
+        try {
+            call.output = typeof fixture === 'function' ? clone(await fixture(clone(args), { module, capability })) : fixture !== undefined ? clone(fixture) : fallback;
+            return clone(call.output);
+        } catch (e) { call.error = String(e.message || e); throw e; }
+    }
+    // `refusing` is the base ports as they were before the seam below: their call() reaches callApi, which throws.
+    // The seam: the interpreter only ever reaches a module through ports.call.
+    ports.call = async (moduleKey, capability, args) => {
+        const m = manifestFor(moduleKey);
+        const c = m?.capabilities?.[capability];
+        if (!c) {
+            calls.push({ module: moduleKey, capability, kind: 'unknown', args: clone(args), error: 'not declared by the module manifest' });
+            throw new Error(`${moduleKey}.${capability} is not declared by the module manifest`);
+        }
+        return answer(moduleKey, capability, c.kind, args, fixtures[`${moduleKey}.${capability}`], sampleOutput(m, c));
+    };
+    return { ports, calls, refusing: base };
+}
+
+/** read/search/subscribe calls fetch; the rest (and code) is what leaves the integration. */
+const isSend = (call) => call.kind === 'write' || call.kind === 'delete';
+
+/** How one outbound call would look where it lands. Slack messages get the real Block Kit/mrkdwn rendering. */
+function renderCall(call, manifest, appName) {
+    if (manifest?.module === 'slack' && /^message\./.test(call.capability)) {
+        const a = call.args || {};
+        const slack = { channel: a.channel, text: a.text, ...(Array.isArray(a.blocks) ? { blocks: a.blocks } : {}) };
+        return { html: slackMessageToHtml({ ...slack, appName }), slack };
+    }
+    return { html: callToHtml(call) };
+}
+
+/**
+ * Dry-run one workflow. Nothing is performed: every capability call is recorded with the args it would carry and
+ * answered from `fixtures` (or an empty record shaped by the manifest). A webhook workflow with no `event` runs on
+ * the manifest's own sample payload for its trigger.
+ *
+ * @param {{ def, installation?, workflowId: string, event?, record?, manifests, fixtures?: object, now?: Function }} p
+ * @returns {Promise<{ workflow: string, status: string, reason?: string, error?: string, waiting?: object, sends: object[], calls: object[], trace: object[] }>}
+ *   `calls`: every call in order, `{ stepId, at, module, capability, kind, args, output, rendered }`; `sends`: the writes
+ *   among them (`rendered` is `{ html, slack? }` for those, null for reads)
+ */
+async function previewWorkflow({ def, installation = {}, workflowId, event, record, manifests, fixtures = {}, now }) {
+    const w = (def.workflows || []).find((x) => x.id === workflowId);
+    if (!w) throw new Error(`Unknown workflow "${workflowId}"`);
+    if (event === undefined) {
+        const t = w.trigger;
+        event = (t.type === 'webhook' && clone(manifests[def.modules[t.module]?.module]?.events?.[t.topic]?.payload)) || {};
+    }
+    const { ports, calls } = recordingPorts({ def, manifests, fixtures });
+    const run = await runWorkflow({ def, installation, workflowId, event, record, ports, manifests, ...(now ? { now } : {}) });
+
+    // The trace has one entry per step that ran; the calls, in the same order, belong to the entries that are capability steps (or code).
+    const callSteps = (run.trace || []).filter((t) => (!isBuiltin(t.use) || t.use === 'code') && (t.status === 'ok' || t.status === 'error'));
+    const aligned = callSteps.length === calls.length;
+    const out = calls.map((c, i) => {
+        const manifest = manifests[def.modules[c.module]?.module];
+        return { stepId: aligned ? callSteps[i].id : null, at: aligned ? callSteps[i].at : null, ...c, rendered: isSend(c) && manifest ? renderCall(c, manifest, def.label || def.id) : null };
+    });
+    const waiting = run.status === 'waiting' ? run.waitingFor : undefined;
+    return {
+        workflow: workflowId, status: run.status, ...(run.reason ? { reason: run.reason } : {}), ...(run.error ? { error: run.error } : {}),
+        ...(waiting ? { waiting: { ...waiting, ...(waiting.kind === 'approval' ? { html: `<div style="${HOSTS.generic.frame}"><div style="${HOSTS.generic.head}">Waits for approval</div><div style="${HOSTS.generic.body}">${esc(waiting.prompt)}</div></div>` } : {}) } } : {}),
+        sends: out.filter(isSend), calls: out, trace: run.trace || [],
+    };
+}
+
+/**
+ * Render one UI surface. `ports` answer the surface's query (real ports for real records; `recordingPorts(...).ports`
+ * with fixtures for samples). `host` defaults to the surface's own.
+ *
+ * @returns {Promise<{ surface, view, html: string, slack?: { blocks, text, truncated }, hubspot?: object }>}
+ */
+async function previewSurface({ def, installation = {}, surfaceId, record, ports, host }) {
+    const { surface, view } = await renderSurface({ def, installation, surfaceId, record, ports });
+    const h = host || surface.host;
+    const opts = { integrationId: installation.integrationId, surface: surface.id };
+    const out = { surface, view };
+    if (h === 'slack') {
+        out.slack = viewToSlack(view, opts);
+        out.html = `<div data-preview-host="slack" style="${HOSTS.slack.frame}"><div style="${HOSTS.slack.head}">${esc(surface.label || def.label || def.id)} · ${esc(surface.placement)}</div><div style="${HOSTS.slack.body}">${view ? slackBlocksToHtml(out.slack.blocks) : '<em>Nothing to show for this record.</em>'}</div></div>`;
+    } else {
+        if (h === 'hubspot') out.hubspot = viewToHubSpot(view, opts);
+        out.html = viewToHtml(view, { host: h, title: `${def.ui.find((u) => u.id === surface.id)?.label || surface.id} · ${surface.placement}` });
+    }
+    return out;
+}
+
+module.exports = { previewSurface, previewWorkflow, recordingPorts, DryRunError, recordOf };

package/integrations/data-defined/renderers/slack.js

@@ -0,0 +1,146 @@
+/**
+ * Resolved view tree -> Slack Block Kit. Data comes from vendor records, so everything that is data is escaped for
+ * mrkdwn, and everything is cut to Slack's limits with a visible marker instead of letting chat.postMessage reject the
+ * whole message (a long deal name must not cost the approval request).
+ */
+const { str, safeUrl, truncate, toneOf, encodeAction } = require('./common');
+
+const LIMITS = { blocks: 50, header: 150, sectionText: 3000, fieldText: 2000, fields: 10, contextText: 3000, contextElements: 10, button: 75, buttonUrl: 3000, actionId: 255, actions: 25, listItems: 25, itemText: 300 };
+const MARK = '…';
+const ZWSP = '\u200b';
+
+/**
+ * Text that is DATA, for a mrkdwn field. `&`, `<` and `>` are the three characters Slack requires escaping (this also
+ * defuses `<!channel>` and `<https://evil|click>` in a vendor field). Slack has no backslash escape for `* _ ~ \``, so
+ * `* _ ~` are fenced with a zero-width space, which stops them pairing into bold/italic/strike without changing how they
+ * look. A fenced backtick would still pair into a code span, so it becomes the look-alike U+02CB.
+ */
+function escapeMrkdwn(v) {
+    return str(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/[*_~]/g, `${ZWSP}$&${ZWSP}`).replace(/`/g, '\u02cb');
+}
+const mrkdwn = (t) => ({ type: 'mrkdwn', text: t });
+const plain = (t) => ({ type: 'plain_text', text: t, emoji: false });
+const clip = (s, max) => truncate(s, max, MARK);
+
+/** Lines packed into as few sections as fit 3000 characters; one line is never split. */
+function linesToSections(lines) {
+    const out = [];
+    let cur = '';
+    for (const l of lines) {
+        const line = clip(l, LIMITS.itemText);
+        if (cur && cur.length + 1 + line.length > LIMITS.sectionText) { out.push(cur); cur = ''; }
+        cur = cur ? `${cur}\n${line}` : line;
+    }
+    if (cur) out.push(cur);
+    return out.map((text) => ({ type: 'section', text: mrkdwn(clip(text, LIMITS.sectionText)) }));
+}
+
+const TONE_EMOJI = { positive: ':large_green_circle:', warning: ':large_yellow_circle:', critical: ':red_circle:', neutral: ':white_circle:' };
+
+/**
+ * @param {object|null} view  resolveView output ({ component, props, children })
+ * @param {{ integrationId?: string, surface?: string }} [opts]  what a button's click carries back
+ * @returns {{ blocks: object[], text: string, truncated: boolean }}  `text` is the notification/fallback text
+ */
+function viewToSlack(view, { integrationId, surface } = {}) {
+    const blocks = [];
+    let text = '';
+    let truncated = false;
+    let pending = []; // consecutive buttons share one actions block
+    let n = 0;
+
+    const flush = () => {
+        if (!pending.length) return;
+        const els = pending.slice(0, LIMITS.actions);
+        if (pending.length > LIMITS.actions) truncated = true;
+        blocks.push({ type: 'actions', elements: els });
+        pending = [];
+    };
+    const push = (b) => { flush(); blocks.push(b); };
+
+    const walk = (node) => {
+        if (!node || typeof node !== 'object') return;
+        const p = node.props || {};
+        switch (node.component) {
+            case 'Heading': {
+                flush();
+                const t = clip(str(p.text), LIMITS.header);
+                if (!text) text = t;
+                if (t) blocks.push({ type: 'header', text: plain(t) });
+                break;
+            }
+            case 'Text': {
+                const t = str(p.text);
+                if (!text) text = t;
+                if (t) push({ type: 'section', text: mrkdwn(clip(escapeMrkdwn(t), LIMITS.sectionText)) });
+                break;
+            }
+            case 'KeyValue': {
+                const items = Array.isArray(p.items) ? p.items : [];
+                for (let i = 0; i < items.length; i += LIMITS.fields) {
+                    const fields = items.slice(i, i + LIMITS.fields).map((it) => mrkdwn(clip(`*${escapeMrkdwn(it?.label)}*\n${escapeMrkdwn(it?.value) || '—'}`, LIMITS.fieldText)));
+                    if (fields.length) push({ type: 'section', fields });
+                }
+                break;
+            }
+            case 'List': {
+                const items = Array.isArray(p.items) ? p.items : [];
+                const lines = items.slice(0, LIMITS.listItems).map((it) => `• ${escapeMrkdwn(it?.title)}${it?.meta ? ` — _${escapeMrkdwn(it.meta)}_` : ''}`);
+                if (items.length > LIMITS.listItems) { lines.push(`_${MARK} and ${items.length - LIMITS.listItems} more_`); truncated = true; }
+                flush();
+                blocks.push(...linesToSections(lines));
+                break;
+            }
+            case 'Table': {
+                const cols = Array.isArray(p.columns) ? p.columns : [];
+                const rows = Array.isArray(p.rows) ? p.rows : [];
+                const lines = [];
+                if (cols.length) lines.push(cols.map((c) => `*${escapeMrkdwn(c)}*`).join('  |  '));
+                for (const r of rows.slice(0, LIMITS.listItems)) lines.push((Array.isArray(r) ? r : []).map((c) => escapeMrkdwn(c) || '—').join('  |  '));
+                if (rows.length > LIMITS.listItems) { lines.push(`_${MARK} and ${rows.length - LIMITS.listItems} more_`); truncated = true; }
+                flush();
+                blocks.push(...linesToSections(lines));
+                break;
+            }
+            case 'Badge': {
+                const t = str(p.text);
+                if (t) push({ type: 'context', elements: [mrkdwn(clip(`${TONE_EMOJI[toneOf(p.tone)]} *${escapeMrkdwn(t)}*`, LIMITS.contextText))] });
+                break;
+            }
+            case 'Empty': {
+                const t = str(p.text);
+                if (t) push({ type: 'context', elements: [mrkdwn(clip(`_${escapeMrkdwn(t)}_`, LIMITS.contextText))] });
+                break;
+            }
+            case 'Divider': push({ type: 'divider' }); break;
+            case 'Button': {
+                const label = clip(str(p.label) || 'Open', LIMITS.button);
+                const style = p.style === 'primary' ? { style: 'primary' } : p.style === 'danger' ? { style: 'danger' } : {};
+                const a = p.action;
+                if (a?.type === 'userAction' && typeof a.workflow === 'string') {
+                    const value = encodeAction({ integrationId, workflow: a.workflow, surface, needsInput: !!a.input });
+                    if (value) pending.push({ type: 'button', text: plain(label), action_id: clip(`frigg:${a.workflow}`, LIMITS.actionId - 8) + `:${n++}`, value, ...style });
+                } else if (a?.type === 'open_url') {
+                    const url = safeUrl(a.url);
+                    if (url && url.length <= LIMITS.buttonUrl) pending.push({ type: 'button', text: plain(label), action_id: `frigg:open:${n++}`, url });
+                }
+                break;
+            }
+            default: break; // Stack, and anything a newer definition adds: just its children
+        }
+        for (const c of node.children || []) walk(c);
+    };
+    walk(view);
+    flush();
+
+    // 50 blocks is Slack's whole-message cap. Keep 49 and say so, rather than lose the message.
+    let out = blocks;
+    if (blocks.length > LIMITS.blocks) {
+        out = [...blocks.slice(0, LIMITS.blocks - 1), { type: 'context', elements: [mrkdwn(`_${MARK} ${blocks.length - (LIMITS.blocks - 1)} more blocks not shown_`)] }];
+        truncated = true;
+    }
+    // `text` is the notification fallback and Slack parses it as mrkdwn too, so a record's `<!channel>` must not ping from there either.
+    return { blocks: out, text: clip(escapeMrkdwn(text || 'Update'), LIMITS.sectionText), truncated };
+}
+
+module.exports = { viewToSlack, escapeMrkdwn, LIMITS };

package/integrations/data-defined/runtime.js

@@ -21,6 +21,21 @@ const { TRANSFORMS } = require('./transforms');
  *        Backed by IntegrationMapping: get = getMapping, put = upsertMapping, claim = createMapping (insert-only; false if it existed)
  * @param {(ref:string, args:object) => Promise<any>} [p.runCode]
  */
+/**
+ * The arguments an Api method is called with. A capability with no `args` takes one object holding every input; one
+ * with `args` (manifest `args`) takes them positionally: an input by name, "$rest" (an object of the inputs not
+ * named in the list) or { value } (a constant, e.g. the sObject name of Salesforce's generic create/get).
+ */
+function argumentsFor(input, order) {
+    if (!Array.isArray(order)) return [input];
+    const named = new Set(order.filter((a) => typeof a === 'string' && a !== '$rest'));
+    return order.map((a) => {
+        if (a === '$rest') return Object.fromEntries(Object.entries(input || {}).filter(([k]) => !named.has(k)));
+        if (a && typeof a === 'object') return a.value;
+        return input?.[a];
+    });
+}
+
 function makePorts({ def, manifests, callApi, store, runCode }) {
     const manifestFor = (key) => manifests[def.modules[key]?.module];
     const normalise = (set, key, value) => {
@@ -39,7 +54,7 @@ function makePorts({ def, manifests, callApi, store, runCode }) {
         async call(moduleKey, capability, args) {
             const c = manifestFor(moduleKey)?.capabilities?.[capability];
             if (!c) throw new Error(`${moduleKey}.${capability} is not declared by the module manifest`);
-            return callApi(moduleKey, c.method, args);
+            return callApi(moduleKey, c.method, args, c.args);
         },
         links: {
             /** By one side's id: link:<set>:<module>:<id>. By identity key: idx:<set>:<key>:<normalised value>. */
@@ -250,4 +265,4 @@ function defaultsOf(settings) {
     return Object.fromEntries(Object.entries(settings || {}).filter(([, s]) => s.default !== undefined).map(([k, s]) => [k, s.default]));
 }
 
-module.exports = { makePorts, runWorkflow, resumeWorkflow, runQuery, renderSurface, resolveView, runLifecycle, resolveOptions, installContext, recordOf, defaultsOf };
+module.exports = { argumentsFor, makePorts, runWorkflow, resumeWorkflow, runQuery, renderSurface, resolveView, runLifecycle, resolveOptions, installContext, recordOf, defaultsOf };

package/integrations/data-defined/schema/capability-manifest.v0.1.schema.json

@@ -411,6 +411,15 @@
             "body": {}
           },
           "description": "Answered at receipt, before anything is queued (Slack url_verification, Asana X-Hook-Secret)."
+        },
+        "status": {
+          "enum": [
+            "unimplemented"
+          ],
+          "description": "The module's Api has no `verify` method (or none that checks a signature). Every delivery fails verification until it does, so definitions that trigger on this module's events validate with a warning."
+        },
+        "note": {
+          "type": "string"
         }
       }
     },
@@ -445,6 +454,37 @@
           },
           "output": {
             "type": "string"
+          },
+          "args": {
+            "type": "array",
+            "description": "How the Api method takes its arguments, when it is not one object holding every input. Each entry is an input name (passed positionally), \"$rest\" (an object of every input not named elsewhere in the list) or {\"value\": x} (a constant, such as the sObject name of a generic Api). Omitted: the method is called with one object of all inputs.",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "value"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "value": {}
+                  }
+                }
+              ]
+            }
+          },
+          "status": {
+            "enum": [
+              "unimplemented"
+            ],
+            "description": "The module's real Api class has no method that does this (or none shaped so the call can be made). Definitions that use it validate with a warning, never an error."
+          },
+          "note": {
+            "type": "string",
+            "description": "What the real method does differently, or what is missing upstream."
           }
         }
       }