402-announce 0.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Crypto Donkey
+
+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,230 @@
+# 402-announce
+
+Announce HTTP 402 services on Nostr for decentralised discovery. Supports both L402 and x402 payment protocols.
+
+[![MIT Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](./LICENSE)
+
+Publishes **kind 31402** parameterised replaceable events so that AI agents (and any Nostr client) can discover paid APIs without a central registry.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Your API] -->|"npm install<br/>402-announce"| B[402-announce]
+    B -->|"kind 31402<br/>signed event"| C[(Nostr Relays)]
+    C -->|subscribe & filter| D[402-mcp]
+    D -->|discover + pay| A
+
+    style B fill:#f59e0b,color:#000
+    style C fill:#8b5cf6,color:#fff
+    style D fill:#3b82f6,color:#fff
+```
+
+Your API publishes a service announcement to Nostr relays. AI agents (via [402-mcp](https://github.com/TheCryptoDonkey/402-mcp)) discover it, pay the invoice, and consume the API. No central registry required.
+
+## Quick start
+
+```bash
+npm install 402-announce
+```
+
+```typescript
+import { announceService } from '402-announce'
+
+const handle = await announceService({
+  secretKey: '64-char-hex-nostr-secret-key',
+  relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],
+  identifier: 'jokes-api',
+  name: 'Jokes API',
+  url: 'https://jokes.example.com',
+  about: 'A joke-telling service behind an L402 paywall',
+  pricing: [
+    { capability: 'get_joke', price: 1, currency: 'sats' },
+  ],
+  paymentMethods: ['bitcoin-lightning-bolt11', 'bitcoin-cashu'],
+  topics: ['comedy', 'ai'],
+  capabilities: [
+    { name: 'get_joke', description: 'Returns a random joke' },
+  ],
+  version: '1.0.0',
+})
+
+console.log('Published event:', handle.eventId)
+console.log('From pubkey:', handle.pubkey)
+
+// Later, when shutting down:
+handle.close()
+```
+
+## Announce flow
+
+```mermaid
+flowchart TD
+    A[announceService config] --> B{Validate}
+    B -->|"secretKey: 64-char hex"| C[Derive pubkey]
+    B -->|"relays: wss:// URLs"| C
+    C --> D[Build kind 31402 event]
+    D --> E[Sign with secret key]
+    E --> F[Zeroise key bytes]
+    F --> G["Connect relays (parallel, 10s timeout)"]
+    G --> H{Each relay}
+    H -->|success| I[Publish event]
+    H -->|failure| J[Log warning, continue]
+    I --> K["Return { eventId, pubkey, close() }"]
+    J --> K
+```
+
+## Event format
+
+Each announcement is a **kind 31402** parameterised replaceable event. The combination of `pubkey` + `d` tag uniquely identifies a listing — publishing again with the same values updates the existing listing.
+
+```mermaid
+graph TB
+    subgraph "Kind 31402 Event"
+        direction TB
+        subgraph Tags
+            D["d: jokes-api"]
+            N["name: Jokes API"]
+            U["url: https://jokes.example.com"]
+            AB["about: A joke-telling service"]
+            PMI1["pmi: bitcoin-lightning-bolt11"]
+            PMI2["pmi: bitcoin-cashu"]
+            P["price: get_joke, 1, sats"]
+            T["t: comedy"]
+        end
+        subgraph Content["Content (JSON)"]
+            CAP["capabilities: [{ name, description }]"]
+            VER["version: 1.0.0"]
+        end
+    end
+
+    style Tags fill:#1e293b,color:#e2e8f0
+    style Content fill:#1e293b,color:#e2e8f0
+```
+
+### Tags
+
+| Tag       | Required | Description                                  | Example                           |
+|-----------|----------|----------------------------------------------|-----------------------------------|
+| `d`       | yes      | Unique identifier for this listing           | `jokes-api`                       |
+| `name`    | yes      | Human-readable service name                  | `Jokes API`                       |
+| `url`     | yes      | HTTP endpoint for the 402 service            | `https://jokes.example.com`       |
+| `about`   | yes      | Short description                            | `A joke-telling service`          |
+| `pmi`     | yes      | Payment method identifier (repeatable)       | `bitcoin-lightning-bolt11`        |
+| `price`   | yes      | Capability pricing (repeatable)              | `get_joke`, `1`, `sats`           |
+| `t`       | no       | Topic tag for search/filtering (repeatable)  | `comedy`                          |
+| `picture` | no       | Icon URL                                     | `https://example.com/icon.png`    |
+
+### Content
+
+The event content is a JSON object with optional fields:
+
+```json
+{
+  "capabilities": [
+    { "name": "get_joke", "description": "Returns a random joke" }
+  ],
+  "version": "1.0.0"
+}
+```
+
+## API
+
+### `announceService(config): Promise<Announcement>`
+
+High-level function that builds, signs, and publishes the event to multiple relays.
+
+**Returns** an `Announcement` handle:
+- `eventId` — the published Nostr event ID
+- `pubkey` — the Nostr pubkey derived from your secret key
+- `close()` — disconnect from all relays
+
+### `buildAnnounceEvent(secretKey, config): VerifiedEvent`
+
+Lower-level function that builds and signs the event without publishing. Useful if you manage relay connections yourself.
+
+### Config options
+
+| Field            | Type              | Required | Description                                    |
+|------------------|-------------------|----------|------------------------------------------------|
+| `secretKey`      | `string`          | yes      | 64-char hex Nostr secret key                   |
+| `relays`         | `string[]`        | yes      | Relay URLs (`wss://` or `ws://`)               |
+| `identifier`     | `string`          | yes      | Unique listing ID (Nostr `d` tag)              |
+| `name`           | `string`          | yes      | Human-readable service name                    |
+| `url`            | `string`          | yes      | HTTP endpoint for the service                  |
+| `about`          | `string`          | yes      | Short description                              |
+| `pricing`        | `PricingDef[]`    | yes      | Per-capability pricing                         |
+| `paymentMethods` | `string[]`        | yes      | Accepted payment methods                       |
+| `picture`        | `string`          | no       | Icon URL                                       |
+| `topics`         | `string[]`        | no       | Topic tags for filtering                       |
+| `capabilities`   | `CapabilityDef[]` | no       | Capability details (stored in event content)   |
+| `version`        | `string`          | no       | Service version (stored in event content)      |
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    subgraph "Your Server"
+        API[Your API]
+        TB[toll-booth<br/>L402 paywall]
+        AN[402-announce]
+    end
+
+    subgraph "Nostr Network"
+        R1[(Relay 1)]
+        R2[(Relay 2)]
+    end
+
+    subgraph "AI Agent"
+        MCP[402-mcp<br/>discovery + payment]
+    end
+
+    API --> TB
+    TB -->|"protects"| API
+    AN -->|"kind 31402"| R1
+    AN -->|"kind 31402"| R2
+    R1 -->|"subscribe"| MCP
+    R2 -->|"subscribe"| MCP
+    MCP -->|"HTTP + L402 token"| TB
+
+    style TB fill:#ef4444,color:#fff
+    style AN fill:#f59e0b,color:#000
+    style MCP fill:#3b82f6,color:#fff
+```
+
+1. **[toll-booth](https://github.com/TheCryptoDonkey/toll-booth)** wraps your API with an L402 paywall
+2. **402-announce** publishes a kind 31402 event describing the service, pricing, and payment methods
+3. **[402-mcp](https://github.com/TheCryptoDonkey/402-mcp)** discovers the announcement, pays the invoice, and calls your API
+
+## Security
+
+- Secret key bytes are zeroised immediately after signing (in both `announceService` and `buildAnnounceEvent`)
+- Never log or persist the secret key — pass it in and let the library handle cleanup
+- Relay connections use a 10-second timeout to prevent hanging
+- Individual relay failures are logged as warnings but don't reject the promise
+
+## What it does
+
+- Builds and signs kind 31402 Nostr events
+- Publishes to one or more Nostr relays in parallel
+- Zeroises secret key bytes after use
+- Degrades gracefully when individual relays fail
+- Provides a `close()` handle for clean disconnection
+
+## What it does not do
+
+- Does not run an L402 paywall (use [toll-booth](https://github.com/TheCryptoDonkey/toll-booth) for that)
+- Does not subscribe to or search for announcements (use [402-mcp](https://github.com/TheCryptoDonkey/402-mcp) for that)
+- Does not handle payments or token verification
+
+## Ecosystem
+
+| Package | Purpose |
+|---------|---------|
+| [toll-booth](https://github.com/TheCryptoDonkey/toll-booth) | L402 middleware — any API becomes a toll booth in minutes |
+| [satgate](https://github.com/TheCryptoDonkey/satsgate) | Production L402 gateway with Lightning and Cashu support |
+| [402-mcp](https://github.com/TheCryptoDonkey/402-mcp) | MCP server for AI agents to discover, pay, and consume 402 APIs |
+
+## Licence
+
+[MIT](./LICENSE)

package/build/announce.d.ts

@@ -0,0 +1,13 @@
+import type { AnnounceConfig, Announcement } from './types.js';
+/**
+ * Publish a kind 31402 L402 service announcement to Nostr relays.
+ *
+ * Connects to each relay, publishes the signed event, and returns an
+ * {@link Announcement} handle whose `close()` method disconnects all relays.
+ *
+ * Relay failures are logged but do not reject the promise -- the function
+ * degrades gracefully. A warning is emitted if *no* relay accepted the event.
+ *
+ * @throws If the relay list is empty or contains invalid URLs.
+ */
+export declare function announceService(config: AnnounceConfig): Promise<Announcement>;

package/build/announce.js

@@ -0,0 +1,70 @@
+import { getPublicKey } from 'nostr-tools/pure';
+import { Relay } from 'nostr-tools/relay';
+import { buildAnnounceEvent } from './event.js';
+import { hexToBytes } from './utils.js';
+/**
+ * Publish a kind 31402 L402 service announcement to Nostr relays.
+ *
+ * Connects to each relay, publishes the signed event, and returns an
+ * {@link Announcement} handle whose `close()` method disconnects all relays.
+ *
+ * Relay failures are logged but do not reject the promise -- the function
+ * degrades gracefully. A warning is emitted if *no* relay accepted the event.
+ *
+ * @throws If the relay list is empty or contains invalid URLs.
+ */
+export async function announceService(config) {
+    const { relays, secretKey } = config;
+    if (!/^[0-9a-f]{64}$/i.test(secretKey)) {
+        throw new Error('secretKey must be a 64-character hex string');
+    }
+    if (relays.length === 0) {
+        throw new Error('At least one relay URL is required');
+    }
+    for (const url of relays) {
+        if (!/^wss?:\/\//i.test(url)) {
+            throw new Error(`Invalid relay URL: ${url} — must start with wss:// or ws://`);
+        }
+    }
+    // Derive pubkey (zeroises sk bytes internally)
+    const skBytes = hexToBytes(secretKey);
+    const pubkey = getPublicKey(skBytes);
+    skBytes.fill(0);
+    // Build and sign the event
+    const event = buildAnnounceEvent(secretKey, config);
+    // Connect to relays in parallel and publish
+    const connectedRelays = [];
+    let accepted = 0;
+    const results = await Promise.allSettled(relays.map(async (url) => {
+        const relay = await Promise.race([
+            Relay.connect(url),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Relay connection timeout: ${url}`)), 10_000)),
+        ]);
+        connectedRelays.push(relay);
+        await relay.publish(event);
+        accepted++;
+    }));
+    for (const result of results) {
+        if (result.status === 'rejected') {
+            console.warn(`[402-announce] Failed to publish:`, result.reason);
+        }
+    }
+    if (accepted === 0) {
+        console.warn('[402-announce] No relays accepted the event');
+    }
+    return {
+        eventId: event.id,
+        pubkey,
+        close() {
+            for (const relay of connectedRelays) {
+                try {
+                    relay.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=announce.js.map

package/build/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../src/announce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAsB;IAC1D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAEpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACvD,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,oCAAoC,CAAC,CAAA;QAChF,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;IACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAEf,2BAA2B;IAC3B,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAEnD,4CAA4C;IAC5C,MAAM,eAAe,GAAiC,EAAE,CAAA;IACxD,IAAI,QAAQ,GAAG,CAAC,CAAA;IAEhB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC/B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAClB,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAChF;SACF,CAAC,CAAA;QACF,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC1B,QAAQ,EAAE,CAAA;IACZ,CAAC,CAAC,CACH,CAAA;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAA;IAC7D,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,MAAM;QACN,KAAK;YACH,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;gBACpC,IAAI,CAAC;oBACH,KAAK,CAAC,KAAK,EAAE,CAAA;gBACf,CAAC;gBAAC,MAAM,CAAC;oBACP,sBAAsB;gBACxB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/build/event.d.ts

@@ -0,0 +1,12 @@
+import type { AnnounceConfig } from './types.js';
+import type { VerifiedEvent } from 'nostr-tools/pure';
+/**
+ * Build and sign a kind 31402 Nostr event announcing an L402 service.
+ *
+ * The secret key bytes are zeroised after signing.
+ *
+ * @param secretKeyHex - 64-character hex-encoded Nostr secret key
+ * @param config - Service announcement configuration
+ * @returns Signed Nostr event ready for relay publication
+ */
+export declare function buildAnnounceEvent(secretKeyHex: string, config: Omit<AnnounceConfig, 'relays'>): VerifiedEvent;

package/build/event.js

@@ -0,0 +1,58 @@
+import { finalizeEvent } from 'nostr-tools/pure';
+import { L402_ANNOUNCE_KIND } from './types.js';
+import { hexToBytes } from './utils.js';
+/**
+ * Build and sign a kind 31402 Nostr event announcing an L402 service.
+ *
+ * The secret key bytes are zeroised after signing.
+ *
+ * @param secretKeyHex - 64-character hex-encoded Nostr secret key
+ * @param config - Service announcement configuration
+ * @returns Signed Nostr event ready for relay publication
+ */
+export function buildAnnounceEvent(secretKeyHex, config) {
+    if (!/^[0-9a-f]{64}$/i.test(secretKeyHex)) {
+        throw new Error('secretKey must be a 64-character hex string');
+    }
+    const sk = hexToBytes(secretKeyHex);
+    try {
+        const tags = [
+            ['d', config.identifier],
+            ['name', config.name],
+            ['url', config.url],
+            ['about', config.about],
+        ];
+        if (config.picture) {
+            tags.push(['picture', config.picture]);
+        }
+        for (const pm of config.paymentMethods) {
+            tags.push(['pmi', pm]);
+        }
+        for (const p of config.pricing) {
+            tags.push(['price', p.capability, String(p.price), p.currency]);
+        }
+        if (config.topics) {
+            for (const topic of config.topics) {
+                tags.push(['t', topic]);
+            }
+        }
+        const contentObj = {};
+        if (config.capabilities) {
+            contentObj.capabilities = config.capabilities;
+        }
+        if (config.version) {
+            contentObj.version = config.version;
+        }
+        const event = finalizeEvent({
+            kind: L402_ANNOUNCE_KIND,
+            tags,
+            content: JSON.stringify(contentObj),
+            created_at: Math.floor(Date.now() / 1000),
+        }, sk);
+        return event;
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+//# sourceMappingURL=event.js.map

package/build/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAIvC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAoB,EACpB,MAAsC;IAEtC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IAED,MAAM,EAAE,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACnC,IAAI,CAAC;QACH,MAAM,IAAI,GAAe;YACvB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;YACxB,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;YACnB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;SACxB,CAAA;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;QACxC,CAAC;QAED,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAA;QACxB,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;QACjE,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;YACzB,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAA4B,EAAE,CAAA;QAC9C,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;QAC/C,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;QACrC,CAAC;QAED,MAAM,KAAK,GAAG,aAAa,CACzB;YACE,IAAI,EAAE,kBAAkB;YACxB,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;YACnC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;SAC1C,EACD,EAAE,CACH,CAAA;QAED,OAAO,KAAK,CAAA;IACd,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACZ,CAAC;AACH,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export { announceService } from './announce.js';
+export { buildAnnounceEvent } from './event.js';
+export { L402_ANNOUNCE_KIND } from './types.js';
+export type { AnnounceConfig, Announcement, PricingDef, CapabilityDef } from './types.js';

package/build/index.js

@@ -0,0 +1,4 @@
+export { announceService } from './announce.js';
+export { buildAnnounceEvent } from './event.js';
+export { L402_ANNOUNCE_KIND } from './types.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,56 @@
+/** Pricing for a specific capability. */
+export interface PricingDef {
+    /** Capability name (e.g. 'chat', 'get_joke', 'route') */
+    capability: string;
+    /** Price amount */
+    price: number;
+    /** Currency unit (e.g. 'sats') */
+    currency: string;
+}
+/** Capability with description (optional extended metadata). */
+export interface CapabilityDef {
+    name: string;
+    description: string;
+    /** Optional JSON Schema describing the capability's input parameters. */
+    schema?: unknown;
+    /** Optional JSON Schema describing the capability's output. */
+    outputSchema?: unknown;
+}
+/** Configuration for announceService(). */
+export interface AnnounceConfig {
+    /** Nostr secret key (64-char hex) for signing events */
+    secretKey: string;
+    /** Nostr relay URLs to publish to (wss:// or ws://) */
+    relays: string[];
+    /** Unique identifier for this service listing (d tag). Same pubkey + identifier = same listing. */
+    identifier: string;
+    /** Human-readable service name */
+    name: string;
+    /** HTTP URL where the L402 service is accessible */
+    url: string;
+    /** Short description of what the service does */
+    about: string;
+    /** Optional icon URL */
+    picture?: string;
+    /** Pricing for capabilities */
+    pricing: PricingDef[];
+    /** Accepted payment methods (e.g. ['bitcoin-lightning-bolt11', 'bitcoin-cashu']) */
+    paymentMethods: string[];
+    /** Optional topic tags for search/filtering (e.g. ['ai', 'inference']) */
+    topics?: string[];
+    /** Optional capability details (goes in content field) */
+    capabilities?: CapabilityDef[];
+    /** Optional service version (goes in content field) */
+    version?: string;
+}
+/** Handle returned by announceService() for cleanup. */
+export interface Announcement {
+    /** Published event ID */
+    eventId: string;
+    /** Nostr pubkey derived from the secret key */
+    pubkey: string;
+    /** Close relay connections. Synchronous. */
+    close(): void;
+}
+/** The Nostr event kind used for L402 service announcements. */
+export declare const L402_ANNOUNCE_KIND = 31402;

package/build/types.js

@@ -0,0 +1,3 @@
+/** The Nostr event kind used for L402 service announcements. */
+export const L402_ANNOUNCE_KIND = 31402;
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0DA,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA"}

package/build/utils.d.ts

@@ -0,0 +1 @@
+export declare function hexToBytes(hex: string): Uint8Array;

package/build/utils.js

@@ -0,0 +1,8 @@
+export function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/llms-full.txt

@@ -0,0 +1,222 @@
+# 402-announce — Full Reference
+
+> Announce HTTP 402 services on Nostr for decentralised discovery.
+> Supports both L402 and x402 payment protocols.
+> Source: https://github.com/TheCryptoDonkey/402-announce
+
+## Overview
+
+402-announce is a TypeScript library that publishes kind 31402 Nostr events describing paid HTTP APIs. These events enable decentralised service discovery — AI agents and Nostr clients can find, evaluate, and pay for APIs without a central registry.
+
+The library handles event construction, signing, and multi-relay publication. Secret key material is zeroised after use.
+
+## Installation
+
+```bash
+npm install 402-announce
+```
+
+Requires Node.js >= 18. ESM only. Single runtime dependency: nostr-tools.
+
+## API Reference
+
+### announceService(config: AnnounceConfig): Promise<Announcement>
+
+High-level function: builds a kind 31402 event, signs it, connects to relays in parallel, and publishes.
+
+**Parameters:**
+
+AnnounceConfig:
+  - secretKey (string, required): 64-character hex-encoded Nostr secret key
+  - relays (string[], required): Relay URLs (must start with wss:// or ws://)
+  - identifier (string, required): Unique listing ID, used as the Nostr `d` tag. Same pubkey + identifier = same listing.
+  - name (string, required): Human-readable service name
+  - url (string, required): HTTP endpoint where the 402 service is accessible
+  - about (string, required): Short description of the service
+  - pricing (PricingDef[], required): Per-capability pricing. Each entry: { capability, price, currency }
+  - paymentMethods (string[], required): Accepted payment method identifiers
+  - picture (string, optional): Icon URL
+  - topics (string[], optional): Topic tags for search/filtering
+  - capabilities (CapabilityDef[], optional): Capability details stored in event content
+  - version (string, optional): Service version stored in event content
+
+PricingDef:
+  - capability (string): Capability name (e.g. "get_joke", "chat", "inference")
+  - price (number): Price amount
+  - currency (string): Currency unit (e.g. "sats", "USD")
+
+CapabilityDef:
+  - name (string): Capability name
+  - description (string): Human-readable description
+
+**Returns** Announcement:
+  - eventId (string): The published Nostr event ID
+  - pubkey (string): Nostr pubkey derived from the secret key
+  - close(): void — Disconnect from all connected relays
+
+**Behaviour:**
+  - Validates secretKey (must be 64-char hex) and relay URLs (must be wss:// or ws://)
+  - Connects to all relays in parallel with a 10-second timeout per relay
+  - Individual relay failures are logged as warnings but do not reject the promise
+  - If no relay accepts the event, a warning is emitted (but the promise still resolves)
+  - Secret key bytes are zeroised after signing
+
+**Throws:**
+  - If secretKey is not a 64-character hex string
+  - If relays array is empty
+  - If any relay URL does not start with wss:// or ws://
+
+### buildAnnounceEvent(secretKeyHex: string, config: Omit<AnnounceConfig, 'relays'>): VerifiedEvent
+
+Lower-level function: builds and signs the kind 31402 event without publishing. Use this if you manage relay connections yourself.
+
+**Returns** a nostr-tools VerifiedEvent ready for relay publication.
+
+Secret key bytes are zeroised after signing (via try/finally).
+
+### Constants
+
+- L402_ANNOUNCE_KIND = 31402 — The Nostr event kind for service announcements
+
+### Exported types
+
+- AnnounceConfig — Configuration for announceService()
+- Announcement — Handle returned by announceService()
+- PricingDef — Pricing for a specific capability
+- CapabilityDef — Capability with description
+
+## Event Format Specification
+
+### Kind 31402 — Parameterised Replaceable Event
+
+A kind 31402 event is a Nostr parameterised replaceable event (NIP-33). This means:
+- The combination of pubkey + kind + d-tag uniquely identifies a listing
+- Publishing a new event with the same pubkey + kind + d-tag replaces the previous one
+- This allows services to update their announcements (e.g. change pricing) without creating duplicates
+
+### Tag structure
+
+Required tags:
+  ["d", "<identifier>"]           — Unique listing identifier
+  ["name", "<service name>"]      — Human-readable name
+  ["url", "<endpoint URL>"]       — HTTP endpoint
+  ["about", "<description>"]      — Short description
+  ["pmi", "<payment method>"]     — Payment method identifier (one tag per method)
+  ["price", "<capability>", "<amount>", "<currency>"]  — Pricing (one tag per capability)
+
+Optional tags:
+  ["t", "<topic>"]                — Topic tag for filtering (one tag per topic)
+  ["picture", "<icon URL>"]       — Service icon
+
+### Content field
+
+JSON object with optional fields:
+{
+  "capabilities": [
+    { "name": "get_joke", "description": "Returns a random joke" }
+  ],
+  "version": "1.0.0"
+}
+
+### Example event
+
+{
+  "kind": 31402,
+  "pubkey": "ab1234...ef5678",
+  "created_at": 1710000000,
+  "tags": [
+    ["d", "jokes-api"],
+    ["name", "Jokes API"],
+    ["url", "https://jokes.example.com"],
+    ["about", "A joke-telling service behind an L402 paywall"],
+    ["pmi", "bitcoin-lightning-bolt11"],
+    ["pmi", "bitcoin-cashu"],
+    ["price", "get_joke", "1", "sats"],
+    ["t", "comedy"],
+    ["t", "ai"]
+  ],
+  "content": "{\"capabilities\":[{\"name\":\"get_joke\",\"description\":\"Returns a random joke\"}],\"version\":\"1.0.0\"}",
+  "id": "...",
+  "sig": "..."
+}
+
+## Payment Method Identifiers
+
+Known payment method identifiers for the `pmi` tag and `paymentMethods` config:
+
+  bitcoin-lightning-bolt11   — Lightning Network BOLT-11 invoices
+  bitcoin-cashu              — Cashu ecash tokens
+  bitcoin-onchain            — On-chain Bitcoin
+  x402-evm                   — x402 protocol on EVM chains
+  x402-solana                — x402 protocol on Solana
+
+## Integration Patterns
+
+### Producer side: toll-booth + 402-announce
+
+A typical server setup protects an API with toll-booth and announces it with 402-announce:
+
+```typescript
+import { createTollBooth } from 'toll-booth'
+import { announceService } from '402-announce'
+
+// 1. Protect your API with a paywall
+const booth = createTollBooth({ /* payment config */ })
+app.use('/api', booth.middleware)
+
+// 2. Announce it on Nostr
+const handle = await announceService({
+  secretKey: process.env.NOSTR_SECRET_KEY,
+  relays: ['wss://relay.damus.io'],
+  identifier: 'my-api',
+  name: 'My API',
+  url: 'https://api.example.com',
+  about: 'A paid API service',
+  pricing: [{ capability: 'query', price: 10, currency: 'sats' }],
+  paymentMethods: ['bitcoin-lightning-bolt11'],
+})
+
+// 3. Clean up on shutdown
+process.on('SIGTERM', () => handle.close())
+```
+
+### Consumer side: 402-mcp
+
+AI agents use 402-mcp to discover and consume announced services:
+
+1. 402-mcp subscribes to kind 31402 events on configured relays
+2. Agent searches for services by topic, capability, or payment method
+3. 402-mcp handles L402 payment negotiation automatically
+4. Agent receives the API response
+
+The agent never needs to know about Nostr or payment protocols — 402-mcp abstracts it all.
+
+### Updating a listing
+
+Because kind 31402 is a parameterised replaceable event, calling announceService() again with the same identifier and pubkey replaces the previous listing. Use this to update pricing, add capabilities, or change the endpoint URL.
+
+## Security Considerations
+
+- **Key zeroisation**: Secret key bytes (Uint8Array) are filled with zeros immediately after signing, in both announceService() and buildAnnounceEvent(). This limits the window during which key material exists in memory.
+- **Key handling**: Pass the secret key as a hex string. The library converts to bytes, signs, and zeroises. Never log or persist the key yourself.
+- **Relay trust**: Relays are untrusted infrastructure. Events are cryptographically signed — relay operators cannot forge announcements. However, relays can choose not to store or serve your events.
+- **Connection timeouts**: Relay connections time out after 10 seconds to prevent indefinite hangs.
+- **Graceful degradation**: If some relays fail, the event is still published to the others. A warning is emitted only if no relay accepts the event.
+
+## Error Handling
+
+The library throws synchronously for invalid configuration:
+- secretKey not 64-char hex → Error
+- Empty relays array → Error
+- Invalid relay URL (not wss:// or ws://) → Error
+
+Relay-level failures during publication are handled gracefully:
+- Connection timeouts → warning logged, other relays still tried
+- Publish rejections → warning logged, other relays still tried
+- All relays fail → warning logged, promise resolves with eventId from the signed event
+
+## Source
+
+Repository: https://github.com/TheCryptoDonkey/402-announce
+Licence: MIT
+Runtime dependency: nostr-tools

package/llms.txt

@@ -0,0 +1,36 @@
+# 402-announce
+
+> Announce HTTP 402 services on Nostr for decentralised discovery
+
+## What it does
+
+402-announce publishes kind 31402 parameterised replaceable Nostr events that describe paid HTTP APIs. AI agents and Nostr clients discover these announcements to find services they can pay for and consume — no central registry needed.
+
+## Key concepts
+
+- **Kind 31402**: Nostr event kind for L402/x402 service announcements. Parameterised replaceable — same pubkey + identifier updates the existing listing.
+- **Payment methods**: Services declare accepted payment methods via `pmi` tags (e.g. `bitcoin-lightning-bolt11`, `bitcoin-cashu`).
+- **Pricing**: Per-capability pricing via `price` tags (capability name, amount, currency).
+- **Decentralised discovery**: Events are published to standard Nostr relays. Any client can subscribe and filter.
+
+## API surface
+
+Two exports:
+
+- `announceService(config)` — build, sign, and publish to relays. Returns `{ eventId, pubkey, close() }`.
+- `buildAnnounceEvent(secretKey, config)` — build and sign without publishing. Returns a `VerifiedEvent`.
+
+## Ecosystem position
+
+```
+toll-booth (paywall) → protects your API
+402-announce (this)  → tells the world your API exists
+402-mcp (discovery)  → AI agents find, pay, and consume your API
+```
+
+## Details
+
+For full API reference, event format, integration patterns, and examples see:
+- llms-full.txt (comprehensive reference)
+- README.md (human-oriented documentation with diagrams)
+- Source: https://github.com/TheCryptoDonkey/402-announce

package/package.json

@@ -1,10 +1,60 @@
 {
   "name": "402-announce",
-  "version": "0.0.1",
-  "description": "Announce HTTP 402 services on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.",
   "license": "MIT",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "files": [
+    "build",
+    "LICENSE",
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.12.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@types/node": "^25.5.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "l402",
+    "x402",
+    "402",
+    "nostr",
+    "discovery",
+    "lightning",
+    "cashu",
+    "mcp",
+    "ai-agents",
+    "machine-payments",
+    "http-402"
+  ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/TheCryptoDonkey/402-announce.git"
+    "url": "https://github.com/TheCryptoDonkey/402-announce.git"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }