@friggframework/core 2.0.0--canary.698.b1a2d30.0 → 2.0.0--canary.699.0d57ee8.0

package/integrations/{data-defined/data-defined-integration.js → definitions/integration-runtime.js}

@@ -1,10 +1,10 @@
 /**
- * DataDefinedIntegration: one IntegrationBase subclass that runs any published definition.
+ * IntegrationRuntime: one IntegrationBase subclass that runs any published definition.
  *
- * Frigg registers integration classes at startup (appDefinition.integrations). For data-defined integrations the app
+ * Frigg registers integration classes at startup (appDefinition.integrations). For integrations published as definitions the app
  * registers one generated class per definition id:
  *
- *     const { defineIntegrationClass } = require('@friggframework/core/integrations/data-defined');
+ *     const { defineIntegrationClass } = require('@friggframework/core/integrations/definitions');
  *     integrations: [ defineIntegrationClass({ id: 'phone-hubspot', definitions, manifests, modules: { phone: PhoneModule, hubspot: HubSpotModule } }) ]
  *
  * The class's static Definition (name, modules) is what the infrastructure needs, and it is the same for every
@@ -23,7 +23,7 @@ const { createSyncEngine } = require('./sync-engine');
 const { eventsIn, handshakeFor, modulesFor } = require('./webhooks');
 const { buildConfigForm, missingRequired } = require('./config-form');
 
-/** The tick every data-defined trigger runs on: a chosen interval is rounded up to whole multiples of it. */
+/** The tick every trigger of a published definition runs on: a chosen interval is rounded up to whole multiples of it. */
 const INSTANCE_TICK = '5m';
 
 /** A compiled definition's triggers as IntegrationBase trigger declarations: each runs its compiled event. */
@@ -44,7 +44,7 @@ function triggersOf(def, config) {
  * definition. Publishing a new VERSION deploys nothing; a new definition ID is a new class (a deploy, and its own
  * functions and queue). Right for a product team with a handful of integrations.
  *
- * Shape B — one class for every definition (defineSharedIntegrationClass): registered once as "data-defined", its
+ * Shape B — one class for every definition (defineSharedIntegrationClass): registered once as "integration-runtime", its
  * static modules are every API module the app has installed, and each installation names its definition id and
  * version in config. A new integration is a row, not a deploy, and every installation shares one set of functions
  * and one queue. Right for a multi-tenant product, where definitions accumulate without bound.
@@ -60,11 +60,11 @@ function defineIntegrationClass({ id, definitions, manifests, modules, runCode,
     });
 }
 
