@friggframework/core 2.0.0--canary.707.df80bfd.0 → 2.0.0--canary.680.d670696.0

package/integrations/schedule-config.js

@@ -1,80 +0,0 @@
-/**
- * An integration's schedule configuration (`static Definition.schedule`),
- * read by hosts that tick ONGOING_SYNC from a cron (provider-netlify's
- * scheduled-sync function).
- *
- *   schedule: {
- *       // 'class' (default): one ONGOING_SYNC per integration class per tick,
- *       //   with no integration id: the worker runs it on an unhydrated
- *       //   instance, so the handler finds its own installations.
- *       // 'installation': one ONGOING_SYNC per ENABLED integration record of
- *       //   the class, carrying `data.integrationId`, so the worker hydrates
- *       //   that installation before the handler runs.
- *       scope: 'installation',
- *       // Optional, 'installation' only: (integration, { now }) => boolean |
- *       // Promise<boolean>. Return false to skip that installation this tick.
- *       // Without it every installation is dispatched on every tick.
- *       isDue: (integration, { now }) => true,
- *   }
- *
- * Validated at load (loadAppDefinition) so a mistyped scope stops the app
- * rather than silently falling back to 'class'.
- */
-
-const SCHEDULE_SCOPES = Object.freeze({
-    CLASS: 'class',
-    INSTALLATION: 'installation',
-});
-
-const DEFAULT_SCHEDULE_SCOPE = SCHEDULE_SCOPES.CLASS;
-
-class ScheduleConfigError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ScheduleConfigError';
-        this.code = 'SCHEDULE_CONFIG_INVALID';
-    }
-}
-
-/**
- * @param {Object} [definition] - an integration's static Definition
- * @returns {{ scope: 'class'|'installation', isDue: Function|null }}
- * @throws {ScheduleConfigError} when `schedule` is malformed
- */
-function resolveScheduleConfig(definition) {
-    const name = definition?.name || 'integration';
-    const schedule = definition?.schedule;
-    if (schedule === undefined || schedule === null) {
-        return { scope: DEFAULT_SCHEDULE_SCOPE, isDue: null };
-    }
-    if (typeof schedule !== 'object' || Array.isArray(schedule)) {
-        throw new ScheduleConfigError(`${name}: Definition.schedule must be an object`);
-    }
-
-    const scopes = Object.values(SCHEDULE_SCOPES);
-    const scope = schedule.scope === undefined ? DEFAULT_SCHEDULE_SCOPE : schedule.scope;
-    if (!scopes.includes(scope)) {
-        throw new ScheduleConfigError(
-            `${name}: Definition.schedule.scope must be one of ${scopes.map((s) => `'${s}'`).join(', ')} (got ${JSON.stringify(schedule.scope)})`
-        );
-    }
-
-    const isDue = schedule.isDue === undefined ? null : schedule.isDue;
-    if (isDue !== null && typeof isDue !== 'function') {
-        throw new ScheduleConfigError(`${name}: Definition.schedule.isDue must be a function`);
-    }
-    if (isDue && scope !== SCHEDULE_SCOPES.INSTALLATION) {
-        throw new ScheduleConfigError(
-            `${name}: Definition.schedule.isDue applies to scope 'installation' only`
-        );
-    }
-
-    return { scope, isDue };
-}
-
-module.exports = {
-    SCHEDULE_SCOPES,
-    DEFAULT_SCHEDULE_SCOPE,
-    ScheduleConfigError,
-    resolveScheduleConfig,
-};

package/integrations/use-cases/dispatch-ongoing-syncs.js

