@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/application/commands/integration-mapping-commands.js

@@ -0,0 +1,25 @@
+const {
+    createIntegrationMappingRepository,
+} = require('../../integrations/repositories/integration-mapping-repository-factory');
+
+function mapErrorToResponse(error) {
+    return { error: 500, reason: error?.message, code: error?.code };
+}
+
+// Kept separate from integration-commands so the mapping and integration domains stay decoupled.
+function createIntegrationMappingCommands() {
+    const mappingRepository = createIntegrationMappingRepository();
+
+    return {
+        // Returns a Map of integrationId → count, or an error object on failure.
+        async countByIntegrationIds(ids = []) {
+            try {
+                return await mappingRepository.countByIntegrationIds(ids);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = { createIntegrationMappingCommands };

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/report-commands.js

@@ -0,0 +1,188 @@
+const ERROR_CODE_MAP = {
+    EXECUTION_NOT_FOUND: 404,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return { error: status, reason: error?.message, code: error?.code };
+}
+
+/**
+ * Report commands share the AdminScriptExecution store, discriminated by
+ * type:'REPORT'. That store has no user/integration FK, and findExecutionById
+ * rejects non-REPORT rows, so a report lookup can never return another
+ * operation type's record (ADR-010 Decision 3).
+ */
+function createReportCommands({ artifactRepository } = {}) {
+    const {
+        createAdminScriptExecutionRepository,
+    } = require('../../admin-scripts/repositories/admin-script-execution-repository-factory');
+
+    const executionRepository = createAdminScriptExecutionRepository();
+
+    let artifactRepo = artifactRepository || null;
+    function getArtifactRepository() {
+        if (!artifactRepo) {
+            const {
+                createArtifactRepository,
+            } = require('../../artifacts/repositories/artifact-repository-factory');
+            artifactRepo = createArtifactRepository();
+        }
+        return artifactRepo;
+    }
+
+    // Resolve to null rather than throw: a read must not fail because signing did.
+    async function signArtifact(ref) {
+        if (!ref) return null;
+        try {
+            return await getArtifactRepository().signedUrl(ref);
+        } catch (_error) {
+            return null;
+        }
+    }
+
+    return {
+        async createExecution({
+            reportName,
+            reportVersion,
+            trigger,
+            mode,
+            input,
+            audit,
+            seriesName,
+            parentExecutionId,
+        }) {
+            try {
+                return await executionRepository.createExecution({
+                    name: reportName,
+                    type: 'REPORT',
+                    parentExecutionId,
+                    context: {
+                        reportVersion,
+                        trigger,
+                        mode: mode || 'recorded',
+                        input,
+                        audit,
+                        ...(seriesName ? { seriesName } : {}),
+                    },
+                });
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        async findExecutionById(id) {
+            try {
+                const record = await executionRepository.findExecutionById(id);
+                if (!record || record.type !== 'REPORT') {
+                    const error = new Error(`Report execution ${id} not found`);
+                    error.code = 'EXECUTION_NOT_FOUND';
+                    return mapErrorToResponse(error);
+                }
+                // The stored artifact ref is not retrievable on its own; sign it on read.
+                if (record.results?.artifact) {
+                    record.results = {
+                        ...record.results,
+                        artifactUrl: await signArtifact(record.results.artifact),
+                    };
+                }
+                return record;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        // Never-throws: returns [] on error (non-critical read).
+        async listExecutionsByName(reportName, { limit, offset, state } = {}) {
+            try {
+                return await executionRepository.findExecutionsByName(
+                    reportName,
+                    { type: 'REPORT', limit, offset, state }
+                );
+            } catch (error) {
+                return [];
+            }
+        },
+
+        // No mode index in the store, so fetch by name/window and filter snapshots
+        // in JS. Never-throws: returns [] on error.
+        async findSnapshotSeries(reportName, { from, to, limit } = {}) {
+            try {
+                const rows = await executionRepository.findExecutionsByName(
+                    reportName,
+                    {
+                        type: 'REPORT',
+                        from,
+                        to,
+                        sortBy: 'createdAt',
+                        sortOrder: 'asc',
+                        limit,
+                    }
+                );
+                const snapshots = rows.filter(
+                    (row) => row.context?.mode === 'snapshot'
+                );
+                return Promise.all(
+                    snapshots.map(async (row) => ({
+                        executionId: row.id,
+                        capturedAt: row.createdAt,
+                        summary:
+                            row.results?.output?.summary ??
+                            row.results?.summary ??
+                            null,
+                        artifactUrl: await signArtifact(row.results?.artifact),
+                    }))
+                );
+            } catch (error) {
+                return [];
+            }
+        },
+
+        async updateExecutionState(id, state) {
+            try {
+                return await executionRepository.updateExecutionState(id, state);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        async appendExecutionLog(id, logEntry) {
+            try {
+                return await executionRepository.appendExecutionLog(id, logEntry);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        // results.output is the inline JSON payload; results.summary + results.artifact
+        // are a large/binary payload's summary + object-store reference.
+        async completeExecution(
+            id,
+            { state, output, summary, artifact, error, metrics, logs } = {}
+        ) {
+            try {
+                if (state) {
+                    await executionRepository.updateExecutionState(id, state);
+                }
+                const resultsUpdate = {};
+                if (output !== undefined) resultsUpdate.output = output;
+                if (summary !== undefined) resultsUpdate.summary = summary;
+                if (artifact !== undefined) resultsUpdate.artifact = artifact;
+                if (error) resultsUpdate.error = error;
+                if (metrics) resultsUpdate.metrics = metrics;
+                if (logs) resultsUpdate.logs = logs;
+                if (Object.keys(resultsUpdate).length > 0) {
+                    await executionRepository.updateExecutionResults(
+                        id,
+                        resultsUpdate
+                    );
+                }
+                return { success: true };
+            } catch (err) {
+                return mapErrorToResponse(err);
+            }
+        },
+    };
+}
+
+module.exports = { createReportCommands };

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/usage-commands.js

@@ -0,0 +1,56 @@
+// `frigg.usage.*` — the read/write surface over the durable usage store.
+const {
+    createUsageRepository,
+} = require('../../usage/repositories/usage-repository-factory');
+const { computeUsageWindows } = require('../../usage/usage-windows');
+const { resolveNorthStarEntry } = require('../../telemetry/north-star');
+
+function createUsageCommands({ usageRepository } = {}) {
+    const repository = usageRepository || createUsageRepository();
+
+    return {
+        // Increments both the day and hour window rows for `at`.
+        async recordUsageCounter({
+            integrationId,
+            integrationType,
+            metric,
+            value = 1,
+            at = new Date(),
+        }) {
+            const windows = computeUsageWindows(at);
+            for (const window of windows) {
+                await repository.increment({
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                    value,
+                });
+            }
+        },
+
+        async getTotalsByDimension(args) {
+            return repository.getTotalsByDimension(args);
+        },
+
+        async getTimeSeries(args) {
+            return repository.getTimeSeries(args);
+        },
+
+        // Caller supplies the North Star config (Definition.telemetry.northStar);
+        // resolves the counter for the type (byType > default), null if none.
+        async getNorthStarTotals({ northStar, integrationType, since, groupBy = 'integrationType', bucket } = {}) {
+            const entry = resolveNorthStarEntry(northStar, integrationType);
+            if (!entry) return null;
+            const totals = await repository.getTotalsByDimension({
+                metric: entry.name,
+                groupBy,
+                since,
+                bucket,
+            });
+            return { metric: entry.name, totals };
+        },
+    };
+}
+
+module.exports = { createUsageCommands };