@friggframework/core 2.0.0-next.1 → 2.0.0-next.100

package/admin-scripts/repositories/script-schedule-repository-postgres.js

@@ -0,0 +1,210 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ScriptScheduleRepositoryInterface,
+} = require('./script-schedule-repository-interface');
+
+/**
+ * PostgreSQL Script Schedule Repository Adapter
+ * Handles script schedule persistence using Prisma with PostgreSQL
+ *
+ * PostgreSQL-specific characteristics:
+ * - Uses Int IDs with autoincrement
+ * - Requires ID conversion: String (app layer) ↔ Int (database)
+ * - All returned IDs are converted to strings for application layer consistency
+ * - scriptName has unique index
+ */
+class ScriptScheduleRepositoryPostgres extends ScriptScheduleRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = Number.parseInt(id, 10);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
+    /**
+     * Convert schedule object IDs to strings
+     * @private
+     * @param {Object|null} schedule - Schedule object from database
+     * @returns {Object|null} Schedule with string IDs
+     */
+    _convertScheduleIds(schedule) {
+        if (!schedule) return schedule;
+        return {
+            ...schedule,
+            id: schedule.id?.toString(),
+        };
+    }
+
+    /**
+     * Find a schedule by script name
+     *
+     * @param {string} scriptName - The script name
+     * @returns {Promise<Object|null>} Schedule record with string ID or null if not found
+     */
+    async findScheduleByScriptName(scriptName) {
+        const schedule = await this.prisma.scriptSchedule.findUnique({
+            where: { scriptName },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Create or update a schedule (upsert)
+     *
+     * @param {Object} params - Schedule parameters
+     * @param {string} params.scriptName - Name of the script
+     * @param {boolean} params.enabled - Whether schedule is enabled
+     * @param {string} params.cronExpression - Cron expression
+     * @param {string} [params.timezone] - Timezone (default 'UTC')
+     * @param {string} [params.externalScheduleId] - External scheduler ID (e.g., AWS ARN)
+     * @param {string} [params.externalScheduleName] - External scheduler name
+     * @returns {Promise<Object>} Created or updated schedule record with string ID
+     */
+    async upsertSchedule({ scriptName, enabled, cronExpression, timezone, externalScheduleId, externalScheduleName }) {
+        const data = {
+            enabled,
+            cronExpression,
+            timezone: timezone || 'UTC',
+        };
+
+        // Only set external scheduler fields if provided
+        if (externalScheduleId !== undefined) data.externalScheduleId = externalScheduleId;
+        if (externalScheduleName !== undefined) data.externalScheduleName = externalScheduleName;
+
+        const schedule = await this.prisma.scriptSchedule.upsert({
+            where: { scriptName },
+            update: data,
+            create: {
+                scriptName,
+                ...data,
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Delete a schedule by script name
+     *
+     * @param {string} scriptName - The script name
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteSchedule(scriptName) {
+        try {
+            const schedule = await this.prisma.scriptSchedule.delete({
+                where: { scriptName },
+            });
+
+            return {
+                acknowledged: true,
+                deletedCount: 1,
+                deleted: this._convertScheduleIds(schedule),
+            };
+        } catch (error) {
+            // Return 0 count if not found
+            if (error.code === 'P2025') {
+                return {
+                    acknowledged: true,
+                    deletedCount: 0,
+                };
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Update external scheduler information
+     *
+     * @param {string} scriptName - The script name
+     * @param {Object} externalInfo - External schedule information
+     * @param {string} [externalInfo.externalScheduleId] - External scheduler ID (e.g., AWS ARN)
+     * @param {string} [externalInfo.externalScheduleName] - External scheduler name
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleExternalInfo(scriptName, { externalScheduleId, externalScheduleName }) {
+        const data = {};
+        if (externalScheduleId !== undefined) data.externalScheduleId = externalScheduleId;
+        if (externalScheduleName !== undefined) data.externalScheduleName = externalScheduleName;
+
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data,
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Update last triggered timestamp
+     *
+     * @param {string} scriptName - The script name
+     * @param {Date} [timestamp] - Trigger timestamp (default: now)
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleLastTriggered(scriptName, timestamp) {
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data: {
+                lastTriggeredAt: timestamp || new Date(),
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * Update next trigger timestamp
+     *
+     * @param {string} scriptName - The script name
+     * @param {Date} timestamp - Next trigger timestamp
+     * @returns {Promise<Object>} Updated schedule record with string ID
+     */
+    async updateScheduleNextTrigger(scriptName, timestamp) {
+        const schedule = await this.prisma.scriptSchedule.update({
+            where: { scriptName },
+            data: {
+                nextTriggerAt: timestamp,
+            },
+        });
+
+        return this._convertScheduleIds(schedule);
+    }
+
+    /**
+     * List all schedules
+     *
+     * @param {Object} [options] - Query options
+     * @param {boolean} [options.enabledOnly] - Only return enabled schedules
+     * @returns {Promise<Array>} Array of schedule records with string IDs
+     */
+    async listSchedules(options = {}) {
+        const where = {};
+        if (options.enabledOnly) {
+            where.enabled = true;
+        }
+
+        const schedules = await this.prisma.scriptSchedule.findMany({
+            where,
+            orderBy: { scriptName: 'asc' },
+        });
+
+        return schedules.map((schedule) => this._convertScheduleIds(schedule));
+    }
+}
+
+module.exports = { ScriptScheduleRepositoryPostgres };

package/application/commands/README.md

@@ -0,0 +1,451 @@
+# Frigg Commands - Application Service Layer
+
+## Overview
+
+Frigg Commands provide a clean, stable application service layer for all database operations in the Frigg Integration Framework. They abstract away the underlying ORM (currently Mongoose) and provide a consistent API for managing users, credentials, entities, and integrations.
+
+## Why Use Commands?
+
+### 1. **ORM Independence**
+
+Commands isolate your integration code from the underlying database implementation. This allows Frigg to migrate between ORMs (e.g., Mongoose to Prisma) without breaking your integration code.
+
+### 2. **Hexagonal Architecture**
+
+Commands act as the **application service layer** in hexagonal architecture:
+
+-   **Domain Layer**: Your use cases and business logic
+-   **Application Layer**: Frigg Commands (this layer)
+-   **Infrastructure Layer**: Repositories and database models (hidden from you)
+
+### 3. **Single Source of Truth**
+
+All database operations flow through commands, making it easier to:
+
+-   Add caching, logging, or monitoring
+-   Enforce data validation rules
+-   Maintain consistent error handling
+-   Track data access patterns
+
+### 4. **Future-Proof**
+
+When Frigg upgrades its internals, commands maintain backward compatibility. Your integration code continues working without changes.
+
+## Installation
+
+Commands are available through the `@friggframework/core` package:
+
+```javascript
+const { createFriggCommands } = require('@friggframework/core');
+```
+
+## Basic Usage
+
+### Initialize Commands
+
+```javascript
+const { createFriggCommands } = require('@friggframework/core');
+const MyIntegration = require('./MyIntegration');
+
+// Create command set with your integration class
+const commands = createFriggCommands({
+    integrationClass: MyIntegration,
+});
+```
+
+### Use Commands in Your Integration
+
+```javascript
+class MyIntegration extends IntegrationBase {
+    constructor() {
+        super();
+        this.commands = createFriggCommands({
+            integrationClass: MyIntegration,
+        });
+    }
+
+    async hydrateFromExternalUser(externalUserId) {
+        // Find integration context by external entity ID
+        const result =
+            await this.commands.findIntegrationContextByExternalEntityId(
+                externalUserId
+            );
+
+        if (result.error) {
+            return { error: result.error };
+        }
+
+        // Hydrate integration with retrieved context
+        this.setIntegrationRecord(result.context);
+        return { record: this.record };
+    }
+}
+```
+
+### Use Commands in Use Cases
+
+```javascript
+const { createFriggCommands } = require('@friggframework/core');
+
+class AuthenticateUserUseCase {
+    constructor({ commands } = {}) {
+        // Accept injected commands for testing, or create default
+        this.commands =
+            commands ||
+            createFriggCommands({
+                integrationClass: MyIntegration,
+            });
+    }
+
+    async execute({ appUserId, username, email }) {
+        // Find or create user
+        let user = await this.commands.findUserByAppUserId(appUserId);
+
+        if (!user) {
+            user = await this.commands.createUser({
+                appUserId,
+                username,
+                email,
+            });
+        }
+
+        return user;
+    }
+}
+```
+
+## Available Commands
+
+### User Commands
+
+Manage Frigg users (individuals or organizations using your integration).
+
+```javascript
+// Create a new user
+const user = await commands.createUser({
+    username: 'john@example.com',
+    email: 'john@example.com',
+    appUserId: 'external-user-123',
+    password: 'optional-password', // For password-based auth
+});
+
+// Find user by app-specific user ID
+const user = await commands.findUserByAppUserId('external-user-123');
+
+// Find user by username
+const user = await commands.findUserByUsername('john@example.com');
+
+// Find user by Frigg internal ID
+const user = await commands.findIndividualUserById('frigg-user-id');
+
+// Update user
+const updatedUser = await commands.updateUser('frigg-user-id', {
+    email: 'newemail@example.com',
+});
+```
+
+### Credential Commands
+
+Manage OAuth tokens and API credentials.
+
+```javascript
+// Create credential
+const credential = await commands.createCredential({
+    userId: 'frigg-user-id',
+    externalId: 'oauth-user-id',
+    access_token: 'access_token_value',
+    refresh_token: 'refresh_token_value',
+    expires_at: new Date('2024-12-31'),
+    moduleName: 'asana',
+    authIsValid: true,
+});
+
+// Find credential
+const credential = await commands.findCredential({
+    userId: 'frigg-user-id',
+    moduleName: 'asana',
+});
+
+// Update credential (e.g., after token refresh)
+const updated = await commands.updateCredential('credential-id', {
+    access_token: 'new_access_token',
+    expires_at: new Date('2025-01-31'),
+});
+
+// Delete credential
+await commands.deleteCredential('credential-id');
+```
+
+### Entity Commands
+
+Manage module entities (connections to external services).
+
+```javascript
+// Create entity
+const entity = await commands.createEntity({
+    userId: 'frigg-user-id',
+    externalId: 'asana-workspace-123',
+    name: 'My Workspace',
+    moduleName: 'asana',
+    credentialId: 'credential-id',
+});
+
+// Find single entity
+const entity = await commands.findEntity({
+    userId: 'frigg-user-id',
+    externalId: 'asana-workspace-123',
+    moduleName: 'asana',
+});
+
+// Find entity by ID
+const entity = await commands.findEntityById('entity-id');
+
+// Find all entities for user
+const entities = await commands.findEntitiesByUserId('frigg-user-id');
+
+// Find entities by module
+const asanaEntities = await commands.findEntitiesByUserIdAndModuleName(
+    'frigg-user-id',
+    'asana'
+);
+
+// Find multiple entities by IDs
+const entities = await commands.findEntitiesByIds([
+    'entity-id-1',
+    'entity-id-2',
+]);
+
+// Update entity
+const updated = await commands.updateEntity('entity-id', {
+    name: 'Updated Workspace Name',
+});
+
+// Delete entity
+await commands.deleteEntity('entity-id');
+```
+
+### Integration Commands
+
+Manage integration records and load full integration contexts.
+
+```javascript
+// Find integration context by external entity ID
+// Returns { context, error } where context includes record + hydrated modules
+const result = await commands.findIntegrationContextByExternalEntityId(
+    'external-user-or-workspace-id'
+);
+
+if (!result.error) {
+    integration.setIntegrationRecord(result.context);
+}
+
+// Load integration context by integration ID
+const result = await commands.loadIntegrationContextById('integration-id');
+
+if (!result.error) {
+    integration.setIntegrationRecord(result.context);
+}
+```
+
+## Architecture Principles
+
+### Dependency Injection for Testing
+
+Commands support dependency injection for testing:
+
+```javascript
+// Production code - uses real repositories
+const commands = createFriggCommands({ integrationClass: MyIntegration });
+
+// Test code - inject mocks
+const mockCommands = {
+    createUser: jest.fn().mockResolvedValue({ id: 'user-123' }),
+    findUserByAppUserId: jest.fn().mockResolvedValue(null),
+};
+
+const useCase = new MyUseCase({ commands: mockCommands });
+```
+
+### Integration vs Unit Testing
+
+**Commands are designed for integration testing** - they use real repositories by default:
+
+```javascript
+// ❌ Don't do this - commands always use real repositories
+const commands = createFriggCommands({
+    userRepository: mockUserRepo, // This parameter doesn't exist
+});
+
+// ✅ Do this - inject mocked commands into your use cases
+const useCase = new MyUseCase({
+    commands: mockCommands,
+});
+```
+
+### Error Handling
+
+Commands return domain objects directly. Handle errors at the use case level:
+
+```javascript
+try {
+    const user = await commands.createUser({ username, email });
+    return { success: true, user };
+} catch (error) {
+    // Handle database errors
+    return { success: false, error: error.message };
+}
+```
+
+For integration context operations, errors are returned in the result:
+
+```javascript
+const result = await commands.findIntegrationContextByExternalEntityId(userId);
+
+if (result.error) {
+    return { error: result.error };
+}
+
+// Use result.context
+```
+
+## Migration Guide
+
+### From Direct Model Access
+
+**Before (❌ Don't do this):**
+
+```javascript
+const { User } = require('@friggframework/core');
+
+const user = await User.findOne({ appUserId: '123' });
+```
+
+**After (✅ Do this):**
+
+```javascript
+const { createFriggCommands } = require('@friggframework/core');
+
+const commands = createFriggCommands({ integrationClass: MyIntegration });
+const user = await commands.findUserByAppUserId('123');
+```
+
+### From IntegrationRepository (Backend Pattern)
+
+**Before (❌ Old pattern):**
+
+```javascript
+const {
+    IntegrationRepository,
+} = require('./repositories/IntegrationRepository');
+
+this.integrationRepository = new IntegrationRepository(MyIntegration);
+const result =
+    await this.integrationRepository.loadIntegrationRecordByAsanaUser(userId);
+```
+
+**After (✅ New pattern):**
+
+```javascript
+const { createFriggCommands } = require('@friggframework/core');
+
+this.commands = createFriggCommands({ integrationClass: MyIntegration });
+const result = await this.commands.findIntegrationContextByExternalEntityId(
+    userId
+);
+```
+
+## Best Practices
+
+### 1. Create Commands Once
+
+Initialize commands in your constructor:
+
+```javascript
+class MyIntegration extends IntegrationBase {
+    constructor() {
+        super();
+        this.commands = createFriggCommands({
+            integrationClass: MyIntegration,
+        });
+    }
+}
+```
+
+### 2. Pass Commands to Use Cases
+
+Use dependency injection for testability:
+
+```javascript
+class MyUseCase {
+    constructor({ commands } = {}) {
+        this.commands =
+            commands ||
+            createFriggCommands({
+                integrationClass: MyIntegration,
+            });
+    }
+}
+```
+
+### 3. Use Specific Finders
+
+Use the most specific finder method:
+
+```javascript
+// ✅ Good - specific finder
+const user = await commands.findUserByAppUserId('123');
+
+// ❌ Less efficient - generic finder
+const user = await commands.findUser({ appUserId: '123' });
+```
+
+### 4. Handle Null Returns
+
+Most finders return `null` if not found:
+
+```javascript
+const user = await commands.findUserByAppUserId('123');
+
+if (!user) {
+    // Handle user not found
+    user = await commands.createUser({ ... });
+}
+```
+
+## Command Reference
+
+| Category        | Command                                                 | Description                               |
+| --------------- | ------------------------------------------------------- | ----------------------------------------- |
+| **User**        | `createUser(data)`                                      | Create new Frigg user                     |
+|                 | `findUserByAppUserId(appUserId)`                        | Find by external app user ID              |
+|                 | `findUserByUsername(username)`                          | Find by username                          |
+|                 | `findIndividualUserById(id)`                            | Find by Frigg user ID                     |
+|                 | `updateUser(id, updates)`                               | Update user properties                    |
+| **Credential**  | `createCredential(data)`                                | Create OAuth credential                   |
+|                 | `findCredential(filter)`                                | Find credential by filter                 |
+|                 | `updateCredential(id, updates)`                         | Update credential (token refresh)         |
+|                 | `deleteCredential(id)`                                  | Delete credential                         |
+| **Entity**      | `createEntity(data)`                                    | Create module entity                      |
+|                 | `findEntity(filter)`                                    | Find entity by filter                     |
+|                 | `findEntityById(id)`                                    | Find by entity ID                         |
+|                 | `findEntitiesByUserId(userId)`                          | Find all user entities                    |
+|                 | `findEntitiesByUserIdAndModuleName(userId, moduleName)` | Find user entities for module             |
+|                 | `findEntitiesByIds(ids)`                                | Find multiple by IDs                      |
+|                 | `updateEntity(id, updates)`                             | Update entity properties                  |
+|                 | `deleteEntity(id)`                                      | Delete entity                             |
+| **Integration** | `findIntegrationContextByExternalEntityId(externalId)`  | Load integration + modules by external ID |
+|                 | `loadIntegrationContextById(integrationId)`             | Load integration + modules by ID          |
+
+## Support
+
+For questions or issues with commands:
+
+1. Check this README
+2. Review the main Frigg documentation
+3. Open an issue on the Frigg Framework repository
+
+## Related Documentation
+
+-   [Frigg Framework Overview](../../README.md)
+-   [Integration Development Guide](../../docs/integration-guide.md)
+-   [Hexagonal Architecture](../../docs/architecture.md)