@friggframework/core 2.0.0--canary.545.ccb5010.0 → 2.0.0--canary.549.b074651.0

package/README.md

@@ -4,16 +4,16 @@ The `@friggframework/core` package is the foundational layer of the Frigg Framew
 
 ## Table of Contents
 
--   [Architecture Overview](#architecture-overview)
--   [Installation](#installation)
--   [Quick Start](#quick-start)
--   [Core Components](#core-components)
--   [Hexagonal Architecture](#hexagonal-architecture)
--   [Usage Examples](#usage-examples)
--   [Testing](#testing)
--   [Development](#development)
--   [API Reference](#api-reference)
--   [Contributing](#contributing)
+- [Architecture Overview](#architecture-overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Components](#core-components)
+- [Hexagonal Architecture](#hexagonal-architecture)
+- [Usage Examples](#usage-examples)
+- [Testing](#testing)
+- [Development](#development)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
 
 ## Architecture Overview
 
@@ -67,13 +67,11 @@ yarn add @friggframework/core
 `@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`)
+- 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
@@ -83,7 +81,6 @@ yarn add -D prisma @prisma/client
 ```
 
 **Generate Prisma Clients:**
-
 ```bash
 # From @friggframework/core directory
 npm run prisma:generate:mongo      # MongoDB only
@@ -95,9 +92,9 @@ npm run prisma:generate            # Both databases
 
 ### Prerequisites
 
--   Node.js 16+
--   MongoDB 4.4+ (for data persistence)
--   AWS credentials (for SQS, KMS, Lambda deployment)
+- Node.js 16+ 
+- MongoDB 4.4+ (for data persistence)
+- AWS credentials (for SQS, KMS, Lambda deployment)
 
 ### Environment Variables
 
@@ -123,13 +120,11 @@ LOG_LEVEL=info
 The heart of the framework - manages integration lifecycle and business logic.
 
 **Key Classes:**
-
--   `IntegrationBase` - Base class for all integrations
--   `Integration` - Domain aggregate using Proxy pattern
--   Use cases: `CreateIntegration`, `UpdateIntegration`, `DeleteIntegration`
+- `IntegrationBase` - Base class for all integrations
+- `Integration` - Domain aggregate using Proxy pattern
+- Use cases: `CreateIntegration`, `UpdateIntegration`, `DeleteIntegration`
 
 **Usage:**
-
 ```javascript
 const { IntegrationBase } = require('@friggframework/core');
 
@@ -139,8 +134,8 @@ class SlackHubSpotSync extends IntegrationBase {
         version: '2.1.0',
         modules: {
             slack: 'slack',
-            hubspot: 'hubspot',
-        },
+            hubspot: 'hubspot'
+        }
     };
 
     async onCreate({ integrationId }) {
@@ -157,32 +152,30 @@ class SlackHubSpotSync extends IntegrationBase {
 MongoDB integration with Mongoose ODM.
 
 **Key Components:**
-
--   Connection management
--   Pre-built models (User, Integration, Credential, etc.)
--   Schema definitions
+- Connection management
+- Pre-built models (User, Integration, Credential, etc.)
+- Schema definitions
 
 **Usage:**
-
 ```javascript
-const {
-    connectToDatabase,
-    IntegrationModel,
-    UserModel,
+const { 
+    connectToDatabase, 
+    IntegrationModel, 
+    UserModel 
 } = require('@friggframework/core');
 
 await connectToDatabase();
 
 // Query integrations
-const userIntegrations = await IntegrationModel.find({
+const userIntegrations = await IntegrationModel.find({ 
     userId: 'user-123',
-    status: 'ENABLED',
+    status: 'ENABLED' 
 });
 
 // Create user
 const user = new UserModel({
     email: 'user@example.com',
-    name: 'John Doe',
+    name: 'John Doe'
 });
 await user.save();
 ```
@@ -192,7 +185,6 @@ await user.save();
 AES-256-GCM encryption for sensitive data.
 
 **Usage:**
-
 ```javascript
 const { Encrypt, Cryptor } = require('@friggframework/core');
 
@@ -202,12 +194,10 @@ const decrypted = Encrypt.decrypt(encrypted);
 
 // Advanced encryption with custom key
 const cryptor = new Cryptor(process.env.CUSTOM_KEY);
-const secureData = cryptor.encrypt(
-    JSON.stringify({
-        accessToken: 'oauth-token',
-        refreshToken: 'refresh-token',
-    })
-);
+const secureData = cryptor.encrypt(JSON.stringify({
+    accessToken: 'oauth-token',
+    refreshToken: 'refresh-token'
+}));
 ```
 
 ### 5. Error Handling (`/errors`)
@@ -215,12 +205,11 @@ const secureData = cryptor.encrypt(
 Standardized error types with proper HTTP status codes.
 
 **Usage:**
-
 ```javascript
-const {
-    BaseError,
-    RequiredPropertyError,
-    FetchError,
+const { 
+    BaseError, 
+    RequiredPropertyError, 
+    FetchError 
 } = require('@friggframework/core');
 
 // Custom business logic error
@@ -229,13 +218,13 @@ throw new RequiredPropertyError('userId is required');
 // API communication error
 throw new FetchError('Failed to fetch data from external API', {
     statusCode: 404,
-    response: errorResponse,
+    response: errorResponse
 });
 
 // Base error with custom properties
 throw new BaseError('Integration failed', {
     integrationId: 'int-123',
-    errorCode: 'SYNC_FAILED',
+    errorCode: 'SYNC_FAILED'
 });
 ```
 
@@ -244,7 +233,6 @@ throw new BaseError('Integration failed', {
 Structured logging with debug capabilities.
 
 **Usage:**
-
 ```javascript
 const { debug, initDebugLog, flushDebugLog } = require('@friggframework/core');
 
@@ -252,9 +240,9 @@ const { debug, initDebugLog, flushDebugLog } = require('@friggframework/core');
 initDebugLog('integration:slack');
 
 // Log debug information
-debug('Processing webhook payload', {
+debug('Processing webhook payload', { 
     eventType: 'contact.created',
-    payload: webhookData,
+    payload: webhookData 
 });
 
 // Flush logs (useful in serverless environments)
@@ -266,31 +254,27 @@ await flushDebugLog();
 Comprehensive user authentication and authorization system supporting both individual and organizational users.
 
 **Key Classes:**
-
--   `User` - Domain aggregate for user entities
--   `UserRepository` - Data access for user operations
--   Use cases: `LoginUser`, `CreateIndividualUser`, `CreateOrganizationUser`, `GetUserFromBearerToken`
+- `User` - Domain aggregate for user entities
+- `UserRepository` - Data access for user operations
+- Use cases: `LoginUser`, `CreateIndividualUser`, `CreateOrganizationUser`, `GetUserFromBearerToken`
 
 **User Types:**
-
--   **Individual Users**: Personal accounts with email/username authentication
--   **Organization Users**: Business accounts with organization-level access
--   **Hybrid Mode**: Support for both user types simultaneously
+- **Individual Users**: Personal accounts with email/username authentication
+- **Organization Users**: Business accounts with organization-level access
+- **Hybrid Mode**: Support for both user types simultaneously
 
 **Authentication Methods:**
-
--   **Password-based**: Traditional username/password authentication
--   **Token-based**: Bearer token authentication with session management
--   **App-based**: External app user ID authentication (passwordless)
+- **Password-based**: Traditional username/password authentication
+- **Token-based**: Bearer token authentication with session management
+- **App-based**: External app user ID authentication (passwordless)
 
 **Usage:**
-
 ```javascript
-const {
-    LoginUser,
-    CreateIndividualUser,
+const { 
+    LoginUser, 
+    CreateIndividualUser, 
     GetUserFromBearerToken,
-    UserRepository,
+    UserRepository 
 } = require('@friggframework/core');
 
 // Configure user behavior in app definition
@@ -298,7 +282,7 @@ const userConfig = {
     usePassword: true,
     primary: 'individual', // or 'organization'
     individualUserRequired: true,
-    organizationUserRequired: false,
+    organizationUserRequired: false
 };
 
 const userRepository = new UserRepository({ userConfig });
@@ -309,21 +293,18 @@ const user = await createUser.execute({
     email: 'user@example.com',
     username: 'john_doe',
     password: 'secure_password',
-    appUserId: 'external_user_123', // Optional external reference
+    appUserId: 'external_user_123' // Optional external reference
 });
 
 // Login user
 const loginUser = new LoginUser({ userRepository, userConfig });
 const authenticatedUser = await loginUser.execute({
     username: 'john_doe',
-    password: 'secure_password',
+    password: 'secure_password'
 });
 
 // Token-based authentication
-const getUserFromToken = new GetUserFromBearerToken({
-    userRepository,
-    userConfig,
-});
+const getUserFromToken = new GetUserFromBearerToken({ userRepository, userConfig });
 const user = await getUserFromToken.execute('Bearer eyJhbGciOiJIUzI1NiIs...');
 
 // Access user properties
@@ -338,13 +319,12 @@ console.log('Organization user:', user.getOrganizationUser());
 AWS Lambda-specific utilities and helpers.
 
 **Usage:**
-
 ```javascript
 const { TimeoutCatcher } = require('@friggframework/core');
 
 exports.handler = async (event, context) => {
     const timeoutCatcher = new TimeoutCatcher(context);
-
+    
     try {
         // Long-running integration process
         const result = await processIntegrationSync(event);
@@ -373,11 +353,11 @@ User behavior is configured in the app definition, allowing you to customize aut
 const appDefinition = {
     integrations: [HubSpotIntegration],
     user: {
-        usePassword: true, // Enable password authentication
-        primary: 'individual', // Primary user type: 'individual' or 'organization'
-        organizationUserRequired: true, // Require organization user
-        individualUserRequired: true, // Require individual user
-    },
+        usePassword: true,                    // Enable password authentication
+        primary: 'individual',               // Primary user type: 'individual' or 'organization'
+        organizationUserRequired: true,      // Require organization user
+        individualUserRequired: true,        // Require individual user
+    }
 };
 ```
 
@@ -392,20 +372,20 @@ const { User } = require('@friggframework/core');
 const user = new User(individualUser, organizationUser, usePassword, primary);
 
 // Access methods
-user.getId(); // Get primary user ID
-user.getPrimaryUser(); // Get primary user based on config
-user.getIndividualUser(); // Get individual user
-user.getOrganizationUser(); // Get organization user
+user.getId()                    // Get primary user ID
+user.getPrimaryUser()          // Get primary user based on config
+user.getIndividualUser()       // Get individual user
+user.getOrganizationUser()     // Get organization user
 
 // Validation methods
-user.isPasswordRequired(); // Check if password is required
-user.isPasswordValid(password); // Validate password
-user.isIndividualUserRequired(); // Check individual user requirement
-user.isOrganizationUserRequired(); // Check organization user requirement
+user.isPasswordRequired()      // Check if password is required
+user.isPasswordValid(password) // Validate password
+user.isIndividualUserRequired() // Check individual user requirement
+user.isOrganizationUserRequired() // Check organization user requirement
 
 // Configuration methods
-user.setIndividualUser(individualUser);
-user.setOrganizationUser(organizationUser);
+user.setIndividualUser(individualUser)
+user.setOrganizationUser(organizationUser)
 ```
 
 ### Database Models
@@ -441,11 +421,11 @@ The user system uses MongoDB with Mongoose for data persistence:
 
 ### Security Features
 
--   **Password Hashing**: Uses bcrypt with configurable salt rounds
--   **Token Management**: Secure session tokens with expiration
--   **Unique Constraints**: Enforced username and email uniqueness
--   **External References**: Support for external app user/org IDs
--   **Flexible Authentication**: Multiple authentication methods
+- **Password Hashing**: Uses bcrypt with configurable salt rounds
+- **Token Management**: Secure session tokens with expiration
+- **Unique Constraints**: Enforced username and email uniqueness
+- **External References**: Support for external app user/org IDs
+- **Flexible Authentication**: Multiple authentication methods
 
 ## Hexagonal Architecture
 
@@ -466,9 +446,7 @@ class UpdateIntegrationStatus {
         }
 
         // Domain operation
-        const integration = await this.integrationRepository.findById(
-            integrationId
-        );
+        const integration = await this.integrationRepository.findById(integrationId);
         if (!integration) {
             throw new Error('Integration not found');
         }
@@ -476,7 +454,7 @@ class UpdateIntegrationStatus {
         // Update and persist
         integration.status = newStatus;
         integration.updatedAt = new Date();
-
+        
         return await this.integrationRepository.save(integration);
     }
 }
@@ -506,7 +484,7 @@ class IntegrationRepository {
             userId,
             config,
             status: 'NEW',
-            createdAt: new Date(),
+            createdAt: new Date()
         });
         return await integration.save();
     }
@@ -522,7 +500,7 @@ const Integration = new Proxy(class {}, {
     construct(target, args) {
         const [params] = args;
         const instance = new params.integrationClass(params);
-
+        
         // Attach domain properties
         Object.assign(instance, {
             id: params.id,
@@ -530,11 +508,11 @@ const Integration = new Proxy(class {}, {
             entities: params.entities,
             config: params.config,
             status: params.status,
-            modules: params.modules,
+            modules: params.modules
         });
 
         return instance;
-    },
+    }
 });
 ```
 
@@ -587,7 +565,7 @@ class HubSpotIntegration extends IntegrationBase {
 
     constructor() {
         super();
-
+        
         // Define event handlers for various integration actions
         this.events = {
             // Webhook handler with real-time WebSocket broadcasting
@@ -596,8 +574,7 @@ class HubSpotIntegration extends IntegrationBase {
                     console.log('Received HubSpot webhook:', data);
 
                     // Broadcast to all connected WebSocket clients
-                    const activeConnections =
-                        await WebsocketConnection.getActiveConnections();
+                    const activeConnections = await WebsocketConnection.getActiveConnections();
                     const message = JSON.stringify({
                         type: 'HUBSPOT_WEBHOOK',
                         data,
@@ -608,17 +585,16 @@ class HubSpotIntegration extends IntegrationBase {
                     });
                 },
             },
-
+            
             // User action: Get sample data with formatted table output
             [FriggConstants.defaultEvents.GET_SAMPLE_DATA]: {
                 type: FriggConstants.eventTypes.USER_ACTION,
                 handler: this.getSampleData,
                 title: 'Get Sample Data',
-                description:
-                    'Get sample data from HubSpot and display in a formatted table',
+                description: 'Get sample data from HubSpot and display in a formatted table',
                 userActionType: 'QUICK_ACTION',
             },
-
+            
             // User action: List available objects
             GET_OBJECT_LIST: {
                 type: FriggConstants.eventTypes.USER_ACTION,
@@ -627,7 +603,7 @@ class HubSpotIntegration extends IntegrationBase {
                 description: 'Get list of available HubSpot objects',
                 userActionType: 'DATA',
             },
-
+            
             // User action: Create records with dynamic forms
             CREATE_RECORD: {
                 type: FriggConstants.eventTypes.USER_ACTION,
@@ -637,7 +613,7 @@ class HubSpotIntegration extends IntegrationBase {
                 userActionType: 'DATA',
             },
         };
-
+        
         // Extension system for modular functionality
         this.extensions = {
             hubspotWebhooks: {
@@ -711,7 +687,7 @@ class HubSpotIntegration extends IntegrationBase {
         let res;
         const objectType = args.objectType;
         delete args.objectType;
-
+        
         switch (objectType.toLowerCase()) {
             case 'deal':
                 res = await this.hubspot.api.createDeal({ ...args });
@@ -742,7 +718,7 @@ class HubSpotIntegration extends IntegrationBase {
                     },
                     required: [],
                 };
-
+                
                 let uiSchema = {
                     type: 'HorizontalLayout',
                     elements: [
@@ -768,7 +744,7 @@ class HubSpotIntegration extends IntegrationBase {
                             { type: 'Control', scope: '#/properties/amount' }
                         );
                         break;
-
+                        
                     case 'company':
                         jsonSchema.properties = {
                             ...jsonSchema.properties,
@@ -781,7 +757,7 @@ class HubSpotIntegration extends IntegrationBase {
                             { type: 'Control', scope: '#/properties/website' }
                         );
                         break;
-
+                        
                     case 'contact':
                         jsonSchema.properties = {
                             ...jsonSchema.properties,
@@ -789,25 +765,16 @@ class HubSpotIntegration extends IntegrationBase {
                             lastname: { type: 'string', title: 'Last Name' },
                             email: { type: 'string', title: 'Email Address' },
                         };
-                        jsonSchema.required = [
-                            'firstname',
-                            'lastname',
-                            'email',
-                        ];
+                        jsonSchema.required = ['firstname', 'lastname', 'email'];
                         uiSchema.elements.push(
-                            {
-                                type: 'Control',
-                                scope: '#/properties/firstname',
-                            },
+                            { type: 'Control', scope: '#/properties/firstname' },
                             { type: 'Control', scope: '#/properties/lastname' },
                             { type: 'Control', scope: '#/properties/email' }
                         );
                         break;
-
+                        
                     default:
-                        throw new Error(
-                            `Unsupported object type: ${data.name}`
-                        );
+                        throw new Error(`Unsupported object type: ${data.name}`);
                 }
 
                 return {
@@ -829,25 +796,28 @@ module.exports = HubSpotIntegration;
 ```
 
 index.js
-
 ```js
 const HubSpotIntegration = require('./src/integrations/HubSpotIntegration');
 
 const appDefinition = {
-    integrations: [HubSpotIntegration],
+    integrations: [
+        HubSpotIntegration,
+    ],
     user: {
         usePassword: true,
         primary: 'individual',
         organizationUserRequired: true,
         individualUserRequired: true,
-    },
-};
+    }
+}
 
 module.exports = {
     Definition: appDefinition,
-};
+}
+
 ```
 
+
 ### Key Features Demonstrated
 
 This real-world example showcases:
@@ -860,6 +830,7 @@ This real-world example showcases:
 **🔗 Deep Linking**: Direct links to HubSpot records in formatted data
 **⚡ Real-time Updates**: WebSocket connections for live data streaming
 
+
 ## Testing
 
 ### Running Tests
@@ -889,15 +860,13 @@ describe('CreateIntegration Use-Case', () => {
         useCase = new CreateIntegration({
             integrationRepository,
             integrationClasses: [TestIntegration],
-            moduleFactory,
+            moduleFactory
         });
     });
 
     describe('happy path', () => {
         it('creates an integration and returns DTO', async () => {
-            const result = await useCase.execute(['entity-1'], 'user-1', {
-                type: 'test',
-            });
+            const result = await useCase.execute(['entity-1'], 'user-1', { type: 'test' });
             expect(result.id).toBeDefined();
             expect(result.status).toBe('NEW');
         });
@@ -905,9 +874,8 @@ describe('CreateIntegration Use-Case', () => {
 
     describe('error cases', () => {
         it('throws error for unknown integration type', async () => {
-            await expect(
-                useCase.execute(['entity-1'], 'user-1', { type: 'unknown' })
-            ).rejects.toThrow('No integration class found for type: unknown');
+            await expect(useCase.execute(['entity-1'], 'user-1', { type: 'unknown' }))
+                .rejects.toThrow('No integration class found for type: unknown');
         });
     });
 });
@@ -918,10 +886,7 @@ describe('CreateIntegration Use-Case', () => {
 The framework provides test doubles for external dependencies:
 
 ```javascript
-const {
-    TestIntegrationRepository,
-    TestModuleFactory,
-} = require('@friggframework/core/test');
+const { TestIntegrationRepository, TestModuleFactory } = require('@friggframework/core/test');
 
 // Mock repository for testing
 const testRepo = new TestIntegrationRepository();
@@ -981,7 +946,7 @@ const {
     CreateIntegration,
     UpdateIntegration,
     DeleteIntegration,
-
+    
     // Modules
     OAuth2Requester,
     ApiKeyRequester,
@@ -991,25 +956,25 @@ const {
     connectToDatabase,
     mongoose,
     UserModel,
-
+    
     // Utilities
     Encrypt,
     Cryptor,
     BaseError,
     debug,
-    TimeoutCatcher,
+    TimeoutCatcher
 } = require('@friggframework/core');
 ```
 
 ### Environment Configuration
 
-| Variable               | Required | Description                              |
-| ---------------------- | -------- | ---------------------------------------- |
-| `MONGO_URI`            | Yes      | MongoDB connection string                |
-| `FRIGG_ENCRYPTION_KEY` | Yes      | 256-bit encryption key                   |
-| `AWS_REGION`           | No       | AWS region for services                  |
-| `DEBUG`                | No       | Debug logging pattern                    |
-| `LOG_LEVEL`            | No       | Logging level (debug, info, warn, error) |
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MONGO_URI` | Yes | MongoDB connection string |
+| `FRIGG_ENCRYPTION_KEY` | Yes | 256-bit encryption key |
+| `AWS_REGION` | No | AWS region for services |
+| `DEBUG` | No | Debug logging pattern |
+| `LOG_LEVEL` | No | Logging level (debug, info, warn, error) |
 
 ## License
 
@@ -1019,9 +984,9 @@ This project is licensed under the MIT License - see the [LICENSE.md](../../LICE
 
 ## Support
 
--   📖 [Documentation](https://docs.friggframework.org)
--   💬 [Community Slack](https://friggframework.slack.com)
--   🐛 [Issue Tracker](https://github.com/friggframework/frigg/issues)
--   📧 [Email Support](mailto:support@friggframework.org)
+- 📖 [Documentation](https://docs.friggframework.org)
+- 💬 [Community Slack](https://friggframework.slack.com)  
+- 🐛 [Issue Tracker](https://github.com/friggframework/frigg/issues)
+- 📧 [Email Support](mailto:support@friggframework.org)
 
 Built with ❤️ by the Frigg Framework team.

package/assertions/jest.config.ts

@@ -0,0 +1,7 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+    preset: '@friggframework/test-environment',
+};
+
+export default config;