@classytic/arc 2.17.1 → 2.18.0

package/dist/websocket-BJ0w-3Dt.d.mts

@@ -1,186 +0,0 @@
-import { FastifyPluginAsync } from "fastify";
-
-//#region src/integrations/websocket/adapter.d.ts
-/**
- * WebSocket cross-instance adapter contract.
- *
- * The adapter is NOT used for local broadcasts — `RoomManager` handles those.
- * The adapter only handles the cross-instance relay (Redis pub/sub, NATS, etc.)
- * so a message broadcast on instance A is also delivered to clients connected
- * to instance B.
- *
- * Implementations:
- *   - `LocalWebSocketAdapter` (here) — no-op, single-instance only
- *   - `RedisWebSocketAdapter` (@classytic/arc/integrations/websocket-redis)
- *
- * Custom adapters just need to satisfy the interface.
- */
-/**
- * Adapter interface for cross-instance WebSocket broadcast.
- *
- * - `publish()`: Send a message to all instances (via Redis, NATS, etc.)
- * - `subscribe()`: Receive messages from other instances
- * - `close()`: Clean up connections
- */
-interface WebSocketAdapter {
-  /** Adapter name for logging */
-  readonly name: string;
-  /** Publish a room broadcast to all other instances */
-  publish(room: string, message: string): Promise<void>;
-  /** Subscribe to broadcasts from other instances */
-  subscribe(callback: (room: string, message: string) => void): Promise<void>;
-  /** Close adapter connections */
-  close(): Promise<void>;
-}
-/**
- * Default adapter — no cross-instance broadcast (single-instance only).
- * All methods are no-ops. Used when no adapter is configured.
- */
-declare class LocalWebSocketAdapter implements WebSocketAdapter {
-  readonly name = "local";
-  publish(): Promise<void>;
-  subscribe(): Promise<void>;
-  close(): Promise<void>;
-}
-//#endregion
-//#region src/integrations/websocket/types.d.ts
-/**
- * A connected WebSocket client — one entry per TCP socket.
- *
- * `subscriptions` is mutated by `RoomManager`; other fields are set once at
- * handshake time and treated as effectively immutable for the lifetime of
- * the connection.
- */
-interface WebSocketClient {
-  id: string;
-  socket: {
-    send(data: string): void;
-    close(): void;
-    readyState: number;
-  };
-  subscriptions: Set<string>;
-  userId?: string;
-  organizationId?: string;
-  /** OAuth client ID — present for service/machine-to-machine connections */
-  clientId?: string;
-  /** OAuth scopes — present for service/machine-to-machine connections */
-  scopes?: readonly string[];
-  metadata?: Record<string, unknown>;
-}
-interface WebSocketMessage {
-  type: string;
-  resource?: string;
-  channel?: string;
-  data?: unknown;
-}
-/**
- * Result of a successful authentication. The plugin's handshake and the
- * optional re-auth loop both return this shape so the downstream code
- * doesn't branch on auth mode. `null` means rejected.
- */
-interface AuthResult {
-  userId?: string;
-  organizationId?: string;
-  /** Set for machine-to-machine / service account auth */
-  clientId?: string;
-  /** OAuth scopes for service accounts */
-  scopes?: readonly string[];
-}
-interface WebSocketPluginOptions {
-  /** WebSocket endpoint path (default: '/ws') */
-  path?: string;
-  /** Require authentication for WebSocket connections (default: true) */
-  auth?: boolean;
-  /** Resources to auto-broadcast CRUD events for */
-  resources?: string[];
-  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */
-  heartbeatInterval?: number;
-  /** Custom authentication function for WebSocket upgrade */
-  authenticate?: (request: unknown) => Promise<AuthResult | null>;
-  /** Max clients per resource subscription (default: 10000) */
-  maxClientsPerRoom?: number;
-  /**
-   * Expose a stats endpoint at `{path}/stats`.
-   * - `false` (default): stats endpoint is not registered
-   * - `true`: registered without auth
-   * - `'authenticated'`: guarded by `fastify.authenticate` if available
-   */
-  exposeStats?: boolean | "authenticated";
-  /**
-   * Authorize room subscriptions. Return true to allow, false to deny.
-   * Called before every subscribe. If not provided, all rooms are allowed.
-   */
-  roomPolicy?: (client: WebSocketClient, room: string) => boolean | Promise<boolean>;
-  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */
-  maxMessageBytes?: number;
-  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
-  maxSubscriptionsPerClient?: number;
-  /**
-   * Periodic re-authentication interval in ms (default: 0 = disabled).
-   * When set, the server periodically re-validates the client's auth token.
-   * If the token is expired/revoked, the client is disconnected with code 4003.
-   *
-   * Recommended: 300000 (5 minutes) for production.
-   *
-   * @example
-   * ```typescript
-   * websocketPlugin({ reauthInterval: 5 * 60 * 1000 }) // re-check every 5 min
-   * ```
-   */
-  reauthInterval?: number;
-  /** Custom message handler */
-  onMessage?: (client: WebSocketClient, message: WebSocketMessage) => void | Promise<void>;
-  /** Called when a client connects */
-  onConnect?: (client: WebSocketClient) => void | Promise<void>;
-  /** Called when a client disconnects */
-  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;
-  /**
-   * Cross-instance broadcast adapter (default: LocalWebSocketAdapter — single-instance only).
-   * Provide a RedisWebSocketAdapter for multi-instance deployments.
-   *
-   * @example
-   * ```typescript
-   * import { RedisWebSocketAdapter } from '@classytic/arc/integrations/websocket-redis';
-   * adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })
-   * ```
-   */
-  adapter?: WebSocketAdapter;
-}
-//#endregion
-//#region src/integrations/websocket/plugin.d.ts
-/** Pluggable WebSocket integration for Arc */
-declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
-//#endregion
-//#region src/integrations/websocket/room-manager.d.ts
-declare class RoomManager {
-  private rooms;
-  private clients;
-  private maxPerRoom;
-  private adapter?;
-  constructor(maxPerRoom?: number, adapter?: WebSocketAdapter);
-  addClient(client: WebSocketClient): void;
-  removeClient(clientId: string): void;
-  subscribe(clientId: string, room: string): boolean;
-  unsubscribe(clientId: string, room: string): void;
-  broadcast(room: string, message: string, excludeClientId?: string): void;
-  broadcastToOrg(organizationId: string, room: string, message: string): void;
-  /**
-   * Broadcast locally AND through adapter (for cross-instance delivery).
-   * Use this instead of broadcast() when multi-instance is possible.
-   */
-  broadcastWithAdapter(room: string, message: string, excludeClientId?: string): Promise<void>;
-  /**
-   * Org-scoped broadcast locally AND through adapter.
-   * Uses a namespaced room key for the adapter so other instances
-   * can filter by org when delivering locally.
-   */
-  broadcastToOrgWithAdapter(organizationId: string, room: string, message: string): Promise<void>;
-  getClient(clientId: string): WebSocketClient | undefined;
-  getStats(): {
-    clients: number;
-    rooms: number;
-    subscriptions: Record<string, number>;
-  };
-}
-//#endregion
-export { WebSocketMessage as a, WebSocketAdapter as c, WebSocketClient as i, websocketPlugin as n, WebSocketPluginOptions as o, AuthResult as r, LocalWebSocketAdapter as s, RoomManager as t };