nostr-inbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeletor
+
+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,155 @@
+# nostr-inbox
+
+Unified Nostr notification stream for AI agents. Mentions, DMs, DVM requests, zaps, trust attestations, marketplace events — one event loop instead of polling five things.
+
+## Install
+
+```bash
+npm install nostr-inbox
+```
+
+## Quick Start
+
+### Streaming (long-running)
+
+```javascript
+const { createInbox } = require('nostr-inbox');
+
+const inbox = createInbox({
+  pubkey: 'your-hex-pubkey',
+  relays: ['wss://relay.damus.io', 'wss://nos.lol']
+});
+
+inbox.on('notification', (n) => {
+  console.log(`[${n.type}] from ${n.from.slice(0, 12)}... — ${n.content}`);
+});
+
+// High-priority only (DMs, DVM requests, marketplace bids)
+inbox.on('urgent', (n) => {
+  console.log(`🔴 URGENT: ${n.type} from ${n.from.slice(0, 12)}...`);
+});
+
+// Type-specific handlers
+inbox.on('zap', (n) => console.log(`⚡ Zapped!`));
+inbox.on('dvm_request', (n) => console.log(`⚙️ DVM job incoming`));
+inbox.on('trust', (n) => console.log(`🛡️ New trust attestation`));
+
+await inbox.start();
+```
+
+### Polling (one-shot)
+
+```javascript
+const { poll } = require('nostr-inbox');
+
+const result = await poll({
+  pubkey: 'your-hex-pubkey',
+  since: Math.floor(Date.now() / 1000) - 3600 // last hour
+});
+
+console.log(`${result.total} notifications (${result.urgent} urgent)`);
+
+for (const [type, items] of Object.entries(result.byType)) {
+  console.log(`  ${type}: ${items.length}`);
+}
+```
+
+## CLI
+
+```bash
+# Watch real-time notifications
+nostr-inbox watch --pubkey <hex>
+
+# One-shot poll (last hour)
+nostr-inbox poll --pubkey <hex>
+
+# Filter by channel
+nostr-inbox watch --pubkey <hex> --channels mentions,dms,zaps
+
+# JSON output (for piping)
+nostr-inbox poll --pubkey <hex> --json
+
+# Only urgent notifications
+nostr-inbox watch --pubkey <hex> --quiet
+```
+
+## Notification Types
+
+| Type | Kind(s) | Priority | Description |
+|------|---------|----------|-------------|
+| `mention` | 1, 1111 | medium | Text notes / Clawstr comments tagging you |
+| `dm` | 4, 1059 | **high** | Encrypted DMs (NIP-04 + NIP-17 gift wrap) |
+| `dvm_request` | 5000-5099 | **high** | Someone wants you to do work (NIP-90) |
+| `dvm_result` | 6000-6099 | medium | Response to your DVM request |
+| `dvm_feedback` | 7000 | low | DVM processing status |
+| `zap` | 9735 | medium | Lightning zap receipt |
+| `reaction` | 7 | low | Likes / reactions |
+| `trust` | 1985 | medium | ai.wot attestation about you |
+| `trust_network` | 1985 | low | ai.wot attestation about others |
+| `marketplace_bid` | 950 | **high** | Bid on your task (agent-escrow) |
+| `marketplace_delivery` | 951 | **high** | Work submitted for your task |
+| `marketplace_resolution` | 952 | **high** | Task approved / disputed |
+
+## Channels
+
+Enable/disable notification types:
+
+```javascript
+const inbox = createInbox({
+  pubkey: '...',
+  channels: {
+    mentions: true,      // Text note mentions
+    dms: true,           // Encrypted DMs
+    dvmRequests: true,   // DVM work requests
+    dvmResults: true,    // DVM results
+    zaps: true,          // Lightning zaps
+    reactions: false,    // Likes (noisy, disable if you want)
+    trust: true,         // ai.wot attestations
+    marketplace: true    // agent-escrow events
+  }
+});
+```
+
+## API
+
+### `createInbox(opts)` → `inbox`
+
+Creates a streaming inbox.
+
+**Options:**
+- `pubkey` (string, required) — Your hex pubkey
+- `relays` (string[]) — Relay URLs (default: damus, nos.lol, primal)
+- `channels` (object) — Enable/disable notification types
+- `since` (number) — Unix timestamp, only events after this
+- `dedup` (boolean) — Deduplicate events (default: true)
+- `reconnectMs` (number) — Reconnect delay (default: 5000)
+
+**Methods:**
+- `inbox.start()` — Connect and begin streaming
+- `inbox.stop()` — Disconnect
+- `inbox.status()` — Get connection status
+- `inbox.waitFor(type, timeoutMs)` — Promise that resolves on next event of type
+- `inbox.collect(durationMs, filter)` — Collect events for a duration
+
+**Events:**
+- `notification` — Every notification
+- `urgent` — High-priority only
+- `<type>` — Type-specific (e.g., `zap`, `dm`, `dvm_request`)
+- `connected` / `started` / `stopped` — Lifecycle
+- `error` — Connection errors
+
+### `poll(opts)` → `{ total, urgent, notifications, byType }`
+
+One-shot fetch. Same options as `createInbox` plus `timeoutMs`.
+
+## Interop
+
+Built for the agent economy stack:
+- [agent-escrow](https://github.com/jeletor/agent-escrow) — Marketplace events (bids, deliveries, resolutions)
+- [ai-wot](https://github.com/jeletor/ai-wot) — Trust attestation notifications
+- [agent-discovery](https://github.com/jeletor/agent-discovery) — Service announcements
+- [lightning-agent](https://github.com/jeletor/lightning-agent) — Zap handling
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "nostr-inbox",
+  "version": "0.1.0",
+  "description": "Unified Nostr notification stream for AI agents — mentions, DMs, DVM requests, zaps, WoT attestations in one event loop",
+  "main": "src/index.cjs",
+  "bin": {
+    "nostr-inbox": "src/cli.cjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs"
+  },
+  "keywords": [
+    "nostr",
+    "notifications",
+    "inbox",
+    "ai",
+    "agent",
+    "dvm",
+    "nip-90",
+    "zap",
+    "mentions",
+    "ai-wot",
+    "lightning",
+    "streaming"
+  ],
+  "author": "Jeletor <jeletor@jeletor.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeletor/nostr-inbox.git"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.12.0",
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cli.cjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createInbox, poll, KINDS } = require('./index.cjs');
+
+const PRIORITY_COLORS = {
+  high: '\x1b[31m',    // red
+  medium: '\x1b[33m',  // yellow
+  low: '\x1b[90m'      // gray
+};
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+
+function usage() {
+  console.log(`nostr-inbox — Unified Nostr notification stream for AI agents
+
+Usage:
+  nostr-inbox watch [options]    Stream notifications in real-time
+  nostr-inbox poll [options]     One-shot check (fetch and exit)
+  nostr-inbox help               Show this help
+
+Options:
+  --pubkey <hex>          Your Nostr pubkey (hex)
+  --relays <urls>         Comma-separated relay URLs
+  --since <timestamp>     Only events after this Unix timestamp
+  --since-ago <seconds>   Events from N seconds ago (default: 3600)
+  --channels <types>      Comma-separated: mentions,dms,dvmRequests,dvmResults,zaps,reactions,trust,marketplace
+  --json                  Output raw JSON (one per line)
+  --quiet                 Only show urgent notifications
+
+Environment:
+  NOSTR_PUBKEY           Your pubkey (hex)
+  NOSTR_RELAYS           Comma-separated relay URLs
+`);
+}
+
+function parseArgs(args) {
+  const result = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+      result[key] = val;
+    } else {
+      result._.push(args[i]);
+    }
+  }
+  return result;
+}
+
+function parseChannels(str) {
+  if (!str) return {};
+  const channels = {};
+  // Start with all disabled, enable only specified
+  const allOff = {
+    mentions: false, dms: false, dvmRequests: false, dvmResults: false,
+    zaps: false, reactions: false, trust: false, marketplace: false
+  };
+  for (const ch of str.split(',')) {
+    allOff[ch.trim()] = true;
+  }
+  return allOff;
+}
+
+function formatNotification(n) {
+  const color = PRIORITY_COLORS[n.priority] || '';
+  const time = new Date(n.createdAt).toISOString().slice(11, 19);
+  const from = n.from.slice(0, 12) + '...';
+  const content = n.content ? n.content.slice(0, 120).replace(/\n/g, ' ') : '';
+
+  const typeIcons = {
+    mention: '💬',
+    dm: '✉️',
+    dvm_request: '⚙️',
+    dvm_result: '📦',
+    dvm_feedback: '📝',
+    zap: '⚡',
+    reaction: '❤️',
+    trust: '🛡️',
+    trust_network: '🌐',
+    marketplace_bid: '💰',
+    marketplace_delivery: '📋',
+    marketplace_resolution: '✅',
+    unknown: '❓'
+  };
+
+  const icon = typeIcons[n.type] || '❓';
+  return `${color}[${time}] ${icon} ${BOLD}${n.type}${RESET}${color} from ${from}${RESET}  ${content}`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0] || 'help';
+
+  if (command === 'help' || args.help) {
+    usage();
+    return;
+  }
+
+  const pubkey = args.pubkey || process.env.NOSTR_PUBKEY;
+  if (!pubkey) {
+    console.error('Error: --pubkey or NOSTR_PUBKEY required');
+    process.exit(1);
+  }
+
+  const relays = (args.relays || process.env.NOSTR_RELAYS || 'wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net').split(',');
+  const channels = args.channels ? parseChannels(args.channels) : {};
+  const json = args.json === true;
+  const quiet = args.quiet === true;
+
+  if (command === 'poll') {
+    const sinceAgo = args['since-ago'] ? parseInt(args['since-ago'], 10) : 3600;
+    const since = args.since ? parseInt(args.since, 10) : Math.floor(Date.now() / 1000) - sinceAgo;
+
+    const result = await poll({ pubkey, relays, channels, since });
+
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`\n📬 ${result.total} notifications (${result.urgent} urgent) since ${new Date(since * 1000).toISOString()}\n`);
+
+      if (result.total === 0) {
+        console.log('  Nothing new.');
+        return;
+      }
+
+      // Group display
+      for (const [type, items] of Object.entries(result.byType)) {
+        console.log(`  ${type} (${items.length}):`);
+        for (const n of items.slice(0, 10)) {
+          console.log(`    ${formatNotification(n)}`);
+        }
+        if (items.length > 10) console.log(`    ... and ${items.length - 10} more`);
+        console.log();
+      }
+    }
+    return;
+  }
+
+  if (command === 'watch') {
+    const sinceAgo = args['since-ago'] ? parseInt(args['since-ago'], 10) : 60;
+    const since = args.since ? parseInt(args.since, 10) : Math.floor(Date.now() / 1000) - sinceAgo;
+
+    const inbox = createInbox({
+      pubkey,
+      relays,
+      channels,
+      since
+    });
+
+    inbox.on('connected', ({ relay }) => {
+      if (!json) console.log(`  ✓ Connected to ${relay}`);
+    });
+
+    inbox.on('started', ({ connected, total }) => {
+      if (!json) console.log(`\n📬 Watching ${connected}/${total} relays. Ctrl+C to stop.\n`);
+    });
+
+    inbox.on('notification', (n) => {
+      if (quiet && n.priority !== 'high') return;
+      if (json) {
+        console.log(JSON.stringify(n));
+      } else {
+        console.log(formatNotification(n));
+      }
+    });
+
+    inbox.on('error', ({ relay, error }) => {
+      if (!json) console.error(`  ✗ ${relay}: ${error}`);
+    });
+
+    await inbox.start();
+
+    // Graceful shutdown
+    process.on('SIGINT', () => {
+      inbox.stop();
+      console.log('\n👋 Stopped.');
+      process.exit(0);
+    });
+
+    // Keep alive
+    await new Promise(() => {});
+  }
+
+  console.error(`Unknown command: ${command}`);
+  usage();
+  process.exit(1);
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/src/filters.cjs

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * Nostr event kinds we care about
+ */
+const KINDS = {
+  // Core
+  TEXT_NOTE: 1,
+  DM_ENCRYPTED: 4,       // NIP-04 encrypted DM
+  REACTION: 7,
+  
+  // DVM (NIP-90)
+  DVM_REQUEST_BASE: 5000, // 5000-5999
+  DVM_RESULT_BASE: 6000,  // 6000-6999
+  DVM_FEEDBACK: 7000,
+
+  // Zaps (NIP-57)
+  ZAP_RECEIPT: 9735,
+  ZAP_REQUEST: 9734,
+
+  // Trust (ai.wot)
+  LABEL: 1985,            // NIP-32
+
+  // Gift wrap DM (NIP-17)
+  GIFT_WRAP: 1059,
+  SEAL: 13,
+
+  // Agent discovery
+  AGENT_SERVICE: 38990,   // agent-discovery kind
+
+  // Marketplace (agent-escrow)
+  TASK: 30950,
+  BID: 950,
+  DELIVERY: 951,
+  RESOLUTION: 952,
+
+  // Clawstr (NIP-22)
+  COMMENT: 1111
+};
+
+/**
+ * Build subscription filters for a pubkey
+ *
+ * @param {string} pubkey - Hex pubkey to watch
+ * @param {Object} channels - Which notification channels to enable
+ * @param {number} [since] - Unix timestamp, only events after this
+ */
+function buildFilters(pubkey, channels = {}, since = null) {
+  const {
+    mentions = true,
+    dms = true,
+    dvmRequests = true,
+    dvmResults = true,
+    zaps = true,
+    reactions = true,
+    trust = true,
+    marketplace = true
+  } = channels;
+
+  const filters = [];
+  const sinceObj = since ? { since } : {};
+
+  // Mentions: kind 1 events that tag our pubkey
+  if (mentions) {
+    filters.push({
+      kinds: [KINDS.TEXT_NOTE, KINDS.COMMENT],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // DMs: kind 4 events addressed to us
+  if (dms) {
+    filters.push({
+      kinds: [KINDS.DM_ENCRYPTED],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+    // Also gift-wrapped DMs (NIP-17)
+    filters.push({
+      kinds: [KINDS.GIFT_WRAP],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // DVM requests: kind 5xxx tagged to us (we're a DVM provider)
+  if (dvmRequests) {
+    const dvmRequestKinds = [];
+    for (let k = 5000; k < 5100; k++) dvmRequestKinds.push(k);
+    filters.push({
+      kinds: dvmRequestKinds,
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // DVM results: kind 6xxx tagged to us (we requested something)
+  if (dvmResults) {
+    const dvmResultKinds = [];
+    for (let k = 6000; k < 6100; k++) dvmResultKinds.push(k);
+    filters.push({
+      kinds: dvmResultKinds,
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // Zaps: receipts tagged to our pubkey
+  if (zaps) {
+    filters.push({
+      kinds: [KINDS.ZAP_RECEIPT],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // Reactions: to our events (tagged with our pubkey)
+  if (reactions) {
+    filters.push({
+      kinds: [KINDS.REACTION],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  // Trust: ai.wot attestations about us
+  if (trust) {
+    filters.push({
+      kinds: [KINDS.LABEL],
+      '#p': [pubkey],
+      '#L': ['ai.wot'],
+      ...sinceObj
+    });
+  }
+
+  // Marketplace: tasks tagged to us, bids on our tasks, deliveries, resolutions
+  if (marketplace) {
+    filters.push({
+      kinds: [KINDS.BID, KINDS.DELIVERY, KINDS.RESOLUTION],
+      '#p': [pubkey],
+      ...sinceObj
+    });
+  }
+
+  return filters;
+}
+
+/**
+ * Classify an event into a notification type
+ */
+function classifyEvent(event, myPubkey) {
+  const kind = event.kind;
+
+  // DMs
+  if (kind === KINDS.DM_ENCRYPTED || kind === KINDS.GIFT_WRAP) {
+    return { type: 'dm', priority: 'high' };
+  }
+
+  // DVM requests (someone wants us to do work)
+  if (kind >= 5000 && kind < 6000) {
+    return { type: 'dvm_request', priority: 'high', dvmKind: kind };
+  }
+
+  // DVM results (response to our request)
+  if (kind >= 6000 && kind < 7000) {
+    return { type: 'dvm_result', priority: 'medium', dvmKind: kind - 1000 };
+  }
+
+  // DVM feedback
+  if (kind === KINDS.DVM_FEEDBACK) {
+    return { type: 'dvm_feedback', priority: 'low' };
+  }
+
+  // Zaps
+  if (kind === KINDS.ZAP_RECEIPT) {
+    return { type: 'zap', priority: 'medium' };
+  }
+
+  // Trust attestations
+  if (kind === KINDS.LABEL) {
+    const isAboutMe = event.tags.some(t => t[0] === 'p' && t[1] === myPubkey);
+    if (isAboutMe) {
+      return { type: 'trust', priority: 'medium' };
+    }
+    return { type: 'trust_network', priority: 'low' };
+  }
+
+  // Marketplace
+  if (kind === KINDS.BID) return { type: 'marketplace_bid', priority: 'high' };
+  if (kind === KINDS.DELIVERY) return { type: 'marketplace_delivery', priority: 'high' };
+  if (kind === KINDS.RESOLUTION) return { type: 'marketplace_resolution', priority: 'high' };
+
+  // Reactions
+  if (kind === KINDS.REACTION) {
+    return { type: 'reaction', priority: 'low' };
+  }
+
+  // Mentions (text notes / comments that tag us)
+  if (kind === KINDS.TEXT_NOTE || kind === KINDS.COMMENT) {
+    return { type: 'mention', priority: 'medium' };
+  }
+
+  return { type: 'unknown', priority: 'low' };
+}
+
+module.exports = { KINDS, buildFilters, classifyEvent };

package/src/inbox.cjs

@@ -0,0 +1,245 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { Relay, useWebSocketImplementation } = require('nostr-tools/relay');
+const { buildFilters, classifyEvent } = require('./filters.cjs');
+
+// Use ws in Node.js
+try {
+  const WebSocket = require('ws');
+  useWebSocketImplementation(WebSocket);
+} catch (e) {
+  // Browser environment
+}
+
+/**
+ * Create an inbox that streams Nostr notifications
+ *
+ * @param {Object} opts
+ * @param {string} opts.pubkey - Your hex pubkey
+ * @param {string[]} [opts.relays] - Relay URLs
+ * @param {Object} [opts.channels] - Which notification types to enable
+ * @param {number} [opts.since] - Unix timestamp, only events after this
+ * @param {boolean} [opts.dedup] - Deduplicate events by ID (default: true)
+ * @param {Function} [opts.onEvent] - Callback for each event (alternative to EventEmitter)
+ * @param {Function} [opts.onError] - Error callback
+ * @param {number} [opts.reconnectMs] - Reconnect delay on disconnect (default: 5000)
+ * @param {number} [opts.connectTimeoutMs] - Connection timeout (default: 10000)
+ */
+function createInbox(opts) {
+  const {
+    pubkey,
+    relays: relayUrls = ['wss://relay.damus.io', 'wss://nos.lol', 'wss://relay.primal.net'],
+    channels = {},
+    since = null,
+    dedup = true,
+    onEvent = null,
+    onError = null,
+    reconnectMs = 5000,
+    connectTimeoutMs = 10000
+  } = opts;
+
+  if (!pubkey) throw new Error('pubkey is required');
+
+  const emitter = new EventEmitter();
+  const seen = new Set();      // Event ID dedup
+  const connectedRelays = [];  // Active relay connections
+  let running = false;
+  let latestTimestamp = since || Math.floor(Date.now() / 1000) - 60; // default: last minute
+
+  /**
+   * Process an incoming event
+   */
+  function handleEvent(event) {
+    // Dedup
+    if (dedup && seen.has(event.id)) return;
+    if (dedup) {
+      seen.add(event.id);
+      // Prevent memory leak — keep last 10k IDs
+      if (seen.size > 10000) {
+        const arr = Array.from(seen);
+        for (let i = 0; i < 5000; i++) seen.delete(arr[i]);
+      }
+    }
+
+    // Track latest timestamp for reconnection
+    if (event.created_at > latestTimestamp) {
+      latestTimestamp = event.created_at;
+    }
+
+    // Classify
+    const classification = classifyEvent(event, pubkey);
+
+    const notification = {
+      id: event.id,
+      type: classification.type,
+      priority: classification.priority,
+      from: event.pubkey,
+      content: event.content,
+      kind: event.kind,
+      tags: event.tags,
+      createdAt: event.created_at * 1000,
+      raw: event,
+      ...classification
+    };
+
+    // Emit
+    emitter.emit('notification', notification);
+    emitter.emit(classification.type, notification);
+    if (classification.priority === 'high') {
+      emitter.emit('urgent', notification);
+    }
+
+    // Callback
+    if (onEvent) {
+      try { onEvent(notification); } catch (e) { /* user error */ }
+    }
+  }
+
+  /**
+   * Connect to a single relay with auto-reconnect
+   */
+  async function connectRelay(url) {
+    try {
+      const relay = await Promise.race([
+        Relay.connect(url),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), connectTimeoutMs))
+      ]);
+
+      const filters = buildFilters(pubkey, channels, latestTimestamp);
+
+      relay.subscribe(filters, {
+        onevent: handleEvent,
+        oneose() {
+          // Initial sync complete for this relay
+          emitter.emit('synced', { relay: url });
+        }
+      });
+
+      connectedRelays.push({ url, relay });
+      emitter.emit('connected', { relay: url });
+
+      return relay;
+    } catch (err) {
+      const error = { relay: url, error: err.message };
+      emitter.emit('error', error);
+      if (onError) onError(error);
+
+      // Schedule reconnect
+      if (running) {
+        setTimeout(() => connectRelay(url), reconnectMs);
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Start the inbox — connect to all relays and begin streaming
+   */
+  async function start() {
+    if (running) return;
+    running = true;
+
+    emitter.emit('starting', { relays: relayUrls });
+
+    await Promise.allSettled(relayUrls.map(connectRelay));
+
+    emitter.emit('started', {
+      connected: connectedRelays.length,
+      total: relayUrls.length
+    });
+
+    return emitter;
+  }
+
+  /**
+   * Stop the inbox — close all connections
+   */
+  function stop() {
+    running = false;
+    for (const { relay } of connectedRelays) {
+      try { relay.close(); } catch (e) { /* ignore */ }
+    }
+    connectedRelays.length = 0;
+    emitter.emit('stopped');
+  }
+
+  /**
+   * Get current status
+   */
+  function status() {
+    return {
+      running,
+      relays: {
+        connected: connectedRelays.length,
+        total: relayUrls.length,
+        urls: connectedRelays.map(r => r.url)
+      },
+      seen: seen.size,
+      latestTimestamp,
+      channels
+    };
+  }
+
+  /**
+   * Wait for the next event of a specific type (promise-based)
+   */
+  function waitFor(type, timeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        emitter.off(type, handler);
+        reject(new Error(`Timeout waiting for ${type}`));
+      }, timeoutMs);
+
+      function handler(notification) {
+        clearTimeout(timer);
+        resolve(notification);
+      }
+
+      emitter.once(type, handler);
+    });
+  }
+
+  /**
+   * Collect events for a duration, then return them
+   */
+  function collect(durationMs = 5000, filter = null) {
+    return new Promise((resolve) => {
+      const events = [];
+
+      function handler(notification) {
+        if (!filter || filter(notification)) {
+          events.push(notification);
+        }
+      }
+
+      emitter.on('notification', handler);
+
+      setTimeout(() => {
+        emitter.off('notification', handler);
+        resolve(events);
+      }, durationMs);
+    });
+  }
+
+  return {
+    // Lifecycle
+    start,
+    stop,
+    status,
+
+    // EventEmitter interface
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+    once: emitter.once.bind(emitter),
+
+    // Utilities
+    waitFor,
+    collect,
+
+    // Direct access
+    emitter
+  };
+}
+
+module.exports = { createInbox };

package/src/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const { createInbox } = require('./inbox.cjs');
+const { poll } = require('./poller.cjs');
+const { KINDS, buildFilters, classifyEvent } = require('./filters.cjs');
+
+module.exports = {
+  // Main API
+  createInbox,
+  poll,
+
+  // Utilities
+  KINDS,
+  buildFilters,
+  classifyEvent
+};

package/src/poller.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+const { Relay, useWebSocketImplementation } = require('nostr-tools/relay');
+const { buildFilters, classifyEvent } = require('./filters.cjs');
+
+// Use ws in Node.js
+try {
+  const WebSocket = require('ws');
+  useWebSocketImplementation(WebSocket);
+} catch (e) {}
+
+/**
+ * One-shot poll: connect, fetch events since timestamp, disconnect
+ *
+ * Useful for agents that check periodically rather than streaming.
+ *
+ * @param {Object} opts
+ * @param {string} opts.pubkey - Your hex pubkey
+ * @param {string[]} [opts.relays] - Relay URLs
+ * @param {Object} [opts.channels] - Which notification types to check
+ * @param {number} [opts.since] - Unix timestamp
+ * @param {number} [opts.timeoutMs] - Query timeout
+ */
+async function poll(opts) {
+  const {
+    pubkey,
+    relays: relayUrls = ['wss://relay.damus.io', 'wss://nos.lol'],
+    channels = {},
+    since = Math.floor(Date.now() / 1000) - 3600, // default: last hour
+    timeoutMs = 10000
+  } = opts;
+
+  if (!pubkey) throw new Error('pubkey is required');
+
+  const events = new Map();
+  const filters = buildFilters(pubkey, channels, since);
+
+  // Connect to relays and collect events
+  const relayPromises = relayUrls.map(async (url) => {
+    try {
+      const relay = await Promise.race([
+        Relay.connect(url),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), timeoutMs))
+      ]);
+
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, timeoutMs);
+        relay.subscribe(filters, {
+          onevent(event) {
+            events.set(event.id, event);
+          },
+          oneose() {
+            clearTimeout(timer);
+            resolve();
+          }
+        });
+      });
+
+      try { relay.close(); } catch (e) {}
+    } catch (e) {
+      // Relay unavailable — skip
+    }
+  });
+
+  await Promise.allSettled(relayPromises);
+
+  // Classify and sort
+  const notifications = Array.from(events.values())
+    .map(event => {
+      const classification = classifyEvent(event, pubkey);
+      return {
+        id: event.id,
+        type: classification.type,
+        priority: classification.priority,
+        from: event.pubkey,
+        content: event.content,
+        kind: event.kind,
+        tags: event.tags,
+        createdAt: event.created_at * 1000,
+        raw: event,
+        ...classification
+      };
+    })
+    .sort((a, b) => b.createdAt - a.createdAt);
+
+  // Group by type
+  const byType = {};
+  for (const n of notifications) {
+    if (!byType[n.type]) byType[n.type] = [];
+    byType[n.type].push(n);
+  }
+
+  // Summary
+  const urgent = notifications.filter(n => n.priority === 'high');
+
+  return {
+    total: notifications.length,
+    urgent: urgent.length,
+    notifications,
+    byType,
+    since,
+    queriedAt: Date.now()
+  };
+}
+
+module.exports = { poll };