@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

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

@@ -0,0 +1,100 @@
+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/get-integrations-for-user.js

@@ -2,9 +2,17 @@
 const {
     mapIntegrationClassToIntegrationDTO,
 } = require('../utils/map-integration-dto');
+const {
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+} = require('../../modules/scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
 
 /**
- * Use case for retrieving all integrations for a specific user.
+ * Use case for retrieving the integrations a caller may see: the ones they own
+ * or their active organization owns, created in that organization (ADR-056
+ * §3.6), each with `tenancy` ({scope, owner, organizationId, access}).
  * @class GetIntegrationsForUser
  */
 class GetIntegrationsForUser {
@@ -15,13 +23,16 @@ class GetIntegrationsForUser {
      * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes.
      * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
      * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module and entity data operations.
+     * @param {Object} [params.scopePolicy] - from createScopePolicy
      */
     constructor({
         integrationRepository,
         integrationClasses,
         moduleFactory,
         moduleRepository,
+        scopePolicy,
     }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         /**
          * @type {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface}
          */
@@ -32,57 +43,86 @@ class GetIntegrationsForUser {
     }
 
     /**
-     * Executes the retrieval of all integrations for a user.
      * @async
-     * @param {string} userId - ID of the user whose integrations to retrieve.
-     * @returns {Promise<Object[]>} Array of integration DTOs for the specified user.
+     * @param {Object} user - authenticated User
+     * @param {{scope?: string, owner?: string}} [filters] - `?scope=` and `?owner=`
+     * @returns {Promise<Object[]>} Array of integration DTOs.
      */
-    async execute(userId) {
-        const integrationRecords =
-            await this.integrationRepository.findIntegrationsByUserId(userId);
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const records = await this.integrationRepository.findIntegrationsByOwnership(
+            visibilityClauses(ctx, 'integration')
+        );
 
         const integrations = [];
+        for (const record of records) {
+            // The query is the filter; the same rule again means a repository
+            // that returns too much cannot widen the list.
+            const tenancy = describeRecord(record, ctx, 'integration');
+            if (!tenancy || !matchesListFilters(tenancy, filters)) continue;
+            integrations.push({ ...(await this.toDto(record)), tenancy });
+        }
+        return integrations;
+    }
 
-        for (const integrationRecord of integrationRecords) {
-            const entities = await this.moduleRepository.findEntitiesByIds(
-                integrationRecord.entitiesIds
-            );
+    /** Hydrates one stored integration record into its DTO. */
+    async toDto(integrationRecord) {
+        const entities = await this.moduleRepository.findEntitiesByIds(
+            integrationRecord.entitiesIds
+        );
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) =>
+                integrationClass.Definition.name ===
+                integrationRecord.config.type
+        );
 
-            const integrationClass = this.integrationClasses.find(
-                (integrationClass) =>
-                    integrationClass.Definition.name ===
-                    integrationRecord.config.type
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entity.id,
+                integrationRecord.userId
             );
+            modules.push(moduleInstance);
+        }
 
-            const modules = [];
-            for (const entity of entities) {
-                const moduleInstance =
-                    await this.moduleFactory.getModuleInstance(
-                        entity.id,
-                        integrationRecord.userId
-                    );
-                modules.push(moduleInstance);
-            }
+        return mapIntegrationClassToIntegrationDTO({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: entities,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages || { errors: [], warnings: [] },
+            modules,
+            options: integrationClass.getOptionDetails(),
+        });
+    }
+}
 
-            const integrationData = {
-                id: integrationRecord.id,
-                userId: integrationRecord.userId,
-                entities: entities,
-                config: integrationRecord.config,
-                status: integrationRecord.status,
-                version: integrationRecord.version,
-                messages: integrationRecord.messages || { errors: [], warnings: [] },
-                modules,
-                options: integrationClass.getOptionDetails(),
-            };
+/**
+ * Every integration one user id owns, with no organization rules: the lookup
+ * behind the app-level `friggCommands.findIntegrationsByUserId`, which has a
+ * user id and no request.
+ */
+class GetIntegrationsByUserId {
+    /** @param {ConstructorParameters<typeof GetIntegrationsForUser>[0]} params */
+    constructor(params) {
+        this.integrationRepository = params.integrationRepository;
+        this.hydrator = new GetIntegrationsForUser(params);
+    }
 
-            integrations.push(
-                mapIntegrationClassToIntegrationDTO(integrationData)
-            );
+    /** @param {string} userId */
+    async execute(userId) {
+        const records = await this.integrationRepository.findIntegrationsByUserId(
+            userId
+        );
+        const integrations = [];
+        for (const record of records) {
+            integrations.push(await this.hydrator.toDto(record));
         }
-
         return integrations;
     }
 }
 
-module.exports = { GetIntegrationsForUser };
+module.exports = { GetIntegrationsForUser, GetIntegrationsByUserId };

package/integrations/use-cases/index.js

@@ -1,4 +1,7 @@
-const { GetIntegrationsForUser } = require('./get-integrations-for-user');
+const {
+    GetIntegrationsForUser,
+    GetIntegrationsByUserId,
+} = require('./get-integrations-for-user');
 const { DeleteIntegrationForUser } = require('./delete-integration-for-user');
 const { CreateIntegration } = require('./create-integration');
 const { GetIntegration } = require('./get-integration');
@@ -6,9 +9,11 @@ const { CreateProcess } = require('./create-process');
 const { UpdateProcessState } = require('./update-process-state');
 const { UpdateProcessMetrics } = require('./update-process-metrics');
 const { GetProcess } = require('./get-process');
+const { DispatchOngoingSyncs } = require('./dispatch-ongoing-syncs');
 
 module.exports = {
     GetIntegrationsForUser,
+    GetIntegrationsByUserId,
     DeleteIntegrationForUser,
     CreateIntegration,
     GetIntegration,
@@ -16,4 +21,5 @@ module.exports = {
     UpdateProcessState,
     UpdateProcessMetrics,
     GetProcess,
+    DispatchOngoingSyncs,
 }; 

package/integrations/use-cases/integration-operations-for-user.js

@@ -0,0 +1,256 @@
+const Boom = require('@hapi/boom');
+const { describeRecord } = require('../../modules/scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
+const { isIntegrationNotFound } = require('../repositories/integration-not-found');
+
+/**
+ * Management API v2 integration operations. They put an access check
+ * (missing or unavailable integration = 404) in front of the existing
+ * integration use cases, and pass the record's owner id on. Access follows
+ * the owner and the organization the integration was created in (ADR-056
+ * §3.6), not the owner alone.
+ */
+
+const notFound = (integrationId) =>
+    Boom.notFound(`Integration ${integrationId} not found`, {
+        code: 'INTEGRATION_NOT_FOUND',
+    });
+
+/**
+ * The integration record, or 404 when it is missing or the caller may not
+ * use it: not theirs or their active organization's, or created in another
+ * organization.
+ */
+class GetOwnedIntegrationRecord {
+    constructor({ integrationRepository, scopePolicy }) {
+        this.integrationRepository = integrationRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    }
+
+    /** `{ scope, owner, organizationId, access }` of a record to this caller, or null. */
+    describe(record, user) {
+        return describeRecord(record, this.scopePolicy.accessContext(user), 'integration');
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {Object} user - authenticated User
+     * @param {{manage?: boolean}} [options] - `manage: true` for changing or
+     *   deleting: a person may use an organization's integration but only an
+     *   admin may change it (403 ORG_ADMIN_REQUIRED)
+     */
+    async execute(integrationId, user, { manage = false } = {}) {
+        let record = null;
+        try {
+            record = await this.integrationRepository.findIntegrationById(
+                integrationId
+            );
+        } catch (error) {
+            if (
+                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '') ||
+                isIntegrationNotFound(error)
+            ) {
+                throw notFound(integrationId);
+            }
+            throw error;
+        }
+        const tenancy = record && this.describe(record, user);
+        if (!tenancy) throw notFound(integrationId);
+        if (manage) assertCanManage(tenancy.access, `integration ${integrationId}`);
+        return record;
+    }
+}
+
+/**
+ * Creates (or reuses) an integration between entities the caller may use.
+ * The entities' access, the binding scopes and the integration type are
+ * checked before anything is written, and the integration is owned and
+ * paired with an organization by `resolveIntegrationOwnership` (§3, §3.6).
+ */
+class CreateIntegrationForUser {
+    constructor({ createIntegration, resolveIntegrationOwnership, integrationClasses }) {
+        this.createIntegration = createIntegration;
+        this.resolveIntegrationOwnership = resolveIntegrationOwnership;
+        this.integrationClasses = integrationClasses || [];
+    }
+
+    async execute({ entities, config }, user) {
+        if (!config || typeof config !== 'object' || typeof config.type !== 'string') {
+            throw Boom.badRequest('config.type is required', {
+                code: 'VALIDATION_ERROR',
+                details: { field: 'config.type' },
+            });
+        }
+        const known = this.integrationClasses.some(
+            (IntegrationClass) => IntegrationClass.Definition?.name === config.type
+        );
+        if (!known) {
+            throw Boom.badRequest(`Unknown integration type '${config.type}'`, {
+                code: 'UNKNOWN_INTEGRATION_TYPE',
+            });
+        }
+        if (
+            !Array.isArray(entities) ||
+            entities.some((id) => typeof id !== 'string' && typeof id !== 'number')
+        ) {
+            throw Boom.badRequest('entities must be an array of entity ids', {
+                code: 'VALIDATION_ERROR',
+                details: { field: 'entities' },
+            });
+        }
+        const { ownerId, organizationId, adoptUnscoped } =
+            await this.resolveIntegrationOwnership.execute({
+                entityIds: entities,
+                config,
+                user,
+            });
+        return this.createIntegration.execute(
+            entities.map(String),
+            ownerId,
+            config,
+            { organizationId, adoptUnscoped }
+        );
+    }
+}
+
+/** The hydrated integration instance (modules loaded) for an owned integration. */
+class GetIntegrationInstanceForUser {
+    constructor({ getOwnedIntegrationRecord, getIntegrationInstance }) {
+        this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
+        this.getIntegrationInstance = getIntegrationInstance;
+    }
+
+    async execute(integrationId, user) {
+        const record = await this.getOwnedIntegrationRecord.execute(
+            integrationId,
+            user
+        );
+        return this.getIntegrationInstance.execute(record.id, record.userId);
+    }
+}
+
+/** Replaces an owned integration's config. */
+class UpdateIntegrationForUser {
+    constructor({ getOwnedIntegrationRecord, updateIntegration }) {
+        this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
+        this.updateIntegration = updateIntegration;
+    }
+
+    async execute(integrationId, user, config) {
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            throw Boom.badRequest('config must be an object', {
+                code: 'VALIDATION_ERROR',
+                details: { field: 'config' },
+            });
+        }
+        const record = await this.getOwnedIntegrationRecord.execute(
+            integrationId,
+            user,
+            { manage: true }
+        );
+        return this.updateIntegration.execute(record.id, record.userId, config);
+    }
+}
+
+/** Deletes an owned integration (runs its onDelete hooks). */
+class RemoveIntegrationForUser {
+    constructor({ getOwnedIntegrationRecord, deleteIntegrationForUser }) {
+        this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
+        this.deleteIntegrationForUser = deleteIntegrationForUser;
+    }
+
+    async execute(integrationId, user) {
+        const record = await this.getOwnedIntegrationRecord.execute(
+            integrationId,
+            user,
+            { manage: true }
+        );
+        await this.deleteIntegrationForUser.execute(record.id, record.userId);
+    }
+}
+
+/**
+ * Sends one of the framework's user-facing events (GET_CONFIG_OPTIONS,
+ * GET_USER_ACTIONS, ...) to an owned integration. Handlers pass fixed event
+ * names only; caller-chosen action ids go through RunIntegrationActionForUser.
+ */
+class SendIntegrationEventForUser {
+    constructor({ getIntegrationInstanceForUser }) {
+        this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
+    }
+
+    async execute(integrationId, user, event, payload) {
+        const instance = await this.getIntegrationInstanceForUser.execute(
+            integrationId,
+            user
+        );
+        return instance.send(event, payload);
+    }
+}
+
+/**
+ * Runs a user action on an owned integration. Unlike v1, the action id must
+ * be one the integration lists as a user action (static USER_ACTION events
+ * or its dynamic user actions), so a caller cannot fire internal events such
+ * as lifecycle hooks.
+ */
+class RunIntegrationActionForUser {
+    constructor({ getIntegrationInstanceForUser }) {
+        this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
+    }
+
+    async execute(integrationId, user, actionId, payload) {
+        const instance = await this.getIntegrationInstanceForUser.execute(
+            integrationId,
+            user
+        );
+        const actions =
+            typeof instance.loadUserActions === 'function'
+                ? await instance.loadUserActions()
+                : {};
+        if (!actions || !Object.prototype.hasOwnProperty.call(actions, actionId)) {
+            throw Boom.notFound(
+                `Integration ${integrationId} has no user action '${actionId}'`,
+                { code: 'ACTION_NOT_FOUND' }
+            );
+        }
+        return instance.send(actionId, payload);
+    }
+}
+
+/**
+ * Runs the integration's auth test and reconciles its status. Returns the
+ * errors recorded during the test.
+ */
+class TestIntegrationAuthForUser {
+    constructor({ getIntegrationInstanceForUser }) {
+        this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
+    }
+
+    /** @returns {Promise<{ ok: boolean, errors: Array<Object> }>} */
+    async execute(integrationId, user) {
+        const instance = await this.getIntegrationInstanceForUser.execute(
+            integrationId,
+            user
+        );
+        const start = Date.now();
+        const authPassed = await instance.testAuth();
+        await instance.reconcileAuthStatus(authPassed);
+        const errors = (instance.record?.messages?.errors || []).filter(
+            ({ timestamp }) => timestamp >= start
+        );
+        return { ok: Boolean(authPassed) && errors.length === 0, errors };
+    }
+}
+
+module.exports = {
+    GetOwnedIntegrationRecord,
+    CreateIntegrationForUser,
+    GetIntegrationInstanceForUser,
+    UpdateIntegrationForUser,
+    RemoveIntegrationForUser,
+    SendIntegrationEventForUser,
+    RunIntegrationActionForUser,
+    TestIntegrationAuthForUser,
+};