webhookagent 1.1.0 → 1.3.0

package/README.md

@@ -13,14 +13,17 @@ npm install -g @avniyayin/webhookagent
 ```bash
 # Sign up at https://webhookagent.com/dashboard and get your API key
 
-# Start the heartbeat agent
-webhookagent --key=wha_your_key --auto-restart
+# Save your key (one-time — loads automatically after this)
+webhookagent config --key=wha_your_key
 
-# Single check
-webhookagent --key=wha_your_key --once
+# Start heartbeat — polls, breaks on events, outputs ACTION:{json}, exits
+webhookagent --fetch --ack
 
-# Fetch + auto-ack items
-webhookagent --key=wha_your_key --auto-restart --fetch --ack
+# Single check (one poll, then exit)
+webhookagent --once
+
+# Continuous monitoring (for dashboards/debugging, not AI agents)
+webhookagent --auto-restart --fetch --ack
 ```
 
 ## How It Works (Break-on-Action)
@@ -38,10 +41,11 @@ No open ports needed. Works behind any firewall. Events are queued so nothing is
 |------|---------|-------------|
 | `--key=KEY` | - | API key (or set `WHA_API_KEY` env var) |
 | `--url=URL` | `https://webhookagent.com/api` | Base API URL |
-| `--interval=N` | 30 | Seconds between polls |
+| `--interval=N` | 30 | Seconds between polls (auto-adjusts to plan minimum) |
 | `--cycles=N` | 120 | Max polls before exit (~1 hour) |
 | `--once` | - | Single check then exit |
 | `--auto-restart` | - | Never exit — restart after break + max cycles |
+| `--show` | - | Show events without breaking (debug/monitor mode) |
 | `--quiet` | - | Only output ACTION lines (for piping) |
 | `--webhooks=IDS` | all | Comma-separated webhook IDs to filter |
 | `--fetch` | - | Auto-fetch full queue items when actions arrive |

package/lib/heartbeat.js

