@friggframework/core 2.0.0--canary.545.ccb5010.0 → 2.0.0--canary.549.922386d.0

package/CLAUDE.md

@@ -4,12 +4,12 @@ This file provides guidance to Claude Code when working with the Frigg Framework
 
 ## Critical Context (Read First)
 
--   **Package Purpose**: Core framework functionality for building enterprise serverless integrations
--   **Main Architecture**: Hexagonal/DDD architecture with clear separation of adapters, use cases, and repositories
--   **Key Technologies**: Node.js, Express, AWS Lambda, MongoDB/PostgreSQL (Prisma), AWS KMS encryption
--   **Core Value**: Provides building blocks for integration developers - they extend IntegrationBase and use framework services
--   **Security Model**: Field-level encryption, OAuth2 flows, signature validation, VPC deployment
--   **DO NOT**: Bypass architectural layers, skip encryption for sensitive data, expose internal errors to users
+- **Package Purpose**: Core framework functionality for building enterprise serverless integrations
+- **Main Architecture**: Hexagonal/DDD architecture with clear separation of adapters, use cases, and repositories
+- **Key Technologies**: Node.js, Express, AWS Lambda, MongoDB/PostgreSQL (Prisma), AWS KMS encryption
+- **Core Value**: Provides building blocks for integration developers - they extend IntegrationBase and use framework services
+- **Security Model**: Field-level encryption, OAuth2 flows, signature validation, VPC deployment
+- **DO NOT**: Bypass architectural layers, skip encryption for sensitive data, expose internal errors to users
 
 ## Table of Contents
 
@@ -26,14 +26,14 @@ This file provides guidance to Claude Code when working with the Frigg Framework
 
 `@friggframework/core` is the foundational package of the Frigg Framework, providing:
 
--   **IntegrationBase**: Base class all integrations extend
--   **Database Layer**: Multi-database support (MongoDB, DocumentDB, PostgreSQL) with Prisma ORM
--   **Encryption**: Transparent field-level encryption with AWS KMS or AES
--   **User Management**: Individual and organizational user support
--   **Module System**: API module loading and credential management
--   **Lambda Runtime**: Handler factory, worker base class, timeout management
--   **Error Handling**: Standardized error types with proper HTTP status codes
--   **Event System**: Integration lifecycle events and user actions
+- **IntegrationBase**: Base class all integrations extend
+- **Database Layer**: Multi-database support (MongoDB, DocumentDB, PostgreSQL) with Prisma ORM
+- **Encryption**: Transparent field-level encryption with AWS KMS or AES
+- **User Management**: Individual and organizational user support
+- **Module System**: API module loading and credential management
+- **Lambda Runtime**: Handler factory, worker base class, timeout management
+- **Error Handling**: Standardized error types with proper HTTP status codes
+- **Event System**: Integration lifecycle events and user actions
 
 ## Architecture Principles
 
@@ -196,25 +196,22 @@ packages/core/
 **Purpose**: Foundation for building integrations between external systems.
 
 **Key Files**:
-
--   `integration-base.js` - Base class all integrations extend
--   `integration.js` - Integration domain aggregate using Proxy pattern
--   `options.js` - Integration configuration and options
+- `integration-base.js` - Base class all integrations extend
+- `integration.js` - Integration domain aggregate using Proxy pattern
+- `options.js` - Integration configuration and options
 
 **Use Cases**:
-
--   `create-integration.js` - Create new integration instance
--   `update-integration.js` - Update integration configuration
--   `delete-integration-for-user.js` - Remove integration
--   `get-integration-instance.js` - Load integration with modules
--   `load-integration-context.js` - Full integration context loading
+- `create-integration.js` - Create new integration instance
+- `update-integration.js` - Update integration configuration
+- `delete-integration-for-user.js` - Remove integration
+- `get-integration-instance.js` - Load integration with modules
+- `load-integration-context.js` - Full integration context loading
 
 **Repositories**:
-
--   `integration-repository-factory.js` - Creates database-specific repositories
--   `integration-repository-mongo.js` - MongoDB implementation
--   `integration-repository-postgres.js` - PostgreSQL implementation
--   `integration-mapping-repository-*.js` - Mapping data persistence
+- `integration-repository-factory.js` - Creates database-specific repositories
+- `integration-repository-mongo.js` - MongoDB implementation
+- `integration-repository-postgres.js` - PostgreSQL implementation
+- `integration-mapping-repository-*.js` - Mapping data persistence
 
 **Integration developers extend IntegrationBase**:
 
