@friggframework/core 2.0.0-next.115 → 2.0.0-next.117

package/database/documentdb-utils.js

@@ -58,7 +58,10 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            throw new Error(`${errorMsg} - Duplicate key violation`);
+            throw Object.assign(
+                new Error(`${errorMsg} - Duplicate key violation`),
+                { code: 11000 }
+            );
         }
         throw new Error(errorMsg);
     }

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/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/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-mongo.js

@@ -419,7 +419,7 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
         for (const [key, value] of Object.entries(patch)) {
             $set[`config.${key}`] = value;
         }
-        $set.updatedAt = new Date();
+        $set.updatedAt = { $date: new Date().toISOString() };
 
         const result = await this.prisma.$runCommandRaw({
             findAndModify: 'Integration',

package/integrations/repositories/process-repository-mongo.js

@@ -120,7 +120,7 @@ class ProcessRepositoryMongo extends ProcessRepositoryInterface {
         if (normalized.newState !== null) {
             $set.state = normalized.newState;
         }
-        $set.updatedAt = new Date();
+        $set.updatedAt = { $date: new Date().toISOString() };
         update.$set = $set;
 
         if (Object.keys(normalized.pushSlice).length > 0) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.115",
+    "version": "2.0.0-next.117",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.115",
-        "@friggframework/prettier-config": "2.0.0-next.115",
-        "@friggframework/test": "2.0.0-next.115",
+        "@friggframework/eslint-config": "2.0.0-next.117",
+        "@friggframework/prettier-config": "2.0.0-next.117",
+        "@friggframework/test": "2.0.0-next.117",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "a90dfe5e48de5524e61f8919731b323afff5d852"
+    "gitHead": "27771927dd746cc517d0c09189ce63b6e859e8bc"
 }