@qntx/nostr 0.6.0 → 0.8.0

package/dist/nips/nip98.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"nip98.mjs","names":[],"sources":["../../src/nips/nip98.ts"],"sourcesContent":["/**\n * NIP-98: HTTP Auth (kind 27235). Token is standard base64 of the signed event JSON, not base64url.\n *\n * @see https://github.com/nostr-protocol/nips/blob/master/98.md\n */\nimport { sha256 } from \"@noble/hashes/sha2.js\";\nimport { base64 } from \"@scure/base\";\n\nimport { NostrError } from \"../core/error.ts\";\nimport type { Event, EventTemplate } from \"../core/event.ts\";\nimport { validateSignedEvent } from \"../core/event.ts\";\nimport { Kind } from \"../core/kind.ts\";\nimport type { Tag } from \"../core/tag.ts\";\nimport { bytesToHex, utf8Decoder, utf8Encoder } from \"../core/util.ts\";\nimport { verifyEvent } from \"../core/verifier.ts\";\n\nconst AUTHORIZATION_SCHEME = \"Nostr \";\nconst DEFAULT_MAX_SKEW_SEC = 60;\n\nexport class Nip98Error extends NostrError {\n  override name = \"Nip98Error\";\n}\n\n/** SHA-256 of the request body: raw bytes for string/Uint8Array, else JSON.stringify. */\nfunction hashPayload(payload: unknown): string {\n  const bytes =\n    typeof payload === \"string\"\n      ? utf8Encoder.encode(payload)\n      : payload instanceof Uint8Array\n        ? payload\n        : utf8Encoder.encode(JSON.stringify(payload));\n  return bytesToHex(sha256(bytes));\n}\n\n/** RFC 4648 standard base64; accept missing `=` (NIP-98 spec example is unpadded). */\nfunction decodeStandardBase64(encoded: string): Uint8Array {\n  const rem = encoded.length % 4;\n  const padded = rem === 0 ? encoded : encoded + \"=\".repeat(4 - rem);\n  return base64.decode(padded);\n}\n\nfunction stripAuthorizationScheme(token: string): string {\n  const prefix = /^nostr\\s+/i.exec(token);\n  return prefix ? token.slice(prefix[0].length) : token;\n}\n\n/**\n * Sign a kind 27235 auth event and encode it as a NIP-98 token. Uses standard base64\n * (`@scure/base`), not base64url.\n */\nexport async function getToken(\n  url: string,\n  method: string,\n  sign: (template: EventTemplate) => Promise<Event> | Event,\n  opts?: {\n    includeAuthorizationScheme?: boolean;\n    content?: string;\n    payload?: unknown;\n    now?: number;\n  },\n): Promise<string> {\n  const tags: Tag[] = [\n    [\"u\", url],\n    [\"method\", method],\n  ];\n  if (opts?.payload !== undefined) {\n    tags.push([\"payload\", hashPayload(opts.payload)]);\n  }\n\n  const signed = await sign({\n    kind: Kind.HttpAuth,\n    created_at: opts?.now ?? Math.floor(Date.now() / 1000),\n    tags,\n    content: opts?.content ?? \"\",\n  });\n\n  const encoded = base64.encode(utf8Encoder.encode(JSON.stringify(signed)));\n  return opts?.includeAuthorizationScheme === true ? AUTHORIZATION_SCHEME + encoded : encoded;\n}\n\n/** Decode a NIP-98 token (with or without the `Nostr ` scheme) into an event. */\nexport function unpackEventFromToken(token: string): Event {\n  if (token === \"\") {\n    throw new Nip98Error(\"missing token\");\n  }\n\n  const encoded = stripAuthorizationScheme(token);\n\n  let json: string;\n  try {\n    json = utf8Decoder.decode(decodeStandardBase64(encoded));\n  } catch (error) {\n    throw new Nip98Error(\"invalid token encoding\", { cause: error });\n  }\n  if (!json.startsWith(\"{\")) {\n    throw new Nip98Error(\"invalid token\");\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(json);\n  } catch (error) {\n    throw new Nip98Error(\"invalid token JSON\", { cause: error });\n  }\n  if (!validateSignedEvent(parsed)) {\n    throw new Nip98Error(\"token is not a signed event\");\n  }\n  return parsed;\n}\n\n/**\n * True when `event` is a valid NIP-98 auth event for `url` + `method`. Verifies signature, kind\n * 27235, timestamp window, `u`, `method`, and optional `payload` tag.\n */\nexport function validateAuthEvent(\n  event: Event,\n  url: string,\n  method: string,\n  opts?: { payload?: unknown; maxSkewSec?: number },\n): boolean {\n  if (!verifyEvent(event)) {\n    return false;\n  }\n  if (event.kind !== Kind.HttpAuth) {\n    return false;\n  }\n\n  const maxSkewSec = opts?.maxSkewSec ?? DEFAULT_MAX_SKEW_SEC;\n  const now = Math.floor(Date.now() / 1000);\n  if (Math.abs(now - event.created_at) > maxSkewSec) {\n    return false;\n  }\n\n  const u = event.tags.find((t) => t[0] === \"u\")?.[1];\n  if (u !== url) {\n    return false;\n  }\n\n  const m = event.tags.find((t) => t[0] === \"method\")?.[1];\n  if (m === undefined || m.toLowerCase() !== method.toLowerCase()) {\n    return false;\n  }\n\n  if (opts?.payload !== undefined) {\n    const payloadTag = event.tags.find((t) => t[0] === \"payload\")?.[1];\n    if (payloadTag !== hashPayload(opts.payload)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;;;;;;;AAgBA,MAAM,uBAAuB;AAC7B,MAAM,uBAAuB;AAE7B,IAAa,aAAb,cAAgC,WAAW;CACzC,OAAgB;AAClB;;AAGA,SAAS,YAAY,SAA0B;CAC7C,MAAM,QACJ,OAAO,YAAY,WACf,YAAY,OAAO,OAAO,IAC1B,mBAAmB,aACjB,UACA,YAAY,OAAO,KAAK,UAAU,OAAO,CAAC;CAClD,OAAO,WAAW,OAAO,KAAK,CAAC;AACjC;;AAGA,SAAS,qBAAqB,SAA6B;CACzD,MAAM,MAAM,QAAQ,SAAS;CAC7B,MAAM,SAAS,QAAQ,IAAI,UAAU,UAAU,IAAI,OAAO,IAAI,GAAG;CACjE,OAAO,OAAO,OAAO,MAAM;AAC7B;AAEA,SAAS,yBAAyB,OAAuB;CACvD,MAAM,SAAS,aAAa,KAAK,KAAK;CACtC,OAAO,SAAS,MAAM,MAAM,OAAO,EAAE,CAAC,MAAM,IAAI;AAClD;;;;;AAMA,eAAsB,SACpB,KACA,QACA,MACA,MAMiB;CACjB,MAAM,OAAc,CAClB,CAAC,KAAK,GAAG,GACT,CAAC,UAAU,MAAM,CACnB;CACA,IAAI,MAAM,YAAY,KAAA,GACpB,KAAK,KAAK,CAAC,WAAW,YAAY,KAAK,OAAO,CAAC,CAAC;CAGlD,MAAM,SAAS,MAAM,KAAK;EACxB,MAAM,KAAK;EACX,YAAY,MAAM,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;EACrD;EACA,SAAS,MAAM,WAAW;CAC5B,CAAC;CAED,MAAM,UAAU,OAAO,OAAO,YAAY,OAAO,KAAK,UAAU,MAAM,CAAC,CAAC;CACxE,OAAO,MAAM,+BAA+B,OAAO,uBAAuB,UAAU;AACtF;;AAGA,SAAgB,qBAAqB,OAAsB;CACzD,IAAI,UAAU,IACZ,MAAM,IAAI,WAAW,eAAe;CAGtC,MAAM,UAAU,yBAAyB,KAAK;CAE9C,IAAI;CACJ,IAAI;EACF,OAAO,YAAY,OAAO,qBAAqB,OAAO,CAAC;CACzD,SAAS,OAAO;EACd,MAAM,IAAI,WAAW,0BAA0B,EAAE,OAAO,MAAM,CAAC;CACjE;CACA,IAAI,CAAC,KAAK,WAAW,GAAG,GACtB,MAAM,IAAI,WAAW,eAAe;CAGtC,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,IAAI;CAC1B,SAAS,OAAO;EACd,MAAM,IAAI,WAAW,sBAAsB,EAAE,OAAO,MAAM,CAAC;CAC7D;CACA,IAAI,CAAC,oBAAoB,MAAM,GAC7B,MAAM,IAAI,WAAW,6BAA6B;CAEpD,OAAO;AACT;;;;;AAMA,SAAgB,kBACd,OACA,KACA,QACA,MACS;CACT,IAAI,CAAC,YAAY,KAAK,GACpB,OAAO;CAET,IAAI,MAAM,SAAS,KAAK,UACtB,OAAO;CAGT,MAAM,aAAa,MAAM,cAAc;CACvC,MAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;CACxC,IAAI,KAAK,IAAI,MAAM,MAAM,UAAU,IAAI,YACrC,OAAO;CAIT,IADU,MAAM,KAAK,MAAM,MAAM,EAAE,OAAO,GAAG,CAAC,GAAG,OACvC,KACR,OAAO;CAGT,MAAM,IAAI,MAAM,KAAK,MAAM,MAAM,EAAE,OAAO,QAAQ,CAAC,GAAG;CACtD,IAAI,MAAM,KAAA,KAAa,EAAE,YAAY,MAAM,OAAO,YAAY,GAC5D,OAAO;CAGT,IAAI,MAAM,YAAY,KAAA,GACD;MAAA,MAAM,KAAK,MAAM,MAAM,EAAE,OAAO,SAAS,CAAC,GAAG,OAC7C,YAAY,KAAK,OAAO,GACzC,OAAO;CAAA;CAIX,OAAO;AACT"}
+{"version":3,"file":"nip98.mjs","names":[],"sources":["../../src/nips/nip98.ts"],"sourcesContent":["/**\n * NIP-98: HTTP Auth (kind 27235). Token is standard base64 of the signed event JSON, not base64url.\n *\n * @see https://github.com/nostr-protocol/nips/blob/master/98.md\n */\nimport { sha256 } from \"@noble/hashes/sha2.js\";\nimport { base64 } from \"@scure/base\";\n\nimport { NostrError } from \"../core/error.ts\";\nimport type { Event, EventTemplate } from \"../core/event.ts\";\nimport { validateSignedEvent } from \"../core/event.ts\";\nimport { Kind } from \"../core/kind.ts\";\nimport { firstTagValue } from \"../core/tag.ts\";\nimport type { Tag } from \"../core/tag.ts\";\nimport { bytesToHex, nowSeconds, utf8Decoder, utf8Encoder } from \"../core/util.ts\";\nimport { verifyEvent } from \"../core/verifier.ts\";\n\nconst AUTHORIZATION_SCHEME = \"Nostr \";\nconst DEFAULT_MAX_SKEW_SEC = 60;\n\nexport class Nip98Error extends NostrError {\n  override name = \"Nip98Error\";\n}\n\n/** SHA-256 of the request body: raw bytes for string/Uint8Array, else JSON.stringify. */\nfunction hashPayload(payload: unknown): string {\n  const bytes =\n    typeof payload === \"string\"\n      ? utf8Encoder.encode(payload)\n      : payload instanceof Uint8Array\n        ? payload\n        : utf8Encoder.encode(JSON.stringify(payload));\n  return bytesToHex(sha256(bytes));\n}\n\n/** RFC 4648 standard base64; accept missing `=` (NIP-98 spec example is unpadded). */\nfunction decodeStandardBase64(encoded: string): Uint8Array {\n  const rem = encoded.length % 4;\n  const padded = rem === 0 ? encoded : encoded + \"=\".repeat(4 - rem);\n  return base64.decode(padded);\n}\n\nfunction stripAuthorizationScheme(token: string): string {\n  const prefix = /^nostr\\s+/i.exec(token);\n  return prefix ? token.slice(prefix[0].length) : token;\n}\n\n/**\n * Sign a kind 27235 auth event and encode it as a NIP-98 token. Uses standard base64\n * (`@scure/base`), not base64url.\n */\nexport async function getToken(\n  url: string,\n  method: string,\n  sign: (template: EventTemplate) => Promise<Event> | Event,\n  opts?: {\n    includeAuthorizationScheme?: boolean | undefined;\n    content?: string | undefined;\n    payload?: unknown;\n    now?: number | undefined;\n  },\n): Promise<string> {\n  const tags: Tag[] = [\n    [\"u\", url],\n    [\"method\", method],\n  ];\n  if (opts?.payload !== undefined) {\n    tags.push([\"payload\", hashPayload(opts.payload)]);\n  }\n\n  const signed = await sign({\n    kind: Kind.HttpAuth,\n    created_at: opts?.now ?? nowSeconds(),\n    tags,\n    content: opts?.content ?? \"\",\n  });\n\n  const encoded = base64.encode(utf8Encoder.encode(JSON.stringify(signed)));\n  return opts?.includeAuthorizationScheme === true ? AUTHORIZATION_SCHEME + encoded : encoded;\n}\n\n/** Decode a NIP-98 token (with or without the `Nostr ` scheme) into an event. */\nexport function unpackEventFromToken(token: string): Event {\n  if (token === \"\") {\n    throw new Nip98Error(\"missing token\");\n  }\n\n  const encoded = stripAuthorizationScheme(token);\n\n  let json: string;\n  try {\n    json = utf8Decoder.decode(decodeStandardBase64(encoded));\n  } catch (error) {\n    throw new Nip98Error(\"invalid token encoding\", { cause: error });\n  }\n  if (!json.startsWith(\"{\")) {\n    throw new Nip98Error(\"invalid token\");\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(json);\n  } catch (error) {\n    throw new Nip98Error(\"invalid token JSON\", { cause: error });\n  }\n  if (!validateSignedEvent(parsed)) {\n    throw new Nip98Error(\"token is not a signed event\");\n  }\n  return parsed;\n}\n\n/**\n * True when `event` is a valid NIP-98 auth event for `url` + `method`. Verifies signature, kind\n * 27235, timestamp window, `u`, `method`, and optional `payload` tag.\n */\nexport function validateAuthEvent(\n  event: Event,\n  url: string,\n  method: string,\n  opts?: { payload?: unknown; maxSkewSec?: number },\n): boolean {\n  if (!verifyEvent(event)) {\n    return false;\n  }\n  if (event.kind !== Kind.HttpAuth) {\n    return false;\n  }\n\n  const maxSkewSec = opts?.maxSkewSec ?? DEFAULT_MAX_SKEW_SEC;\n  const now = nowSeconds();\n  if (Math.abs(now - event.created_at) > maxSkewSec) {\n    return false;\n  }\n\n  const u = firstTagValue(event.tags, \"u\");\n  if (u !== url) {\n    return false;\n  }\n\n  const m = firstTagValue(event.tags, \"method\");\n  if (m === undefined || m.toLowerCase() !== method.toLowerCase()) {\n    return false;\n  }\n\n  if (opts?.payload !== undefined) {\n    const payloadTag = firstTagValue(event.tags, \"payload\");\n    if (payloadTag !== hashPayload(opts.payload)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;;;;;;;AAiBA,MAAM,uBAAuB;AAC7B,MAAM,uBAAuB;AAE7B,IAAa,aAAb,cAAgC,WAAW;CACzC,OAAgB;AAClB;;AAGA,SAAS,YAAY,SAA0B;CAC7C,MAAM,QACJ,OAAO,YAAY,WACf,YAAY,OAAO,OAAO,IAC1B,mBAAmB,aACjB,UACA,YAAY,OAAO,KAAK,UAAU,OAAO,CAAC;CAClD,OAAO,WAAW,OAAO,KAAK,CAAC;AACjC;;AAGA,SAAS,qBAAqB,SAA6B;CACzD,MAAM,MAAM,QAAQ,SAAS;CAC7B,MAAM,SAAS,QAAQ,IAAI,UAAU,UAAU,IAAI,OAAO,IAAI,GAAG;CACjE,OAAO,OAAO,OAAO,MAAM;AAC7B;AAEA,SAAS,yBAAyB,OAAuB;CACvD,MAAM,SAAS,aAAa,KAAK,KAAK;CACtC,OAAO,SAAS,MAAM,MAAM,OAAO,EAAE,CAAC,MAAM,IAAI;AAClD;;;;;AAMA,eAAsB,SACpB,KACA,QACA,MACA,MAMiB;CACjB,MAAM,OAAc,CAClB,CAAC,KAAK,GAAG,GACT,CAAC,UAAU,MAAM,CACnB;CACA,IAAI,MAAM,YAAY,KAAA,GACpB,KAAK,KAAK,CAAC,WAAW,YAAY,KAAK,OAAO,CAAC,CAAC;CAGlD,MAAM,SAAS,MAAM,KAAK;EACxB,MAAM,KAAK;EACX,YAAY,MAAM,OAAO,WAAW;EACpC;EACA,SAAS,MAAM,WAAW;CAC5B,CAAC;CAED,MAAM,UAAU,OAAO,OAAO,YAAY,OAAO,KAAK,UAAU,MAAM,CAAC,CAAC;CACxE,OAAO,MAAM,+BAA+B,OAAO,uBAAuB,UAAU;AACtF;;AAGA,SAAgB,qBAAqB,OAAsB;CACzD,IAAI,UAAU,IACZ,MAAM,IAAI,WAAW,eAAe;CAGtC,MAAM,UAAU,yBAAyB,KAAK;CAE9C,IAAI;CACJ,IAAI;EACF,OAAO,YAAY,OAAO,qBAAqB,OAAO,CAAC;CACzD,SAAS,OAAO;EACd,MAAM,IAAI,WAAW,0BAA0B,EAAE,OAAO,MAAM,CAAC;CACjE;CACA,IAAI,CAAC,KAAK,WAAW,GAAG,GACtB,MAAM,IAAI,WAAW,eAAe;CAGtC,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,IAAI;CAC1B,SAAS,OAAO;EACd,MAAM,IAAI,WAAW,sBAAsB,EAAE,OAAO,MAAM,CAAC;CAC7D;CACA,IAAI,CAAC,oBAAoB,MAAM,GAC7B,MAAM,IAAI,WAAW,6BAA6B;CAEpD,OAAO;AACT;;;;;AAMA,SAAgB,kBACd,OACA,KACA,QACA,MACS;CACT,IAAI,CAAC,YAAY,KAAK,GACpB,OAAO;CAET,IAAI,MAAM,SAAS,KAAK,UACtB,OAAO;CAGT,MAAM,aAAa,MAAM,cAAc;CACvC,MAAM,MAAM,WAAW;CACvB,IAAI,KAAK,IAAI,MAAM,MAAM,UAAU,IAAI,YACrC,OAAO;CAIT,IADU,cAAc,MAAM,MAAM,GAChC,MAAM,KACR,OAAO;CAGT,MAAM,IAAI,cAAc,MAAM,MAAM,QAAQ;CAC5C,IAAI,MAAM,KAAA,KAAa,EAAE,YAAY,MAAM,OAAO,YAAY,GAC5D,OAAO;CAGT,IAAI,MAAM,YAAY,KAAA,GACD;MAAA,cAAc,MAAM,MAAM,SAChC,MAAM,YAAY,KAAK,OAAO,GACzC,OAAO;CAAA;CAIX,OAAO;AACT"}

package/dist/{pool-DBIYMtwy.d.mts → pool-CqQvUnsq.d.mts}

@@ -1,7 +1,8 @@
-import { n as EventTemplate, t as Event } from "./event-fU3Y01PR.mjs";
-import { t as Filter } from "./filter-C0IMByE3.mjs";
-import { n as CountResult } from "./message-iGPIqnn0.mjs";
-import { a as NegentropyStorageVector } from "./nip77-DH4RhS5r.mjs";
+import { n as EventTemplate, t as Event } from "./event-DJeb_DIL.mjs";
+import { t as Filter } from "./filter-jI_9htF7.mjs";
+import { n as CountResult } from "./message-tclYCVNc.mjs";
+import { t as EventVerifier } from "./verifier-CgTFpgsC.mjs";
+import { a as NegentropyStorageVector } from "./nip77-DzUwUxHq.mjs";
 import { t as WebSocketConstructor } from "./websocket-CmeqvAkp.mjs";
 //#region src/relay/subscription.d.ts
 type SubscriptionHandlers = {
@@ -20,8 +21,9 @@ type SubscriptionHandlers = {
 type SubscribeOptions = SubscriptionHandlers & {
   id?: string | undefined;
   /**
-   * If set, fire `oneose` once after this many ms if EOSE has not arrived. Does not close the REQ.
-   * `Relay.fetch` is the one-shot closer.
+   * If set, fire `oneose` once after this many ms if EOSE has not arrived. The synthesized EOSE
+   * also closes a `closeOnEose` subscription — without it a one-shot REQ would hang until a real
+   * EOSE that is then ignored.
    */
   eoseTimeoutMs?: number | undefined;
   /**
@@ -31,41 +33,23 @@ type SubscribeOptions = SubscriptionHandlers & {
   closeOnEose?: boolean | undefined;
   signal?: AbortSignal | undefined;
 };
-declare class Subscription {
-  #private;
+/** Uniform close handle returned by subscriptions, fan-ins, and feeds. */
+type Closer = {
+  close: (reason?: string) => void;
+};
+/** Public subscription handle returned by {@link Relay.subscribe}. */
+type RelaySubscription = {
   readonly id: string;
-  readonly filters: Filter[];
-  readonly handlers: SubscriptionHandlers;
-  readonly closeOnEose: boolean;
-  eosed: boolean;
-  closed: boolean;
-  /** True after one CLOSED `auth-required:` retry. */
-  authRetried: boolean;
-  /** Inclusive NIP-01 `since` watermark from verified EVENTs. */
-  lastCreatedAt: number | undefined;
-  /** Event ids at `lastCreatedAt` (same-second reconnect dedup). Not all seen ids. */
-  readonly idsAtWatermark: Set<string>;
-  constructor(filters: Filter[], opts: SubscribeOptions, sendClose: (id: string) => void);
-  close(reason?: string): void;
-  /** Advance the reconnect watermark after a verified EVENT. */
-  noteVerified(event: Event): void;
-  /**
-   * Filters for re-REQ. Original `filters` stay unchanged. NIP-01 `since` is inclusive — never
-   * `lastCreatedAt + 1`.
-   */
-  replayFilters(): Filter[];
-}
-/** AsyncIterable wrapper over a subscription's events until EOSE or close. */
-declare function subscriptionToAsyncIterable(start: (handlers: SubscriptionHandlers) => {
+  readonly closed: boolean;
   close: (reason?: string) => void;
-}, opts?: {
+};
+/** AsyncIterable wrapper over a subscription's events until EOSE or close. */
+declare function subscriptionToAsyncIterable(start: (handlers: SubscriptionHandlers) => Closer, opts?: {
   signal?: AbortSignal | undefined;
   includeEose?: boolean | undefined;
-}): AsyncIterable<Event> & {
-  close: (reason?: string) => void;
-};
+}): AsyncIterable<Event> & Closer;
 //#endregion
-//#region src/relay/subscribe.d.ts
+//#region src/relay/fetch.d.ts
 /** How a one-shot {@link Relay.fetch} REQ ended. */
 type RelayFetchEnd = {
   readonly type: "eose";
@@ -77,12 +61,29 @@ type RelayFetchEnd = {
 };
 /** `Relay.fetch` result: collected events plus the REQ's end reason. */
 type RelayFetchResult = {
-  readonly events: Event[];
+  readonly events: ReadonlyArray<Event>;
   readonly end: RelayFetchEnd;
 };
 //#endregion
+//#region src/relay/ok-tracker.d.ts
+/** A relay's NIP-01 OK reply to a published event. */
+type PublishResult = {
+  readonly ok: boolean;
+  readonly message: string;
+};
+//#endregion
 //#region src/relay/relay.d.ts
-/** Relay lifecycle states. */
+/**
+ * Relay lifecycle states:
+ *
+ * - `initialized` — constructed; `connect()` not yet attempted.
+ * - `connecting` — a `connect()` attempt is in flight (socket opening / resubscribing).
+ * - `connected` — socket open; REQ/EVENT/COUNT flow.
+ * - `disconnected` — socket down: a reconnect is scheduled when `enableReconnect` has live
+ *   subscriptions to restore, or `disconnect()` severed manually (REQ state kept).
+ * - `closed` — terminal until the next `connect()`: `close()` or a socket death without a scheduled
+ *   reconnect.
+ */
 declare const RelayStatus: {
   readonly Initialized: "initialized";
   readonly Connecting: "connecting";
@@ -95,7 +96,7 @@ type RelayStatusName = (typeof RelayStatus)[keyof typeof RelayStatus];
 /** Per-relay options: socket override, verification, timeouts, reconnect, ping, NIP-42 auth. */
 type RelayOptions = {
   websocketImplementation?: WebSocketConstructor | undefined;
-  verifyEvent?: ((event: Event) => boolean) | undefined;
+  verifyEvent?: EventVerifier | undefined;
   publishTimeoutMs?: number | undefined;
   connectTimeoutMs?: number | undefined;
   /**
@@ -104,17 +105,28 @@ type RelayOptions = {
    */
   enableReconnect?: boolean | undefined;
   /** Backoff delays in ms between reconnect attempts. */
-  reconnectBackoffMs?: number[] | undefined;
+  reconnectBackoffMs?: ReadonlyArray<number> | undefined;
   enablePing?: boolean | undefined;
   pingIntervalMs?: number | undefined;
   pingTimeoutMs?: number | undefined;
   /** When set, CLOSED/OK `auth-required:` triggers AUTH then retries the REQ/EVENT/COUNT. */
   authSigner?: ((template: EventTemplate) => Promise<Event>) | undefined;
 };
-/** A relay's NIP-01 OK reply to a published event. */
-type PublishResult = {
-  ok: boolean;
-  message: string;
+/** Typed event payloads for {@link Relay.on}: lifecycle and protocol notifications. */
+type RelayEventMap = {
+  /** A NIP-01 NOTICE message from the relay. */
+  notice: string;
+  /** Terminal close of the relay (a transient disconnect with reconnect does not fire it). */
+  close: undefined;
+  /** Fired when the relay sends a NIP-42 AUTH challenge. */
+  auth: string;
+  /** Fired after a successful reconnect (not the initial connect). */
+  reconnect: undefined;
+  /**
+   * Fired when a delivered EVENT fails id/signature verification, just before the event is dropped.
+   * A poisoned verifier dropping events does not fire it.
+   */
+  invalidevent: undefined;
 };
 /**
  * Single-relay NIP-01 client. Connection lifecycle, REQ/CLOSE, EVENT publish ACK, AUTH, COUNT,
@@ -123,17 +135,6 @@ type PublishResult = {
 declare class Relay {
   #private;
   readonly url: string;
-  onnotice: ((msg: string) => void) | undefined;
-  onclose: (() => void) | undefined;
-  /** Fired when the relay sends a NIP-42 AUTH challenge. */
-  onauth: ((challenge: string) => void) | undefined;
-  /** Fired after a successful reconnect (not the initial connect). */
-  onreconnect: (() => void) | undefined;
-  /**
-   * Fired when a delivered EVENT fails id/signature verification, just before the event is dropped.
-   * A poisoned verifier dropping events does not fire it.
-   */
-  oninvalidevent: (() => void) | undefined;
   constructor(url: string, opts?: RelayOptions);
   /** Latest NIP-42 challenge, if any. */
   get challenge(): string | undefined;
@@ -145,6 +146,12 @@ declare class Relay {
   get subscriptionCount(): number;
   /** One-shot requests still awaiting a relay reply (EVENT ACK, COUNT, NEG). */
   get inFlightCount(): number;
+  /**
+   * Listen for a relay 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 RelayEventMap>(type: K, listener: (payload: RelayEventMap[K]) => void): () => void;
   static connect(url: string, opts?: RelayOptions & {
     signal?: AbortSignal;
   }): Promise<Relay>;
@@ -161,25 +168,26 @@ declare class Relay {
    */
   disconnect(): void;
   /** Low-level REQ with callbacks. Survives reconnect when enableReconnect is on. */
-  subscribe(filters: Filter[], opts?: SubscribeOptions): Subscription;
+  subscribe(filters: ReadonlyArray<Filter>, opts?: SubscribeOptions): RelaySubscription;
   /** AsyncIterable of events for filters until the subscription is closed. */
-  stream(filters: Filter[], opts?: {
-    signal?: AbortSignal;
-    id?: string;
-  }): AsyncIterable<Event> & {
-    close: (reason?: string) => void;
-  };
+  stream(filters: ReadonlyArray<Filter>, opts?: {
+    signal?: AbortSignal | undefined;
+    id?: string | undefined;
+  }): AsyncIterable<Event> & Closer;
   /**
    * One-shot query: collect events until the REQ ends, then close. `end` reports how it ended —
    * relay `EOSE`, relay `CLOSED` (with its reason), or the local timeout; events received before a
    * CLOSED or the deadline are still returned. Abort rejects; a failed (re)connect rejects.
    */
-  fetch(filters: Filter[], opts?: {
+  fetch(filters: ReadonlyArray<Filter>, opts?: {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
     id?: string | undefined;
   }): Promise<RelayFetchResult>;
-  /** Publish an event and wait for OK. */
+  /**
+   * Publish an event and wait for OK. A concurrent publish of the same event id joins the in-flight
+   * publish instead of racing it — the joiner's `timeoutMs` does not apply.
+   */
   publish(event: Event, opts?: {
     timeoutMs?: number | undefined;
   }): Promise<PublishResult>;
@@ -187,7 +195,7 @@ declare class Relay {
    * NIP-45 COUNT: ask the relay how many events match `filters`. Resolves with the COUNT payload
    * (count / optional approximate / optional hll).
    */
-  count(filters: Filter[], opts?: {
+  count(filters: ReadonlyArray<Filter>, opts?: {
     id?: string | undefined;
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
@@ -198,8 +206,8 @@ declare class Relay {
   }): Promise<PublishResult>;
   /**
    * Clear a cached AUTH rejection for the current challenge so a later `auth()` signs again. A
-   * successful auth and in-flight answers are kept. When a challenge is pending and unanswered,
-   * `onauth` is re-fired so the pool's automatic auth can run once more.
+   * successful auth and in-flight answers are kept. When a challenge is pending and unanswered, an
+   * `auth` event is re-fired so the pool's automatic auth can run once more.
    */
   resetAuth(): void;
   /**
@@ -231,16 +239,7 @@ type InvalidEventPolicy = {
   cooldownMs: number;
 };
 /** Pool-wide options applied to every managed relay. */
-type PoolOptions = {
-  websocketImplementation?: WebSocketConstructor | undefined;
-  verifyEvent?: RelayOptions["verifyEvent"];
-  publishTimeoutMs?: number | undefined;
-  connectTimeoutMs?: number | undefined;
-  enableReconnect?: boolean | undefined;
-  reconnectBackoffMs?: number[] | undefined;
-  enablePing?: boolean | undefined;
-  pingIntervalMs?: number | undefined;
-  pingTimeoutMs?: number | undefined;
+type PoolOptions = Omit<RelayOptions, "authSigner"> & {
   /**
    * When set, automatically answer NIP-42 AUTH challenges for relays that send them. Return
    * undefined to skip a given relay URL.
@@ -252,7 +251,6 @@ type PoolOptions = {
   /** Close unused relays. Unset/0 = disabled. */
   idleTimeoutMs?: number | undefined;
   idleCleanupIntervalMs?: number | undefined;
-  onIdleRelaysClosed?: ((urls: string[]) => void) | undefined;
   /**
    * Soft cap on connected non-pinned relays. When `ensureRelay` would create a new non-pinned relay
    * at the cap, the least-recently-used idle one is closed first (idle = no subscriptions and no
@@ -269,17 +267,33 @@ type PoolOptions = {
    * through the normal reconnect path. Unset = events are dropped without counting, as before.
    */
   invalidEventPolicy?: InvalidEventPolicy | undefined;
+};
+/** Typed event payloads for {@link Pool.on}. */
+type PoolEventMap = {
+  /** Normalized URLs closed by an idle-cleanup pass. */
+  idle: ReadonlyArray<string>;
   /**
-   * Fired once when a relay is suspended for exceeding `invalidEventPolicy`: `url` is the
-   * normalized relay URL and `until` the epoch-ms time the suspension lifts.
+   * A relay suspended for exceeding `invalidEventPolicy`: `url` is the normalized relay URL and
+   * `until` the epoch-ms time the suspension lifts.
    */
-  onRelaySuspended?: ((url: string, until: number) => void) | undefined;
+  suspend: {
+    readonly url: string;
+    readonly until: number;
+  };
 };
-/** Per-relay publish outcome: the relay's OK reply or an error string. */
+/** Per-relay publish outcome: the relay's OK verdict or a transport-level failure. */
 type PoolPublishResult = {
-  url: string;
-  result?: PublishResult;
-  error?: string;
+  readonly url: string;
+  readonly status: "ok";
+  readonly message: string;
+} | {
+  readonly url: string;
+  readonly status: "rejected";
+  readonly message: string;
+} | {
+  readonly url: string;
+  readonly status: "failed";
+  readonly error: Error;
 };
 /** Multi-relay subscribe options: callbacks also receive the normalized relay URL. */
 type PoolSubscribeOptions = Omit<SubscribeOptions, "onevent" | "receivedEvent"> & {
@@ -288,25 +302,32 @@ type PoolSubscribeOptions = Omit<SubscribeOptions, "onevent" | "receivedEvent">
 };
 /** Per-relay one-shot fetch outcome: collected events plus how its REQ ended. */
 type PoolFetchResult = {
-  url: string;
-  events: Event[];
-  end: RelayFetchEnd | {
+  readonly url: string;
+  readonly events: ReadonlyArray<Event>;
+  readonly end: RelayFetchEnd | {
     readonly type: "failed";
-    readonly reason: string;
+    readonly error: Error;
   };
 };
-/** Per-relay NIP-45 COUNT result (or its error). */
-type PoolCountResult = {
-  url: string;
-  count?: number;
-  approximate?: boolean;
-  hll?: string;
-  error?: string;
+/** Per-relay NIP-45 COUNT result (or a transport-level failure). */
+type PoolCountResult = ({
+  readonly url: string;
+  readonly status: "ok";
+} & CountResult) | {
+  readonly url: string;
+  readonly status: "failed";
+  readonly error: Error;
 };
 /** Multi-relay coordinator: connection reuse, cross-relay event dedup, fan-out publish. */
 declare class Pool {
   #private;
   constructor(opts?: PoolOptions);
+  /**
+   * Listen for a pool 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 PoolEventMap>(type: K, listener: (payload: PoolEventMap[K]) => void): () => void;
   setAllowInsecure(allow: boolean): void;
   setTrustedInsecureUrls(urls: ReadonlyArray<string>): void;
   setPinnedUrls(urls: ReadonlyArray<string>): void;
@@ -320,43 +341,46 @@ declare class Pool {
     signal?: AbortSignal | undefined;
     timeoutMs?: number | undefined;
   }): Promise<Relay>;
-  close(urls?: string[]): void;
+  /** Close every pooled relay and clear all pool state. */
+  close(): void;
+  /** Close and forget the listed relays; other pooled relays are untouched. */
+  closeRelays(urls: ReadonlyArray<string>): void;
   /**
    * Subscribe across relays. Deduplicates by event id. Returns a closer; callbacks receive every
    * new event once.
    */
-  subscribe(relays: string[], filters: Filter[], opts?: PoolSubscribeOptions): {
-    close: (reason?: string) => void;
-  };
+  subscribe(relays: ReadonlyArray<string>, filters: ReadonlyArray<Filter>, opts?: PoolSubscribeOptions): Closer;
   /**
    * One-shot fetch per relay: each entry reports its own events and end reason (`eose`, `closed`,
    * `timeout`), or `failed` when the connect or REQ itself errored. An abort rejects the whole
    * call. Events are not deduped across relays — use {@link fetch} for that.
    */
-  fetchEach(relays: string[], filters: Filter[], opts?: {
+  fetchEach(relays: ReadonlyArray<string>, filters: ReadonlyArray<Filter>, opts?: {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
   }): Promise<PoolFetchResult[]>;
   /** Fetch events until each connected relay EOSE or timeout; dedupe by id. */
-  fetch(relays: string[], filters: Filter[], opts?: {
+  fetch(relays: ReadonlyArray<string>, filters: ReadonlyArray<Filter>, opts?: {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
     /** Every event of every relay batch, including cross-relay duplicates. */
     onevent?: ((event: Event, relayUrl: string) => void) | undefined;
   }): Promise<Event[]>;
   /** Publish to all listed relays; returns per-relay outcomes. */
-  publish(relays: string[], event: Event, opts?: {
+  publish(relays: ReadonlyArray<string>, event: Event, opts?: {
     timeoutMs?: number | undefined;
   }): Promise<PoolPublishResult[]>;
   /** First successful publish (Promise.any semantics). */
-  publishAny(relays: string[], event: Event, opts?: {
+  publishAny(relays: ReadonlyArray<string>, event: Event, opts?: {
     timeoutMs?: number | undefined;
-  }): Promise<PoolPublishResult>;
+  }): Promise<Extract<PoolPublishResult, {
+    status: "ok";
+  }>>;
   /**
    * NIP-45 COUNT across relays. Per-relay outcomes; failures do not throw. Counts are not summed —
    * each relay reports independently (may overlap).
    */
-  count(relays: string[], filters: Filter[], opts?: {
+  count(relays: ReadonlyArray<string>, filters: ReadonlyArray<Filter>, opts?: {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
   }): Promise<PoolCountResult[]>;
@@ -367,5 +391,5 @@ declare class Pool {
   connectedUrls(): string[];
 }
 //#endregion
-export { SubscriptionHandlers as _, PoolOptions as a, PublishResult as c, RelayStatus as d, RelayStatusName as f, Subscription as g, SubscribeOptions as h, PoolFetchResult as i, Relay as l, RelayFetchResult as m, Pool as n, PoolPublishResult as o, RelayFetchEnd as p, PoolCountResult as r, PoolSubscribeOptions as s, InvalidEventPolicy as t, RelayOptions as u, subscriptionToAsyncIterable as v };
-//# sourceMappingURL=pool-DBIYMtwy.d.mts.map
+export { Closer as _, PoolFetchResult as a, SubscriptionHandlers as b, PoolSubscribeOptions as c, RelayOptions as d, RelayStatus as f, RelayFetchResult as g, RelayFetchEnd as h, PoolEventMap as i, Relay as l, PublishResult as m, Pool as n, PoolOptions as o, RelayStatusName as p, PoolCountResult as r, PoolPublishResult as s, InvalidEventPolicy as t, RelayEventMap as u, RelaySubscription as v, subscriptionToAsyncIterable as x, SubscribeOptions as y };
+//# sourceMappingURL=pool-CqQvUnsq.d.mts.map