@99xio/xians-sdk-typescript/dist/AgentSDK.d.ts

A lightweight, framework-agnostic SDK for Agent WebSocket/SignalR communication

import { HubEvents } from './core/Hub';
import type { Settings } from './core/types';
import type { Agent } from './core/types';
/**
 * Chat message structure for regular conversation messages
 */
export interface ChatMessageData {
    workflowId: string;
    text: string;
    direction: 'Incoming' | 'Outgoing';
    timestamp: Date;
    threadId: string;
    data?: any;
    isHistorical: boolean;
}
/**
 * Handoff message structure for agent-to-agent transitions
 */
export interface HandoffMessage {
    workflowId: string;
    text: string;
    direction: 'Incoming' | 'Outgoing';
    timestamp: Date;
    threadId: string;
    data?: any;
    isHistorical: boolean;
}
/**
 * Options required to initialize the AgentSDK.
 * These correspond 1-to-1 with the SettingsContext data that the app already uses.
 */
export interface AgentSDKOptions extends Settings {
}
/**
 * A thin, ergonomic facade over WebSocketHub.
 *
 * The goal is to hide the complexity of SignalR / WebSocket logic while still
 * exposing the most common actions an integrating app needs:
 *   1. connect / disconnect
 *   2. send chat or data messages to a specific agent
 *   3. subscribe to high-level events (message, connection_change, error, …)
 */
export declare class AgentSDK {
    #private;
    private hub;
    private initialized;
    private connecting;
    private readonly options;
    private static _hub;
    private static _initPromise;
    constructor(options: AgentSDKOptions);
    /**
     * Establish websocket connections for all configured agents.
     * Safe to call multiple times – subsequent calls become no-ops.
     * Prevents multiple concurrent connection attempts.
     */
    connect(agents: Agent[]): Promise<void>;
    /** Disconnect every active agent connection */
    disconnect(): Promise<void>;
    /**
     * Send a plain-text chat message to the agent identified by `workflowType`.
     */
    sendChat(workflowType: string, text: string, data?: any, overrideDefaultData?: string): Promise<void>;
    /**
     * Send an arbitrary JSON-serialisable payload as a *Data* message.
     */
    sendData(workflowType: string, data: unknown): Promise<void>;
    /**
     * Subscribe to hub-level events in a type-safe manner.
     * Returns an unsubscribe function for convenience.
     */
    on<E extends keyof HubEvents>(event: E, handler: (ev: any) => void): () => void;
    /** Manually remove a subscription created earlier via `on`. */
    off<E extends keyof HubEvents>(event: E, handler: (ev: any) => void): void;
    /** Convenience accessor to inspect current connection states */
    getConnectionStates(): Map<number, import("./core/types").ConnectionState>;
    /** Convenience accessor to retrieve chat history for a given workflow */
    getChatHistory(workflowType: string): import("./core/types").Message[];
    /**
     * Expose hub statistics – handy for debugging dashboards.
     */
    getStats(): {
        connectionStats: [number, import("./core/types").ConnectionState][];
        metadataStats: {
            totalSubscribers: number;
            messageTypes: string[];
            subscribersByType: Record<string, number>;
        };
        eventStats: {
            totalEvents: number;
            totalListeners: number;
            eventStats: Record<string, number>;
        };
    };
    /**
     * Retrieve connection information for a specific agent workflow.
     */
    getAgentConnectionStateByWorkflowType(workflowType: string): import("./core/types").ConnectionState | undefined;
    /**
     * Refresh thread history for a specific workflow by requesting it from the server.
     * Returns true if the request was successful, false otherwise.
     */
    refreshThreadHistory(workflowType: string): Promise<boolean>;
    /**
     * Subscribe to *data* messages coming from the backend.
     * This allows you to receive both Chat and Data message types from agents.
     */
    subscribeToData(subscriberId: string, messageTypes: string[], callback: (msg: any) => void): () => void;
    /** Unsubscribe from data messages by subscriber ID. */
    unsubscribeFromData(subscriberId: string): void;
    /**
     * Subscribe specifically to chat messages.
     * This provides a dedicated channel for handling regular conversation messages.
     *
     * @param callback - Function called when a chat message is received
     * @returns Unsubscribe function
     */
    subscribeToChatMessages(callback: (chat: ChatMessageData) => void): () => void;
    /**
     * Subscribe specifically to handoff messages.
     * This provides a dedicated channel for handling agent-to-agent handoffs.
     *
     * @param callback - Function called when a handoff message is received
     * @returns Unsubscribe function
     */
    subscribeToHandoffs(callback: (handoff: HandoffMessage) => void): () => void;
    /**
     * Initialise a shared singleton instance. Subsequent calls return the first
     * instance that was created, ignoring the provided options (they should be
     * identical across the app anyway).
     */
    static initShared(options: AgentSDKOptions): AgentSDK;
    /** Obtain the previously-initialised shared instance. */
    static getShared(): AgentSDK;
    /**
     * Reset the shared instance - useful for testing or hot reloads
     */
    static resetShared(): void;
    /**
     * Get connection status for debugging
     */
    getConnectionStatus(): {
        initialized: boolean;
        connecting: boolean;
        hasSharedInstance: boolean;
        hasHub: boolean;
        connectionStates: Map<number, import("./core/types").ConnectionState>;
    };
}
export default AgentSDK;
//# sourceMappingURL=AgentSDK.d.ts.map