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

package/integrations/define/json-schema-lite.js

@@ -1,68 +0,0 @@
-/**
- * The small part of JSON Schema that extension `options` and `config` need, without a dependency: type, properties,
- * required, additionalProperties: false, items, enum, const, oneOf/anyOf, minimum/maximum, default. Pure.
- *
- * A function value is accepted for any property: binding options may depend on instance config (ADR-054 §4,
- * `subscribe: (config) => [...]`), and they are checked again once resolved.
- */
-const typeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
-
-function matchesType(value, type) {
-    const t = typeOf(value);
-    if (type === 'integer') return t === 'number' && Number.isInteger(value);
-    return t === type;
-}
-
-/**
- * @param {object} schema
- * @param {*} value
- * @param {string} [path]
- * @returns {string[]} problems, empty when valid
- */
-function check(schema, value, path = '') {
-    if (!schema || typeof schema !== 'object') return [];
-    if (typeof value === 'function') return [];
-    const at = path || '(root)';
-    const problems = [];
-    if (schema.type !== undefined) {
-        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-        if (!types.some((t) => matchesType(value, t))) return [`${at} must be ${types.join(' or ')}`];
-    }
-    if (schema.const !== undefined && value !== schema.const) problems.push(`${at} must be ${JSON.stringify(schema.const)}`);
-    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) problems.push(`${at} must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}`);
-    if (typeof value === 'number') {
-        if (schema.minimum !== undefined && value < schema.minimum) problems.push(`${at} must be >= ${schema.minimum}`);
-        if (schema.maximum !== undefined && value > schema.maximum) problems.push(`${at} must be <= ${schema.maximum}`);
-    }
-    for (const key of ['oneOf', 'anyOf']) {
-        if (Array.isArray(schema[key])) {
-            const passing = schema[key].filter((s) => check(s, value, path).length === 0).length;
-            if (key === 'oneOf' ? passing !== 1 : passing === 0) problems.push(`${at} does not match ${key === 'oneOf' ? 'exactly one' : 'any'} of the allowed shapes`);
-        }
-    }
-    if (typeOf(value) === 'object') {
-        for (const req of schema.required || []) {
-            if (value[req] === undefined) problems.push(`${path ? `${path}.` : ''}${req} is required`);
-        }
-        const props = schema.properties || {};
-        for (const [k, v] of Object.entries(value)) {
-            if (props[k]) problems.push(...check(props[k], v, path ? `${path}.${k}` : k));
-            else if (schema.additionalProperties === false) problems.push(`${path ? `${path}.` : ''}${k} is not an allowed option`);
-        }
-    }
-    if (typeOf(value) === 'array' && schema.items) {
-        value.forEach((item, i) => problems.push(...check(schema.items, item, `${path}[${i}]`)));
-    }
-    return problems;
-}
-
-/** The value with the schema's top-level property defaults filled in (shallow, as config forms do). */
-function withDefaults(schema, value = {}) {
-    const out = { ...(value || {}) };
-    for (const [k, prop] of Object.entries(schema?.properties || {})) {
-        if (out[k] === undefined && prop && prop.default !== undefined) out[k] = prop.default;
-    }
-    return out;
-}
-
-module.exports = { check, withDefaults };

package/integrations/define/subscriptions.js

