@gala-chain/launchpad-sdk 5.0.3 → 5.0.4-beta.1

package/dist/src/services/StreamTokenServiceBase.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Stream Token Service Base
+ *
+ * Abstract base class providing shared functionality for streaming-related services.
+ * Contains common helper methods for token validation, endpoint building,
+ * admin authentication, JWT authentication, and response handling.
+ *
+ * @category Services
+ * @since 5.1.1
+ * @internal
+ */
+import { HttpClient } from '../utils/http';
+import { BaseService } from './BaseService';
+import { TokenNameConstraint, InternalApiResponse } from '../types/common';
+import type { JwtAuth } from '../auth/JwtAuth';
+/**
+ * Admin API key header name
+ */
+export declare const ADMIN_API_KEY_HEADER = "x-api-key";
+/**
+ * Stream Token Service Base Class
+ *
+ * Provides shared functionality for StreamingService and StreamChatService:
+ * - Token name validation
+ * - Endpoint URL building with path parameters
+ * - Admin header management
+ * - JWT authentication support
+ * - Response data extraction
+ *
+ * @example
+ * ```typescript
+ * class MyStreamService extends StreamTokenServiceBase {
+ *   constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth) {
+ *     super(http, adminApiKey, jwtAuth, false);
+ *   }
+ *
+ *   async getStatus(tokenName: string) {
+ *     this.validateTokenName(tokenName, MY_CONSTRAINTS.TOKEN_NAME);
+ *     const endpoint = this.buildEndpoint('/api/:tokenName/status', { tokenName });
+ *     const response = await this.http.get(endpoint, this.getAdminHeaders());
+ *     return this.extractData(response);
+ *   }
+ *
+ *   async startStream(tokenName: string) {
+ *     // JWT-protected endpoint
+ *     const endpoint = this.buildEndpoint('/api/:tokenName/start', { tokenName });
+ *     const response = await this.http.post(endpoint, {}, { headers: this.getJwtHeaders() });
+ *     return this.extractData(response);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StreamTokenServiceBase extends BaseService {
+    /**
+     * Admin API key for authenticated endpoints
+     */
+    protected readonly adminApiKey: string | undefined;
+    /**
+     * JWT authentication manager for session-based auth
+     */
+    protected jwtAuth: JwtAuth | undefined;
+    /**
+     * Create a new stream token service instance
+     *
+     * @param http - HTTP client for API requests
+     * @param adminApiKey - Optional admin API key for admin-only endpoints
+     * @param jwtAuth - Optional JWT auth manager for session-based auth
+     * @param debugMode - Enable debug logging
+     */
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean);
+    /**
+     * Set the JWT authentication manager
+     *
+     * This allows dynamic configuration of JWT auth after service creation.
+     *
+     * @param jwtAuth - JWT auth manager instance
+     */
+    setJwtAuth(jwtAuth: JwtAuth): void;
+    /**
+     * Validate token name format against provided constraints
+     *
+     * @param tokenName - Token name to validate
+     * @param constraints - Token name validation constraints
+     * @throws {ValidationError} If token name is invalid
+     */
+    protected validateTokenName(tokenName: string, constraints: TokenNameConstraint): void;
+    /**
+     * Validate a required string parameter
+     *
+     * @param value - Value to validate
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @throws {ValidationError} If value is missing or not a string
+     *
+     * @example
+     * ```typescript
+     * this.validateRequiredString(assetId, 'assetId', 'Asset ID');
+     * // Throws: ValidationError('Asset ID is required', 'assetId', 'REQUIRED')
+     * ```
+     */
+    protected validateRequiredString(value: string | undefined, fieldName: string, displayName: string): void;
+    /**
+     * Validate an optional string parameter with max length constraint
+     *
+     * @param value - Value to validate (undefined/null allowed)
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @param maxLength - Maximum allowed string length
+     * @throws {ValidationError} If value is not a string or exceeds maxLength
+     *
+     * @example
+     * ```typescript
+     * this.validateOptionalString(description, 'description', 'Description', 255);
+     * this.validateOptionalString(reason, 'reason', 'Reason', 500);
+     * ```
+     */
+    protected validateOptionalString(value: string | undefined | null, fieldName: string, displayName: string, maxLength: number): void;
+    /**
+     * Validate an optional number parameter with min/max constraints
+     *
+     * @param value - Value to validate (undefined/null allowed)
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @param min - Minimum allowed value
+     * @param max - Maximum allowed value
+     * @param minMessage - Custom message suffix for minimum violation
+     * @param maxMessage - Custom message suffix for maximum violation
+     * @throws {ValidationError} If value is not a number or out of range
+     *
+     * @example
+     * ```typescript
+     * this.validateOptionalNumber(durationSeconds, 'durationSeconds', 'Duration', 60, 31536000, '1 minute', '1 year');
+     * ```
+     */
+    protected validateOptionalNumber(value: number | undefined | null, fieldName: string, displayName: string, min: number, max: number, minMessage?: string, maxMessage?: string): void;
+    /**
+     * Validate an optional ISO 8601 date string
+     *
+     * @param value - Value to validate (undefined/null allowed)
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @throws {ValidationError} If value is not a valid ISO 8601 date
+     *
+     * @example
+     * ```typescript
+     * this.validateOptionalDate(expiresAt, 'expiresAt', 'Expiration date');
+     * ```
+     */
+    protected validateOptionalDate(value: string | undefined | null, fieldName: string, displayName: string): void;
+    /**
+     * Validate a positive integer (for IDs)
+     *
+     * @param value - Value to validate
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @throws {ValidationError} If value is not a positive integer
+     *
+     * @example
+     * ```typescript
+     * this.validatePositiveInteger(id, 'id', 'API key ID');
+     * this.validatePositiveInteger(inviteId, 'inviteId', 'Invite ID');
+     * ```
+     */
+    protected validatePositiveInteger(value: number, fieldName: string, displayName: string): void;
+    /**
+     * Validate a status filter against an enum object
+     *
+     * Generic validator for status filters used in list operations.
+     * Works with any enum-like const object (OVERSEER_STATUS, INVITE_STATUS, etc.)
+     *
+     * @param status - Status value to validate (undefined allowed)
+     * @param validStatusEnum - Enum-like const object to validate against
+     * @param fieldName - Field name for error message (default: 'status')
+     * @throws {ValidationError} If status is not a valid enum value
+     *
+     * @example
+     * ```typescript
+     * this.validateStatusFilter(options.status, OVERSEER_INVITE_STATUS);
+     * this.validateStatusFilter(options.status, OVERSEER_STATUS);
+     * ```
+     */
+    protected validateStatusFilter<T extends Record<string, string>>(status: string | undefined, validStatusEnum: T, fieldName?: string): void;
+    /**
+     * Build pagination query parameters with max limit enforcement
+     *
+     * Consolidates the common pagination building pattern used across services:
+     * - Converts page/limit to strings
+     * - Enforces max limit constraint
+     * - Only includes params that are defined
+     *
+     * @param options - Options object with optional page and limit
+     * @param maxLimit - Maximum allowed limit value
+     * @returns Query params object with stringified page and limit
+     *
+     * @example
+     * ```typescript
+     * const params = this.buildPaginationParams(
+     *   { page: 1, limit: 50 },
+     *   CONSTRAINTS.PAGINATION.MAX_LIMIT
+     * );
+     * // Result: { page: '1', limit: '20' } if max is 20
+     * ```
+     */
+    protected buildPaginationParams(options: {
+        page?: number;
+        limit?: number;
+    }, maxLimit: number): Record<string, string>;
+    /**
+     * Add optional filter parameters to a query params object
+     *
+     * Consolidates the common pattern of conditionally adding filter params.
+     * Only adds params that have truthy values (not undefined, null, or empty string).
+     *
+     * @param params - Query params object to add to (mutated)
+     * @param options - Options object containing filter values
+     * @param fields - Array of field names to extract from options
+     * @returns The mutated params object (for chaining)
+     *
+     * @example
+     * ```typescript
+     * const params = this.buildPaginationParams(options, MAX_LIMIT);
+     * this.addOptionalFilterParams(params, options, ['search', 'name', 'userAddress']);
+     * ```
+     */
+    protected addOptionalFilterParams<T>(params: Record<string, string>, options: T, fields: (keyof T & string)[]): Record<string, string>;
+    /**
+     * Build endpoint URL with path parameters
+     *
+     * @param template - URL template with :param placeholders
+     * @param params - Parameters to substitute (values are lowercased and encoded)
+     * @returns Built URL with substituted parameters
+     *
+     * @example
+     * ```typescript
+     * const url = this.buildEndpoint('/api/:tokenName/status', { tokenName: 'MyToken' });
+     * // Returns: '/api/mytoken/status'
+     * ```
+     */
+    protected buildEndpoint(template: string, params: Record<string, string>): string;
+    /**
+     * Build endpoint URL with an ID parameter (case-preserved)
+     *
+     * Unlike buildEndpoint which lowercases values (for tokenName),
+     * this preserves the ID case for message IDs and other identifiers.
+     *
+     * This consolidates the duplicate buildEndpointWithId methods found in
+     * CommentsService and ChatMessagesService.
+     *
+     * @param template - URL template with :id placeholder
+     * @param id - ID value to substitute (case-preserved, URI-encoded)
+     * @returns Built URL with ID substituted
+     *
+     * @example
+     * ```typescript
+     * const url = this.buildEndpointWithId('/api/messages/:id', 'msg-1234567890123-abc');
+     * // Returns: '/api/messages/msg-1234567890123-abc'
+     * ```
+     */
+    protected buildEndpointWithId(template: string, id: string): string;
+    /**
+     * Validate token name and build endpoint URL in one step
+     *
+     * Consolidates the common pattern of validating token name then building endpoint:
+     * ```typescript
+     * this.validateTokenName(tokenName, constraints);
+     * const endpoint = this.buildEndpoint(template, { tokenName });
+     * ```
+     *
+     * @param tokenName - Token name to validate
+     * @param constraints - Token name validation constraints
+     * @param template - URL template with :tokenName placeholder
+     * @returns Built endpoint URL with validated, normalized token name
+     * @throws {ValidationError} If token name is invalid
+     *
+     * @example
+     * ```typescript
+     * const endpoint = this.validateAndBuildTokenEndpoint(
+     *   tokenName,
+     *   STREAMING_CONSTRAINTS.TOKEN_NAME,
+     *   STREAMING_ENDPOINTS.GET_STREAM_INFO
+     * );
+     * ```
+     */
+    protected validateAndBuildTokenEndpoint(tokenName: string, constraints: TokenNameConstraint, template: string): string;
+    /**
+     * Get admin headers for admin-only endpoints
+     *
+     * @returns Headers object with admin API key
+     * @throws {ConfigurationError} If admin API key is not configured
+     */
+    protected getAdminHeaders(): Record<string, string>;
+    /**
+     * Get JWT headers for session-authenticated endpoints
+     *
+     * @returns Headers object with Authorization: Bearer token
+     * @throws {ConfigurationError} If JWT auth is not configured or no token
+     */
+    protected getJwtHeaders(): Record<string, string>;
+    /**
+     * Check if JWT authentication is available
+     *
+     * @returns true if JWT auth is configured with a valid token
+     */
+    protected hasJwtAuth(): boolean;
+    /**
+     * Check if admin API key is configured
+     *
+     * @returns true if admin API key is set
+     */
+    protected hasAdminApiKey(): boolean;
+    /**
+     * Get headers for dual-auth endpoints (API key OR JWT).
+     *
+     * Dual-auth endpoints accept either admin API key or JWT authentication.
+     * This allows both admins and owners to perform the same operation with
+     * different authorization levels.
+     *
+     * Priority:
+     * 1. Admin API key (if configured) - takes precedence
+     * 2. JWT auth (if authenticated) - fallback for owners
+     *
+     * @returns Headers for authentication
+     * @throws ConfigurationError if neither auth method is available
+     *
+     * @example
+     * ```typescript
+     * // In a subclass
+     * async toggleFeatureWithDualAuth(tokenName: string) {
+     *   const headers = this.getDualAuthHeaders();
+     *   // If admin API key is set, uses admin headers
+     *   // Otherwise, requires valid JWT authentication
+     *   return this.http.post(endpoint, {}, headers);
+     * }
+     * ```
+     */
+    protected getDualAuthHeaders(): Record<string, string>;
+    /**
+     * Extract data from backend response wrapper
+     *
+     * @param response - Response object with data, error, and message fields
+     * @returns Extracted data
+     * @throws {Error} If response indicates an error or has no data
+     */
+    protected extractData<T>(response: InternalApiResponse<T>): T;
+    /**
+     * Toggle a feature (enable/disable) for a token
+     *
+     * Shared implementation for enable/disable patterns in streaming services.
+     * Handles validation, endpoint building, admin auth, and response extraction.
+     *
+     * @param tokenName - Token name to toggle feature for
+     * @param endpoint - API endpoint template with :tokenName placeholder
+     * @param constraints - Token name validation constraints
+     * @returns Toggle result with enabled status and token name
+     * @throws {ValidationError} If token name is invalid
+     * @throws {ConfigurationError} If admin API key is not configured
+     *
+     * @example
+     * ```typescript
+     * // In StreamingService
+     * async disableStream(tokenName: string) {
+     *   return this.toggleFeature(tokenName, STREAMING_ENDPOINTS.DISABLE_STREAM, STREAMING_CONSTRAINTS.TOKEN_NAME);
+     * }
+     * ```
+     */
+    protected toggleFeature(tokenName: string, endpoint: string, constraints: TokenNameConstraint): Promise<{
+        enabled: boolean;
+        tokenName: string;
+    }>;
+}
+//# sourceMappingURL=StreamTokenServiceBase.d.ts.map

