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

package/queues/queue-provider-factory.js

@@ -0,0 +1,93 @@
+/**
+ * Queue Provider Factory
+ *
+ * Creates queue provider instances based on appDefinition or environment configuration.
+ * Uses the provider plugin system (resolveProvider) to load the correct
+ * queue adapter for the active platform (AWS, Netlify, etc.).
+ *
+ * Priority order for determining provider:
+ * 1. Explicit `provider` option passed to factory
+ * 2. `appDefinition.queue.provider` property
+ * 3. `QUEUE_PROVIDER` environment variable
+ * 4. Default: resolved provider's QueueProvider
+ *
+ * Special providers (not tied to a platform):
+ * - 'qstash' -> Upstash QStash (platform-agnostic)
+ */
+
+const { resolveProvider } = require('../providers/resolve-provider');
+
+const QUEUE_PROVIDERS = {
+    QSTASH: 'qstash',
+};
+
+// Map legacy QUEUE_PROVIDER values to Frigg provider names
+const LEGACY_PROVIDER_MAP = {
+    sqs: 'aws',
+    'netlify-background': 'netlify',
+};
+
+/**
+ * Determine the queue provider from config hierarchy
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Explicit provider override
+ * @param {Object} [options.appDefinition] - Frigg app definition object
+ * @returns {string|undefined} Provider name, or undefined for auto-detect
+ */
+function determineProvider(options = {}) {
+    if (options.provider) {
+        return options.provider;
+    }
+
+    if (options.appDefinition?.queue?.provider) {
+        return options.appDefinition.queue.provider;
+    }
+
+    if (process.env.QUEUE_PROVIDER) {
+        return process.env.QUEUE_PROVIDER;
+    }
+
+    return undefined; // Let resolveProvider() pick the default
+}
+
+/**
+ * Create a queue provider instance
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Queue provider name
+ * @param {Object} [options.appDefinition] - Frigg app definition (reads queue.provider)
+ * @param {Object} [options.providerOptions] - Options passed to the provider constructor
+ * @returns {QueueProvider} Implementation of queue provider interface
+ */
+function createQueueProvider(options = {}) {
+    const explicit = determineProvider(options);
+    const providerOptions = options.providerOptions || {};
+
+    // QStash is a third-party queue not tied to any platform provider
+    if (explicit === QUEUE_PROVIDERS.QSTASH) {
+        const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+        return new QStashQueueProvider(providerOptions);
+    }
+
+    // Use the resolved provider's queue adapter.
+    // Legacy QUEUE_PROVIDER values (sqs, netlify-background) are mapped
+    // to provider names for backward compatibility.
+    const providerName = LEGACY_PROVIDER_MAP[explicit] || explicit;
+    const providerOverride = providerName ? { provider: providerName } : {};
+    const provider = resolveProvider(null, providerOverride);
+
+    const QueueProviderClass = provider.QueueProvider;
+    if (!QueueProviderClass) {
+        throw new Error(
+            `Provider '${provider.name}' does not export a QueueProvider`
+        );
+    }
+    return new QueueProviderClass(providerOptions);
+}
+
+module.exports = {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+};

package/queues/queue-provider.js