-function defineSharedIntegrationClass({ name = 'data-defined', definitions, manifests, modules, runCode, IntegrationBase, lookup, runs }) {
+function defineSharedIntegrationClass({ name = 'integration-runtime', definitions, manifests, modules, runCode, IntegrationBase, lookup, runs }) {
     return makeClass({
         name, defaultId: null, definitions, manifests, runCode, IntegrationBase, lookup, runs,
         modules: Object.fromEntries(Object.entries(modules).map(([key, definition]) => [key, { definition }])),
-        display: { label: 'Data-defined integration', description: 'Runs any published integration definition.', category: 'Custom' },
+        display: { label: 'Integration runtime', description: 'Runs any published integration definition.', category: 'Custom' },
         version: '0.1.0',
     });
 }
@@ -132,7 +132,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
     // database can pass their own store or `false` to keep none).
     let runStore = runs;
     // App-level webhooks fan out to the installations of every type this deployment runs.
-    const findInstallations = (externalId, moduleName, Cls) => (lookup || friggLookup(async (type) => type === id || type === Cls.Definition.name || Boolean(await DataDefinedIntegration.IntegrationProvider?.resolve(type))))(externalId, moduleName);
+    const findInstallations = (externalId, moduleName, Cls) => (lookup || friggLookup(async (type) => type === id || type === Cls.Definition.name || Boolean(await IntegrationRuntime.IntegrationProvider?.resolve(type))))(externalId, moduleName);
     const runRepository = () => (runStore === undefined ? (runStore = require('./repositories/workflow-run-repository').createWorkflowRunRepository()) : runStore);
     const baseFor = (typeName) => `${process.env.FRIGG_PUBLIC_URL || ''}/api/${typeName}-integration/webhooks`;
     const pinnedDefinitions = new Map();   // `${id}@${version}` -> definition, for the trigger tick
@@ -142,7 +142,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
     // A code class's own Definition.triggers (IntegrationBase.triggersFor), kept beside the compiled ones.
     const codeTriggers = async (Cls, installation) => (embedded && typeof Base.triggersFor === 'function' ? Base.triggersFor.call(Cls, installation) : []);
 
-    class DataDefinedIntegration extends Base {
+    class IntegrationRuntime extends Base {
         // version is display only; installations pin their own. A code class keeps every part of its Definition.
         // instanceTriggers: schedule-triggered workflows and polling syncs are this class's recurring triggers,
         // resolved per installation (triggersFor) on one 5m tick.
@@ -190,8 +190,8 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             return [...new Set([own, ...provided])];
         }
 
-        /** How the routers find data-defined classes and the store and manifests they run on. */
-        static DataDefined = { definitions, manifests, shared: !defaultId, runs: () => runRepository() };
+        /** How the routers find integration runtime classes and the store and manifests they run on. */
+        static IntegrationRuntime = { definitions, manifests, shared: !defaultId, runs: () => runRepository() };
 
         /** Shape A: the one definition this class runs. A class generated for a published definition sets its own. */
         static definitionId = defaultId;
@@ -315,7 +315,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             if (embedded && !ownsWebhooks(this.def)) return super.onWebhook(params);
             const { data = {} } = params || {};
             if (data.module && data.topic) return this.routeEvents(data.module, [{ topic: data.topic, event: data.body, eventId: data.eventId || data.body?.id || null }]);
-            const delivery = { body: data.body, headers: data.headers || {}, query: data.query || {} };
+            const delivery = { body: data.body, headers: data.headers || {}, query: data.query || {}, rawBody: data.rawBody, method: data.method, url: data.url };
             // No installation yet (an app-level webhook): find the ones it is for.
             if (!this.id || !this.def) return this.fanOutAppWebhook(delivery);
 
@@ -325,7 +325,8 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             const manifest = manifests[this.def.modules[key].module];
             if (manifest.webhook?.verify) {
                 let ok = false;
-                try { ok = await this.moduleFor(key).api[manifest.webhook.verify]({ headers: delivery.headers, body: delivery.body, query: delivery.query }); } catch { ok = false; }
+                // The raw body, method and URL travel from receipt (IntegrationBase.onWebhookReceived): vendors sign bytes.
+                try { ok = await this.moduleFor(key).api[manifest.webhook.verify]({ headers: delivery.headers, body: delivery.body, query: delivery.query, rawBody: delivery.rawBody, method: delivery.method, url: delivery.url }); } catch { ok = false; }
                 if (ok !== true) { this.logWebhook('webhook.rejected', { module: key }); return { routed: 0, rejected: true }; }
             }
             const own = this.accountOf(key);
@@ -352,7 +353,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             let queued = 0;
             for (const account of accounts) {
                 for (const integrationId of await findInstallations(account, moduleName, this.constructor)) {
-                    await this.queueWebhook({ integrationId, body: delivery.body, headers: delivery.headers, query: delivery.query });
+                    await this.queueWebhook({ integrationId, body: delivery.body, headers: delivery.headers, query: delivery.query, rawBody: delivery.rawBody, method: delivery.method, url: delivery.url });
                     queued += 1;
                 }
             }
@@ -366,7 +367,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
         }
 
         logWebhook(eventName, fields) {
-            try { require('../../logs').getLogger('frigg.data-defined').info('Webhook not routed', { eventName: `frigg.data-defined.${eventName}`, integrationId: this.id || null, ...fields }); } catch { /* logging must never break delivery */ }
+            try { require('../../logs').getLogger('frigg.integrations.runtime').info('Webhook not routed', { eventName: `frigg.integrations.runtime.${eventName}`, integrationId: this.id || null, ...fields }); } catch { /* logging must never break delivery */ }
         }
 
         async onCreate(params) {
@@ -419,7 +420,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                     const store = runRepository();
                     if (store) await store.createRun({ integrationId: this.id, definitionId: name, definitionVersion: this.def?.version, workflowId: event, triggerType: 'code', status, error: error ? String(error.message || error) : null, retryable: Boolean(error), trace: [], startedAt, endedAt: new Date().toISOString() });
                 } catch (e) {
-                    try { require('../../logs').getLogger('frigg.data-defined').warn('Workflow run not recorded', { eventName: 'frigg.data-defined.run.not_recorded', integrationId: this.id, workflowId: event, cause: e?.message }); } catch { /* ignore */ }
+                    try { require('../../logs').getLogger('frigg.integrations.runtime').warn('Workflow run not recorded', { eventName: 'frigg.integrations.runtime.run.not_recorded', integrationId: this.id, workflowId: event, cause: e?.message }); } catch { /* ignore */ }
                 }
             };
             let out;