@@ -1,100 +0,0 @@
-const {
-    SCHEDULE_SCOPES,
-    resolveScheduleConfig,
-} = require('../schedule-config');
-
-const ONGOING_SYNC_EVENT = 'ONGOING_SYNC';
-const ACTIVE_STATUS = 'ENABLED';
-
-/**
- * Dispatches one cron tick of ONGOING_SYNC to the queue worker, per each
- * integration class's `Definition.schedule.scope` (schedule-config.js):
- *
- * - 'class' (default): one message per class, `data: {}`.
- * - 'installation': one message per ENABLED integration record of the class,
- *   `data: { integrationId }`, so the worker hydrates that installation;
- *   skipped when the definition's `isDue(integration, { now })` says no.
- *
- * Only classes that implement `startOngoingSync` take part. A failure for one
- * class or installation is counted and logged; the rest still go out.
- */
-class DispatchOngoingSyncs {
-    /**
-     * @param {Object} params
-     * @param {Object} params.integrationRepository - findIntegrations({ type, status })
-     * @param {Object} params.queueProvider - send(message, queueId)
-     * @param {string} params.queueId - the worker the messages go to
-     * @param {() => Date} [params.now]
-     * @param {Object} [params.logger=console]
-     */
-    constructor({ integrationRepository, queueProvider, queueId, now = () => new Date(), logger = console }) {
-        this.integrationRepository = integrationRepository;
-        this.queueProvider = queueProvider;
-        this.queueId = queueId;
-        this.now = now;
-        this.logger = logger;
-    }
-
-    /**
-     * @param {Array<Function>} integrationClasses
-     * @returns {Promise<{ dispatched: number, notDue: number, errors: number }>}
-     */
-    async execute(integrationClasses = []) {
-        const result = { dispatched: 0, notDue: 0, errors: 0 };
-        const now = this.now();
-
-        for (const IntegrationClass of integrationClasses) {
-            const name = IntegrationClass?.Definition?.name;
-            if (!name) continue;
-            if (typeof IntegrationClass.prototype?.startOngoingSync !== 'function') continue;
-
-            try {
-                const { scope, isDue } = resolveScheduleConfig(IntegrationClass.Definition);
-                if (scope === SCHEDULE_SCOPES.INSTALLATION) {
-                    await this._dispatchPerInstallation(name, isDue, now, result);
-                } else {
-                    await this._send(name, {});
-                    result.dispatched++;
-                }
-            } catch (error) {
-                result.errors++;
-                this.logger.error(`[ScheduledSync] Failed to dispatch sync for ${name}:`, error.message);
-            }
-        }
-
-        return result;
-    }
-
-    async _dispatchPerInstallation(name, isDue, now, result) {
-        const integrations = await this.integrationRepository.findIntegrations({
-            type: name,
-            status: ACTIVE_STATUS,
-        });
-
-        for (const integration of integrations || []) {
-            try {
-                if (isDue && (await isDue(integration, { now })) !== true) {
-                    result.notDue++;
-                    continue;
-                }
-                await this._send(name, { integrationId: integration.id });
-                result.dispatched++;
-            } catch (error) {
-                result.errors++;
-                this.logger.error(
-                    `[ScheduledSync] Failed to dispatch sync for ${name} integration ${integration?.id}:`,
-                    error.message
-                );
-            }
-        }
-    }
-
-    _send(integrationName, data) {
-        return this.queueProvider.send(
-            { integrationName, event: ONGOING_SYNC_EVENT, data },
-            this.queueId
-        );
-    }
-}
-
-module.exports = { DispatchOngoingSyncs, ONGOING_SYNC_EVENT };

package/integrations/use-cases/resolve-integration-ownership.js