@@ -1,186 +0,0 @@
-/**
- * App-scope webhook subscriptions (ADR-054 §2): one set per provider app, shared by every account (HubSpot v3
- * subscriptions belong to the developer app, not to a portal). The desired set is the union over every integration
- * class in the app that enables the extension: a static `use()` option counts once per class, an option that is a
- * function of instance config counts once per ENABLED installation.
- *
- *     subscriptions: {
- *         scope: 'app',
- *         desired: (options) => options.subscribe,             // what one binding needs, as keys
- *         list: (api, env) => api.listWebhookSubscriptions(…), // what the provider has
- *         key: (sub) => 'deal.propertyChange:dealstage',       // a listed subscription as a desired key
- *         create: (api, env, key) => …,
- *         remove: (api, env, sub) => …,                        // used only with prune
- *     }
- *
- * Add-only by default. Reconcile creates what is missing and never removes anything unless it is called with
- * `prune: true`. A dry run reports `create` and `remove` (what pruning would do) and writes nothing. Pruning also
- * needs the full union: when an option depends on installation config and the installations cannot be listed (a
- * deploy step without database access), the group is not pruned and the result says why.
- *
- * Supported setup: one provider developer app per stage. The subscriptions are app-wide, so two stages (or two
- * Frigg apps) that share a developer app would see, and with `prune` remove, each other's subscriptions.
- *
- * Invokers (no recurring trigger):
- *   (a) after deploy: `frigg deploy` (devtools) runs it add-only; `--prune-subscriptions` prunes;
- *   (b) installation lifecycle: create and config update of an installation whose binding options are functions of
- *       its config (`ensureInstallationSubscriptions`, add-only, that installation's needs only);
- *   (c) the admin script (`createReconcileSubscriptionsScript`, with `prune` and `dryRun` inputs).
- */
-const { planOf } = require('./define-integration');
-const { resolveOptions, appApiOf, envFor } = require('./extension-binding');
-
-const hasFunctionOption = (binding) => Object.values(binding.options === true ? {} : binding.options || {}).some((v) => typeof v === 'function');
-
-/** Every ENABLED installation of a class, paged by id (what the trigger tick reads). Needs the database. */
-function defaultListInstallations() {
-    let repository;
-    return async function* list(IntegrationClass) {
-        if (!repository) repository = require('../repositories/integration-repository-factory').createIntegrationRepository();
-        let after;
-        for (;;) {
-            const page = await repository.findIntegrations({ type: IntegrationClass.Definition.name, status: 'ENABLED', limit: 500, after });
-            if (!page?.length) return;
-            yield* page;
-            if (page.length < 500) return;
-            after = page[page.length - 1].id;
-        }
-    };
-}
-
-/** The app-scope bindings of some classes, grouped by extension. */
-function groupsOf(integrations, only) {
-    const groups = new Map();   // ext -> [{ Cls, binding }]
-    for (const Cls of integrations) {
-        for (const binding of planOf(Cls)?.extensionBindings || []) {
-            if (binding.ext.subscriptions?.scope !== 'app') continue;
-            if (only && binding.ext.name !== only) continue;
-            if (!groups.has(binding.ext)) groups.set(binding.ext, []);
-            groups.get(binding.ext).push({ Cls, binding });
-        }
-    }
-    return groups;
-}
-
-function keyOf(subs) {
-    return (s) => (typeof s === 'string' ? s : subs.key ? subs.key(s) : s.key);
-}
-
-/**
- * @param {object} params
- * @param {Function[]} params.integrations the app's integration classes (appDefinition.integrations)
- * @param {((Cls: Function) => AsyncIterable<{ id, config }>)|null} [params.listInstallations] null: no database
- * @param {boolean} [params.prune] remove what no binding needs (default false: add-only)
- * @param {boolean} [params.dryRun] plan only: report create and remove, write nothing
- * @param {string} [params.extension] only this extension (by name)
- * @param {object} [params.log]
- * @returns {Promise<Array<{ extension, module, desired, create, remove, kept, created, removed, complete, pruneSkipped? }>>}
- */
-async function reconcileAppSubscriptions({ integrations = [], listInstallations = defaultListInstallations(), prune = false, dryRun = false, extension, log } = {}) {
-    const results = [];
-    for (const [ext, entries] of groupsOf(integrations, extension)) {
-        const subs = ext.subscriptions;
-        const desired = new Set();
-        let complete = true;
-        const want = (options) => { for (const k of subs.desired(options) || []) desired.add(typeof k === 'string' ? k : subs.key(k)); };
-        for (const { Cls, binding } of entries) {
-            if (!hasFunctionOption(binding)) { want(resolveOptions(binding, {})); continue; }
-            if (!listInstallations) { complete = false; continue; }
-            for await (const installation of listInstallations(Cls)) {
-                try {
-                    want(resolveOptions(binding, installation.config || {}));
-                } catch (error) {
-                    complete = false;
-                    log?.warn?.('Installation options skipped in subscription reconcile', { eventName: 'frigg.subscriptions.options_invalid', integrationId: installation.id, error });
-                }
-            }
-        }
-        const { binding } = entries[0];
-        const api = appApiOf(binding);
-        const env = envFor(ext);
-        const existing = (await subs.list(api, env)) || [];
-        const k = keyOf(subs);
-        const existingKeys = new Map(existing.map((s) => [k(s), s]));
-        const create = [...desired].filter((key) => !existingKeys.has(key));
-        const remove = subs.remove ? [...existingKeys.keys()].filter((key) => !desired.has(key)) : [];
-        const kept = [...existingKeys.keys()].filter((key) => desired.has(key));
-        let pruneSkipped;
-        if (prune && !subs.remove) pruneSkipped = 'the extension has no subscriptions.remove';
-        else if (prune && !complete) pruneSkipped = 'installation config could not be read for every binding, so the desired set is incomplete';
-        const created = [], removed = [];
-        if (!dryRun) {
-            for (const key of create) { await subs.create(api, env, key); created.push(key); }
-            if (prune && !pruneSkipped) for (const key of remove) { await subs.remove(api, env, existingKeys.get(key)); removed.push(key); }
-        }
-        log?.info?.('Webhook subscriptions reconciled', { eventName: 'frigg.subscriptions.reconciled', extension: ext.name, created: created.length, removed: removed.length, wouldRemove: remove.length, prune, dryRun });
-        results.push({ extension: ext.name, module: binding.moduleName, desired: [...desired], create, remove, kept, created, removed, complete, ...(pruneSkipped ? { pruneSkipped } : {}) });
-    }
-    return results;
-}
-
-/**
- * Lifecycle invoker (b): the subscriptions one installation needs, created when missing. Only bindings whose options
- * are functions of installation config take part (a static option was handled at deploy). Add-only: a deleted or
- * reconfigured installation's old subscriptions stay until a reconcile runs with `prune`.
- * @param {object} integration a hydrated defineIntegration instance
- * @returns {Promise<Array<{ extension, created: string[] }>>}
- */
-async function ensureInstallationSubscriptions(integration) {
-    const plan = planOf(integration.constructor);
-    const out = [];
-    for (const binding of plan?.extensionBindings || []) {
-        const subs = binding.ext.subscriptions;
-        if (subs?.scope !== 'app' || !hasFunctionOption(binding)) continue;
-        const desired = (subs.desired(resolveOptions(binding, integration.resolvedConfig())) || []).map((d) => (typeof d === 'string' ? d : subs.key(d)));
-        const api = appApiOf(binding);
-        const env = envFor(binding.ext);
-        const have = new Set(((await subs.list(api, env)) || []).map(keyOf(subs)));
-        const created = [];
-        for (const key of desired) if (!have.has(key)) { await subs.create(api, env, key); created.push(key); }
-        out.push({ extension: binding.ext.name, created });
-    }
-    return out;
-}
-
-/**
- * Admin-script invoker (c): an admin script class (the AdminScriptBase shape, no import needed) that runs the
- * reconcile in the deployed stack, where the installations can be read. Inputs: `prune`, `dryRun` (or
- * `args: ['--prune', '--dry-run']`).
- *
- *     const { createReconcileSubscriptionsScript } = require('@friggframework/core');
- *     module.exports = createReconcileSubscriptionsScript({ name: 'hubspot.reconcile-subscriptions', extension: 'hubspot-webhooks' });
- */
-function createReconcileSubscriptionsScript({ name = 'frigg.subscriptions.reconcile', extension, description, loadIntegrations } = {}) {
-    return class ReconcileSubscriptionsScript {
-        static Definition = {
-            name,
-            version: '1.0.0',
-            description: description || `Create the app-scope webhook subscriptions${extension ? ` of ${extension}` : ''} that installed integrations need; with prune, remove the ones none needs.`,
-            source: 'BUILTIN',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    prune: { type: 'boolean', default: false, description: 'Remove subscriptions no binding needs (one developer app per stage only)' },
-                    dryRun: { type: 'boolean', default: false, description: 'Report what would be created and removed; change nothing' },
-                    args: { type: 'array', items: { type: 'string', enum: ['--prune', '--dry-run'] }, description: 'CLI form of the flags' },
-                },
-            },
-            config: { timeout: 300000, requireIntegrationInstance: false },
-            display: { category: 'maintenance', icon: null },
-        };
-
-        constructor(params = {}) { this.context = params.context || null; }
-
-        /** `{ prune, dryRun }`, or the CLI form `{ args: ['--prune', '--dry-run'] }`. */
-        async execute({ prune = false, dryRun = false, args = [] } = {}) {
-            const flags = Array.isArray(args) ? args : String(args).split(/\s+/);
-            prune = Boolean(prune) || flags.includes('--prune');
-            dryRun = Boolean(dryRun) || flags.includes('--dry-run');
-            const integrations = loadIntegrations ? await loadIntegrations() : require('../../handlers/app-definition-loader').loadAppDefinition().integrations;
-            const results = await reconcileAppSubscriptions({ integrations, prune: Boolean(prune), dryRun: Boolean(dryRun), extension });
-            return { prune: Boolean(prune), dryRun: Boolean(dryRun), results };
-        }
-    };
-}
-
-module.exports = { reconcileAppSubscriptions, ensureInstallationSubscriptions, createReconcileSubscriptionsScript, hasFunctionOption };

