@sockethub/client 5.0.0-alpha.12 → 5.0.0-alpha.14

package/dist/sockethub-client.d.ts

@@ -0,0 +1,280 @@
+import type { ActivityStream } from "@sockethub/schemas";
+import EventEmitter from "eventemitter3";
+import type { Socket } from "socket.io-client";
+export interface EventMapping {
+    credentials: Map<string, ActivityStream>;
+    connect: Map<string, ActivityStream>;
+    join: Map<string, ActivityStream>;
+}
+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;
+}
+interface CustomEmitter extends EventEmitter {
+    _emit(s: string, o: unknown, c?: unknown): void;
+    connect(): void;
+    disconnect(): void;
+    connected: boolean;
+    id: string;
+}
+interface PlatformRegistrySchemas {
+    credentials?: object;
+    messages?: object;
+}
+/**
+ * Server-declared platform metadata used by the client for context generation
+ * and runtime validation.
+ */
+export interface PlatformRegistryEntry {
+    id: string;
+    version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    types: Array<string>;
+    schemas: PlatformRegistrySchemas;
+}
+export interface PlatformRegistryPayload {
+    version?: string;
+    fingerprint?: string;
+    unchanged?: boolean;
+    contexts?: {
+        as?: string;
+        sockethub?: string;
+    };
+    platforms?: Array<PlatformRegistryEntry>;
+}
+export interface ClientReadyInfo {
+    state: "ready";
+    reason: ReadyReason;
+    sockethubVersion: string;
+    contexts: {
+        as: string;
+        sockethub: string;
+    };
+    platforms: Array<{
+        id: string;
+        version: string;
+        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)
+ *
+ * @example
+ * ```typescript
+ * // Create client
+ * const socket = io('http://localhost:10550');
+ * const client = new SockethubClient(socket);
+ *
+ * // 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 {
+    /**
+     * In-memory storage for client state that should be replayed on reconnection.
+     *
+     * Security: Stored ONLY in JavaScript heap memory. Never persisted to disk,
+     * localStorage, or any permanent storage. Cleared on page reload.
+     */
+    private events;
+    private _socket;
+    socket: CustomEmitter;
+    debug: boolean;
+    private readonly options;
+    private platformRegistry;
+    private asContextUrl?;
+    private sockethubContextUrl?;
+    private sockethubVersion?;
+    private initState;
+    private hasReadyOnce;
+    private initCycle?;
+    private initTokenCounter;
+    private initTimeoutTimer?;
+    private waitingWarningTimer?;
+    private waitingWarningIntervalMs;
+    private readyWaiters;
+    private outboundQueue;
+    private outboundSequence;
+    private registryFingerprint?;
+    private latestReadyInfo?;
+    constructor(socket: Socket, options?: SockethubClientOptions);
+    /**
+     * 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 eventCredentials;
+    private eventMessage;
+    private static getKey;
+    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;
+    /**
+     * Type guard to check if an object is an ActivityStream with a valid actor.id.
+     */
+    private hasActorId;
+    /**
+     * 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;
+}
+export {};