applesauce-relay 5.1.0 → 6.0.0

package/dist/group.d.ts

@@ -1,62 +1,51 @@
-import { IAsyncEventStoreActions, IEventStoreActions } from "applesauce-core/event-store";
 import type { Filter, NostrEvent } from "applesauce-core/helpers";
-import { BehaviorSubject, MonoTypeOperatorFunction, Observable } from "rxjs";
-import { NegentropySyncOptions, type ReconcileFunction } from "./negentropy.js";
-import { SyncDirection } from "./relay.js";
-import { CountResponse, FilterInput, IGroup, IGroupRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayStatus, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
-/** Options for negentropy sync on a group of relays */
-export type GroupNegentropySyncOptions = NegentropySyncOptions & {
-    /** Whether to sync in parallel (default true) */
-    parallel?: boolean;
-};
-/** Options for a subscription on a group of relays */
-export type GroupSubscriptionOptions = SubscriptionOptions & {
-    /** Deduplicate events with an event store (default is a temporary instance of EventMemory), null will disable deduplication */
-    eventStore?: IEventStoreActions | IAsyncEventStoreActions | null;
-};
-/** Options for a request on a group of relays */
-export type GroupRequestOptions = RequestOptions & {
-    /** Deduplicate events with an event store (default is a temporary instance of EventMemory), null will disable deduplication */
-    eventStore?: IEventStoreActions | IAsyncEventStoreActions | null;
-};
-export declare class RelayGroup implements IGroup {
-    protected relays$: BehaviorSubject<IRelay[]> | Observable<IRelay[]>;
+import { BehaviorSubject, Observable } from "rxjs";
+import { type ReconcileFunction } from "./negentropy.js";
+import { Relay, SyncDirection } from "./relay.js";
+import { FilterInput, GroupNegentropySyncOptions, GroupRelayInput, GroupReqMessage, GroupReqOptions, GroupRequestCompleteOperator, GroupRequestOptions, GroupSubscriptionOptions, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayCountResponse, RelayReqMessage, RelayStatus } from "./types.js";
+export declare class RelayGroup {
+    protected relays$: BehaviorSubject<Relay[]> | Observable<Relay[]>;
     /** Observable of relay status for all relays in the group */
     status$: Observable<Record<string, RelayStatus>>;
-    get relays(): IRelay[];
-    constructor(relays: IGroupRelayInput);
+    get relays(): Relay[];
+    constructor(relays: GroupRelayInput);
     /** Whether this group is controlled by an upstream observable */
     private get controlled();
     /** Check if a relay is in the group */
-    has(relay: IRelay | string): boolean;
+    has(relay: Relay | string): boolean;
     /** Add a relay to the group */
-    add(relay: IRelay): void;
+    add(relay: Relay): void;
     /** Remove a relay from the group */
-    remove(relay: IRelay): void;
+    remove(relay: Relay): void;
     /** Internal logic for handling requests to multiple relays */
-    protected internalSubscription(project: (relay: IRelay) => Observable<SubscriptionResponse>, eventOperator?: MonoTypeOperatorFunction<NostrEvent>): Observable<SubscriptionResponse>;
+    protected internalSubscription(project: (relay: Relay) => Observable<RelayReqMessage>): Observable<GroupReqMessage>;
     /** Internal logic for handling publishes to multiple relays */
-    protected internalPublish(project: (relay: IRelay) => Observable<PublishResponse>): Observable<PublishResponse>;
-    /**
-     * Make a request to all relays
-     * @note This does not deduplicate events
-     */
-    req(filters: FilterInput, id?: string, opts?: {
-        /** Deduplicate events with an event store (default is a temporary instance of EventMemory), null will disable deduplication */
-        eventStore?: IEventStoreActions | IAsyncEventStoreActions | null;
-    }): Observable<SubscriptionResponse>;
+    protected internalPublish(project: (relay: Relay) => Observable<PublishResponse>): Observable<PublishResponse>;
+    /** Send a REQ to all relays and returns all responses */
+    req(filters: FilterInput, opts?: GroupReqOptions): Observable<GroupReqMessage>;
     /** Send an event to all relays */
     event(event: NostrEvent): Observable<PublishResponse>;
     /** Negentropy sync events with the relays and an event store */
     negentropy(store: NegentropyReadStore, filter: Filter, reconcile: ReconcileFunction, opts?: GroupNegentropySyncOptions): Promise<boolean>;
     /** Publish an event to all relays with retries ( default 3 retries ) */
     publish(event: NostrEvent, opts?: PublishOptions): Promise<PublishResponse[]>;
-    /** Request events from all relays and complete on EOSE */
+    /** Request events from all relays and complete based on condition */
     request(filters: FilterInput, opts?: GroupRequestOptions): Observable<NostrEvent>;
     /** Open a subscription to all relays with retries ( default 3 retries ) */
-    subscription(filters: FilterInput, opts?: GroupSubscriptionOptions): Observable<SubscriptionResponse>;
+    subscription(filters: FilterInput, opts?: GroupSubscriptionOptions): Observable<NostrEvent>;
     /** Count events on all relays in the group */
-    count(filters: Filter | Filter[], id?: string): Observable<Record<string, CountResponse>>;
+    count(filters: Filter | Filter[], id?: string): Observable<Record<string, RelayCountResponse>>;
     /** Negentropy sync events with the relays and an event store */
     sync(store: NegentropySyncStore | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
+    /**
+     * Creates a complete condition that waits for the first EOSE message from a relay and then starts a timeout for the remaining relays
+     * @param timeout - The timeout in milliseconds for the remaining relays
+     */
+    static completeAfterFirstRelay(timeout?: number): GroupRequestCompleteOperator;
+    /** Creates a group request complete operator that waits for all relays to send an EOSE message or timeout */
+    static completeOnAllEose(): GroupRequestCompleteOperator;
+    /** A group request complete condition that completes when any of the provided conditions are truthy (OR) */
+    static completeOnAny(...conditions: GroupRequestCompleteOperator[]): GroupRequestCompleteOperator;
+    /** A group request complete condition that completes when any of the provided conditions are truthy (AND) */
+    static completeOnAll(...conditions: GroupRequestCompleteOperator[]): GroupRequestCompleteOperator;
 }

package/dist/group.js

@@ -1,9 +1,8 @@
 import { EventMemory } from "applesauce-core/event-store";
 import { filterDuplicateEvents } from "applesauce-core/observable";
 import { nanoid } from "nanoid";
-import { BehaviorSubject, catchError, combineLatest, defaultIfEmpty, defer, endWith, filter, from, identity, ignoreElements, lastValueFrom, map, merge, of, scan, share, shareReplay, startWith, switchMap, take, takeWhile, toArray, } from "rxjs";
-import { completeOnEose } from "./operators/complete-on-eose.js";
-import { onlyEvents } from "./operators/only-events.js";
+import { BehaviorSubject, catchError, combineLatest, connect, defaultIfEmpty, defer, filter, from, identity, lastValueFrom, map, merge, of, scan, share, shareReplay, startWith, switchMap, take, timeout, timer, toArray, } from "rxjs";
+import { completeWhen } from "./operators/complete-when.js";
 import { reverseSwitchMap } from "./operators/reverse-switch-map.js";
 /** Convert an error to a PublishResponse */
 function errorToPublishResponse(relay) {
@@ -63,11 +62,11 @@ export class RelayGroup {
         this.relays$.next(this.relays.filter((r) => r !== relay));
     }
     /** Internal logic for handling requests to multiple relays */
-    internalSubscription(project, eventOperator = identity) {
+    internalSubscription(project) {
         // Keep a cache of upstream observables for each relay
         const upstream = new WeakMap();
         // Subscribe to the group relays
-        const main = this.relays$.pipe(
+        const messages = this.relays$.pipe(
         // Every time they change switch to a new observable
         // Using reverseSwitchMap to subscribe to the new relays before unsubscribing from the old ones
         // This avoids sending duplicate REQ messages to the relays
@@ -80,44 +79,17 @@ export class RelayGroup {
                     continue;
                 }
                 const observable = project(relay).pipe(
-                // Catch connection errors and return EOSE
-                catchError(() => of("EOSE")), 
-                // Map values into tuple of relay and value
-                map((value) => [relay, value]));
+                // Catch connection errors and return ERROR
+                catchError((err) => of({ type: "ERROR", from: relay.url, error: err })));
                 observables.push(observable);
                 upstream.set(relay, observable);
             }
             return merge(...observables);
         }), 
-        // Only create one upstream subscription
-        share());
-        // Create an observable that only emits the events from the relays
-        const events = main.pipe(
-        // Pick the value from the tuple
-        map(([_, value]) => value), 
-        // Only return events
-        onlyEvents(), 
-        // Add event operations
-        eventOperator);
-        // Create an observable that emits EOSE when all relays have sent EOSE
-        const eose = this.relays$.pipe(
-        // When the relays change, switch to a new observable
-        switchMap((relays) => 
-        // Subscribe to the events, and wait for EOSE from all relays
-        main.pipe(
-        // Only select EOSE messages
-        filter(([_, value]) => value === "EOSE"), 
-        // Track the relays that have sent EOSE
-        scan((received, [relay]) => [...received, relay], []), 
-        // Keep the observable open while there are relays that have not sent EOSE
-        takeWhile((received) => relays.some((r) => !received.includes(r))), 
-        // Ignore all values
-        ignoreElements(), 
-        // When all relays have sent EOSE, emit EOSE
-        endWith("EOSE"))));
-        return merge(events, eose).pipe(
-        // Ensure a single upstream
+        // Ensure a single upstream subscription
+        // NOTE: this is required because the complete operator will subscribe many times to this
         share());
+        return messages;
     }
     /** Internal logic for handling publishes to multiple relays */
     internalPublish(project) {
@@ -144,20 +116,17 @@ export class RelayGroup {
                 upstream.set(relay, observable);
             }
             return merge(...observables);
-        }));
+        }), 
+        // Ensure a single upstream publish
+        share());
     }
