@modelriver/cli 1.2.3 → 1.2.5

package/README.md

@@ -30,9 +30,10 @@ modelriver login
 
 You'll be prompted for:
 1. **API Key**: Your ModelRiver API key (starts with `mr_live_` or `mr_test_`)
-2. **Forward URL**: Where to forward webhooks (e.g., `http://localhost:4000`)
+2. **Forward URL**: Where to forward webhooks on your machine (e.g., `http://localhost:3001/webhook/modelriver`)
 
-The URL will be automatically normalized to include `/webhook/modelriver`.
+This is your local webhook receiver (CLI default port **3001**), not the ModelRiver API port (**4000**).
+The URL will be automatically normalized to include `/webhook/modelriver` if needed.
 
 ### Step 2: Start Forwarding
 
@@ -54,6 +55,7 @@ For convenience, the CLI supports short aliases:
 | `forward` | `f` | Forward using saved config |
 | `trigger` | `t` | Send async request |
 | `websocket` | `ws` | Test WebSocket connection |
+| `callback` | - | Complete event-driven callback |
 | `test-webhook` | - | Test webhook delivery end-to-end |
 
 Example:
@@ -90,7 +92,7 @@ Create a config file at `~/.modelriver/config.json` or `.modelriverrc` in your p
 {
   "api_key": "mr_live_YOUR_API_KEY",
   "api_url": "https://api.modelriver.com",
-  "forward_url": "http://localhost:4000/webhook/modelriver"
+  "forward_url": "http://localhost:3001/webhook/modelriver"
 }
 ```
 
@@ -113,14 +115,14 @@ ModelRiver CLI Login
 Configure your ModelRiver CLI credentials.
 
 Enter your ModelRiver API key: mr_live_abc123...
-Enter your webhook forward URL (e.g. http://localhost:4000/webhook/modelriver): http://localhost:4000
+Enter your webhook forward URL (e.g. http://localhost:3001/webhook/modelriver): http://localhost:3001/webhook/modelriver
 
 ✓ Configuration saved!
 
 Saved Configuration
 ───────────────────
 ✓ API Key: mr_live_abc123...
-✓ Forward URL: http://localhost:4000/webhook/modelriver
+✓ Forward URL: http://localhost:3001/webhook/modelriver
 ```
 
 ### `modelriver forward` - Quick Webhook Forwarding
@@ -183,6 +185,38 @@ modelriver listen --port 3002 --forward --print
   Data: {"result": "..."}
 ```
 
+**Event-driven example:**
+```
+[timestamp] Webhook received via WebSocket:
+  Channel ID: abc-123-def
+  Status: ai_generated (callback required)
+  Type: task.ai_generated
+  Event: schema_result_ready
+  Callback URL: https://api.modelriver.com/v1/callback/abc-123-def
+  Customer data: { "ticket_id": "TCK-10042" }
+  AI response: { ... }
+
+> Event-driven webhook — complete the flow with a callback:
+>   modelriver callback --channel-id abc-123-def --data '{"summary":"..."}'
+```
+
+### `modelriver callback` - Complete Event-driven Flows
+
+After `listen` receives a `task.ai_generated` webhook, complete the flow:
+
+```bash
+# Using channel ID
+modelriver callback \
+  --channel-id abc-123-def \
+  --data '{"summary":"Escalated to auth","priority":"high"}' \
+  --task-id TCK-10042
+
+# Using full callback URL from the webhook
+modelriver callback \
+  --callback-url "https://api.modelriver.com/v1/callback/abc-123-def" \
+  --data '{"summary":"Escalated to auth"}'
+```
+
 ### `modelriver websocket` - Test WebSocket Connection
 
 Test WebSocket connections to production and receive real-time responses.
@@ -231,8 +265,8 @@ Send a test async request and get channel details.
 # Basic trigger
 modelriver trigger --workflow my-workflow --message "Test message"
 
-# With custom payload
-modelriver trigger --workflow my-workflow --payload '{"messages": [...]}'
+# With custom payload (workflow can be in --payload or via --workflow)
+modelriver trigger --workflow my-workflow --payload '{"messages": [...], "metadata": {"ticket_id":"TCK-1"}}'
 
 # Create webhook to receive response
 modelriver trigger --workflow my-workflow --message "Test" --webhook-url https://webhook.site/your-id
@@ -241,6 +275,17 @@ modelriver trigger --workflow my-workflow --message "Test" --webhook-url https:/
 modelriver trigger --workflow my-workflow --message "Test" --print-channel
 ```
 
+For **event-driven** workflows, after triggering:
+
+```bash
+# Terminal 1
+modelriver listen --print
+
+# Terminal 2
+modelriver trigger --workflow my-event-workflow --message "Test" --print-channel
+modelriver callback --channel-id CHANNEL_ID --data '{"enriched":true}'
+```
+
 **Example Output:**
 ```
 ✓ Async request created
@@ -344,6 +389,23 @@ export MODELRIVER_API_KEY=mr_live_YOUR_KEY
 modelriver trigger --workflow my-workflow --message "Test" --print-channel
 ```
 
+### Example 4: Event-driven Workflow End-to-End
+
+```bash
+# Terminal 1: Listen for webhooks
+export MODELRIVER_API_KEY=mr_live_YOUR_KEY
+modelriver listen --print
+
+# Terminal 2: Trigger + callback
+modelriver trigger \
+  --workflow my-event-workflow \
+  --payload '{"messages":[{"role":"user","content":"Test"}],"metadata":{"ticket_id":"TCK-1"}}' \
+  --print-channel
+
+# After Terminal 1 shows task.ai_generated:
+modelriver callback --channel-id CHANNEL_ID --data '{"summary":"Done"}'
+```
+
 ## Webhook Payload Format
 
 Webhooks are sent as HTTP POST requests with the following format:
@@ -410,6 +472,7 @@ The CLI uses these ModelRiver API endpoints:
 - `POST /v1/webhooks` - Create a new webhook
 - `DELETE /v1/webhooks/:id` - Delete a webhook
 - `POST /v1/cli/connect` - Connect CLI and get WebSocket token
