notif-agent 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Connection states matching the Pusher-like lifecycle.
+ */
+type ConnectionState = 'initialized' | 'connecting' | 'connected' | 'unavailable' | 'failed' | 'disconnected';
+interface StateChangePayload {
+    previous: ConnectionState;
+    current: ConnectionState;
+}
+interface EventMetadata {
+    channel?: string;
+    event: string;
+    id?: string;
+    timestamp?: number;
+}
+type EventCallback<T = any> = (data: T, metadata?: EventMetadata) => void;
+type GlobalEventCallback = (eventName: string, data: any, metadata?: EventMetadata) => void;
+type TransportType = 'auto' | 'eventsource' | 'fetch';
+interface NotifAgentOptions {
+    /**
+     * The SSE endpoint URL.
+     */
+    url?: string;
+    /**
+     * Custom HTTP headers (forces `fetch` transport if specified in browser).
+     * Can be an object or a sync/async function returning an object.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Query parameters to append to the SSE URL.
+     */
+    queryParams?: Record<string, string | number | boolean>;
+    /**
+     * Whether to send cookies with cross-origin requests.
+     * Defaults to false.
+     */
+    withCredentials?: boolean;
+    /**
+     * SSE Transport mechanism.
+     * - 'auto': uses Fetch stream if custom headers or non-browser, otherwise EventSource if available.
+     * - 'eventsource': uses standard EventSource.
+     * - 'fetch': uses fetch API with ReadableStream.
+     * Defaults to 'auto'.
+     */
+    transport?: TransportType;
+    /**
+     * Initial delay in ms before reconnection attempts.
+     * Defaults to 1000ms.
+     */
+    reconnectBaseDelay?: number;
+    /**
+     * Maximum reconnect delay in ms.
+     * Defaults to 30000ms.
+     */
+    reconnectMaxDelay?: number;
+    /**
+     * Maximum number of reconnect attempts before transitioning to 'failed'.
+     * Defaults to Infinity.
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Heartbeat timeout in ms. If no data/ping is received within this period,
+     * the connection is presumed dead and reconnected.
+     * Defaults to 45000ms (45s).
+     */
+    heartbeatTimeout?: number;
+    /**
+     * Whether to automatically connect upon instantiation.
+     * Defaults to true.
+     */
+    autoConnect?: boolean;
+    /**
+     * Enable verbose console logging for debugging.
+     * Defaults to false.
+     */
+    debug?: boolean;
+    /**
+     * Endpoint URL for channel authorization (Pusher-compatible authEndpoint).
+     * Automatically invoked when subscribing to private or presence channels (e.g. `private-*`).
+     */
+    authEndpoint?: string;
+    /**
+     * Custom authentication headers and parameters sent to `authEndpoint`.
+     */
+    auth?: {
+        headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+        params?: Record<string, any>;
+    };
+}
+type ChannelSubscriptionState = 'unsubscribed' | 'subscribing' | 'subscribed' | 'error';
+interface SSEMessagePayload<T = any> {
+    channel?: string;
+    event: string;
+    data: T;
+    id?: string;
+    timestamp?: number;
+}
+
+declare class Channel {
+    readonly name: string;
+    state: ChannelSubscriptionState;
+    private emitter;
+    constructor(name: string);
+    /**
+     * Whether the channel is currently successfully subscribed.
+     */
+    get subscribed(): boolean;
+    /**
+     * Bind an event listener to this channel.
+     *
+     * Example:
+     * ```ts
+     * channel.bind('new-comment', (data) => {
+     *   console.log(data);
+     * });
+     * ```
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind an event listener from this channel.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind a global listener to all events received on this channel.
+     *
+     * Example:
+     * ```ts
+     * channel.bind_global((eventName, data) => {
+     *   console.log(`Event ${eventName}:`, data);
+     * });
+     * ```
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global listener from this channel.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Internal method to dispatch an event onto this channel.
+     */
+    handleEvent<T = any>(event: string, data: T, metadata?: EventMetadata): void;
+    /**
+     * Internal method to update subscription status and fire Pusher-compatible subscription events.
+     */
+    setSubscribed(data?: any): void;
+    /**
+     * Internal method to set subscription error.
+     */
+    setSubscriptionError(error: any): void;
+    /**
+     * Internal method called when channel is unsubscribed.
+     */
+    setUnsubscribed(): void;
+}
+
+declare class ConnectionManager {
+    state: ConnectionState;
+    clientId: string | null;
+    /**
+     * Pusher-compatible alias for clientId.
+     */
+    get socket_id(): string | null;
+    private emitter;
+    private options;
+    private eventSource;
+    private abortController;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private isManuallyClosed;
+    constructor(url: string, options?: NotifAgentOptions);
+    bind<T = any>(event: string, callback: (data: T) => void): this;
+    unbind<T = any>(event?: string, callback?: (data: T) => void): this;
+    connect(): void;
+    disconnect(): void;
+    private transition;
+    private establishConnection;
+    private connectViaEventSource;
+    private connectViaFetch;
+    private processSSEFrame;
+    private parseAndDispatchMessage;
+    private handleConnectionSuccess;
+    private handleConnectionFailure;
+    private scheduleReconnect;
+    private resetHeartbeat;
+    private clearHeartbeat;
+    private clearTimers;
+    private closeActiveTransport;
+    private buildUrl;
+    private resolveHeaders;
+    private log;
+}
+
+declare class NotifAgent {
+    readonly connection: ConnectionManager;
+    private options;
+    private channels;
+    private globalEmitter;
+    /**
+     * Unique client connection ID provided by NotifServer handshake.
+     */
+    get clientId(): string | null;
+    /**
+     * Pusher-compatible alias for clientId.
+     */
+    get socket_id(): string | null;
+    constructor(urlOrOptions: string | NotifAgentOptions, maybeOptions?: NotifAgentOptions);
+    /**
+     * Subscribe to a channel.
+     *
+     * Example:
+     * ```ts
+     * const channel = agent.subscribe('orders');
+     * channel.bind('created', (order) => { ... });
+     * ```
+     */
+    subscribe(channelName: string): Channel;
+    /**
+     * Internal authorization helper for private/presence channels.
+     */
+    private authorizeChannel;
+    /**
+     * Unsubscribe from a channel.
+     */
+    unsubscribe(channelName: string): void;
+    /**
+     * Get an existing subscribed channel by name, if any.
+     */
+    channel(channelName: string): Channel | undefined;
+    /**
+     * Return all currently subscribed channels.
+     */
+    allChannels(): Channel[];
+    /**
+     * Bind to an event across all channels or global events.
+     *
+     * Example:
+     * ```ts
+     * agent.bind('system-alert', (data) => console.log(data));
+     * ```
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind an event listener.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind to all events regardless of name.
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global event listener.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Connect to the SSE endpoint.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the SSE endpoint.
+     */
+    disconnect(): void;
+    /**
+     * Route incoming SSE message to global emitters and specific channels.
+     */
+    private routeMessage;
+}
+
+declare class EventEmitter {
+    private listeners;
+    private globalListeners;
+    /**
+     * Bind a callback to a specific event name.
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind a callback from a specific event name, or all callbacks if callback is omitted.
+     * If both event and callback are omitted, all listeners are removed.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind a callback to ALL incoming events on this emitter.
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global callback, or all global callbacks if callback is omitted.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Emit an event to registered listeners and global listeners.
+     */
+    emit<T = any>(event: string, data: T, metadata?: EventMetadata): void;
+    /**
+     * Clear all listeners.
+     */
+    clear(): void;
+}
+
+export { Channel, type ChannelSubscriptionState, ConnectionManager, type ConnectionState, type EventCallback, EventEmitter, type EventMetadata, type GlobalEventCallback, NotifAgent, type NotifAgentOptions, type SSEMessagePayload, type StateChangePayload, type TransportType, NotifAgent as default };