@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/integrations/definitions/webhooks.js

@@ -1,119 +0,0 @@
-/**
- * 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/integration-types.js

@@ -1,73 +0,0 @@
-/**
- * Integration types: how an installation's `config.type` becomes the class that runs it.
- *
- * Most types are classes the app registers at startup (appDefinition.integrations). A registered class may also be
- * a provider: `static IntegrationProvider = { resolve(type), list() }` answers for types that exist as data rather
- * than code (published integration definitions). Those resolve to classes of their own, with their own name, so a
- * caller cannot tell how an integration was made; only the deployment underneath (queue, functions) is shared.
- *
- * Registered classes win over provided ones, so a published definition can never shadow code. When one would have,
- * that is logged (once per name per process) as `frigg.integrations.definition.shadowed_by_code`: the definition is
- * dead weight and whoever published it expects it to be installable.
- */
-const { getLogger } = require('../logs');
-
-const warnedShadowed = new Set();
-
-/** A definition is ignored because registered code has the same name. Logging must never break a listing. */
-function warnShadowed(name, provider) {
-    if (warnedShadowed.has(name)) return;
-    warnedShadowed.add(name);
-    try {
-        getLogger('frigg.integrations').warn('A published integration definition is ignored because registered code has the same name', {
-            eventName: 'frigg.integrations.definition.shadowed_by_code',
-            integrationName: name,
-            provider: provider?.name || null,
-        });
-    } catch { /* ignore */ }
-}
-
-/**
- * The class for a type, or null.
- * @param {object} [context] who is asking. With `workspaceId`, a type built in another workspace does not resolve:
- *        what a user may install or see. Without it (hydrating an installation that exists) every type resolves.
- */
-async function resolveIntegrationClass(integrationClasses, type, context) {
-    if (!type) return null;
-    const registered = integrationClasses.find((c) => c?.Definition?.name === type);
-    if (registered) return (await isVisible(registered, context)) ? registered : null;
-    for (const c of integrationClasses) {
-        if (!c?.IntegrationProvider) continue;
-        const provided = await c.IntegrationProvider.resolve(type, context);
-        if (provided) return provided;
-    }
-    return null;
-}
-
-/**
- * Whether a registered class is offered to whoever is asking: `static visible(context)` (defineIntegration's
- * `visible`, ADR-063 §4). Without a context (hydrating an installation that exists) every class is visible.
- */
-async function isVisible(IntegrationClass, context) {
-    if (!context || typeof IntegrationClass?.visible !== 'function') return true;
-    return Boolean(await IntegrationClass.visible(context));
-}
-
-/**
- * Every type a user can install: the registered classes, except providers (which are hosts, not integrations),
- * plus every type each provider offers.
- */
-async function listIntegrationClasses(integrationClasses, context) {
-    const registered = new Set(integrationClasses.map((c) => c?.Definition?.name));
-    const out = [];
-    for (const c of integrationClasses) {
-        if (!c?.IntegrationProvider) { if (await isVisible(c, context)) out.push(c); continue; }
-        for (const provided of await c.IntegrationProvider.list(context)) {
-            if (registered.has(provided.Definition.name)) warnShadowed(provided.Definition.name, c);
-            else out.push(provided);
-        }
-    }
-    return out;
-}
-
-module.exports = { resolveIntegrationClass, listIntegrationClasses, _resetShadowWarningsForTests: () => warnedShadowed.clear() };

package/integrations/triggers.js

