mcast-client/dist/index.d.cts

WebSocket client for Mcast real-time messaging

/**
 * Configuration options for the McastClient
 */
interface McastOptions {
    /**
     * Authentication token for the client
     */
    authToken: string;
    /**
     * The channel to connect to
     */
    channel: string;
    /**
     * Optionally, root topics subscribed to filtered on server
     */
    topics?: Array<string>;
    /**
     * Additional headers to include in requests
     */
    headers?: Record<string, string>;
    /**
     * Whether to automatically reconnect on connection loss
     * @default true
     */
    autoReconnect?: boolean;
    /**
     * Maximum reconnection attempts before giving up
     * @default 5
     */
    maxReconnectAttempts?: number;
    /**
     * Delay between reconnection attempts (in milliseconds)
     * @default 3000
     */
    reconnectDelay?: number;
    /**
     * Whether to log debug information to the console
     * @default false
     */
    debug?: boolean;
}
/**
 * Message object for publishing and receiving
 */
interface Message {
    /**
     * Topic of the message
     */
    topic: string;
    /**
     * Payload of the message
     */
    payload: Record<string, any>;
}
/**
 * Serialized message format used internally
 */
interface SerializedMessage {
    /**
     * Topic of the message
     */
    topic: string;
    /**
     * Serialized payload of the message
     */
    payload: string;
}
/**
 * Connection states for WebSocket connections
 */
declare enum ConnectionState {
    DISCONNECTING = "disconnecting",
    DISCONNECTED = "disconnected",
    CONNECTING = "connecting",
    CONNECTED = "connected",
    RECONNECTING = "reconnecting",
    ERROR = "error"
}
/**
 * Constant representing all topics
 */
declare const TOPIC_ALL: string;
/**
 * Response from the server to the client
 */
interface StandardResponse {
    success: boolean;
    message?: string;
    error?: string;
    data?: any;
}
/**
 * Account focused response from the server to the client
 */
interface AccountResponse {
    clientId: string;
    channel?: string;
    token?: string;
    tokenExpiresAt?: Date;
    clientName?: string;
    clientGroup?: string;
}
/**
 * Callback type for message subscription
 */
type MessageCallback = (topic: string, message: Record<string, any>) => void;

/**
 * Mcast WebSocket Client
 *
 * Manages WebSocket connections to a Mcast server for real-time messaging
 */
declare class McastClient {
    private baseUrl;
    private authToken;
    private channel;
    private headers;
    private autoReconnect;
    private maxReconnectAttempts;
    private reconnectDelay;
    private debug;
    private rootTopics;
    private pubSocket;
    private subSocket;
    private pubState;
    private subState;
    private pubReconnectAttempts;
    private subReconnectAttempts;
    private listeners;
    private stateChangeListeners;
    private pubConnectPromise;
    private subConnectPromise;
    private isDisconnecting;
    /**
     * Creates a new instance of the McastClient
     *
     * @param options Configuration options for the client
     */
    constructor(options: McastOptions);
    /**
     * Handling storing the new auth token and updating headers
     *
     * @param token The new auth token
     */
    private updateAuthToken;
    /**
     * Rotates the account token via HTTP POST
     *
     * @returns Promise that resolves with the server response
     */
    rotateToken(): Promise<AccountResponse>;
    /**
     * Sets up a WebSocket connection for publishing messages
     *
     * @returns Promise that resolves when the connection is established
     */
    private connectPublisher;
    /**
     * Sets up a WebSocket connection for subscribing to messages
     *
     * @returns Promise that resolves when the connection is established
     */
    private connectSubscriber;
    /**
     * Attempts to reconnect the publisher socket
     */
    private attemptReconnectPublisher;
    /**
     * Attempts to reconnect the subscriber socket
     */
    private attemptReconnectSubscriber;
    /**
     * Updates the publisher connection state and notifies listeners
     *
     * @param state New connection state
     */
    private updatePublisherState;
    /**
     * Updates the subscriber connection state and notifies listeners
     *
     * @param state New connection state
     */
    private updateSubscriberState;
    /**
     * Notifies all state change listeners of a state change
     *
     * @param state New connection state
     * @param connectionType Type of connection that changed state
     */
    private notifyStateChangeListeners;
    /**
     * Publishes a message to a topic
     *
     * @param topic Topic to publish to
     * @param payload Message payload to publish
     * @returns Promise that resolves when the message is published
     */
    publish(topic: string, payload: Record<string, any>): Promise<void>;
    /**
     * Publishes a message via HTTP POST instead of WebSocket
     *
     * @param topic Topic to publish to
     * @param payload Message payload to publish
     * @returns Promise that resolves with the server response
     */
    publishHttp(topic: string, payload: Record<string, any>): Promise<StandardResponse>;
    /**
     * Subscribes to one or more topics
     *
     * @param callback Callback function to call when a message is received
     * @param topics Optional topic or topics to subscribe to filtered on client
     * @returns Promise that resolves when the subscription is established
     */
    subscribe(callback: MessageCallback, topics?: string | string[]): Promise<void>;
    /**
     * Unsubscribes from a topic
     *
     * @param topic Topic to unsubscribe from
     * @param callback Optional callback function to remove. If not provided, all callbacks for the topic will be removed.
     */
    unsubscribe(topic: string, callback?: MessageCallback): void;
    /**
     * Disconnects from the server
     *
     * @returns Promise that resolves when disconnection is complete
     */
    disconnect(): Promise<void>;
    /**
     * Adds a listener for connection state changes
     *
     * @param listener Function to call when the connection state changes
     * @returns Function to remove the listener
     */
    onStateChange(listener: (state: ConnectionState, connectionType: "publisher" | "subscriber") => void): () => void;
    /**
     * Gets the current connection state for the publisher
     */
    getPublisherState(): ConnectionState;
    /**
     * Gets the current connection state for the subscriber
     */
    getSubscriberState(): ConnectionState;
    /**
     * Checks if a socket is connected
     *
     * @param socket WebSocket to check
     * @returns True if the socket is connected
     */
    private isSocketConnected;
    /**
     * Gets the WebSocket base URL (ws:// or wss://) from the HTTP base URL
     *
     * @returns WebSocket base URL
     */
    private getWebSocketBaseUrl;
    /**
     * Logs a debug message if debug mode is enabled
     *
     * @param message Message to log
     * @param args Additional arguments to log
     */
    private logDebug;
}

/**
 * Load client configuration from environment variables
 *
 * @returns Client options loaded from environment variables
 * @throws Error if required environment variables are missing
 */
declare function loadFromEnv(): McastOptions;

export { ConnectionState, McastClient, type McastOptions, type Message, type MessageCallback, type SerializedMessage, type StandardResponse, TOPIC_ALL, loadFromEnv };