@sockethub/client 5.0.0-alpha.8 → 5.0.0-beta.0

package/dist/sockethub-client.d.ts

@@ -0,0 +1,345 @@
+import type { ActivityStream, ServiceDescriptor, ServiceEndpoints } from "@sockethub/schemas";
+import EventEmitter from "eventemitter3";
+import type { ManagerOptions, Socket, SocketOptions } from "socket.io-client";
+import { type PlatformRegistryEntry, type PlatformRegistryPayload } from "./client-registry";
+import { type DiscoverOptions, type SocketFactory } from "./discovery";
+export type { ServiceDescriptor, ServiceEndpoints };
+export type { PlatformRegistryEntry, PlatformRegistryPayload, } from "./client-registry";
+export { type DiscoverOptions, DiscoveryError, discoverSockethub, resolveEndpoint, type SocketFactory, } from "./discovery";
+export type { EventMapping } from "./replay-store";
+type InitState = "idle" | "initializing" | "ready" | "init_error" | "closed";
+type ReadyReason = "initial-connect" | "reconnect" | "schemas-update";
+type InitErrorPhase = "schemas-request" | "schemas-apply" | "timeout";
+export interface SockethubClientOptions {
+    initTimeoutMs?: number;
+    maxQueuedOutbound?: number;
+    maxQueuedAgeMs?: number;
+}
+export interface ConnectOptions extends SockethubClientOptions, DiscoverOptions {
+    /**
+     * The `io()` factory to create the socket with. Defaults to the `io`
+     * global set by `/socket.io.js`, then to the `socket.io-client` package
+     * when it can be imported.
+     */
+    io?: SocketFactory;
+    /**
+     * Extra Socket.IO options (auth, transports, ...). `path` is always taken
+     * from the discovered descriptor.
+     */
+    socketOptions?: Partial<ManagerOptions & SocketOptions>;
+}
+interface CustomEmitter extends EventEmitter {
+    _emit(s: string, o: unknown, c?: unknown): void;
+    connect(): void;
+    disconnect(): void;
+    connected: boolean;
+    id: string;
+}
+export interface ClientReadyInfo {
+    state: "ready";
+    reason: ReadyReason;
+    apiVersion: number;
+    contexts: {
+        as: string;
+        sockethub: string;
+    };
+    platforms: Array<{
+        id: string;
+        apiVersion: number;
+        contextUrl: string;
+        contextVersion: string;
+        schemaVersion: string;
+        types: Array<string>;
+    }>;
+}
+export interface ClientInitError {
+    error: string;
+    phase: InitErrorPhase;
+    retrying: boolean;
+}
+/**
+ * SockethubClient - Client library for Sockethub protocol gateway
+ *
+ * A JavaScript client for connecting to Sockethub servers. Provides a high-level
+ * API for sending and receiving ActivityStreams messages over Socket.IO, with
+ * automatic state management and reconnection handling.
+ *
+ * Sockethub acts as a protocol gateway, translating ActivityStreams messages into
+ * various protocols (XMPP, IRC, RSS, etc.). This client handles the communication
+ * with the Sockethub server, including credential management, connection state,
+ * and automatic reconnection.
+ *
+ * ## Automatic Reconnection & State Replay
+ *
+ * This client automatically handles transient network disconnections by storing
+ * connection state in memory and replaying it when the socket reconnects.
+ *
+ * ### Security Model
+ *
+ * **Storage Location:**
+ * - All credentials and state are stored ONLY in JavaScript memory (heap)
+ * - Nothing is persisted to localStorage, sessionStorage, cookies, or disk
+ * - Memory is cleared when the browser tab closes or page refreshes
+ *
+ * **Replay Triggers:**
+ * - Automatic replay occurs on Socket.IO reconnection events
+ * - Typically triggered by brief network interruptions (WiFi switching, mobile network blips)
+ * - Does NOT occur on page refresh (new SockethubClient instance = empty state)
+ *
+ * **Server Restart Behavior:**
+ * - If server restarts, client socket will reconnect and replay credentials
+ * - Server must handle replayed credentials appropriately (validate, reject stale sessions, etc.)
+ * - Applications should implement proper session validation server-side
+ *
+ * **Lifetime:**
+ * - Credentials exist only during the browser tab's lifetime
+ * - Cleared on page reload, tab close, or manual disconnect
+ * - Not accessible across tabs or after browser restart
+ *
+ * **What Gets Replayed:**
+ * - Credentials (username/password/tokens sent via credentials event)
+ * - Activity Objects (actor definitions)
+ * - Connect commands (platform connections)
+ * - Join commands (room/channel joins)
+ *
+ * When one of this client's actors is renamed (an `update` with
+ * `object.type: "address"`, e.g. an IRC nick change, whether this client
+ * requested it and the server acknowledged it, or the server reported it),
+ * the stored entries move to the new actor so a reconnect replays the current
+ * identity rather than the old one.
+ *
+ * @example
+ * ```typescript
+ * // Discover the Socket.IO endpoint from the server's base URL and connect
+ * const client = await SockethubClient.connect('http://localhost:10550');
+ *
+ * // Or wrap a socket you created yourself
+ * const client = new SockethubClient(io('http://localhost:10550', { path: '/sockethub' }));
+ *
+ * // Wait for schema registry before sending messages
+ * await client.ready();
+ *
+ * // Build canonical @context for a platform
+ * const ctx = client.contextFor('irc');
+ *
+ * // Send credentials - these will be replayed on reconnection
+ * client.socket.emit('credentials', {
+ *   '@context': ctx,
+ *   type: 'credentials',
+ *   actor: { id: 'user@example.com', type: 'person' },
+ *   object: { type: 'credentials', username: 'user', password: 'pass' }
+ * });
+ * ```
+ */
+export default class SockethubClient {
+    private replayStore;
+    private _socket;
+    socket: CustomEmitter;
+    debug: boolean;
+    /**
+     * The service descriptor fetched by `SockethubClient.connect()`: API
+     * versions, enabled platforms, and the advertised endpoints (including
+     * `endpoints.httpActions` when that transport is on). Undefined for
+     * clients built from a ready-made socket.
+     */
+    readonly descriptor?: ServiceDescriptor;
+    /**
+     * The origin the descriptor was discovered from and the socket connects
+     * to. `endpointUrl()` resolves the descriptor's endpoint paths against it.
+     * Undefined for clients built from a ready-made socket.
+     */
+    readonly serverOrigin?: string;
+    /**
+     * Absolute URL of an advertised endpoint, resolved against
+     * `serverOrigin`, or undefined when the server does not advertise it (for
+     * example `httpActions` while HTTP actions are disabled) or when this
+     * client was not created by `connect()`.
+     *
+     * @example
+     * ```typescript
+     * const url = sc.endpointUrl('httpActions');
+     * if (url) {
+     *   await fetch(url, { method: 'POST', body });
+     * }
+     * ```
+     */
+    endpointUrl(name: keyof ServiceEndpoints): string | undefined;
+    private readonly options;
+    private platformRegistry;
+    private asContextUrl?;
+    private sockethubContextUrl?;
+    private apiVersion?;
+    private initState;
+    private hasReadyOnce;
+    private initCycle?;
+    private initTokenCounter;
+    private initTimeoutTimer?;
+    private waitingWarningTimer?;
+    private waitingWarningIntervalMs;
+    private readyWaiters;
+    private outboundQueue;
+    private outboundSequence;
+    private registryFingerprint?;
+    private latestReadyInfo?;
+    /**
+     * Discover a server's endpoints from its base URL and connect to it.
+     *
+     * Fetches the base URL with `Accept: application/json`, validates the
+     * service descriptor, and opens a Socket.IO connection to the base URL's
+     * origin with the advertised path. The descriptor is exposed as
+     * `client.descriptor` and the origin as `client.serverOrigin`. Rejects
+     * with a `DiscoveryError` when the server is unreachable, does not answer
+     * with JSON, or does not advertise a Socket.IO endpoint.
+     *
+     * @example
+     * ```typescript
+     * const sc = await SockethubClient.connect('https://sh.example.org', {
+     *   initTimeoutMs: 5000,
+     * });
+     * await sc.ready();
+     * console.log(sc.endpointUrl('httpActions')); // absolute URL, or undefined
+     * ```
+     */
+    static connect(baseUrl: string, options?: ConnectOptions): Promise<SockethubClient>;
+    constructor(socket: Socket, options?: SockethubClientOptions, discovered?: {
+        descriptor: ServiceDescriptor;
+        serverOrigin: string;
+    });
+    /**
+     * Clear stored credentials to prevent automatic replay on reconnection.
+     *
+     * This method removes all stored credentials from memory. Useful for
+     * security-sensitive applications that want to prevent automatic credential
+     * replay when the socket reconnects.
+     *
+     * @example
+     * ```typescript
+     * // Clear credentials on disconnect
+     * sc.socket.on('disconnect', () => {
+     *   sc.clearCredentials();
+     * });
+     * ```
+     */
+    clearCredentials(): void;
+    /**
+     * Return the platform registry discovered from the server.
+     */
+    getRegisteredPlatforms(): Array<PlatformRegistryEntry>;
+    /**
+     * Indicates whether server-provided schema/context registry data is loaded.
+     */
+    isSchemasReady(): boolean;
+    /**
+     * Indicates whether the client has completed schema initialization.
+     */
+    isReady(): boolean;
+    /**
+     * Returns the current client initialization state.
+     */
+    getInitState(): InitState;
+    /**
+     * Return the canonical base contexts learned from the server registry.
+     */
+    getRegisteredBaseContexts(): {
+        as: string;
+        sockethub: string;
+    };
+    getPlatformSchema(platform: string, schemaType?: "messages" | "credentials"): object | undefined;
+    /**
+     * Wait for schema registry data from the server and return the normalized payload.
+     * @deprecated Use ready(timeoutMs?) instead.
+     */
+    waitForSchemas(timeoutMs?: number): Promise<PlatformRegistryPayload>;
+    /**
+     * Wait until the client reaches a ready state.
+     */
+    ready(timeoutMs?: number): Promise<ClientReadyInfo>;
+    /**
+     * Validate an activity stream against currently registered platform schemas.
+     * Returns an empty string when valid.
+     */
+    validateActivity(activity: ActivityStream): string;
+    /**
+     * Build canonical Sockethub contexts for a platform using server-provided schema metadata.
+     */
+    contextFor(platform: string): ActivityStream["@context"];
+    private createPublicEmitter;
+    /**
+     * Ask server for the latest platform/context registry via ack callback.
+     * This keeps client context composition aligned with server schema state.
+     */
+    private requestSchemaRegistry;
+    /**
+     * Apply server-provided registry metadata to local runtime state.
+     * Also registers platform contexts/schemas with @sockethub/schemas validators
+     * so local validation uses the same canonical sources as the server.
+     */
+    private applyPlatformRegistry;
+    private buildPlatformRegistryPayload;
+    private buildReadyInfo;
+    private resolveReadyWaiters;
+    private rejectReadyWaiters;
+    private emitInitError;
+    private emitClientError;
+    private clearInitTimers;
+    private startWaitingWarnings;
+    private startInitialization;
+    private markReady;
+    private handleSchemasPayload;
+    private handlePublicEmit;
+    private enqueueOutbound;
+    private flushOutboundQueue;
+    private sendOutbound;
+    private log;
+    private registerSocketIOHandlers;
+    /**
+     * Keeps the replay maps on the actor the server now knows after a rename
+     * the server reported.
+     *
+     * A server-forced nick change arrives as an incoming `update` with
+     * `object.type: "address"`. The stored credentials, connect, and join
+     * entries are keyed by the actor at send time, so left alone a reconnect
+     * would replay the old nick and open a second connection under an
+     * identity this one no longer holds.
+     *
+     * Only entries for the renamed actor on that platform move. The maps hold
+     * only this client's own actors, and `rememberRequestedRename` keeps them
+     * on the nick this connection currently holds, so a rename of some other
+     * user (including one who later took a nick this client released) never
+     * matches a stored entry.
+     *
+     * A rejected nick change is not a rename. The server echoes the failed
+     * job — the original update plus `error` — to every other session sharing
+     * the connection. Following that echo would point those sessions at a
+     * nick the server refused, so their next command misses the live worker
+     * and opens a second connection.
+     */
+    private followActorRename;
+    /**
+     * Moves the replay maps when a nick change this client requested is
+     * acknowledged. The platform consumes the server's confirmation as the
+     * job's completion rather than delivering it as a message, so without
+     * this the maps would stay on the released nick: a reconnect would
+     * replay it, and whoever took it in the meantime could steer where
+     * `followActorRename` moves this client's state.
+     */
+    private rememberRequestedRename;
+    private moveReplayState;
+    /**
+     * Replays previously sent events to the server after reconnection.
+     *
+     * This method is called automatically when the Socket.IO connection is
+     * re-established after a transient network interruption. It resends
+     * credentials and connection state so the user doesn't need to manually
+     * re-authenticate or rejoin channels.
+     *
+     * Security considerations:
+     * - Only replays events stored in memory during this session
+     * - Does not replay after page refresh (memory cleared)
+     * - Server should validate replayed credentials (may be stale/revoked)
+     *
+     * @param name - Event name to emit ("credentials", "message")
+     * @param asMap - Map of events to replay
+     */
+    private replay;
+}