@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.694.f66a64a.0

package/integrations/data-defined/webhooks.js

@@ -0,0 +1,119 @@
+/**
+ * Turning a provider's webhook delivery into the module events a definition listens for. Pure; no I/O.
+ *
+ * Providers disagree about everything: where the topic is (a body field, a header, two fields combined), whether one
+ * POST carries one event or a batch (HubSpot sends an array, QuickBooks nests entities inside notifications), which
+ * account it is about, and whether the first request is a handshake to answer synchronously (Slack url_verification,
+ * Asana X-Hook-Secret). A manifest says so in its `webhook` block, with the same template expressions definitions
+ * use, so none of it is code:
+ *
+ *   "webhook": {
+ *     "scope": "app",                                   // one URL for every account ("installation": one per install)
+ *     "batch": "body",                                  // path to the array of events; [outer, inner] for two levels
+ *     "topic": "{{item.subscriptionType}}",             // the provider's topic; a list tries each until one is non-empty
+ *     "eventId": "{{item.eventId}}",                    // dedupe id
+ *     "account": "{{item.portalId}}",                   // the connected account (entity externalId) the event is about
+ *     "verify": "verifyWebhookSignature",               // optional Api method: ({ headers, body, query }) -> boolean
+ *     "handshake": { "when": "...", "status": 200, "headers": {...}, "body": {...} },
+ *     "unwrap": "payload"                               // a form-encoded field holding the JSON body (Slack interactivity)
+ *   }
+ *
+ * and each event says which provider topic it is (`match`, default: the event key) and optionally a condition on the
+ * record (`when`): a phone module reports a missed call as call.completed with status missed.
+ *
+ * Template context: { body, headers, query, item, parent }. `item` is the event (the body itself when there is no
+ * batch); `parent` is the outer item of a two-level batch (a QuickBooks notification, which carries the realmId).
+ */
+const { resolve, evaluate, getPath } = require('./expressions');
+
+const list = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+const str = (v) => (v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v));
+
+/** The first template in `tpls` that renders to a non-empty string. */
+function renderFirst(tpls, ctx) {
+    for (const t of list(tpls)) {
+        const v = str(resolve(t, ctx)).trim();
+        if (v) return v;
+    }
+    return '';
+}
+
+/** Lower-case header names, as Express and Lambda deliver them, so manifests can always write headers.x-shopify-topic. */
+function normaliseHeaders(headers = {}) {
+    return Object.fromEntries(Object.entries(headers || {}).map(([k, v]) => [k.toLowerCase(), Array.isArray(v) ? v[0] : v]));
+}
+
+/** The delivery as the manifest sees it: lower-case headers, and the JSON body unwrapped from a form field if declared. */
+function prepare(webhook = {}, delivery) {
+    let body = delivery.body;
+    if (webhook.unwrap && body && typeof body[webhook.unwrap] === 'string') {
+        try { body = JSON.parse(body[webhook.unwrap]); } catch { /* not JSON: leave the body as delivered */ }
+    }
+    return { body, headers: normaliseHeaders(delivery.headers), query: delivery.query || {} };
+}
+
+/** Split one delivery into events: [{ item, parent }]. */
+function splitBatch(webhook = {}, input) {
+    const paths = list(webhook.batch);
+    const at = (obj, p) => (p === 'body' ? obj.body : p === '$' ? obj : getPath(obj, '$.' + p));
+    if (!paths.length) return [{ item: input.body, parent: null }];
+    const outer = at(input, paths[0]);
+    const outerItems = Array.isArray(outer) ? outer : outer == null ? [] : [outer];
+    if (paths.length === 1) return outerItems.map((item) => ({ item, parent: null }));
+    return outerItems.flatMap((parent) => {
+        const inner = getPath(parent, '$.' + paths[1]);
+        return (Array.isArray(inner) ? inner : inner == null ? [] : [inner]).map((item) => ({ item, parent }));
+    });
+}
+
+/**
+ * Every module event in one delivery.
+ * @param {object} manifest   the module's capability manifest
+ * @param {{ body, headers?, query? }} delivery
+ * @returns {Array<{ topic: string, providerTopic: string, eventId: string|null, account: string|null, event: object, record: any }>}
+ *          topic is the manifest's event key (what definitions name); event is the item the workflow sees as $.event.
+ */
+function eventsIn(manifest, delivery) {
+    const webhook = manifest?.webhook;
+    if (!webhook) return [];
+    const input = prepare(webhook, delivery);
+    const out = [];
+    for (const { item, parent } of splitBatch(webhook, input)) {
+        const ctx = { ...input, item, parent };
+        const providerTopic = renderFirst(webhook.topic, ctx);
+        if (!providerTopic) continue;
+        const eventId = renderFirst(webhook.eventId, ctx) || null;
+        const account = webhook.account ? renderFirst(webhook.account, ctx) || null : null;
+        for (const [key, ev] of Object.entries(manifest.events || {})) {
+            if (ev.delivery && ev.delivery !== 'webhook') continue;
+            if ((ev.match ?? key) !== providerTopic) continue;
+            const record = ev.record ? getPath(item, '$.' + ev.record) : item;
+            if (ev.when && !evaluate(ev.when, { event: item, record, headers: input.headers, parent })) continue;
+            out.push({ topic: key, providerTopic, eventId, account, event: item, record });
+        }
+    }
+    return out;
+}
+
+/** A handshake to answer at receipt, before anything is queued: { status, headers, body } or null. */
+function handshakeFor(manifest, delivery) {
+    const h = manifest?.webhook?.handshake;
+    if (!h) return null;
+    const ctx = prepare(manifest.webhook, delivery);
+    if (!evaluate(h.when, ctx)) return null;
+    return { status: h.status || 200, headers: resolve(h.headers || {}, ctx), body: h.body === undefined ? '' : resolve(h.body, ctx) };
+}
+
+/**
+ * Which module of a definition a delivery came from. The URL names it (?module=<module name>); without that, the one
+ * module whose manifest recognises an event in the body. Returns module keys of the definition (usually one).
+ */
+function modulesFor(def, manifests, delivery) {
+    const named = delivery.query?.module;
+    const keys = Object.entries(def.modules || {}).filter(([, m]) => (named ? m.module === named : true)).map(([k]) => k);
+    if (named) return keys;
+    const recognised = keys.filter((k) => eventsIn(manifests[def.modules[k].module], delivery).length > 0);
+    return recognised.length === 1 ? recognised : [];
+}
+
+module.exports = { eventsIn, handshakeFor, modulesFor, splitBatch, renderFirst, normaliseHeaders };

