ntfy-bridge 0.1.0

package/.gitattributes

@@ -0,0 +1,3 @@
+# Linguist overrides
+*.ts linguist-language=TypeScript
+package-lock.json linguist-generated=true

package/README.md

@@ -0,0 +1,87 @@
+# ntfy-bridge
+
+Local bridge from [ntfy.sh](https://ntfy.sh) to localhost.
+
+Subscribe to ntfy.sh topics and forward messages to your local endpoint. Perfect for AI agents that need real-time notifications without exposing public webhooks.
+
+```
+ntfy.sh → ntfy-bridge (local) → localhost:8080
+```
+
+## Install
+
+```bash
+npm install -g ntfy-bridge
+```
+
+Or run directly with npx:
+
+```bash
+npx ntfy-bridge --topic alerts --forward http://localhost:8080/hooks
+```
+
+## Usage
+
+```bash
+ntfy-bridge --topic <topic> --forward <url>
+```
+
+**Options:**
+- `-t, --topic <topic>` — ntfy.sh topic to subscribe (can repeat)
+- `-f, --forward <url>` — Local endpoint to forward messages to
+
+**Examples:**
+
+```bash
+# Single topic
+ntfy-bridge -t alerts -f http://localhost:8080/hooks
+
+# Multiple topics
+ntfy-bridge -t alerts -t news -f http://localhost:18789/hooks/ntfy
+
+# Full URL
+ntfy-bridge -t ntfy.sh/my-secret-topic -f http://localhost:8080/hooks
+
+# Self-hosted ntfy
+ntfy-bridge -t ntfy.example.com/alerts -f http://localhost:8080/hooks
+```
+
+## Payload Format
+
+Messages are normalized and forwarded as JSON:
+
+```json
+{
+  "source": "ntfy",
+  "topic": "alerts",
+  "id": "abc123",
+  "time": 1707379800,
+  "title": "Alert",
+  "message": "Something happened",
+  "tags": ["warning"],
+  "priority": 3,
+  "raw": { ... }
+}
+```
+
+## Use Cases
+
+- **AI Agents** — Feed real-time signals to OpenClaw, AutoGPT, etc.
+- **Automation** — Trigger local scripts from ntfy notifications
+- **Development** — Test webhook integrations locally
+
+## How It Works
+
+1. ntfy-bridge connects to ntfy.sh topics via SSE (outbound only)
+2. When a message arrives, it forwards to your local endpoint
+3. Your app receives the webhook on localhost
+
+No public endpoint needed. No firewall config. Just run locally.
+
+## Related
+
+For a managed signal marketplace with routing, billing, and delivery guarantees, see [Herald](https://github.com/starksama/herald).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import EventSource from "eventsource";
+import { normalizeTopicUrl, createPayload } from "./lib.js";
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const topics = [];
+    let forward = "";
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--topic" || arg === "-t") {
+            topics.push(args[++i]);
+        }
+        else if (arg === "--forward" || arg === "-f") {
+            forward = args[++i];
+        }
+        else if (arg === "--help" || arg === "-h") {
+            console.log(`
+ntfy-bridge - Local bridge from ntfy.sh to localhost
+
+Usage:
+  ntfy-bridge --topic <topic> --forward <url>
+
+Options:
+  -t, --topic <topic>    ntfy.sh topic to subscribe to (can be repeated)
+  -f, --forward <url>    Local endpoint to forward messages to
+  -h, --help             Show this help
+
+Examples:
+  ntfy-bridge -t alerts -f http://localhost:8080/hooks
+  ntfy-bridge -t ntfy.sh/my-topic -t ntfy.sh/other -f http://localhost:18789/hooks/ntfy
+`);
+            process.exit(0);
+        }
+    }
+    if (topics.length === 0) {
+        console.error("Error: No topics specified. Use --topic <topic>");
+        process.exit(1);
+    }
+    if (!forward) {
+        console.error("Error: No forward URL specified. Use --forward <url>");
+        process.exit(1);
+    }
+    return { topics, forward };
+}
+async function forwardMessage(msg, forwardUrl) {
+    const payload = createPayload(msg);
+    try {
+        const response = await fetch(forwardUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        if (response.ok) {
+            console.log(`[${msg.topic}] Forwarded: ${msg.title || msg.message || msg.id}`);
+        }
+        else {
+            console.warn(`[${msg.topic}] Forward returned ${response.status}`);
+        }
+    }
+    catch (error) {
+        console.error(`[${msg.topic}] Forward failed:`, error);
+    }
+}
+function subscribeToTopic(topic, forwardUrl) {
+    const url = normalizeTopicUrl(topic);
+    console.log(`Subscribing to: ${url}`);
+    const es = new EventSource(url);
+    es.onopen = () => {
+        console.log(`Connected to ${topic}`);
+    };
+    es.onmessage = async (event) => {
+        try {
+            const msg = JSON.parse(event.data);
+            if (msg.event === "message" || !msg.event) {
+                await forwardMessage(msg, forwardUrl);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to parse message:`, error);
+        }
+    };
+    es.onerror = (error) => {
+        console.error(`SSE error on ${topic}:`, error);
+        // EventSource auto-reconnects
+    };
+}
+function main() {
+    const { topics, forward } = parseArgs();
+    console.log("ntfy-bridge starting");
+    console.log(`Forwarding to: ${forward}`);
+    console.log(`Subscribing to ${topics.length} topic(s)`);
+    for (const topic of topics) {
+        subscribeToTopic(topic, forward);
+    }
+    // Keep alive
+    process.on("SIGINT", () => {
+        console.log("\nShutting down...");
+        process.exit(0);
+    });
+}
+main();

package/dist/lib.d.ts

@@ -0,0 +1,27 @@
+export interface NtfyMessage {
+    id: string;
+    time: number;
+    event?: string;
+    topic: string;
+    title?: string;
+    message?: string;
+    tags?: string[];
+    priority?: number;
+}
+export interface BridgePayload {
+    source: "ntfy";
+    topic: string;
+    id: string;
+    time: number;
+    title?: string;
+    message?: string;
+    tags: string[];
+    priority: number;
+    raw: NtfyMessage;
+}
+export declare function normalizeTopicUrl(topic: string): string;
+export declare function createPayload(msg: NtfyMessage): BridgePayload;
+export declare function parseArgs(argv: string[]): {
+    topics: string[];
+    forward: string;
+} | null;

package/dist/lib.js

@@ -0,0 +1,45 @@
+export function normalizeTopicUrl(topic) {
+    if (topic.startsWith("http")) {
+        return `${topic.replace(/\/$/, "")}/sse`;
+    }
+    else if (topic.includes("/")) {
+        return `https://${topic.replace(/\/$/, "")}/sse`;
+    }
+    else {
+        return `https://ntfy.sh/${topic}/sse`;
+    }
+}
+export function createPayload(msg) {
+    return {
+        source: "ntfy",
+        topic: msg.topic,
+        id: msg.id,
+        time: msg.time,
+        title: msg.title,
+        message: msg.message,
+        tags: msg.tags || [],
+        priority: msg.priority || 3,
+        raw: msg,
+    };
+}
+export function parseArgs(argv) {
+    const args = argv.slice(2);
+    const topics = [];
+    let forward = "";
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--topic" || arg === "-t") {
+            topics.push(args[++i]);
+        }
+        else if (arg === "--forward" || arg === "-f") {
+            forward = args[++i];
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return null; // Signal help requested
+        }
+    }
+    if (topics.length === 0 || !forward) {
+        return null;
+    }
+    return { topics, forward };
+}

package/dist/lib.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { normalizeTopicUrl, createPayload, parseArgs } from "./lib.js";
+describe("normalizeTopicUrl", () => {
+    it("handles full https URL", () => {
+        expect(normalizeTopicUrl("https://ntfy.sh/alerts")).toBe("https://ntfy.sh/alerts/sse");
+    });
+    it("handles full https URL with trailing slash", () => {
+        expect(normalizeTopicUrl("https://ntfy.sh/alerts/")).toBe("https://ntfy.sh/alerts/sse");
+    });
+    it("handles domain/topic format", () => {
+        expect(normalizeTopicUrl("ntfy.example.com/alerts")).toBe("https://ntfy.example.com/alerts/sse");
+    });
+    it("handles simple topic name (defaults to ntfy.sh)", () => {
+        expect(normalizeTopicUrl("alerts")).toBe("https://ntfy.sh/alerts/sse");
+    });
+    it("handles http URL", () => {
+        expect(normalizeTopicUrl("http://localhost:8080/test")).toBe("http://localhost:8080/test/sse");
+    });
+});
+describe("createPayload", () => {
+    it("creates payload with all fields", () => {
+        const msg = {
+            id: "abc123",
+            time: 1700000000,
+            event: "message",
+            topic: "alerts",
+            title: "Test Title",
+            message: "Test message",
+            tags: ["warning", "test"],
+            priority: 4,
+        };
+        const payload = createPayload(msg);
+        expect(payload.source).toBe("ntfy");
+        expect(payload.topic).toBe("alerts");
+        expect(payload.id).toBe("abc123");
+        expect(payload.time).toBe(1700000000);
+        expect(payload.title).toBe("Test Title");
+        expect(payload.message).toBe("Test message");
+        expect(payload.tags).toEqual(["warning", "test"]);
+        expect(payload.priority).toBe(4);
+        expect(payload.raw).toEqual(msg);
+    });
+    it("uses defaults for missing optional fields", () => {
+        const msg = {
+            id: "xyz",
+            time: 1700000000,
+            topic: "test",
+        };
+        const payload = createPayload(msg);
+        expect(payload.tags).toEqual([]);
+        expect(payload.priority).toBe(3);
+        expect(payload.title).toBeUndefined();
+        expect(payload.message).toBeUndefined();
+    });
+});
+describe("parseArgs", () => {
+    it("parses topic and forward", () => {
+        const result = parseArgs(["node", "script", "-t", "alerts", "-f", "http://localhost:8080"]);
+        expect(result).toEqual({
+            topics: ["alerts"],
+            forward: "http://localhost:8080",
+        });
+    });
+    it("parses multiple topics", () => {
+        const result = parseArgs([
+            "node", "script",
+            "--topic", "alerts",
+            "--topic", "news",
+            "--forward", "http://localhost:8080"
+        ]);
+        expect(result).toEqual({
+            topics: ["alerts", "news"],
+            forward: "http://localhost:8080",
+        });
+    });
+    it("returns null for help flag", () => {
+        const result = parseArgs(["node", "script", "--help"]);
+        expect(result).toBeNull();
+    });
+    it("returns null if missing topics", () => {
+        const result = parseArgs(["node", "script", "-f", "http://localhost"]);
+        expect(result).toBeNull();
+    });
+    it("returns null if missing forward", () => {
+        const result = parseArgs(["node", "script", "-t", "alerts"]);
+        expect(result).toBeNull();
+    });
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ntfy-bridge",
+  "version": "0.1.0",
+  "description": "Local bridge from ntfy.sh to localhost",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ntfy-bridge": "dist/index.js"
+  },
+  "keywords": [
+    "ntfy",
+    "notifications",
+    "webhook",
+    "bridge",
+    "localhost",
+    "ai-agents"
+  ],
+  "author": "starksama",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starksama/ntfy-bridge.git"
+  },
+  "dependencies": {
+    "eventsource": "^2.0.2"
+  },
+  "devDependencies": {
+    "@types/eventsource": "^1.1.15",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+import EventSource from "eventsource";
+import { normalizeTopicUrl, createPayload, NtfyMessage } from "./lib.js";
+
+function parseArgs(): { topics: string[]; forward: string } {
+  const args = process.argv.slice(2);
+  const topics: string[] = [];
+  let forward = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--topic" || arg === "-t") {
+      topics.push(args[++i]);
+    } else if (arg === "--forward" || arg === "-f") {
+      forward = args[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      console.log(`
+ntfy-bridge - Local bridge from ntfy.sh to localhost
+
+Usage:
+  ntfy-bridge --topic <topic> --forward <url>
+
+Options:
+  -t, --topic <topic>    ntfy.sh topic to subscribe to (can be repeated)
+  -f, --forward <url>    Local endpoint to forward messages to
+  -h, --help             Show this help
+
+Examples:
+  ntfy-bridge -t alerts -f http://localhost:8080/hooks
+  ntfy-bridge -t ntfy.sh/my-topic -t ntfy.sh/other -f http://localhost:18789/hooks/ntfy
+`);
+      process.exit(0);
+    }
+  }
+
+  if (topics.length === 0) {
+    console.error("Error: No topics specified. Use --topic <topic>");
+    process.exit(1);
+  }
+  if (!forward) {
+    console.error("Error: No forward URL specified. Use --forward <url>");
+    process.exit(1);
+  }
+
+  return { topics, forward };
+}
+
+async function forwardMessage(
+  msg: NtfyMessage,
+  forwardUrl: string
+): Promise<void> {
+  const payload = createPayload(msg);
+
+  try {
+    const response = await fetch(forwardUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (response.ok) {
+      console.log(`[${msg.topic}] Forwarded: ${msg.title || msg.message || msg.id}`);
+    } else {
+      console.warn(`[${msg.topic}] Forward returned ${response.status}`);
+    }
+  } catch (error) {
+    console.error(`[${msg.topic}] Forward failed:`, error);
+  }
+}
+
+function subscribeToTopic(topic: string, forwardUrl: string): void {
+  const url = normalizeTopicUrl(topic);
+  console.log(`Subscribing to: ${url}`);
+
+  const es = new EventSource(url);
+
+  es.onopen = () => {
+    console.log(`Connected to ${topic}`);
+  };
+
+  es.onmessage = async (event) => {
+    try {
+      const msg: NtfyMessage = JSON.parse(event.data);
+      if (msg.event === "message" || !msg.event) {
+        await forwardMessage(msg, forwardUrl);
+      }
+    } catch (error) {
+      console.warn(`Failed to parse message:`, error);
+    }
+  };
+
+  es.onerror = (error) => {
+    console.error(`SSE error on ${topic}:`, error);
+    // EventSource auto-reconnects
+  };
+}
+
+function main(): void {
+  const { topics, forward } = parseArgs();
+
+  console.log("ntfy-bridge starting");
+  console.log(`Forwarding to: ${forward}`);
+  console.log(`Subscribing to ${topics.length} topic(s)`);
+
+  for (const topic of topics) {
+    subscribeToTopic(topic, forward);
+  }
+
+  // Keep alive
+  process.on("SIGINT", () => {
+    console.log("\nShutting down...");
+    process.exit(0);
+  });
+}
+
+main();

package/src/lib.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { normalizeTopicUrl, createPayload, parseArgs, NtfyMessage } from "./lib.js";
+
+describe("normalizeTopicUrl", () => {
+  it("handles full https URL", () => {
+    expect(normalizeTopicUrl("https://ntfy.sh/alerts")).toBe(
+      "https://ntfy.sh/alerts/sse"
+    );
+  });
+
+  it("handles full https URL with trailing slash", () => {
+    expect(normalizeTopicUrl("https://ntfy.sh/alerts/")).toBe(
+      "https://ntfy.sh/alerts/sse"
+    );
+  });
+
+  it("handles domain/topic format", () => {
+    expect(normalizeTopicUrl("ntfy.example.com/alerts")).toBe(
+      "https://ntfy.example.com/alerts/sse"
+    );
+  });
+
+  it("handles simple topic name (defaults to ntfy.sh)", () => {
+    expect(normalizeTopicUrl("alerts")).toBe("https://ntfy.sh/alerts/sse");
+  });
+
+  it("handles http URL", () => {
+    expect(normalizeTopicUrl("http://localhost:8080/test")).toBe(
+      "http://localhost:8080/test/sse"
+    );
+  });
+});
+
+describe("createPayload", () => {
+  it("creates payload with all fields", () => {
+    const msg: NtfyMessage = {
+      id: "abc123",
+      time: 1700000000,
+      event: "message",
+      topic: "alerts",
+      title: "Test Title",
+      message: "Test message",
+      tags: ["warning", "test"],
+      priority: 4,
+    };
+
+    const payload = createPayload(msg);
+
+    expect(payload.source).toBe("ntfy");
+    expect(payload.topic).toBe("alerts");
+    expect(payload.id).toBe("abc123");
+    expect(payload.time).toBe(1700000000);
+    expect(payload.title).toBe("Test Title");
+    expect(payload.message).toBe("Test message");
+    expect(payload.tags).toEqual(["warning", "test"]);
+    expect(payload.priority).toBe(4);
+    expect(payload.raw).toEqual(msg);
+  });
+
+  it("uses defaults for missing optional fields", () => {
+    const msg: NtfyMessage = {
+      id: "xyz",
+      time: 1700000000,
+      topic: "test",
+    };
+
+    const payload = createPayload(msg);
+
+    expect(payload.tags).toEqual([]);
+    expect(payload.priority).toBe(3);
+    expect(payload.title).toBeUndefined();
+    expect(payload.message).toBeUndefined();
+  });
+});
+
+describe("parseArgs", () => {
+  it("parses topic and forward", () => {
+    const result = parseArgs(["node", "script", "-t", "alerts", "-f", "http://localhost:8080"]);
+    expect(result).toEqual({
+      topics: ["alerts"],
+      forward: "http://localhost:8080",
+    });
+  });
+
+  it("parses multiple topics", () => {
+    const result = parseArgs([
+      "node", "script",
+      "--topic", "alerts",
+      "--topic", "news",
+      "--forward", "http://localhost:8080"
+    ]);
+    expect(result).toEqual({
+      topics: ["alerts", "news"],
+      forward: "http://localhost:8080",
+    });
+  });
+
+  it("returns null for help flag", () => {
+    const result = parseArgs(["node", "script", "--help"]);
+    expect(result).toBeNull();
+  });
+
+  it("returns null if missing topics", () => {
+    const result = parseArgs(["node", "script", "-f", "http://localhost"]);
+    expect(result).toBeNull();
+  });
+
+  it("returns null if missing forward", () => {
+    const result = parseArgs(["node", "script", "-t", "alerts"]);
+    expect(result).toBeNull();
+  });
+});

package/src/lib.ts

@@ -0,0 +1,69 @@
+export interface NtfyMessage {
+  id: string;
+  time: number;
+  event?: string;
+  topic: string;
+  title?: string;
+  message?: string;
+  tags?: string[];
+  priority?: number;
+}
+
+export interface BridgePayload {
+  source: "ntfy";
+  topic: string;
+  id: string;
+  time: number;
+  title?: string;
+  message?: string;
+  tags: string[];
+  priority: number;
+  raw: NtfyMessage;
+}
+
+export function normalizeTopicUrl(topic: string): string {
+  if (topic.startsWith("http")) {
+    return `${topic.replace(/\/$/, "")}/sse`;
+  } else if (topic.includes("/")) {
+    return `https://${topic.replace(/\/$/, "")}/sse`;
+  } else {
+    return `https://ntfy.sh/${topic}/sse`;
+  }
+}
+
+export function createPayload(msg: NtfyMessage): BridgePayload {
+  return {
+    source: "ntfy",
+    topic: msg.topic,
+    id: msg.id,
+    time: msg.time,
+    title: msg.title,
+    message: msg.message,
+    tags: msg.tags || [],
+    priority: msg.priority || 3,
+    raw: msg,
+  };
+}
+
+export function parseArgs(argv: string[]): { topics: string[]; forward: string } | null {
+  const args = argv.slice(2);
+  const topics: string[] = [];
+  let forward = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--topic" || arg === "-t") {
+      topics.push(args[++i]);
+    } else if (arg === "--forward" || arg === "-f") {
+      forward = args[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      return null; // Signal help requested
+    }
+  }
+
+  if (topics.length === 0 || !forward) {
+    return null;
+  }
+
+  return { topics, forward };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}