package/integrations/define/tests/fixtures/hubspot.js

@@ -1,109 +0,0 @@
-/**
- * A test stand-in for @friggframework/api-module-hubspot with its webhooks extension on contract 2: the same shape
- * as the module change (api-module-library `claude/hubspot-contract-2`), reduced to what example (a) touches. Real
- * HTTP through core's OAuth2Requester, so tests nock api.hubapi.com.
- */
-const crypto = require('crypto');
-const { OAuth2Requester } = require('../../../../modules/requester/oauth-2');
-
-const BASE = 'https://api.hubapi.com';
-const OBJECT_TYPE_IDS = { contact: '0-1', company: '0-2', deal: '0-3' };
-
-class Api extends OAuth2Requester {
-    constructor(params = {}) {
-        super(params);
-        this.portalId = params.portalId ?? null;
-        this.urls = { record: (type, id) => `https://app.hubspot.com/contacts/${this.portalId}/record/${OBJECT_TYPE_IDS[type] || type}/${id}` };
-    }
-    getOwnerById(id) { return this._get({ url: `${BASE}/crm/v3/owners/${id}` }); }
-    batchReadObjects(type, body) { return this._post({ url: `${BASE}/crm/v3/objects/${type}/batch/read`, body }); }
-    getPipelineDetails(type) { return this._get({ url: `${BASE}/crm/v3/pipelines/${type}` }); }
-    async listWebhookSubscriptions({ appId }) { return (await this._get({ url: `${BASE}/webhooks/v3/${appId}/subscriptions` })).results || []; }
-    createWebhookSubscription({ appId, eventType, propertyName }) { return this._post({ url: `${BASE}/webhooks/v3/${appId}/subscriptions`, body: { eventType, ...(propertyName ? { propertyName } : {}), active: true } }); }
-    deleteWebhookSubscription({ appId, subscriptionId }) { return this._delete({ url: `${BASE}/webhooks/v3/${appId}/subscriptions/${subscriptionId}` }); }
-}
-
-const Definition = { moduleName: 'hubspot', getName: () => 'hubspot', API: Api };
-
-/** HubSpot v3: base64(HMAC-SHA256(secret, method + url + rawBody + timestamp)), 5 minutes. */
-function verify(input, { env }) {
-    const h = Object.fromEntries(Object.entries(input.headers || {}).map(([k, v]) => [k.toLowerCase(), v]));
-    const ts = Number(h['x-hubspot-request-timestamp']);
-    if (!env.HUBSPOT_CLIENT_SECRET) return { valid: false, reason: 'missing client secret' };
-    if (!h['x-hubspot-signature-v3'] || !Number.isFinite(ts)) return { valid: false, reason: 'missing signature headers' };
-    if (Math.abs(Date.now() - ts) > 5 * 60 * 1000) return { valid: false, reason: 'timestamp outside 5 minutes' };
-    const body = input.rawBody ?? JSON.stringify(input.body ?? '');
-    const expected = crypto.createHmac('sha256', env.HUBSPOT_CLIENT_SECRET).update(`${input.method}${input.url}${body}${h['x-hubspot-request-timestamp']}`).digest('base64');
-    const a = Buffer.from(expected), b = Buffer.from(String(h['x-hubspot-signature-v3']));
-    return { valid: a.length === b.length && crypto.timingSafeEqual(a, b), reason: 'signature mismatch' };
-}
-
-const VERBS = { creation: 'created', propertyChange: 'changed', deletion: 'deleted' };
-const PLURAL = { deal: 'deals', contact: 'contacts', company: 'companies' };
-
-async function normalize(batch, { api, options }) {
-    const out = [];
-    for (const e of batch) {
-        const [object, kind] = String(e.subscriptionType || '').split('.');
-        if (!PLURAL[object] || !VERBS[kind]) continue;
-        if (api && api.portalId == null) api.portalId = String(e.portalId);
-        const changes = kind === 'propertyChange' ? { [e.propertyName]: { to: e.propertyValue } } : {};
-        let record = { id: String(e.objectId), properties: kind === 'propertyChange' ? { [e.propertyName]: e.propertyValue } : {} };
-        if (options.hydrate && kind !== 'deletion') {
-            const properties = Array.isArray(options.hydrate) ? options.hydrate : undefined;
-            const res = await api.batchReadObjects(PLURAL[object], { inputs: [{ id: String(e.objectId) }], ...(properties ? { properties } : {}) });
-            record = res.results?.[0] || record;
-        }
-        out.push({ name: `${object}.${VERBS[kind]}`, payload: { [object]: record, changes, event: e } });
-    }
-    return out;
-}
-
-const webhooks = {
-    name: 'hubspot-webhooks',
-    contract: 2,
-    requires: { core: '>=2.0.0-next.0 <3' },
-    useDatabase: false,
-    env: ['HUBSPOT_CLIENT_SECRET', 'HUBSPOT_APP_ID', 'HUBSPOT_DEVELOPER_API_KEY'],
-    options: {
-        type: 'object',
-        properties: {
-            subscribe: { type: 'array', items: { type: 'string' } },
-            hydrate: { oneOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }], default: false },
-        },
-        required: ['subscribe'],
-        additionalProperties: false,
-    },
-    routes: [{ path: '/webhooks', method: 'POST' }],
-    verify,
-    receive: (input) => (Array.isArray(input.body) ? input.body : []).map((e) => ({ externalId: e?.portalId, body: e })),
-    resolve: { module: 'hubspot' },
-    emits: {
-        'deal.created': {}, 'deal.changed': {}, 'deal.deleted': {},
-        'contact.created': {}, 'contact.changed': {}, 'contact.deleted': {},
-        'company.created': {}, 'company.changed': {}, 'company.deleted': {},
-    },
-    normalize,
-    subscriptions: {
-        scope: 'app',
-        desired: (options) => options.subscribe,
-        key: (s) => (s.propertyName ? `${s.eventType}:${s.propertyName}` : s.eventType),
-        list: (api, env) => api.listWebhookSubscriptions({ appId: env.HUBSPOT_APP_ID }),
-        create: (api, env, key) => { const [eventType, propertyName] = key.split(':'); return api.createWebhookSubscription({ appId: env.HUBSPOT_APP_ID, eventType, propertyName }); },
-        remove: (api, env, sub) => api.deleteWebhookSubscription({ appId: env.HUBSPOT_APP_ID, subscriptionId: sub.id }),
-    },
-};
-
-const fields = {
-    dealStages: ({ title = 'Deal stage', multiple = false, required = false, default: dflt } = {}) => ({
-        module: 'hubspot',
-        required,
-        schema: multiple ? { type: 'array', title, items: { type: 'string' }, ...(dflt !== undefined ? { default: dflt } : {}) } : { type: 'string', title, ...(dflt !== undefined ? { default: dflt } : {}) },
-        options: async (api) => {
-            const res = await api.getPipelineDetails('deals');
-            return (res.results || []).flatMap((p) => (p.stages || []).map((s) => ({ const: s.id, title: `${p.label}: ${s.label}` })));
-        },
-    }),
-};
-
-module.exports = { Api, Definition, extensions: { webhooks }, fields };