-    /**
-     * Make a request to all relays
-     * @note This does not deduplicate events
-     */
-    req(filters, id = nanoid(), opts) {
-        return this.internalSubscription((relay) => relay.req(filters, id), opts?.eventStore ? filterDuplicateEvents(opts?.eventStore) : identity);
+    /** Send a REQ to all relays and returns all responses */
+    req(filters, opts) {
+        return this.internalSubscription((relay) => relay.req(filters, opts));
     }
     /** Send an event to all relays */
     event(event) {
-        return this.internalPublish((relay) => relay.event(event)).pipe(
-        // Ensure a single upstream subscription
-        share());
+        return this.internalPublish((relay) => relay.event(event));
     }
     /** Negentropy sync events with the relays and an event store */
     async negentropy(store, filter, reconcile, opts) {
@@ -177,21 +146,42 @@ export class RelayGroup {
     publish(event, opts) {
         return lastValueFrom(this.internalPublish((relay) => from(relay.publish(event, opts))).pipe(toArray(), defaultIfEmpty([])));
     }
-    /** Request events from all relays and complete on EOSE */
+    /** Request events from all relays and complete based on condition */
     request(filters, opts) {
-        return this.internalSubscription((relay) => relay.request(filters, opts).pipe(
-        // Simulate EOSE on completion
-        endWith("EOSE")), 
+        const complete = opts?.complete ??
+            // Default complete condition is to wait for the first relay to send an EOSE message and then timeout or all relays to EOSE
+            RelayGroup.completeOnAny(RelayGroup.completeAfterFirstRelay(5_000), RelayGroup.completeOnAllEose());
+        return this.internalSubscription(
+        // NOTE: we need to use the .req() method here because it returns the full RelayReqResponse object
+        (relay) => relay.req(filters, 
+        // Manually default to relays reconnect config
+        { ...opts, reconnect: opts?.reconnect ?? relay.requestReconnect })).pipe(
+        // Add the completion condition if provided
+        complete ? completeWhen(complete) : identity, 
+        // Add request timeout
+        timeout({ first: opts?.timeout ?? 30_000 }), 
+        // Filter only for event messages
+        filter((message) => message.type === "EVENT"), 
+        // Extract event messages
+        map((message) => message.event), 
         // If an event store is provided, filter duplicate events
-        opts?.eventStore == null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory())).pipe(
-        // Complete when all relays have sent EOSE
-        completeOnEose());
+        opts?.eventStore === null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory()), 
+        // Only create one upstream subscription
+        share());
     }
     /** Open a subscription to all relays with retries ( default 3 retries ) */
     subscription(filters, opts) {
-        return this.internalSubscription((relay) => relay.subscription(filters, opts), 
+        return this.internalSubscription(
+        // NOTE: we need to use the .req() method here because it returns the full RelayReqResponse object
+        (relay) => relay.req(filters, { ...opts, reconnect: opts?.reconnect ?? relay.subscriptionReconnect })).pipe(
+        // Filter only for event messages
+        filter((message) => message.type === "EVENT"), 
+        // Extract event messages
+        map((message) => message.event), 
         // If an event store is provided, filter duplicate events
-        opts?.eventStore == null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory()));
+        opts?.eventStore === null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory()), 
+        // Only create one upstream subscription
+        share());
     }
     /** Count events on all relays in the group */
     count(filters, id = nanoid()) {
@@ -214,4 +204,43 @@ export class RelayGroup {
         // Only create one upstream subscription
         share());
     }
