@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

package/handlers/routers/integration-webhook-routers.js

@@ -6,82 +6,120 @@ const {
     IntegrationEventDispatcher,
 } = require('../integration-event-dispatcher');
 
-const handlers = {};
-const { integrations: integrationClasses } = loadAppDefinition();
-
 // `webhooks.received` is counted at the DB-connected ON_WEBHOOK dispatch (see
 // usage-rollup-subscriber), not in this DB-free receipt handler.
 
-for (const IntegrationClass of integrationClasses) {
-    const webhookConfig = IntegrationClass.Definition.webhooks;
+/**
+ * Builds the webhook receiver router for every integration with webhooks
+ * enabled. Pure: no handler wrapping, so the AWS handlers below and other
+ * hosts (provider-netlify's webhooks function) mount the same routers.
+ *
+ * @param {Array<Function>} integrationClasses
+ * @returns {Array<{ key: string, eventName: string, router: import('express').Router }>}
+ */
+function buildWebhookRouters(integrationClasses) {
+    const entries = [];
+    for (const IntegrationClass of integrationClasses) {
+        const webhookConfig = IntegrationClass.Definition.webhooks;
 
-    // Skip if webhooks not enabled
-    if (
-        !webhookConfig ||
-        (typeof webhookConfig === 'object' && !webhookConfig.enabled)
-    ) {
-        continue;
-    }
+        // Skip if webhooks not enabled
+        if (
+            !webhookConfig ||
+            (typeof webhookConfig === 'object' && !webhookConfig.enabled)
+        ) {
+            continue;
+        }
 
-    const router = Router();
-    const basePath = `/api/${IntegrationClass.Definition.name}-integration/webhooks`;
+        const router = Router();
+        const basePath = `/api/${IntegrationClass.Definition.name}-integration/webhooks`;
 
-    console.log(
-        `\n│ Configuring webhook routes for ${IntegrationClass.Definition.name}:`
-    );
+        console.log(
+            `\n│ Configuring webhook routes for ${IntegrationClass.Definition.name}:`
+        );
 
-    // General webhook route (no integration ID)
-    router.post(basePath, async (req, res, next) => {
-        try {
-            const integrationInstance = new IntegrationClass();
-            const dispatcher = new IntegrationEventDispatcher(
-                integrationInstance
-            );
-            await dispatcher.dispatchHttp({
-                event: 'WEBHOOK_RECEIVED',
-                req,
-                res,
-                next,
-            });
-        } catch (error) {
-            next(error);
-        }
-    });
-    console.log(`│ POST ${basePath}`);
+        // General webhook route (no integration ID)
+        router.post(basePath, async (req, res, next) => {
+            try {
+                const integrationInstance = new IntegrationClass();
+                const dispatcher = new IntegrationEventDispatcher(
+                    integrationInstance
+                );
+                await dispatcher.dispatchHttp({
+                    event: 'WEBHOOK_RECEIVED',
+                    req,
+                    res,
+                    next,
+                });
+            } catch (error) {
+                next(error);
+            }
+        });
+        console.log(`│ POST ${basePath}`);
 
-    // Integration-specific webhook route (with integration ID)
-    router.post(`${basePath}/:integrationId`, async (req, res, next) => {
-        try {
-            const integrationInstance = new IntegrationClass();
-            const dispatcher = new IntegrationEventDispatcher(
-                integrationInstance
-            );
-            // Logs only: the id comes from an unauthenticated URL, so it must
-            // not reach the telemetry context that drives usage attribution.
-            await runInContext(
-                { [LOGGER_SCOPE_KEY]: { integrationId: req.params.integrationId } },
-                () =>
-                    dispatcher.dispatchHttp({
-                        event: 'WEBHOOK_RECEIVED',
-                        req,
-                        res,
-                        next,
-                    })
-            );
-        } catch (error) {
-            next(error);
-        }
-    });
-    console.log(`│ POST ${basePath}/:integrationId`);
-    console.log('│');
+        // Integration-specific webhook route (with integration ID)
+        router.post(`${basePath}/:integrationId`, async (req, res, next) => {
+            try {
+                const integrationInstance = new IntegrationClass();
+                const dispatcher = new IntegrationEventDispatcher(
+                    integrationInstance
+                );
+                // Logs only: the id comes from an unauthenticated URL, so it must
+                // not reach the telemetry context that drives usage attribution.
+                await runInContext(
+                    {
+                        [LOGGER_SCOPE_KEY]: {
+                            integrationId: req.params.integrationId,
+                        },
+                    },
+                    () =>
+                        dispatcher.dispatchHttp({
+                            event: 'WEBHOOK_RECEIVED',
+                            req,
+                            res,
+                            next,
+                        })
+                );
+            } catch (error) {
+                next(error);
+            }
+        });
+        console.log(`│ POST ${basePath}/:integrationId`);
+        console.log('│');
 
-    handlers[`${IntegrationClass.Definition.name}Webhook`] = {
-        handler: createAppHandler(
-            `HTTP Event: ${IntegrationClass.Definition.name} Webhook`,
+        entries.push({
+            key: `${IntegrationClass.Definition.name}Webhook`,
+            eventName: `HTTP Event: ${IntegrationClass.Definition.name} Webhook`,
             router,
+        });
+    }
+    return entries;
+}
+
+/**
+ * One router serving every integration's webhook routes, for hosts that run
+ * them all in one function (provider-netlify).
+ *
+ * @param {Array<Function>} [integrationClasses] - defaults to the app's.
+ * @returns {import('express').Router}
+ */
+function createWebhookRouter(integrationClasses) {
+    const classes = integrationClasses || loadAppDefinition().integrations;
+    const combined = Router();
+    for (const entry of buildWebhookRouters(classes)) {
+        combined.use(entry.router);
+    }
+    return combined;
+}
+
+const handlers = {};
+for (const entry of buildWebhookRouters(loadAppDefinition().integrations)) {
+    handlers[entry.key] = {
+        handler: createAppHandler(
+            entry.eventName,
+            entry.router,
             false // shouldUseDatabase = false
         ),
     };
 }
 
-module.exports = { handlers };
+module.exports = { handlers, buildWebhookRouters, createWebhookRouter };

package/handlers/workers/integration-defined-workers.js

@@ -10,10 +10,13 @@ const { createQueueWorker } = require('../backend-utils');
 // const { getExtensionWorkers } = require('../../integrations/extension');
 
 const handlers = {};
-const { integrations: integrationClasses } = loadAppDefinition();
+const { integrations: integrationClasses, moduleDefinitions } =
+    loadAppDefinition();
 
 integrationClasses.forEach((IntegrationClass) => {
-    const defaultQueueWorker = createQueueWorker(IntegrationClass);
+    const defaultQueueWorker = createQueueWorker(IntegrationClass, {
+        moduleDefinitions,
+    });
 
     handlers[`${IntegrationClass.Definition.name}`] = {
         queueWorker: createHandler({

package/index.js

@@ -25,6 +25,14 @@ const {
     UserRepositoryMongo,
     UserRepositoryPostgres,
 } = require('./user/repositories/user-repository-factory');
+const {
+    createOrganizationMembershipRepository,
+    OrganizationMembershipRepositoryMongo,
+    OrganizationMembershipRepositoryPostgres,
+} = require('./user/repositories/organization-membership-repository-factory');
+const {
+    EnsureOrganizationMembership,
+} = require('./user/use-cases/ensure-organization-membership');
 const {
     GetUserFromXFriggHeaders,
 } = require('./user/use-cases/get-user-from-x-frigg-headers');
@@ -99,11 +107,36 @@ const {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
 } = require('./modules/index');
+const {
+    ManagementApiConfigError,
+} = require('./management-api/management-api-config');
 const application = require('./application');
 const utils = require('./utils');
 
-const { QueuerUtil } = require('./queues');
+const {
+    QueuerUtil,
+    QueueProvider,
+    QueueClientInterface,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
+} = require('./queues');
+const {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+    isDeployedRuntime,
+} = require('./providers');
+
+// App-level core extensions (appDefinition.coreExtensions): Prisma models, encrypted
+// fields, admin routes and bootstrap hooks (friggframework/frigg#545).
+const extensions = require('./extensions');
 
 module.exports = {
     // assertions
@@ -130,6 +163,10 @@ module.exports = {
     createUserRepository,
     UserRepositoryMongo,
     UserRepositoryPostgres,
+    createOrganizationMembershipRepository,
+    OrganizationMembershipRepositoryMongo,
+    OrganizationMembershipRepositoryPostgres,
+    EnsureOrganizationMembership,
     GetUserFromXFriggHeaders,
     GetUserFromAdopterJwt,
     AuthenticateUser,
@@ -150,6 +187,7 @@ module.exports = {
     Options,
     checkRequiredParams,
     createIntegrationRouter,
+    // Deprecated (ADR-059): use getEntityTypeRegistry.
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     CreateProcess,
@@ -206,8 +244,34 @@ module.exports = {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
+    ManagementApiConfigError,
     // queues
     QueuerUtil,
+    QueueProvider,
+    QueueClientInterface,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
+
+    // provider plugins (appDefinition.provider)
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+    isDeployedRuntime,
+
+    // app-level extensions
+    extensions,
+    loadExtensions: extensions.loadExtensions,
+    composeSchemas: extensions.composeSchemas,
+    mountExtensionRoutes: extensions.mountExtensionRoutes,
+    createExtensionRoutesRouter: extensions.createExtensionRoutesRouter,
+    runExtensionBootstraps: extensions.runExtensionBootstraps,
+    initializeApp: extensions.initializeApp,
 
     // utils
     ...utils,

package/infrastructure/scheduler/index.js

@@ -5,13 +5,19 @@
  * Follows hexagonal architecture with interface + adapters pattern.
  *
  * Providers:
- * - eventbridge: AWS EventBridge Scheduler (production)
+ * - eventbridge: AWS EventBridge Scheduler (production on AWS)
+ * - netlify: poll-and-dispatch from a Netlify scheduled function
  * - mock: In-memory mock scheduler (local development)
+ *
+ * Adapters are lazy getters (friggframework/frigg#545, 1176a004): the
+ * EventBridge adapter requires @aws-sdk/client-scheduler, which is not a
+ * core dependency, and core/index -> application -> scheduler-commands ->
+ * this barrel runs on every require('@friggframework/core'). An eager
+ * require crashed any deployment without that SDK (e.g. a pruned Netlify
+ * function bundle).
  */
 
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
-const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
-const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
 const {
     createSchedulerService,
     SCHEDULER_PROVIDERS,
@@ -22,9 +28,16 @@ module.exports = {
     // Interface (Port)
     SchedulerServiceInterface,
 
-    // Adapters
-    EventBridgeSchedulerAdapter,
-    MockSchedulerAdapter,
+    // Adapters (loaded on access)
+    get EventBridgeSchedulerAdapter() {
+        return require('./eventbridge-scheduler-adapter').EventBridgeSchedulerAdapter;
+    },
+    get MockSchedulerAdapter() {
+        return require('./mock-scheduler-adapter').MockSchedulerAdapter;
+    },
+    get NetlifySchedulerAdapter() {
+        return require('./netlify-scheduler-adapter').NetlifySchedulerAdapter;
+    },
 
     // Factory
     createSchedulerService,

package/infrastructure/scheduler/netlify-scheduler-adapter.js

@@ -0,0 +1,216 @@
+/**
+ * Netlify Scheduler Adapter
+ *
+ * Implements SchedulerServiceInterface for Netlify deployments.
+ *
+ * Netlify Scheduled Functions use cron syntax but are defined statically in
+ * netlify.toml or via the @netlify/functions schedule() helper. They cannot
+ * be created dynamically at runtime like EventBridge Scheduler.
+ *
+ * Strategy for one-time scheduled jobs on Netlify:
+ *   1. Store the schedule in the database (same as mock adapter pattern)
+ *   2. A Netlify Scheduled Function runs on a cron interval (e.g., every 5 min)
+ *   3. The cron function queries for due schedules and dispatches them
+ *      to a background function for execution
+ *
+ * This is a "poll-and-dispatch" pattern vs EventBridge's "push" pattern.
+ * Trade-off: slightly less precise timing (up to cron interval delay),
+ * but works on any platform without cloud-specific scheduling APIs.
+ *
+ * For integrations that need the queue provider to dispatch jobs:
+ *   - queueResourceId maps to the background function URL path
+ *   - Payload is stored and forwarded when the cron fires
+ */
+
+const { SchedulerServiceInterface } = require('./scheduler-service-interface');
+
+// The one queue worker every Netlify deployment has (provider-netlify's
+// worker-background function); it dispatches by integrationName.
+const DEFAULT_WORKER_PATH = '/.netlify/functions/worker-background';
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
+class NetlifySchedulerAdapter extends SchedulerServiceInterface {
+    /**
+     * @param {Object} options
+     * @param {Object} options.repository - Repository for persisting schedules
+     *   Must implement: save(schedule), delete(scheduleName),
+     *   findByName(scheduleName), findDue(now)
+     * @param {Object} [options.queueProvider] - Queue provider for dispatching due jobs
+     * @param {number} [options.leaseMs] - how long a claimed (PROCESSING) job
+     *   is held before another tick may take it again (default 5 minutes,
+     *   well past a Netlify scheduled function's 60-second limit)
+     */
+    constructor(options = {}) {
+        super();
+        this.repository = options.repository;
+        this.queueProvider = options.queueProvider;
+        this.leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] No repository provided. ' +
+                    'Schedules will be stored in memory (lost on function restart). ' +
+                    'Provide a database-backed repository for production use.'
+            );
+            this._inMemorySchedules = new Map();
+        }
+    }
+
+    /**
+     * Where a due job is sent. Netlify has no per-integration queues, so an
+     * SQS-style queue URL (often unset here) maps to the worker function;
+     * a function path is kept as given.
+     *
+     * @param {string} [queueUrl]
+     * @returns {string} a path NetlifyBackgroundProvider.send() accepts
+     */
+    toQueueResourceId(queueUrl) {
+        return typeof queueUrl === 'string' && queueUrl.startsWith('/')
+            ? queueUrl
+            : DEFAULT_WORKER_PATH;
+    }
+
+    async scheduleOneTime({
+        scheduleName,
+        scheduleAt,
+        queueResourceId,
+        payload,
+    }) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+        if (!scheduleAt || !(scheduleAt instanceof Date))
+            throw new Error('scheduleAt must be a valid Date object');
+        if (!queueResourceId) throw new Error('queueResourceId is required');
+
+        const scheduleData = {
+            scheduleName,
+            scheduledAt: scheduleAt.toISOString(),
+            queueResourceId,
+            payload,
+            createdAt: new Date().toISOString(),
+            state: 'PENDING',
+        };
+
+        if (this.repository) {
+            await this.repository.save(scheduleData);
+        } else {
+            this._inMemorySchedules.set(scheduleName, scheduleData);
+        }
+
+        console.log(
+            `[NetlifyScheduler] Scheduled: ${scheduleName} for ${scheduleAt.toISOString()}`
+        );
+
+        return {
+            scheduledJobId: `netlify-schedule-${scheduleName}`,
+            scheduledAt: scheduleAt.toISOString(),
+        };
+    }
+
+    async deleteSchedule(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        if (this.repository) {
+            await this.repository.delete(scheduleName);
+        } else {
+            this._inMemorySchedules.delete(scheduleName);
+        }
+
+        console.log(`[NetlifyScheduler] Deleted schedule: ${scheduleName}`);
+    }
+
+    async getScheduleStatus(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        let schedule;
+        if (this.repository) {
+            schedule = await this.repository.findByName(scheduleName);
+        } else {
+            schedule = this._inMemorySchedules.get(scheduleName);
+        }
+
+        if (!schedule) {
+            return { exists: false };
+        }
+
+        return {
+            exists: true,
+            scheduledAt: schedule.scheduledAt,
+            state: schedule.state,
+        };
+    }
+
+    /**
+     * Process due schedules. Called by the Netlify cron function.
+     *
+     * Finds all schedules where scheduledAt <= now, dispatches them
+     * to the queue provider, and marks them as completed.
+     *
+     * @returns {Promise<{ processed: number, errors: number }>}
+     */
+    async processDueSchedules() {
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] Cannot process due schedules without a repository'
+            );
+            return { processed: 0, errors: 0, skipped: 0 };
+        }
+
+        const now = new Date();
+        const lease = { leaseMs: this.leaseMs };
+        const dueSchedules = await this.repository.findDue(now, lease);
+
+        let processed = 0;
+        let errors = 0;
+        let skipped = 0;
+
+        for (const schedule of dueSchedules) {
+            try {
+                // Claim before dispatch. Two overlapping ticks can both see
+                // the row in findDue; only the one whose conditional update
+                // wins sends it. A repository without claim() (a custom one)
+                // keeps the old unconditional PROCESSING write.
+                const claimed =
+                    typeof this.repository.claim === 'function'
+                        ? await this.repository.claim(schedule.scheduleName, now, lease)
+                        : (await this.repository.save({ ...schedule, state: 'PROCESSING' }), true);
+                if (!claimed) {
+                    skipped++;
+                    continue;
+                }
+
+                if (this.queueProvider) {
+                    await this.queueProvider.send(
+                        schedule.payload,
+                        schedule.queueResourceId
+                    );
+                } else {
+                    console.log(
+                        `[NetlifyScheduler] No queue provider — logging payload for: ${schedule.scheduleName}`,
+                        JSON.stringify(schedule.payload)
+                    );
+                }
+
+                await this.repository.delete(schedule.scheduleName);
+                processed++;
+            } catch (error) {
+                console.error(
+                    `[NetlifyScheduler] Error processing schedule ${schedule.scheduleName}:`,
+                    error
+                );
+                // Mark as FAILED so it won't be re-dispatched automatically.
+                // Operators can inspect FAILED schedules and retry manually.
+                await this.repository
+                    .save({ ...schedule, state: 'FAILED' })
+                    .catch(() => {});
+                errors++;
+            }
+        }
+
+        console.log(
+            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors, ${skipped} claimed elsewhere`
+        );
+        return { processed, errors, skipped };
+    }
+}
+
+module.exports = { NetlifySchedulerAdapter, DEFAULT_WORKER_PATH, DEFAULT_LEASE_MS };

package/infrastructure/scheduler/scheduled-job-repository.js

@@ -0,0 +1,118 @@
+/**
+ * Scheduled Job Repository
+ *
+ * Prisma-based implementation of the repository interface required by
+ * NetlifySchedulerAdapter. Persists one-time scheduled jobs to the
+ * ScheduledJob model so they survive function restarts.
+ *
+ * Repository interface:
+ *   save(scheduleData)        — Upsert a scheduled job
+ *   delete(scheduleName)      — Remove a scheduled job
+ *   findByName(scheduleName)  — Find a single scheduled job
+ *   findDue(now, { leaseMs }) — Find due jobs: PENDING, or PROCESSING with an
+ *                               expired lease (a dispatcher that died after
+ *                               claiming), where scheduledAt <= now
+ *   claim(scheduleName, now, { leaseMs })
+ *                             — Atomically move one due job to PROCESSING;
+ *                               true only for the one caller that won it
+ *
+ * The lease clock is the row's updatedAt: a claim writes it, so a PROCESSING
+ * row whose updatedAt is older than now - leaseMs is claimable again.
+ */
+
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
+// Rows a dispatcher may take: never claimed, or claimed by one that has not
+// finished within the lease.
+function claimableWhere(now, leaseMs = DEFAULT_LEASE_MS) {
+    return {
+        OR: [
+            { state: 'PENDING' },
+            {
+                state: 'PROCESSING',
+                updatedAt: { lt: new Date(now.getTime() - leaseMs) },
+            },
+        ],
+    };
+}
+
+class ScheduledJobRepository {
+    /**
+     * @param {Object} options
+     * @param {import('@prisma/client').PrismaClient} options.prismaClient
+     */
+    constructor({ prismaClient }) {
+        if (!prismaClient) {
+            throw new Error(
+                'ScheduledJobRepository requires a prismaClient instance'
+            );
+        }
+        this.prisma = prismaClient;
+    }
+
+    async save(scheduleData) {
+        return this.prisma.scheduledJob.upsert({
+            where: { scheduleName: scheduleData.scheduleName },
+            update: {
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+            create: {
+                scheduleName: scheduleData.scheduleName,
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+        });
+    }
+
+    async delete(scheduleName) {
+        try {
+            await this.prisma.scheduledJob.delete({
+                where: { scheduleName },
+            });
+        } catch (error) {
+            // P2025 = record not found — safe to ignore on delete
+            if (error.code !== 'P2025') {
+                throw error;
+            }
+        }
+    }
+
+    async findByName(scheduleName) {
+        return this.prisma.scheduledJob.findUnique({
+            where: { scheduleName },
+        });
+    }
+
+    async findDue(now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        return this.prisma.scheduledJob.findMany({
+            where: {
+                scheduledAt: { lte: now },
+                ...claimableWhere(now, leaseMs),
+            },
+            orderBy: { scheduledAt: 'asc' },
+        });
+    }
+
+    /**
+     * Conditional update: only a row that is still claimable moves to
+     * PROCESSING, so of two overlapping ticks exactly one gets count === 1.
+     * (PostgreSQL re-checks the WHERE on the row it locked; MongoDB updates
+     * each document atomically.)
+     *
+     * @returns {Promise<boolean>} true when this caller claimed the job
+     */
+    async claim(scheduleName, now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        const { count } = await this.prisma.scheduledJob.updateMany({
+            where: { scheduleName, ...claimableWhere(now, leaseMs) },
+            data: { state: 'PROCESSING', updatedAt: now },
+        });
+        return count === 1;
+    }
+}
+
+module.exports = { ScheduledJobRepository, DEFAULT_LEASE_MS };