@@ -1,244 +0,0 @@
-/**
- * Recurring triggers (ADR-055): what an integration declares, how one installation resolves it, and whether it is
- * due at a tick. Pure; no I/O. The tick itself is `use-cases/run-trigger-tick.js`; the run is
- * `IntegrationBase.onTriggerRun`.
- *
- *   static Definition = {
- *       name: 'housecallpro',
- *       triggers: {
- *           pollErp: { every: '15m', handler: 'pollErp' },                              // every installation
- *           ongoingSync: { every: '1h', configurable: { min: '15m' }, handler: sync },   // an installation may retime it
- *           perPlan: { every: (config) => config.pollEvery, when: (config) => config.poll !== false, handler },
- *           digest: { cron: '0 8 * * 1-5', timezone: 'America/New_York', configurable: true, handler },
- *           nightly: { at: 'cron(0 3 * * ? *)', timezone: 'Europe/London', handler },   // same time for everyone
- *       },
- *   };
- *
- * Nothing is created per installation. Devtools provisions one function per integration with one schedule per
- * distinct tick and one per `at` trigger (`provisioningOf`). At each tick the function pages through the ENABLED
- * installations and sends `{ event: 'FRIGG_TRIGGER_RUN', data: { integrationId, trigger, scheduledFor } }` for each
- * one that is due. A disabled or deleted installation is simply not due, and a config change applies at the next tick.
- *
- * Two additions to ADR-055 (its "Amendment (ADR-063)"):
- *   - `configurable: true | { min }` on an `every` or `cron` trigger lets an installation choose its own timing at
- *     `config.triggers.<name>` (`{ every }`, `{ cron, timezone }` or `{ enabled: false }`), never more often than `min`.
- *     A choice that breaks the floor, or a trigger that is not configurable, keeps the default (and is reported).
- *   - `cron` (five fields, with `timezone`) is a calendar trigger that may differ per installation. It runs off the
- *     shared tick: due when a firing falls in (previous tick, this tick]. `at` stays the ADR-055 calendar trigger,
- *     the same for every installation, with an exact schedule of its own.
- */
-const { parseEvery, validateRecurrence, minGapMinutes, lastFiringIn, isTimeZone } = require('../infrastructure/scheduler/recurrence');
-
-const TRIGGER_RUN = 'FRIGG_TRIGGER_RUN';
-/** A tick that ran out of time sends this to the integration's queue to carry on from its page cursor. */
-const TRIGGER_TICK = 'FRIGG_TRIGGER_TICK';
-
-const DEFAULT_TICK_MINUTES = 5;
-const MAX_EVERY_MINUTES = 1440;   // longer cadences use a calendar (`at` / `cron`)
-const AT = /^cron\(\S+ \S+ \S+ \S+ \S+ \S+\)$/;
-const OVERLAP = ['skip', 'allow'];
-
-const configurableOf = (c) => (c ? (c === true ? {} : c) : false);
-const kindOf = (t) => (t.at !== undefined ? 'at' : t.cron !== undefined ? 'cron' : 'every');
-const recurrenceOf = (r) => (r?.every !== undefined ? { every: r.every } : r?.cron !== undefined ? { cron: r.cron, ...(r.timezone ? { timezone: r.timezone } : {}) } : null);
-
-/** A minutes count as the shortest duration string: 90 -> '90m', 60 -> '1h', 1440 -> '1d'. */
-function durationOf(minutes) {
-    if (minutes % 1440 === 0) return `${minutes / 1440}d`;
-    if (minutes % 60 === 0) return `${minutes / 60}h`;
-    return `${minutes}m`;
-}
-
-/**
- * The tick a trigger runs on, in minutes. `tick` when set. Otherwise: for a constant `every`, that interval; for an
- * `every` given as a function, 5 minutes; for a `cron`, 5 minutes, or less when the cron itself fires more often.
- * A configurable trigger never ticks slower than its floor (or 5 minutes, without one), so the fastest choice it
- * allows can run. `at` triggers have no tick (null): each has its own schedule.
- */
-function tickMinutesOf(trigger) {
-    if (kindOf(trigger) === 'at') return null;
-    if (trigger.tick !== undefined) return parseEvery(trigger.tick);
-    const configurable = configurableOf(trigger.configurable);
-    const floor = configurable ? (configurable.min !== undefined ? parseEvery(configurable.min) : DEFAULT_TICK_MINUTES) : Infinity;
-    let natural;
-    if (kindOf(trigger) === 'cron') {
-        const gap = minGapMinutes({ cron: trigger.cron });
-        natural = Math.max(1, Math.min(DEFAULT_TICK_MINUTES, gap ?? DEFAULT_TICK_MINUTES));
-    } else {
-        natural = typeof trigger.every === 'function' ? DEFAULT_TICK_MINUTES : parseEvery(trigger.every) ?? DEFAULT_TICK_MINUTES;
-    }
-    return Math.max(1, Math.min(natural, floor ?? DEFAULT_TICK_MINUTES, MAX_EVERY_MINUTES));
-}
-
-/**
- * Problems with a trigger declaration, found without an installation (definition time and build time).
- * @returns {string[]}
- */
-function validateTrigger(name, t) {
-    const at = (m) => `${name}: ${m}`;
-    if (!t || typeof t !== 'object') return [at('A trigger is an object')];
-    const problems = [];
-    const kinds = ['every', 'at', 'cron'].filter((k) => t[k] !== undefined);
-    if (kinds.length !== 1) return [at('Give exactly one of every, at or cron')];
-    if (typeof t.handler !== 'function' && typeof t.handler !== 'string') problems.push(at('handler must be a function or a method name'));
-    if (t.overlap !== undefined && !OVERLAP.includes(t.overlap)) problems.push(at(`overlap must be ${OVERLAP.join(' or ')}`));
-    if (t.when !== undefined && typeof t.when !== 'function') problems.push(at('when must be a function of the installation config'));
-    if (t.tick !== undefined) {
-        const tick = parseEvery(t.tick);
-        if (tick === null || tick > MAX_EVERY_MINUTES) problems.push(at(`tick "${t.tick}" is not a duration between 1m and 1d`));
-    }
-    const kind = kinds[0];
-    if (kind === 'at') {
-        if (typeof t.at !== 'string' || !AT.test(t.at)) problems.push(at(`at "${t.at}" must be an EventBridge cron(...) expression with six fields`));
-        if (t.timezone !== undefined && !isTimeZone(t.timezone)) problems.push(at(`Unknown time zone "${t.timezone}"`));
-        if (t.configurable) problems.push(at('An at trigger runs at one time for every installation; use cron to let installations choose'));
-        if (t.tick !== undefined) problems.push(at('An at trigger has its own schedule; tick does not apply'));
-        return problems;
-    }
-    const configurable = configurableOf(t.configurable);
-    if (configurable && configurable.min !== undefined && parseEvery(configurable.min) === null) problems.push(at(`configurable.min "${configurable.min}" is not a duration (15m, 2h, 1d)`));
-    if (kind === 'every' && typeof t.every === 'function') return problems;
-    const recurrence = recurrenceOf(t);
-    for (const p of validateRecurrence(recurrence)) problems.push(at(p));
-    if (kind === 'every' && parseEvery(t.every) > MAX_EVERY_MINUTES) problems.push(at(`every "${t.every}" is longer than 1d; use at or cron`));
-    if (!problems.length && configurable && configurable.min !== undefined) {
-        for (const p of validateRecurrence(recurrence, { min: configurable.min })) problems.push(at(`The default breaks its own minimum: ${p}`));
-    }
-    return problems;
-}
-
-/** Problems with every trigger a Definition declares. */
-function validateTriggers(triggers = {}) {
-    return Object.entries(triggers || {}).flatMap(([name, t]) => validateTrigger(name, t));
-}
-
-/**
- * What devtools provisions for an integration class: the distinct ticks (minutes) of its `every`/`cron` triggers,
- * including the tick of the triggers it resolves per installation (`Definition.instanceTriggers`), and one entry per
- * `at` trigger. Throws on an invalid declaration, so a bad trigger fails the build rather than the first tick.
- *
- * @returns {{ ticks: number[], at: Array<{ name, at, timezone? }> }}
- */
-function provisioningOf(IntegrationClass) {
-    const Definition = IntegrationClass?.Definition || {};
-    const triggers = Definition.triggers || {};
-    const problems = validateTriggers(triggers);
-    const instance = Definition.instanceTriggers;
-    if (instance && parseEvery(instance.tick) === null) problems.push(`instanceTriggers.tick "${instance.tick}" is not a duration`);
-    if (problems.length) throw new Error(`Integration "${Definition.name}" declares invalid triggers: ${problems.join('; ')}`);
-    const ticks = new Set();
-    const at = [];
-    for (const [name, t] of Object.entries(triggers)) {
-        if (kindOf(t) === 'at') at.push({ name, at: t.at, ...(t.timezone ? { timezone: t.timezone } : {}) });
-        else ticks.add(tickMinutesOf(t));
-    }
-    if (instance) ticks.add(parseEvery(instance.tick));
-    return { ticks: [...ticks].sort((a, b) => a - b), at };
-}
-
-/** Does this class declare any triggers (fixed or per installation)? */
-function hasTriggers(IntegrationClass) {
-    const Definition = IntegrationClass?.Definition || {};
-    return Object.keys(Definition.triggers || {}).length > 0 || Boolean(Definition.instanceTriggers);
-}
-
-/**
- * One trigger, resolved for one installation.
- *
- * @param {string} name
- * @param {Object} t - the declaration (plus `choice` when the caller found the installation's choice elsewhere)
- * @param {Object} config - the installation's config
- * @returns {{ name, kind, recurrence?, at?, tickMinutes, cadence?, overlap, active: boolean, inactive?: string,
- *             source: 'definition'|'installation', problems: string[] }}
- *          `active: false` when `when` excludes the installation or it paused a configurable trigger.
- *          An invalid choice keeps the default and is listed in `problems`, so a bad edit never stops a trigger.
- */
-function resolveTrigger(name, t, config = {}) {
-    const kind = kindOf(t);
-    const out = { name, kind, tickMinutes: tickMinutesOf(t), overlap: t.overlap || 'skip', active: true, source: 'definition', problems: [] };
-    if (typeof t.when === 'function' && !t.when(config)) return { ...out, active: false, inactive: 'when' };
-    if (kind === 'at') return { ...out, at: t.at, timezone: t.timezone };
-
-    let recurrence = kind === 'every' ? { every: typeof t.every === 'function' ? t.every(config) : t.every } : recurrenceOf(t);
-    const configurable = configurableOf(t.configurable);
-    const choice = t.choice !== undefined ? t.choice : config?.triggers?.[name];
-    if (choice && typeof choice === 'object' && (recurrenceOf(choice) || choice.enabled !== undefined)) {
-        if (!configurable) out.problems.push('This trigger is not configurable');
-        else {
-            const picked = recurrenceOf(choice);
-            const issues = picked ? validateRecurrence(picked, { min: configurable.min }) : [];
-            if (picked?.every !== undefined && !issues.length && parseEvery(picked.every) > MAX_EVERY_MINUTES) issues.push(`every "${picked.every}" is longer than 1d`);
-            if (issues.length) out.problems.push(...issues);
-            else {
-                if (picked) { recurrence = picked; out.source = 'installation'; }
-                if (choice.enabled === false) return { ...out, recurrence, active: false, inactive: 'paused' };
-            }
-        }
-    }
-    const own = validateRecurrence(recurrence);
-    if (recurrence.every !== undefined && !own.length && parseEvery(recurrence.every) > MAX_EVERY_MINUTES) own.push(`every "${recurrence.every}" is longer than 1d`);
-    if (own.length) return { ...out, recurrence, active: false, inactive: 'invalid', problems: [...out.problems, ...own] };
-    out.recurrence = recurrence;
-    // An interval runs every n ticks (rounded up to a whole number of ticks).
-    if (recurrence.every !== undefined) out.cadence = Math.max(1, Math.ceil(parseEvery(recurrence.every) / out.tickMinutes));
-    return out;
-}
-
-/** A stable, evenly spread number for an installation id (FNV-1a, 32 bits). */
-function hashId(value) {
-    let h = 0x811c9dc5;
-    for (const ch of String(value)) {
-        h ^= ch.codePointAt(0);
-        h = Math.imul(h, 0x01000193) >>> 0;
-    }
-    return h;
-}
-
-/** The start of the tick slot an instant falls in: tick runs are keyed by slot, so a late or repeated tick agrees. */
-function slotStart(timeMs, tickMinutes) {
-    const size = tickMinutes * 60000;
-    return Math.floor(timeMs / size) * size;
-}
-
-/**
- * Is a resolved trigger due for this installation at this tick slot?
- *
- * - every: due when `slot mod n == hash(integrationId) mod n` (n = cadence in ticks), so it is stateless and spreads
- *   installations evenly across the cadence. scheduledFor is the slot start.
- * - cron:  due when it fired in (slot start - tick, slot start]. scheduledFor is that firing, so two ticks in one slot
- *   (a redelivery, a retried continuation) name the same run.
- * - at:    due whenever its own schedule invoked the tick; scheduledFor is that time, to the minute.
- *
- * @param {Object} resolved - from resolveTrigger
- * @param {{ integrationId, slotMs: number, firing?: (recurrence, from, to) => number|null }} at
- * @returns {{ scheduledFor: string } | null}
- */
-function dueRun(resolved, { integrationId, slotMs, firing = lastFiringIn }) {
-    if (!resolved?.active) return null;
-    if (resolved.kind === 'at') return { scheduledFor: new Date(Math.floor(slotMs / 60000) * 60000).toISOString() };
-    if (resolved.recurrence.every !== undefined) {
-        const n = resolved.cadence;
-        const slot = Math.floor(slotMs / (resolved.tickMinutes * 60000));
-        return slot % n === hashId(integrationId) % n ? { scheduledFor: new Date(slotMs).toISOString() } : null;
-    }
-    const fired = firing(resolved.recurrence, slotMs - resolved.tickMinutes * 60000, slotMs);
-    return fired === null ? null : { scheduledFor: new Date(fired).toISOString() };
-}
-
-module.exports = {
-    TRIGGER_RUN,
-    TRIGGER_TICK,
-    DEFAULT_TICK_MINUTES,
-    configurableOf,
-    recurrenceOf,
-    durationOf,
-    tickMinutesOf,
-    validateTrigger,
-    validateTriggers,
-    provisioningOf,
-    hasTriggers,
-    resolveTrigger,
-    hashId,
-    slotStart,
-    dueRun,
-};