@@ -527,7 +528,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                 if (store && rowId && store.updateRun) row = await store.updateRun(rowId, { status: run.status, reason: run.reason, error: run.error, retryable: Boolean(run.retryable), trace: run.trace, waitingFor: run.waitingFor ?? null, resumeAt: run.resumeAt ?? null, endedAt: run.endedAt ?? null });
                 else if (store) row = await store.createRun({ ...stored, runKey: run.id, integrationId: this.id, definitionId: run.definition?.id, definitionVersion: run.definition?.version, triggerType: run.trigger?.type, eventId: run.trigger?.eventId });
             } catch (e) {
-                try { require('../../logs').getLogger('frigg.data-defined').warn('Workflow run not recorded', { eventName: 'frigg.data-defined.run.not_recorded', integrationId: this.id, workflowId: run.workflowId, cause: e?.message }); } catch { /* ignore */ }
+                try { require('../../logs').getLogger('frigg.integrations.runtime').warn('Workflow run not recorded', { eventName: 'frigg.integrations.runtime.run.not_recorded', integrationId: this.id, workflowId: run.workflowId, cause: e?.message }); } catch { /* ignore */ }
             }
             if (run.status === 'waiting' && row?.id && !rowId) await this.mappingStore().put(`wait:${run.id}`, { ...(await this.mappingStore().get(`wait:${run.id}`)), rowId: row.id });
             if (run.status === 'failed') { const e = new Error(run.error); e.run = run; throw e; } // the queue retries
@@ -560,7 +561,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                 queueUrl: typeof this.scheduleQueueUrl === 'function' ? this.scheduleQueueUrl() : process.env[`${name.toUpperCase().replace(/-/g, '_')}_QUEUE_URL`],
             });
             if (booked?.error || booked?.warning) {
-                try { require('../../logs').getLogger('frigg.data-defined').error('Run resume not booked', { eventName: 'frigg.data-defined.run.resume_not_booked', integrationId: this.id, runId: run.id, kind: cp.wait.kind, reason: booked.reason || booked.warning }); } catch { /* ignore */ }
+                try { require('../../logs').getLogger('frigg.integrations.runtime').error('Run resume not booked', { eventName: 'frigg.integrations.runtime.run.resume_not_booked', integrationId: this.id, runId: run.id, kind: cp.wait.kind, reason: booked.reason || booked.warning }); } catch { /* ignore */ }
             }
         }
 
@@ -678,9 +679,9 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             return out;
         }
     }
