@qntx/nostr 0.1.0 → 0.2.1

package/dist/pool-B7p_reAm.d.mts

@@ -0,0 +1,333 @@
+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 { t as WebSocketConstructor } from "./websocket-CmeqvAkp.mjs";
+//#region src/relay/subscription.d.ts
+type SubscriptionHandlers = {
+  onevent?: ((event: Event) => void) | undefined;
+  oneose?: (() => void) | undefined;
+  onclose?: ((reason: string) => void) | undefined;
+  /** Skip verify + onevent when true. Evaluated after parse, before verify. */
+  alreadyHaveEvent?: ((id: string) => boolean) | undefined;
+  /**
+   * Fired for every EVENT id this sub sees, including duplicates and alreadyHaveEvent hits, after
+   * parse and before the verify skip.
+   */
+  receivedEvent?: ((id: string) => void) | undefined;
+};
+/** Options for {@link Relay.subscribe}: event handlers plus REQ behavior. */
+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.
+   */
+  eoseTimeoutMs?: number | undefined;
+  /**
+   * One-shot REQ: do not join a live coalescing group, and close on EOSE. Default false (live).
+   * `Relay.fetch` passes true.
+   */
+  closeOnEose?: boolean | undefined;
+  signal?: AbortSignal | undefined;
+};
+declare class Subscription {
+  #private;
+  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) => {
+  close: (reason?: string) => void;
+}, opts?: {
+  signal?: AbortSignal | undefined;
+  includeEose?: boolean | undefined;
+}): AsyncIterable<Event> & {
+  close: (reason?: string) => void;
+};
+//#endregion
+//#region src/relay/relay.d.ts
+/** Relay lifecycle states. */
+declare const RelayStatus: {
+  readonly Initialized: "initialized";
+  readonly Connecting: "connecting";
+  readonly Connected: "connected";
+  readonly Disconnected: "disconnected";
+  readonly Closed: "closed";
+};
+/** Union of the {@link RelayStatus} values. */
+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;
+  publishTimeoutMs?: number | undefined;
+  connectTimeoutMs?: number | undefined;
+  /**
+   * When true, unexpected disconnects schedule reconnect with backoff and re-fire open
+   * subscriptions. Default false.
+   */
+  enableReconnect?: boolean | undefined;
+  /** Backoff delays in ms between reconnect attempts. */
+  reconnectBackoffMs?: 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;
+};
+/**
+ * Single-relay NIP-01 client. Connection lifecycle, REQ/CLOSE, EVENT publish ACK, AUTH, COUNT,
+ * NIP-77, optional reconnect.
+ */
+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;
+  get connected(): boolean;
+  get status(): RelayStatusName;
+  get generation(): number;
+  get reconnectEnabled(): boolean;
+  /** User subscriptions only; dummy ping REQs are not counted. */
+  get subscriptionCount(): number;
+  /** One-shot requests still awaiting a relay reply (EVENT ACK, COUNT, NEG). */
+  get inFlightCount(): number;
+  static connect(url: string, opts?: RelayOptions & {
+    signal?: AbortSignal;
+  }): Promise<Relay>;
+  connect(opts?: {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+  }): Promise<void>;
+  /** Graceful shutdown: disables reconnect and closes all subscriptions. */
+  close(): void;
+  /**
+   * Sever the socket while keeping every subscription: unlike {@link close}, open REQ state is
+   * preserved and reconnect stays suppressed — the next {@link connect} re-subscribes all of them.
+   * {@link Pool} uses this to suspend a relay without tearing down its live subscriptions.
+   */
+  disconnect(): void;
+  /** Low-level REQ with callbacks. Survives reconnect when enableReconnect is on. */
+  subscribe(filters: Filter[], opts?: SubscribeOptions): Subscription;
+  /** AsyncIterable of events for filters until the subscription is closed. */
+  stream(filters: Filter[], opts?: {
+    signal?: AbortSignal;
+    id?: string;
+  }): AsyncIterable<Event> & {
+    close: (reason?: string) => void;
+  };
+  /** One-shot query: collect events until EOSE or timeout, then close. */
+  fetch(filters: Filter[], opts?: {
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    id?: string | undefined;
+  }): Promise<Event[]>;
+  /** Publish an event and wait for OK. */
+  publish(event: Event, opts?: {
+    timeoutMs?: number | undefined;
+  }): Promise<PublishResult>;
+  /**
+   * 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?: {
+    id?: string | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+  }): Promise<CountResult>;
+  /** NIP-42 AUTH: sign the current challenge and wait for OK. */
+  auth(sign: (template: EventTemplate) => Promise<Event>, opts?: {
+    timeoutMs?: number | undefined;
+  }): 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.
+   */
+  resetAuth(): void;
+  /**
+   * NIP-77: run Negentropy reconciliation against this relay. Returns the local-only (`have`) and
+   * remote-only (`need`) event ids. Does not upload or download events.
+   *
+   * `timeoutMs` is a single wall-clock deadline for the whole session (`NEG-OPEN` through the last
+   * `NEG-MSG`), not a per-message budget. Default: {@link RelayOptions.publishTimeoutMs}.
+   */
+  negReconcile(filter: Filter, storage: NegentropyStorageVector, opts?: {
+    id?: string | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+  }): Promise<{
+    have: string[];
+    need: string[];
+  }>;
+  /** Generate a unique subscription id for this relay instance. */
+  nextSubId(prefix?: string): string;
+}
+//#endregion
+//#region src/relay/pool.d.ts
+/** Per-relay tolerance for events that fail id/signature verification. */
+type InvalidEventPolicy = {
+  /** Invalid events tolerated within `windowMs`; exceeding it suspends the relay. */
+  limit: number;
+  windowMs: number;
+  /** How long a suspended relay stays closed before it may reconnect. */
+  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;
+  /**
+   * When set, automatically answer NIP-42 AUTH challenges for relays that send them. Return
+   * undefined to skip a given relay URL.
+   */
+  automaticallyAuth?: ((relayURL: string) => ((event: EventTemplate) => Promise<Event>) | undefined) | undefined;
+  /** When false (default), ensureRelay rejects isInsecureRelayUrl unless trusted. */
+  allowInsecure?: boolean | undefined;
+  trustedInsecureUrls?: ReadonlyArray<string> | undefined;
+  /** 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
+   * in-flight requests). If none is idle the connect proceeds anyway — the cap never fails a
+   * request.
+   */
+  maxRelays?: number | undefined;
+  /** Normalized URLs never closed by idle cleanup or `maxRelays` eviction. */
+  pinnedUrls?: ReadonlyArray<string> | undefined;
+  /**
+   * When set, a relay whose `limit`-th-plus-one EVENT fails id/signature verification inside a
+   * `windowMs` sliding window is disconnected and suspended for `cooldownMs`. During suspension
+   * `ensureRelay` rejects with {@link RelaySuspendedError}; once it lifts, live subscriptions resume
+   * through the normal reconnect path. Unset = events are dropped without counting, as before.
+   */
+  invalidEventPolicy?: InvalidEventPolicy | undefined;
+  /**
+   * 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.
+   */
+  onRelaySuspended?: ((url: string, until: number) => void) | undefined;
+};
+/** Per-relay publish outcome: the relay's OK reply or an error string. */
+type PoolPublishResult = {
+  url: string;
+  result?: PublishResult;
+  error?: string;
+};
+/** Multi-relay subscribe options: callbacks also receive the normalized relay URL. */
+type PoolSubscribeOptions = Omit<SubscribeOptions, "onevent" | "receivedEvent"> & {
+  onevent?: ((event: Event, relayUrl: string) => void) | undefined;
+  receivedEvent?: ((id: string, relayUrl: string) => void) | undefined;
+};
+/** Per-relay NIP-45 COUNT result (or its error). */
+type PoolCountResult = {
+  url: string;
+  count?: number;
+  approximate?: boolean;
+  hll?: string;
+  error?: string;
+};
+/** Multi-relay coordinator: connection reuse, cross-relay event dedup, fan-out publish. */
+declare class Pool {
+  #private;
+  constructor(opts?: PoolOptions);
+  setAllowInsecure(allow: boolean): void;
+  setTrustedInsecureUrls(urls: ReadonlyArray<string>): void;
+  setPinnedUrls(urls: ReadonlyArray<string>): void;
+  /**
+   * Drop cached AUTH rejections and re-fire pending challenges on every pooled relay, so a later
+   * `setSigner` takes effect without reconnect.
+   */
+  resetAuth(): void;
+  cleanIdleRelays(): void;
+  ensureRelay(url: string, opts?: {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+  }): Promise<Relay>;
+  close(urls?: 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;
+  };
+  /** Fetch events until each connected relay EOSE or timeout; dedupe by id. */
+  fetch(relays: string[], filters: 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?: {
+    timeoutMs?: number | undefined;
+  }): Promise<PoolPublishResult[]>;
+  /** First successful publish (Promise.any semantics). */
+  publishAny(relays: string[], event: Event, opts?: {
+    timeoutMs?: number | undefined;
+  }): Promise<PoolPublishResult>;
+  /**
+   * 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?: {
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+  }): Promise<PoolCountResult[]>;
+  listRelays(): string[];
+  /** Lookup a pooled relay, including disconnected reconnecting entries. */
+  getRelay(url: string): Relay | undefined;
+  /** Currently connected URLs. Unlike listRelays(), excludes reconnecting/disconnected entries. */
+  connectedUrls(): string[];
+}
+//#endregion
+export { PoolPublishResult as a, Relay as c, RelayStatusName as d, SubscribeOptions as f, subscriptionToAsyncIterable as h, PoolOptions as i, RelayOptions as l, SubscriptionHandlers as m, Pool as n, PoolSubscribeOptions as o, Subscription as p, PoolCountResult as r, PublishResult as s, InvalidEventPolicy as t, RelayStatus as u };
+//# sourceMappingURL=pool-B7p_reAm.d.mts.map