@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/fleet/rooms/room-client.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Fleet rooms — member client.
+ *
+ * Reconnection follows the Buzz ACP harness (`crates/buzz-acp/src/relay.rs`):
+ * resubscribe after reconnect from a per-subscription cursor and drop events
+ * already seen with a two-generation id set (`TwoGenDedup`, 12 000 ids). The
+ * cursor is the hub `seq` (plus its `storeId`) instead of `created_at`, so
+ * member clock drift cannot open a hole.
+ *
+ * Everything received is untrusted data: signatures and room tags are checked
+ * again locally (the hub could be compromised), and `text` is the content
+ * passed through the fleet peer-text sanitizer. This client never runs a tool,
+ * a prompt or a command because of a message.
+ *
+ * @module fleet/rooms/room-client
+ */
+import { EventEmitter } from 'events';
+import { type ReadonlyRoomEvent, type RoomEvent, type RoomMessageInput, type ThreadReference } from './room-event.js';
+import { type RoomFilter } from './room-filter.js';
+export interface FleetRoomClientOptions {
+    /** Hub WebSocket URL, e.g. `ws://127.0.0.1:3000/ws`. */
+    url: string;
+    apiKey?: string;
+    jwt?: string;
+    /** Member secret key (64 hex). Never logged or sent. */
+    secretKey: string;
+    /** Audience override for a hub reached through a proxy; defaults to `url`. */
+    audience?: string;
+    requestTimeoutMs?: number;
+    autoReconnect?: boolean;
+    reconnectInitialDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+    /** Consecutive failed reconnection attempts before giving up. */
+    reconnectMaxAttempts?: number;
+}
+export interface RoomCursor {
+    storeId: string;
+    throughSeq: number;
+}
+export interface RoomFetchOptions {
+    /** Maximum messages retained by this one-shot read (default 500, maximum 1000). */
+    maxMessages?: number;
+    /** Maximum approximate encoded result size (default and maximum 4 MiB). */
+    maxBytes?: number;
+}
+export interface ReceivedRoomMessage {
+    seq: number;
+    room: string;
+    author: string;
+    event: ReadonlyRoomEvent;
+    mentions: string[];
+    thread?: ThreadReference;
+    /** Content after the peer-text sanitizer; display it, never execute it. */
+    text: string;
+}
+export interface RoomEoseInfo {
+    storeId: string;
+    throughSeq: number;
+    gap: boolean;
+    epochChanged: boolean;
+    /** More replay records exist after `throughSeq`. */
+    truncated: boolean;
+}
+export interface RoomSubscriptionHandlers {
+    onMessage(message: ReceivedRoomMessage): void;
+    /** Stored events delivered; later messages are live. */
+    onEose?(info: RoomEoseInfo): void;
+    /** Terminal close (`restricted:`, `invalid:` …); the subscription is gone. */
+    onClosed?(message: string): void;
+}
+export interface RoomSubscriptionHandle {
+    readonly subId: string;
+    cursor(): RoomCursor | undefined;
+    close(): Promise<void>;
+}
+export declare class RoomClientError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+interface RoomConnectionInfo {
+    pubkey: string;
+    name: string;
+    rooms: unknown[];
+}
+export declare class FleetRoomClient extends EventEmitter {
+    readonly pubkey: string;
+    readonly audience: string;
+    private readonly options;
+    private readonly requestTimeoutMs;
+    private readonly reconnectInitialDelayMs;
+    private readonly reconnectMaxDelayMs;
+    private readonly reconnectMaxAttempts;
+    private ws;
+    private ready;
+    private closing;
+    private everConnected;
+    private requestCounter;
+    private readonly pending;
+    private readonly subscriptions;
+    private readonly seen;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private readyWaiters;
+    private opening;
+    private connectionInfo;
+    constructor(options: FleetRoomClientOptions);
+    get isReady(): boolean;
+    /** Connect, authenticate the WebSocket, then prove the member key. */
+    connect(): Promise<RoomConnectionInfo>;
+    private startOpen;
+    private open;
+    private proveIdentity;
+    private sendRaw;
+    private request;
+    private handleMessage;
+    private onEvent;
+    private onEose;
+    private onClosed;
+    private closeSubscriptionLocally;
+    private callHandler;
+    private sendSubscribe;
+    private waitUntilReady;
+    /**
+     * Sign and publish. Resolves once the hub has durably stored the message
+     * (or already had it). A connection lost before the acknowledgement is
+     * retried once with the SAME signed event, which the hub deduplicates.
+     */
+    publish(input: RoomMessageInput): Promise<{
+        id: string;
+        seq: number;
+        duplicate: boolean;
+        storeId: string;
+    }>;
+    publishSigned(event: RoomEvent): Promise<{
+        id: string;
+        seq: number;
+        duplicate: boolean;
+        storeId: string;
+    }>;
+    /** Open a subscription; it survives reconnections until closed. */
+    subscribe(subId: string, filters: RoomFilter[], handlers: RoomSubscriptionHandlers, cursor?: RoomCursor): RoomSubscriptionHandle;
+    private openSubscription;
+    /**
+     * One-shot read: stored messages matching `filters` (or after `cursor`),
+     * returned with the cursor to resume from next time.
+     */
+    fetch(filters: RoomFilter[], cursor?: RoomCursor, options?: RoomFetchOptions): Promise<{
+        messages: ReceivedRoomMessage[];
+        cursor: RoomCursor;
+        gap: boolean;
+        epochChanged: boolean;
+        truncated: boolean;
+    }>;
+    private onSocketClosed;
+    private scheduleReconnect;
+    close(): Promise<void>;
+}
+export {};