@@ -1,177 +0,0 @@
-const Boom = require('@hapi/boom');
-const { SCOPES, resolveScope } = require('../../modules/scope-resolution');
-const {
-    integrationOwnerKind,
-    resolveIntegrationOwner,
-} = require('../../modules/scope-resolution');
-const {
-    describeRecord,
-    unscopedRowsBelongHere,
-} = require('../../modules/scope-visibility');
-const {
-    bindingScopeSetting,
-    readIntegrationOwnership,
-} = require('../../modules/scope-config');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
-const { entityTypeNameOf } = require('../../modules/entity-type-registry');
-
-const notFound = (entityId) =>
-    Boom.notFound(`Entity ${entityId} not found`, { code: 'ENTITY_NOT_FOUND' });
-
-/**
- * Who owns an integration about to be created, and in which organization
- * (ADR-056 §3, §3.3, §3.6). Shared by the v1 and v2 create paths. Nothing is
- * persisted before this has answered, so a refusal leaves no row behind.
- *
- * Every entity must be one the caller may use in the active organization. A
- * missing one, another organization's and a `global` one are the same 404, so
- * ids cannot be probed. When the integration declares a scope (a binding's
- * `scope` or `Definition.entities[key].scope`, or `Definition.ownership.scope`)
- * the entity's scope must be in it. Levels below the integration (entity type,
- * app, default) decide where a connection is CREATED and do not restrict what
- * an integration may bind, so an app that adds a registry scope later does not
- * break integrations that already use older connections.
- *
- * The owner follows the entities (all organization: the organization;
- * otherwise the person) unless `Definition.ownership.owner` says. Every entity
- * must then be of the owner's own scope: an integration is loaded by its owner,
- * who must own what it uses, so an integration that mixes an organization
- * entity with a person's own, or that names an owner that does not match, is
- * refused with a 400 here, before anything is written.
- */
-class ResolveIntegrationOwnership {
-    /**
-     * @param {Object} params
-     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
-     * @param {Array<Function>} params.integrationClasses
-     * @param {Object} [params.scopePolicy] - from createScopePolicy
-     */
-    constructor({ moduleRepository, integrationClasses, scopePolicy }) {
-        this.moduleRepository = moduleRepository;
-        this.integrationClasses = integrationClasses || [];
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
-    }
-
-    /**
-     * @param {Object} params
-     * @param {Array<string|number>} params.entityIds
-     * @param {Object} params.config - `{ type }`
-     * @param {Object} params.user - authenticated User
-     * @returns {Promise<{ownerId: string, organizationId: (string|null), ownerKind: string, adoptUnscoped: boolean}>}
-     */
-    async execute({ entityIds, config, user }) {
-        const ctx = this.scopePolicy.accessContext(user);
-        const integrationClass = this.integrationClasses.find(
-            (IntegrationClass) => IntegrationClass.Definition?.name === config?.type
-        );
-        const ownership = readIntegrationOwnership(integrationClass);
-
-        const entities = await this.loadEntities(entityIds);
-        const scoped = entities.map((entity) => ({
-            entity,
-            scope: this.acceptedScope({ entity, ctx, integrationClass, ownership }),
-        }));
-
-        const ownerKind = integrationOwnerKind(
-            scoped.map(({ scope }) => scope),
-            ownership.owner
-        );
-        this.assertOneScope(scoped, ownerKind, config?.type);
-        return {
-            ...resolveIntegrationOwner(ownerKind, ctx),
-            ownerKind,
-            // Whether an existing integration with no organization (written
-            // before scoping) is this caller's to reuse. An organization-owned
-            // one is unambiguous: its owner is the organization, whoever asks
-            // and whatever their own legacy pointer says. A person's is theirs
-            // only where scope-visibility says (their legacy organization).
-            adoptUnscoped:
-                ownerKind === SCOPES.ORGANIZATION ||
-                unscopedRowsBelongHere(ctx, 'integration'),
-        };
-    }
-
-    /** Every entity must be of the integration owner's own scope (see the class comment). */
-    assertOneScope(scoped, ownerKind, type) {
-        for (const { entity, scope } of scoped) {
-            if (scope === ownerKind) continue;
-            // The load-time check (resolveOwnershipConfig) only sees declared
-            // scopes; this one sees the entities actually named.
-            if (ownerKind === SCOPES.ORGANIZATION) {
-                throw Boom.badRequest(
-                    "An organization-owned integration cannot use an 'individual' entity: a shared integration must not run on one person's credential",
-                    {
-                        code: 'ORG_INTEGRATION_INDIVIDUAL_ENTITY',
-                        details: { entityId: String(entity.id) },
-                    }
-                );
-            }
-            throw Boom.badRequest(
-                `Integration '${type}' would be owned by the person but uses the organization entity ${entity.id}. An integration must use entities of one scope: all of the person's, or all of the organization's.`,
-                {
-                    code: 'MIXED_ENTITY_SCOPES',
-                    details: { entityId: String(entity.id), scope },
-                }
-            );
-        }
-    }
-
-    async loadEntities(entityIds) {
-        const ids = (entityIds || []).map(String);
-        if (ids.length === 0) return [];
-        let found;
-        try {
-            found = await this.moduleRepository.findEntitiesByIds(ids);
-        } catch (error) {
-            // A malformed id (e.g. not an integer on PostgreSQL) is "not found".
-            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
-                throw notFound(ids[0]);
-            }
-            throw error;
-        }
-        const byId = new Map((found || []).filter(Boolean).map((e) => [String(e.id), e]));
-        return ids.map((id) => {
-            if (!byId.has(id)) throw notFound(id);
-            return byId.get(id);
-        });
-    }
-
-    /** The entity's scope for this caller, or a refusal. */
-    acceptedScope({ entity, ctx, integrationClass, ownership }) {
-        const described = describeRecord(entity, ctx, 'entity');
-        if (!described) throw notFound(entity.id);
-        const { scope } = described;
-
-        const declared = this.declaredScope({ entity, integrationClass, ownership });
-        if (declared && !declared.allow.includes(scope)) {
-            throw Boom.badRequest(
-                `Entity ${entity.id} is ${scope}-scoped, but this integration binds ${entity.moduleName} at ${declared.allow.join(' or ')} scope`,
-                {
-                    code: 'ENTITY_SCOPE_MISMATCH',
-                    details: { entityId: String(entity.id), scope, allowed: declared.allow },
-                }
-            );
-        }
-        return scope;
-    }
-
-    /**
-     * What the integration itself declares for this entity's binding (levels 2
-     * and 3 only), or null when it declares nothing.
-     */
-    declaredScope({ entity, integrationClass, ownership }) {
-        const Definition = integrationClass?.Definition;
-        const key = Object.keys(Definition?.modules || {}).find(
-            (candidate) =>
-                entityTypeNameOf(Definition.modules[candidate]?.definition) ===
-                entity.moduleName
-        );
-        const resolved = resolveScope({
-            binding: key === undefined ? undefined : bindingScopeSetting(Definition, key),
-            integration: ownership.scope,
-        });
-        return resolved.decidedBy === 'default' ? null : resolved;
-    }
-}
-
-module.exports = { ResolveIntegrationOwnership };