-    Object.defineProperty(DataDefinedIntegration, 'name', { value: `DataDefined_${id.replace(/-/g, '_')}` });
-    if (!defaultId) DataDefinedIntegration.IntegrationProvider = definitionProvider(DataDefinedIntegration, definitions);
-    return DataDefinedIntegration;
+    Object.defineProperty(IntegrationRuntime, 'name', { value: `IntegrationRuntime_${id.replace(/-/g, '_')}` });
+    if (!defaultId) IntegrationRuntime.IntegrationProvider = definitionProvider(IntegrationRuntime, definitions);
+    return IntegrationRuntime;
 }
 
 /**

package/integrations/{data-defined → definitions}/renderers/hubspot.js

@@ -1,9 +1,14 @@
 /**
- * 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.
+ * Resolved view tree -> a JSON description of HubSpot UI-extension components. Names and prop values were checked
+ * against @hubspot/ui-extensions 0.17.1 (its shared.synced/types/components/*.d.ts). Data, not React: a thin card
+ * deployed once maps `{ type, props, children }` onto `React.createElement(components[type], props, ...children)`, 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.
+ * A node is `{ type, props?, children?, action? }`; a child is a string (text) or a node. Strings are text, never markup.
+ * `props` holds only real component props, passed straight through. `action` is OURS, not a HubSpot prop: the card must
+ * not spread it onto the component, but turn it into `onClick={() => runServerless(...)}` that posts it to the actions
+ * endpoint (a userAction button), because a UI extension cannot call out except through a serverless function.
+ * An `open_url` button needs no action: it is the real `href` prop, which the host opens in a new tab.
  */
 const { str, safeUrl, toneOf } = require('./common');
 
@@ -11,7 +16,7 @@ const { str, safeUrl, toneOf } = require('./common');
 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 } : {}) });
