webhookagent 1.0.1 → 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
@@ -54,20 +54,78 @@
 // CONFIG
 // ============================================================
 
-const args = parseArgs(process.argv.slice(2));
-const API_KEY = args.key || process.env.WHA_API_KEY || '';
-const BASE_URL = (args.url || process.env.WHA_URL || 'https://webhookagent.com/api').replace(/\/$/, '');
-const INTERVAL = parseInt(args.interval || '30') * 1000;
-const MAX_CYCLES = args.once ? 1 : parseInt(args.cycles || '120');
+const fs = require('fs');
+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 subcommands
+const rawArgs = process.argv.slice(2);
+if (rawArgs[0] === 'config') {
+  handleConfig(rawArgs.slice(1));
+  process.exit(0);
+}
+
+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 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 || 'all';
+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. Use --key=wha_... or set WHA_API_KEY env var');
+  console.error('ERROR: API key required.');
+  console.error('  Option 1: webhookagent config --key=wha_...   (saves securely, recommended)');
+  console.error('  Option 2: webhookagent --key=wha_...          (passed each time)');
+  console.error('  Option 3: set WHA_API_KEY env var');
   process.exit(1);
 }
 
@@ -86,6 +144,91 @@ function parseArgs(argv) {
   return result;
 }
 
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    }
+  } catch (e) { /* ignore */ }
+  return {};
+}
+
+function saveConfig(data) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  const existing = loadConfig();
+  const merged = { ...existing, ...data };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n');
+  return merged;
+}
+
+function handleConfig(argv) {
+  const configArgs = parseArgs(argv);
+
+  // webhookagent config --key=wha_...
+  if (configArgs.key) {
+    saveConfig({ api_key: configArgs.key });
+    console.log(`API key saved to ${CONFIG_FILE}`);
+    console.log('You can now run: webhookagent --fetch --ack');
+    return;
+  }
+
+  // webhookagent config --webhooks=wh-abc,wh-def
+  if (configArgs.webhooks) {
+    saveConfig({ webhooks: configArgs.webhooks });
+    console.log(`Webhook filter saved: ${configArgs.webhooks}`);
+    return;
+  }
+
+  // webhookagent config --url=https://...
+  if (configArgs.url) {
+    saveConfig({ api_url: configArgs.url });
+    console.log(`API URL saved: ${configArgs.url}`);
+    return;
+  }
+
+  // webhookagent config --show
+  if (configArgs.show) {
+    const cfg = loadConfig();
+    if (Object.keys(cfg).length === 0) {
+      console.log('No config saved. Use: webhookagent config --key=wha_...');
+    } else {
+      const display = { ...cfg };
+      if (display.api_key) display.api_key = display.api_key.slice(0, 8) + '...' + display.api_key.slice(-4);
+      console.log(JSON.stringify(display, null, 2));
+    }
+    return;
+  }
+
+  // webhookagent config --clear
+  if (configArgs.clear) {
+    try { fs.unlinkSync(CONFIG_FILE); } catch (e) { /* ignore */ }
+    console.log('Config cleared.');
+    return;
+  }
+
+  // No args — show help
+  console.log('WebhookAgent Config');
+  console.log('  webhookagent config --key=wha_...        Save API key');
+  console.log('  webhookagent config --webhooks=ID1,ID2   Save webhook filter');
+  console.log('  webhookagent config --show               Show saved config');
+  console.log('  webhookagent config --clear              Delete saved config');
+}
+
+function buildRestartCommand() {
+  const parts = ['webhookagent'];
+  // Only include --key if it was passed explicitly (not from config/env)
+  if (args.key) parts.push(`--key=${args.key}`);
+  if (AUTO_FETCH) parts.push('--fetch');
+  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(' ');
+}
+
 function log(msg) {
   if (QUIET) return;
   process.stderr.write(`${new Date().toLocaleTimeString()} ${msg}\n`);
@@ -95,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);
@@ -103,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;
@@ -155,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 {
@@ -171,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,
       }));
@@ -183,9 +345,35 @@ async function processActions(actions, heartbeatData) {
 // ============================================================
 
 async function main() {
-  log('WebhookAgent Heartbeat Runtime v1.0');
-  log(`Polling ${BASE_URL} every ${INTERVAL / 1000}s, max ${MAX_CYCLES} cycles${AUTO_RESTART ? ' (continuous)' : ''}`);
-  if (WEBHOOKS_FILTER !== 'all') log(`Filtering webhooks: ${WEBHOOKS_FILTER}`);
+  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;
+  if (WEBHOOKS_FILTER !== 'all') {
+    const filterParts = WEBHOOKS_FILTER.split(',').map(s => s.trim());
+    const hasNames = filterParts.some(p => !p.startsWith('wh-') && !/^\d+$/.test(p));
+    if (hasNames) {
+      const webhooks = await api('/webhooks');
+      if (webhooks && webhooks.webhooks) {
+        const resolved = filterParts.map(f => {
+          // If it looks like an ID already, keep it
+          if (f.startsWith('wh-') || /^\d+$/.test(f)) return f;
+          // Otherwise match by name (case-insensitive)
+          const match = webhooks.webhooks.find(w => w.name.toLowerCase() === f.toLowerCase());
+          if (match) {
+            log(`Resolved "${f}" → ${match.webhook_id}`);
+            return match.webhook_id;
+          }
+          log(`WARN: webhook name "${f}" not found, skipping`);
+          return null;
+        }).filter(Boolean);
+        resolvedFilter = resolved.join(',');
+      }
+    }
+    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('---');
@@ -195,7 +383,7 @@ async function main() {
     let brokeOnAction = false;
 
     for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
-      const path = `/heartbeat?webhooks=${encodeURIComponent(WEBHOOKS_FILTER)}`;
+      const path = `/heartbeat?webhooks=${encodeURIComponent(resolvedFilter)}`;
       const data = await api(path);
 
       if (!data) {
@@ -208,20 +396,45 @@ 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}`);
 
         await processActions(actions, data);
 
         brokeOnAction = true;
+
+        // Tell the agent exactly how to restart
+        if (!AUTO_RESTART) {
+          const cmd = buildRestartCommand();
+          console.log('RESTART:' + cmd);
+          log(`Process events above, then run: ${cmd}`);
+        }
+
         break; // ← THE BREAK — exit loop so parent process can handle
       }
 
@@ -230,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.0.1",
+  "version": "1.3.0",
   "description": "WebhookAgent heartbeat runtime — poll, break, process webhook events at your agent's pace",
   "main": "lib/heartbeat.js",
   "bin": {