@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/infrastructure/scheduler/index.js

@@ -4,30 +4,34 @@
  * Provides scheduling capabilities for one-time jobs.
  * Follows hexagonal architecture with interface + adapters pattern.
  *
- * Providers:
- * - eventbridge: AWS EventBridge Scheduler (production)
- * - mock: In-memory mock scheduler (local development)
+ * Use createSchedulerService() to get the correct adapter for the
+ * active provider. The factory uses resolveProvider() internally.
+ *
+ * Adapters:
+ * - AWS EventBridge: via @friggframework/provider-aws (SchedulerAdapter)
+ * - Netlify: NetlifySchedulerAdapter (ships with core, no AWS deps)
+ * - Mock: MockSchedulerAdapter (local development)
  */
 
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
-const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
-const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
 const {
     createSchedulerService,
     SCHEDULER_PROVIDERS,
-    determineProvider,
 } = require('./scheduler-service-factory');
 
 module.exports = {
     // Interface (Port)
     SchedulerServiceInterface,
 
-    // Adapters
-    EventBridgeSchedulerAdapter,
-    MockSchedulerAdapter,
+    // Core adapters (no external SDK dependencies)
+    get MockSchedulerAdapter() {
+        return require('./mock-scheduler-adapter').MockSchedulerAdapter;
+    },
+    get NetlifySchedulerAdapter() {
+        return require('./netlify-scheduler-adapter').NetlifySchedulerAdapter;
+    },
 
-    // Factory
+    // Factory — resolves the correct adapter via provider plugin system
     createSchedulerService,
     SCHEDULER_PROVIDERS,
-    determineProvider,
 };

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