+const node = (type, props, children, action) => ({ type, ...(props && Object.keys(props).length ? { props } : {}), ...(action ? { action } : {}), ...(children && children.length ? { children } : {}) });
 
 /**
  * @param {object|null} view
@@ -34,16 +39,16 @@ function viewToHubSpot(view, { integrationId, surface } = {}) {
                 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 'Empty': return node('EmptyState', { layout: 'vertical' }, [node('Text', {}, [str(p.text)])]);
             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) };
+                const href = a?.type === 'open_url' ? safeUrl(a.url) : null;
                 // 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']);
+                return node('Button', { variant, ...(href ? { href } : action ? {} : { disabled: true }) }, [str(p.label) || 'Open'], action);
             }
             default: return kids().length === 1 ? kids()[0] : node('Flex', { direction: 'column', gap: 'sm' }, kids());
         }

package/integrations/{data-defined → definitions}/router.js

@@ -1,11 +1,11 @@
 /**
  * HTTP routes for integration versions, run history, sync progress and approvals, mounted by createIntegrationRouter
- * when the app registers the integration runtime (a class with `DataDefined`). They answer for EVERY integration,
+ * when the app registers the integration runtime (a class with `IntegrationRuntime`). They answer for EVERY integration,
  * however it was made: an integration with no run history, syncs or other versions gets an empty answer, not a 404.
  * Thin adapters: authenticate, call a use case, map the result to a status.
  *
  * Signed-in users (Frigg's usual authentication: bearer token, x-frigg headers or adopter JWT):
- *   GET  /api/data-defined/definitions                   what can be installed: latest published version of each
+ *   GET  /api/integration-definitions                   what can be installed: latest published version of each
  *                                                        (GET /api/integrations lists the same types as options)
  *   GET  /api/integrations/:integrationId/upgrade?to=    the upgrade plan for an installation (changes nothing)
  *   POST /api/integrations/:integrationId/upgrade        { to? } apply it (refused while anything is needed)
@@ -46,7 +46,7 @@ const noUpgrade = (integration) => ({
  * auth: 'user' = a signed-in user (the workspace is the user's Frigg id), 'admin' = x-frigg-admin-api-key.
  */
 const DEFINITION_ROUTES = Object.freeze({
-    catalogue:        { method: 'GET',  path: '/api/data-defined/definitions', auth: 'user' },
+    catalogue:        { method: 'GET',  path: '/api/integration-definitions', auth: 'user' },
     upgradePlan:      { method: 'GET',  path: '/api/integrations/:integrationId/upgrade', auth: 'user' },
     upgradeApply:     { method: 'POST', path: '/api/integrations/:integrationId/upgrade', auth: 'user' },
     runs:             { method: 'GET',  path: '/api/integrations/:integrationId/runs', auth: 'user' },
@@ -71,21 +71,21 @@ const guard = (fn) => catchAsyncError(async (req, res) => { try { await fn(req,
  * @param {{ execute(req): Promise<{ getId(): string }> }} authenticateUser
  * @param {{ getIntegrationInstance, integrationClasses: Function[] }} deps
  */
-function setDataDefinedRoutes(router, authenticateUser, { getIntegrationInstance, integrationClasses }) {
-    const classes = integrationClasses.filter((c) => c.DataDefined);
+function setIntegrationRuntimeRoutes(router, authenticateUser, { getIntegrationInstance, integrationClasses }) {
+    const classes = integrationClasses.filter((c) => c.IntegrationRuntime);
     if (!classes.length) return false;
-    const catalogClass = classes.find((c) => c.DataDefined.shared) || classes[0];
-    const { definitions, manifests } = catalogClass.DataDefined;
+    const catalogClass = classes.find((c) => c.IntegrationRuntime.shared) || classes[0];
+    const { definitions, manifests } = catalogClass.IntegrationRuntime;
 
     const installation = async (req) => {
         const user = await authenticateUser.execute(req);
         return getIntegrationInstance.execute(req.params.integrationId, user.getId());
     };
-    const runtimeOf = (integration) => integration?.constructor?.DataDefined || null;
+    const runtimeOf = (integration) => integration?.constructor?.IntegrationRuntime || null;
 
     router.route(path('catalogue')).get(guard(async (req, res) => {
         const user = await authenticateUser.execute(req);
-        const lists = await Promise.all(classes.map((c) => (c.DataDefined.definitions.list ? c.DataDefined.definitions.list({ workspaceId: String(user.getId()) }) : [])));
+        const lists = await Promise.all(classes.map((c) => (c.IntegrationRuntime.definitions.list ? c.IntegrationRuntime.definitions.list({ workspaceId: String(user.getId()) }) : [])));
         const seen = new Set();
         res.json({ definitions: lists.flat().filter((d) => (seen.has(d.id) ? false : seen.add(d.id))) });
     }));
@@ -105,7 +105,7 @@ function setDataDefinedRoutes(router, authenticateUser, { getIntegrationInstance
 
     router.route(path('runs')).get(guard(async (req, res) => {
         const integration = await installation(req);
-        const store = runtimeOf(integration)?.runs() || catalogClass.DataDefined.runs();
+        const store = runtimeOf(integration)?.runs() || catalogClass.IntegrationRuntime.runs();
         if (!store) return res.json({ runs: [] });
         const { workflowId, status, before, limit } = req.query;
         res.json({ runs: await store.listRuns(integration.id, { workflowId, status, before, limit: limit ? Number(limit) : undefined }) });
@@ -167,4 +167,4 @@ function setDataDefinedRoutes(router, authenticateUser, { getIntegrationInstance
     return true;
 }
 
-module.exports = { setDataDefinedRoutes, DEFINITION_ROUTES };
+module.exports = { setIntegrationRuntimeRoutes, DEFINITION_ROUTES };

package/integrations/{data-defined → definitions}/runtime.js

@@ -1,5 +1,5 @@
 /**
- * The pieces DataDefinedIntegration wires to Frigg. Each takes its I/O as arguments, so the whole runtime can be
+ * The pieces IntegrationRuntime wires to Frigg. Each takes its I/O as arguments, so the whole runtime can be
  * driven in a test with fakes and the same code runs in Lambda.
  *
  *   makePorts      capability calls go through the module manifest to an Api method; links live in IntegrationMapping

package/integrations/{data-defined → definitions}/schema/installation.v0.1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://friggframework.org/schemas/installation/v0.1.json",
-  "title": "Data-defined installation config v0.1",
+  "title": "Installation config v0.1",
   "description": "What one customer chose, stored as Integration.config. The definition says what is possible; this says what is on.",
   "type": "object",
   "required": [

package/integrations/{data-defined → definitions}/schema/records.md

@@ -1,4 +1,4 @@
-# Data-defined integrations: database records (v0.1)
+# Integrations published as definitions: database records (v0.1)
 
 Three layers, stored separately. Worked examples for Phone ↔ HubSpot are in `examples/records/`.
 

package/integrations/{data-defined → definitions}/scripts/validate.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Validate data-defined integration definitions and capability manifests: JSON Schema, then references.
+ * Validate integration definitions and capability manifests: JSON Schema, then references.
  *
  *   node scripts/validate.js                       every bundled manifest and example
  *   node scripts/validate.js my.definition.json    one or more definitions (files or directories)

package/integrations/{data-defined → definitions}/use-cases/definition-use-cases.js

@@ -1,5 +1,5 @@
 /**
- * Application layer for data-defined integrations (ADR-063): publishing definition versions, the catalogue the
+ * Application layer for integrations published as definitions (ADR-063): publishing definition versions, the catalogue the
  * runtime reads from, and per-installation upgrades. Business rules live here; the repositories only store rows.
  *
  *   createDefinitionCatalog()        what defineSharedIntegrationClass({ definitions }) reads: get(id, version), latest(id)

package/integrations/{data-defined → definitions}/versioning.js

@@ -1,5 +1,5 @@
 /**
- * Versioning for data-defined integrations.
+ * Versioning for integrations published as definitions.
  *
  * A published version is immutable and every installation pins one exact version, so a release never changes a
  * running customer until that installation is upgraded. Three questions are answered here:

package/integrations/integration-base.js

@@ -46,6 +46,26 @@ const constantsToBeMigrated = {
     },
 };
 
+/**
+ * The facts about a webhook request that signature checks need, small enough to travel in the queue message: the
+ * method, the public URL the vendor called, and the raw body (up to 96 KB; beyond that it is left out and a check that
+ * needs it fails closed, because SQS messages are capped at 256 KB and the parsed body travels too).
+ */
+const RAW_BODY_LIMIT = 96 * 1024;
+function webhookRequestFacts(req) {
+    const h = req.headers || {};
+    const proto = String(h['x-forwarded-proto'] || req.protocol || 'https').split(',')[0].trim();
+    const host = h['x-forwarded-host'] || h.host;
+    const url = host ? `${proto}://${host}${req.originalUrl || req.url || ''}` : undefined;
+    const raw = req.rawBody;
+    const rawBody = raw == null ? undefined : (Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw));
+    return {
+        method: req.method,
+        ...(url ? { url } : {}),
+        ...(rawBody !== undefined && Buffer.byteLength(rawBody) <= RAW_BODY_LIMIT ? { rawBody } : {}),
+    };
+}
+
 class IntegrationBase {
     // todo: maybe we can pass this as Dependency Injection in the sub-class constructor
     integrationRepository = createIntegrationRepository();
@@ -552,7 +572,7 @@ class IntegrationBase {
     /**
      * The recurring triggers declared for one installation (ADR-055): `Definition.triggers`, each with its `name`.
      * Static so the tick can read them from a record without hydrating the installation; a class whose triggers
-     * depend on the installation (data-defined integrations, `Definition.instanceTriggers`) overrides it.
+     * depend on the installation (integrations published as definitions, `Definition.instanceTriggers`) overrides it.
      * @param {{ config?: Object, record?: Object }} [installation]
      * @returns {Promise<Array<Object>>}
      */
@@ -699,6 +719,7 @@ class IntegrationBase {
             body,
             headers: req.headers,
             query: req.query,
+            ...webhookRequestFacts(req),
         });
 
         res.status(200).json({ received: true });
@@ -708,6 +729,15 @@ class IntegrationBase {
         // Default: no-op, integrations override this
     }
 
+    /**
+     * What a module's verifyWebhookSignature needs about a queued delivery (onWebhookReceived put it there): the
+     * headers, the parsed body, the raw body exactly as received, and the method and public URL some vendors sign
+     * (HubSpot v3). Call as `this.<module>.api.verifyWebhookSignature(this.webhookVerificationInput(data))`.
+     */
+    webhookVerificationInput(data = {}) {
+        return { headers: data.headers || {}, body: data.body, query: data.query || {}, rawBody: data.rawBody, method: data.method, url: data.url };
+    }
+
     /**
      * Queue a webhook for asynchronous worker dispatch.
      *

package/integrations/integration-router.js

@@ -210,7 +210,7 @@ function createIntegrationRouter() {
         getPossibleIntegrations,
     });
     // Integration versions, run history, sync progress and approvals (ADR-063): mounted when the app registers the integration runtime.
-    require('./data-defined/router').setDataDefinedRoutes(router, authenticateUser, {
+    require('./definitions/router').setIntegrationRuntimeRoutes(router, authenticateUser, {
         getIntegrationInstance,
         integrationClasses,
     });

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.698.b1a2d30.0",
+    "version": "2.0.0--canary.699.0d57ee8.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.698.b1a2d30.0",
-        "@friggframework/prettier-config": "2.0.0--canary.698.b1a2d30.0",
-        "@friggframework/test": "2.0.0--canary.698.b1a2d30.0",
+        "@friggframework/eslint-config": "2.0.0--canary.699.0d57ee8.0",
+        "@friggframework/prettier-config": "2.0.0--canary.699.0d57ee8.0",
+        "@friggframework/test": "2.0.0--canary.699.0d57ee8.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -67,7 +67,7 @@
     "scripts": {
         "lint:fix": "prettier --write --loglevel error . && eslint . --fix",
         "test": "jest --passWithNoTests # TODO",
-        "validate:definitions": "node integrations/data-defined/scripts/validate.js",
+        "validate:definitions": "node integrations/definitions/scripts/validate.js",
         "prisma:generate:mongo": "npx prisma generate --schema ./prisma-mongodb/schema.prisma",
         "prisma:generate:postgres": "npx prisma generate --schema ./prisma-postgresql/schema.prisma",
         "prisma:generate": "npm run prisma:generate:mongo && npm run prisma:generate:postgres",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "b1a2d30f3296992d698742a0c0a99b916c7fbfbe"
+    "gitHead": "0d57ee8eff44caba64a32685026c122cae03580f"
 }

package/prisma-mongodb/schema.prisma

@@ -455,7 +455,7 @@ model UsageCounter {
   @@map("UsageCounter")
 }
 
-// Data-defined integrations (ADR-063): one immutable row per published definition version.
+// Integrations published as definitions (ADR-063): one immutable row per published definition version.
 enum DefinitionStatus {
   DRAFT
   PUBLISHED
@@ -487,7 +487,7 @@ model IntegrationDefinitionVersion {
   @@map("IntegrationDefinitionVersion")
 }
 
-// One row per data-defined workflow run. trace holds step ids, statuses, timings and error messages, never request or
+// One row per workflow run. trace holds step ids, statuses, timings and error messages, never request or
 // response bodies.
 model WorkflowRun {
   id                String      @id @default(auto()) @map("_id") @db.ObjectId

package/prisma-postgresql/schema.prisma

@@ -436,7 +436,7 @@ model UsageCounter {
   @@index([metric, integrationType, window])
 }
 
-// Data-defined integrations (ADR-063): one immutable row per published definition version.
+// Integrations published as definitions (ADR-063): one immutable row per published definition version.
 enum DefinitionStatus {
   DRAFT
   PUBLISHED
@@ -467,7 +467,7 @@ model IntegrationDefinitionVersion {
   @@index([workspaceId, status])
 }
 
-// One row per data-defined workflow run. trace holds step ids, statuses, timings and error messages, never request or
+// One row per workflow run. trace holds step ids, statuses, timings and error messages, never request or
 // response bodies.
 model WorkflowRun {
   id                Int         @id @default(autoincrement())