package/integrations/index.js

@@ -21,7 +21,6 @@ module.exports = {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
-    // Deprecated (ADR-059): a wrapper over getEntityTypeRegistry.
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     validateExtensionBinding,

package/integrations/integration-base.js

@@ -22,6 +22,7 @@ const { getTelemetry } = require('../telemetry/telemetry-runtime');
 const { instrumentHandler } = require('../telemetry/instrument-handler');
 const { bindTelemetryContext } = require('../telemetry/bind-telemetry-context');
 const { getLogger } = require('../logs');
+const { TRIGGER_RUN, TRIGGER_TICK, resolveTrigger } = require('./triggers');
 
 const constantsToBeMigrated = {
     defaultEvents: {
@@ -35,6 +36,8 @@ const constantsToBeMigrated = {
         REFRESH_USER_ACTION_OPTIONS: 'REFRESH_USER_ACTION_OPTIONS',
         WEBHOOK_RECEIVED: 'WEBHOOK_RECEIVED', // HTTP handler, no DB
         ON_WEBHOOK: 'ON_WEBHOOK', // Queue worker, DB-connected
+        [TRIGGER_RUN]: TRIGGER_RUN, // Queue worker: one recurring trigger run (ADR-055)
+        [TRIGGER_TICK]: TRIGGER_TICK, // Queue worker: a trigger tick carrying on from its page cursor
         // etc...
     },
     types: {
@@ -91,6 +94,9 @@ class IntegrationBase {
         extensions: {},
         // usage: { canonical: ['records.synced'], custom: { 'deals.enriched': { unit, label } } }
         usage: {},
+        // Recurring triggers (ADR-055) — see integrations/triggers.js
+        // Shape: { [name]: { every | at | cron, timezone?, tick?, when?, overlap?, configurable?, handler } }
+        triggers: {},
         display: {
             name: 'Integration Name',
             logo: '',
@@ -171,6 +177,14 @@ class IntegrationBase {
                 type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
                 handler: this.onWebhook,
             },
+            [TRIGGER_RUN]: {
+                type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
+                handler: this.onTriggerRun,
+            },
+            [TRIGGER_TICK]: {
+                type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
+                handler: this.onTriggerTick,
+            },
         };
     }
 
@@ -457,6 +471,35 @@ class IntegrationBase {
         );
     }
 
+    /**
+     * Insert-only mapping write; usable as an atomic claim/lock row.
+     * @throws {MappingAlreadyExistsError} If a mapping for sourceId exists
+     */
+    async createMapping(sourceId, mapping) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.createMapping(
+            this.id,
+            sourceId,
+            mapping
+        );
+    }
+
+    /**
+     * Deletes the mapping for sourceId. A missing mapping is not an error
+     * (resolves with deletedCount 0).
+     */
+    async deleteMapping(sourceId) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.deleteMapping(
+            this.id,
+            sourceId
+        );
+    }
+
     /**
      * CHILDREN CAN OVERRIDE THESE CONFIGURATION METHODS
      */
@@ -493,10 +536,84 @@ class IntegrationBase {
         } else if (this.status === 'NEEDS_CONFIG') {
             await this.persistStatus('ENABLED');
         }
+        await this.reportTriggerChoices();
     }
 
     async onDelete(params) {}
 
