@qntx/nostr 0.6.0 → 0.7.0

package/dist/{gossip-oloDMWEj.mjs → gossip-CcTp9VpU.mjs}

@@ -1,7 +1,8 @@
-import { l as normalizeURL } from "./util-LfQirgDk.mjs";
+import { d as nowSeconds, l as normalizeRelayUrls, u as normalizeURL } from "./util-yFYzlbrm.mjs";
 import { t as Kind } from "./kind-Cxwhhkx8.mjs";
-import { a as isReplaceableWinner } from "./event-D8Nfoh4K.mjs";
+import { a as isReplaceableWinner } from "./event-DinQMmJ1.mjs";
 import { parseRelayList } from "./nips/nip65.mjs";
+import { i as trimOldest, r as touchKey } from "./collections-DtwMc1NU.mjs";
 import { parseDmRelayList } from "./nips/nip17.mjs";
 //#region src/gossip/gossip.ts
 function emptyRoutes() {
@@ -26,7 +27,11 @@ var Gossip = class {
 		this.#maxPubkeys = opts.maxPubkeys ?? 1e4;
 	}
 	/**
-	* Ingest a routing list event. - kind:10002 → write/read (NIP-65) - kind:10050 → dm (NIP-17)
+	* Ingest a routing list event.
+	*
+	* - Kind:10002 → write/read (NIP-65)
+	* - Kind:10050 → dm (NIP-17)
+	*
 	* Returns true if routes for that list type were updated.
 	*/
 	ingest(event) {
@@ -50,7 +55,7 @@ var Gossip = class {
 		}
 		return false;
 	}
-	setRoutes(pubkey, items, updatedAt = Math.floor(Date.now() / 1e3), eventId) {
+	setRoutes(pubkey, items, updatedAt = nowSeconds(), eventId) {
 		const pk = pubkey.toLowerCase();
 		const prev = this.#lookup(pk) ?? emptyRoutes();
 		if (prev.updatedAt > updatedAt) return false;
@@ -70,8 +75,8 @@ var Gossip = class {
 			} catch {
 				continue;
 			}
-			if (item.write && !write.includes(url)) write.push(url);
-			if (item.read && !read.includes(url)) read.push(url);
+			if (item.marker !== "read" && !write.includes(url)) write.push(url);
+			if (item.marker !== "write" && !read.includes(url)) read.push(url);
 		}
 		this.#put(pk, {
 			write: write.slice(0, this.#maxRelays),
@@ -84,7 +89,7 @@ var Gossip = class {
 		});
 		return true;
 	}
-	setDmRoutes(pubkey, relays, updatedAt = Math.floor(Date.now() / 1e3), eventId) {
+	setDmRoutes(pubkey, relays, updatedAt = nowSeconds(), eventId) {
 		const pk = pubkey.toLowerCase();
 		const prev = this.#lookup(pk) ?? emptyRoutes();
 		if (prev.dmUpdatedAt > updatedAt) return false;
@@ -95,16 +100,7 @@ var Gossip = class {
 			created_at: prev.dmUpdatedAt,
 			id: prev.dmListId
 		})) return false;
-		const dm = [];
-		for (const raw of relays) {
-			let url;
-			try {
-				url = normalizeURL(raw);
-			} catch {
-				continue;
-			}
-			if (!dm.includes(url)) dm.push(url);
-		}
+		const dm = normalizeRelayUrls(relays);
 		this.#put(pk, {
 			write: prev.write,
 			read: prev.read,
@@ -137,10 +133,12 @@ var Gossip = class {
 		return this.#routes.size;
 	}
 	/**
-	* Route a user-facing filter into per-relay sub-filters plus leftover. - authors → outbox relays,
-	* filter narrowed per relay's authors - #p only → inbox relays of those pubkeys - neither / all
-	* unrouted → remainder is the original filter - mixed → remainder is the narrowed leftover; all
-	* routed → no remainder
+	* Route a user-facing filter into per-relay sub-filters plus leftover.
+	*
+	* - Authors → outbox relays, filter narrowed per relay's authors
+	* - #p only → inbox relays of those pubkeys
+	* - Neither / all unrouted → remainder is the original filter
+	* - Mixed → remainder is the narrowed leftover; all routed → no remainder
 	*/
 	route(filter) {
 		const authors = filter.authors?.map((a) => a.toLowerCase());
@@ -215,24 +213,16 @@ var Gossip = class {
 	/** Read that refreshes LRU recency. */
 	#lookup(pk) {
 		const routes = this.#routes.get(pk);
-		if (routes !== void 0) {
-			this.#routes.delete(pk);
-			this.#routes.set(pk, routes);
-		}
+		if (routes !== void 0) touchKey(this.#routes, pk, routes);
 		return routes;
 	}
 	/** Write at the newest LRU end, then trim the oldest beyond the cap. */
 	#put(pk, routes) {
-		this.#routes.delete(pk);
-		this.#routes.set(pk, routes);
-		while (this.#routes.size > this.#maxPubkeys) {
-			const oldest = this.#routes.keys().next().value;
-			if (oldest === void 0) break;
-			this.#routes.delete(oldest);
-		}
+		touchKey(this.#routes, pk, routes);
+		trimOldest(this.#routes, this.#maxPubkeys);
 	}
 };
 //#endregion
 export { Gossip as t };
 
-//# sourceMappingURL=gossip-oloDMWEj.mjs.map
+//# sourceMappingURL=gossip-CcTp9VpU.mjs.map

package/dist/gossip-CcTp9VpU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gossip-CcTp9VpU.mjs","names":[],"sources":["../src/gossip/gossip.ts"],"sourcesContent":["import { touchKey, trimOldest } from \"../core/collections.ts\";\nimport type { Event } from \"../core/event.ts\";\nimport { isReplaceableWinner } from \"../core/event.ts\";\nimport type { Filter } from \"../core/filter.ts\";\nimport { Kind } from \"../core/kind.ts\";\nimport { normalizeRelayUrls, normalizeURL, nowSeconds } from \"../core/util.ts\";\nimport { parseDmRelayList } from \"../nips/nip17.ts\";\nimport { parseRelayList } from \"../nips/nip65.ts\";\nimport type { RelayListItem } from \"../nips/nip65.ts\";\n\n/** Relay routing state for one pubkey: NIP-65 outbox/inbox plus NIP-17 DM relays. */\nexport type PubkeyRoutes = {\n  /** Relays the user writes to (outbox). NIP-65. */\n  readonly write: ReadonlyArray<string>;\n  /** Relays the user reads from (inbox). NIP-65. */\n  readonly read: ReadonlyArray<string>;\n  /** Relays for NIP-17 gift-wrap delivery. Kind 10050. */\n  readonly dm: ReadonlyArray<string>;\n  /** `created_at` of the last accepted kind:10002 list. */\n  readonly updatedAt: number;\n  /** `created_at` of the last accepted kind:10050 list. */\n  readonly dmUpdatedAt: number;\n  /** Event id of the last accepted kind:10002 (NIP-01 equal-timestamp tie-break). */\n  readonly relayListId?: string | undefined;\n  /** Event id of the last accepted kind:10050. */\n  readonly dmListId?: string | undefined;\n};\n\n/** A filter split by gossip routes: per-relay narrowed filters plus the unrouted remainder. */\nexport type RoutedFilter = {\n  /** Url → already-narrowed filter. Empty when nothing routed. */\n  perRelay: Map<string, Filter>;\n  /**\n   * Unrouted work for the caller:\n   *\n   * - No authors and no #p: original filter (\"generic\")\n   * - Authors/#p all unrouted: original filter (\"orphan\")\n   * - Mixed: narrowed leftover (\"fallback\")\n   * - All routed: undefined\n   */\n  remainder?: Filter;\n};\n\nexport type GossipOptions = {\n  /** Max relays to keep per direction when ranking. Default 4. */\n  maxRelaysPerPubkey?: number | undefined;\n  /**\n   * Max pubkeys with tracked routes; the map is LRU — writes and lookups refresh recency, and\n   * inserting beyond the cap drops the oldest entry. Default 10_000.\n   */\n  maxPubkeys?: number | undefined;\n};\n\nfunction emptyRoutes(): PubkeyRoutes {\n  return {\n    write: [],\n    read: [],\n    dm: [],\n    updatedAt: 0,\n    dmUpdatedAt: 0,\n  };\n}\n\n/**\n * Routing table for NIP-65 (10002) and NIP-17 DM relays (10050). Ingest replaceable list events,\n * then route filters into per-relay REQs.\n */\nexport class Gossip {\n  readonly #routes = new Map<string, PubkeyRoutes>();\n  readonly #maxRelays: number;\n  readonly #maxPubkeys: number;\n\n  constructor(opts: GossipOptions = {}) {\n    this.#maxRelays = opts.maxRelaysPerPubkey ?? 4;\n    this.#maxPubkeys = opts.maxPubkeys ?? 10_000;\n  }\n\n  /**\n   * Ingest a routing list event.\n   *\n   * - Kind:10002 → write/read (NIP-65)\n   * - Kind:10050 → dm (NIP-17)\n   *\n   * Returns true if routes for that list type were updated.\n   */\n  ingest(event: Event): boolean {\n    if (event.kind === Kind.RelayList) {\n      let items: RelayListItem[];\n      try {\n        items = parseRelayList(event);\n      } catch {\n        return false;\n      }\n      return this.setRoutes(event.pubkey, items, event.created_at, event.id);\n    }\n    if (event.kind === Kind.DirectMessageRelaysList) {\n      let relays: string[];\n      try {\n        relays = parseDmRelayList(event);\n      } catch {\n        return false;\n      }\n      return this.setDmRoutes(event.pubkey, relays, event.created_at, event.id);\n    }\n    return false;\n  }\n\n  setRoutes(\n    pubkey: string,\n    items: ReadonlyArray<RelayListItem>,\n    updatedAt: number = nowSeconds(),\n    eventId?: string,\n  ): boolean {\n    const pk = pubkey.toLowerCase();\n    const prev = this.#lookup(pk) ?? emptyRoutes();\n    if (prev.updatedAt > updatedAt) {\n      return false;\n    }\n    if (\n      eventId !== undefined &&\n      prev.relayListId !== undefined &&\n      prev.updatedAt === updatedAt &&\n      !isReplaceableWinner(\n        { created_at: updatedAt, id: eventId },\n        { created_at: prev.updatedAt, id: prev.relayListId },\n      )\n    ) {\n      return false;\n    }\n\n    const write: string[] = [];\n    const read: string[] = [];\n    for (const item of items) {\n      let url: string;\n      try {\n        url = normalizeURL(item.url);\n      } catch {\n        continue;\n      }\n      if (item.marker !== \"read\" && !write.includes(url)) {\n        write.push(url);\n      }\n      if (item.marker !== \"write\" && !read.includes(url)) {\n        read.push(url);\n      }\n    }\n\n    this.#put(pk, {\n      write: write.slice(0, this.#maxRelays),\n      read: read.slice(0, this.#maxRelays),\n      dm: prev.dm,\n      updatedAt,\n      dmUpdatedAt: prev.dmUpdatedAt,\n      relayListId: eventId ?? prev.relayListId,\n      dmListId: prev.dmListId,\n    });\n    return true;\n  }\n\n  setDmRoutes(\n    pubkey: string,\n    relays: ReadonlyArray<string>,\n    updatedAt: number = nowSeconds(),\n    eventId?: string,\n  ): boolean {\n    const pk = pubkey.toLowerCase();\n    const prev = this.#lookup(pk) ?? emptyRoutes();\n    if (prev.dmUpdatedAt > updatedAt) {\n      return false;\n    }\n    if (\n      eventId !== undefined &&\n      prev.dmListId !== undefined &&\n      prev.dmUpdatedAt === updatedAt &&\n      !isReplaceableWinner(\n        { created_at: updatedAt, id: eventId },\n        { created_at: prev.dmUpdatedAt, id: prev.dmListId },\n      )\n    ) {\n      return false;\n    }\n\n    const dm = normalizeRelayUrls(relays);\n\n    this.#put(pk, {\n      write: prev.write,\n      read: prev.read,\n      dm: dm.slice(0, this.#maxRelays),\n      updatedAt: prev.updatedAt,\n      dmUpdatedAt: updatedAt,\n      relayListId: prev.relayListId,\n      dmListId: eventId ?? prev.dmListId,\n    });\n    return true;\n  }\n\n  getRoutes(pubkey: string): Readonly<PubkeyRoutes> | undefined {\n    return this.#lookup(pubkey.toLowerCase());\n  }\n\n  outboxRelays(pubkey: string): ReadonlyArray<string> {\n    return this.#lookup(pubkey.toLowerCase())?.write ?? [];\n  }\n\n  inboxRelays(pubkey: string): ReadonlyArray<string> {\n    return this.#lookup(pubkey.toLowerCase())?.read ?? [];\n  }\n\n  /** NIP-17 kind:10050 delivery relays for gift-wraps. */\n  dmRelays(pubkey: string): ReadonlyArray<string> {\n    return this.#lookup(pubkey.toLowerCase())?.dm ?? [];\n  }\n\n  clear(pubkey?: string): void {\n    if (pubkey !== undefined && pubkey !== \"\") {\n      this.#routes.delete(pubkey.toLowerCase());\n    } else {\n      this.#routes.clear();\n    }\n  }\n\n  get size(): number {\n    return this.#routes.size;\n  }\n\n  /**\n   * Route a user-facing filter into per-relay sub-filters plus leftover.\n   *\n   * - Authors → outbox relays, filter narrowed per relay's authors\n   * - #p only → inbox relays of those pubkeys\n   * - Neither / all unrouted → remainder is the original filter\n   * - Mixed → remainder is the narrowed leftover; all routed → no remainder\n   */\n  route(filter: Filter): RoutedFilter {\n    const authors = filter.authors?.map((a) => a.toLowerCase());\n    const pTags = filter[\"#p\"]?.map((p) => p.toLowerCase());\n\n    if ((!authors || authors.length === 0) && (!pTags || pTags.length === 0)) {\n      return { perRelay: new Map(), remainder: filter };\n    }\n\n    if (authors && authors.length > 0 && (!pTags || pTags.length === 0)) {\n      return this.#breakAuthors(filter, authors, \"write\");\n    }\n\n    if (pTags && pTags.length > 0 && (!authors || authors.length === 0)) {\n      const { authors: _authors, ...base } = filter;\n      return this.#breakAuthors(base, pTags, \"read\", (b, pubkeys) => ({ ...b, \"#p\": pubkeys }));\n    }\n\n    // both authors and #p: send full filter to union of routes\n    const unionKeys = new Set([...(authors ?? []), ...(pTags ?? [])]);\n    const relays = new Set<string>();\n    let anyUnrouted = false;\n    for (const pk of unionKeys) {\n      const r = this.#lookup(pk);\n      const urls = r ? [...r.write, ...r.read] : [];\n      if (urls.length === 0) {\n        anyUnrouted = true;\n        continue;\n      }\n      for (const u of urls) {\n        relays.add(u);\n      }\n    }\n    if (relays.size === 0) {\n      return { perRelay: new Map(), remainder: filter };\n    }\n    const map = new Map<string, Filter>();\n    for (const url of relays) {\n      map.set(url, { ...filter });\n    }\n    return anyUnrouted ? { perRelay: map, remainder: filter } : { perRelay: map };\n  }\n\n  #breakAuthors(\n    filter: Filter,\n    pubkeys: string[],\n    direction: \"read\" | \"write\",\n    narrow: (base: Filter, pubkeys: string[]) => Filter = (base, pks) => ({\n      ...base,\n      authors: pks,\n    }),\n  ): RoutedFilter {\n    const perRelay = new Map<string, string[]>();\n    const unrouted: string[] = [];\n    let anyRoute = false;\n\n    for (const pk of pubkeys) {\n      const routes = this.#lookup(pk);\n      const urls = direction === \"write\" ? routes?.write : routes?.read;\n      if (!urls || urls.length === 0) {\n        unrouted.push(pk);\n        continue;\n      }\n      anyRoute = true;\n      for (const url of urls) {\n        const list = perRelay.get(url) ?? [];\n        list.push(pk);\n        perRelay.set(url, list);\n      }\n    }\n\n    if (!anyRoute) {\n      return { perRelay: new Map(), remainder: filter };\n    }\n\n    const map = new Map<string, Filter>();\n    for (const [url, pks] of perRelay) {\n      map.set(url, narrow(filter, pks));\n    }\n    return unrouted.length > 0\n      ? { perRelay: map, remainder: narrow(filter, unrouted) }\n      : { perRelay: map };\n  }\n\n  /** Read that refreshes LRU recency. */\n  #lookup(pk: string): PubkeyRoutes | undefined {\n    const routes = this.#routes.get(pk);\n    if (routes !== undefined) {\n      touchKey(this.#routes, pk, routes);\n    }\n    return routes;\n  }\n\n  /** Write at the newest LRU end, then trim the oldest beyond the cap. */\n  #put(pk: string, routes: PubkeyRoutes): void {\n    touchKey(this.#routes, pk, routes);\n    trimOldest(this.#routes, this.#maxPubkeys);\n  }\n}\n"],"mappings":"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"}

package/dist/gossip.d.mts

@@ -1,3 +1,3 @@
-import { i as RoutedFilter, n as GossipOptions, r as PubkeyRoutes, t as Gossip } from "./gossip-DpIvkBuj.mjs";
+import { i as RoutedFilter, n as GossipOptions, r as PubkeyRoutes, t as Gossip } from "./gossip-C7HLW5kI.mjs";
 import "./index-CaxrMD1A.mjs";
 export { Gossip, type GossipOptions, type PubkeyRoutes, type RoutedFilter };

package/dist/gossip.mjs

@@ -1,2 +1,2 @@
-import { t as Gossip } from "./gossip-oloDMWEj.mjs";
+import { t as Gossip } from "./gossip-CcTp9VpU.mjs";
 export { Gossip };

package/dist/{index-CvkvqB16.d.mts → index-DU9tRFTZ.d.mts}

@@ -1,4 +1,3 @@
-import { t as Event } from "./event-fU3Y01PR.mjs";
 //#region src/core/limits.d.ts
 /** NIP-01 event id length in bytes. */
 declare const EVENT_ID_BYTES = 32;
@@ -30,6 +29,11 @@ declare function assertSecretKeyBytes(bytes: Uint8Array): void;
  * serialization keeps a trailing `/` on the root path (`wss://a.example/`).
  */
 declare function normalizeURL(url: string): string;
+/**
+ * Normalize each entry like {@link normalizeURL}; empty or invalid entries are skipped and the
+ * results are deduplicated in first-seen order.
+ */
+declare function normalizeRelayUrls(urls: Iterable<string>): string[];
 //#endregion
 //#region src/core/kind.d.ts
 /** NIP-01 regular: stored by relays. */
@@ -80,22 +84,5 @@ type KindName = keyof typeof Kind;
 /** Union of the numeric kind values on {@link Kind}. */
 type KnownKind = (typeof Kind)[KindName];
 //#endregion
-//#region src/core/verifier.d.ts
-/**
- * Verification backend: return true iff `sha256(serializedUtf8)` equals `id` and `sig` is a valid
- * BIP-340 signature of `id` by the x-only `pubkey`. Inputs are raw bytes (`id`/`pubkey` 32, `sig`
- * 64). Exceptions propagate through the built verifier unmarked — a throwing backend is broken and
- * must surface.
- */
-type SerializedEventVerifier = (serializedUtf8: Uint8Array, id: Uint8Array, pubkey: Uint8Array, sig: Uint8Array) => boolean;
-/**
- * Build an event verifier with exactly the semantics of {@link verifyEvent}, delegating the hash and
- * signature check to `backend`. Verified/failed results share `verifyEvent`'s WeakSet caches, so
- * verifiers built this way and `verifyEvent` agree on (and reuse) each other's results.
- */
-declare function createEventVerifier(backend: SerializedEventVerifier): (event: Event) => boolean;
-/** Verify event id and BIP-340 signature. Uses WeakSet cache (does not mutate the event). */
-declare const verifyEvent: (event: Event) => boolean;
-//#endregion
-export { SIGNATURE_BYTES as C, SECRET_KEY_BYTES as S, isHex32 as _, KindClassification as a, EVENT_ID_BYTES as b, classifyKind as c, isRegularKind as d, isReplaceableKind as f, hexToBytes as g, bytesToHex as h, Kind as i, isAddressableKind as l, assertSecretKeyBytes as m, createEventVerifier as n, KindName as o, assertHex32 as p, verifyEvent as r, KnownKind as s, SerializedEventVerifier as t, isEphemeralKind as u, isHex64 as v, SUBSCRIPTION_ID_MAX_CHARS as w, PUBLIC_KEY_BYTES as x, normalizeURL as y };
-//# sourceMappingURL=index-CvkvqB16.d.mts.map
+export { SUBSCRIPTION_ID_MAX_CHARS as S, normalizeURL as _, classifyKind as a, SECRET_KEY_BYTES as b, isRegularKind as c, assertSecretKeyBytes as d, bytesToHex as f, normalizeRelayUrls as g, isHex64 as h, KnownKind as i, isReplaceableKind as l, isHex32 as m, KindClassification as n, isAddressableKind as o, hexToBytes as p, KindName as r, isEphemeralKind as s, Kind as t, assertHex32 as u, EVENT_ID_BYTES as v, SIGNATURE_BYTES as x, PUBLIC_KEY_BYTES as y };
+//# sourceMappingURL=index-DU9tRFTZ.d.mts.map

package/dist/{index-q4MDce_r.d.mts → index-DiXwNn2M.d.mts}

@@ -1,7 +1,7 @@
-import { t as Event } from "./event-fU3Y01PR.mjs";
-import { t as Filter } from "./filter-C0IMByE3.mjs";
-import { a as NostrError } from "./error-CR8Urc84.mjs";
-import { n as Pool } from "./pool-DBIYMtwy.mjs";
+import { t as Event } from "./event-DJeb_DIL.mjs";
+import { t as Filter } from "./filter-jI_9htF7.mjs";
+import { a as NostrError } from "./error-BquXDmIN.mjs";
+import { g as Closer, n as Pool } from "./pool-SzJKPIa3.mjs";
 //#region src/relay/error.d.ts
 /** Base class for relay errors; carries the relay URL when known. */
 declare class RelayError extends NostrError {
@@ -69,9 +69,7 @@ type FanInOptions = {
  * Aggregate EOSE/close across routed jobs. One `seen` set. `pending` counts URL list entries
  * (duplicates included). `pendingEose` counts unique `jobIndex:url` keys.
  */
-declare function fanIn(pool: Pool, jobs: ReadonlyArray<RoutedJob>, opts?: FanInOptions): {
-  close: (reason?: string) => void;
-};
+declare function fanIn(pool: Pool, jobs: ReadonlyArray<RoutedJob>, opts?: FanInOptions): Closer;
 declare function fetchRouted(pool: Pool, jobs: ReadonlyArray<RoutedJob>, opts?: {
   timeoutMs?: number | undefined;
   signal?: AbortSignal | undefined;
@@ -81,4 +79,4 @@ declare function fetchRouted(pool: Pool, jobs: ReadonlyArray<RoutedJob>, opts?:
 }): Promise<Event[]>;
 //#endregion
 export { isInsecureRelayUrl as a, RelayError as c, RelayTimeoutError as d, fetchRouted as i, RelayPublishError as l, RoutedJob as n, RelayClosedError as o, fanIn as r, RelayConnectionError as s, FanInOptions as t, RelaySuspendedError as u };
-//# sourceMappingURL=index-q4MDce_r.d.mts.map
+//# sourceMappingURL=index-DiXwNn2M.d.mts.map

package/dist/{index-CNl2q67H.d.mts → index-DocgD9K0.d.mts}

@@ -1,17 +1,16 @@
-import { n as EventTemplate, r as UnsignedEvent, t as Event } from "./event-fU3Y01PR.mjs";
-import { t as EventBuilder } from "./builder-sSflu6nB.mjs";
-import { t as Filter } from "./filter-C0IMByE3.mjs";
-import { t as Gossip } from "./gossip-DpIvkBuj.mjs";
-import { a as NostrError } from "./error-CR8Urc84.mjs";
-import { i as PoolFetchResult, n as Pool, o as PoolPublishResult, t as InvalidEventPolicy } from "./pool-DBIYMtwy.mjs";
-import { t as WebSocketConstructor } from "./websocket-CmeqvAkp.mjs";
-import { t as EventStore } from "./types-2pCUprRU.mjs";
-import { t as ReactiveEventStore } from "./reactive-7aqeip4A.mjs";
-import { a as OutboxFeed, n as Loaders } from "./index-lvXeER5t.mjs";
-import { a as Rumor } from "./nip59-zQgdLcEr.mjs";
-import { i as ReplyTo, r as Recipient } from "./nip17-CKIufV98.mjs";
-import { t as NostrSigner } from "./types-CRQEk0Oi.mjs";
-import { t as StorageError } from "./error-BW7re1UN.mjs";
+import { n as EventTemplate, r as UnsignedEvent, t as Event } from "./event-DJeb_DIL.mjs";
+import { t as EventBuilder } from "./builder-DgkqDylK.mjs";
+import { t as Filter } from "./filter-jI_9htF7.mjs";
+import { t as Gossip } from "./gossip-C7HLW5kI.mjs";
+import { a as NostrError } from "./error-BquXDmIN.mjs";
+import { a as PoolOptions, g as Closer, i as PoolFetchResult, n as Pool, o as PoolPublishResult } from "./pool-SzJKPIa3.mjs";
+import { t as EventStore } from "./types-Cm-XMgtH.mjs";
+import { t as ReactiveEventStore } from "./reactive-BJ1ggn4d.mjs";
+import { a as OutboxFeed, n as Loaders } from "./index-iLT8UzY3.mjs";
+import { a as Rumor } from "./nip59-BFIihLYY.mjs";
+import { i as ReplyTo, r as Recipient } from "./nip17-cTDFfFVt.mjs";
+import { t as NostrSigner } from "./types-DNmiscfd.mjs";
+import { t as StorageError } from "./error-BD_0QFKT.mjs";
 //#region src/client/types.d.ts
 /** Direction of a {@link Client.sync} run: upload, download, or both. */
 declare const SyncDirection: {
@@ -23,18 +22,18 @@ declare const SyncDirection: {
 type SyncDirectionName = (typeof SyncDirection)[keyof typeof SyncDirection];
 /** Options for {@link Client.sync} (NIP-77 set reconciliation). */
 type SyncOptions = {
-  relays?: ReadonlyArray<string>;
-  direction?: SyncDirectionName;
+  relays?: ReadonlyArray<string> | undefined;
+  direction?: SyncDirectionName | undefined;
   /**
    * Wall-clock deadline for the Negentropy reconciliation session (`NEG-OPEN` through `NEG-CLOSE`),
    * in milliseconds. One clock for the whole session — not reset per `NEG-MSG`. Default: the relay
    * `publishTimeoutMs`. Upload/download phases reuse this value as their per-call timeout.
    */
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  dryRun?: boolean;
+  timeoutMs?: number | undefined;
+  signal?: AbortSignal | undefined;
+  dryRun?: boolean | undefined;
   /** When false, skip observe/storage on downloaded events. Default true. */
-  observe?: boolean;
+  observe?: boolean | undefined;
 };
 /** Outcome of a {@link Client.sync} run: ids compared, sent, received, and failures. */
 type SyncSummary = {
@@ -45,126 +44,104 @@ type SyncSummary = {
   sendFailures: Record<string, string>;
   persistFailures: Record<string, string>;
 };
-/** Options for {@link Client.builder} / `ClientOptions` accepted by the builder. */
-type ClientOptions = {
-  signer?: NostrSigner;
-  relays?: ReadonlyArray<string>;
-  websocketImplementation?: WebSocketConstructor;
-  /** Injected EVENT verifier. Default is core BIP-340. */
-  verifyEvent?: (event: Event) => boolean;
-  connectTimeoutMs?: number;
-  publishTimeoutMs?: number;
+/**
+ * Options for the {@link Client} constructor. Pool fields are forwarded to {@link Pool}; the
+ * client-only fields are documented here.
+ */
+type ClientOptions = Omit<PoolOptions, "automaticallyAuth"> & {
+  signer?: NostrSigner | undefined;
+  relays?: ReadonlyArray<string> | undefined;
   /**
    * When true (default), answer NIP-42 AUTH automatically. The signer is read at challenge time, so
    * `setSigner()` applies to live connections; challenges received while no signer is set are
    * ignored.
    */
-  automaticAuth?: boolean;
-  /** When true (default), relays reconnect with backoff after disconnect. */
-  enableReconnect?: boolean;
-  /** Keepalive ping. Default false. */
-  enablePing?: boolean;
-  pingIntervalMs?: number;
-  pingTimeoutMs?: number;
-  /** Forwarded to the pool: when false (default), `ws://` relays are rejected. */
-  allowInsecure?: boolean;
-  /** Forwarded to the pool: `ws://` URLs allowed despite `allowInsecure`. */
-  trustedInsecureUrls?: ReadonlyArray<string>;
-  /** Forwarded to the pool: close idle relays after this many ms. */
-  idleTimeoutMs?: number;
-  /** Forwarded to the pool: soft cap on connected non-pinned relays. */
-  maxRelays?: number;
-  /** Forwarded to the pool: relays never closed by idle cleanup or `maxRelays`. */
-  pinnedUrls?: ReadonlyArray<string>;
-  /**
-   * Forwarded to the pool: a relay exceeding `limit` verification failures inside `windowMs` is
-   * disconnected and suspended for `cooldownMs`.
-   */
-  invalidEventPolicy?: InvalidEventPolicy;
-  /** Forwarded to the pool: fired once when a relay is suspended, with the lift time. */
-  onRelaySuspended?: (url: string, until: number) => void;
-  gossip?: Gossip;
+  automaticAuth?: boolean | undefined;
+  gossip?: Gossip | undefined;
   /**
    * Local event store. Defaults to {@link MemoryEventStore}. Browser apps that want persistence must
    * pass {@link IndexedDbEventStore} and `await open()`.
    */
-  storage?: EventStore;
+  storage?: EventStore | undefined;
   /**
    * Synchronous reactive index that mirrors every ingested event before callbacks and persistence.
    * Defaults to a new {@link ReactiveEventStore}.
    */
-  index?: ReactiveEventStore;
+  index?: ReactiveEventStore | undefined;
   /**
    * When true (default), every ingested event is written to storage. Set false to disable automatic
    * persistence while keeping the store for manual use.
    */
-  persistEvents?: boolean;
+  persistEvents?: boolean | undefined;
+};
+/** Typed event payloads for {@link Client.on}. */
+type ClientEventMap = {
   /**
    * Storage I/O failures: live `putMany` flush and `fetchEvents({ localFirst: true })` query. Those
    * paths do not throw.
    */
-  onstorageerror?: (err: StorageError) => void;
+  storageerror: StorageError;
 };
 type FetchEventsOptions = {
-  relays?: string[];
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  gossip?: boolean;
+  relays?: ReadonlyArray<string> | undefined;
+  timeoutMs?: number | undefined;
+  signal?: AbortSignal | undefined;
+  gossip?: boolean | undefined;
   /** When true, query local storage first and merge with network results. Defaults to false. */
-  localFirst?: boolean;
+  localFirst?: boolean | undefined;
   /** When false, skip writing fetched events to storage/observe. Default true. */
-  observe?: boolean;
+  observe?: boolean | undefined;
   /**
    * Every event of every relay batch, including duplicates across relays. `relayUrl` is the
    * normalized URL of the relay that delivered it.
    */
-  onevent?: (event: Event, relayUrl: string) => void;
+  onevent?: ((event: Event, relayUrl: string) => void) | undefined;
 };
 /** Options for {@link Client.fetchEach}: one-shot per-relay fetch, no gossip routing. */
 type FetchEachOptions = {
-  relays?: string[];
-  timeoutMs?: number;
-  signal?: AbortSignal;
+  relays?: ReadonlyArray<string> | undefined;
+  timeoutMs?: number | undefined;
+  signal?: AbortSignal | undefined;
   /** When false, skip writing fetched events to storage/observe. Default true. */
-  observe?: boolean;
+  observe?: boolean | undefined;
 };
 type SubscribeOptions = {
-  relays?: string[];
+  relays?: ReadonlyArray<string> | undefined;
   /**
    * First receipt of each event only (deduped across relays). `relayUrl` is the normalized URL of
    * the relay that delivered it first.
    */
-  onevent?: (event: Event, relayUrl: string) => void;
+  onevent?: ((event: Event, relayUrl: string) => void) | undefined;
   /** Every receipt from every relay, including duplicates skipped by dedupe. */
-  receivedEvent?: (id: string, relayUrl: string) => void;
-  oneose?: () => void;
-  onclose?: (reason: string) => void;
-  signal?: AbortSignal;
-  id?: string;
+  receivedEvent?: ((id: string, relayUrl: string) => void) | undefined;
+  oneose?: (() => void) | undefined;
+  onclose?: ((reason: string) => void) | undefined;
+  signal?: AbortSignal | undefined;
+  id?: string | undefined;
   /**
    * If set, fire `oneose` once after this many ms if not all relays have EOSEd. Does not close the
    * subscription.
    */
-  eoseTimeoutMs?: number;
+  eoseTimeoutMs?: number | undefined;
   /** Fan out REQs via NIP-65 gossip routes when available. */
-  gossip?: boolean;
+  gossip?: boolean | undefined;
   /** When false, skip writing received events to storage/observe. Default true. */
-  observe?: boolean;
+  observe?: boolean | undefined;
 };
 type PublishOptions = {
-  relays?: string[];
-  timeoutMs?: number;
-  gossip?: boolean;
+  relays?: ReadonlyArray<string> | undefined;
+  timeoutMs?: number | undefined;
+  gossip?: boolean | undefined;
   /** When false, skip writing the published event to storage/observe. Default true. */
-  observe?: boolean;
+  observe?: boolean | undefined;
 };
 /** Options for sending a NIP-17 private message. */
 type SendPrivateMessageOptions = {
-  readonly subject?: string;
-  readonly replyTo?: ReplyTo;
-  readonly created_at?: number;
-  readonly timeoutMs?: number;
-  readonly observe?: boolean;
+  readonly subject?: string | undefined;
+  readonly replyTo?: ReplyTo | undefined;
+  readonly created_at?: number | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly observe?: boolean | undefined;
 };
 /** Result of sending a NIP-17 DM: the rumor plus per-recipient wrap publish results. */
 type PrivateMessageSendResult = {
@@ -180,83 +157,31 @@ type ReceivedPrivateMessage = {
   wrap: Event;
   rumor: Rumor;
   /** Normalized URL of the relay that delivered the wrap, when known. */
-  relayUrl?: string;
+  relayUrl?: string | undefined;
 };
 /** Options for fetching NIP-17 private-message history. */
 type FetchPrivateMessagesOptions = {
-  readonly since?: number;
-  readonly until?: number;
-  readonly timeoutMs?: number;
-  readonly signal?: AbortSignal;
-  readonly observe?: boolean;
+  readonly since?: number | undefined;
+  readonly until?: number | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly observe?: boolean | undefined;
 };
 /** Options for a live NIP-17 private-message subscription. */
 type SubscribePrivateMessagesOptions = {
-  readonly since?: number;
-  readonly onevent?: (msg: ReceivedPrivateMessage) => void;
-  readonly oneose?: () => void;
-  readonly onclose?: (reason: string) => void;
-  readonly signal?: AbortSignal;
-  readonly eoseTimeoutMs?: number;
-  readonly observe?: boolean;
+  readonly since?: number | undefined;
+  readonly onevent?: ((msg: ReceivedPrivateMessage) => void) | undefined;
+  readonly oneose?: (() => void) | undefined;
+  readonly onclose?: ((reason: string) => void) | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly eoseTimeoutMs?: number | undefined;
+  readonly observe?: boolean | undefined;
 };
 /** Client lifecycle, configuration, or abort failure (not cryptographic). */
 declare class ClientError extends NostrError {
   name: string;
 }
 //#endregion
-//#region src/client/builder.d.ts
-/**
- * Fluent constructor for {@link Client}. The constructor is supplied by {@link Client.builder} so
- * this module never imports the `Client` value, keeping the client/builder dependency
- * one-directional.
- */
-declare class ClientBuilder {
-  #private;
-  constructor(newClient: (opts: ClientOptions) => Client);
-  signer(signer: NostrSigner): this;
-  relays(urls: ReadonlyArray<string>): this;
-  addRelay(url: string): this;
-  websocketImplementation(impl: WebSocketConstructor): this;
-  verifyEvent(fn: (event: Event) => boolean): this;
-  connectTimeoutMs(ms: number): this;
-  publishTimeoutMs(ms: number): this;
-  automaticAuth(enabled: boolean): this;
-  /** Allow `ws://` relays. Default false. */
-  allowInsecure(allow: boolean): this;
-  /** `ws://` URLs allowed despite `allowInsecure` being off. */
-  trustedInsecureUrls(urls: ReadonlyArray<string>): this;
-  /** Close idle relays after this many ms. Unset = disabled. */
-  idleTimeoutMs(ms: number): this;
-  /** Soft cap on connected non-pinned relays. */
-  maxRelays(n: number): this;
-  /** Relays never closed by idle cleanup or `maxRelays` eviction. */
-  pinnedUrls(urls: ReadonlyArray<string>): this;
-  /** Forwarded to the pool: suspend a relay delivering too many invalid events. */
-  invalidEventPolicy(policy: InvalidEventPolicy): this;
-  /** Forwarded to the pool: fired once when a relay is suspended, with the lift time. */
-  onRelaySuspended(cb: (url: string, until: number) => void): this;
-  enableReconnect(enabled: boolean): this;
-  enablePing(enabled: boolean): this;
-  pingIntervalMs(ms: number): this;
-  pingTimeoutMs(ms: number): this;
-  /**
-   * Local event store. Defaults to {@link MemoryEventStore}. Browser apps that want persistence must
-   * pass {@link IndexedDbEventStore} and `await open()`.
-   */
-  storage(store: EventStore): this;
-  /**
-   * Synchronous reactive index mirroring ingested events. Defaults to a new
-   * {@link ReactiveEventStore}.
-   */
-  index(index: ReactiveEventStore): this;
-  /** When false, Client will not auto-write events to storage. Default true. */
-  persistEvents(enabled: boolean): this;
-  gossip(gossip: Gossip): this;
-  onstorageerror(fn: (err: StorageError) => void): this;
-  build(): Client;
-}
-//#endregion
 //#region src/client/client.d.ts
 /** Layer-5 facade: signer + default relays + pool + loaders + gossip + event store. */
 declare class Client {
@@ -266,9 +191,7 @@ declare class Client {
   readonly gossip: Gossip;
   readonly storage: EventStore;
   readonly index: ReactiveEventStore;
-  onstorageerror: ((err: StorageError) => void) | undefined;
   constructor(opts?: ClientOptions);
-  static builder(): ClientBuilder;
   get signer(): NostrSigner | undefined;
   get relays(): ReadonlyArray<string>;
   get isShutdown(): boolean;
@@ -277,9 +200,15 @@ declare class Client {
   removeRelay(url: string): void;
   /** Connect all configured relays (best-effort; failures are ignored). */
   connect(opts?: {
-    signal?: AbortSignal;
+    signal?: AbortSignal | undefined;
   }): Promise<void>;
   shutdown(): Promise<void>;
+  /**
+   * Listen for a client event. Multiple listeners per type are allowed and fire in registration
+   * order; a throwing listener is reported and does not break the dispatch. Returns an unsubscribe
+   * function.
+   */
+  on<K extends keyof ClientEventMap>(type: K, listener: (err: ClientEventMap[K]) => void): () => void;
   /** Ingest one inbound event: index (with relay URL) → meta → persistence. */
   observe(event: Event, relayUrl?: string): void;
   /** Ingest many events (deduped by id, order preserved) as one persist batch. */
@@ -316,26 +245,22 @@ declare class Client {
    * Fetch events. With `gossip: true`, routes filters by NIP-65 when possible. With `localFirst:
    * true`, merges storage hits with network results.
    */
-  fetchEvents(filter: Filter | Filter[], opts?: FetchEventsOptions): Promise<Event[]>;
+  fetchEvents(filter: Filter | ReadonlyArray<Filter>, opts?: FetchEventsOptions): Promise<Event[]>;
   /**
    * One-shot fetch with per-relay results: each entry reports its events and end reason (`eose`,
    * `closed`, `timeout`, or `failed` when the relay could not be reached). Events are ingested into
    * the index with each relay's URL in `seenOn` and persisted exactly like {@link fetchEvents}
    * (`observe` defaults to true). No gossip routing and no local merge.
    */
-  fetchEach(filter: Filter | Filter[], opts?: FetchEachOptions): Promise<PoolFetchResult[]>;
+  fetchEach(filter: Filter | ReadonlyArray<Filter>, opts?: FetchEachOptions): Promise<PoolFetchResult[]>;
   /** Query local storage only (no network). */
-  queryLocal(filter: Filter | Filter[]): Promise<Event[]>;
-  subscribe(filter: Filter | Filter[], opts?: SubscribeOptions): {
-    close: (reason?: string) => void;
-  };
+  queryLocal(filter: Filter | ReadonlyArray<Filter>): Promise<Event[]>;
+  subscribe(filter: Filter | ReadonlyArray<Filter>, opts?: SubscribeOptions): Closer;
   /** Publish a kind:10050 NIP-17 DM relay list (`relay` tags). Not kind 10002. */
   setDmRelays(relays: ReadonlyArray<string>, opts?: PublishOptions): Promise<PoolPublishResult[]>;
   sendPrivateMessage(recipients: string | Recipient | ReadonlyArray<string | Recipient>, content: string, opts?: SendPrivateMessageOptions): Promise<PrivateMessageSendResult>;
   fetchPrivateMessages(opts?: FetchPrivateMessagesOptions): Promise<ReceivedPrivateMessage[]>;
-  subscribePrivateMessages(opts?: SubscribePrivateMessagesOptions): Promise<{
-    close: (reason?: string) => void;
-  }>;
+  subscribePrivateMessages(opts?: SubscribePrivateMessagesOptions): Promise<Closer>;
   /**
    * NIP-77 sync against one relay: reconcile, then optionally upload local-only events and/or
    * download remote-only events. `observe: false` skips putMany and ingest; received ids are still
@@ -350,5 +275,5 @@ declare class Client {
   sync(filter: Filter, opts?: SyncOptions): Promise<SyncSummary>;
 }
 //#endregion
-export { SyncSummary as _, FetchEachOptions as a, PrivateMessageSendResult as c, SendPrivateMessageOptions as d, SubscribeOptions as f, SyncOptions as g, SyncDirectionName as h, ClientOptions as i, PublishOptions as l, SyncDirection as m, ClientBuilder as n, FetchEventsOptions as o, SubscribePrivateMessagesOptions as p, ClientError as r, FetchPrivateMessagesOptions as s, Client as t, ReceivedPrivateMessage as u };
-//# sourceMappingURL=index-CNl2q67H.d.mts.map
+export { SyncSummary as _, FetchEachOptions as a, PrivateMessageSendResult as c, SendPrivateMessageOptions as d, SubscribeOptions as f, SyncOptions as g, SyncDirectionName as h, ClientOptions as i, PublishOptions as l, SyncDirection as m, ClientError as n, FetchEventsOptions as o, SubscribePrivateMessagesOptions as p, ClientEventMap as r, FetchPrivateMessagesOptions as s, Client as t, ReceivedPrivateMessage as u };
+//# sourceMappingURL=index-DocgD9K0.d.mts.map