@qntx/nostr 0.5.0 → 0.7.0

package/dist/{pool-DBIYMtwy.d.mts → pool-SzJKPIa3.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-CbBZOhq3.mjs";
+import { t as EventVerifier } from "./verifier-CgTFpgsC.mjs";
+import { a as NegentropyStorageVector } from "./nip77-C9QcZn7b.mjs";
 import { t as WebSocketConstructor } from "./websocket-CmeqvAkp.mjs";
 //#region src/relay/subscription.d.ts
 type SubscriptionHandlers = {
@@ -31,39 +32,21 @@ 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
 /** How a one-shot {@link Relay.fetch} REQ ended. */
@@ -82,7 +65,17 @@ type RelayFetchResult = {
 };
 //#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 +88,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,7 +97,7 @@ 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;
@@ -116,6 +109,22 @@ 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,
  * NIP-77, optional reconnect.
@@ -123,17 +132,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 +143,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 +165,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 +192,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 +203,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 +236,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.
@@ -275,11 +271,19 @@ type PoolOptions = {
    */
   onRelaySuspended?: ((url: string, until: number) => void) | undefined;
 };
-/** 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: string;
 };
 /** Multi-relay subscribe options: callbacks also receive the normalized relay URL. */
 type PoolSubscribeOptions = Omit<SubscribeOptions, "onevent" | "receivedEvent"> & {
@@ -295,13 +299,14 @@ type PoolFetchResult = {
     readonly reason: string;
   };
 };
-/** 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: string;
 };
 /** Multi-relay coordinator: connection reuse, cross-relay event dedup, fan-out publish. */
 declare class Pool {
@@ -325,38 +330,38 @@ declare class Pool {
    * 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 +372,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 { RelaySubscription as _, PoolOptions as a, subscriptionToAsyncIterable as b, PublishResult as c, RelayOptions as d, RelayStatus as f, Closer as g, RelayFetchResult as h, PoolFetchResult as i, Relay as l, RelayFetchEnd as m, Pool as n, PoolPublishResult as o, RelayStatusName as p, PoolCountResult as r, PoolSubscribeOptions as s, InvalidEventPolicy as t, RelayEventMap as u, SubscribeOptions as v, SubscriptionHandlers as y };
+//# sourceMappingURL=pool-SzJKPIa3.d.mts.map