webhookagent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avni Yayin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @avniyayin/webhookagent
+
+Cross-platform Node.js heartbeat agent for [WebhookAgent.com](https://webhookagent.com) — receive webhooks, queue them, process at your pace.
+
+## Install
+
+```bash
+npm install -g @avniyayin/webhookagent
+```
+
+## Quick Start
+
+```bash
+# Sign up at https://webhookagent.com/dashboard and get your API key
+
+# Start the heartbeat agent
+webhookagent --key=wha_your_key --auto-restart
+
+# Single check
+webhookagent --key=wha_your_key --once
+
+# Fetch + auto-ack items
+webhookagent --key=wha_your_key --auto-restart --fetch --ack
+```
+
+## How It Works (Break-on-Action)
+
+1. **Poll** — Agent sends heartbeat every N seconds (default: 30)
+2. **Break** — When events arrive, the polling loop exits
+3. **Process** — Your logic handles the events
+4. **Reconnect** — Agent restarts the heartbeat loop
+
+No open ports needed. Works behind any firewall. Events are queued so nothing is lost.
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--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 |
+| `--cycles=N` | 120 | Max polls before exit (~1 hour) |
+| `--once` | - | Single check then exit |
+| `--auto-restart` | - | Never exit — restart after break + max cycles |
+| `--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 |
+| `--ack` | - | Auto-acknowledge items after outputting them |
+| `--json` | - | Output full heartbeat JSON |
+
+## Output Format
+
+Status logs go to `stderr`, actions go to `stdout` as `ACTION:{json}` lines.
+
+```bash
+# Pipe to your processor
+webhookagent --key=wha_abc123 --quiet --auto-restart | node my-processor.js
+```
+
+## Programmatic Usage
+
+```javascript
+const { execSync } = require('child_process');
+
+// Quick single check
+const result = execSync('webhookagent --key=wha_abc --once --json', { encoding: 'utf8' });
+const data = JSON.parse(result);
+```
+
+## Environment Variables
+
+- `WHA_API_KEY` — API key (alternative to `--key` flag)
+- `WHA_URL` — Base URL override
+
+## Links
+
+- [WebhookAgent.com](https://webhookagent.com)
+- [API Docs](https://webhookagent.com/docs)
+- [Dashboard](https://webhookagent.com/dashboard)
+- [@avniyayin](https://x.com/avniyayin)
+
+## License
+
+MIT

package/lib/heartbeat.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * WebhookAgent Heartbeat Runtime v1.0
+ * Cross-platform Node.js agent for polling + processing webhook events
+ *
+ * Inspired by MoltedOpus Agent Runtime v1.4
+ * Works on: Windows, macOS, Linux — anywhere Node.js runs
+ *
+ * HOW IT WORKS (Break-on-Action Pattern):
+ *   1. Polls /api/heartbeat every N seconds (default: 30)
+ *   2. When the heartbeat returns actions (pending webhook events), it BREAKS
+ *   3. Outputs ACTION:{json} lines for your parent process to handle
+ *   4. After processing, your parent restarts the heartbeat (or use --auto-restart)
+ *   5. This ensures your agent processes events at its own pace
+ *
+ * USAGE:
+ *   node heartbeat.js --key=wha_... [options]
+ *
+ * OPTIONS:
+ *   --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)
+ *   --once             Single heartbeat check, then exit
+ *   --auto-restart     Never exit — restart after break + after max cycles
+ *   --quiet            Only output ACTION lines, no status logs
+ *   --webhooks=IDS     Comma-separated webhook IDs to filter (default: all)
+ *   --fetch            Auto-fetch full queue items when actions arrive
+ *   --ack              Auto-acknowledge items after outputting them
+ *   --json             Output full heartbeat JSON instead of ACTION lines
+ *
+ * OUTPUT FORMAT:
+ *   Status lines go to stderr (so you can pipe stdout cleanly)
+ *   Actions print to stdout as: ACTION:{json}
+ *
+ * EXAMPLES:
+ *   # Simple poll loop
+ *   node heartbeat.js --key=wha_abc123
+ *
+ *   # Continuous with auto-restart
+ *   node heartbeat.js --key=wha_abc123 --auto-restart
+ *
+ *   # Single check, fetch items, auto-ack
+ *   node heartbeat.js --key=wha_abc123 --once --fetch --ack
+ *
+ *   # Pipe actions to another script
+ *   node heartbeat.js --key=wha_abc123 --quiet --auto-restart | node my-processor.js
+ *
+ *   # Filter specific webhooks
+ *   node heartbeat.js --key=wha_abc123 --webhooks=wh-abc-123,wh-def-456
+ */
+
+// ============================================================
+// 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 AUTO_RESTART = !!args['auto-restart'];
+const QUIET = !!args.quiet;
+const WEBHOOKS_FILTER = args.webhooks || 'all';
+const AUTO_FETCH = !!args.fetch;
+const AUTO_ACK = !!args.ack;
+const JSON_MODE = !!args.json;
+
+if (!API_KEY) {
+  console.error('ERROR: API key required. Use --key=wha_... or set WHA_API_KEY env var');
+  process.exit(1);
+}
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function parseArgs(argv) {
+  const result = {};
+  for (const arg of argv) {
+    if (arg.startsWith('--')) {
+      const [key, ...valParts] = arg.slice(2).split('=');
+      result[key] = valParts.length ? valParts.join('=') : true;
+    }
+  }
+  return result;
+}
+
+function log(msg) {
+  if (QUIET) return;
+  process.stderr.write(`${new Date().toLocaleTimeString()} ${msg}\n`);
+}
+
+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)',
+  };
+  const opts = { method, headers };
+  if (body) opts.body = JSON.stringify(body);
+
+  try {
+    const res = await fetch(`${BASE_URL}${path}`, opts);
+    const data = await res.json();
+    if (!res.ok) {
+      log(`ERROR: HTTP ${res.status} on ${method} ${path}: ${data.error || 'Unknown'}`);
+      return null;
+    }
+    return data;
+  } catch (err) {
+    log(`ERROR: ${err.message}`);
+    return null;
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ============================================================
+// ACTION PROCESSING
+// ============================================================
+
+async function processActions(actions, heartbeatData) {
+  if (JSON_MODE) {
+    console.log(JSON.stringify(heartbeatData));
+    return;
+  }
+
+  for (const action of actions) {
+    const whId = action.webhook_id;
+    const whName = action.webhook_name;
+    const pending = action.pending;
+
+    log(`  >> ${whName}: ${pending} pending events`);
+
+    if (AUTO_FETCH) {
+      // Fetch full queue items
+      const queue = await api(`/webhooks/${whId}/queue?status=pending&limit=50`);
+      if (queue && queue.items) {
+        const ids = [];
+        for (const item of queue.items) {
+          ids.push(item.id);
+          const output = {
+            type: 'webhook_event',
+            webhook_id: whId,
+            webhook_name: whName,
+            item_id: item.id,
+            method: item.method,
+            content_type: item.content_type,
+            headers: item.headers,
+            body: item.body_json || item.body,
+            query_params: item.query_params,
+            source_ip: item.source_ip,
+            received_at: item.received_at,
+          };
+          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 {
+      // Just output the action summary with preview
+      console.log('ACTION:' + JSON.stringify({
+        type: 'webhook_events',
+        webhook_id: whId,
+        webhook_name: whName,
+        pending: pending,
+        items_preview: action.items_preview || [],
+        fetch: action.fetch,
+        ack: action.ack,
+      }));
+    }
+  }
+}
+
+// ============================================================
+// MAIN HEARTBEAT LOOP
+// ============================================================
+
+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}`);
+  if (AUTO_FETCH) log('Auto-fetch: ON');
+  if (AUTO_ACK) log('Auto-ack: ON');
+  log('---');
+
+  do {
+    let retries = 0;
+    let brokeOnAction = false;
+
+    for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
+      const path = `/heartbeat?webhooks=${encodeURIComponent(WEBHOOKS_FILTER)}`;
+      const data = await api(path);
+
+      if (!data) {
+        retries++;
+        log(`WARN: heartbeat failed (retry ${retries}/3)`);
+        if (retries >= 3) {
+          log('FATAL: 3 consecutive failures, exiting');
+          process.exit(1);
+        }
+        await sleep(10000);
+        continue;
+      }
+      retries = 0;
+
+      const user = data.user || {};
+      const summary = data.summary || {};
+      const actions = data.actions || [];
+
+      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 {
+        log(`BREAK | ${actions.length} webhook(s) with pending events | plan=${user.plan} events_left=${user.events_remaining}`);
+
+        await processActions(actions, data);
+
+        brokeOnAction = true;
+        break; // ← THE BREAK — exit loop so parent process can handle
+      }
+
+      if (cycle < MAX_CYCLES) {
+        await sleep(INTERVAL);
+      }
+    }
+
+    if (!brokeOnAction) {
+      log(`Max cycles reached (${MAX_CYCLES}), exiting cleanly`);
+    }
+
+    if (AUTO_RESTART) {
+      const wait = brokeOnAction ? 5000 : INTERVAL;
+      log(`Auto-restart: sleeping ${wait / 1000}s...`);
+      await sleep(wait);
+    }
+
+  } while (AUTO_RESTART);
+}
+
+// Handle clean exit
+process.on('SIGINT', () => {
+  log('Interrupted, shutting down...');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  log('Terminated, shutting down...');
+  process.exit(0);
+});
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "webhookagent",
+  "version": "1.0.0",
+  "description": "WebhookAgent heartbeat runtime — poll, break, process webhook events at your agent's pace",
+  "main": "lib/heartbeat.js",
+  "bin": {
+    "webhookagent": "lib/heartbeat.js"
+  },
+  "scripts": {
+    "start": "node lib/heartbeat.js"
+  },
+  "keywords": [
+    "webhook",
+    "agent",
+    "heartbeat",
+    "queue",
+    "polling",
+    "break-on-action",
+    "ai-agent",
+    "webhook-queue",
+    "event-processing"
+  ],
+  "author": "Avni Yayin <avni.yayin@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://webhookagent.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/avniyayin/webhookagent"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ]
+}