@friggframework/core 2.0.0--canary.667.f74cf3b.0 → 2.0.0--canary.710.7cfcf12.0

package/database/encryption/field-encryption-service.js

@@ -1,3 +1,5 @@
+const { isEncryptedEnvelope } = require('./ciphertext-format');
+
 /**
  * Field Encryption Service
  *
@@ -147,12 +149,7 @@ class FieldEncryptionService {
     }
 
     _isEncrypted(value) {
-        if (typeof value !== 'string') {
-            return false;
-        }
-
-        const parts = value.split(':');
-        return parts.length >= 4;
+        return isEncryptedEnvelope(value);
     }
 
     _getNestedValue(obj, path) {
@@ -218,22 +215,22 @@ class FieldEncryptionService {
     }
 
     /**
-     * Serialize a value for encryption
-     * Objects/arrays are JSON stringified, primitives are converted to strings
+     * Serialize a value for encryption.
+     * Every value is JSON-encoded, strings included, so the type survives
+     * the round trip: '123456' is stored as "\"123456\"" and reads back as a
+     * string, 1234 reads back as a number.
      * @private
      */
     _serializeForEncryption(value) {
-        if (typeof value === 'object' && value !== null) {
-            // JSON.stringify for objects and arrays
-            return JSON.stringify(value);
-        }
-        // For primitives (string, number, boolean), convert to string
-        return String(value);
+        return JSON.stringify(value);
     }
 
     /**
-     * Deserialize a value after decryption
-     * Attempts to parse as JSON, returns string if parsing fails
+     * Deserialize a value after decryption.
+     * Parses the JSON written by _serializeForEncryption. Values encrypted by
+     * earlier versions stored strings raw: those that aren't valid JSON come
+     * back unchanged; a raw legacy string that is also valid JSON (e.g.
+     * '123456') still parses as it always did.
      * @private
      */
     _deserializeAfterDecryption(value) {

package/database/prisma.js

@@ -1,7 +1,10 @@
 const {
     createEncryptionExtension,
 } = require('./encryption/prisma-encryption-extension');
-const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
+const {
+    loadCustomEncryptionSchema,
+    EncryptionSchemaError,
+} = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
 const config = require('./config');
@@ -125,6 +128,12 @@ const prismaClientSingleton = () => {
                 `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
             );
         } catch (error) {
+            // An invalid encryption configuration must fail startup: carrying
+            // on without the extension would write encrypted fields in
+            // plaintext.
+            if (error instanceof EncryptionSchemaError) {
+                throw error;
+            }
             logger.error(
                 'Failed to initialize encryption extension:',
                 error

package/errors/index.js

@@ -6,6 +6,9 @@ const {
     ParameterTypeError,
 } = require('./validation-errors');
 const { ClientSafeError } = require('./client-safe-error');
+const {
+    MappingAlreadyExistsError,
+} = require('./mapping-already-exists-error');
 
 module.exports = {
     BaseError,
@@ -14,4 +17,5 @@ module.exports = {
     RequiredPropertyError,
     ParameterTypeError,
     ClientSafeError,
+    MappingAlreadyExistsError,
 };

package/errors/mapping-already-exists-error.js

@@ -0,0 +1,14 @@
+const { BaseError } = require('./base-error');
+
+class MappingAlreadyExistsError extends BaseError {
+    constructor(integrationId, sourceId, ...errorOptions) {
+        super(
+            `Mapping already exists for integration ${integrationId} and sourceId ${sourceId}`,
+            ...errorOptions
+        );
+        this.integrationId = integrationId;
+        this.sourceId = sourceId;
+    }
+}
+
+module.exports = { MappingAlreadyExistsError };

package/handlers/WEBHOOKS.md

@@ -483,6 +483,35 @@ async onWebhook({ data }) {
 }
 ```
 
+`getMapping` followed by `upsertMapping` is not atomic. To claim an event so only one
+concurrent worker proceeds, use the insert-only `createMapping`, which throws
+`MappingAlreadyExistsError` (exported from `@friggframework/core`) when the
+`sourceId` is already taken. `deleteMapping(sourceId)` releases the claim and is a
+no-op when nothing exists.
+
+```javascript
+const { MappingAlreadyExistsError } = require('@friggframework/core');
+
+async onWebhook({ data }) {
+    const claimId = `claim:${data.body.id}`;
+    try {
+        await this.createMapping(claimId, { claimedAt: new Date() });
+    } catch (error) {
+        if (error instanceof MappingAlreadyExistsError) {
+            return { processed: false, duplicate: true };
+        }
+        throw error;
+    }
+
+    try {
+        await this.processEvent(data.body);
+    } catch (error) {
+        await this.deleteMapping(claimId);
+        throw error;
+    }
+}
+```
+
 ### 4. Error Handling
 ```javascript
 async onWebhook({ data }) {

package/index.js

@@ -57,6 +57,7 @@ const {
     HaltError,
     RequiredPropertyError,
     ParameterTypeError,
+    MappingAlreadyExistsError,
 } = require('./errors/index');
 const {
     IntegrationBase,
@@ -144,6 +145,7 @@ module.exports = {
     HaltError,
     RequiredPropertyError,
     ParameterTypeError,
+    MappingAlreadyExistsError,
 
     // integrations
     IntegrationBase,

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

@@ -11,19 +11,65 @@
  * This adapter implements SchedulerServiceInterface for AWS EventBridge Scheduler.
  */
 
-const {
-    SchedulerClient,
-    CreateScheduleCommand,
-    DeleteScheduleCommand,
-    GetScheduleCommand,
-    ResourceNotFoundException,
-} = require('@aws-sdk/client-scheduler');
-
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
 
+const SCHEDULER_SDK = '@aws-sdk/client-scheduler';
+
+/**
+ * Lazily load the AWS EventBridge Scheduler SDK.
+ *
+ * Requiring `@aws-sdk/client-scheduler` at module top level would put the AWS
+ * SDK on the load path of every consumer of `@friggframework/core`, including
+ * those using the mock scheduler or no scheduler at all. Loading it here, on
+ * construction of the EventBridge adapter, keeps it out of the module-load
+ * path. The adapter calls it exactly once, in its constructor, and keeps the
+ * classes its methods need on the instance.
+ *
+ * Only a MODULE_NOT_FOUND for the scheduler SDK itself is rewritten into an
+ * actionable message; any other failure (including a missing transitive
+ * dependency) is rethrown unchanged so the real cause is not masked.
+ *
+ * @returns {object} The relevant exports from `@aws-sdk/client-scheduler`.
+ */
+function loadSchedulerSdk() {
+    try {
+        // Keep the literal specifier so bundlers (esbuild) can resolve it.
+        return require('@aws-sdk/client-scheduler');
+    } catch (error) {
+        const isSchedulerSdkMissing =
+            error &&
+            error.code === 'MODULE_NOT_FOUND' &&
+            typeof error.message === 'string' &&
+            error.message.includes(SCHEDULER_SDK);
+        if (isSchedulerSdkMissing) {
+            throw new Error(
+                `The EventBridge scheduler requires the "${SCHEDULER_SDK}" package, ` +
+                    `which is not installed. Install it (\`npm install ${SCHEDULER_SDK}\`) ` +
+                    'to use the EventBridge scheduler provider, or use the mock scheduler provider ' +
+                    '(SCHEDULER_PROVIDER=mock) for local development.',
+                { cause: error }
+            );
+        }
+        throw error;
+    }
+}
+
 class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
     constructor({ region } = {}) {
         super();
+        const {
+            SchedulerClient,
+            CreateScheduleCommand,
+            DeleteScheduleCommand,
+            GetScheduleCommand,
+            ResourceNotFoundException,
+        } = loadSchedulerSdk();
+        this.sdk = {
+            CreateScheduleCommand,
+            DeleteScheduleCommand,
+            GetScheduleCommand,
+            ResourceNotFoundException,
+        };
         this.client = new SchedulerClient({
             region: region || process.env.AWS_REGION || 'us-east-1',
         });
@@ -42,7 +88,12 @@ class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
      * @param {Object} params.payload - Message payload
      * @returns {Promise<{scheduledJobId: string, scheduledAt: string}>}
      */
-    async scheduleOneTime({ scheduleName, scheduleAt, queueResourceId, payload }) {
+    async scheduleOneTime({
+        scheduleName,
+        scheduleAt,
+        queueResourceId,
+        payload,
+    }) {
         if (!scheduleName) {
             throw new Error('scheduleName is required');
         }
@@ -59,8 +110,11 @@ class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
         }
 
         // Format date to AWS schedule expression (at(yyyy-mm-ddThh:mm:ss))
-        const scheduleExpression = `at(${scheduleAt.toISOString().replace(/\.\d{3}Z$/, '')})`;
+        const scheduleExpression = `at(${scheduleAt
+            .toISOString()
+            .replace(/\.\d{3}Z$/, '')})`;
 
+        const { CreateScheduleCommand } = this.sdk;
         const command = new CreateScheduleCommand({
             Name: scheduleName,
             GroupName: this.scheduleGroupName,
@@ -107,6 +161,7 @@ class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
             throw new Error('scheduleName is required');
         }
 
+        const { DeleteScheduleCommand, ResourceNotFoundException } = this.sdk;
         const command = new DeleteScheduleCommand({
             Name: scheduleName,
             GroupName: this.scheduleGroupName,
@@ -141,6 +196,7 @@ class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
             throw new Error('scheduleName is required');
         }
 
+        const { GetScheduleCommand, ResourceNotFoundException } = this.sdk;
         const command = new GetScheduleCommand({
             Name: scheduleName,
             GroupName: this.scheduleGroupName,
@@ -153,9 +209,7 @@ class EventBridgeSchedulerAdapter extends SchedulerServiceInterface {
             // Format: at(yyyy-mm-ddThh:mm:ss)
             let scheduledAt = null;
             if (response.ScheduleExpression) {
-                const match = response.ScheduleExpression.match(
-                    /^at\((.+)\)$/
-                );
+                const match = response.ScheduleExpression.match(/^at\((.+)\)$/);
                 if (match) {
                     scheduledAt = new Date(match[1] + 'Z').toISOString();
                 }

package/integrations/integration-base.js

@@ -457,6 +457,35 @@ class IntegrationBase {
         );
     }
 
+    /**
+     * Insert-only mapping write; usable as an atomic claim/lock row.
+     * @throws {MappingAlreadyExistsError} If a mapping for sourceId exists
+     */
+    async createMapping(sourceId, mapping) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.createMapping(
+            this.id,
+            sourceId,
+            mapping
+        );
+    }
+
+    /**
+     * Deletes the mapping for sourceId. A missing mapping is not an error
+     * (resolves with deletedCount 0).
+     */
+    async deleteMapping(sourceId) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.deleteMapping(
+            this.id,
+            sourceId
+        );
+    }
+
     /**
      * CHILDREN CAN OVERRIDE THESE CONFIGURATION METHODS
      */

package/integrations/integration-router.js

@@ -42,9 +42,6 @@ const {
 } = require('../modules/use-cases/get-entity-options-by-type');
 const { TestModuleAuth } = require('../modules/use-cases/test-module-auth');
 const { GetModule } = require('../modules/use-cases/get-module');
-const {
-    CreateEntityFromCredential,
-} = require('../modules/use-cases/create-entity-from-credential');
 const {
     GetEntityOptionsById,
 } = require('../modules/use-cases/get-entity-options-by-id');
@@ -201,13 +198,6 @@ function createIntegrationRouter() {
             getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
-    const createEntityFromCredential = new CreateEntityFromCredential({
-        processAuthorizationCallback,
-        credentialRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
-    });
-
     const router = express();
 
     setIntegrationRoutes(router, authenticateUser, {
@@ -228,7 +218,6 @@ function createIntegrationRouter() {
         getEntityOptionsById,
         refreshEntityOptions,
         processAuthorizationCallback,
-        createEntityFromCredential,
     });
     return router;
 }
@@ -513,7 +502,6 @@ function setEntityRoutes(router, authenticateUser, useCases) {
         getEntityOptionsById,
         refreshEntityOptions,
         processAuthorizationCallback,
-        createEntityFromCredential,
     } = useCases;
 
     router.route('/api/authorize').get(
@@ -578,19 +566,35 @@ function setEntityRoutes(router, authenticateUser, useCases) {
     router.route('/api/entity').post(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
                 'data',
             ]);
             checkRequiredParams(req.body.data, ['credential_id']);
 
-            res.json(
-                await createEntityFromCredential.execute({
-                    user,
-                    entityType: params.entityType,
-                    credentialId: params.data.credential_id,
-                })
+            // May want to pass along the user ID as well so credential ID's can't be fished???
+            const credential = await getCredentialForUser.execute(
+                params.data.credential_id,
+                userId
+            );
+
+            if (!credential) {
+                throw Boom.badRequest('Invalid credential ID');
+            }
+
+            const module = await getModuleInstanceFromType.execute(
+                userId,
+                params.entityType
             );
+            const entityDetails = await module.getEntityDetails(
+                module.api,
+                null,
+                null,
+                userId
+            );
+
+            res.json(await module.findOrCreateEntity(entityDetails));
         })
     );
 

package/integrations/repositories/integration-mapping-repository-documentdb.js

@@ -1,4 +1,5 @@
 const { prisma } = require('../../database/prisma');
+const { MappingAlreadyExistsError } = require('../../errors');
 const {
     toObjectId,
     fromObjectId,
@@ -180,6 +181,55 @@ class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositor
         return this._mapMapping(decryptedMapping);
     }
 
+    async createMapping(integrationId, sourceId, mapping) {
+        const now = new Date();
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'IntegrationMapping',
+            {
+                integrationId,
+                sourceId:
+                    sourceId === null || sourceId === undefined
+                        ? null
+                        : String(sourceId),
+                mapping,
+                createdAt: now,
+                updatedAt: now,
+            }
+        );
+
+        let insertedId;
+        try {
+            insertedId = await insertOne(
+                this.prisma,
+                'IntegrationMapping',
+                encryptedDocument
+            );
+        } catch (error) {
+            if (error.code === 11000) {
+                throw new MappingAlreadyExistsError(integrationId, sourceId, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+
+        const created = await findOne(this.prisma, 'IntegrationMapping', {
+            _id: insertedId,
+        });
+        if (!created) {
+            throw new Error(
+                'Failed to create mapping: Document not found after insert. ' +
+                    'This indicates a database consistency issue.'
+            );
+        }
+        return this._mapMapping(
+            await this.encryptionService.decryptFields(
+                'IntegrationMapping',
+                created
+            )
+        );
+    }
+
     async findMappingsByIntegration(integrationId) {
         const filter = {};
         if (integrationId) filter.integrationId = integrationId;

package/integrations/repositories/integration-mapping-repository-interface.js

@@ -39,6 +39,21 @@ class IntegrationMappingRepositoryInterface {
         throw new Error('Method upsertMapping must be implemented by subclass');
     }
 
+    /**
+     * Insert a mapping, failing if one already exists for the
+     * (integrationId, sourceId) pair. Atomic: usable as a claim/lock row.
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {string} sourceId - The source ID for lookup
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created mapping document
+     * @throws {MappingAlreadyExistsError} If the pair already exists
+     * @abstract
+     */
+    async createMapping(integrationId, sourceId, mapping) {
+        throw new Error('createMapping must be implemented by subclass');
+    }
+
     /**
      * Find all mappings for an integration
      *

package/integrations/repositories/integration-mapping-repository-mongo.js

@@ -1,4 +1,5 @@
 const { prisma } = require('../../database/prisma');
+const { MappingAlreadyExistsError } = require('../../errors');
 const {
     assertMappingWrittenUnencrypted,
     decryptQueriedMappings,
@@ -93,6 +94,34 @@ class IntegrationMappingRepositoryMongo extends IntegrationMappingRepositoryInte
         });
     }
 
+    /**
+     * Insert a mapping; fails if (integrationId, sourceId) already exists
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created mapping document
+     * @throws {MappingAlreadyExistsError} If the pair already exists
+     */
+    async createMapping(integrationId, sourceId, mapping) {
+        try {
+            return await this.prisma.integrationMapping.create({
+                data: {
+                    integrationId,
+                    sourceId: this._toString(sourceId),
+                    mapping,
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2002') {
+                throw new MappingAlreadyExistsError(integrationId, sourceId, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+
     /**
      * Find all mappings for an integration
      * Replaces: IntegrationMapping.find({ integration: integrationId })

package/integrations/repositories/integration-mapping-repository-postgres.js

@@ -1,4 +1,5 @@
 const { prisma } = require('../../database/prisma');
+const { MappingAlreadyExistsError } = require('../../errors');
 const {
     assertMappingWrittenUnencrypted,
     decryptQueriedMappings,
@@ -150,6 +151,35 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
         return this._convertMappingIds(result);
     }
 
+    /**
+     * Insert a mapping; fails if (integrationId, sourceId) already exists
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created mapping document
+     * @throws {MappingAlreadyExistsError} If the pair already exists
+     */
+    async createMapping(integrationId, sourceId, mapping) {
+        try {
+            const created = await this.prisma.integrationMapping.create({
+                data: {
+                    integrationId: this._stringToInt(integrationId),
+                    sourceId: this._toString(sourceId),
+                    mapping,
+                },
+            });
+            return this._convertMappingIds(created);
+        } catch (error) {
+            if (error.code === 'P2002') {
+                throw new MappingAlreadyExistsError(integrationId, sourceId, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+
     /**
      * Find all mappings for an integration
      * Replaces: IntegrationMapping.find({ integration: integrationId })

package/integrations/repositories/integration-mapping-repository.js

@@ -1,4 +1,5 @@
 const { prisma } = require('../../database/prisma');
+const { MappingAlreadyExistsError } = require('../../errors');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
@@ -69,6 +70,34 @@ class IntegrationMappingRepository extends IntegrationMappingRepositoryInterface
         });
     }
 
+    /**
+     * Insert a mapping; fails if (integrationId, sourceId) already exists
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created mapping document
+     * @throws {MappingAlreadyExistsError} If the pair already exists
+     */
+    async createMapping(integrationId, sourceId, mapping) {
+        try {
+            return await this.prisma.integrationMapping.create({
+                data: {
+                    integrationId,
+                    sourceId,
+                    mapping,
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2002') {
+                throw new MappingAlreadyExistsError(integrationId, sourceId, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+
     /**
      * Find all mappings for an integration
      * Replaces: IntegrationMapping.find({ integration: integrationId })

package/integrations/repositories/integration-repository-documentdb.js

@@ -164,6 +164,38 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
         return this._mapIntegration(created);
     }
 
+    async addEntitiesToIntegration(integrationId, entityIds) {
+        const objectId = toObjectId(integrationId);
+        if (!objectId) return null;
+        const result = await updateOne(
+            this.prisma,
+            'Integration',
+            { _id: objectId },
+            {
+                $addToSet: { entityIds: { $each: toObjectIdArray(entityIds) } },
+                $set: { updatedAt: { $date: new Date().toISOString() } },
+            }
+        );
+        if (!result?.n) return null;
+        return this.findIntegrationById(integrationId);
+    }
+
+    async removeEntitiesFromIntegration(integrationId, entityIds) {
+        const objectId = toObjectId(integrationId);
+        if (!objectId) return null;
+        const result = await updateOne(
+            this.prisma,
+            'Integration',
+            { _id: objectId },
+            {
+                $pullAll: { entityIds: toObjectIdArray(entityIds) },
+                $set: { updatedAt: { $date: new Date().toISOString() } },
+            }
+        );
+        if (!result?.n) return null;
+        return this.findIntegrationById(integrationId);
+    }
+
     async findIntegrationByUserId(userId) {
         const objectId = toObjectId(userId);
         if (!objectId) return null;