+    /**
+     * Creates a complete condition that waits for the first EOSE message from a relay and then starts a timeout for the remaining relays
+     * @param timeout - The timeout in milliseconds for the remaining relays
+     */
+    static completeAfterFirstRelay(timeout = 5_000) {
+        return (source) => 
+        // Listen for first EOSE message from a relay
+        source.pipe(filter((m) => m.type === "EOSE")).pipe(
+        // Ignore all other EOSE messages
+        take(1), 
+        // Start a timeout for the remaining relays
+        switchMap(() => timer(timeout)), 
+        // Emit true when the timeout completes
+        map(() => true));
+    }
+    /** Creates a group request complete operator that waits for all relays to send an EOSE message or timeout */
+    static completeOnAllEose() {
+        return (source) => source.pipe(
+        // Filter for relay status messages
+        filter((message) => message.type === "OPEN" || message.type === "EOSE" || message.type === "ERROR"), 
+        // Accumulate the relay status messages
+        scan((acc, message) => acc.set(message.from, message.type), new Map()), 
+        // Emit true when all relays are no longer OPEN
+        map((all) => Array.from(all.values()).every((t) => t !== "OPEN")));
+    }
+    /** A group request complete condition that completes when any of the provided conditions are truthy (OR) */
+    static completeOnAny(...conditions) {
+        return connect((shared$) => 
+        // Merge all the conditions
+        merge(...conditions.map((condition) => shared$.pipe(condition))));
+    }
+    /** A group request complete condition that completes when any of the provided conditions are truthy (AND) */
+    static completeOnAll(...conditions) {
+        return connect((shared$) => 
+        // Get last state from all conditions
+        combineLatest(conditions.map((condition) => shared$.pipe(condition))).pipe(
+        // Check all values are truthy
+        map((all) => all.every((v) => !!v))));
+    }
 }