package/integrations/define/tests/fixtures/slack.js

@@ -1,26 +0,0 @@
-/**
- * A test stand-in for @friggframework/api-module-slack as ADR-054 item 6 describes it (bot token, fields.channel):
- * no extension, only an Api and a config field. Real HTTP through core's OAuth2Requester, so tests nock slack.com.
- */
-const { OAuth2Requester } = require('../../../../modules/requester/oauth-2');
-
-const BASE = 'https://slack.com/api';
-
-class Api extends OAuth2Requester {
-    postMessage(body) { return this._post({ url: `${BASE}/chat.postMessage`, body, headers: { 'Content-Type': 'application/json; charset=utf-8' } }); }
-    lookupUserByEmail(email) { return this._get({ url: `${BASE}/users.lookupByEmail`, query: { email } }); }
-    listConversations() { return this._get({ url: `${BASE}/conversations.list`, query: { types: 'public_channel,private_channel', exclude_archived: true } }); }
-}
-
-const Definition = { moduleName: 'slack', getName: () => 'slack', API: Api };
-
-const fields = {
-    channel: ({ title = 'Channel', required = false } = {}) => ({
-        module: 'slack',
-        required,
-        schema: { type: 'string', title },
-        options: async (api) => ((await api.listConversations()).channels || []).map((c) => ({ const: c.id, title: `#${c.name}` })),
-    }),
-};
-
-module.exports = { Api, Definition, extensions: {}, fields };