@@ -20,7 +20,7 @@
  *   --key=KEY          API key (or set WHA_API_KEY env var)
  *   --url=URL          Base URL (default: https://webhookagent.com/api)
  *   --interval=N       Seconds between polls (default: 30)
- *   --cycles=N         Max polls before exit (default: 120 = ~1 hour)
+ *   --cycles=N         Max polls before exit (default: unlimited)
  *   --once             Single heartbeat check, then exit
  *   --auto-restart     Never exit — restart after break + after max cycles
  *   --quiet            Only output ACTION lines, no status logs
@@ -60,7 +60,7 @@ const path = require('path');
 const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.webhookagent');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
-// Handle `webhookagent config` subcommand
+// Handle subcommands
 const rawArgs = process.argv.slice(2);
 if (rawArgs[0] === 'config') {
   handleConfig(rawArgs.slice(1));
@@ -69,19 +69,57 @@ if (rawArgs[0] === 'config') {
 
 const args = parseArgs(rawArgs);
 
+if (args.help || args.h || rawArgs[0] === 'help') {
+  console.log(`WebhookAgent Heartbeat Runtime v1.2
+
+Usage: webhookagent [options]
+       webhookagent config --key=wha_...
+
+Options:
+  --key=KEY          API key (or save with: webhookagent config --key=wha_...)
+  --interval=N       Seconds between polls (auto-adjusts to plan minimum)
+  --cycles=N         Max polls before exit (default: unlimited)
+  --once             Single heartbeat check, then exit
+  --auto-restart     Never exit — restart after break + after max cycles
+  --show             Show events without breaking (debug/monitor mode)
+  --fetch            Auto-fetch full queue items when actions arrive
+  --ack              Auto-acknowledge items after outputting them
+  --webhooks=IDS     Comma-separated webhook IDs or names to filter
+  --json             Output full heartbeat JSON instead of ACTION lines
+  --quiet            Only output ACTION lines, no status logs
+  --url=URL          API base URL (default: https://webhookagent.com/api)
+
+Config:
+  webhookagent config --key=wha_...    Save API key (recommended)
+  webhookagent config --webhooks=ID    Save webhook filter
+  webhookagent config --show           Show saved config
+  webhookagent config --clear          Delete saved config
+
+Examples:
+  webhookagent --fetch --ack                   Poll, fetch events, auto-ack
+  webhookagent --once --fetch                  Single check, fetch items
+  webhookagent --auto-restart --fetch --ack    Continuous loop
+  webhookagent --quiet --fetch | node app.js   Pipe to your processor
+
+Docs: https://webhookagent.com/docs`);
+  process.exit(0);
+}
+
 // Load saved config (if exists)
 const savedConfig = loadConfig();
 
 const API_KEY = args.key || process.env.WHA_API_KEY || savedConfig.api_key || '';
 const BASE_URL = (args.url || process.env.WHA_URL || savedConfig.api_url || 'https://webhookagent.com/api').replace(/\/$/, '');
-const INTERVAL = parseInt(args.interval || '30') * 1000;
-const MAX_CYCLES = args.once ? 1 : parseInt(args.cycles || '120');
+const USER_INTERVAL = args.interval ? parseInt(args.interval) * 1000 : null;
+let INTERVAL = USER_INTERVAL || 30000;
+const MAX_CYCLES = args.once ? 1 : (args.cycles ? parseInt(args.cycles) : Infinity);
 const AUTO_RESTART = !!args['auto-restart'];
 const QUIET = !!args.quiet;
 const WEBHOOKS_FILTER = args.webhooks || savedConfig.webhooks || 'all';
 const AUTO_FETCH = !!args.fetch;
 const AUTO_ACK = !!args.ack;
 const JSON_MODE = !!args.json;
+const SHOW_MODE = !!args.show;
 
 if (!API_KEY) {
   console.error('ERROR: API key required.');
@@ -186,6 +224,7 @@ function buildRestartCommand() {
   if (AUTO_ACK) parts.push('--ack');
   if (WEBHOOKS_FILTER !== 'all' && args.webhooks) parts.push(`--webhooks=${WEBHOOKS_FILTER}`);
   if (args.interval) parts.push(`--interval=${args.interval}`);
+  if (SHOW_MODE) parts.push('--show');
   if (QUIET) parts.push('--quiet');
   return parts.join(' ');
 }
@@ -199,7 +238,7 @@ async function api(path, method = 'GET', body = null) {
   const headers = {
     'Authorization': `Bearer ${API_KEY}`,
     'Content-Type': 'application/json',
-    'User-Agent': 'WebhookAgent-Heartbeat/1.0 (Node.js)',
+    'User-Agent': 'WebhookAgent-Heartbeat/1.2 (Node.js)',
   };
   const opts = { method, headers };
   if (body) opts.body = JSON.stringify(body);
@@ -207,6 +246,11 @@ async function api(path, method = 'GET', body = null) {
   try {
     const res = await fetch(`${BASE_URL}${path}`, opts);
     const data = await res.json();
+    if (res.status === 429 && data.retry_after) {
+      log(`RATE LIMITED: ${data.error || 'Too fast'}. Waiting ${data.retry_after}s...`);
+      await sleep(data.retry_after * 1000);
+      return { _rate_limited: true };
+    }
     if (!res.ok) {
       log(`ERROR: HTTP ${res.status} on ${method} ${path}: ${data.error || 'Unknown'}`);
       return null;
@@ -259,12 +303,25 @@ async function processActions(actions, heartbeatData) {
             source_ip: item.source_ip,
             received_at: item.received_at,
           };
+          // When --ack is not used, include acknowledge instructions with each item
+          if (!AUTO_ACK) {
+            output.needs_ack = true;
+            output.ack_hint = `After you've handled this event, mark it as done so it leaves the queue.`;
+            output.ack_command = `curl -s -X POST "${BASE_URL}/webhooks/${whId}/queue/ack" -H "Authorization: Bearer ${API_KEY}" -H "Content-Type: application/json" -d '{"item_ids":[${item.id}]}'`;
+          }
           console.log('ACTION:' + JSON.stringify(output));
         }
 
         if (AUTO_ACK && ids.length > 0) {
           await api(`/webhooks/${whId}/queue/ack`, 'POST', { item_ids: ids });
           log(`  >> Acked ${ids.length} items from ${whName}`);
+        } else if (!AUTO_ACK && ids.length > 0) {
+          log(`  >> ${ids.length} items fetched from ${whName} — remember to acknowledge them when done`);
+          console.log('ACK_ALL:' + JSON.stringify({
+            hint: `You have ${ids.length} items to process. Once you're done with each one, acknowledge it so it's cleared from the queue. You can ack them all at once:`,
+            command: `curl -s -X POST "${BASE_URL}/webhooks/${whId}/queue/ack" -H "Authorization: Bearer ${API_KEY}" -H "Content-Type: application/json" -d '{"item_ids":[${ids.join(',')}]}'`,
+            item_ids: ids
+          }));
         }
       }
     } else {
@@ -275,6 +332,7 @@ async function processActions(actions, heartbeatData) {
         webhook_name: whName,
         pending: pending,
         items_preview: action.items_preview || [],
+        fetch_hint: `There are ${pending} events waiting. Fetch the full payloads, process them, and acknowledge when done.`,
         fetch: action.fetch,
         ack: action.ack,
       }));
@@ -287,8 +345,8 @@ async function processActions(actions, heartbeatData) {
 // ============================================================
 
 async function main() {
-  log('WebhookAgent Heartbeat Runtime v1.1');
-  log(`Polling ${BASE_URL} every ${INTERVAL / 1000}s, max ${MAX_CYCLES} cycles${AUTO_RESTART ? ' (continuous)' : ''}`);
+  log('WebhookAgent Heartbeat Runtime v1.3');
+  log(`Polling ${BASE_URL} every ${INTERVAL / 1000}s${MAX_CYCLES === Infinity ? '' : `, max ${MAX_CYCLES} cycles`}${AUTO_RESTART ? ' (continuous)' : ''}${SHOW_MODE ? ' (show mode — no break)' : ''}`);
 
   // Resolve webhook names to IDs if needed
   let resolvedFilter = WEBHOOKS_FILTER;
@@ -315,6 +373,7 @@ async function main() {
     }
     log(`Filtering webhooks: ${resolvedFilter}`);
   }
+  if (SHOW_MODE) log('Show mode: ON (events displayed, no break)');
   if (AUTO_FETCH) log('Auto-fetch: ON');
   if (AUTO_ACK) log('Auto-ack: ON');
   log('---');
@@ -337,14 +396,31 @@ async function main() {
         await sleep(10000);
         continue;
       }
+      if (data._rate_limited) { continue; }
       retries = 0;
 
       const user = data.user || {};
       const summary = data.summary || {};
       const actions = data.actions || [];
 
+      // Auto-adjust poll interval from server recommendation
+      if (user.poll_interval && user.poll_interval > 0) {
+        const serverInterval = user.poll_interval * 1000;
+        if (USER_INTERVAL && USER_INTERVAL < serverInterval) {
+          log(`WARN: --interval=${USER_INTERVAL / 1000}s is below plan minimum (${user.poll_interval}s). Using server value.`);
+          INTERVAL = serverInterval;
+        } else if (!USER_INTERVAL && serverInterval !== INTERVAL) {
+          INTERVAL = serverInterval;
+          log(`Poll interval adjusted to ${user.poll_interval}s (${user.plan} plan)`);
+        }
+      }
+
       if (actions.length === 0) {
         log(`ok | plan=${user.plan} events=${user.events_used}/${user.events_limit} (${user.events_remaining} left) | pending=${summary.total_pending}`);
+      } else if (SHOW_MODE) {
+        // Show mode: display events but keep polling (no break)
+        log(`SHOW | ${actions.length} webhook(s) with pending events | plan=${user.plan} events_left=${user.events_remaining}`);
+        await processActions(actions, data);
       } else {
         log(`BREAK | ${actions.length} webhook(s) with pending events | plan=${user.plan} events_left=${user.events_remaining}`);
 
@@ -367,7 +443,7 @@ async function main() {
       }
     }
 
-    if (!brokeOnAction) {
+    if (!brokeOnAction && MAX_CYCLES !== Infinity) {
       log(`Max cycles reached (${MAX_CYCLES}), exiting cleanly`);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhookagent",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "WebhookAgent heartbeat runtime — poll, break, process webhook events at your agent's pace",
   "main": "lib/heartbeat.js",
   "bin": {