@@ -0,0 +1,46 @@
+/**
+ * Queue Provider Interface (Port)
+ *
+ * Defines the contract for queue message sending.
+ * All queue adapters must extend this interface.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify Background Functions, QStash, etc.)
+ */
+class QueueProvider {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} message - Message payload (will be JSON-serialized)
+     * @param {string} queueId - Queue identifier (URL, name, or endpoint depending on provider)
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async send(message, queueId) {
+        throw new Error('Method send must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object[]} entries - Array of message payloads
+     * @param {string} queueId - Queue identifier
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async batchSend(entries, queueId) {
+        throw new Error('Method batchSend must be implemented by subclass');
+    }
+
+    /**
+     * Parse an incoming event into an array of message payloads.
+     * Each provider has its own event shape (SQS Records, HTTP body, etc.)
+     *
+     * @param {Object} event - Raw event from the runtime (Lambda event, HTTP request, etc.)
+     * @returns {Object[]} Array of parsed message payloads
+     */
+    parseEvent(event) {
+        throw new Error('Method parseEvent must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueProvider };

package/queues/queuer-util.js

@@ -1,30 +1,41 @@
 const { v4: uuid } = require('uuid');
-const { SQSClient, SendMessageCommand, SendMessageBatchCommand } = require('@aws-sdk/client-sqs');
 
-const awsConfigOptions = () => {
-    const config = {};
-    if (process.env.IS_OFFLINE) {
-        config.credentials = {
-            accessKeyId: 'test-aws-key',
-            secretAccessKey: 'test-aws-secret',
-        };
-        config.region = 'us-east-1';
-    }
-    if (process.env.AWS_ENDPOINT) {
-        config.endpoint = process.env.AWS_ENDPOINT;
-    }
-    return config;
-};
+/**
+ * QueuerUtil - Queue message utility.
+ *
+ * BREAKING CHANGE (v3): A queue client must be set via setQueueClient()
+ * before calling send() or batchSend().
+ * For AWS/SQS, pass `new SqsQueueClient()` from @friggframework/provider-aws.
+ * See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.
+ */
+let _queueClient = null;
 
-const sqs = new SQSClient(awsConfigOptions());
+function getQueueClient() {
+    if (!_queueClient) {
+        throw new Error(
+            'QueuerUtil requires a queue client. Call QueuerUtil.setQueueClient() first, e.g.:\n' +
+            '  const { SqsQueueClient } = require("@friggframework/provider-aws");\n' +
+            '  QueuerUtil.setQueueClient(new SqsQueueClient());\n' +
+            'See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.'
+        );
+    }
+    return _queueClient;
+}
 
 const QueuerUtil = {
+    /**
+     * Set the queue client. Must be called before send() or batchSend().
+     * @param {QueueClientInterface} client
+     */
+    setQueueClient(client) {
+        _queueClient = client;
+    },
+
     send: async (message, queueUrl) => {
-        const command = new SendMessageCommand({
+        return getQueueClient().sendMessage({
             MessageBody: JSON.stringify(message),
             QueueUrl: queueUrl,
         });
-        return sqs.send(command);
     },
 
     batchSend: async (entries = [], queueUrl) => {
@@ -38,23 +49,20 @@ const QueuerUtil = {
             });
             // Sends 10, then purges the buffer
             if (buffer.length === batchSize) {
-                const command = new SendMessageBatchCommand({
-                    Entries: buffer,
+                await getQueueClient().sendMessageBatch({
+                    Entries: [...buffer],
                     QueueUrl: queueUrl,
                 });
-                await sqs.send(command);
-                // Purge the buffer
-                buffer.splice(0, buffer.length);
+                buffer.length = 0;
             }
         }
 
         // If any remaining entries under 10 are left in the buffer, send and return
         if (buffer.length > 0) {
-            const command = new SendMessageBatchCommand({
+            return getQueueClient().sendMessageBatch({
                 Entries: buffer,
                 QueueUrl: queueUrl,
             });
-            return sqs.send(command);
         }
 
         // If we're exact... just return an empty object for now

package/syncs/repositories/sync-repository-documentdb.js

@@ -69,7 +69,9 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
                     $set: documentData,
                 }
             );
-            const updated = await findOne(this.prisma, 'Sync', { _id: existing._id });
+            const updated = await findOne(this.prisma, 'Sync', {
+                _id: existing._id,
+            });
             return this._mapSync(updated);
         }
 
@@ -103,7 +105,9 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
         const doc = await findOne(this.prisma, 'Sync', { _id: syncObjectId });
         if (!doc) return null;
 
-        const identifiers = Array.isArray(doc.dataIdentifiers) ? [...doc.dataIdentifiers] : [];
+        const identifiers = Array.isArray(doc.dataIdentifiers)
+            ? [...doc.dataIdentifiers]
+            : [];
         identifiers.push({
             syncId: syncObjectId,
             entityId: toObjectId(dataIdentifier.entity),
@@ -124,7 +128,9 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
             }
         );
 
-        const updated = await findOne(this.prisma, 'Sync', { _id: syncObjectId });
+        const updated = await findOne(this.prisma, 'Sync', {
+            _id: syncObjectId,
+        });
         return updated ? this._mapSync(updated) : null;
     }
 
@@ -134,7 +140,8 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
         }
 
         const entry = syncObj.dataIdentifiers.find(
-            (identifier) => fromObjectId(identifier.entityId) === String(entityId)
+            (identifier) =>
+                fromObjectId(identifier.entityId) === String(entityId)
         );
 
         if (entry) {
@@ -178,7 +185,9 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
             query.integrationId = toObjectId(filter.integrationId);
         }
         if (filter.entities) {
-            query.entityIds = (filter.entities || []).map((id) => toObjectId(id)).filter(Boolean);
+            query.entityIds = (filter.entities || [])
+                .map((id) => toObjectId(id))
+                .filter(Boolean);
             delete query.entities;
         }
         return query;
@@ -190,8 +199,11 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
             prepared.integrationId = toObjectId(data.integrationId);
         }
         if (data.entities !== undefined || data.entityIds !== undefined) {
-            const list = data.entities !== undefined ? data.entities : data.entityIds;
-            prepared.entityIds = (list || []).map((id) => toObjectId(id)).filter(Boolean);
+            const list =
+                data.entities !== undefined ? data.entities : data.entityIds;
+            prepared.entityIds = (list || [])
+                .map((id) => toObjectId(id))
+                .filter(Boolean);
         }
         if (data.hash !== undefined) prepared.hash = data.hash;
         if (data.name !== undefined) prepared.name = data.name;
@@ -199,13 +211,17 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
         if (data.results !== undefined) prepared.results = data.results;
         if (timestamp) prepared.updatedAt = timestamp;
         if (data.dataIdentifiers !== undefined) {
-            prepared.dataIdentifiers = (data.dataIdentifiers || []).map((identifier) => ({
-                syncId: toObjectId(identifier.syncId),
-                entityId: toObjectId(identifier.entityId),
-                idData: identifier.idData,
-                hash: identifier.hash,
-                createdAt: identifier.createdAt ? new Date(identifier.createdAt) : new Date(),
-            }));
+            prepared.dataIdentifiers = (data.dataIdentifiers || []).map(
+                (identifier) => ({
+                    syncId: toObjectId(identifier.syncId),
+                    entityId: toObjectId(identifier.entityId),
+                    idData: identifier.idData,
+                    hash: identifier.hash,
+                    createdAt: identifier.createdAt
+                        ? new Date(identifier.createdAt)
+                        : new Date(),
+                })
+            );
         }
         return prepared;
     }
@@ -214,7 +230,9 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
         if (!doc) return null;
         return {
             id: fromObjectId(doc._id),
-            integrationId: doc.integrationId ? fromObjectId(doc.integrationId) : null,
+            integrationId: doc.integrationId
+                ? fromObjectId(doc.integrationId)
+                : null,
             entities: Array.isArray(doc.entityIds)
                 ? doc.entityIds.map((id) => fromObjectId(id))
                 : [],
@@ -225,8 +243,12 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
             name: doc.name ?? null,
             dataIdentifiers: Array.isArray(doc.dataIdentifiers)
                 ? doc.dataIdentifiers.map((identifier) => ({
-                      syncId: identifier.syncId ? fromObjectId(identifier.syncId) : null,
-                      entityId: identifier.entityId ? fromObjectId(identifier.entityId) : null,
+                      syncId: identifier.syncId
+                          ? fromObjectId(identifier.syncId)
+                          : null,
+                      entityId: identifier.entityId
+                          ? fromObjectId(identifier.entityId)
+                          : null,
                       idData: identifier.idData,
                       hash: identifier.hash,
                   }))
@@ -236,5 +258,3 @@ class SyncRepositoryDocumentDB extends SyncRepositoryInterface {
 }
 
 module.exports = { SyncRepositoryDocumentDB };
-
-

package/syncs/repositories/sync-repository-factory.js

@@ -1,6 +1,4 @@
-const { SyncRepositoryMongo } = require('./sync-repository-mongo');
 const { SyncRepositoryPostgres } = require('./sync-repository-postgres');
-const { SyncRepositoryDocumentDB } = require('./sync-repository-documentdb');
 const config = require('../../database/config');
 
 /**
@@ -19,12 +17,14 @@ function createSyncRepository() {
 
     switch (dbType) {
         case 'mongodb':
+            const { SyncRepositoryMongo } = require('./sync-repository-mongo');
             return new SyncRepositoryMongo();
 
         case 'postgresql':
             return new SyncRepositoryPostgres();
 
         case 'documentdb':
+            const { SyncRepositoryDocumentDB } = require('./sync-repository-documentdb');
             return new SyncRepositoryDocumentDB();
 
         default:
@@ -37,7 +37,7 @@ function createSyncRepository() {
 module.exports = {
     createSyncRepository,
     // Export adapters for direct testing
-    SyncRepositoryMongo,
+    get SyncRepositoryMongo() { return require('./sync-repository-mongo').SyncRepositoryMongo; },
     SyncRepositoryPostgres,
-    SyncRepositoryDocumentDB,
+    get SyncRepositoryDocumentDB() { return require('./sync-repository-documentdb').SyncRepositoryDocumentDB; },
 };

package/syncs/repositories/sync-repository-interface.js

@@ -56,7 +56,9 @@ class SyncRepositoryInterface {
      * @abstract
      */
     async addDataIdentifier(syncId, dataIdentifier) {
-        throw new Error('Method addDataIdentifier must be implemented by subclass');
+        throw new Error(
+            'Method addDataIdentifier must be implemented by subclass'
+        );
     }
 
     /**
@@ -69,7 +71,9 @@ class SyncRepositoryInterface {
      * @abstract
      */
     getEntityObjIdForEntityIdFromObject(syncObj, entityId) {
-        throw new Error('Method getEntityObjIdForEntityIdFromObject must be implemented by subclass');
+        throw new Error(
+            'Method getEntityObjIdForEntityIdFromObject must be implemented by subclass'
+        );
     }
 
     /**

package/syncs/repositories/sync-repository-postgres.js

@@ -46,24 +46,26 @@ class SyncRepositoryPostgres extends SyncRepositoryInterface {
             ...sync,
             id: sync.id?.toString(),
             integrationId: sync.integrationId?.toString(),
-            entities: sync.entities?.map(e => ({
+            entities: sync.entities?.map((e) => ({
                 ...e,
                 id: e.id?.toString(),
                 userId: e.userId?.toString(),
-                credentialId: e.credentialId?.toString()
+                credentialId: e.credentialId?.toString(),
             })),
-            dataIdentifiers: sync.dataIdentifiers?.map(di => ({
+            dataIdentifiers: sync.dataIdentifiers?.map((di) => ({
                 ...di,
                 id: di.id?.toString(),
                 syncId: di.syncId?.toString(),
                 entityId: di.entityId?.toString(),
-                entity: di.entity ? {
-                    ...di.entity,
-                    id: di.entity.id?.toString(),
-                    userId: di.entity.userId?.toString(),
-                    credentialId: di.entity.credentialId?.toString()
-                } : di.entity
-            }))
+                entity: di.entity
+                    ? {
+                          ...di.entity,
+                          id: di.entity.id?.toString(),
+                          userId: di.entity.userId?.toString(),
+                          credentialId: di.entity.credentialId?.toString(),
+                      }
+                    : di.entity,
+            })),
         };
     }
 
@@ -123,7 +125,9 @@ class SyncRepositoryPostgres extends SyncRepositoryInterface {
         // Convert IDs in syncData if present
         const convertedData = { ...syncData };
         if (convertedData.integrationId) {
-            convertedData.integrationId = this._convertId(convertedData.integrationId);
+            convertedData.integrationId = this._convertId(
+                convertedData.integrationId
+            );
         }
 
         if (existing) {
@@ -155,7 +159,9 @@ class SyncRepositoryPostgres extends SyncRepositoryInterface {
         // Convert IDs in updates if present
         const convertedUpdates = { ...updates };
         if (convertedUpdates.integrationId) {
-            convertedUpdates.integrationId = this._convertId(convertedUpdates.integrationId);
+            convertedUpdates.integrationId = this._convertId(
+                convertedUpdates.integrationId
+            );
         }
 
         const updated = await this.prisma.sync.update({
@@ -241,7 +247,7 @@ class SyncRepositoryPostgres extends SyncRepositoryInterface {
                 },
             },
         });
-        return syncs.map(sync => this._convertSyncIds(sync));
+        return syncs.map((sync) => this._convertSyncIds(sync));
     }
 
     /**