package/integrations/use-cases/run-trigger-tick.js

@@ -1,155 +0,0 @@
-/**
- * The trigger tick (ADR-055 "Runtime / Tick"): one invocation of an integration's `{integration}Triggers` function.
- *
- * It is invoked by one of the integration's schedules: `{ tick: '5m', time }` for the shared tick of its `every` and
- * `cron` triggers, or `{ at: '<trigger name>', time }` for an `at` trigger. `time` is the schedule's own firing time,
- * so the slot it falls in, and therefore every due decision and every `scheduledFor`, is the same if the same tick
- * is delivered twice or carried on by a continuation.
- *
- * 1. Page through the ENABLED installations of this integration, `pageSize` (500) at a time, by id. A class that hosts
- *    other installation types (`static triggerTypes()`, the shared runtime of published definitions) pages each.
- * 2. For each installation and trigger, resolve config, `when` and the cadence (integrations/triggers.js).
- * 3. Due: `every` when `slot mod n == hash(integrationId) mod n`; `cron` when it fired in (previous tick, this tick];
- *    `at` always (it is its own schedule).
- * 4. Send `{ event: 'FRIGG_TRIGGER_RUN', data: { integrationId, trigger, scheduledFor } }` to the integration queue in
- *    batches, with `DelaySeconds` jitter (a stable 0..min(tick, 900 s) per installation and trigger) for tick runs.
- * 5. Near the Lambda deadline, send `{ event: 'FRIGG_TRIGGER_TICK', data: { tick|at, time, cursor } }` to the same
- *    queue and stop; the queue worker carries on from the cursor (IntegrationBase.onTriggerTick).
- *
- * Missed ticks are not replayed: a trigger is a "check now" signal, and handlers keep their own watermark.
- */
-const { parseEvery, lastFiringIn } = require('../../infrastructure/scheduler/recurrence');
-const { TRIGGER_RUN, TRIGGER_TICK, resolveTrigger, dueRun, slotStart, hashId } = require('../triggers');
-
-const PAGE_SIZE = 500;
-const DEADLINE_MARGIN_MS = 30000;
-const MAX_DELAY_SECONDS = 900;   // SQS DelaySeconds ceiling
-
-class RunTriggerTick {
-    /**
-     * @param {Object} deps
-     * @param {Function} deps.integrationClass - the IntegrationBase subclass (Definition.name, triggersFor, optional triggerTypes)
-     * @param {Object} deps.integrationRepository - findIntegrations({ type, status, limit, after })
-     * @param {Object} deps.queue - { batchSend(entries, queueUrl, { delaySeconds }), send(message, queueUrl) }
-     * @param {string} deps.queueUrl
-     * @param {Object} [deps.logger]
-     * @param {number} [deps.pageSize]
-     */
-    constructor({ integrationClass, integrationRepository, queue, queueUrl, logger, pageSize = PAGE_SIZE }) {
-        this.Integration = integrationClass;
-        this.repository = integrationRepository;
-        this.queue = queue;
-        this.queueUrl = queueUrl;
-        this.logger = logger;
-        this.pageSize = pageSize;
-    }
-
-    /**
-     * @param {Object} params
-     * @param {string} [params.tick] - '5m': evaluate the every/cron triggers on this tick
-     * @param {string} [params.at] - an `at` trigger's name: run it for every ENABLED installation
-     * @param {string} [params.time] - the schedule's firing time (ISO); defaults to now
-     * @param {string|number|{type: string, after: string|number|null}} [params.cursor] - continue after this installation id
-     *        (in this type, when the class covers several)
-     * @param {() => number} [params.remainingMs] - time left in this invocation
-     * @returns {Promise<{ installations: number, sent: number, pages: number, continued: boolean, failed: Array }>}
-     */
-    async execute({ tick, at, time, cursor, remainingMs = () => Infinity }) {
-        const name = this.Integration.Definition?.name;
-        if (!this.queueUrl) throw new Error(`No queue URL for integration "${name}"; trigger runs have nowhere to go`);
-        const tickMinutes = at ? null : parseEvery(tick);
-        if (!at && tickMinutes === null) throw new Error(`Trigger tick "${tick}" is not a duration`);
-        const timeMs = time && !Number.isNaN(Date.parse(time)) ? Date.parse(time) : Date.now();
-        const slotMs = at ? Math.floor(timeMs / 60000) * 60000 : slotStart(timeMs, tickMinutes);
-        const firings = new Map();   // one cron answer per recurrence per tick (the window is the same), not per installation
-        const firing = (recurrence, from, to) => {
-            const key = `${recurrence.cron}|${recurrence.timezone || 'UTC'}`;
-            if (!firings.has(key)) firings.set(key, lastFiringIn(recurrence, from, to));
-            return firings.get(key);
-        };
-        const delayOf = (m) => (at ? 0 : hashId(`${m.data.integrationId}:${m.data.trigger}`) % Math.min(tickMinutes * 60, MAX_DELAY_SECONDS));
-
-        // The installation types this tick covers: the class's own, unless it hosts others (a shared runtime whose
-        // published definitions are integration types of their own; static triggerTypes). With more than one, the
-        // continuation cursor names the type it stopped in: `{ type, after }`.
-        const types = typeof this.Integration.triggerTypes === 'function' ? await this.Integration.triggerTypes() : [name];
-        let typeIndex = 0;
-        let after = cursor;
-        if (cursor && typeof cursor === 'object') {
-            typeIndex = Math.max(0, types.indexOf(cursor.type));
-            after = cursor.after ?? null;
-        }
-        const cursorAt = (type, id) => (types.length > 1 ? { type, after: id } : id);
-        const continueAt = async (nextCursor) => {
-            await this.queue.send({ event: TRIGGER_TICK, data: { ...(at ? { at } : { tick }), time: new Date(timeMs).toISOString(), cursor: nextCursor } }, this.queueUrl);
-        };
-
-        const out = { installations: 0, sent: 0, pages: 0, continued: false, failed: [] };
-        for (;;) {
-            const type = types[typeIndex];
-            const rows = await this.repository.findIntegrations({ type, status: 'ENABLED', limit: this.pageSize, after });
-            out.pages += 1;
-            const messages = [];
-            for (const row of rows) {
-                out.installations += 1;
-                try {
-                    const declarations = await this.Integration.triggersFor({ config: row.config || {}, record: row });
-                    for (const declaration of declarations) {
-                        const isAt = declaration.at !== undefined;
-                        if (at ? declaration.name !== at || !isAt : isAt) continue;
-                        const resolved = resolveTrigger(declaration.name, declaration, row.config || {});
-                        if (!at && resolved.tickMinutes !== tickMinutes) continue;
-                        const due = dueRun(resolved, { integrationId: row.id, slotMs, firing });
-                        if (due) messages.push({ event: TRIGGER_RUN, data: { integrationId: row.id, trigger: declaration.name, scheduledFor: due.scheduledFor } });
-                    }
-                } catch (error) {
-                    // One installation's bad config must not stop the others' runs.
-                    out.failed.push({ integrationId: row.id, error: error.message });
-                    this.logger?.warn('Trigger tick skipped an installation', { eventName: 'frigg.triggers.installation_failed', integration: name, integrationId: row.id, error });
-                }
-            }
-            if (messages.length) {
-                await this.queue.batchSend(messages, this.queueUrl, { delaySeconds: delayOf });
-                out.sent += messages.length;
-            }
-            if (rows.length < this.pageSize) {
-                // This type is done; carry on with the next one, from its start.
-                typeIndex += 1;
-                if (typeIndex >= types.length) return out;
-                after = null;
-            } else {
-                after = rows[rows.length - 1].id;
-            }
-            if (remainingMs() < DEADLINE_MARGIN_MS) {
-                await continueAt(cursorAt(types[typeIndex], after));
-                out.continued = true;
-                return out;
-            }
-        }
-    }
-}
-
-/** The queue URL Frigg's infrastructure gives an integration: `<NAME>_QUEUE_URL`, dashes as underscores. */
-function queueUrlFor(integrationName) {
-    return process.env[`${String(integrationName).toUpperCase().replace(/-/g, '_')}_QUEUE_URL`];
-}
-
-/**
- * Run a tick with Frigg's real adapters: the integration repository, the SQS queuer and the integration's queue.
- * Used by the `{integration}Triggers` Lambda and by a continuation on the queue worker.
- */
-async function runTriggerTick(integrationClass, event = {}, context) {
-    const { createIntegrationRepository } = require('../repositories/integration-repository-factory');
-    const { QueuerUtil } = require('../../queues');
-    const { getLogger } = require('../../logs');
-    const remainingMs = typeof context?.getRemainingTimeInMillis === 'function' ? () => context.getRemainingTimeInMillis() : undefined;
-    return new RunTriggerTick({
-        integrationClass,
-        integrationRepository: createIntegrationRepository(),
-        queue: QueuerUtil,
-        queueUrl: queueUrlFor(integrationClass.Definition.name),
-        logger: getLogger('frigg.triggers'),
-    }).execute({ tick: event.tick, at: event.at, time: event.time, cursor: event.cursor, remainingMs });
-}
-
-module.exports = { RunTriggerTick, runTriggerTick, queueUrlFor, PAGE_SIZE };