+- `POST /v1/callback/:channel_id` - Complete event-driven callback
 
 **Development** (localhost or custom API URL):
 - Same endpoints but with `/api/v1` prefix instead of `/v1`
@@ -429,6 +492,7 @@ Tests cover critical components including:
 - Configuration loading
 - API client validation
 - Output formatting
+- Event-driven webhook payload helpers
 
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelriver/cli",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "ModelRiver CLI for testing webhooks and WebSockets from production",
   "main": "src/index.js",
   "bin": {
@@ -47,6 +47,8 @@
   "files": [
     "bin/",
     "src/",
-    "README.md"
+    "README.md",
+    "!src/**/*.test.js",
+    "!**/*.test.js"
   ]
 }

package/src/commands/callback.js

@@ -0,0 +1,81 @@
+const ApiClient = require('../lib/api-client');
+const Logger = require('../utils/logger');
+const Formatter = require('../utils/formatter');
+
+async function callbackCommand(options) {
+  const {
+    channelId,
+    callbackUrl,
+    data,
+    taskId,
+    metadata,
+    payload,
+    apiKey,
+    apiUrl,
+  } = options;
+
+  if (!callbackUrl && !channelId) {
+    Logger.error('Error: --channel-id or --callback-url is required');
+    process.exit(1);
+  }
+
+  let body;
+
+  try {
+    if (payload) {
+      body = JSON.parse(payload);
+    } else {
+      body = {};
+
+      if (data) {
+        body.data = typeof data === 'string' ? JSON.parse(data) : data;
+      }
+
+      if (taskId) {
+        body.task_id = taskId;
+      }
+
+      if (metadata) {
+        body.metadata =
+          typeof metadata === 'string' ? JSON.parse(metadata) : metadata;
+      }
+    }
+  } catch (error) {
+    Logger.error(`Invalid JSON: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (body.data !== undefined && (typeof body.data !== 'object' || Array.isArray(body.data))) {
+    Logger.error('Error: "data" must be a JSON object');
+    process.exit(1);
+  }
+
+  try {
+    const apiClient = new ApiClient(apiKey, apiUrl);
+    const targetUrl =
+      callbackUrl ||
+      `${apiClient.apiUrl}${apiClient.apiPath}/callback/${channelId}`;
+
+    const spinner = Logger.spinner(`Sending callback to ${targetUrl}...`);
+    spinner.start();
+
+    const response = await apiClient.sendCallback(targetUrl, body);
+
+    if (response.status >= 400) {
+      spinner.fail('Callback failed');
+      Logger.error(response.data?.error || response.data?.message || `HTTP ${response.status}`);
+      if (response.data) {
+        console.log(Formatter.json(response.data));
+      }
+      process.exit(1);
+    }
+
+    spinner.succeed('Callback accepted');
+    console.log(Formatter.json(response.data));
+  } catch (error) {
+    Logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { callbackCommand };

package/src/commands/listen.js

@@ -5,6 +5,10 @@ const WebhookVerifier = require('../lib/webhook-verifier');
 const Logger = require('../utils/logger');
 const Formatter = require('../utils/formatter');
 const { parseForwardUrl } = require('../utils/url-helpers');
+const {
+  printWebhookDetails,
+  resolveCallbackUrl,
+} = require('../utils/webhook-payload');
 
 async function listenCommand(options) {
   let { apiKey, apiUrl, print, port, verbose, forward, forwardUrl } = options;
@@ -68,7 +72,7 @@ async function listenCommand(options) {
 
     // Debug: Show API key info if verbose
     if (verbose) {
-      Logger.info(`> API URL: ${apiUrl}`);
+      Logger.info(`> API URL: ${apiClient.apiUrl}`);
       Logger.info(`> API Path: ${apiClient.apiPath}`);
       Logger.info(`> API Key (first 30 chars): ${apiKey.substring(0, 30)}...`);
     }
@@ -152,20 +156,27 @@ async function listenCommand(options) {
           );
         }
 
-        if (print) {
-          const timestampStr = Formatter.timestamp(new Date());
-          Logger.log(`\n[${timestampStr}] Webhook received:`);
-          Logger.log(`  Channel ID: ${channel_id || 'N/A'}`);
-          Logger.log(`  Status: ${data?.status || 'N/A'}`);
-          if (isValid !== null) {
-            Logger.log(`  Signature: ${isValid ? '✓ Valid' : '✗ Invalid'}`);
-          }
-          if (data?.data) {
-            Logger.log(`  Data: ${Formatter.json(data.data)}`);
-          }
-          if (data?.meta) {
-            Logger.log(`  Meta: ${Formatter.json(data.meta)}`);
-          }
+        // Skip printing when this request came from our own WebSocket forwarder
+        // (already printed in the WebSocket handler). Still print external POSTs.
+        const isInternalForward = req.headers['x-modelriver-cli-internal'] === '1';
+        if (print && !isInternalForward) {
+          printWebhookDetails(
+            {
+              channel_id,
+              data,
+              callback_url: req.body.callback_url || resolveCallbackUrl(req.body),
+            },
+            {
+              Logger,
+              Formatter,
+              WebhookVerifier,
+              webhookSecret,
+              signature,
+              timestamp: payloadTimestamp || timestamp,
+              apiKey,
+              label: 'Webhook received (local server)',
+            }
+          );
         }
 
         // Always return 200 to acknowledge receipt
@@ -175,6 +186,25 @@ async function listenCommand(options) {
       server = app.listen(localPort, 'localhost', () => {
         Logger.success(`> Local server listening on http://localhost:${localPort}/webhook`);
       });
+
+      server.on('error', (error) => {
+        if (error.code === 'EADDRINUSE') {
+          spinner.fail(`Port ${localPort} is already in use`);
+          Logger.error(`Another process is listening on port ${localPort}.`);
+          Logger.warning(`> Use a different port: modelriver listen --print --port ${Number(localPort) + 1}`);
+          Logger.warning('> Or stop the other process and try again');
+          if (wsClient) {
+            wsClient.close();
+          }
+          process.exit(1);
+        }
+
+        Logger.error(`Local server error: ${error.message}`);
+        if (wsClient) {
+          wsClient.close();
+        }
+        process.exit(1);
+      });
     } else {
       Logger.success(`> Forwarding webhooks to http://localhost:${localPort}/webhook`);
     }