@@ -227,8 +224,8 @@ class MyIntegration extends IntegrationBase {
         version: '1.0.0',
         modules: {
             serviceA: 'service-a',
-            serviceB: 'service-b',
-        },
+            serviceB: 'service-b'
+        }
     };
 
     async onCreate({ integrationId }) {
@@ -243,60 +240,52 @@ class MyIntegration extends IntegrationBase {
 **Purpose**: Multi-database support with transparent encryption.
 
 **Key Components**:
-
--   `prisma.js` - Prisma client initialization with encryption extension
--   `mongo.js` - Mongoose connection management (legacy)
--   `models/` - Mongoose model definitions
+- `prisma.js` - Prisma client initialization with encryption extension
+- `mongo.js` - Mongoose connection management (legacy)
+- `models/` - Mongoose model definitions
 
 **Encryption System** (`/database/encryption`):
-
--   **Transparent encryption**: Application code never sees encrypted data
--   **Database-agnostic**: Works with MongoDB and PostgreSQL
--   **AWS KMS or AES**: Production KMS, development AES
--   **Configurable**: Via environment variables and app definition
+- **Transparent encryption**: Application code never sees encrypted data
+- **Database-agnostic**: Works with MongoDB and PostgreSQL
+- **AWS KMS or AES**: Production KMS, development AES
+- **Configurable**: Via environment variables and app definition
 
 **See**: `database/encryption/README.md` for comprehensive documentation
 
 **Repositories**:
-
--   `health-check-repository.js` - Database health monitoring
--   `token-repository.js` - Authentication tokens
--   `websocket-connection-repository.js` - WebSocket connections
--   DocumentDB-enabled adapters mirror the MongoDB APIs but execute raw commands (`$runCommandRaw`, `$aggregateRaw`) for compatibility; encrypted models (e.g., credentials) still delegate reads to Prisma so the encryption extension can decrypt secrets transparently.
+- `health-check-repository.js` - Database health monitoring
+- `token-repository.js` - Authentication tokens
+- `websocket-connection-repository.js` - WebSocket connections
+- DocumentDB-enabled adapters mirror the MongoDB APIs but execute raw commands (`$runCommandRaw`, `$aggregateRaw`) for compatibility; encrypted models (e.g., credentials) still delegate reads to Prisma so the encryption extension can decrypt secrets transparently.
 
 **Use Cases**:
-
--   `check-database-health-use-case.js` - Database health checks
--   `test-encryption-use-case.js` - Encryption verification
+- `check-database-health-use-case.js` - Database health checks
+- `test-encryption-use-case.js` - Encryption verification
 
 ### 3. User Management (`/user`)
 
 **Purpose**: Individual and organizational user authentication.
 
 **User Types**:
-
--   **Individual Users**: Personal accounts with email/password
--   **Organization Users**: Business accounts with organization-level access
--   **Hybrid**: Support both simultaneously
+- **Individual Users**: Personal accounts with email/password
+- **Organization Users**: Business accounts with organization-level access
+- **Hybrid**: Support both simultaneously
 
 **Authentication Methods**:
-
--   Password-based (bcrypt hashed)
--   Token-based (Bearer tokens)
--   App-based (external app user IDs)
+- Password-based (bcrypt hashed)
+- Token-based (Bearer tokens)
+- App-based (external app user IDs)
 
 **Use Cases**:
-
--   `login-user.js` - User authentication
--   `create-individual-user.js` - Create personal account
--   `create-organization-user.js` - Create business account
--   `get-user-from-bearer-token.js` - Token authentication
+- `login-user.js` - User authentication
+- `create-individual-user.js` - Create personal account
+- `create-organization-user.js` - Create business account
+- `get-user-from-bearer-token.js` - Token authentication
 
 **Repositories**:
-
--   `user-repository-factory.js` - Creates database-specific repositories
--   `user-repository-mongo.js` - MongoDB implementation
--   `user-repository-postgres.js` - PostgreSQL implementation
+- `user-repository-factory.js` - Creates database-specific repositories
+- `user-repository-mongo.js` - MongoDB implementation
+- `user-repository-postgres.js` - PostgreSQL implementation
 
 **Configuration** (in app definition):
 
@@ -316,24 +305,21 @@ class MyIntegration extends IntegrationBase {
 **Purpose**: API module loading, credential management, and HTTP clients.
 
 **Key Classes**:
-
--   `Credential` - API credentials domain entity
--   `Entity` - External service entity (account, workspace, etc.)
--   `Requester` - Base HTTP client class
--   `OAuth2Requester` - OAuth 2.0 flow implementation
--   `ApiKeyRequester` - API key authentication
--   `BasicAuthRequester` - Basic authentication
+- `Credential` - API credentials domain entity
+- `Entity` - External service entity (account, workspace, etc.)
+- `Requester` - Base HTTP client class
+- `OAuth2Requester` - OAuth 2.0 flow implementation
+- `ApiKeyRequester` - API key authentication
+- `BasicAuthRequester` - Basic authentication
 
 **Module Factory**:
-
--   `ModuleFactory` - Creates and configures API module instances
--   Handles credential injection
--   Manages module lifecycle
+- `ModuleFactory` - Creates and configures API module instances
+- Handles credential injection
+- Manages module lifecycle
 
 **Repositories**:
-
--   `module-repository.js` - Module data access
--   `credential-repository.js` - Credential persistence (encrypted)
+- `module-repository.js` - Module data access
+- `credential-repository.js` - Credential persistence (encrypted)
 
 ### 5. Core Runtime System (`/core`)
 
@@ -342,11 +328,10 @@ class MyIntegration extends IntegrationBase {
 **See**: `core/CLAUDE.md` for comprehensive documentation
 
 **Key Components**:
-
--   `create-handler.js` - Lambda handler factory
--   `Worker.js` - SQS job processing base class
--   `Delegate.js` - Observer/delegation pattern
--   `load-installed-modules.js` - Dynamic module loading
+- `create-handler.js` - Lambda handler factory
+- `Worker.js` - SQS job processing base class
+- `Delegate.js` - Observer/delegation pattern
+- `load-installed-modules.js` - Dynamic module loading
 
 **Handler Pattern**:
 
@@ -355,12 +340,12 @@ const { createHandler } = require('@friggframework/core');
 
 const handler = createHandler({
     eventName: 'MyIntegration',
-    isUserFacingResponse: true, // Sanitize errors
-    shouldUseDatabase: true, // Connect to DB
+    isUserFacingResponse: true,  // Sanitize errors
+    shouldUseDatabase: true,     // Connect to DB
     method: async (event, context) => {
         // Your logic here
         return { statusCode: 200, body: 'Success' };
-    },
+    }
 });
 ```
 
@@ -385,11 +370,10 @@ class MyWorker extends Worker {
 **Purpose**: Cryptor adapter for AWS KMS and AES encryption.
 
 **Key Class**: `Cryptor.js`
-
--   Envelope encryption pattern
--   AWS KMS integration
--   AES-256-GCM fallback
--   Key rotation support
+- Envelope encryption pattern
+- AWS KMS integration
+- AES-256-GCM fallback
+- Key rotation support
 
 **Usage**:
 
@@ -397,7 +381,7 @@ class MyWorker extends Worker {
 const { Cryptor } = require('@friggframework/core');
 
 const cryptor = new Cryptor({
-    shouldUseAws: process.env.KMS_KEY_ARN ? true : false,
+    shouldUseAws: process.env.KMS_KEY_ARN ? true : false
 });
 
 const encrypted = await cryptor.encrypt('sensitive-data');
@@ -409,33 +393,29 @@ const decrypted = await cryptor.decrypt(encrypted);
 **Purpose**: HTTP/Lambda request handling and routing.
 
 **Key Routers**:
-
--   `integration-router.js` - Integration CRUD operations
--   `auth.js` - Authentication endpoints
--   `health.js` - Health check endpoints with encryption verification
+- `integration-router.js` - Integration CRUD operations
+- `auth.js` - Authentication endpoints
+- `health.js` - Health check endpoints with encryption verification
 
 **Handler Types**:
-
--   **User-facing**: Sanitize errors, friendly responses
--   **Server-to-server**: Full error details for debugging
--   **Background workers**: SQS message processing
+- **User-facing**: Sanitize errors, friendly responses
+- **Server-to-server**: Full error details for debugging
+- **Background workers**: SQS message processing
 
 **Event Dispatcher**:
-
--   `integration-event-dispatcher.js` - Routes events to integration handlers
--   Supports lifecycle events and user actions
+- `integration-event-dispatcher.js` - Routes events to integration handlers
+- Supports lifecycle events and user actions
 
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.
 
 **Error Types**:
-
--   `BaseError` - Base error class
--   `FetchError` - HTTP request failures
--   `HaltError` - Stop processing without retry
--   `RequiredPropertyError` - Missing required parameters
--   `ParameterTypeError` - Invalid parameter type
+- `BaseError` - Base error class
+- `FetchError` - HTTP request failures
+- `HaltError` - Stop processing without retry
+- `RequiredPropertyError` - Missing required parameters
+- `ParameterTypeError` - Invalid parameter type
 
 **Usage**:
 
@@ -452,10 +432,9 @@ if (!userId) {
 **Purpose**: Structured logging with debug capabilities.
 
 **Functions**:
-
--   `debug(message, data)` - Debug logging
--   `initDebugLog(eventName, event)` - Initialize debug context
--   `flushDebugLog(error)` - Flush logs on error
+- `debug(message, data)` - Debug logging
+- `initDebugLog(eventName, event)` - Initialize debug context
+- `flushDebugLog(error)` - Flush logs on error
 
 **Usage**:
 
@@ -473,9 +452,8 @@ flushDebugLog(); // On error
 **Purpose**: AWS Lambda-specific utilities.
 
 **Key Classes**:
-
--   `TimeoutCatcher` - Detect approaching Lambda timeout
--   Graceful shutdown handling
+- `TimeoutCatcher` - Detect approaching Lambda timeout
+- Graceful shutdown handling
 
 **Usage**:
 
@@ -533,10 +511,10 @@ const appDefinition = {
     encryption: {
         schema: {
             MyCustomModel: {
-                fields: ['secretData', 'data.apiKey'],
-            },
-        },
-    },
+                fields: ['secretData', 'data.apiKey']
+            }
+        }
+    }
 };
 ```
 
@@ -547,8 +525,8 @@ Edit `database/encryption/encryption-schema-registry.js`:
 ```javascript
 const ENCRYPTION_SCHEMA = {
     MyModel: {
-        fields: ['sensitiveField'],
-    },
+        fields: ['sensitiveField']
+    }
 };
 ```
 
@@ -593,7 +571,7 @@ describe('MyUseCase', () => {
     beforeEach(() => {
         mockRepository = {
             findById: jest.fn(),
-            save: jest.fn(),
+            save: jest.fn()
         };
         useCase = new MyUseCase({ repository: mockRepository });
     });
@@ -660,35 +638,35 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 
 ### Required
 
--   `AWS_REGION` - AWS region for services
--   `DATABASE_URL` - Database connection string (auto-set)
--   `DB_TYPE` - Database type: 'mongodb' or 'postgresql'
+- `AWS_REGION` - AWS region for services
+- `DATABASE_URL` - Database connection string (auto-set)
+- `DB_TYPE` - Database type: 'mongodb' or 'postgresql'
 
 ### Encryption
 
--   `KMS_KEY_ARN` - AWS KMS key ARN (production)
--   `AES_KEY_ID` - AES key ID (development)
--   `AES_KEY` - AES encryption key (development)
--   `STAGE` - Environment stage (dev, test, local bypass encryption)
+- `KMS_KEY_ARN` - AWS KMS key ARN (production)
+- `AES_KEY_ID` - AES key ID (development)
+- `AES_KEY` - AES encryption key (development)
+- `STAGE` - Environment stage (dev, test, local bypass encryption)
 
 ### Optional
 
--   `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
--   `DEBUG` - Debug logging pattern
--   `LOG_LEVEL` - Logging level (debug, info, warn, error)
+- `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
+- `DEBUG` - Debug logging pattern
+- `LOG_LEVEL` - Logging level (debug, info, warn, error)
 
 ## Version Information
 
--   **Current Version**: 2.0.0-next.0 (pre-release)
--   **Node.js**: >=18 required
--   **Dependencies**: See package.json for full list
+- **Current Version**: 2.0.0-next.0 (pre-release)
+- **Node.js**: >=18 required
+- **Dependencies**: See package.json for full list
 
 ## Support and Documentation
 
--   **Main Framework CLAUDE.md**: See root Frigg CLAUDE.md for framework-wide guidance
--   **Core Runtime**: See `core/CLAUDE.md` for Lambda/Worker patterns
--   **Encryption**: See `database/encryption/README.md` for encryption details
--   **Package README**: See `README.md` for API reference
+- **Main Framework CLAUDE.md**: See root Frigg CLAUDE.md for framework-wide guidance
+- **Core Runtime**: See `core/CLAUDE.md` for Lambda/Worker patterns
+- **Encryption**: See `database/encryption/README.md` for encryption details
+- **Package README**: See `README.md` for API reference
 
 ## Recent Important Changes
 
@@ -699,15 +677,13 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 **Problem**: The `FieldEncryptionService` was converting objects to the string `"[object Object]"` before encrypting, corrupting JSON fields like `IntegrationMapping.mapping`.
 
 **Solution**: Added `_serializeForEncryption()` and `_deserializeAfterDecryption()` methods:
-
--   Objects are now JSON.stringify'd before encryption
--   Decrypted strings are JSON.parse'd back to objects
--   Plain strings work as before
+- Objects are now JSON.stringify'd before encryption
+- Decrypted strings are JSON.parse'd back to objects
+- Plain strings work as before
 
 **Files Changed**:
-
--   `database/encryption/field-encryption-service.js`
--   `database/encryption/field-encryption-service.test.js`
+- `database/encryption/field-encryption-service.js`
+- `database/encryption/field-encryption-service.test.js`
 
 **Test Coverage**: All 40 tests pass, including new object encryption test.