package/dist/liveness.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from "rxjs";
-import { IPool } from "./types.js";
+import type { RelayPool } from "./pool.js";
 /** Relay health states for liveness tracking */
 export type RelayHealthState = "online" | "offline" | "dead";
 /** State information for a relay's health tracking */
@@ -114,9 +114,9 @@ export declare class RelayLiveness {
     reset(relay?: string): void;
     private connections;
     /** Connect to a {@link RelayPool} instance and track relay connections */
-    connectToPool(pool: IPool): void;
+    connectToPool(pool: RelayPool): void;
     /** Disconnect from a {@link RelayPool} instance */
-    disconnectFromPool(pool: IPool): void;
+    disconnectFromPool(pool: RelayPool): void;
     private updateRelayState;
     private saveKnownRelays;
     private saveRelayState;

package/dist/operators/complete-on-eose.d.ts

@@ -1,6 +1,6 @@
 import { MonoTypeOperatorFunction, OperatorFunction } from "rxjs";
 import { NostrEvent } from "applesauce-core/helpers/event";
-import { SubscriptionResponse } from "../types.js";
-export declare function completeOnEose(includeEose: true): MonoTypeOperatorFunction<SubscriptionResponse>;
-export declare function completeOnEose(): OperatorFunction<SubscriptionResponse, NostrEvent>;
-export declare function completeOnEose(includeEose: false): OperatorFunction<SubscriptionResponse, NostrEvent>;
+import { RelaySubscriptionResponse } from "../types.js";
+export declare function completeOnEose(includeEose: true): MonoTypeOperatorFunction<RelaySubscriptionResponse>;
+export declare function completeOnEose(): OperatorFunction<RelaySubscriptionResponse, NostrEvent>;
+export declare function completeOnEose(includeEose: false): OperatorFunction<RelaySubscriptionResponse, NostrEvent>;

package/dist/operators/complete-when.d.ts

@@ -0,0 +1,7 @@
+import { MonoTypeOperatorFunction, OperatorFunction } from "rxjs";
+/**
+ * Complete an observable when an operator emits a value
+ * @param operator - The operator to apply to the source observable
+ * @param check - A method used to check value for completion, defaults to truthy
+ */
+export declare function completeWhen<T, U>(operator: OperatorFunction<T, U>, check?: ((v: U) => boolean) | null): MonoTypeOperatorFunction<T>;

package/dist/operators/complete-when.js

@@ -0,0 +1,14 @@
+import { connect, filter, take, takeUntil } from "rxjs";
+/**
+ * Complete an observable when an operator emits a value
+ * @param operator - The operator to apply to the source observable
+ * @param check - A method used to check value for completion, defaults to truthy
+ */
+export function completeWhen(operator, check = (v) => !!v) {
+    return connect((shared$) => {
+        const complete$ = check ? shared$.pipe(operator, filter(check), take(1)) : shared$.pipe(operator, take(1));
+        return shared$.pipe(
+        // Complete when the operator returns truthy value
+        takeUntil(complete$));
+    });
+}

package/dist/operators/index.d.ts

@@ -1,7 +1,5 @@
 export * from "./complete-on-eose.js";
 export * from "./liveness.js";
-export * from "./mark-from-relay.js";
 export * from "./only-events.js";
 export * from "./reverse-switch-map.js";
 export * from "./store-events.js";
-export * from "./to-event-store.js";

package/dist/operators/index.js

@@ -1,7 +1,5 @@
 export * from "./complete-on-eose.js";
 export * from "./liveness.js";
-export * from "./mark-from-relay.js";
 export * from "./only-events.js";
 export * from "./reverse-switch-map.js";
 export * from "./store-events.js";
-export * from "./to-event-store.js";

package/dist/operators/only-events.d.ts

@@ -1,5 +1,5 @@
 import { OperatorFunction } from "rxjs";
 import { NostrEvent } from "applesauce-core/helpers/event";
-import { SubscriptionResponse } from "../types.js";
+import { RelaySubscriptionResponse } from "../types.js";
 /** Filter subscription responses and only return the events */
-export declare function onlyEvents(): OperatorFunction<SubscriptionResponse, NostrEvent>;
+export declare function onlyEvents(): OperatorFunction<RelaySubscriptionResponse, NostrEvent>;

package/dist/operators/store-events.d.ts

@@ -1,5 +1,5 @@
 import { IEventStore } from "applesauce-core";
 import { MonoTypeOperatorFunction } from "rxjs";
-import { SubscriptionResponse } from "../types.js";
+import { RelaySubscriptionResponse } from "../types.js";
 /** Sends all events to the event store but does not remove duplicates */
-export declare function storeEvents(eventStore: IEventStore): MonoTypeOperatorFunction<SubscriptionResponse>;
+export declare function storeEvents(eventStore: IEventStore): MonoTypeOperatorFunction<RelaySubscriptionResponse>;

package/dist/pool.d.ts

@@ -5,8 +5,8 @@ import { BehaviorSubject, Observable, Subject } from "rxjs";
 import { RelayGroup } from "./group.js";
 import type { NegentropySyncOptions, ReconcileFunction } from "./negentropy.js";
 import { Relay, SyncDirection, type RelayOptions } from "./relay.js";
-import type { CountResponse, FilterInput, IPool, IPoolRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishResponse, RelayStatus, SubscriptionResponse } from "./types.js";
-export declare class RelayPool implements IPool {
+import type { RelayCountResponse, FilterInput, GroupReqOptions, GroupReqMessage, PoolRelayInput, NegentropyReadStore, NegentropySyncStore, PublishResponse, RelayStatus } from "./types.js";
+export declare class RelayPool {
     options?: RelayOptions | undefined;
     relays$: BehaviorSubject<Map<string, Relay>>;
     get relays(): Map<string, Relay>;
@@ -15,34 +15,34 @@ export declare class RelayPool implements IPool {
     /** Whether to ignore relays that are ready=false */
     ignoreOffline: boolean;
     /** A signal when a relay is added */
-    add$: Subject<IRelay>;
+    add$: Subject<Relay>;
     /** A signal when a relay is removed */
-    remove$: Subject<IRelay>;
+    remove$: Subject<Relay>;
     constructor(options?: RelayOptions | undefined);
     /** Get or create a new relay connection */
     relay(url: string): Relay;
     /** Create a group of relays */
-    group(relays: IPoolRelayInput, ignoreOffline?: boolean): RelayGroup;
+    group(relays: PoolRelayInput, ignoreOffline?: boolean): RelayGroup;
     /** Removes a relay from the pool and defaults to closing the connection */
-    remove(relay: string | IRelay, close?: boolean): void;
+    remove(relay: string | Relay, close?: boolean): void;
     /** Make a REQ to multiple relays that does not deduplicate events */
-    req(relays: IPoolRelayInput, filters: FilterInput, id?: string): Observable<SubscriptionResponse>;
+    req(relays: PoolRelayInput, filters: FilterInput, opts?: GroupReqOptions): Observable<GroupReqMessage>;
     /** Send an EVENT message to multiple relays */
-    event(relays: IPoolRelayInput, event: NostrEvent): Observable<PublishResponse>;
+    event(relays: PoolRelayInput, event: NostrEvent): Observable<PublishResponse>;
     /** Negentropy sync event ids with the relays and an event store */
-    negentropy(relays: IPoolRelayInput, store: NegentropyReadStore, filter: Filter, reconcile: ReconcileFunction, opts?: NegentropySyncOptions): Promise<boolean>;
+    negentropy(relays: PoolRelayInput, store: NegentropyReadStore, filter: Filter, reconcile: ReconcileFunction, opts?: NegentropySyncOptions): Promise<boolean>;
     /** Publish an event to multiple relays */
-    publish(relays: IPoolRelayInput, event: Parameters<RelayGroup["publish"]>[0], opts?: Parameters<RelayGroup["publish"]>[1]): Promise<PublishResponse[]>;
+    publish(relays: PoolRelayInput, event: Parameters<RelayGroup["publish"]>[0], opts?: Parameters<RelayGroup["publish"]>[1]): Promise<PublishResponse[]>;
     /** Request events from multiple relays */
-    request(relays: IPoolRelayInput, filters: FilterInput, opts?: Parameters<RelayGroup["request"]>[1]): Observable<NostrEvent>;
+    request(relays: PoolRelayInput, filters: Parameters<RelayGroup["request"]>[0], opts?: Parameters<RelayGroup["request"]>[1]): Observable<NostrEvent>;
     /** Open a subscription to multiple relays */
-    subscription(relays: IPoolRelayInput, filters: FilterInput, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    subscription(relays: PoolRelayInput, filters: Parameters<RelayGroup["subscription"]>[0], options?: Parameters<RelayGroup["subscription"]>[1]): Observable<NostrEvent>;
     /** Open a subscription for a map of relays and filters */
-    subscriptionMap(relays: FilterMap | Observable<FilterMap>, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    subscriptionMap(relays: FilterMap | Observable<FilterMap>, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<NostrEvent>;
     /** Open a subscription for an {@link OutboxMap} and filter */
-    outboxSubscription(outboxes: OutboxMap | Observable<OutboxMap>, filter: Omit<Filter, "authors">, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    outboxSubscription(outboxes: OutboxMap | Observable<OutboxMap>, filter: Omit<Filter, "authors">, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<NostrEvent>;
     /** Count events on multiple relays */
-    count(relays: IPoolRelayInput, filters: Filter | Filter[], id?: string): Observable<Record<string, CountResponse>>;
+    count(relays: PoolRelayInput, filters: Filter | Filter[], id?: string): Observable<Record<string, RelayCountResponse>>;
     /** Negentropy sync events with the relays and an event store */
-    sync(relays: IPoolRelayInput, store: NegentropySyncStore | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
+    sync(relays: PoolRelayInput, store: NegentropySyncStore | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
 }

package/dist/pool.js

@@ -82,9 +82,9 @@ export class RelayPool {
         this.remove$.next(instance);
     }
     /** Make a REQ to multiple relays that does not deduplicate events */
-    req(relays, filters, id) {
+    req(relays, filters, opts) {
         // Never filter out offline relays in manual methods
-        return this.group(relays, false).req(filters, id);
+        return this.group(relays, false).req(filters, opts);
     }
     /** Send an EVENT message to multiple relays */
     event(relays, event) {

package/dist/relay.d.ts

@@ -4,21 +4,25 @@ import { Filter } from "applesauce-core/helpers/filter";
 import { BehaviorSubject, MonoTypeOperatorFunction, Observable, RepeatConfig, RetryConfig, Subject } from "rxjs";
 import { WebSocketSubject, WebSocketSubjectConfig } from "rxjs/webSocket";
 import { type NegentropySyncOptions, type ReconcileFunction } from "./negentropy.js";
-import { AuthSigner, CountResponse, FilterInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayInformation, RelayStatus, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
+import { AuthSigner, FilterInput, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayCountResponse, RelayInformation, RelayReqMessage, RelayReqOptions, RelayRequestCompleteOperator, RelayRequestOptions, RelayRequestResponse, RelayStatus, RelaySubscriptionOptions, RelaySubscriptionResponse } from "./types.js";
 /** Flags for the negentropy sync type */
 export declare enum SyncDirection {
     RECEIVE = 1,
     SEND = 2,
     BOTH = 3
 }
-/** An error that is thrown when a REQ is closed from the relay side */
-export declare class ReqCloseError extends Error {
+/** Base error thrown when a relay closes a REQ or COUNT with a CLOSED message */
+export declare class RelayClosedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Thrown when the relay closes a subscription with an auth-required: prefix */
+export declare class AuthRequiredError extends RelayClosedError {
+    constructor(reason: string);
 }
 export type RelayOptions = {
     /** Custom WebSocket implementation */
     WebSocket?: WebSocketSubjectConfig<any>["WebSocketCtor"];
-    /** How long to wait for an EOSE message (default 10s) */
-    eoseTimeout?: number;
     /** How long to wait for an OK message from the relay (default 10s) */
     eventTimeout?: number;
     /** How long to wait for a publish to complete (default 30s) */
@@ -38,14 +42,14 @@ export type RelayOptions = {
         now: number;
         attempts: number;
     }) => "reconnect" | "close" | "ignore";
-    /** Default retry config for subscription() method */
-    subscriptionRetry?: RetryConfig;
-    /** Default retry config for request() method */
-    requestRetry?: RetryConfig;
+    /** Default reconnect config for subscription() method */
+    subscriptionReconnect?: RetryConfig;
+    /** Default reconnect config for request() method */
+    requestReconnect?: RetryConfig;
     /** Default retry config for publish() method */
     publishRetry?: RetryConfig;
 };
-export declare class Relay implements IRelay {
+export declare class Relay {
     url: string;
     protected log: typeof logger;
     protected socket: WebSocketSubject<any>;
@@ -103,7 +107,7 @@ export declare class Relay implements IRelay {
     open$: Subject<Event>;
     /** An observable that emits when underlying websocket is closed */
     close$: Subject<CloseEvent>;
-    /** An observable that emits when underlying websocket is closing due to unsubscription */
+    /** An observable that emits when underlying websocket is closing due to unsubscribe or complete */
     closing$: Subject<void>;
     /** Tracks active req() operations by subscription ID */
     reqs$: BehaviorSubject<Record<string, Filter[]>>;
@@ -118,8 +122,6 @@ export declare class Relay implements IRelay {
     get information(): RelayInformation | null;
     get lastMessageAt(): number;
     get reqs(): Record<string, Filter[]>;
-    /** If an EOSE message is not seen in this time, emit one locally (default 10s)  */
-    eoseTimeout: number;
     /** How long to wait for an OK message from the relay (default 10s) */
     eventTimeout: number;
     /** How long to wait for a publish to complete (default 30s) */
@@ -132,12 +134,12 @@ export declare class Relay implements IRelay {
     pingFrequency: number;
     /** How long to wait for EOSE response in milliseconds (default 20000) */
     pingTimeout: number;
-    /** Default retry config for subscription() method */
-    protected subscriptionReconnect: RetryConfig;
-    /** Default retry config for request() method */
-    protected requestReconnect: RetryConfig;
+    /** Default reconnect config for subscription() method */
+    subscriptionReconnect: RetryConfig;
+    /** Default reconnect config for request() method */
+    requestReconnect: RetryConfig;
     /** Default retry config for publish() method */
-    protected publishRetry: RetryConfig;
+    publishRetry: RetryConfig;
     /** Policy hook for unresponsive connections */
     protected onUnresponsive?: RelayOptions["onUnresponsive"];
     protected receivedAuthRequiredForReq: BehaviorSubject<boolean>;
@@ -158,9 +160,9 @@ export declare class Relay implements IRelay {
     /** Send a message to the relay */
     send(message: any): void;
     /** Create a REQ observable that emits events or "EOSE" or errors */
-    req(filters: FilterInput, id?: string): Observable<SubscriptionResponse>;
+    req(filters: FilterInput, opts?: RelayReqOptions): Observable<RelayReqMessage>;
     /** Create a COUNT observable that emits a single count response */
-    count(filters: Filter | Filter[], id?: string): Observable<CountResponse>;
+    count(filters: Filter | Filter[], id?: string): Observable<RelayCountResponse>;
     /** Send an EVENT or AUTH message and return an observable of PublishResponse that completes or errors */
     event(event: NostrEvent, verb?: "EVENT" | "AUTH"): Observable<PublishResponse>;
     /** send and AUTH message */
@@ -169,22 +171,20 @@ export declare class Relay implements IRelay {
     negentropy(store: NegentropyReadStore, filter: Filter, reconcile: ReconcileFunction, opts?: NegentropySyncOptions): Promise<boolean>;
     /** Authenticate with the relay using a signer */
     authenticate(signer: AuthSigner): Promise<PublishResponse>;
-    /** Internal operator for creating the retry() operator */
+    /** Internal operator for creating the retry() operator for reconnecting to the websocket */
     protected customRetryOperator<T extends unknown = unknown>(times: undefined | boolean | number | RetryConfig, base?: RetryConfig): MonoTypeOperatorFunction<T>;
-    /** Internal operator for creating the repeat() operator */
+    /** Internal operator for creating the repeat() operator for resubscribing */
     protected customRepeatOperator<T extends unknown = unknown>(times: undefined | boolean | number | RepeatConfig | undefined): MonoTypeOperatorFunction<T>;
     /** Internal operator for creating the timeout() operator */
     protected customTimeoutOperator<T extends unknown = unknown>(timeout: undefined | boolean | number, defaultTimeout: number): MonoTypeOperatorFunction<T>;
-    /** Internal operator for handling auth-required errors from REQ/COUNT operations */
-    protected handleAuthRequiredForReq(operation: "REQ" | "COUNT"): MonoTypeOperatorFunction<any>;
     /** Creates a REQ that retries when relay errors ( default 3 retries ) */
-    subscription(filters: FilterInput, opts?: SubscriptionOptions): Observable<SubscriptionResponse>;
+    subscription(filters: FilterInput, opts?: RelaySubscriptionOptions): Observable<RelaySubscriptionResponse>;
     /** Makes a single request that retires on errors and completes on EOSE */
-    request(filters: FilterInput, opts?: RequestOptions): Observable<NostrEvent>;
+    request(filters: FilterInput, opts?: RelayRequestOptions): Observable<RelayRequestResponse>;
     /** Publishes an event to the relay and retries when relay errors or responds with auth-required ( default 3 retries ) */
     publish(event: NostrEvent, opts?: PublishOptions): Promise<PublishResponse>;
     /** Negentropy sync events with the relay and an event store */
-    sync(store: NegentropySyncStore, filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
+    sync(store: NegentropySyncStore, filters: Filter, direction?: SyncDirection): Observable<NostrEvent>;
     /** Force close the connection */
     close(): void;
     /** An async method that returns the NIP-11 information document for the relay */
@@ -197,4 +197,12 @@ export declare class Relay implements IRelay {
     static fetchInformationDocument(url: string): Observable<RelayInformation | null>;
     /** Static method to create a reconnection method for each relay */
     static createReconnectTimer(_relay: string): (_error?: Error | CloseEvent, tries?: number) => Observable<0>;
+    /** A complete condition that waits for the subscription to open */
+    static afterOpen(condition: RelayRequestCompleteOperator): RelayRequestCompleteOperator;
+    /** An OR complete condition, that completes when either condition is truthy */
+    static completeOr(...conditions: RelayRequestCompleteOperator[]): RelayRequestCompleteOperator;
+    /** An AND complete condition, that completes when all conditions are truthy */
+    static completeAnd(...conditions: RelayRequestCompleteOperator[]): RelayRequestCompleteOperator;
+    /** A default complete condition that waits for the subscription to open and then completes after a timeout */
+    static defaultComplete(timeout: number, afterOpen?: number): RelayRequestCompleteOperator;
 }