@friggframework/core 2.0.0-next.45 → 2.0.0-next.47

package/README.md

@@ -62,6 +62,34 @@ npm install @friggframework/core
 yarn add @friggframework/core
 ```
 
+### Prisma Support (Optional)
+
+`@friggframework/core` supports both MongoDB and PostgreSQL via Prisma ORM. **Prisma is an optional peer dependency** - you only need to install it if you're using database features that require migrations or schema generation.
+
+**When you need Prisma:**
+- Running database migrations (`prisma migrate`, `prisma db push`)
+- Generating Prisma clients for your application
+- Using the migration Lambda function (`dbMigrate`)
+
+**Installation:**
+```bash
+# Install Prisma CLI and Client as dev dependencies
+npm install --save-dev prisma @prisma/client
+
+# Or with yarn
+yarn add -D prisma @prisma/client
+```
+
+**Generate Prisma Clients:**
+```bash
+# From @friggframework/core directory
+npm run prisma:generate:mongo      # MongoDB only
+npm run prisma:generate:postgres   # PostgreSQL only
+npm run prisma:generate            # Both databases
+```
+
+**Note:** The published npm package includes pre-generated Prisma clients, so you don't need to install Prisma just to use `@friggframework/core` in production. Prisma is only required if you're actively developing migrations or running the migration Lambda function.
+
 ### Prerequisites
 
 - Node.js 16+ 

package/application/commands/integration-commands.js

@@ -142,6 +142,25 @@ function createIntegrationCommands({ integrationClass } = {}) {
                 return mapErrorToResponse(error);
             }
         },
+
+        /**
+         * Update integration configuration
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Object} params.config - Updated config object
+         * @returns {Promise<Object>} Updated integration
+         */
+        async updateIntegrationConfig({ integrationId, config }) {
+            try {
+                const integration = await integrationRepository.updateIntegrationConfig(
+                    integrationId,
+                    config
+                );
+                return integration;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
     };
 }
 

package/core/Worker.js

@@ -1,10 +1,9 @@
-const AWS = require('aws-sdk');
+const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
 
-AWS.config.update({ region: process.env.AWS_REGION });
-const sqs = new AWS.SQS({ apiVersion: '2012-11-05' });
+const sqs = new SQSClient({ region: process.env.AWS_REGION });
 
 class Worker {
     async getQueueURL(params) {
@@ -12,15 +11,9 @@ class Worker {
         // let params = {
         //     QueueName:  process.env.QueueName
         // };
-        return new Promise((resolve, reject) => {
-            sqs.getQueueUrl(params, (err, data) => {
-                if (err) {
-                    reject(err);
-                } else {
-                    resolve(data.QueueUrl);
-                }
-            });
-        });
+        const command = new GetQueueUrlCommand(params);
+        const data = await sqs.send(command);
+        return data.QueueUrl;
     }
 
     async run(params, context = {}) {
@@ -54,15 +47,9 @@ class Worker {
     }
 
     async sendAsyncSQSMessage(params) {
-        return new Promise((resolve, reject) => {
-            sqs.sendMessage(params, (err, data) => {
-                if (err) {
-                    reject(err);
-                } else {
-                    resolve(data.MessageId);
-                }
-            });
-        });
+        const command = new SendMessageCommand(params);
+        const data = await sqs.send(command);
+        return data.MessageId;
     }
 
     // Throw an exception if the params do not validate

package/credential/repositories/credential-repository-mongo.js

@@ -44,7 +44,6 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
             userId: credential.userId,
             externalId: credential.externalId,
             authIsValid: credential.authIsValid,
-            subType: credential.subType,
             ...data, // Spread OAuth tokens from JSON field
         };
     }
@@ -100,6 +99,17 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
         if (!identifiers)
             throw new Error('identifiers required to upsert credential');
 
+        if (!identifiers.user && !identifiers.userId) {
+            throw new Error('user or userId required in identifiers');
+        }
+        if (!identifiers.externalId) {
+            throw new Error(
+                'externalId required in identifiers to prevent credential collision. ' +
+                'When multiple credentials exist for the same user, both userId and externalId ' +
+                'are needed to uniquely identify which credential to update.'
+            );
+        }
+
         // Build where clause from identifiers
         const where = this._convertIdentifiersToWhere(identifiers);
 
@@ -109,7 +119,7 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
             userId,
             externalId,
             authIsValid,
-            subType,
+            
             ...oauthData
         } = details;
 
@@ -132,7 +142,6 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
                         authIsValid !== undefined
                             ? authIsValid
                             : existing.authIsValid,
-                    subType: subType !== undefined ? subType : existing.subType,
                     data: mergedData,
                 },
             });
@@ -152,7 +161,7 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
                 userId: userId || user,
                 externalId,
                 authIsValid: authIsValid,
-                subType,
+                
                 data: oauthData,
             },
         });
@@ -225,7 +234,7 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
             userId,
             externalId,
             authIsValid,
-            subType,
+            
             ...oauthData
         } = updates;
 
@@ -240,7 +249,6 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
                     externalId !== undefined ? externalId : existing.externalId,
                 authIsValid:
                     authIsValid !== undefined ? authIsValid : existing.authIsValid,
-                subType: subType !== undefined ? subType : existing.subType,
                 data: mergedData,
             },
         });
@@ -273,7 +281,6 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
         if (identifiers.user) where.userId = identifiers.user;
         if (identifiers.userId) where.userId = identifiers.userId;
         if (identifiers.externalId) where.externalId = identifiers.externalId;
-        if (identifiers.subType) where.subType = identifiers.subType;
 
         return where;
     }
@@ -292,7 +299,6 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
         if (filter.user) where.userId = filter.user;
         if (filter.userId) where.userId = filter.userId;
         if (filter.externalId) where.externalId = filter.externalId;
-        if (filter.subType) where.subType = filter.subType;
 
         return where;
     }

package/credential/repositories/credential-repository-postgres.js

@@ -61,7 +61,6 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
             userId: credential.userId?.toString(),
             externalId: credential.externalId,
             authIsValid: credential.authIsValid,
-            subType: credential.subType,
             ...data, // Spread OAuth tokens from JSON field
         };
     }
@@ -119,12 +118,23 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         if (!identifiers)
             throw new Error('identifiers required to upsert credential');
 
+        if (!identifiers.user && !identifiers.userId) {
+            throw new Error('user or userId required in identifiers');
+        }
+        if (!identifiers.externalId) {
+            throw new Error(
+                'externalId required in identifiers to prevent credential collision. ' +
+                'When multiple credentials exist for the same user, both userId and externalId ' +
+                'are needed to uniquely identify which credential to update.'
+            );
+        }
+
         const where = this._convertIdentifiersToWhere(identifiers);
 
         const { user, externalId } = identifiers;
 
         // Separate schema fields from dynamic OAuth data
-        const { authIsValid, subType, ...oauthData } = details;
+        const { authIsValid, ...oauthData } = details;
 
         const existing = await this.prisma.credential.findFirst({ where });
 
@@ -143,7 +153,6 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
                         authIsValid !== undefined
                             ? authIsValid
                             : existing.authIsValid,
-                    subType: subType !== undefined ? subType : existing.subType,
                     data: mergedData,
                 },
             });
@@ -162,7 +171,7 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
                 userId: this._convertId(user),
                 externalId,
                 authIsValid: authIsValid,
-                subType,
+                
                 data: oauthData,
             },
         });
@@ -231,7 +240,7 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         }
 
         // Separate schema fields from OAuth data
-        const { user, authIsValid, subType, ...oauthData } =
+        const { user, authIsValid, ...oauthData } =
             updates;
 
         // Merge OAuth data with existing
@@ -245,7 +254,6 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
                     externalId !== undefined ? externalId : existing.externalId,
                 authIsValid:
                     authIsValid !== undefined ? authIsValid : existing.authIsValid,
-                subType: subType !== undefined ? subType : existing.subType,
                 data: mergedData,
             },
         });
@@ -278,7 +286,6 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         if (identifiers.userId)
             where.userId = this._convertId(identifiers.userId);
         if (identifiers.externalId) where.externalId = identifiers.externalId;
-        if (identifiers.subType) where.subType = identifiers.subType;
 
         return where;
     }
@@ -298,7 +305,6 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         if (filter.user) where.userId = this._convertId(filter.user);
         if (filter.userId) where.userId = this._convertId(filter.userId);
         if (filter.externalId) where.externalId = filter.externalId;
-        if (filter.subType) where.subType = filter.subType;
 
         return where;
     }

package/credential/repositories/credential-repository.js

@@ -50,7 +50,6 @@ class CredentialRepository extends CredentialRepositoryInterface {
             userId: credential.userId,
             externalId: credential.externalId,
             authIsValid: credential.authIsValid,
-            subType: credential.subType,
             ...data, // Spread OAuth tokens from JSON field
         };
     }
@@ -115,7 +114,7 @@ class CredentialRepository extends CredentialRepositoryInterface {
             userId,
             externalId,
             authIsValid,
-            subType,
+            
             ...oauthData
         } = details;
 
@@ -138,7 +137,6 @@ class CredentialRepository extends CredentialRepositoryInterface {
                         authIsValid !== undefined
                             ? authIsValid
                             : existing.authIsValid,
-                    subType: subType !== undefined ? subType : existing.subType,
                     data: mergedData,
                 },
             });
@@ -158,7 +156,7 @@ class CredentialRepository extends CredentialRepositoryInterface {
                 userId: userId || user,
                 externalId,
                 authIsValid: authIsValid,
-                subType,
+                
                 data: oauthData,
             },
         });
@@ -231,7 +229,7 @@ class CredentialRepository extends CredentialRepositoryInterface {
             userId,
             externalId,
             authIsValid,
-            subType,
+            
             ...oauthData
         } = updates;
 
@@ -246,7 +244,6 @@ class CredentialRepository extends CredentialRepositoryInterface {
                     externalId !== undefined ? externalId : existing.externalId,
                 authIsValid:
                     authIsValid !== undefined ? authIsValid : existing.authIsValid,
-                subType: subType !== undefined ? subType : existing.subType,
                 data: mergedData,
             },
         });
@@ -279,7 +276,6 @@ class CredentialRepository extends CredentialRepositoryInterface {
         if (identifiers.user) where.userId = identifiers.user;
         if (identifiers.userId) where.userId = identifiers.userId;
         if (identifiers.externalId) where.externalId = identifiers.externalId;
-        if (identifiers.subType) where.subType = identifiers.subType;
 
         return where;
     }
@@ -298,7 +294,6 @@ class CredentialRepository extends CredentialRepositoryInterface {
         if (filter.user) where.userId = filter.user;
         if (filter.userId) where.userId = filter.userId;
         if (filter.externalId) where.externalId = filter.externalId;
-        if (filter.subType) where.subType = filter.subType;
 
         return where;
     }

package/database/MONGODB_TRANSACTION_FIX.md

@@ -0,0 +1,198 @@
+# MongoDB Transaction Namespace Fix
+
+## Problem
+
+The encryption health check was failing with the following error:
+
+```
+Cannot create namespace frigg.Credential in multi-document transaction.
+Error code: 263
+```
+
+### Root Cause
+
+MongoDB does not allow creating collections (namespaces) inside multi-document transactions. When Prisma tries to create a document in a collection that doesn't exist yet, MongoDB needs to implicitly create the collection. If this happens inside a transaction context, MongoDB throws error code 263.
+
+### Technical Details
+
+- **MongoDB Constraint**: Collections must exist before being used in multi-document transactions
+- **Prisma Behavior**: Prisma may implicitly use transactions for certain operations
+- **Impact**: Health checks fail on fresh databases or when collections haven't been created yet
+
+## Solution
+
+**Implemented a comprehensive schema initialization system that ensures all collections exist at application startup.**
+
+### Architectural Approach
+
+Rather than checking before each individual database operation, we take a **systematic, fail-fast approach**:
+
+1. **Parse Prisma Schema**: Extract all collection names from the Prisma schema definition
+2. **Initialize at Startup**: Create all collections when the database connection is established
+3. **Fail Fast**: If there are database issues, the application fails immediately at startup rather than during runtime operations
+4. **Idempotent**: Safe to run multiple times - only creates collections that don't exist
+
+This follows the **"fail fast"** principle and ensures consistent state across all application instances.
+
+### Changes Made
+
+1. **Created MongoDB Schema Initialization** (`packages/core/database/utils/mongodb-schema-init.js`)
+   - `initializeMongoDBSchema()` - Ensures all Prisma collections exist at startup
+   - `getPrismaCollections()` - Returns list of all Prisma collection names
+   - `PRISMA_COLLECTIONS` - Constant array of all 13 Prisma collections
+   - Only runs for MongoDB (skips PostgreSQL)
+   - Fails fast if database not connected
+
+2. **Created MongoDB Collection Utilities** (`packages/core/database/utils/mongodb-collection-utils.js`)
+   - `ensureCollectionExists(collectionName)` - Ensures a single collection exists
+   - `ensureCollectionsExist(collectionNames)` - Batch creates multiple collections
+   - `collectionExists(collectionName)` - Checks if a collection exists
+   - Handles race conditions gracefully (NamespaceExists errors)
+
+3. **Integrated into Database Connection** (`packages/core/database/prisma.js`)
+   - Modified `connectPrisma()` to call `initializeMongoDBSchema()` after connection
+   - Ensures all collections exist before application handles requests
+
+4. **Updated Health Check Repository** (`packages/core/database/repositories/health-check-repository-mongodb.js`)
+   - Removed per-operation collection existence checks
+   - Added documentation noting schema is initialized at startup
+
+5. **Added Comprehensive Tests**
+   - `mongodb-schema-init.test.js` - Tests schema initialization system
+   - `mongodb-collection-utils.test.js` - Tests collection utility functions
+   - Tests error handling, race conditions, and edge cases
+
+### Implementation Flow
+
+```javascript
+// 1. Application startup - connect to database
+await connectPrisma();
+  └─> await initializeMongoDBSchema();
+       └─> await ensureCollectionsExist([
+            'User', 'Token', 'Credential', 'Entity',
+            'Integration', 'IntegrationMapping', 'Process',
+            'Sync', 'DataIdentifier', 'Association',
+            'AssociationObject', 'State', 'WebsocketConnection'
+           ]);
+
+// 2. Now all collections exist - safe to handle requests
+// No per-operation checks needed!
+await prisma.credential.create({ data: {...} }); // Works without namespace error
+```
+
+## Best Practices Followed
+
+1. **Domain-Driven Design**: Created reusable utility module for MongoDB-specific concerns
+2. **Hexagonal Architecture**: Infrastructure concerns (schema initialization) handled in infrastructure layer
+3. **Test-Driven Development**: Added comprehensive tests for all utility functions
+4. **Fail Fast Principle**: Database issues discovered at startup, not during runtime
+5. **Idempotency**: Safe to run multiple times across multiple instances
+6. **Error Handling**: Graceful degradation on race conditions and errors
+7. **Documentation**: Inline comments, JSDoc, and comprehensive documentation
+
+## Benefits
+
+### Immediate Benefits
+- ✅ Fixes encryption health check failures on fresh databases
+- ✅ Prevents transaction namespace errors across **all** Prisma operations
+- ✅ No per-operation overhead - collections created once at startup
+- ✅ Fail fast - database issues discovered immediately at startup
+- ✅ Idempotent - safe to run multiple times and across multiple instances
+
+### Architectural Benefits
+- ✅ **Clean separation of concerns**: Schema initialization is infrastructure concern, handled at startup
+- ✅ **Follows DDD/Hexagonal Architecture**: Infrastructure layer handles database setup, repositories focus on business operations
+- ✅ **Consistent across all environments**: Dev, test, staging, production all follow same pattern
+- ✅ **No repository-level checks needed**: All repositories benefit automatically
+- ✅ **Well-tested and documented**: Comprehensive test coverage and documentation
+
+### Operational Benefits
+- ✅ **Predictable startup**: Clear logging of schema initialization
+- ✅ **Zero runtime overhead**: Collections created once, not on every operation
+- ✅ **Production-ready**: Handles race conditions, errors, and edge cases gracefully
+
+## Design Decisions
+
+### Why Initialize at Startup?
+
+We considered two approaches:
+
+**❌ Per-Operation Checks (Initial approach)**
+```javascript
+async createCredential(data) {
+    await ensureCollectionExists('Credential'); // Check every time
+    return await prisma.credential.create({ data });
+}
+```
+- Pros: Guarantees collection exists before each operation
+- Cons: Runtime overhead, repeated checks, scattered logic
+
+**✅ Startup Initialization (Final approach)**
+```javascript
+// Once at startup
+await connectPrisma(); // Initializes all collections
+
+// All operations just work
+async createCredential(data) {
+    return await prisma.credential.create({ data }); // No checks needed
+}
+```
+- Pros: Zero runtime overhead, centralized logic, fail fast, consistent
+- Cons: Requires database connection at startup (already required)
+
+### Benefits of Startup Approach
+
+1. **Performance**: Collections created once vs. checking before every operation
+2. **Simplicity**: No conditional logic in repositories
+3. **Reliability**: Fail fast at startup if database has issues
+4. **Maintainability**: Single source of truth for schema initialization
+5. **DDD Alignment**: Infrastructure concerns handled in infrastructure layer
+
+## Logging Output
+
+When the application starts, you'll see clear logging:
+
+```
+Initializing MongoDB schema - ensuring all collections exist...
+Created MongoDB collection: Credential
+MongoDB schema initialization complete - 13 collections verified (45ms)
+```
+
+On subsequent startups (collections already exist):
+```
+Initializing MongoDB schema - ensuring all collections exist...
+MongoDB schema initialization complete - 13 collections verified (12ms)
+```
+
+## References
+
+- [Prisma Issue #8305](https://github.com/prisma/prisma/issues/8305) - MongoDB "Cannot create namespace" error
+- [Mongoose Issue #6699](https://github.com/Automattic/mongoose/issues/6699) - Similar issue in Mongoose
+- [MongoDB Transactions Documentation](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-operations) - Operations allowed in transactions
+- [Prisma MongoDB Guide](https://www.prisma.io/docs/guides/database/mongodb) - Using Prisma with MongoDB
+
+## Future Considerations
+
+### Automatic Schema Sync
+Consider enhancing the system to:
+- Parse Prisma schema file dynamically to extract collection names
+- Auto-detect schema changes and create new collections
+- Provide CLI command for manual schema initialization
+
+### Migration Support
+For production deployments with existing data:
+- Document migration procedures for new collections
+- Consider pre-migration scripts for blue-green deployments
+- Add health check for schema initialization status
+
+### Multi-Database Support
+The system already handles:
+- ✅ MongoDB - Full schema initialization
+- ✅ PostgreSQL - Skips initialization (uses Prisma migrations)
+- Consider adding explicit migration support for DocumentDB-specific features
+
+### Index Creation
+Future enhancement could also create indexes at startup:
+- Parse Prisma schema for `@@index` directives
+- Create indexes if they don't exist
+- Provide index health checks

package/database/adapters/lambda-invoker.js

@@ -0,0 +1,97 @@
+/**
+ * Lambda Invoker Adapter
+ * Infrastructure layer - handles AWS Lambda function invocations
+ * 
+ * Part of Hexagonal Architecture:
+ * - Infrastructure Layer adapter for AWS SDK
+ * - Used by Domain Layer use cases
+ * - Isolates AWS-specific logic from business logic
+ */
+
+const { LambdaClient, InvokeCommand } = require('@aws-sdk/client-lambda');
+
+/**
+ * Custom error for Lambda invocation failures
+ * Provides structured error information for debugging
+ */
+class LambdaInvocationError extends Error {
+    constructor(message, functionName, statusCode) {
+        super(message);
+        this.name = 'LambdaInvocationError';
+        this.functionName = functionName;
+        this.statusCode = statusCode;
+    }
+}
+
+/**
+ * Adapter for invoking AWS Lambda functions
+ * 
+ * Infrastructure layer - handles AWS SDK communication
+ * Converts AWS SDK responses to domain-friendly formats
+ */
+class LambdaInvoker {
+    /**
+     * @param {LambdaClient} lambdaClient - AWS Lambda client (injected for testability)
+     */
+    constructor(lambdaClient = new LambdaClient({})) {
+        this.client = lambdaClient;
+    }
+
+    /**
+     * Invoke Lambda function synchronously
+     * 
+     * @param {string} functionName - Lambda function name or ARN
+     * @param {Object} payload - Event payload to send to Lambda
+     * @returns {Promise<Object>} Parsed response body
+     * @throws {LambdaInvocationError} If Lambda returns error status
+     * @throws {Error} If AWS SDK call fails
+     */
+    async invoke(functionName, payload) {
+        try {
+            const command = new InvokeCommand({
+                FunctionName: functionName,
+                InvocationType: 'RequestResponse', // Synchronous
+                Payload: JSON.stringify(payload),
+            });
+
+            const response = await this.client.send(command);
+
+            // Parse response payload
+            let result;
+            try {
+                result = JSON.parse(Buffer.from(response.Payload).toString());
+            } catch (parseError) {
+                throw new LambdaInvocationError(
+                    `Failed to parse Lambda response: ${parseError.message}`,
+                    functionName,
+                    null
+                );
+            }
+
+            // Check status code
+            if (result.statusCode === 200) {
+                return result.body;
+            }
+
+            // Lambda returned error status
+            const errorMessage = result.body?.error || 'Lambda invocation failed';
+            throw new LambdaInvocationError(
+                `Lambda ${functionName} returned error: ${errorMessage}`,
+                functionName,
+                result.statusCode
+            );
+        } catch (error) {
+            // Re-throw LambdaInvocationError as-is
+            if (error instanceof LambdaInvocationError) {
+                throw error;
+            }
+
+            // Wrap AWS SDK errors
+            throw new Error(`Failed to invoke Lambda ${functionName}: ${error.message}`);
+        }
+    }
+}
+
+module.exports = { LambdaInvoker, LambdaInvocationError };
+
+

package/database/config.js

@@ -4,13 +4,22 @@
  */
 
 /**
- * Determines database type from app definition
- * Reads backend/index.js Definition.database configuration
+ * Determines database type from environment or app definition
+ * 
+ * Detection order:
+ * 1. DB_TYPE environment variable (set for migration handlers)
+ * 2. App definition (backend/index.js Definition.database configuration)
  *
  * @returns {'mongodb'|'postgresql'} Database type
  * @throws {Error} If database type cannot be determined or app definition missing
  */
 function getDatabaseType() {
+    // First, check DB_TYPE environment variable (migration handlers set this)
+    if (process.env.DB_TYPE) {
+        return process.env.DB_TYPE;
+    }
+
+    // Fallback: Load app definition
     try {
         const path = require('node:path');
         const fs = require('node:fs');