package/dist/src/services/StreamTokenServiceBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamTokenServiceBase.d.ts","sourceRoot":"","sources":["../../../src/services/StreamTokenServiceBase.ts"],"names":[],"mappings":"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"}

package/dist/src/services/StreamWebSocketService.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Stream WebSocket Service
+ *
+ * Handles real-time streaming and chat events via Socket.IO including:
+ * - Stream status updates (IDLE/ACTIVE/DISABLED)
+ * - Viewer count updates
+ * - Chat messages
+ * - Subscription management
+ *
+ * @category Services
+ * @since 5.1.0
+ */
+import { Socket } from 'socket.io-client';
+import { LoggerBase } from './BaseService';
+import { StreamStatusEvent, StreamSubscribedEvent, StreamUnsubscribedEvent, ViewerCountEvent, StreamGlobalStatusEvent, StreamCountdownEvent, StreamLanguageEvent } from '../types/streaming.dto';
+import { StreamChatMessageEvent, StreamChatSentEvent, StreamChatErrorEvent, StreamChatStatusEvent, StreamChatGlobalStatusEvent, StreamChatAuthenticatedEvent, StreamChatAuthErrorEvent, StreamReactionEvent, StreamReactionErrorEvent, StreamChatPinnedEvent, StreamChatUnpinnedEvent, TypingIndicatorEvent } from '../types/stream-chat.dto';
+/**
+ * Stream WebSocket configuration
+ */
+export interface StreamWebSocketConfig {
+    /** Stream WebSocket server URL (SEPARATE from bundleBaseUrl) */
+    url: string;
+    /** JWT token for authentication (optional - required for chat) */
+    authToken?: string;
+    /** Maximum reconnection attempts (default: 5) */
+    reconnectAttempts?: number;
+    /** Delay between reconnection attempts in ms (default: 2000) */
+    reconnectDelay?: number;
+    /** Subscription timeout in ms (default: 10000) */
+    subscriptionTimeout?: number;
+}
+/**
+ * Stream event names used by the backend
+ */
+export declare const STREAM_EVENTS: {
+    readonly SUBSCRIBE: "subscribe_token";
+    readonly UNSUBSCRIBE: "unsubscribe_token";
+    readonly AUTHENTICATE: "authenticate";
+    readonly SEND_CHAT: "send_stream_chat";
+    readonly SEND_REACTION: "send_stream_reaction";
+    readonly TYPING_START: "typing_start";
+    readonly TYPING_STOP: "typing_stop";
+    readonly STREAM_STATUS: "stream_status";
+    readonly STREAM_SUBSCRIBED: "token_subscribed";
+    readonly STREAM_UNSUBSCRIBED: "token_unsubscribed";
+    readonly VIEWER_COUNT: "viewer_count";
+    readonly STREAM_GLOBAL_STATUS: "stream_global_status";
+    readonly CHAT_MESSAGE: "stream_chat_message";
+    readonly CHAT_SENT: "stream_chat_sent";
+    readonly CHAT_ERROR: "stream_chat_error";
+    readonly CHAT_STATUS: "stream_chat_status";
+    readonly CHAT_GLOBAL_STATUS: "stream_chat_global_status";
+    readonly CHAT_AUTHENTICATED: "stream_chat_authenticated";
+    readonly CHAT_AUTH_ERROR: "stream_chat_auth_error";
+    readonly REACTION: "stream_reaction";
+    readonly REACTION_ERROR: "stream_reaction_error";
+    readonly USER_TYPING: "user_typing";
+    readonly CHAT_PINNED: "stream_chat_pinned";
+    readonly CHAT_UNPINNED: "stream_chat_unpinned";
+    readonly COUNTDOWN_UPDATED: "stream_countdown_updated";
+    readonly LANGUAGE_UPDATED: "stream_language_updated";
+};
+/**
+ * Callback types for stream events
+ */
+export interface StreamEventCallbacks {
+    onStreamStatus?: (event: StreamStatusEvent) => void;
+    onStreamSubscribed?: (event: StreamSubscribedEvent) => void;
+    onStreamUnsubscribed?: (event: StreamUnsubscribedEvent) => void;
+    onViewerCount?: (event: ViewerCountEvent) => void;
+    onStreamGlobalStatus?: (event: StreamGlobalStatusEvent) => void;
+    onChatMessage?: (event: StreamChatMessageEvent) => void;
+    onChatSent?: (event: StreamChatSentEvent) => void;
+    onChatError?: (event: StreamChatErrorEvent) => void;
+    onChatStatus?: (event: StreamChatStatusEvent) => void;
+    onChatGlobalStatus?: (event: StreamChatGlobalStatusEvent) => void;
+    onChatAuthenticated?: (event: StreamChatAuthenticatedEvent) => void;
+    onChatAuthError?: (event: StreamChatAuthErrorEvent) => void;
+    onReaction?: (event: StreamReactionEvent) => void;
+    onReactionError?: (event: StreamReactionErrorEvent) => void;
+    onTypingIndicator?: (event: TypingIndicatorEvent) => void;
+    onChatPinned?: (event: StreamChatPinnedEvent) => void;
+    onChatUnpinned?: (event: StreamChatUnpinnedEvent) => void;
+    onCountdownUpdated?: (event: StreamCountdownEvent) => void;
+    onLanguageUpdated?: (event: StreamLanguageEvent) => void;
+}
+/**
+ * Stream WebSocket Service
+ *
+ * Manages real-time connections for streaming and chat functionality.
+ * Uses a SEPARATE WebSocket endpoint from the bundle backend.
+ *
+ * Key features:
+ * - Event buffering to prevent race conditions
+ * - Room-based subscriptions per token
+ * - Automatic reconnection with re-subscription
+ * - Memory-safe listener cleanup
+ *
+ * @example
+ * ```typescript
+ * const wsService = new StreamWebSocketService({
+ *   url: 'wss://stream.gala.com',
+ *   authToken: 'jwt-token-here'
+ * });
+ *
+ * await wsService.connect();
+ *
+ * // Subscribe to a stream
+ * await wsService.subscribeToStream('mytoken', {
+ *   onStreamStatus: (event) => console.log('Status:', event.status),
+ *   onViewerCount: (event) => console.log('Viewers:', event.count),
+ *   onChatMessage: (event) => console.log('Chat:', event.message.content)
+ * });
+ *
+ * // Send a chat message
+ * wsService.sendChatMessage('mytoken', 'Hello everyone!');
+ *
+ * // Cleanup
+ * wsService.unsubscribeFromStream('mytoken');
+ * wsService.disconnect();
+ * ```
+ */
+export declare class StreamWebSocketService extends LoggerBase {
+    private socket;
+    private config;
+    private isSocketIOAvailable;
+    private reconnectionManager;
+    private isAuthenticated;
+    private subscribedRooms;
+    private roomCallbacks;
+    private pendingSubscriptions;
+    private eventBuffer;
+    private eventBufferTimeouts;
+    private readonly MAX_BUFFER_SIZE;
+    private readonly BUFFER_CLEANUP_MS;
+    private globalCallbacks;
+    constructor(config: StreamWebSocketConfig, debug?: boolean);
+    /**
+     * Check if Socket.IO is available
+     */
+    private checkSocketIOAvailability;
+    /**
+     * Get room name for token
+     */
+    private getRoomName;
+    /**
+     * Buffer an event for potential late listeners
+     */
+    private bufferEvent;
+    /**
+     * Process buffered events for a newly subscribed token
+     */
+    private processBufferedEvents;
+    /**
+     * Setup global event listeners
+     */
+    private setupGlobalListeners;
+    /**
+     * Re-subscribe to all active rooms after reconnection
+     */
+    private resubscribeAll;
+    /**
+     * Connect to the stream WebSocket server
+     *
+     * @returns Promise that resolves when connected
+     * @throws ConfigurationError if Socket.IO is not available
+     */
+    connect(): Promise<void>;
+    /**
+     * Authenticate with the stream server for chat operations
+     *
+     * @param token JWT token for authentication
+     */
+    authenticate(token: string): void;
+    /**
+     * Subscribe to a token's stream events
+     *
+     * @param tokenName Token name to subscribe to
+     * @param callbacks Event callbacks for this subscription
+     * @returns Promise that resolves when subscription is confirmed
+     * @throws ValidationError if WebSocket is not connected
+     * @throws Error if subscription times out
+     */
+    subscribeToStream(tokenName: string, callbacks?: StreamEventCallbacks): Promise<StreamSubscribedEvent>;
+    /**
+     * Unsubscribe from a token's stream events
+     *
+     * @param tokenName Token name to unsubscribe from
+     */
+    unsubscribeFromStream(tokenName: string): void;
+    /**
+     * Send a chat message via WebSocket (faster than REST)
+     *
+     * @param tokenName Token name for the chat room
+     * @param content Message content
+     * @throws ValidationError if not authenticated or not connected
+     */
+    sendChatMessage(tokenName: string, content: string): void;
+    /**
+     * Send an ephemeral emoji reaction to a live stream
+     *
+     * Reactions are broadcast to all viewers but NOT persisted to database.
+     * Rate limiting is enforced server-side (burst of 10, then 0.5/sec refill).
+     *
+     * @param tokenName Token name for the stream
+     * @param emoji Emoji to send (single emoji or short sequence, max 15 chars)
+     * @param streamTime Current stream timecode in seconds (for viewer sync)
+     * @throws ValidationError if not authenticated or not connected
+     * @since 5.2.0
+     */
+    sendReaction(tokenName: string, emoji: string, streamTime?: number): void;
+    /**
+     * Send typing indicator start event
+     *
+     * Indicates user has started typing in chat. Server broadcasts typing
+     * status to all viewers in the room except the sender.
+     *
+     * Auto-expires after 5 seconds if no typing activity.
+     * Use sendTypingStop() to explicitly stop the indicator.
+     *
+     * @param tokenName Token name for the chat room
+     * @throws ValidationError if not authenticated or not connected
+     * @since 5.11.0
+     */
+    sendTypingStart(tokenName: string): void;
+    /**
+     * Send typing indicator stop event
+     *
+     * Indicates user has stopped typing (e.g., message sent, input cleared, blur).
+     * Call this when user sends message, clears input, or loses focus.
+     *
+     * @param tokenName Token name for the chat room
+     * @throws ValidationError if not authenticated or not connected
+     * @since 5.11.0
+     */
+    sendTypingStop(tokenName: string): void;
+    /**
+     * Set global event callbacks (not per-room)
+     *
+     * @param callbacks Global event callbacks
+     */
+    setGlobalCallbacks(callbacks: StreamEventCallbacks): void;
+    /**
+     * Get list of currently subscribed tokens
+     */
+    getSubscribedTokens(): string[];
+    /**
+     * Check if connected to the WebSocket server
+     */
+    isConnected(): boolean;
+    /**
+     * Check if authenticated for chat operations
+     */
+    isAuthenticatedForChat(): boolean;
+    /**
+     * Get the underlying Socket.IO instance
+     */
+    getSocket(): Socket | null;
+    /**
+     * Disconnect from the stream WebSocket server
+     *
+     * Cleans up all listeners, subscriptions, and buffers.
+     * All cleanup operations are wrapped in try-catch to ensure
+     * complete cleanup even if individual steps fail.
+     */
+    disconnect(): void;
+}
+//# sourceMappingURL=StreamWebSocketService.d.ts.map

package/dist/src/services/StreamWebSocketService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamWebSocketService.d.ts","sourceRoot":"","sources":["../../../src/services/StreamWebSocketService.ts"],"names":[],"mappings":"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"}