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

package/integrations/define/define-integration.js

@@ -1,335 +0,0 @@
-/**
- * `defineIntegration` (ADR-054 §1): the code front door to the integration runtime.
- *
- * It returns an ordinary IntegrationBase subclass with a static `Definition` and an instance `events` map: the same
- * compile target an ADR-063 integration document reaches through `fromDefinitionDocument` (definitions/). Builders,
- * routers, the queue worker, the ADR-055 trigger tick and the management API read that target and nothing else, so
- * the two front doors share one runtime; neither is a serialisation of the other.
- *
- *     const DealAlerts = defineIntegration({
- *         name: 'deal-alerts', version: '1.0.0', display: { label, description, category },
- *         modules: { crm: use(hubspot, { webhooks: { subscribe: [...] } }), chat: use(slack) },
- *         config: { channel: slack.fields.channel({ required: true }), minAmount: { type: 'number', default: 0 } },
- *         on: { 'crm.deal.changed': async ({ deal, changes }, { modules: { crm, chat }, config, log }) => { … } },
- *         triggers: { digest: { cron: '0 8 * * 1-5', timezone: 'UTC', handler: async (payload, ctx) => { … } } },
- *         actions: { SEND_TEST: { title: 'Send a test', run: async (input, ctx) => { … } } },
- *         visible: (context) => true,
- *     });
- *
- * Handlers are `(payload, ctx)` and are called without `this`. `ctx` has a fixed set of core-owned keys:
- *     { modules: { <key>: api }, config, log, telemetry, commands, integration }
- * The keys inside `ctx.modules` are the author's (`crm`, `chat`); nothing else in `ctx` is.
- *
- * Compiles to:
- *     Definition.modules        { crm: { definition: hubspot.Definition }, chat: { definition: slack.Definition } }
- *     Definition.extensions     { 'crm-webhooks': <contract-1 binding> }  (extension-binding.js)
- *     Definition.triggers       { digest, 'crm.<ext trigger>' }          (ADR-055, run by Stack B's tick)
- *     this.events               SEND_TEST (USER_ACTION) + the extension's queue events (merged at initialize)
- *     getConfigOptions()        { jsonSchema, uiSchema } with module field choices loaded from the account
- */
-const { IntegrationBase } = require('../integration-base');
-const { validateTrigger } = require('../triggers');
-const { normalizeBinding } = require('./use');
-const { validateExtension, isContract2 } = require('./define-extension');
-const { compileBinding, resolveOptions } = require('./extension-binding');
-const { compileConfig, resolveConfig, configOptions } = require('./config');
-const { check, withDefaults } = require('./json-schema-lite');
-
-const SPEC_KEYS = new Set(['name', 'version', 'display', 'usage', 'modules', 'config', 'on', 'triggers', 'actions', 'visible', 'webhooks', 'routes']);
-const NAME = /^[a-z0-9][a-z0-9-]*$/;
-const ACTION_KEY = /^[A-Z][A-Z0-9_]*$/;
-const PLAN = Symbol.for('frigg.define.plan');
-
-/**
- * Module keys that cannot be used: IntegrationBase attaches each module to the instance under its key
- * (`_appendModules`: `this[key] = module`), so a key that names an instance field or method would overwrite it.
- * Inside `ctx.modules` any name is fine; the instance is the constraint.
- */
-const INSTANCE_FIELDS = ['id', 'userId', 'entities', 'config', 'status', 'version', 'messages', 'modules', 'record', 'events', 'on',
-    'defaultEvents', 'logger', 'telemetry', 'def', 'compiled', 'ports', 'integrationRepository', 'integrationMappingRepository',
-    'updateIntegrationStatus', 'updateIntegrationMessages', 'updateIntegrationConfig', 'patchIntegrationConfig', 'triggerProcessRepository',
-    'commands', 'constructor'];
-let reservedKeys;
-function isReservedModuleKey(key) {
-    if (!reservedKeys) {
-        reservedKeys = new Set(INSTANCE_FIELDS);
-        for (let p = IntegrationBase.prototype; p && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
-            for (const n of Object.getOwnPropertyNames(p)) reservedKeys.add(n);
-        }
-        for (const n of ['handlerContext', 'resolvedConfig', 'runEmitted', 'syncInstallationSubscriptions']) reservedKeys.add(n);
-    }
-    return reservedKeys.has(key) || key.startsWith('_');
-}
-
-const pascal = (s) => s.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('') || 'Integration';
-
-function fail(name, msg) {
-    throw new Error(`defineIntegration(${name ? `"${name}"` : ''}): ${msg}`);
-}
-
-/** Every module binding, each enabled extension validated and compiled. */
-function compileModules(name, modules) {
-    if (!modules || typeof modules !== 'object' || !Object.keys(modules).length) fail(name, '"modules" must bind at least one API module');
-    const bindings = [];
-    const extensionBindings = [];
-    const definitionModules = {};
-    const contract1 = {};
-    for (const [key, value] of Object.entries(modules)) {
-        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) fail(name, `module key "${key}" must be an identifier (it is ctx.modules.${key})`);
-        if (isReservedModuleKey(key)) fail(name, `module key "${key}" names a member of IntegrationBase, where modules are also attached (this.${key}); choose another key`);
-        const b = normalizeBinding(key, value);
-        bindings.push(b);
-        definitionModules[key] = { definition: b.module.Definition };
-        for (const [extKey, options] of Object.entries(b.extensions)) {
-            if (options === false || options === undefined) continue;
-            const ext = b.module.extensions?.[extKey];
-            if (!ext) fail(name, `modules.${key}: ${b.moduleName} has no extension "${extKey}" (it has ${Object.keys(b.module.extensions || {}).join(', ') || 'none'})`);
-            validateExtension(ext, { where: `defineIntegration("${name}") modules.${key}` });
-            if (!isContract2(ext)) {
-                // A contract-1 bundle binds as it does today, under the derived key; its event names stay global.
-                if (options !== true && Object.keys(options || {}).length) fail(name, `modules.${key}: extension "${extKey}" is contract 1 and takes no options`);
-                contract1[`${key}-${extKey}`] = { extension: ext };
-                continue;
-            }
-            const raw = options === true ? {} : options;
-            // Function values depend on instance config (ADR-054 §4): present now, checked once resolved.
-            const problems = check(ext.options, withDefaults(ext.options, raw));
-            if (problems.length) fail(name, `use(${b.moduleName}, { ${extKey} }): ${problems.join('; ')}`);
-            extensionBindings.push({ moduleKey: key, extKey, ext, module: b.module, moduleName: b.moduleName, options: raw });
-        }
-    }
-    return { bindings, extensionBindings, definitionModules, contract1 };
-}
-
-function compileTriggers(name, triggers = {}, extensionBindings) {
-    if (typeof triggers !== 'object' || Array.isArray(triggers)) fail(name, '"triggers" must be an object keyed by trigger name');
-    const out = {};
-    const add = (triggerName, t, handlerOf) => {
-        if (out[triggerName]) fail(name, `trigger "${triggerName}" is declared twice`);
-        if (typeof t?.handler !== 'function') fail(name, `trigger "${triggerName}": "handler" must be a function (payload, ctx)`);
-        const problems = validateTrigger(triggerName, t);
-        if (problems.length) fail(name, problems.join('; '));
-        out[triggerName] = { ...t, handler: handlerOf(t.handler) };
-    };
-    // Called by IntegrationBase#onTriggerRun with `this` = the hydrated installation; the author's handler gets ctx.
-    const wrap = (fn) => function runTrigger(payload) { return fn(payload, this.handlerContext()); };
-    for (const [n, t] of Object.entries(triggers)) {
-        if (n.includes('.')) fail(name, `trigger "${n}": dotted names are reserved for module extensions (<moduleKey>.<name>)`);
-        add(n, t, wrap);
-    }
-    for (const b of extensionBindings) {
-        for (const [n, t] of Object.entries(b.ext.triggers || {})) {
-            // An extension trigger gets the extension ctx (its own api and options), not the integration's.
-            add(`${b.moduleKey}.${n}`, t, (fn) => function runExtensionTrigger(payload) {
-                const config = this.resolvedConfig();
-                return fn(payload, this.handlerContext({ api: this[b.moduleKey]?.api, options: resolveOptions(b, config) }));
-            });
-        }
-    }
-    return out;
-}
-
-function compileActions(name, actions = {}) {
-    if (typeof actions !== 'object' || Array.isArray(actions)) fail(name, '"actions" must be an object keyed by action id');
-    const out = {};
-    for (const [id, a] of Object.entries(actions)) {
-        if (!ACTION_KEY.test(id)) fail(name, `action "${id}": ids are UPPER_SNAKE_CASE (they are USER_ACTION event names)`);
-        if (typeof a?.run !== 'function') fail(name, `action "${id}": "run" must be a function (input, ctx)`);
-        if (typeof a.title !== 'string' || !a.title) fail(name, `action "${id}": needs a "title"`);
-        out[id] = a;
-    }
-    return out;
-}
-
-function defineIntegration(spec = {}) {
-    const { name } = spec;
-    if (typeof name !== 'string' || !NAME.test(name)) fail(name, '"name" must be lower-kebab-case (it names routes, functions and queues)');
-    for (const key of Object.keys(spec)) if (!SPEC_KEYS.has(key)) fail(name, `unknown key "${key}"`);
-    if (spec.version !== undefined && typeof spec.version !== 'string') fail(name, '"version" must be a string');
-    if (spec.visible !== undefined && typeof spec.visible !== 'function') fail(name, '"visible" must be a function (context) => boolean');
-
-    const { bindings, extensionBindings, definitionModules, contract1 } = compileModules(name, spec.modules);
-    const extensions = { ...contract1 };
-    const emitted = new Map();   // 'crm.deal.changed' -> { binding, name }
-    const internalEvents = new Set();
-    for (const b of extensionBindings) {
-        const c = compileBinding(b);
-        if (extensions[c.key]) fail(name, `two bindings derive the key "${c.key}"`);
-        extensions[c.key] = c.compiled;
-        for (const ev of Object.keys(c.compiled.extension.events)) internalEvents.add(ev);
-        for (const n of Object.keys(b.ext.emits || {})) emitted.set(`${b.moduleKey}.${n}`, { binding: b, name: n });
-    }
-
-    const on = spec.on || {};
-    if (typeof on !== 'object' || Array.isArray(on)) fail(name, '"on" must be an object keyed by event name');
-    for (const [event, handler] of Object.entries(on)) {
-        if (typeof handler !== 'function') fail(name, `on["${event}"]: handlers are functions (payload, ctx); method names are not accepted`);
-        if (!emitted.has(event)) {
-            const known = [...emitted.keys()];
-            fail(name, `on["${event}"]: no bound extension emits it${known.length ? ` (bound extensions emit ${known.join(', ')})` : ' (no bound extension emits events)'}`);
-        }
-    }
-    const actions = compileActions(name, spec.actions);
-    for (const id of Object.keys(actions)) if (internalEvents.has(id)) fail(name, `action "${id}" collides with an extension event`);
-    const triggers = compileTriggers(name, spec.triggers, extensionBindings);
-    const configPlan = compileConfig(spec.config, bindings, `defineIntegration("${name}")`);
-
-    const plan = Object.freeze({ name, bindings, extensionBindings, on: { ...on }, actions, configPlan, emitted });
-
-    const Definition = {
-        name,
-        version: spec.version || '1.0.0',
-        modules: definitionModules,
-        display: { label: name, description: '', category: '', ...(spec.display || {}) },
-        ...(spec.usage ? { usage: spec.usage } : {}),
-        ...(Object.keys(extensions).length ? { extensions } : {}),
-        ...(Object.keys(triggers).length ? { triggers } : {}),
-        ...(spec.webhooks !== undefined ? { webhooks: spec.webhooks } : {}),
-        ...(spec.routes ? { routes: spec.routes } : {}),
-    };
-
-    class DefinedIntegration extends IntegrationBase {
-        static Definition = Definition;
-
-        static [PLAN] = plan;
-
-        constructor(params) {
-            super(params);
-            for (const [id, a] of Object.entries(actions)) {
-                this.events[id] = {
-                    type: 'USER_ACTION',
-                    userActionType: a.userActionType || 'DATA_ACTION',
-                    title: a.title,
-                    ...(a.description ? { description: a.description } : {}),
-                    handler: (input) => a.run(input ?? {}, this.handlerContext()),
-                };
-            }
-        }
-
-        /** The stored config with the form's defaults filled in: what handlers see as ctx.config. */
-        resolvedConfig() {
-            return resolveConfig(plan.configPlan, this.config || {});
-        }
-
-        /**
-         * The context every handler gets (ADR-054 §1). Built per dispatch, frozen. `integration` is a read-only
-         * record (ADR-054 open question 6, lean: read-only); `commands` is created on first use. `extra` adds the
-         * extension keys (`api`, `options`) for an extension's own handlers.
-         */
-        handlerContext(extra = {}) {
-            const self = this;
-            const modules = {};
-            for (const b of plan.bindings) {
-                Object.defineProperty(modules, b.key, { enumerable: true, get: () => self[b.key]?.api });
-            }
-            let commands;
-            const integration = Object.freeze({
-                id: this.id ?? null,
-                name: plan.name,
-                status: this.status ?? null,
-                userId: this.userId ?? null,
-                entities: this.entities ?? null,
-                version: this.version ?? Definition.version,
-            });
-            const ctx = {
-                modules: Object.freeze(modules),
-                config: Object.freeze(this.resolvedConfig()),
-                log: this.logger,
-                telemetry: this.telemetry,
-                integration,
-                ...extra,
-            };
-            Object.defineProperty(ctx, 'commands', {
-                enumerable: true,
-                get() {
-                    if (!commands) {
-                        const { createFriggCommands } = require('../../application');
-                        commands = createFriggCommands({ integrationClass: self.constructor });
-                    }
-                    return commands;
-                },
-            });
-            return Object.freeze(ctx);
-        }
-
-        /**
-         * Run one emitted event: the `on` handler, else the extension's default handler, else ack and count it.
-         * @returns {Promise<'handled'|'unhandled'|'undeclared'>}
-         */
-        async runEmitted(binding, eventName, payload) {
-            const full = `${binding.moduleKey}.${eventName}`;
-            if (!binding.ext.emits || !Object.prototype.hasOwnProperty.call(binding.ext.emits, eventName)) {
-                this.logger.warn('Extension produced an event it does not declare', { eventName: 'frigg.extension.event_undeclared', event: full });
-                return 'undeclared';
-            }
-            const handler = plan.on[full] || binding.ext.emits[eventName].handler;
-            if (!handler) {
-                try { this.telemetry?.event?.('frigg.extension.event_unhandled', { event: full }); } catch { /* telemetry never breaks dispatch */ }
-                this.logger.info('Event has no handler', { eventName: 'frigg.extension.event_unhandled', event: full });
-                return 'unhandled';
-            }
-            await handler(payload, this.handlerContext());
-            return 'handled';
-        }
-
-        /*
-         * Lifecycle invoker for app-scope subscriptions (ADR-054 §2, amended): after the base hook, an installation
-         * whose binding options are functions of its config gets the subscriptions it needs, add-only. A failure is
-         * a warning on the installation, never a failed create or update.
-         * TODO(ADR-054 §5): move these call sites into the lifecycle dispatcher when it lands.
-         */
-        async onCreate(params) {
-            await super.onCreate(params);
-            await this.syncInstallationSubscriptions('create');
-        }
-
-        async onUpdate(params) {
-            await super.onUpdate(params);
-            await this.syncInstallationSubscriptions('update');
-        }
-
-        async onDelete(params) {
-            await super.onDelete(params);
-            await this.syncInstallationSubscriptions('delete');
-        }
-
-        async syncInstallationSubscriptions(event) {
-            const { ensureInstallationSubscriptions, hasFunctionOption } = require('./subscriptions');
-            const bindings = plan.extensionBindings.filter((b) => b.ext.subscriptions?.scope === 'app' && hasFunctionOption(b));
-            if (!bindings.length) return [];
-            if (event === 'delete') {
-                // Add-only: nothing to create for an installation that is going away, and removing needs the whole
-                // app's union, so its subscriptions stay until a reconcile runs with prune.
-                this.logger.info('Subscriptions kept on delete; a pruning reconcile removes the ones no installation needs', { eventName: 'frigg.subscriptions.kept_on_delete', extensions: bindings.map((b) => b.ext.name) });
-                return [];
-            }
-            if (this.status && this.status !== 'ENABLED') return [];
-            try {
-                return await ensureInstallationSubscriptions(this);
-            } catch (error) {
-                this.logger.warn('Webhook subscriptions not created', { eventName: 'frigg.subscriptions.ensure_failed', event, error });
-                try {
-                    await this.updateIntegrationMessages?.execute(this.id, 'warnings', 'Webhook subscriptions not created', 'The provider subscriptions this installation needs could not be created. They are retried on the next config save or reconcile.', Date.now());
-                } catch { /* a report, never a failure */ }
-                return [];
-            }
-        }
-
-        async getConfigOptions() {
-            return configOptions(plan.configPlan, (key) => this[key]?.api, this.config || {}, this.logger);
-        }
-
-        async refreshConfigOptions(params = {}) {
-            const values = params?.data ?? params?.formData ?? params ?? {};
-            return configOptions(plan.configPlan, (key) => this[key]?.api, { ...(this.config || {}), ...values }, this.logger);
-        }
-    }
-    Object.defineProperty(DefinedIntegration, 'name', { value: pascal(name) });
-    if (spec.visible) DefinedIntegration.visible = spec.visible;
-    return DefinedIntegration;
-}
-
-/** The compiled plan of a class made by defineIntegration, or null for any other class. */
-const planOf = (Cls) => (Cls && Object.prototype.hasOwnProperty.call(Cls, PLAN) ? Cls[PLAN] : null);
-
-module.exports = { defineIntegration, planOf };

package/integrations/define/examples/deal-alerts.js

@@ -1,140 +0,0 @@
-// =====================================================================================
-// (a) ONE-WAY, EVENT-DRIVEN: a HubSpot deal enters a chosen stage -> post to Slack.
-// This is the WHOLE app: backend/index.js (ADR-054 Appendix A, unchanged except these notes).
-// App code: ~70 lines. Nothing else in the repo but package.json and infrastructure.js.
-// Runs end to end in tests/example-deal-alerts.test.js (HubSpot and Slack nock'd).
-// =====================================================================================
-const { defineApp, defineIntegration, use } = require('@friggframework/core');
-const hubspot = require('@friggframework/api-module-hubspot');
-const slack = require('@friggframework/api-module-slack');
-
-const DealAlerts = defineIntegration({
-    name: 'deal-alerts',
-    version: '1.0.0',
-    display: {
-        label: 'Deal alerts in Slack',
-        description: 'Posts to a Slack channel when a HubSpot deal reaches a chosen stage.',
-        category: 'Notifications',
-    },
-
-    // The module key (crm, chat) is the namespace for everything a module's extensions
-    // contribute: routes (/api/deal-alerts-integration/crm-webhooks/...), events
-    // ('crm.deal.changed'), config fields, and admin scripts.
-    modules: {
-        crm: use(hubspot, {
-            webhooks: {
-                subscribe: ['deal.creation', 'deal.propertyChange:dealstage'],
-                hydrate: ['dealname', 'amount', 'dealstage', 'pipeline', 'hubspot_owner_id'],
-            },
-        }),
-        chat: use(slack),
-    },
-
-    // Per-install form shown to the end user. Module fields load their options from
-    // the connected account (Slack channels, HubSpot pipelines and stages).
-    config: {
-        channel: slack.fields.channel({ title: 'Post to channel', required: true }),
-        stages: hubspot.fields.dealStages({
-            title: 'Alert when a deal enters',
-            multiple: true,
-            default: ['closedwon'],
-        }),
-        minAmount: { type: 'number', title: 'Only deals worth at least', default: 0 },
-        mentionOwner: { type: 'boolean', title: 'Mention the deal owner', default: true },
-    },
-
-    // Handlers take (payload, ctx). ctx.modules holds the APIs under the keys chosen
-    // above (crm, chat); every other ctx key is core's and fixed.
-    on: {
-        // Emitted by hubspot.extensions.webhooks after it verified the v3 signature,
-        // resolved portalId -> this integration, and batch-read the deal (hydrate).
-        async 'crm.deal.changed'({ deal, changes }, { modules: { crm, chat }, config, log }) {
-            const stage = changes.dealstage?.to ?? deal.properties.dealstage;
-            if (!config.stages.includes(stage)) return;
-            if (Number(deal.properties.amount ?? 0) < config.minAmount) return;
-
-            let mention = '';
-            if (config.mentionOwner && deal.properties.hubspot_owner_id) {
-                const owner = await crm.getOwnerById(deal.properties.hubspot_owner_id);
-                const user = owner?.email && (await chat.lookupUserByEmail(owner.email).catch(() => null));
-                if (user?.user?.id) mention = ` <@${user.user.id}>`;
-            }
-
-            await chat.postMessage({
-                channel: config.channel,
-                text: `Deal *${deal.properties.dealname}* moved to ${stage}${mention}`,
-                blocks: [
-                    { type: 'section', text: { type: 'mrkdwn',
-                        text: `*${deal.properties.dealname}*  ${stage}\nAmount: ${deal.properties.amount ?? 'n/a'}${mention}` } },
-                    { type: 'actions', elements: [{ type: 'button', text: { type: 'plain_text', text: 'Open in HubSpot' },
-                        url: crm.urls.record('deal', deal.id) }] },
-                ],
-            });
-            log.info({ dealId: deal.id, stage }, 'deal alert posted');
-        },
-    },
-
-    actions: {
-        SEND_TEST_ALERT: {
-            title: 'Send a test message',
-            async run(_input, { modules: { chat }, config }) {
-                await chat.postMessage({ channel: config.channel, text: 'Deal alerts are connected.' });
-                return { ok: true };
-            },
-        },
-    },
-});
-
-module.exports = defineApp({
-    name: 'deal-alerts',
-    integrations: [DealAlerts],
-    database: { postgres: { enable: true } },
-    encryption: { fieldLevelEncryptionMethod: 'kms' },
-});
-
-// =====================================================================================
-// WHAT EACH IMPORT CONTRIBUTES (none of it is written in this file)
-//
-// @friggframework/core
-//   defineIntegration -> an IntegrationBase subclass with a static Definition, so every
-//     existing builder, router, worker and the management API work unchanged.
-//   modules -> Definition.modules; use(hubspot, { webhooks }) -> Definition.extensions['crm-webhooks'],
-//     the contract-1 binding next already deploys (route /crm-webhooks/webhooks, function
-//     deal-alerts__crmwebhooks). The same compile target as an ADR-063 integration document.
-//   on/actions -> this.events (LIFE_CYCLE_EVENT / USER_ACTION), handler(payload, ctx),
-//     ctx = { modules: { crm, chat }, config, log, telemetry, commands, integration }.
-//     No `this`. The keys inside ctx.modules are this file's; the rest are core's.
-//   config -> getConfigOptions() jsonSchema/uiSchema + validateConfig() (NEEDS_CONFIG).
-//   Queue worker, DLQ, retries, delivery.isLastAttempt, structured logs, telemetry,
-//   usage counters, encryption, token refresh: already on next.
-//
-// @friggframework/api-module-hubspot
-//   Definition: OAuth2, scopes, entity identity (portalId = externalId).
-//   Api: getOwnerById, batch reads, urls.record(); static rateLimit (ADR-049, descriptive).
-//   fields.dealStages: config field with options loaded from the connected portal.
-//   extensions.webhooks (contract 2):
-//     route POST /webhooks, useDatabase: false, verify: HubSpot v3 HMAC + 5 min skew
-//     resolve: portalId -> integration (the RESOLVE hop the extension does by hand today)
-//     subscriptions: scope 'app' (HubSpot v3 subscriptions are per developer app);
-//       desired set = union of every installed binding's `subscribe`; reconcileAppSubscriptions()
-//       creates what is missing (add-only; `prune` removes what no binding needs). Runs after
-//       `frigg deploy`, on installation create/update when options depend on config, and from
-//       the admin script. One HubSpot developer app per stage.
-//     emits: deal.created | deal.changed {deal, changes} | deal.deleted (+ contact.*, company.*)
-//     hydrate: batch-reads the object with the listed properties before dispatch.
-//     env: HUBSPOT_CLIENT_SECRET, HUBSPOT_APP_ID, HUBSPOT_DEVELOPER_API_KEY (ADR-027 scoping).
-//     scripts: hubspot.reconcile-subscriptions (prune, dryRun), appended by defineApp;
-//       hubspot.replay-webhook is a follow-up.
-//
-// @friggframework/api-module-slack
-//   Definition: OAuth2 bot install, team_id = externalId.
-//   Api: postMessage, lookupUserByEmail; static rateLimit (tiered, per-method).
-//   fields.channel: config field with options from conversations.list.
-//   (extensions.events — Slack Events API receiver with url_verification handshake — is
-//    available but not enabled here, so no route is deployed for it.)
-//
-// Provisioned by devtools from the Definition (no infrastructure code in the app):
-//   deal-alerts (HTTP catch-all), deal-alerts__crmwebhooks (receiver, no Prisma layer),
-//   deal-alerts QueueWorker + queue + DLQ, and the admin-script functions that run
-//   hubspot.reconcile-subscriptions.
-// =====================================================================================

