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

package/application/commands/process-commands.js

@@ -0,0 +1,135 @@
+/**
+ * Process Commands
+ *
+ * Application Layer - Command factory for long-running process tracking.
+ *
+ * Wraps the Process use cases (create, get, update state, update metrics)
+ * behind the same `createXCommands()` surface used by the other domains so
+ * integration developers can track processes without touching repositories
+ * or the underlying ORM directly.
+ *
+ * @example
+ * const processCommands = createProcessCommands();
+ * const process = await processCommands.createProcess({
+ *     userId: 'user-1',
+ *     integrationId: 'integration-1',
+ *     name: 'zoho-crm-contact-sync',
+ *     type: 'CRM_SYNC',
+ * });
+ * await processCommands.updateProcessState(process.id, 'FETCHING_TOTAL');
+ * await processCommands.updateProcessMetrics(process.id, { processed: 100, success: 100 });
+ */
+
+const {
+    createProcessRepository,
+} = require('../../integrations/repositories/process-repository-factory');
+const { CreateProcess } = require('../../integrations/use-cases/create-process');
+const { GetProcess } = require('../../integrations/use-cases/get-process');
+const {
+    UpdateProcessState,
+} = require('../../integrations/use-cases/update-process-state');
+const {
+    UpdateProcessMetrics,
+} = require('../../integrations/use-cases/update-process-metrics');
+
+const ERROR_CODE_MAP = {
+    PROCESS_NOT_FOUND: 404,
+    INVALID_PROCESS_DATA: 400,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return {
+        error: status,
+        reason: error?.message,
+        code: error?.code,
+    };
+}
+
+/**
+ * Create process tracking commands.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.websocketService] - Optional WebSocket service
+ *     forwarded to UpdateProcessMetrics for progress broadcasting.
+ * @returns {Object} Process commands object
+ */
+function createProcessCommands({ websocketService } = {}) {
+    const processRepository = createProcessRepository();
+
+    const createProcessUseCase = new CreateProcess({ processRepository });
+    const getProcessUseCase = new GetProcess({ processRepository });
+    const updateProcessStateUseCase = new UpdateProcessState({
+        processRepository,
+    });
+    const updateProcessMetricsUseCase = new UpdateProcessMetrics({
+        processRepository,
+        websocketService,
+    });
+
+    return {
+        /**
+         * Create a new process record.
+         * @param {Object} processData - Process data (userId, integrationId, name, type, ...)
+         * @returns {Promise<Object>} Created process record
+         */
+        async createProcess(processData) {
+            try {
+                return await createProcessUseCase.execute(processData);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Retrieve a process by ID.
+         * @param {string} processId - Process ID
+         * @returns {Promise<Object|null>} Process record, or null if not found
+         */
+        async getProcess(processId) {
+            try {
+                return await getProcessUseCase.execute(processId);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Transition a process to a new state, merging optional context updates.
+         * @param {string} processId - Process ID
+         * @param {string} newState - New state value
+         * @param {Object} [contextUpdates={}] - Context fields to merge
+         * @returns {Promise<Object>} Updated process record
+         */
+        async updateProcessState(processId, newState, contextUpdates = {}) {
+            try {
+                return await updateProcessStateUseCase.execute(
+                    processId,
+                    newState,
+                    contextUpdates
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Apply a metrics update (counters + bounded error history) to a process.
+         * @param {string} processId - Process ID
+         * @param {Object} metricsUpdate - Metrics to add (processed, success, errors, skipped, errorDetails)
+         * @returns {Promise<Object>} Updated process record
+         */
+        async updateProcessMetrics(processId, metricsUpdate) {
+            try {
+                return await updateProcessMetricsUseCase.execute(
+                    processId,
+                    metricsUpdate
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = { createProcessCommands };

package/application/commands/scheduler-commands.js

@@ -0,0 +1,263 @@
+/**
+ * Scheduler Commands
+ *
+ * Application Layer - Command pattern for scheduling operations.
+ *
+ * Follows hexagonal architecture:
+ * - Receives SchedulerServiceInterface via dependency injection
+ * - Contains business logic (validation, logging, error mapping)
+ * - Protocol-agnostic (doesn't know about HTTP/Lambda)
+ *
+ * @example
+ * const schedulerCommands = createSchedulerCommands({ integrationName: 'zoho' });
+ * await schedulerCommands.scheduleJob({
+ *     jobId: 'zoho-notif-renewal-abc123',
+ *     scheduledAt: new Date(Date.now() + 6 * 24 * 60 * 60 * 1000), // 6 days
+ *     event: 'REFRESH_WEBHOOK',
+ *     payload: { integrationId: 'abc123' },
+ *     queueUrl: process.env.ZOHO_QUEUE_URL,
+ * });
+ */
+
+const { createSchedulerService } = require('../../infrastructure/scheduler');
+
+/**
+ * Derive SQS ARN from SQS URL
+ *
+ * SQS URL format: https://sqs.{region}.amazonaws.com/{account-id}/{queue-name}
+ * SQS ARN format: arn:aws:sqs:{region}:{account-id}:{queue-name}
+ *
+ * @param {string} queueUrl - SQS queue URL
+ * @returns {string} SQS queue ARN
+ */
+function deriveArnFromQueueUrl(queueUrl) {
+    try {
+        const url = new URL(queueUrl);
+        const region = url.hostname.split('.')[1];
+        const pathParts = url.pathname.split('/').filter(Boolean);
+        const accountId = pathParts[0];
+        const queueName = pathParts[1];
+        return `arn:aws:sqs:${region}:${accountId}:${queueName}`;
+    } catch (error) {
+        throw new Error(`Invalid SQS queue URL: ${queueUrl}`);
+    }
+}
+
+const ERROR_CODE_MAP = {
+    SCHEDULER_NOT_CONFIGURED: 503,
+    INVALID_JOB_DATA: 400,
+    SCHEDULE_NOT_FOUND: 404,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return {
+        error: status,
+        reason: error?.message,
+        code: error?.code,
+    };
+}
+
+/**
+ * Create scheduler commands for an integration
+ *
+ * @param {Object} params
+ * @param {string} params.integrationName - Name of the integration (used for logging)
+ * @param {SchedulerServiceInterface} [params.schedulerService] - Optional injected scheduler service
+ * @returns {Object} Scheduler commands object
+ */
+function createSchedulerCommands({ integrationName, schedulerService }) {
+    if (!integrationName) {
+        throw new Error('integrationName is required');
+    }
+
+    // Support both dependency injection and lazy creation
+    // DI is preferred for testability, lazy creation for convenience
+    let _schedulerService = schedulerService || null;
+
+    function getSchedulerService() {
+        if (!_schedulerService) {
+            try {
+                _schedulerService = createSchedulerService();
+            } catch (error) {
+                console.warn(
+                    `[${integrationName}] Scheduler service not available: ${error.message}`
+                );
+                return null;
+            }
+        }
+        return _schedulerService;
+    }
+
+    return {
+        /**
+         * Schedule a one-time job to be executed at a specific time
+         *
+         * @param {Object} params
+         * @param {string} params.jobId - Unique identifier for the job
+         * @param {Date} params.scheduledAt - When to execute the job
+         * @param {string} params.event - Event name to trigger
+         * @param {Object} params.payload - Additional payload data
+         * @param {string} params.queueUrl - Target SQS queue URL (ARN is derived internally)
+         * @returns {Promise<{jobArn: string, scheduledAt: string} | {error: number, reason: string}>}
+         */
+        async scheduleJob({ jobId, scheduledAt, event, payload, queueUrl }) {
+            try {
+                if (!jobId) {
+                    const error = new Error('jobId is required');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                if (!scheduledAt || !(scheduledAt instanceof Date)) {
+                    const error = new Error('scheduledAt must be a valid Date');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                if (!event) {
+                    const error = new Error('event is required');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                if (!queueUrl) {
+                    const error = new Error('queueUrl is required');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                // Derive ARN from URL (business logic - transformation)
+                const queueArn = deriveArnFromQueueUrl(queueUrl);
+
+                // Get scheduler service (via DI or factory)
+                const service = getSchedulerService();
+                if (!service) {
+                    console.warn(
+                        `[${integrationName}] Scheduler not configured, skipping job schedule`
+                    );
+                    return {
+                        jobId,
+                        jobArn: null,
+                        scheduledAt: null,
+                        warning: 'Scheduler not configured',
+                    };
+                }
+
+                // Build the SQS message payload (business logic - assembly)
+                const sqsPayload = {
+                    event,
+                    integrationName,
+                    data: payload || {},
+                    scheduledAt: scheduledAt.toISOString(),
+                    createdAt: new Date().toISOString(),
+                };
+
+                // Delegate to service (Port interface)
+                const result = await service.scheduleOneTime({
+                    scheduleName: jobId,
+                    scheduleAt: scheduledAt,
+                    queueResourceId: queueArn,
+                    payload: sqsPayload,
+                });
+
+                console.log(
+                    `[${integrationName}] Scheduled job ${jobId} for ${result.scheduledAt}`
+                );
+
+                return {
+                    jobId,
+                    jobArn: result.scheduledJobId,
+                    scheduledAt: result.scheduledAt,
+                };
+            } catch (error) {
+                console.error(
+                    `[${integrationName}] Failed to schedule job ${jobId}:`,
+                    error.message
+                );
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Delete a scheduled job
+         *
+         * @param {string} jobId - Job ID to delete
+         * @returns {Promise<{success: boolean, jobId: string} | {error: number, reason: string}>}
+         */
+        async deleteJob(jobId) {
+            try {
+                if (!jobId) {
+                    const error = new Error('jobId is required');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                const service = getSchedulerService();
+                if (!service) {
+                    console.warn(
+                        `[${integrationName}] Scheduler not configured, skipping job deletion`
+                    );
+                    return {
+                        success: true,
+                        jobId,
+                        warning: 'Scheduler not configured',
+                    };
+                }
+
+                await service.deleteSchedule(jobId);
+
+                console.log(`[${integrationName}] Deleted scheduled job ${jobId}`);
+
+                return {
+                    success: true,
+                    jobId,
+                };
+            } catch (error) {
+                console.error(
+                    `[${integrationName}] Failed to delete job ${jobId}:`,
+                    error.message
+                );
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Get the status of a scheduled job
+         *
+         * @param {string} jobId - Job ID to check
+         * @returns {Promise<{exists: boolean, scheduledAt?: string, state?: string} | {error: number, reason: string}>}
+         */
+        async getJobStatus(jobId) {
+            try {
+                if (!jobId) {
+                    const error = new Error('jobId is required');
+                    error.code = 'INVALID_JOB_DATA';
+                    throw error;
+                }
+
+                const service = getSchedulerService();
+                if (!service) {
+                    return {
+                        exists: false,
+                        warning: 'Scheduler not configured',
+                    };
+                }
+
+                const status = await service.getScheduleStatus(jobId);
+
+                return status;
+            } catch (error) {
+                console.error(
+                    `[${integrationName}] Failed to get job status ${jobId}:`,
+                    error.message
+                );
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = {
+    createSchedulerCommands,
+};

package/application/commands/user-commands.js

@@ -0,0 +1,312 @@
+const {
+    createUserRepository,
+} = require('../../user/repositories/user-repository-factory');
+
+const ERROR_CODE_MAP = {
+    USER_NOT_FOUND: 404,
+    USER_ALREADY_EXISTS: 409,
+    INVALID_USER_DATA: 400,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return {
+        error: status,
+        reason: error?.message,
+        code: error?.code,
+    };
+}
+
+/**
+ * Create user command factory
+ *
+ * NOTE: This is an internal API. Integration developers should use createFriggCommands() instead.
+ *
+ * @returns {Object} User command object with CRUD operations
+ */
+function createUserCommands() {
+    const userRepository = createUserRepository();
+
+    return {
+        /**
+         * Create a new individual user
+         * @param {Object} params
+         * @param {string} params.username - Username (usually email)
+         * @param {string} [params.email] - Email address
+         * @param {string} [params.appUserId] - External application user ID
+         * @param {string} [params.password] - Password (optional)
+         * @returns {Promise<Object>} Created user object
+         */
+        async createUser({ username, email, appUserId, password } = {}) {
+            try {
+                if (!username) {
+                    const error = new Error('username is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const userData = { username };
+                if (email) userData.email = email;
+                if (appUserId) userData.appUserId = appUserId;
+                if (password) userData.password = password;
+
+                const user = await userRepository.createIndividualUser(
+                    userData
+                );
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                if (error.code === 11000) {
+                    // Duplicate key error
+                    const duplicateError = new Error(
+                        `User with username '${username}' already exists`
+                    );
+                    duplicateError.code = 'USER_ALREADY_EXISTS';
+                    return mapErrorToResponse(duplicateError);
+                }
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find a user by their application user ID
+         * @param {string} appUserId - External application user ID
+         * @returns {Promise<Object|null>} User object or null if not found
+         */
+        async findUserByAppUserId(appUserId) {
+            try {
+                if (!appUserId) {
+                    const error = new Error('appUserId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserByAppUserId(
+                    appUserId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find a user by their username
+         * @param {string} username - Username to search for
+         * @returns {Promise<Object|null>} User object or null if not found
+         */
+        async findUserByUsername(username) {
+            try {
+                if (!username) {
+                    const error = new Error('username is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserByUsername(
+                    username
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find an individual user by their ID
+         * @param {string} userId - Individual user ID to search for
+         * @returns {Promise<Object|null>} Individual user object or null if not found
+         */
+        async findIndividualUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserById(
+                    userId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user._id?.toString() || user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find all individual users linked to an organization user
+         * @param {string} organizationUserId - Organization user ID to search for
+         * @returns {Promise<Object[]>} Array of individual user objects (empty if none)
+         */
+        async findIndividualUsersByOrganizationId(organizationUserId) {
+            try {
+                if (!organizationUserId) {
+                    const error = new Error('organizationUserId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const users =
+                    await userRepository.findIndividualUsersByOrganizationId(
+                        organizationUserId
+                    );
+
+                return (users || []).map((user) => ({
+                    id: user._id?.toString() || user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                }));
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find an organization user by their ID
+         * @param {string} userId - Organization user ID to search for
+         * @returns {Promise<Object|null>} Organization user object or null if not found
+         */
+        async findOrganizationUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findOrganizationUserById(
+                    userId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    appOrgId: user.appOrgId,
+                    name: user.name,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Update a user by ID
+         * @param {string} userId - User ID to update
+         * @param {Object} updates - Fields to update
+         * @returns {Promise<Object>} Updated user object
+         */
+        async updateUser(userId, updates) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.IndividualUser.update(
+                    userId,
+                    updates
+                );
+
+                if (!user) {
+                    const error = new Error(`User ${userId} not found`);
+                    error.code = 'USER_NOT_FOUND';
+                    throw error;
+                }
+
+                return {
+                    id: user._id.toString(),
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Delete a user by ID
+         *
+         * IMPORTANT: This does NOT automatically cascade delete related records in MongoDB.
+         * Integration developers MUST manually delete related data first:
+         * 1. Delete integrations (via deleteIntegrationById)
+         * 2. Delete entities (via deleteEntityById)
+         * 3. Delete credentials (via deleteCredentialById)
+         * 4. Finally delete user (via deleteUserById)
+         *
+         * @param {string} userId - User ID to delete
+         * @returns {Promise<Object>} Deletion result
+         */
+        async deleteUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const deleted = await userRepository.deleteUser(userId);
+
+                if (!deleted) {
+                    const error = new Error(`User ${userId} not found`);
+                    error.code = 'USER_NOT_FOUND';
+                    return mapErrorToResponse(error);
+                }
+
+                return {
+                    success: true,
+                    userId,
+                    message: 'User deleted successfully',
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = {
+    createUserCommands,
+    ERROR_CODE_MAP,
+};