nostr-bray 2.3.0 → 3.0.0

package/dist/zap/handlers.d.ts

@@ -1,34 +1,33 @@
-import type { Event as NostrEvent } from 'nostr-tools';
+import type { GetBalanceResult, NwcRequestOptions, NwcTransaction, NwcTransport, PayInvoiceResult } from '@forgesworn/nwc-kit';
 import type { SigningContext } from '../signing-context.js';
 import type { RelayPool } from '../relay-pool.js';
-import type { PublishResult } from '../types.js';
 /**
  * Load the wallets map from the JSON file. Returns empty map if file missing.
  *
  * @param walletsFile - Absolute path to the JSON wallets store.
- * @returns A map of public key hex strings to NWC URIs.
+ * @returns A map of public key hex strings to absolute NWC secret-file paths.
  *
  * @example
  * const wallets = loadWallets('/home/user/.bray/wallets.json')
- * // { 'abc123...': 'nostr+walletconnect://...' }
+ * // { 'abc123...': '/run/secrets/alice-nwc' }
  */
 export declare function loadWallets(walletsFile: string): Record<string, string>;
 /**
  * Save the wallets map to the JSON file. Creates parent dirs and sets 0600.
  *
  * @param walletsFile - Absolute path to the JSON wallets store.
- * @param wallets - Map of public key hex strings to NWC URIs to persist.
+ * @param wallets - Map of public key hex strings to absolute NWC secret-file paths.
  * @returns void
  *
  * @example
  * saveWallets('/home/user/.bray/wallets.json', {
- *   'abc123...': 'nostr+walletconnect://pubkey?relay=wss://relay.example&secret=deadbeef',
+ *   'abc123...': '/run/secrets/alice-nwc',
  * })
  */
 export declare function saveWallets(walletsFile: string, wallets: Record<string, string>): void;
 /**
  * Resolve the NWC URI for the active identity.
- * 1. Per-identity wallet from wallets file
+ * 1. Per-identity NWC secret file referenced by the wallet registry
  * 2. Global NWC URI (fallback)
  * 3. undefined (no wallet configured)
  *
@@ -37,27 +36,28 @@ export declare function saveWallets(walletsFile: string, wallets: Record<string,
  * @returns The resolved NWC URI, or `undefined` if no wallet is configured.
  *
  * @example
- * const uri = resolveNwcUri(ctx, '/home/user/.bray/wallets.json', process.env.NWC_URI)
+ * const uri = resolveNwcUri(ctx, '/home/user/.bray/wallets.json', configuredNwcUri)
  * if (!uri) throw new Error('No wallet configured')
  */
 export declare function resolveNwcUri(ctx: SigningContext, walletsFile: string, globalNwcUri?: string): string | undefined;
 export interface NwcConnection {
     pubkey: string;
     relay: string;
-    secret: string;
+    relays: readonly string[];
+    lud16?: string;
 }
 /**
  * Parse a nostr+walletconnect:// URI.
  *
  * @param uri - A `nostr+walletconnect://` URI as specified in NIP-47.
- * @returns A parsed {@link NwcConnection} containing the wallet pubkey, relay URL, and connection secret.
- * @throws {Error} If `pubkey`, `relay`, or `secret` are missing from the URI.
+ * @returns Public connection metadata. The connection secret is never returned.
+ * @throws {Error} If the URI is malformed or insecure.
  *
  * @example
  * const conn = parseNwcUri(
  *   'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
  * )
- * // { pubkey: 'abc123', relay: 'wss://relay.example', secret: 'deadbeef' }
+ * // { pubkey: 'abc123', relay: 'wss://relay.example/', relays: ['wss://relay.example/'] }
  */
 export declare function parseNwcUri(uri: string): NwcConnection;
 export interface ZapReceipt {
@@ -87,9 +87,8 @@ export declare function handleZapReceipts(ctx: SigningContext, pool: RelayPool,
  * Decode basic bolt11 invoice fields.
  *
  * @param bolt11 - A BOLT-11 Lightning invoice string (e.g. `lnbc...`).
- * @returns An object with the decoded fields. `amountMsats` is present when the
- *   amount is encoded in the invoice prefix; `description` and `expiry` are not
- *   yet decoded and will be absent in the current implementation.
+ * @returns The bounded amount, description and expiry fields committed by the
+ *   invoice. `amountMsats` is absent for an amountless invoice.
  *
  * @example
  * const { amountMsats } = handleZapDecode('lnbc1000n1...')
@@ -100,142 +99,47 @@ export declare function handleZapDecode(bolt11: string): {
     description?: string;
     expiry?: number;
 };
-/**
- * Pay a Lightning invoice via NWC.
- *
- * @param args - Payment arguments.
- * @param args.invoice - BOLT-11 Lightning invoice to pay.
- * @param args.nwcUri - NWC URI identifying the wallet to use.
- * @returns The signed NIP-47 request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapSend(ctx, pool, {
- *   invoice: 'lnbc500n1...',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapSend(ctx: SigningContext, pool: RelayPool, args: {
-    invoice: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * Request wallet balance via NWC.
- *
- * @param args - Balance request arguments.
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `get_balance` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapBalance(ctx, pool, {
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapBalance(ctx: SigningContext, pool: RelayPool, args: {
+interface NwcOperationOptions extends NwcRequestOptions {
+    /** Injectable for deterministic tests and specialised relay transports. */
+    transport?: NwcTransport;
+}
+interface NwcArgs extends NwcOperationOptions {
     nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
+}
+export interface ZapPaymentResult extends PayInvoiceResult {
+    paymentHash: string;
+    verified: true;
+}
 /**
- * Generate a Lightning invoice via NWC.
- *
- * @param args - Invoice creation arguments.
- * @param args.amountMsats - Invoice amount in millisatoshis.
- * @param args.description - Optional human-readable memo attached to the invoice.
- * @param args.nwcUri - NWC URI identifying the wallet to use.
- * @returns The signed NIP-47 `make_invoice` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapMakeInvoice(ctx, pool, {
- *   amountMsats: 21_000,
- *   description: 'Coffee ☕',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
+ * The wallet may have submitted a payment but Bray cannot prove settlement.
+ * Callers must reconcile `paymentHash` before attempting the invoice again.
  */
-export declare function handleZapMakeInvoice(ctx: SigningContext, pool: RelayPool, args: {
+export declare class ZapPaymentOutcomeUnknownError extends Error {
+    readonly paymentHash: string;
+    readonly code = "PAYMENT_OUTCOME_UNKNOWN";
+    constructor(paymentHash: string);
+}
+/** Pay a BOLT-11 invoice and return only after the wallet proves settlement. */
+export declare function handleZapSend(_ctx: SigningContext, _pool: RelayPool, args: {
+    invoice: string;
+} & NwcArgs): Promise<ZapPaymentResult>;
+/** Return the wallet's confirmed balance in millisatoshis. */
+export declare function handleZapBalance(_ctx: SigningContext, _pool: RelayPool, args: NwcArgs): Promise<GetBalanceResult>;
+/** Generate a Lightning invoice through the configured wallet. */
+export declare function handleZapMakeInvoice(_ctx: SigningContext, _pool: RelayPool, args: {
     amountMsats: number;
     description?: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * Look up an invoice via NWC.
- *
- * @param args - Lookup arguments. Provide at least one of `paymentHash` or `invoice`.
- * @param args.paymentHash - Hex-encoded payment hash of the invoice to look up.
- * @param args.invoice - BOLT-11 invoice string to look up.
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `lookup_invoice` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapLookupInvoice(ctx, pool, {
- *   paymentHash: 'a1b2c3...',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapLookupInvoice(ctx: SigningContext, pool: RelayPool, args: {
+} & NwcArgs): Promise<NwcTransaction>;
+/** Look up an invoice and return the wallet's authenticated result. */
+export declare function handleZapLookupInvoice(_ctx: SigningContext, _pool: RelayPool, args: {
     paymentHash?: string;
     invoice?: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * List recent transactions via NWC.
- *
- * @param args - Pagination arguments.
- * @param args.limit - Maximum number of transactions to return (default 10).
- * @param args.offset - Number of transactions to skip for pagination (default 0).
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `list_transactions` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapListTransactions(ctx, pool, {
- *   limit: 5,
- *   offset: 0,
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapListTransactions(ctx: SigningContext, pool: RelayPool, args: {
+} & NwcArgs): Promise<NwcTransaction>;
+/** List recent transactions through the isolated NIP-47 extension 05 client. */
+export declare function handleZapListTransactions(_ctx: SigningContext, _pool: RelayPool, args: {
     limit?: number;
     offset?: number;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
+} & NwcArgs): Promise<{
+    transactions: NwcTransaction[];
 }>;
-/**
- * Parse a NWC wallet response event.
- *
- * @param nwcUri - The NWC URI whose secret is used to decrypt the response.
- * @param event - A kind 23195 NIP-47 response event from the wallet service.
- * @returns The decrypted response payload containing `result_type`, an optional
- *   `result` object, and an optional `error` with `code` and `message`.
- *
- * @example
- * const response = handleZapParseResponse(
- *   'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- *   walletResponseEvent,
- * )
- * if (response.error) console.error(response.error.message)
- * else console.log(response.result)
- */
-export declare function handleZapParseResponse(nwcUri: string, event: NostrEvent): {
-    result_type: string;
-    result?: Record<string, unknown>;
-    error?: {
-        code: string;
-        message: string;
-    };
-};
+export {};