package/integrations/define/extension-binding.js

@@ -1,174 +0,0 @@
-/**
- * A contract-2 extension enabled on a module binding, compiled into the contract-1 binding that `next` already runs
- * (ADR-054 §3). Nothing downstream changes: devtools gives the binding its own function, the defined-routes router
- * mounts it under the binding key, `_mergeExtensions` merges its events, and the queue worker dispatches them.
- *
- * For `modules: { crm: use(hubspot, { webhooks }) }`:
- *
- *   binding key        crm-webhooks           route  /api/{integration}-integration/crm-webhooks/webhooks
- *   function           {integration}__crmwebhooks (devtools, from Definition.extensions as today)
- *   queue events       CRM__WEBHOOKS__RECEIVED (receipt, no DB) -> CRM__WEBHOOKS__RESOLVE (worker, dry)
- *                      -> CRM__WEBHOOKS__DISPATCH (worker, the installation hydrated)
- *                      CRM__WEBHOOKS__DEAL_CHANGED, … one per emitted event (replays, tests)
- *   integration events crm.deal.changed, … (the `on` map)
- *   triggers           crm.<name> (merged into Definition.triggers)
- *
- * Every name derives from the module key, so two modules that both emit `contact.changed`, or the same module bound
- * twice, never collide; no bare name reaches the global event map.
- */
-const { check, withDefaults } = require('./json-schema-lite');
-
-const upper = (s) => String(s).replace(/[^A-Za-z0-9]+/g, '_').replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
-const bindingKeyOf = (moduleKey, extKey) => `${moduleKey}-${extKey}`;
-const eventPrefixOf = (moduleKey, extKey) => `${upper(moduleKey)}__${upper(extKey)}__`;
-
-function envFor(ext) {
-    return Object.fromEntries((ext.env || []).map((k) => [k, process.env[k]]));
-}
-
-/**
- * The binding's options for one installation: function values resolved with its config, defaults applied, then
- * checked against the extension's schema.
- */
-function resolveOptions(binding, config = {}) {
-    const raw = binding.options === true ? {} : binding.options || {};
-    const resolved = Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, typeof v === 'function' ? v(config) : v]));
-    const out = withDefaults(binding.ext.options, resolved);
-    const problems = check(binding.ext.options, out);
-    if (problems.length) throw new Error(`use(${binding.moduleName}, { ${binding.extKey} }) for this installation: ${problems.join('; ')}`);
-    return out;
-}
-
-/** The Api a verify method or an app-scope subscription runs on: the module's Api class, without a credential. */
-function appApiOf(binding) {
-    const Api = binding.module.Definition?.API || binding.module.Api;
-    return Api ? new Api({}) : null;
-}
-
-async function runVerify(binding, input, ctx) {
-    const { ext } = binding;
-    let out;
-    if (typeof ext.verify === 'string') {
-        const api = appApiOf(binding);
-        if (!api || typeof api[ext.verify] !== 'function') return { valid: false, reason: `the module Api has no ${ext.verify}()` };
-        out = await api[ext.verify](input);
-    } else {
-        out = await ext.verify(input, ctx);
-    }
-    if (typeof out === 'boolean') return { valid: out, reason: out ? undefined : 'signature check failed' };
-    return { valid: Boolean(out?.valid), reason: out?.reason };
-}
-
-/** The installations an external account belongs to, among this integration type: the entity reverse lookup. */
-async function defaultLookup(IntegrationClass, externalId, moduleName) {
-    const { createIntegrationCommands } = require('../../application/commands/integration-commands');
-    const commands = createIntegrationCommands({ integrationClass: IntegrationClass });
-    const ids = await commands.listIntegrationsByEntityExternalId(String(externalId), moduleName);
-    const out = [];
-    for (const integrationId of ids || []) {
-        const found = await commands.loadIntegrationContextById(integrationId);
-        const type = found?.context?.record?.config?.type;
-        if (type === undefined || type === IntegrationClass.Definition.name) out.push(integrationId);
-    }
-    return out;
-}
-
-/**
- * @param {object} binding { moduleKey, extKey, ext, module, moduleName, options }
- * @param {object} plan the integration's compiled plan (on handlers), read at call time
- * @returns {{ key: string, compiled: object, emitted: string[], prefix: string }}
- */
-function compileBinding(binding) {
-    const { moduleKey, extKey, ext } = binding;
-    const key = bindingKeyOf(moduleKey, extKey);
-    const prefix = eventPrefixOf(moduleKey, extKey);
-    const RECEIVED = `${prefix}RECEIVED`;
-    const RESOLVE = `${prefix}RESOLVE`;
-    const DISPATCH = `${prefix}DISPATCH`;
-    const emits = ext.emits || {};
-    const emitted = Object.keys(emits).map((n) => `${moduleKey}.${n}`);
-    const env = () => envFor(ext);
-    const where = `${moduleKey}-${extKey}`;
-
-    /** Receipt: handshake, verification, split. No database: the binding's function has no Prisma layer. */
-    async function received({ req, res }) {
-        const { webhookRequestFacts } = require('../integration-base');
-        const input = { headers: req.headers || {}, body: req.body, query: req.query || {}, params: req.params || {}, ...webhookRequestFacts(req) };
-        const ctx = { env: env(), options: binding.options, log: this.logger };
-        if (ext.handshake) {
-            const h = await ext.handshake(input, ctx);
-            if (h) {
-                for (const [k, v] of Object.entries(h.headers || {})) res.set(k, String(v));
-                res.status(h.status || 200);
-                return h.body === undefined ? {} : h.body;
-            }
-        }
-        if (ext.verify) {
-            const v = await runVerify(binding, input, ctx);
-            if (!v.valid) {
-                this.logger.warn('Webhook rejected', { eventName: 'frigg.extension.webhook_rejected', binding: where, reason: v.reason });
-                res.status(401);
-                return { error: 'invalid signature' };
-            }
-        }
-        const items = (await ext.receive(input, ctx)) || [];
-        let queued = 0;
-        for (const item of items) {
-            if (item?.externalId === undefined || item?.externalId === null) {
-                this.logger.warn('Webhook item without an account id skipped', { eventName: 'frigg.extension.webhook_item_skipped', binding: where });
-                continue;
-            }
-            await this.queueWebhook({ event: RESOLVE, externalId: String(item.externalId), body: item.body });
-            queued += 1;
-        }
-        return { received: items.length, queued };
-    }
-
-    /** Worker, dry instance: which installations of this integration the account belongs to; one message each. */
-    async function resolve({ data = {} } = {}) {
-        const Cls = this.constructor;
-        const lookup = (externalId, moduleName) => (Cls.lookupInstallations || defaultLookup)(Cls, externalId, moduleName);
-        const ids = typeof ext.resolve === 'function'
-            ? await ext.resolve({ externalId: data.externalId, body: data.body }, { lookup, env: env(), log: this.logger })
-            : await lookup(data.externalId, ext.resolve.module);
-        if (!ids?.length) {
-            this.logger.info('Webhook for an account with no installation', { eventName: 'frigg.extension.webhook_unresolved', binding: where });
-            return { resolved: 0 };
-        }
-        for (const integrationId of ids) await this.queueWebhook({ event: DISPATCH, integrationId, body: data.body });
-        return { resolved: ids.length };
-    }
-
-    /** Worker, the installation hydrated: normalize into named events and run the integration's handlers. */
-    async function dispatch({ data = {} } = {}) {
-        const config = this.resolvedConfig();
-        const ctx = { api: this[moduleKey]?.api, options: resolveOptions(binding, config), config, env: env(), log: this.logger };
-        const events = ext.normalize ? await ext.normalize([data.body], ctx) : [data.body];
-        const results = [];
-        for (const e of events || []) results.push(await this.runEmitted(binding, e?.name, e?.payload));
-        return { dispatched: results.filter((r) => r === 'handled').length, events: results.length };
-    }
-
-    const events = {
-        [RECEIVED]: { type: 'LIFE_CYCLE_EVENT', handler: received },
-        [RESOLVE]: { type: 'LIFE_CYCLE_EVENT', handler: resolve },
-        [DISPATCH]: { type: 'LIFE_CYCLE_EVENT', handler: dispatch },
-    };
-    for (const name of Object.keys(emits)) {
-        events[`${prefix}${upper(name)}`] = {
-            type: 'LIFE_CYCLE_EVENT',
-            handler: async function emittedEvent({ data = {} } = {}) { return this.runEmitted(binding, name, data.payload); },
-        };
-    }
-    const compiled = {
-        extension: {
-            name: ext.name,
-            useDatabase: ext.useDatabase ?? false,
-            routes: (ext.routes || []).map((r) => ({ path: r.path, method: r.method, event: RECEIVED })),
-            events,
-        },
-    };
-    return { key, compiled, emitted, prefix };
-}
-
-module.exports = { compileBinding, resolveOptions, appApiOf, runVerify, defaultLookup, bindingKeyOf, eventPrefixOf, envFor, upper };

package/integrations/define/index.js

@@ -1,11 +0,0 @@
-/**
- * One-file integrations (ADR-054, the stable event-driven path): `defineIntegration`, `defineApp`, `use`, and the
- * contract-2 extension helper. See DESIGN.md in this folder for how it shares the ADR-063 runtime.
- */
-const { defineIntegration, planOf } = require('./define-integration');
-const { defineApp } = require('./define-app');
-const { use } = require('./use');
-const { defineExtension, validateExtension, isContract2 } = require('./define-extension');
-const { reconcileAppSubscriptions, ensureInstallationSubscriptions, createReconcileSubscriptionsScript } = require('./subscriptions');
-
-module.exports = { defineIntegration, defineApp, use, defineExtension, validateExtension, isContract2, reconcileAppSubscriptions, ensureInstallationSubscriptions, createReconcileSubscriptionsScript, planOf };