@friggframework/core 2.0.0-next.92 → 2.0.0-next.93

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/index.js

@@ -7,6 +7,9 @@ const { createEntityCommands } = require('./commands/entity-commands');
 const {
     createCredentialCommands,
 } = require('./commands/credential-commands');
+const {
+    createProcessCommands,
+} = require('./commands/process-commands');
 const {
     createSchedulerCommands,
 } = require('./commands/scheduler-commands');
@@ -36,6 +39,8 @@ function createFriggCommands({ integrationClass }) {
 
     const credentialCommands = createCredentialCommands();
 
+    const processCommands = createProcessCommands();
+
     return {
         // Integration commands
         ...integrationCommands,
@@ -48,6 +53,9 @@ function createFriggCommands({ integrationClass }) {
 
         // Credential commands
         ...credentialCommands,
+
+        // Process commands
+        ...processCommands,
     };
 }
 
@@ -60,6 +68,7 @@ module.exports = {
     createUserCommands,
     createEntityCommands,
     createCredentialCommands,
+    createProcessCommands,
     createSchedulerCommands,
 
     // Legacy standalone function

package/index.js

@@ -146,6 +146,7 @@ module.exports = {
     createUserCommands: application.createUserCommands,
     createEntityCommands: application.createEntityCommands,
     createCredentialCommands: application.createCredentialCommands,
+    createProcessCommands: application.createProcessCommands,
     createSchedulerCommands: application.createSchedulerCommands,
     findIntegrationContextByExternalEntityId:
         application.findIntegrationContextByExternalEntityId,

package/integrations/use-cases/create-process.js

@@ -22,6 +22,8 @@
  *   results: { aggregateData: { totalSynced: 0, totalFailed: 0 } }
  * });
  */
+const { invalidProcessData } = require('./process-errors');
+
 class CreateProcess {
     /**
      * @param {Object} params
@@ -86,40 +88,40 @@ class CreateProcess {
         const missingFields = requiredFields.filter(field => !processData[field]);
 
         if (missingFields.length > 0) {
-            throw new Error(
+            throw invalidProcessData(
                 `Missing required fields for process creation: ${missingFields.join(', ')}`
             );
         }
 
         // Validate field types
         if (typeof processData.userId !== 'string') {
-            throw new Error('userId must be a string');
+            throw invalidProcessData('userId must be a string');
         }
         if (typeof processData.integrationId !== 'string') {
-            throw new Error('integrationId must be a string');
+            throw invalidProcessData('integrationId must be a string');
         }
         if (typeof processData.name !== 'string') {
-            throw new Error('name must be a string');
+            throw invalidProcessData('name must be a string');
         }
         if (typeof processData.type !== 'string') {
-            throw new Error('type must be a string');
+            throw invalidProcessData('type must be a string');
         }
 
         // Validate optional fields if provided
         if (processData.state && typeof processData.state !== 'string') {
-            throw new Error('state must be a string');
+            throw invalidProcessData('state must be a string');
         }
         if (processData.context && typeof processData.context !== 'object') {
-            throw new Error('context must be an object');
+            throw invalidProcessData('context must be an object');
         }
         if (processData.results && typeof processData.results !== 'object') {
-            throw new Error('results must be an object');
+            throw invalidProcessData('results must be an object');
         }
         if (processData.childProcesses && !Array.isArray(processData.childProcesses)) {
-            throw new Error('childProcesses must be an array');
+            throw invalidProcessData('childProcesses must be an array');
         }
         if (processData.parentProcessId && typeof processData.parentProcessId !== 'string') {
-            throw new Error('parentProcessId must be a string');
+            throw invalidProcessData('parentProcessId must be a string');
         }
     }
 }

package/integrations/use-cases/get-process.js

@@ -15,6 +15,8 @@
  * // or
  * const process = await getProcess.executeOrThrow(processId);
  */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
 class GetProcess {
     /**
      * @param {Object} params
@@ -36,7 +38,7 @@ class GetProcess {
     async execute(processId) {
         // Validate input
         if (!processId || typeof processId !== 'string') {
-            throw new Error('processId must be a non-empty string');
+            throw invalidProcessData('processId must be a non-empty string');
         }
 
         // Delegate to repository
@@ -58,7 +60,7 @@ class GetProcess {
         const process = await this.execute(processId);
 
         if (!process) {
-            throw new Error(`Process not found: ${processId}`);
+            throw processNotFound(`Process not found: ${processId}`);
         }
 
         return process;
@@ -71,7 +73,7 @@ class GetProcess {
      */
     async executeMany(processIds) {
         if (!Array.isArray(processIds)) {
-            throw new Error('processIds must be an array');
+            throw invalidProcessData('processIds must be an array');
         }
 
         const processes = await Promise.all(

package/integrations/use-cases/process-errors.js

@@ -0,0 +1,28 @@
+/**
+ * Process Error Helpers
+ *
+ * Constructs Errors carrying a stable `code` so the application layer
+ * (`createProcessCommands` → `mapErrorToResponse`) can translate domain
+ * failures into HTTP statuses:
+ *   - INVALID_PROCESS_DATA → 400 (caller-supplied data is invalid)
+ *   - PROCESS_NOT_FOUND    → 404 (the referenced process does not exist)
+ *
+ * Repository/infrastructure failures are intentionally left uncoded so
+ * they surface as 500s.
+ */
+
+function createCodedError(message, code) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+
+function invalidProcessData(message) {
+    return createCodedError(message, 'INVALID_PROCESS_DATA');
+}
+
+function processNotFound(message) {
+    return createCodedError(message, 'PROCESS_NOT_FOUND');
+}
+
+module.exports = { invalidProcessData, processNotFound };

package/integrations/use-cases/update-process-metrics.js

@@ -34,6 +34,8 @@
  *   errorDetails: [{ contactId: 'abc', error: 'Missing email', timestamp: '...' }]
  * });
  */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
 class UpdateProcessMetrics {
     /**
      * @param {Object} params
@@ -66,10 +68,10 @@ class UpdateProcessMetrics {
      */
     async execute(processId, metricsUpdate) {
         if (!processId || typeof processId !== 'string') {
-            throw new Error('processId must be a non-empty string');
+            throw invalidProcessData('processId must be a non-empty string');
         }
         if (!metricsUpdate || typeof metricsUpdate !== 'object') {
-            throw new Error('metricsUpdate must be an object');
+            throw invalidProcessData('metricsUpdate must be an object');
         }
 
         // Phase 1: atomic increments + bounded error history.
@@ -119,7 +121,7 @@ class UpdateProcessMetrics {
         }
 
         if (!updatedProcess) {
-            throw new Error(`Process not found: ${processId}`);
+            throw processNotFound(`Process not found: ${processId}`);
         }
 
         // Phase 2: derived metrics (non-atomic, best-effort). Preserved

package/integrations/use-cases/update-process-state.js

@@ -22,6 +22,8 @@
  *   pagination: { pageSize: 100 }
  * });
  */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
 class UpdateProcessState {
     /**
      * @param {Object} params
@@ -45,13 +47,13 @@ class UpdateProcessState {
     async execute(processId, newState, contextUpdates = {}) {
         // Validate inputs
         if (!processId || typeof processId !== 'string') {
-            throw new Error('processId must be a non-empty string');
+            throw invalidProcessData('processId must be a non-empty string');
         }
         if (!newState || typeof newState !== 'string') {
-            throw new Error('newState must be a non-empty string');
+            throw invalidProcessData('newState must be a non-empty string');
         }
         if (contextUpdates && typeof contextUpdates !== 'object') {
-            throw new Error('contextUpdates must be an object');
+            throw invalidProcessData('contextUpdates must be an object');
         }
 
         // Route through the atomic path when the repo supports it AND we
@@ -82,10 +84,13 @@ class UpdateProcessState {
                     { set, newState }
                 );
                 if (!updated) {
-                    throw new Error(`Process not found: ${processId}`);
+                    throw processNotFound(`Process not found: ${processId}`);
                 }
                 return updated;
             } catch (error) {
+                if (error.code === 'PROCESS_NOT_FOUND') {
+                    throw error;
+                }
                 throw new Error(
                     `Failed to update process state: ${error.message}`
                 );
@@ -100,7 +105,7 @@ class UpdateProcessState {
         try {
             const process = await this.processRepository.findById(processId);
             if (!process) {
-                throw new Error(`Process not found: ${processId}`);
+                throw processNotFound(`Process not found: ${processId}`);
             }
 
             const updates = { state: newState };
@@ -114,7 +119,7 @@ class UpdateProcessState {
             return await this.processRepository.update(processId, updates);
         } catch (error) {
             // Re-throw "Process not found" as-is; wrap other errors.
-            if (error.message && error.message.startsWith('Process not found')) {
+            if (error.code === 'PROCESS_NOT_FOUND') {
                 throw error;
             }
             throw new Error(`Failed to update process state: ${error.message}`);
@@ -140,7 +145,7 @@ class UpdateProcessState {
     async updateContextOnly(processId, contextUpdates) {
         const process = await this.processRepository.findById(processId);
         if (!process) {
-            throw new Error(`Process not found: ${processId}`);
+            throw processNotFound(`Process not found: ${processId}`);
         }
 
         const updates = {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.92",
+    "version": "2.0.0-next.93",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.92",
-        "@friggframework/prettier-config": "2.0.0-next.92",
-        "@friggframework/test": "2.0.0-next.92",
+        "@friggframework/eslint-config": "2.0.0-next.93",
+        "@friggframework/prettier-config": "2.0.0-next.93",
+        "@friggframework/test": "2.0.0-next.93",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "25cf5cf934fa2b7e16a32b49dad50edc2b557136"
+    "gitHead": "abfd168927bbd6f1620ccbeb0a61225e19ce1a28"
 }