package/modules/entity-scope.js

@@ -1,15 +0,0 @@
-/**
- * Entity scopes and ownership (ADR-056 §3), re-exported from the four files it
- * is split into:
- *
- *   scope-resolution  constants, scope resolution, ownership on create
- *   scope-config      reading and validating app-definition settings
- *   scope-visibility  who may see which stored row
- *   scope-policy      the object a use case asks
- */
-module.exports = {
-    ...require('./scope-resolution'),
-    ...require('./scope-config'),
-    ...require('./scope-visibility'),
-    ...require('./scope-policy'),
-};

package/modules/proxy/proxy-bases.js

@@ -1,169 +0,0 @@
-const { ProxyConfigError } = require('./proxy-errors');
-
-/**
- * Named base URLs for the entity proxy (ADR-052, amendment 2026-10-18).
- *
- * A module declares where its API lives. One host is `proxy.baseUrl`, which
- * means `{ default: baseUrl }`. A module whose API spans several hosts (Google:
- * Drive, Docs, Sheets, Analytics Data, Ads) declares `proxy.baseUrls`, a map of
- * name to URL. A caller picks a base by NAME in the proxy request's `base`
- * field; it never supplies a URL or a host, so the host still comes only from
- * the module.
- */
-
-const DEFAULT_BASE = 'default';
-const BASE_NAME = /^[a-z][a-z0-9-]*$/;
-
-const isPlainObject = (value) =>
-    value !== null && typeof value === 'object' && !Array.isArray(value);
-
-const describeRule = (rule) =>
-    `${rule && typeof rule.method === 'string' ? rule.method : '?'} ${
-        rule && typeof rule.path === 'string' ? rule.path : '?'
-    }`;
-
-function isValidBaseName(name) {
-    return typeof name === 'string' && name.length <= 64 && BASE_NAME.test(name);
-}
-
-function assertBaseUrl(moduleName, name, value) {
-    const where = `Module ${moduleName} proxy.baseUrls.${name}`;
-    if (typeof value !== 'string') {
-        throw new ProxyConfigError(`${where} must be an absolute https URL string (functions are not accepted)`);
-    }
-    let url;
-    try {
-        url = new URL(value);
-    } catch {
-        throw new ProxyConfigError(`${where} is not a valid absolute URL`);
-    }
-    if (url.protocol !== 'https:') {
-        throw new ProxyConfigError(`${where} must use https`);
-    }
-    if (url.username || url.password || url.search || url.hash) {
-        throw new ProxyConfigError(
-            `${where} must not carry credentials, a query or a fragment`
-        );
-    }
-}
-
-/**
- * The bases a module declares, validated.
- *
- * @param {object} definition - a module definition
- * @returns {{ names: string[], values: Map<string, string|Function|undefined>, declared: boolean }}
- *   `declared` is false when the module names no base of its own; it then has
- *   the single base `default`, resolved from the requester at call time.
- * @throws {ProxyConfigError}
- */
-function resolveModuleBases(definition) {
-    const moduleName = definition?.moduleName ?? '(unnamed)';
-    const proxy = definition?.proxy;
-    const hasBaseUrl = proxy?.baseUrl !== undefined;
-    const hasBaseUrls = proxy?.baseUrls !== undefined;
-
-    if (hasBaseUrl && hasBaseUrls) {
-        throw new ProxyConfigError(
-            `Module ${moduleName} declares both proxy.baseUrl and proxy.baseUrls; use one ` +
-                '(baseUrl means { default: baseUrl })'
-        );
-    }
-    if (hasBaseUrls) {
-        if (!isPlainObject(proxy.baseUrls) || Object.keys(proxy.baseUrls).length === 0) {
-            throw new ProxyConfigError(
-                `Module ${moduleName} proxy.baseUrls must be a non-empty object of name to URL`
-            );
-        }
-        const values = new Map();
-        for (const [name, value] of Object.entries(proxy.baseUrls)) {
-            if (!isValidBaseName(name)) {
-                throw new ProxyConfigError(
-                    `Module ${moduleName} proxy.baseUrls has the invalid name ${JSON.stringify(
-                        name
-                    )}; names match ${BASE_NAME}`
-                );
-            }
-            assertBaseUrl(moduleName, name, value);
-            values.set(name, value);
-        }
-        return { names: [...values.keys()], values, declared: true };
-    }
-    return {
-        names: [DEFAULT_BASE],
-        values: new Map([[DEFAULT_BASE, proxy?.baseUrl]]),
-        declared: hasBaseUrl,
-    };
-}
-
-/** The base a rule applies to; a rule without `base` applies to `default`. */
-const ruleBase = (rule) => (rule && rule.base !== undefined ? rule.base : DEFAULT_BASE);
-
-/**
- * Load-time check of every allow rule that names a base: the app's
- * `managementApi.proxy.modules.<module>.allow` and each module's own
- * `proxy.allow`. A rule for a base the module does not declare could never
- * match, which reads as "allowed" and is not, so it stops the app.
- *
- * @param {Array<object>} moduleDefinitions
- * @param {{ modules?: Object }} [proxyConfig] - resolved managementApi.proxy
- * @throws {ProxyConfigError}
- */
-function assertProxyConfig(moduleDefinitions, proxyConfig = {}) {
-    const namesByModule = new Map();
-    for (const definition of moduleDefinitions || []) {
-        if (!definition?.moduleName) continue;
-        const { names } = resolveModuleBases(definition);
-        namesByModule.set(definition.moduleName, names);
-        const own = definition.proxy?.allow;
-        if (Array.isArray(own)) {
-            assertRulesUseDeclaredBases(
-                definition.moduleName,
-                names,
-                own,
-                `Module ${definition.moduleName} proxy.allow`
-            );
-        }
-    }
-    for (const [moduleName, override] of Object.entries(proxyConfig.modules || {})) {
-        const names = namesByModule.get(moduleName);
-        // An override for a module that is not registered is not new: it never applied.
-        if (!names || !Array.isArray(override?.allow)) continue;
-        assertRulesUseDeclaredBases(
-            moduleName,
-            names,
-            override.allow,
-            `managementApi.proxy.modules.${moduleName}.allow`
-        );
-    }
-}
-
-function assertRulesUseDeclaredBases(moduleName, names, rules, where) {
-    for (const rule of rules) {
-        if (!isPlainObject(rule) || rule.base === undefined) continue;
-        if (!isValidBaseName(rule.base) || !names.includes(rule.base)) {
-            throw new ProxyConfigError(
-                `${where}: the rule ${describeRule(rule)} names the base ${JSON.stringify(
-                    rule.base
-                )}, which module ${moduleName} does not declare (declared: ${names.join(', ')})`
-            );
-        }
-    }
-    // A rule with no base means `default`; the module must have one.
-    if (!names.includes(DEFAULT_BASE)) {
-        const bare = rules.find((rule) => isPlainObject(rule) && rule.base === undefined);
-        if (bare) {
-            throw new ProxyConfigError(
-                `${where}: the rule ${describeRule(bare)} names no base, so it applies to ` +
-                    `"default", which module ${moduleName} does not declare (declared: ${names.join(', ')})`
-            );
-        }
-    }
-}
-
-module.exports = {
-    DEFAULT_BASE,
-    isValidBaseName,
-    resolveModuleBases,
-    ruleBase,
-    assertProxyConfig,
-};

package/modules/repositories/entity-not-found.js

@@ -1,18 +0,0 @@
-/**
- * The error `findEntityById` throws for an id with no row, and the one
- * predicate that recognises it (as integration-not-found.js does for
- * integrations). The adapters build the error here and use cases match it
- * here, so a missing entity can be told from any other failure without
- * widening a regex.
- *
- * Why it matters: a use case that answers 404 for another tenant's entity must
- * answer the same 404 for an id that does not exist. Otherwise the status code
- * says which ids exist (ADR-052 §3, ADR-056 §3.6).
- */
-const MESSAGE = /^Entity .+ not found$/;
-
-const entityNotFoundError = (id) => new Error(`Entity ${id} not found`);
-
-const isEntityNotFound = (error) => MESSAGE.test(error?.message || '');
-
-module.exports = { entityNotFoundError, isEntityNotFound };