nostr-core 0.1.0

package/README.md

@@ -0,0 +1,229 @@
+# nostr-core
+
+Dead-simple, vendor-neutral [Nostr Wallet Connect (NWC)](https://github.com/nostr-protocol/nips/blob/master/47.md) client for JavaScript and TypeScript.
+
+```ts
+import { NWC } from 'nostr-core'
+
+const nwc = new NWC('nostr+walletconnect://...')
+await nwc.connect()
+
+const { balance } = await nwc.getBalance()
+console.log(`Balance: ${balance} msats`)
+
+const { preimage } = await nwc.payInvoice('lnbc...')
+console.log('Paid! Preimage:', preimage)
+
+nwc.close()
+```
+
+## Features
+
+- **Single connection string** - pass a `nostr+walletconnect://` URI and start making calls
+- **Full NIP-47 coverage** - `pay_invoice`, `get_balance`, `make_invoice`, `list_transactions`, `pay_keysend`, `sign_message`, and more
+- **Auto-encryption** - detects NIP-04 or NIP-44 support and handles it transparently
+- **Typed errors** - specific error classes for timeouts, connection failures, wallet rejections, and decryption issues
+- **Zero framework deps** - built on audited [noble](https://paulmillr.com/noble/) cryptography libraries only
+- **ESM-only** - tree-shakeable, modern JavaScript
+
+## Install
+
+```sh
+npm install nostr-core
+```
+
+Requires Node.js 18+ or any runtime with Web Crypto and WebSocket support (Deno, Bun, Cloudflare Workers).
+
+## Quick Start
+
+### Connect to a Wallet
+
+```ts
+import { NWC } from 'nostr-core'
+
+const nwc = new NWC('nostr+walletconnect://...')
+await nwc.connect()
+
+const info = await nwc.getInfo()
+console.log('Connected to:', info.alias)
+console.log('Methods:', info.methods)
+```
+
+### Pay an Invoice
+
+```ts
+try {
+  const { preimage, fees_paid } = await nwc.payInvoice('lnbc...')
+  console.log('Preimage:', preimage)
+} catch (err) {
+  console.error('Payment failed:', err.message)
+}
+```
+
+### Pay a Lightning Address
+
+```ts
+try {
+  const { preimage, invoice } = await nwc.payLightningAddress('hello@getalby.com', 100)
+  console.log('Paid 100 sats! Preimage:', preimage)
+} catch (err) {
+  console.error('Payment failed:', err.message)
+}
+```
+
+### Pay a Lightning Address in Fiat
+
+```ts
+// Pay $5 USD to a Lightning Address - automatically converts to sats
+const { preimage, sats, rate } = await nwc.payLightningAddressFiat('hello@getalby.com', 5, 'usd')
+console.log(`Paid ${sats} sats ($5 at $${rate}/BTC)`)
+```
+
+### Create an Invoice
+
+```ts
+const tx = await nwc.makeInvoice({
+  amount: 10000, // msats
+  description: 'Coffee',
+})
+console.log('Invoice:', tx.invoice)
+```
+
+### Listen for Payments
+
+```ts
+nwc.on('payment_received', (notification) => {
+  console.log('Received:', notification.notification.amount, 'msats')
+})
+```
+
+### Close
+
+```ts
+nwc.close()
+```
+
+## API
+
+### NWC Methods
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to relay, auto-detect encryption |
+| `getInfo()` | Wallet metadata (alias, network, supported methods) |
+| `getBalance()` | Wallet balance in msats |
+| `getBudget()` | NWC spending budget info |
+| `payInvoice(invoice, amount?)` | Pay a BOLT-11 invoice |
+| `payKeysend(params)` | Keysend payment to a node pubkey |
+| `makeInvoice(params)` | Create a Lightning invoice |
+| `lookupInvoice(params)` | Look up an invoice by hash or string |
+| `listTransactions(params?)` | List past transactions |
+| `signMessage(message)` | Sign a message with the wallet's key |
+| `payLightningAddress(address, amountSats)` | Resolve a Lightning Address and pay the invoice |
+| `payLightningAddressFiat(address, fiatAmount, currency)` | Convert fiat to sats and pay a Lightning Address |
+| `on(event, handler)` | Listen for `payment_received` / `payment_sent` |
+| `off(event, handler)` | Remove an event handler |
+| `close()` | Disconnect and clean up |
+
+### Configuration
+
+```ts
+const nwc = new NWC(connectionString)
+nwc.replyTimeout = 30000   // Wallet reply timeout (default: 60s)
+nwc.publishTimeout = 10000 // Relay publish timeout (default: 5s)
+```
+
+### Error Handling
+
+```ts
+import { NWCWalletError, NWCTimeoutError, NWCConnectionError } from 'nostr-core'
+
+try {
+  await nwc.payInvoice('lnbc...')
+} catch (err) {
+  if (err instanceof NWCWalletError) {
+    console.error(`Wallet rejected [${err.code}]: ${err.message}`)
+  } else if (err instanceof NWCTimeoutError) {
+    console.error('Timed out:', err.code) // 'PUBLISH_TIMEOUT' or 'REPLY_TIMEOUT'
+  } else if (err instanceof NWCConnectionError) {
+    console.error('Connection lost')
+  }
+}
+```
+
+Error hierarchy:
+
+```
+NWCError (code: string)
+├── NWCWalletError          - wallet rejected the request
+├── NWCTimeoutError         - generic timeout
+│   ├── NWCPublishTimeoutError  - relay didn't acknowledge
+│   └── NWCReplyTimeoutError    - wallet didn't respond
+├── NWCPublishError         - relay rejected the event
+├── NWCConnectionError      - couldn't connect to relay
+├── NWCDecryptionError      - couldn't decrypt response
+├── LightningAddressError   - Lightning Address resolution failed
+└── FiatConversionError     - fiat-to-sats conversion failed
+```
+
+## Low-Level Exports
+
+nostr-core also exports the building blocks used internally:
+
+```ts
+import {
+  // Key management
+  generateSecretKey, getPublicKey,
+
+  // Events
+  finalizeEvent, verifyEvent, getEventHash, serializeEvent, validateEvent,
+
+  // Relay connections
+  Relay, RelayPool,
+
+  // Encryption
+  nip04, nip44,
+
+  // Bech32 encoding
+  nip19,
+
+  // Filters
+  matchFilter, matchFilters,
+
+  // Utilities
+  normalizeURL, bytesToHex, hexToBytes, randomBytes,
+} from 'nostr-core'
+```
+
+## Why nostr-core over @getalby/sdk?
+
+If you've used `@getalby/sdk` before, here's why `nostr-core` is a better fit for most NWC use cases:
+
+| | **nostr-core** | **@getalby/sdk** | |
+|---|---|---|---|
+| **Install size** | 118 MB | 159 MB | **26% smaller** |
+| **Packages installed** | 79 | 436 | **82% fewer** |
+| **Dependency tree** | 132 total | 698 total | **81% fewer** |
+| **Vendor lock-in** | None - pure NIP-47 protocol | Coupled to Alby (OAuth, webhooks, branding) | |
+| **Error handling** | Typed hierarchy (8 specific classes) | Generic errors | |
+| **Encryption** | Auto-detects NIP-04 / NIP-44 | Manual configuration | |
+| **Fiat conversion** | Built-in (zero extra deps) | Via `@getalby/lightning-tools` | |
+| **Runtime support** | Node 18+, Deno, Bun, Cloudflare Workers | Primarily Node.js | |
+| **API surface** | One class (`NWC`) | Multiple overlapping abstractions | |
+
+**Use `@getalby/sdk`** if you need Alby OAuth or WebLN compatibility. **Use `nostr-core`** for everything else - including Lightning Address payments and fiat currency conversion, which are now supported natively.
+
+See the full [comparison guide](./docs/guide/comparison.md) for details.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [@noble/curves](https://github.com/paulmillr/noble-curves) | secp256k1 / schnorr signatures |
+| [@noble/hashes](https://github.com/paulmillr/noble-hashes) | SHA-256, HMAC, HKDF |
+| [@noble/ciphers](https://github.com/paulmillr/noble-ciphers) | AES-CBC, ChaCha20 |
+| [@scure/base](https://github.com/paulmillr/scure-base) | Base64, bech32 encoding |
+
+## License
+
+MIT

package/dist/crypto.d.ts

@@ -0,0 +1,3 @@
+export declare function generateSecretKey(): Uint8Array;
+export declare function getPublicKey(secretKey: Uint8Array): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAE1D"}

package/dist/crypto.js

@@ -0,0 +1,9 @@
+import { schnorr } from '@noble/curves/secp256k1';
+import { bytesToHex } from '@noble/hashes/utils';
+export function generateSecretKey() {
+    return schnorr.utils.randomSecretKey();
+}
+export function getPublicKey(secretKey) {
+    return bytesToHex(schnorr.getPublicKey(secretKey));
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,SAAqB;IAChD,OAAO,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAA;AACpD,CAAC"}

package/dist/event.d.ts

@@ -0,0 +1,22 @@
+export declare const verifiedSymbol: unique symbol;
+export type NostrEvent = {
+    kind: number;
+    tags: string[][];
+    content: string;
+    created_at: number;
+    pubkey: string;
+    id: string;
+    sig: string;
+    [verifiedSymbol]?: boolean;
+};
+export type EventTemplate = Pick<NostrEvent, 'kind' | 'tags' | 'content' | 'created_at'>;
+export type UnsignedEvent = Pick<NostrEvent, 'kind' | 'tags' | 'content' | 'created_at' | 'pubkey'>;
+export interface VerifiedEvent extends NostrEvent {
+    [verifiedSymbol]: true;
+}
+export declare function validateEvent<T>(event: T): event is T & UnsignedEvent;
+export declare function serializeEvent(evt: UnsignedEvent): string;
+export declare function getEventHash(event: UnsignedEvent): string;
+export declare function finalizeEvent(t: EventTemplate, secretKey: Uint8Array): VerifiedEvent;
+export declare function verifyEvent(event: NostrEvent): event is VerifiedEvent;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,eAAqB,CAAA;AAEhD,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,cAAc,CAAC,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC,CAAA;AACxF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC,CAAA;AAEnG,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CACvB;AAID,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,aAAa,CAkBrE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAGzD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAGzD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,GAAG,aAAa,CAOpF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,IAAI,aAAa,CAiBrE"}

package/dist/event.js

@@ -0,0 +1,68 @@
+import { schnorr } from '@noble/curves/secp256k1';
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { utf8Encoder } from './utils.js';
+export const verifiedSymbol = Symbol('verified');
+const isRecord = (obj) => obj instanceof Object;
+export function validateEvent(event) {
+    if (!isRecord(event))
+        return false;
+    if (typeof event.kind !== 'number')
+        return false;
+    if (typeof event.content !== 'string')
+        return false;
+    if (typeof event.created_at !== 'number')
+        return false;
+    if (typeof event.pubkey !== 'string')
+        return false;
+    if (!event.pubkey.match(/^[a-f0-9]{64}$/))
+        return false;
+    if (!Array.isArray(event.tags))
+        return false;
+    for (let i = 0; i < event.tags.length; i++) {
+        const tag = event.tags[i];
+        if (!Array.isArray(tag))
+            return false;
+        for (let j = 0; j < tag.length; j++) {
+            if (typeof tag[j] !== 'string')
+                return false;
+        }
+    }
+    return true;
+}
+export function serializeEvent(evt) {
+    if (!validateEvent(evt))
+        throw new Error("can't serialize event with wrong or missing properties");
+    return JSON.stringify([0, evt.pubkey, evt.created_at, evt.kind, evt.tags, evt.content]);
+}
+export function getEventHash(event) {
+    const eventHash = sha256(utf8Encoder.encode(serializeEvent(event)));
+    return bytesToHex(eventHash);
+}
+export function finalizeEvent(t, secretKey) {
+    const event = t;
+    event.pubkey = bytesToHex(schnorr.getPublicKey(secretKey));
+    event.id = getEventHash(event);
+    event.sig = bytesToHex(schnorr.sign(hexToBytes(event.id), secretKey));
+    event[verifiedSymbol] = true;
+    return event;
+}
+export function verifyEvent(event) {
+    if (typeof event[verifiedSymbol] === 'boolean')
+        return event[verifiedSymbol];
+    const hash = getEventHash(event);
+    if (hash !== event.id) {
+        event[verifiedSymbol] = false;
+        return false;
+    }
+    try {
+        const valid = schnorr.verify(hexToBytes(event.sig), hexToBytes(hash), hexToBytes(event.pubkey));
+        event[verifiedSymbol] = valid;
+        return valid;
+    }
+    catch {
+        event[verifiedSymbol] = false;
+        return false;
+    }
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;AAoBhD,MAAM,QAAQ,GAAG,CAAC,GAAY,EAAkC,EAAE,CAAC,GAAG,YAAY,MAAM,CAAA;AAExF,MAAM,UAAU,aAAa,CAAI,KAAQ;IACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAClC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAChD,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACnD,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACtD,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAClD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC;QAAE,OAAO,KAAK,CAAA;IAEvD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAA;QACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAA;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAClG,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAA;AACzF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACnE,OAAO,UAAU,CAAC,SAAS,CAAC,CAAA;AAC9B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAgB,EAAE,SAAqB;IACnE,MAAM,KAAK,GAAG,CAAkB,CAAA;IAChC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAA;IAC1D,KAAK,CAAC,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;IAC9B,KAAK,CAAC,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAA;IACrE,KAAK,CAAC,cAAc,CAAC,GAAG,IAAI,CAAA;IAC5B,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,IAAI,OAAO,KAAK,CAAC,cAAc,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC,CAAA;IAE5E,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;IAChC,IAAI,IAAI,KAAK,KAAK,CAAC,EAAE,EAAE,CAAC;QACtB,KAAK,CAAC,cAAc,CAAC,GAAG,KAAK,CAAA;QAC7B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;QAC/F,KAAK,CAAC,cAAc,CAAC,GAAG,KAAK,CAAA;QAC7B,OAAO,KAAK,CAAA;IACd,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,cAAc,CAAC,GAAG,KAAK,CAAA;QAC7B,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/fiat.d.ts

@@ -0,0 +1,9 @@
+import type { FiatRate, FiatConversion } from './types.js';
+export declare function getExchangeRate(currency: string): Promise<FiatRate>;
+export declare function fiatToSats(amount: number, currency: string): Promise<FiatConversion>;
+export declare function satsToFiat(sats: number, currency: string): Promise<{
+    amount: number;
+    rate: number;
+    currency: string;
+}>;
+//# sourceMappingURL=fiat.d.ts.map

package/dist/fiat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiat.d.ts","sourceRoot":"","sources":["../src/fiat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAM1D,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiCzE;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAS1F;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAS7D"}

package/dist/fiat.js

@@ -0,0 +1,48 @@
+import { FiatConversionError } from './types.js';
+// Cache exchange rates for 60 seconds
+const rateCache = new Map();
+const CACHE_TTL_MS = 60_000;
+export async function getExchangeRate(currency) {
+    const key = currency.toLowerCase();
+    const cached = rateCache.get(key);
+    const now = Date.now();
+    if (cached && now - cached.timestamp < CACHE_TTL_MS) {
+        return { rate: cached.rate, currency: key, timestamp: cached.timestamp };
+    }
+    const url = `https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=${key}`;
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (err) {
+        throw new FiatConversionError(`Failed to fetch exchange rate: ${err.message}`);
+    }
+    if (!response.ok) {
+        throw new FiatConversionError(`Exchange rate API returned ${response.status}`);
+    }
+    const data = await response.json();
+    const rate = data?.bitcoin?.[key];
+    if (typeof rate !== 'number' || rate <= 0) {
+        throw new FiatConversionError(`Unsupported or invalid currency: ${currency}`);
+    }
+    const timestamp = now;
+    rateCache.set(key, { rate, timestamp });
+    return { rate, currency: key, timestamp };
+}
+export async function fiatToSats(amount, currency) {
+    if (amount <= 0) {
+        throw new FiatConversionError('Amount must be positive');
+    }
+    const { rate, currency: cur } = await getExchangeRate(currency);
+    const sats = Math.round((amount / rate) * 1e8);
+    return { sats, rate, currency: cur };
+}
+export async function satsToFiat(sats, currency) {
+    if (sats <= 0) {
+        throw new FiatConversionError('Sats must be positive');
+    }
+    const { rate, currency: cur } = await getExchangeRate(currency);
+    const amount = (sats / 1e8) * rate;
+    return { amount, rate, currency: cur };
+}
+//# sourceMappingURL=fiat.js.map

package/dist/fiat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiat.js","sourceRoot":"","sources":["../src/fiat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAGhD,sCAAsC;AACtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+C,CAAA;AACxE,MAAM,YAAY,GAAG,MAAM,CAAA;AAE3B,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAEtB,IAAI,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAA;IAC1E,CAAC;IAED,MAAM,GAAG,GAAG,2EAA2E,GAAG,EAAE,CAAA;IAE5F,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,mBAAmB,CAAC,kCAAmC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAA;IAC3F,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,mBAAmB,CAAC,8BAA8B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAChF,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAClC,MAAM,IAAI,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;IAEjC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,mBAAmB,CAAC,oCAAoC,QAAQ,EAAE,CAAC,CAAA;IAC/E,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAA;IACrB,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;IAEvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc,EAAE,QAAgB;IAC/D,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,mBAAmB,CAAC,yBAAyB,CAAC,CAAA;IAC1D,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAA;IAE9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAA;AACtC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,QAAgB;IAEhB,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,mBAAmB,CAAC,uBAAuB,CAAC,CAAA;IACxD,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC/D,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,IAAI,CAAA;IAElC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAA;AACxC,CAAC"}

package/dist/filter.d.ts

@@ -0,0 +1,14 @@
+import type { NostrEvent } from './event.js';
+export type Filter = {
+    ids?: string[];
+    kinds?: number[];
+    authors?: string[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    search?: string;
+    [key: `#${string}`]: string[] | undefined;
+};
+export declare function matchFilter(filter: Filter, event: NostrEvent): boolean;
+export declare function matchFilters(filters: Filter[], event: NostrEvent): boolean;
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,MAAM,MAAM,GAAG;IACnB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,CAAC,GAAG,EAAE,IAAI,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;CAC1C,CAAA;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAiBtE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAK1E"}

package/dist/filter.js

@@ -0,0 +1,29 @@
+export function matchFilter(filter, event) {
+    if (filter.ids && filter.ids.indexOf(event.id) === -1)
+        return false;
+    if (filter.kinds && filter.kinds.indexOf(event.kind) === -1)
+        return false;
+    if (filter.authors && filter.authors.indexOf(event.pubkey) === -1)
+        return false;
+    for (const f in filter) {
+        if (f[0] === '#') {
+            const tagName = f.slice(1);
+            const values = filter[`#${tagName}`];
+            if (values && !event.tags.find(([t, v]) => t === tagName && values.indexOf(v) !== -1))
+                return false;
+        }
+    }
+    if (filter.since && event.created_at < filter.since)
+        return false;
+    if (filter.until && event.created_at > filter.until)
+        return false;
+    return true;
+}
+export function matchFilters(filters, event) {
+    for (let i = 0; i < filters.length; i++) {
+        if (matchFilter(filters[i], event))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=filter.js.map

package/dist/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAiB;IAC3D,IAAI,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IACnE,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IACzE,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAE/E,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC,CAAA;YACpC,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,OAAO,IAAI,MAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACtG,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACjE,IAAI,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IAEjE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAiB,EAAE,KAAiB;IAC/D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;IACjD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { NWC } from './nwc.js';
+export type { EncryptionType, Nip47Method, Nip47NotificationType, GetInfoResponse, GetBalanceResponse, GetBudgetResponse, PayResponse, Transaction, MakeInvoiceRequest, PayInvoiceRequest, PayKeysendRequest, LookupInvoiceRequest, ListTransactionsRequest, ListTransactionsResponse, SignMessageRequest, SignMessageResponse, Nip47Notification, NWCConnectionOptions, LightningAddressResponse, FiatRate, FiatConversion, } from './types.js';
+export { NWCError, NWCWalletError, NWCTimeoutError, NWCPublishTimeoutError, NWCReplyTimeoutError, NWCPublishError, NWCConnectionError, NWCDecryptionError, LightningAddressError, FiatConversionError, } from './types.js';
+export { fetchInvoice, validateLightningAddress, parseLightningAddress } from './lightning-address.js';
+export { getExchangeRate, fiatToSats, satsToFiat } from './fiat.js';
+export { generateSecretKey, getPublicKey } from './crypto.js';
+export { finalizeEvent, verifyEvent, getEventHash, serializeEvent, validateEvent, verifiedSymbol } from './event.js';
+export type { NostrEvent, EventTemplate, UnsignedEvent, VerifiedEvent } from './event.js';
+export { matchFilter, matchFilters } from './filter.js';
+export type { Filter } from './filter.js';
+export * as nip04 from './nip04.js';
+export * as nip44 from './nip44.js';
+export * as nip19 from './nip19.js';
+export { Relay, Subscription } from './relay.js';
+export type { SubscriptionParams } from './relay.js';
+export { RelayPool } from './pool.js';
+export type { SubCloser, PoolSubscribeParams } from './pool.js';
+export { normalizeURL, utf8Encoder, utf8Decoder, bytesToHex, hexToBytes, randomBytes } from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAG9B,YAAY,EACV,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,QAAQ,EACR,cAAc,GACf,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAGtG,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAGnE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG7D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AACpH,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAGzF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACvD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGzC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAGnC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,24 @@
+// Main API
+export { NWC } from './nwc.js';
+// Error classes
+export { NWCError, NWCWalletError, NWCTimeoutError, NWCPublishTimeoutError, NWCReplyTimeoutError, NWCPublishError, NWCConnectionError, NWCDecryptionError, LightningAddressError, FiatConversionError, } from './types.js';
+// Lightning Address
+export { fetchInvoice, validateLightningAddress, parseLightningAddress } from './lightning-address.js';
+// Fiat Conversion
+export { getExchangeRate, fiatToSats, satsToFiat } from './fiat.js';
+// Crypto
+export { generateSecretKey, getPublicKey } from './crypto.js';
+// Event system
+export { finalizeEvent, verifyEvent, getEventHash, serializeEvent, validateEvent, verifiedSymbol } from './event.js';
+// Filters
+export { matchFilter, matchFilters } from './filter.js';
+// NIPs
+export * as nip04 from './nip04.js';
+export * as nip44 from './nip44.js';
+export * as nip19 from './nip19.js';
+// Networking
+export { Relay, Subscription } from './relay.js';
+export { RelayPool } from './pool.js';
+// Utils
+export { normalizeURL, utf8Encoder, utf8Decoder, bytesToHex, hexToBytes, randomBytes } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AA2B9B,gBAAgB;AAChB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEtG,kBAAkB;AAClB,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEnE,SAAS;AACT,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE7D,eAAe;AACf,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGpH,UAAU;AACV,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAGvD,OAAO;AACP,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC,aAAa;AACb,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,QAAQ;AACR,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/lightning-address.d.ts

@@ -0,0 +1,26 @@
+import type { LightningAddressResponse } from './types.js';
+/**
+ * Validate whether a string is a valid Lightning Address format (name@domain).
+ */
+export declare function validateLightningAddress(address: string): boolean;
+/**
+ * Parse a Lightning Address into its name and domain parts.
+ * Throws LightningAddressError if the format is invalid.
+ */
+export declare function parseLightningAddress(address: string): {
+    name: string;
+    domain: string;
+};
+/**
+ * Resolve a Lightning Address to a BOLT-11 invoice via LNURL-pay.
+ *
+ * 1. Fetches the LNURL-pay metadata from `https://{domain}/.well-known/lnurlp/{name}`
+ * 2. Validates the response (callback URL, min/max sendable)
+ * 3. Calls the callback with `?amount={msats}` to obtain an invoice
+ *
+ * @param address - Lightning Address (e.g. `hello@getalby.com`)
+ * @param amountSats - Amount in satoshis to request
+ * @returns The BOLT-11 invoice string and any LNURL metadata
+ */
+export declare function fetchInvoice(address: string, amountSats: number): Promise<LightningAddressResponse>;
+//# sourceMappingURL=lightning-address.d.ts.map

package/dist/lightning-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightning-address.d.ts","sourceRoot":"","sources":["../src/lightning-address.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI1D;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMvF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAiGzG"}