package/integrations/define/use.js

@@ -1,39 +0,0 @@
-/**
- * `use(module, extensionOptions?)` (ADR-054 §1): a module binding that enables some of the module's extensions.
- *
- *     modules: {
- *         crm: use(hubspot, { webhooks: { subscribe: ['deal.creation'] } }),   // enable hubspot.extensions.webhooks
- *         chat: use(slack),                                                    // no extension
- *         erp: erp,                                                            // the module export alone
- *         old: { definition: erp.Definition },                                 // the shape Definition.modules has today
- *     }
- *
- * The key (`crm`) is the integration author's: it names `ctx.modules.crm`, the routes, events, triggers and fields
- * the module's extensions contribute. `use` is core's, so a module does not implement it.
- */
-const BINDING = Symbol.for('frigg.define.binding');
-
-function use(module, extensions = {}) {
-    if (!module || typeof module !== 'object' || !module.Definition) {
-        throw new Error('use(module, options): the first argument must be an API module export (it has a Definition)');
-    }
-    if (!extensions || typeof extensions !== 'object' || Array.isArray(extensions)) {
-        throw new Error(`use(${module.Definition.moduleName || 'module'}, options): options are an object keyed by extension name`);
-    }
-    return { [BINDING]: true, module, extensions };
-}
-
-/** Any accepted form of a `modules` entry, as `{ key, module, extensions, moduleName }`. */
-function normalizeBinding(key, value) {
-    let module, extensions = {};
-    if (value && value[BINDING]) ({ module, extensions } = value);
-    else if (value?.Definition) module = value;
-    else if (value?.definition) module = { Definition: value.definition };
-    else throw new Error(`modules.${key}: expected use(module), a module export, or { definition }`);
-    const def = module.Definition;
-    const moduleName = typeof def.getName === 'function' ? def.getName() : def.moduleName;
-    if (!moduleName) throw new Error(`modules.${key}: the module's Definition has no moduleName`);
-    return { key, module, extensions, moduleName };
-}
-
-module.exports = { use, normalizeBinding, BINDING };