+    /**
+     * 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.
+     * @param {{ config?: Object, record?: Object }} [installation]
+     * @returns {Promise<Array<Object>>}
+     */
+    static async triggersFor(installation = {}) {
+        return Object.entries(this.Definition?.triggers || {}).map(([name, t]) => ({ ...t, name }));
+    }
+
+    /** This installation's trigger declarations (the static `triggersFor`, unless a subclass knows better). */
+    async triggerDeclarations() {
+        return this.constructor.triggersFor({ config: this.config || {}, record: this.record });
+    }
+
+    /**
+     * Run one recurring trigger: the queue worker dispatches `FRIGG_TRIGGER_RUN` here with
+     * `{ integrationId, trigger, scheduledFor }` after hydrating the installation. The handler is called as
+     * `handler(payload, ctx)` with `payload = { trigger, scheduledFor }` and `ctx = { modules, config, log, integration }`
+     * (ADR-054); a string handler names a method on this instance. Overlap and the run record: use-cases/run-trigger.js.
+     */
+    async onTriggerRun({ data = {} } = {}) {
+        const declarations = await this.triggerDeclarations();
+        const declaration = declarations.find((t) => t.name === data.trigger);
+        const resolved = declaration ? resolveTrigger(declaration.name, declaration, this.config || {}) : null;
+        const payload = { trigger: data.trigger, scheduledFor: data.scheduledFor };
+        const invoke = async (p) => {
+            const handler = typeof declaration.handler === 'string' ? this[declaration.handler] : declaration.handler;
+            if (typeof handler !== 'function') throw new Error(`Trigger "${declaration.name}" handler "${declaration.handler}" is not a method of ${this.constructor.Definition?.name}`);
+            return handler.call(this, p, { modules: this.modules, config: this.config || {}, log: this.logger, integration: this });
+        };
+        const { RunTrigger } = require('./use-cases/run-trigger');
+        if (!this.triggerProcessRepository) {
+            const { createProcessRepository } = require('./repositories/process-repository-factory');
+            this.triggerProcessRepository = createProcessRepository();
+        }
+        const outcome = await new RunTrigger({ processRepository: this.triggerProcessRepository }).execute({ integration: this, resolved, invoke, payload });
+        if (outcome.status !== 'ran') {
+            this.logger.info('Trigger run not started', { eventName: `${this.logger.name}.trigger_${outcome.status}`, trigger: data.trigger, reason: outcome.reason });
+        }
+        return outcome;
+    }
+
+    /** A tick that ran out of time continues here, on a dry instance, from its page cursor. */
+    async onTriggerTick({ data = {}, context } = {}) {
+        const { runTriggerTick } = require('./use-cases/run-trigger-tick');
+        return runTriggerTick(this.constructor, data, context);
+    }
+
+    /**
+     * Report each trigger timing this installation chose that cannot be used (not configurable, or under the
+     * floor): the trigger keeps its default, and the integration gets a warning message saying why. No-op for an
+     * integration without triggers.
+     */
+    async reportTriggerChoices() {
+        if (this.id === undefined || this.id === null) return [];
+        try {
+            const declarations = await this.triggerDeclarations();
+            const problems = declarations
+                .map((t) => ({ name: t.name, problems: resolveTrigger(t.name, t, this.config || {}).problems }))
+                .filter((p) => p.problems.length);
+            for (const p of problems) {
+                await this.updateIntegrationMessages.execute(this.id, 'warnings', 'Trigger timing not changed', `${p.name}: ${p.problems.join('; ')}`, Date.now());
+            }
+            return problems;
+        } catch (error) {
+            // A report, never a reason to fail the update.
+            this.logger.warn('Trigger choices not checked', { eventName: `${this.logger.name}.trigger_choices_unchecked`, error });
+            return [];
+        }
+    }
+
     async getConfigOptions() {
         const options = {
             jsonSchema: {},