@@ -0,0 +1,185 @@
+/**
+ * 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');
+
+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
+     */
+    constructor(options = {}) {
+        super();
+        this.repository = options.repository;
+        this.queueProvider = options.queueProvider;
+
+        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();
+        }
+    }
+
+    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 };
+        }
+
+        const now = new Date();
+        const dueSchedules = await this.repository.findDue(now);
+
+        let processed = 0;
+        let errors = 0;
+
+        for (const schedule of dueSchedules) {
+            try {
+                // Mark as PROCESSING before dispatch so the next cron tick
+                // won't re-pick this schedule (findDue only returns PENDING).
+                await this.repository.save({
+                    ...schedule,
+                    state: 'PROCESSING',
+                });
+
+                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`
+        );
+        return { processed, errors };
+    }
+}
+
+module.exports = { NetlifySchedulerAdapter };

package/infrastructure/scheduler/scheduler-service-factory.js

@@ -4,70 +4,77 @@
  * Creates scheduler service instances based on configuration.
  * Returns implementations of SchedulerServiceInterface.
  *
+ * Uses the provider plugin system (resolveProvider) to load the correct
+ * scheduler adapter for the active platform (AWS, Netlify, etc.).
+ *
  * Environment Detection:
- * - SCHEDULER_PROVIDER=eventbridge -> Use AWS EventBridge Scheduler
  * - SCHEDULER_PROVIDER=mock -> Use in-memory mock scheduler
  * - Default in dev/test/local stages -> Mock scheduler
- * - Default in other stages -> EventBridge scheduler
+ * - Otherwise -> Resolved provider's SchedulerAdapter
  */
 
-const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
-const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+const { resolveProvider } = require('../../providers/resolve-provider');
 
 const SCHEDULER_PROVIDERS = {
-    EVENTBRIDGE: 'eventbridge',
     MOCK: 'mock',
 };
 
 const LOCAL_STAGES = ['dev', 'test', 'local'];
 
 /**
- * Determine the scheduler provider based on environment
+ * Determine if mock scheduler should be used
  *
- * @returns {string} Provider name
+ * @param {string} [explicit] - Explicit provider override
+ * @returns {boolean}
  */
-function determineProvider() {
-    const explicitProvider = process.env.SCHEDULER_PROVIDER;
-    if (explicitProvider) {
-        return explicitProvider;
+function shouldUseMock(explicit) {
+    if (explicit === SCHEDULER_PROVIDERS.MOCK) {
+        return true;
     }
-
-    const stage = process.env.STAGE || 'dev';
-    if (LOCAL_STAGES.includes(stage)) {
-        return SCHEDULER_PROVIDERS.MOCK;
+    if (!explicit) {
+        const stage = process.env.STAGE || 'dev';
+        return LOCAL_STAGES.includes(stage);
     }
-
-    return SCHEDULER_PROVIDERS.EVENTBRIDGE;
+    return false;
 }
 
 /**
  * Create a scheduler service instance
  *
  * @param {Object} options
- * @param {string} options.provider - Scheduler provider ('eventbridge' or 'mock')
+ * @param {string} options.provider - Scheduler provider ('mock', or omit for auto-detect)
  * @param {string} options.region - AWS region (for EventBridge)
  * @param {boolean} options.verbose - Verbose logging (for Mock)
+ * @param {Object} options.repository - Schedule repository (for Netlify - persists schedules)
+ * @param {Object} options.queueProvider - Queue provider (for Netlify - dispatches due jobs)
  * @returns {SchedulerServiceInterface} Implementation of scheduler interface
  */
 function createSchedulerService(options = {}) {
-    const provider = options.provider || determineProvider();
+    const explicit = options.provider || process.env.SCHEDULER_PROVIDER;
+
+    if (shouldUseMock(explicit)) {
+        const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+        return new MockSchedulerAdapter({ verbose: options.verbose });
+    }
+
+    // Use the resolved provider's scheduler adapter.
+    // Legacy SCHEDULER_PROVIDER values (eventbridge, netlify) are mapped
+    // to provider names for backward compatibility.
+    const LEGACY_MAP = { eventbridge: 'aws', netlify: 'netlify' };
+    const providerName = LEGACY_MAP[explicit] || explicit;
+    const providerOverride = providerName ? { provider: providerName } : {};
+    const provider = resolveProvider(null, providerOverride);
 
-    switch (provider) {
-        case SCHEDULER_PROVIDERS.EVENTBRIDGE:
-            return new EventBridgeSchedulerAdapter({
-                region: options.region,
-            });
-        case SCHEDULER_PROVIDERS.MOCK:
-            return new MockSchedulerAdapter({
-                verbose: options.verbose,
-            });
-        default:
-            throw new Error(`Unknown scheduler provider: ${provider}`);
+    const Adapter = provider.SchedulerAdapter;
+    if (!Adapter) {
+        throw new Error(
+            `Provider '${provider.name}' does not export a SchedulerAdapter`
+        );
     }
+    return new Adapter(options);
 }
 
 module.exports = {
     createSchedulerService,
     SCHEDULER_PROVIDERS,
-    determineProvider,
 };

package/integrations/WEBHOOK-QUICKSTART.md

@@ -14,7 +14,7 @@ class MyIntegration extends IntegrationBase {
         modules: {
             myapi: { definition: MyApiDefinition },
         },
-        webhooks: true,  // ← Add this line
+        webhooks: true, // ← Add this line
     };
 }
 ```
@@ -55,10 +55,11 @@ POST /api/my-integration-integration/webhooks/:integrationId
 ## That's It!
 
 The default behavior handles:
-- ✅ Receiving webhooks (instant 200 OK response)
-- ✅ Queuing to SQS
-- ✅ Loading your integration with DB and API modules
-- ✅ Calling your `onWebhook` handler
+
+-   ✅ Receiving webhooks (instant 200 OK response)
+-   ✅ Queuing to SQS
+-   ✅ Loading your integration with DB and API modules
+-   ✅ Calling your `onWebhook` handler
 
 ## Optional: Custom Signature Verification
 
@@ -85,20 +86,24 @@ async onWebhookReceived({ req, res }) {
 ## Two Webhook Routes
 
 ### With Integration ID (Recommended)
+
 ```
 POST /api/{name}-integration/webhooks/:integrationId
 ```
-- Full integration loaded in worker
-- Access to DB, config, and API modules
-- Use `this.myapi`, `this.config`, etc.
+
+-   Full integration loaded in worker
+-   Access to DB, config, and API modules
+-   Use `this.myapi`, `this.config`, etc.
 
 ### Without Integration ID
+
 ```
 POST /api/{name}-integration/webhooks
 ```
-- Unhydrated integration
-- Useful for system-wide events
-- Limited context
+
+-   Unhydrated integration
+-   Useful for system-wide events
+-   Limited context
 
 ## Need Help?
 
@@ -107,6 +112,7 @@ See full documentation: `packages/core/handlers/WEBHOOKS.md`
 ## Common Patterns
 
 ### Slack
+
 ```javascript
 async onWebhookReceived({ req, res }) {
     if (req.body.type === 'url_verification') {
@@ -117,6 +123,7 @@ async onWebhookReceived({ req, res }) {
 ```
 
 ### Stripe
+
 ```javascript
 async onWebhookReceived({ req, res }) {
     const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
@@ -131,6 +138,7 @@ async onWebhookReceived({ req, res }) {
 ```
 
 ### GitHub
+
 ```javascript
 async onWebhookReceived({ req, res }) {
     const crypto = require('crypto');
@@ -139,13 +147,12 @@ async onWebhookReceived({ req, res }) {
         .createHmac('sha256', process.env.GITHUB_WEBHOOK_SECRET)
         .update(JSON.stringify(req.body))
         .digest('hex');
-    
+
     if (`sha256=${hash}` !== signature) {
         return res.status(401).json({ error: 'Invalid signature' });
     }
-    
+
     await this.queueWebhook({ integrationId: req.params.integrationId, body: req.body });
     res.status(200).json({ received: true });
 }
 ```
-

package/integrations/index.js

@@ -10,6 +10,9 @@ const {
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
+const {
+    createProcessRepository,
+} = require('./repositories/process-repository-factory');
 
 module.exports = {
     IntegrationBase,
@@ -18,4 +21,5 @@ module.exports = {
     checkRequiredParams,
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
+    createProcessRepository,
 };

package/integrations/integration-base.js

@@ -204,11 +204,11 @@ class IntegrationBase {
     /**
      * Returns the modules as object with keys as module names.
      * Uses the keys from Definition.modules to attach modules correctly.
-     * 
+     *
      * Example:
      *   Definition.modules = { attio: {...}, quo: { definition: { getName: () => 'quo-attio' } } }
      *   Module with getName()='quo-attio' gets attached as this.quo (not this['quo-attio'])
-     * 
+     *
      * @private
      * @param {Array} integrationModules - Array of module instances
      * @returns {Object} The modules object
@@ -220,13 +220,16 @@ class IntegrationBase {
         // e.g., 'quo-attio' → 'quo', 'attio' → 'attio'
         const moduleNameToKey = {};
         if (this.constructor.Definition?.modules) {
-            for (const [key, moduleConfig] of Object.entries(this.constructor.Definition.modules)) {
+            for (const [key, moduleConfig] of Object.entries(
+                this.constructor.Definition.modules
+            )) {
                 const definition = moduleConfig.definition;
                 if (definition) {
                     // Use getName() if available, fallback to moduleName
-                    const definitionName = typeof definition.getName === 'function'
-                        ? definition.getName()
-                        : definition.moduleName;
+                    const definitionName =
+                        typeof definition.getName === 'function'
+                            ? definition.getName()
+                            : definition.moduleName;
                     if (definitionName) {
                         moduleNameToKey[definitionName] = key;
                     }