@@ -184,25 +214,16 @@ async function listenCommand(options) {
       const { channel_id, timestamp, data, signature } = webhookPayload;
 
       if (print) {
-        const timestampStr = Formatter.timestamp(new Date());
-        Logger.log(`\n[${timestampStr}] Webhook received via WebSocket:`);
-        Logger.log(`  Channel ID: ${channel_id || 'N/A'}`);
-        Logger.log(`  Status: ${data?.status || 'N/A'}`);
-        if (signature && webhookSecret) {
-          const isValid = WebhookVerifier.verify(
-            signature,
-            data,
-            webhookSecret,
-            timestamp.toString()
-          );
-          Logger.log(`  Signature: ${isValid ? '✓ Valid' : '✗ Invalid'}`);
-        }
-        if (data?.data) {
-          Logger.log(`  Data: ${Formatter.json(data.data)}`);
-        }
-        if (data?.meta) {
-          Logger.log(`  Meta: ${Formatter.json(data.meta)}`);
-        }
+        printWebhookDetails(webhookPayload, {
+          Logger,
+          Formatter,
+          WebhookVerifier,
+          webhookSecret,
+          signature,
+          timestamp,
+          apiKey,
+          label: 'Webhook received via WebSocket',
+        });
       }
 
       // Forward to local server
@@ -211,7 +232,8 @@ async function listenCommand(options) {
       const postData = JSON.stringify({
         channel_id,
         timestamp,
-        data
+        callback_url: resolveCallbackUrl(webhookPayload),
+        data,
       });
 
       // Parse the forward URL or use localhost defaults
@@ -232,7 +254,8 @@ async function listenCommand(options) {
           'Content-Length': Buffer.byteLength(postData),
           'X-ModelRiver-Signature': signature || '',
           'X-ModelRiver-Timestamp': timestamp.toString(),
-          'X-ModelRiver-Webhook-Id': webhookPayload.webhook_id || ''
+          'X-ModelRiver-Webhook-Id': webhookPayload.webhook_id || '',
+          'X-ModelRiver-CLI-Internal': '1',
         }
       };
 

package/src/commands/login.js

@@ -114,10 +114,11 @@ async function loginCommand(options) {
         }
 
         // Prompt for forward URL
-        const defaultForwardUrl = currentForwardUrl || 'http://localhost:4000';
+        // Default to the CLI local receiver port (3001), not ModelRiver API (4000).
+        const defaultForwardUrl = currentForwardUrl || 'http://localhost:3001/webhook/modelriver';
         let forwardUrl = await prompt(
             rl,
-            'Enter your webhook forward URL (e.g. http://localhost:4000/webhook/modelriver)',
+            'Enter your webhook forward URL (e.g. http://localhost:3001/webhook/modelriver)',
             defaultForwardUrl,
             false, // maskDefault
             false  // showDefault - Hide the (http://...) bracket as requested

package/src/commands/trigger.js

@@ -23,6 +23,17 @@ async function triggerCommand(options) {
           messages: [{ role: 'user', content: message || 'Test from CLI' }]
         };
 
+    // Allow --workflow with --payload when payload omits workflow
+    if (workflow && !requestPayload.workflow) {
+      requestPayload.workflow = workflow;
+    }
+
+    if (!requestPayload.workflow) {
+      spinner.fail('Workflow required');
+      Logger.error('Provide --workflow or include "workflow" in --payload JSON');
+      process.exit(1);
+    }
+
     const response = await apiClient.createAsyncRequest(requestPayload);
 
     spinner.succeed('Async request created');
@@ -61,6 +72,7 @@ async function triggerCommand(options) {
     } else {
       Logger.info('\n> Use --webhook-url to automatically receive responses via webhook');
       Logger.info('> Or use "modelriver websocket" to connect and receive responses');
+      Logger.info('> For event-driven workflows, complete with: modelriver callback --channel-id <id> --data \'{...}\'');
     }
 
   } catch (error) {

package/src/commands/websocket.js

@@ -3,6 +3,11 @@ const WebSocketClient = require('../lib/websocket-client');
 const config = require('../lib/config');
 const Logger = require('../utils/logger');
 const Formatter = require('../utils/formatter');
+const {
+  buildCallbackHint,
+  isFinalWebSocketStatus,
+  isIntermediateWebSocketStatus,
+} = require('../utils/webhook-payload');
 
 /**
  * Normalize WebSocket URL for production environments
@@ -74,9 +79,20 @@ async function websocketCommand(options) {
             messages: [{ role: 'user', content: message || 'Test from CLI' }]
           };
 
+        // Allow --workflow with --payload when payload omits workflow
+        if (workflow && !requestPayload.workflow) {
+          requestPayload.workflow = workflow;
+        }
+
+        if (!requestPayload.workflow) {
+          spinner.fail('Workflow required');
+          Logger.error('Provide --workflow or include "workflow" in --payload JSON');
+          process.exit(1);
+        }
+
         if (verbose) {
           Logger.info(`\n> API URL: ${apiClient.apiUrl}`);
-          Logger.info(`> Workflow: ${workflow}`);
+          Logger.info(`> Workflow: ${requestPayload.workflow}`);
           Logger.info(`> Payload: ${JSON.stringify(requestPayload, null, 2)}`);
         }
 
@@ -194,21 +210,59 @@ async function websocketCommand(options) {
 
       // Set up response listener BEFORE waiting (to catch responses that arrive quickly)
       let responseReceived = false;
+      let sawIntermediateEvent = false;
 
       // Timeout after 5 minutes
       const timeoutId = setTimeout(() => {
         if (!responseReceived) {
           Logger.error('\n❌ Timeout: No response received after 5 minutes');
-          Logger.error('   Possible causes:');
-          Logger.error('   1. Workflow is still processing (try waiting longer)');
-          Logger.error('   2. Workflow failed on the server (check server logs)');
-          Logger.error('   3. Server did not broadcast the response');
+          if (sawIntermediateEvent) {
+            Logger.error('   Event-driven flow is waiting for a backend callback.');
+            Logger.error(`   Complete it with: modelriver callback --channel-id ${channelIdToUse} --data '{"summary":"..."}'`);
+          } else {
+            Logger.error('   Possible causes:');
+            Logger.error('   1. Workflow is still processing (try waiting longer)');
+            Logger.error('   2. Workflow failed on the server (check server logs)');
+            Logger.error('   3. Server did not broadcast the response');
+          }
           wsClient.close();
           process.exit(1);
         }
       }, 5 * 60 * 1000);
 
       wsClient.onResponse((payload) => {
+        const status = payload?.status;
+
+        if (isIntermediateWebSocketStatus(status)) {
+          sawIntermediateEvent = true;
+          Logger.warning(`\n⏳ Event-driven update (${status})`);
+          Logger.info(`> Channel ID: ${payload.channel_id || channelIdToUse}`);
+          if (payload.event_name) {
+            Logger.info(`> Event: ${payload.event_name}`);
+          }
+          if (payload.message) {
+            Logger.info(`> Message: ${payload.message}`);
+          }
+
+          const callbackUrl = `${apiClient.apiUrl}${apiClient.apiPath}/callback/${channelIdToUse}`;
+          const hint = buildCallbackHint(callbackUrl, channelIdToUse, apiClient.apiKey);
+          if (hint) {
+            Logger.warning(`\n${hint}\n`);
+          }
+
+          if (verbose) {
+            Logger.info(`Intermediate payload: ${Formatter.json(payload)}`);
+          }
+          return;
+        }
+
+        if (!isFinalWebSocketStatus(status) && status) {
+          if (verbose) {
+            Logger.info(`Received non-final status "${status}", waiting for completion...`);
+          }
+          return;
+        }
+
         responseReceived = true;
         clearTimeout(timeoutId);
         Logger.success('\n✅ Response received:\n');

package/src/index.js

@@ -6,6 +6,7 @@ const { listenCommand } = require('./commands/listen');
 const { forwardCommand } = require('./commands/forward');
 const { websocketCommand } = require('./commands/websocket');
 const { triggerCommand } = require('./commands/trigger');
+const { callbackCommand } = require('./commands/callback');
 const { testWebhookCommand } = require('./commands/test-webhook');
 const { listWebhooks, verifyWebhook } = require('./commands/webhook');
 const config = require('./lib/config');
@@ -48,7 +49,7 @@ program
     listenCommand({
       ...options,
       apiKey: options.apiKey || program.opts().apiKey,
-      apiUrl: options.apiUrl || program.opts().apiUrl
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
     });
   });
 
@@ -77,11 +78,29 @@ program
     websocketCommand({
       ...options,
       apiKey: options.apiKey || program.opts().apiKey,
-      apiUrl: options.apiUrl || program.opts().apiUrl,
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
       projectId: options.projectId || program.opts().projectId
     });
   });
 
+// Callback command - complete event-driven flows
+program
+  .command('callback')
+  .description('Send an event-driven callback to complete a pending channel')
+  .option('-c, --channel-id <id>', 'Channel ID from trigger/listen output')
+  .option('--callback-url <url>', 'Full callback URL from webhook payload')
+  .option('-d, --data <json>', 'Callback data object JSON')
+  .option('-P, --payload <json>', 'Full callback payload JSON')
+  .option('--task-id <id>', 'Optional task ID')
+  .option('--metadata <json>', 'Optional metadata object JSON')
+  .action((options) => {
+    callbackCommand({
+      ...options,
+      apiKey: options.apiKey || program.opts().apiKey,
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
+    });
+  });
+
 // Test Webhook command
 program
   .command('test-webhook')
@@ -97,7 +116,7 @@ program
     testWebhookCommand({
       ...options,
       apiKey: options.apiKey || program.opts().apiKey,
-      apiUrl: options.apiUrl || program.opts().apiUrl
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
     });
   });
 
@@ -115,7 +134,7 @@ program
     triggerCommand({
       ...options,
       apiKey: options.apiKey || program.opts().apiKey,
-      apiUrl: options.apiUrl || program.opts().apiUrl
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl()
     });
   });
 
@@ -132,7 +151,7 @@ webhookCmd
     listWebhooks({
       ...options,
       apiKey: options.apiKey || program.opts().apiKey,
-      apiUrl: options.apiUrl || program.opts().apiUrl
+      apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
     });
   });
 

package/src/lib/api-client.js

@@ -1,6 +1,13 @@
 const axios = require('axios');
 const config = require('./config');
 
+function createAuthHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  };
+}
+
 class ApiClient {
   constructor(apiKey = null, apiUrl = null) {
     this.apiKey = apiKey || config.getApiKey();
@@ -166,6 +173,21 @@ class ApiClient {
       }
     }
   }
+
+  /**
+   * Send an event-driven callback to complete a pending channel.
+   * @param {string} callbackUrl - Full callback URL from webhook payload
+   * @param {object} body - Callback payload { data?, task_id?, metadata? }
+   * @returns {Promise<object>} - Axios-like response { status, data }
+   */
+  async sendCallback(callbackUrl, body) {
+    const response = await axios.post(callbackUrl, body, {
+      headers: createAuthHeaders(this.apiKey),
+      validateStatus: (status) => status < 500,
+    });
+
+    return response;
+  }
 }
 
 module.exports = ApiClient;

package/src/lib/websocket-client.js

@@ -88,7 +88,7 @@ class WebSocketClient {
       }
 
       const joinRef = '1';
-
+      
       const joinMsg = JSON.stringify({
         topic: channelName,
         event: 'phx_join',
@@ -110,7 +110,7 @@ class WebSocketClient {
             resolved = true;
             // Remove this listener - handleMessage() will continue processing other messages
             this.ws.removeListener('message', handleJoinResponse);
-
+            
             if (msg.payload.status === 'ok') {
               this.channel = channelName;
               resolve(msg.payload);
@@ -126,7 +126,7 @@ class WebSocketClient {
       // Add listener for join response
       // The handleMessage() listener in connect() will also be called, but won't match
       this.ws.on('message', handleJoinResponse);
-
+      
       this.ws.send(joinMsg);
 
       // Timeout after 10 seconds

package/src/utils/webhook-payload.js

@@ -0,0 +1,160 @@
+/**
+ * Helpers for standard vs event-driven webhook payloads.
+ */
+
+function isEventDrivenWebhook(data) {
+  return Boolean(data && data.type === 'task.ai_generated');
+}
+
+function resolveCallbackUrl(webhookPayload) {
+  if (!webhookPayload) {
+    return null;
+  }
+
+  const { data, callback_url: topLevelCallbackUrl } = webhookPayload;
+
+  return topLevelCallbackUrl || data?.callback_url || null;
+}
+
+function getWebhookStatusLabel(data) {
+  if (!data) {
+    return 'N/A';
+  }
+
+  if (isEventDrivenWebhook(data)) {
+    return 'ai_generated (callback required)';
+  }
+
+  return data.status || 'N/A';
+}
+
+function getCustomerData(data) {
+  if (!data || typeof data !== 'object') {
+    return null;
+  }
+
+  const customerData = data.customer_data || data.ai_response?.customer_data;
+  if (!customerData || typeof customerData !== 'object') {
+    return null;
+  }
+
+  return Object.keys(customerData).length > 0 ? customerData : null;
+}
+
+function buildCallbackHint(callbackUrl, channelId, apiKey) {
+  if (!callbackUrl && !channelId) {
+    return null;
+  }
+
+  const keyHint = apiKey
+    ? `${apiKey.substring(0, 12)}...`
+    : '$MODELRIVER_API_KEY';
+
+  const lines = [
+    '> Event-driven webhook — complete the flow with a callback:',
+  ];
+
+  if (channelId) {
+    lines.push(
+      `>   modelriver callback --channel-id ${channelId} --data '{"summary":"..."}'`
+    );
+  }
+
+  if (callbackUrl) {
+    if (channelId) {
+      lines.push('> Or:');
+    }
+    lines.push(
+      `>   modelriver callback --callback-url "${callbackUrl}" --data '{"summary":"..."}'`
+    );
+    lines.push(
+      `>   curl -X POST "${callbackUrl}" \\`,
+      `>     -H "Authorization: Bearer ${keyHint}" \\`,
+      `>     -H "Content-Type: application/json" \\`,
+      `>     -d '{"data":{"enriched":true},"task_id":"your-task-id"}'`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function printWebhookDetails(webhookPayload, options = {}) {
+  const {
+    Logger,
+    Formatter,
+    WebhookVerifier,
+    webhookSecret,
+    signature,
+    timestamp,
+    apiKey,
+    label = 'Webhook received',
+  } = options;
+
+  const { channel_id, data } = webhookPayload;
+  const callbackUrl = resolveCallbackUrl(webhookPayload);
+  const timestampStr = Formatter.timestamp(new Date());
+
+  Logger.log(`\n[${timestampStr}] ${label}:`);
+  Logger.log(`  Channel ID: ${channel_id || 'N/A'}`);
+  Logger.log(`  Status: ${getWebhookStatusLabel(data)}`);
+
+  if (isEventDrivenWebhook(data)) {
+    Logger.log(`  Type: ${data.type}`);
+    Logger.log(`  Event: ${data.event || 'N/A'}`);
+
+    if (callbackUrl) {
+      Logger.log(`  Callback URL: ${callbackUrl}`);
+    }
+
+    const customerData = getCustomerData(data);
+    if (customerData) {
+      Logger.log(`  Customer data: ${Formatter.json(customerData)}`);
+    }
+
+    if (data.ai_response) {
+      Logger.log(`  AI response: ${Formatter.json(data.ai_response)}`);
+    }
+
+    const hint = buildCallbackHint(callbackUrl, channel_id, apiKey);
+    if (hint) {
+      Logger.warning(`\n${hint}\n`);
+    }
+  } else {
+    if (signature && webhookSecret && data) {
+      const isValid = WebhookVerifier.verify(
+        signature,
+        data,
+        webhookSecret,
+        String(timestamp)
+      );
+      Logger.log(`  Signature: ${isValid ? '✓ Valid' : '✗ Invalid'}`);
+    }
+
+    if (data?.data) {
+      Logger.log(`  Data: ${Formatter.json(data.data)}`);
+    }
+
+    if (data?.meta) {
+      Logger.log(`  Meta: ${Formatter.json(data.meta)}`);
+    }
+  }
+}
+
+function isIntermediateWebSocketStatus(status) {
+  return status === 'ai_generated' || status === 'step_received' || status === 'pending';
+}
+
+function isFinalWebSocketStatus(status) {
+  return status === 'completed' || status === 'success' || status === 'error';
+}
+
+module.exports = {
+  isEventDrivenWebhook,
+  resolveCallbackUrl,
+  getCustomerData,
+  getWebhookStatusLabel,
+  buildCallbackHint,
+  printWebhookDetails,
+  isIntermediateWebSocketStatus,
+  isFinalWebSocketStatus,
+};

package/src/lib/api-client.test.js

@@ -1,101 +0,0 @@
-// Mock fs to prevent reading from actual ~/.modelriver/config.json
-jest.mock('fs', () => ({
-    existsSync: jest.fn(() => false),
-    readFileSync: jest.fn(() => '{}'),
-    writeFileSync: jest.fn(),
-    mkdirSync: jest.fn(),
-}));
-
-describe('ApiClient', () => {
-    const originalEnv = process.env;
-
-    beforeEach(() => {
-        jest.resetModules();
-        // Re-apply the mock after resetModules
-        jest.doMock('fs', () => ({
-            existsSync: jest.fn(() => false),
-            readFileSync: jest.fn(() => '{}'),
-            writeFileSync: jest.fn(),
-            mkdirSync: jest.fn(),
-        }));
-        process.env = { ...originalEnv };
-        // Clear any config env vars first
-        delete process.env.MODELRIVER_API_KEY;
-        // Then set a valid API key for tests that need it
-        process.env.MODELRIVER_API_KEY = 'mr_live_validtestkey123';
-    });
-
-    afterAll(() => {
-        process.env = originalEnv;
-    });
-
-    describe('constructor validation', () => {
-        it('should throw error when API key is missing', () => {
-            delete process.env.MODELRIVER_API_KEY;
-            const ApiClient = require('./api-client');
-
-            expect(() => new ApiClient(null, 'https://api.modelriver.com'))
-                .toThrow('API key is required');
-        });
-
-        it('should throw error for invalid API key format', () => {
-            const ApiClient = require('./api-client');
-
-            expect(() => new ApiClient('invalid-key-format', 'https://api.modelriver.com'))
-                .toThrow('Invalid API key format');
-        });
-
-        it('should accept mr_live_ prefixed keys', () => {
-            const ApiClient = require('./api-client');
-
-            expect(() => new ApiClient('mr_live_abc123', 'https://api.modelriver.com'))
-                .not.toThrow();
-        });
-
-        it('should accept mr_test_ prefixed keys', () => {
-            const ApiClient = require('./api-client');
-
-            expect(() => new ApiClient('mr_test_abc123', 'https://api.modelriver.com'))
-                .not.toThrow();
-        });
-    });
-
-    describe('apiPath detection', () => {
-        it('should use /v1 for production URLs', () => {
-            const ApiClient = require('./api-client');
-            const client = new ApiClient('mr_live_test123', 'https://api.modelriver.com');
-
-            expect(client.apiPath).toBe('/v1');
-        });
-
-        it('should use /v1 for *.modelriver.com subdomains', () => {
-            const ApiClient = require('./api-client');
-            const client = new ApiClient('mr_live_test123', 'https://staging.modelriver.com');
-
-            expect(client.apiPath).toBe('/v1');
-        });
-
-        it('should use /api/v1 for localhost', () => {
-            const ApiClient = require('./api-client');
-            const client = new ApiClient('mr_live_test123', 'http://localhost:4000');
-
-            expect(client.apiPath).toBe('/api/v1');
-        });
-
-        it('should use /api/v1 for non-production URLs', () => {
-            const ApiClient = require('./api-client');
-            const client = new ApiClient('mr_live_test123', 'http://my-dev-server.local');
-
-            expect(client.apiPath).toBe('/api/v1');
-        });
-    });
-
-    describe('URL normalization', () => {
-        it('should strip trailing slashes from API URL', () => {
-            const ApiClient = require('./api-client');
-            const client = new ApiClient('mr_live_test123', 'https://api.modelriver.com/');
-
-            expect(client.apiUrl).toBe('https://api.modelriver.com');
-        });
-    });
-});

package/src/lib/config.test.js

@@ -1,98 +0,0 @@
-// We need to test the Config class, but it's exported as a singleton instance.
-// We'll test the behavior through environment variables.
-
-// Mock fs to prevent reading from actual ~/.modelriver/config.json
-jest.mock('fs', () => ({
-    existsSync: jest.fn(() => false),
-    readFileSync: jest.fn(() => '{}'),
-    writeFileSync: jest.fn(),
-    mkdirSync: jest.fn(),
-}));
-
-describe('Config', () => {
-    const originalEnv = process.env;
-
-    beforeEach(() => {
-        // Reset modules to get fresh Config instance
-        jest.resetModules();
-        // Re-apply the mock after resetModules
-        jest.doMock('fs', () => ({
-            existsSync: jest.fn(() => false),
-            readFileSync: jest.fn(() => '{}'),
-            writeFileSync: jest.fn(),
-            mkdirSync: jest.fn(),
-        }));
-        process.env = { ...originalEnv };
-        // Clear any config-related env vars
-        delete process.env.MODELRIVER_API_KEY;
-        delete process.env.MODELRIVER_API_URL;
-    });
-
-    afterAll(() => {
-        process.env = originalEnv;
-    });
-
-    describe('getApiKey', () => {
-        it('should read API key from MODELRIVER_API_KEY env var', () => {
-            process.env.MODELRIVER_API_KEY = 'mr_live_test123';
-            const config = require('./config');
-
-            expect(config.getApiKey()).toBe('mr_live_test123');
-        });
-
-        it('should return undefined when API key not set', () => {
-            delete process.env.MODELRIVER_API_KEY;
-            const config = require('./config');
-
-            expect(config.getApiKey()).toBeFalsy();
-        });
-    });
-
-    describe('getApiUrl', () => {
-        it('should return default URL when not set', () => {
-            delete process.env.MODELRIVER_API_URL;
-            const config = require('./config');
-
-            expect(config.getApiUrl()).toBe('https://api.modelriver.com');
-        });
-
-        it('should read API URL from MODELRIVER_API_URL env var', () => {
-            process.env.MODELRIVER_API_URL = 'http://localhost:4000';
-            const config = require('./config');
-
-            expect(config.getApiUrl()).toBe('http://localhost:4000');
-        });
-    });
-
-    describe('getWebSocketUrl', () => {
-        it('should convert https:// to wss://', () => {
-            process.env.MODELRIVER_API_URL = 'https://api.modelriver.com';
-            const config = require('./config');
-
-            expect(config.getWebSocketUrl()).toBe('wss://api.modelriver.com');
-        });
-
-        it('should convert http:// to ws://', () => {
-            process.env.MODELRIVER_API_URL = 'http://localhost:4000';
-            const config = require('./config');
-
-            expect(config.getWebSocketUrl()).toBe('ws://localhost:4000');
-        });
-    });
-
-    describe('get', () => {
-        it('should prioritize env vars over defaults', () => {
-            process.env.MODELRIVER_CUSTOM_KEY = 'env-value';
-            const config = require('./config');
-
-            expect(config.get('custom-key', 'default-value')).toBe('env-value');
-        });
-
-        it('should return default when env var not set', () => {
-            delete process.env.MODELRIVER_MISSING_KEY;
-            const config = require('./config');
-
-            expect(config.get('missing-key', 'fallback')).toBe('fallback');
-        });
-    });
-});

package/src/lib/webhook-verifier.test.js

@@ -1,90 +0,0 @@
-const WebhookVerifier = require('./webhook-verifier');
-
-describe('WebhookVerifier', () => {
-    const secret = 'test-secret-key-12345';
-    const timestamp = '1704825600';
-    const payload = { status: 'success', name: 'Test User' };
-
-    describe('generateSignature', () => {
-        it('should generate a consistent HMAC-SHA256 signature', () => {
-            const sig1 = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const sig2 = WebhookVerifier.generateSignature(payload, secret, timestamp);
-
-            expect(sig1).toBe(sig2);
-            expect(typeof sig1).toBe('string');
-            expect(sig1.length).toBe(64); // SHA256 hex is 64 chars
-        });
-
-        it('should produce different signatures for different payloads', () => {
-            const sig1 = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const sig2 = WebhookVerifier.generateSignature({ different: 'data' }, secret, timestamp);
-
-            expect(sig1).not.toBe(sig2);
-        });
-
-        it('should produce different signatures for different secrets', () => {
-            const sig1 = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const sig2 = WebhookVerifier.generateSignature(payload, 'different-secret', timestamp);
-
-            expect(sig1).not.toBe(sig2);
-        });
-
-        it('should produce different signatures for different timestamps', () => {
-            const sig1 = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const sig2 = WebhookVerifier.generateSignature(payload, secret, '1704825601');
-
-            expect(sig1).not.toBe(sig2);
-        });
-    });
-
-    describe('verify', () => {
-        it('should return true for valid signatures', () => {
-            const signature = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const isValid = WebhookVerifier.verify(signature, payload, secret, timestamp);
-
-            expect(isValid).toBe(true);
-        });
-
-        it('should return false for tampered payloads', () => {
-            const signature = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const tamperedPayload = { ...payload, name: 'Hacker' };
-            const isValid = WebhookVerifier.verify(signature, tamperedPayload, secret, timestamp);
-
-            expect(isValid).toBe(false);
-        });
-
-        it('should return false for wrong secret', () => {
-            const signature = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const isValid = WebhookVerifier.verify(signature, payload, 'wrong-secret', timestamp);
-
-            expect(isValid).toBe(false);
-        });
-
-        it('should return false for wrong timestamp', () => {
-            const signature = WebhookVerifier.generateSignature(payload, secret, timestamp);
-            const isValid = WebhookVerifier.verify(signature, payload, secret, 'wrong-timestamp');
-
-            expect(isValid).toBe(false);
-        });
-    });
-
-    describe('secureCompare', () => {
-        it('should return true for equal strings', () => {
-            expect(WebhookVerifier.secureCompare('abc123', 'abc123')).toBe(true);
-        });
-
-        it('should return false for different strings', () => {
-            expect(WebhookVerifier.secureCompare('abc123', 'xyz789')).toBe(false);
-        });
-
-        it('should return false for different length strings', () => {
-            expect(WebhookVerifier.secureCompare('short', 'muchlongerstring')).toBe(false);
-        });
-
-        it('should return false for non-string inputs', () => {
-            expect(WebhookVerifier.secureCompare(null, 'string')).toBe(false);
-            expect(WebhookVerifier.secureCompare('string', undefined)).toBe(false);
-            expect(WebhookVerifier.secureCompare(123, 456)).toBe(false);
-        });
-    });
-});

package/src/utils/formatter.test.js

@@ -1,84 +0,0 @@
-const Formatter = require('./formatter');
-
-describe('Formatter', () => {
-    describe('json', () => {
-        it('should format objects with default 2-space indentation', () => {
-            const obj = { name: 'test', value: 123 };
-            const result = Formatter.json(obj);
-
-            expect(result).toBe('{\n  "name": "test",\n  "value": 123\n}');
-        });
-
-        it('should format with custom indentation', () => {
-            const obj = { key: 'value' };
-            const result = Formatter.json(obj, 4);
-
-            expect(result).toBe('{\n    "key": "value"\n}');
-        });
-
-        it('should handle arrays', () => {
-            const arr = [1, 2, 3];
-            const result = Formatter.json(arr);
-
-            expect(result).toBe('[\n  1,\n  2,\n  3\n]');
-        });
-    });
-
-    describe('timestamp', () => {
-        it('should return ISO format string', () => {
-            const date = new Date('2024-01-09T12:00:00Z');
-            const result = Formatter.timestamp(date);
-
-            expect(result).toBe('2024-01-09T12:00:00.000Z');
-        });
-
-        it('should use current date when no argument provided', () => {
-            const result = Formatter.timestamp();
-
-            expect(result).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
-        });
-    });
-
-    describe('formatDuration', () => {
-        it('should format milliseconds', () => {
-            expect(Formatter.formatDuration(500)).toBe('500ms');
-            expect(Formatter.formatDuration(999)).toBe('999ms');
-        });
-
-        it('should format seconds', () => {
-            expect(Formatter.formatDuration(1000)).toBe('1.0s');
-            expect(Formatter.formatDuration(5500)).toBe('5.5s');
-            expect(Formatter.formatDuration(59999)).toBe('60.0s');
-        });
-
-        it('should format minutes', () => {
-            expect(Formatter.formatDuration(60000)).toBe('1.0m');
-            expect(Formatter.formatDuration(90000)).toBe('1.5m');
-            expect(Formatter.formatDuration(300000)).toBe('5.0m');
-        });
-    });
-
-    describe('table', () => {
-        it('should format a simple table', () => {
-            const headers = ['Name', 'Age'];
-            const rows = [
-                ['Alice', 30],
-                ['Bob', 25]
-            ];
-            const result = Formatter.table(headers, rows);
-
-            expect(result).toContain('Name');
-            expect(result).toContain('Age');
-            expect(result).toContain('Alice');
-            expect(result).toContain('Bob');
-        });
-
-        it('should handle empty cells', () => {
-            const headers = ['A', 'B'];
-            const rows = [['value', null]];
-            const result = Formatter.table(headers, rows);
-
-            expect(result).toContain('value');
-        });
-    });
-});

package/src/utils/url-helpers.test.js

@@ -1,144 +0,0 @@
-// Tests for URL helper utilities
-const { normalizeWebhookUrl, extractPort, isValidApiKeyFormat, parseForwardUrl } = require('./url-helpers');
-
-describe('URL Helpers', () => {
-    describe('normalizeWebhookUrl', () => {
-        it('should add /webhook/modelriver to base URL', () => {
-            expect(normalizeWebhookUrl('http://localhost:4000'))
-                .toBe('http://localhost:4000/webhook/modelriver');
-        });
-
-        it('should add /modelriver to URL ending with /webhook', () => {
-            expect(normalizeWebhookUrl('http://localhost:4000/webhook'))
-                .toBe('http://localhost:4000/webhook/modelriver');
-        });
-
-        it('should not modify URL already ending with /webhook/modelriver', () => {
-            expect(normalizeWebhookUrl('http://localhost:4000/webhook/modelriver'))
-                .toBe('http://localhost:4000/webhook/modelriver');
-        });
-
-        it('should handle trailing slashes', () => {
-            expect(normalizeWebhookUrl('http://localhost:4000/'))
-                .toBe('http://localhost:4000/webhook/modelriver');
-        });
-
-        it('should handle URLs with port', () => {
-            expect(normalizeWebhookUrl('http://localhost:3001'))
-                .toBe('http://localhost:3001/webhook/modelriver');
-        });
-
-        it('should handle https URLs', () => {
-            expect(normalizeWebhookUrl('https://myserver.com'))
-                .toBe('https://myserver.com/webhook/modelriver');
-        });
-
-        it('should return empty for falsy input', () => {
-            expect(normalizeWebhookUrl('')).toBeFalsy();
-            expect(normalizeWebhookUrl(null)).toBeFalsy();
-            expect(normalizeWebhookUrl(undefined)).toBeFalsy();
-        });
-    });
-
-    describe('extractPort', () => {
-        it('should extract port from URL with explicit port', () => {
-            expect(extractPort('http://localhost:4000')).toBe(4000);
-            expect(extractPort('http://localhost:3001/webhook')).toBe(3001);
-        });
-
-        it('should return 80 for http without port', () => {
-            expect(extractPort('http://example.com')).toBe(80);
-        });
-
-        it('should return 443 for https without port', () => {
-            expect(extractPort('https://example.com')).toBe(443);
-        });
-
-        it('should return null for invalid URLs', () => {
-            expect(extractPort('not-a-url')).toBeNull();
-            expect(extractPort('')).toBeNull();
-        });
-    });
-
-    describe('isValidApiKeyFormat', () => {
-        it('should accept mr_live_ prefixed keys', () => {
-            expect(isValidApiKeyFormat('mr_live_abc123xyz')).toBe(true);
-        });
-
-        it('should accept mr_test_ prefixed keys', () => {
-            expect(isValidApiKeyFormat('mr_test_abc123xyz')).toBe(true);
-        });
-
-        it('should reject keys without valid prefix', () => {
-            expect(isValidApiKeyFormat('invalid_key')).toBe(false);
-            expect(isValidApiKeyFormat('mr_invalid_key')).toBe(false);
-            expect(isValidApiKeyFormat('abc123')).toBe(false);
-        });
-
-        it('should reject empty or falsy keys', () => {
-            expect(isValidApiKeyFormat('')).toBe(false);
-            expect(isValidApiKeyFormat(null)).toBe(false);
-            expect(isValidApiKeyFormat(undefined)).toBe(false);
-        });
-    });
-
-    describe('parseForwardUrl', () => {
-        it('should parse localhost URL with port', () => {
-            const result = parseForwardUrl('http://localhost:4000/webhook/modelriver');
-            expect(result).toEqual({
-                hostname: 'localhost',
-                port: 4000,
-                path: '/webhook/modelriver',
-                protocol: 'http'
-            });
-        });
-
-        it('should parse external URL with port', () => {
-            const result = parseForwardUrl('http://myserver.com:3001/webhook/modelriver');
-            expect(result).toEqual({
-                hostname: 'myserver.com',
-                port: 3001,
-                path: '/webhook/modelriver',
-                protocol: 'http'
-            });
-        });
-
-        it('should default to port 80 for http without explicit port', () => {
-            const result = parseForwardUrl('http://example.com/webhook/modelriver');
-            expect(result.port).toBe(80);
-            expect(result.hostname).toBe('example.com');
-        });
-
-        it('should default to port 443 for https without explicit port', () => {
-            const result = parseForwardUrl('https://example.com/webhook/modelriver');
-            expect(result.port).toBe(443);
-            expect(result.protocol).toBe('https');
-        });
-
-        it('should handle URLs with different paths', () => {
-            const result = parseForwardUrl('http://localhost:5000/custom/path');
-            expect(result.path).toBe('/custom/path');
-        });
-
-        it('should return null for empty or falsy input', () => {
-            expect(parseForwardUrl('')).toBeNull();
-            expect(parseForwardUrl(null)).toBeNull();
-            expect(parseForwardUrl(undefined)).toBeNull();
-        });
-
-        it('should handle URLs without protocol by defaulting to http', () => {
-            const result = parseForwardUrl('myserver:4000/webhook/modelriver');
-            expect(result).toEqual({
-                hostname: 'myserver',
-                port: 4000,
-                path: '/webhook/modelriver',
-                protocol: 'http'
-            });
-        });
-
-        it('should return null for invalid URLs', () => {
-            expect(parseForwardUrl('http://invalid url with spaces')).toBeNull();
-            expect(parseForwardUrl('just text with spaces')).toBeNull();
-        });
-    });
-});