@sygnl/talon 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,242 @@
+/**
+ * Message sent TO the edge
+ */
+interface OutboundMessage {
+    /** Message type/event name */
+    type: string;
+    /** Message payload */
+    data: Record<string, unknown>;
+    /** Optional message ID for tracking */
+    id?: string;
+    /** Timestamp */
+    timestamp?: number;
+}
+/**
+ * Message received FROM the edge
+ */
+interface InboundMessage {
+    /** Message type/event name */
+    type: string;
+    /** Message payload */
+    data: Record<string, unknown>;
+    /** Optional message ID */
+    id?: string;
+    /** Timestamp */
+    timestamp?: number;
+}
+/**
+ * Transport connection state
+ */
+type TransportState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Transport interface - all transports must implement this
+ */
+interface TalonTransport {
+    /**
+     * Current connection state
+     */
+    readonly state: TransportState;
+    /**
+     * Connect to the transport
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the transport
+     */
+    disconnect(): void;
+    /**
+     * Send a message to the edge
+     * @param message - Message to send
+     */
+    send(message: OutboundMessage): Promise<void>;
+    /**
+     * Subscribe to messages from the edge
+     * @param handler - Function to call when message received
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    /**
+     * Subscribe to connection state changes
+     * @param handler - Function to call when state changes
+     * @returns Unsubscribe function
+     */
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    /**
+     * Subscribe to errors
+     * @param handler - Function to call when error occurs
+     * @returns Unsubscribe function
+     */
+    onError(handler: (error: Error) => void): () => void;
+}
+
+/**
+ * WebSocket transport options
+ */
+interface WebSocketTransportOptions {
+    /** WebSocket URL */
+    url: string;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
+    reconnectDelay?: number;
+    /** Max reconnect attempts (0 = infinite) */
+    maxReconnectAttempts?: number;
+    /** Connection timeout in ms */
+    connectionTimeout?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * WebSocket transport for bidirectional communication
+ *
+ * Features:
+ * - Real-time bidirectional communication
+ * - Auto-reconnect with exponential backoff
+ * - Connection state management
+ * - Message queuing during disconnection
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketTransport({
+ *   url: 'wss://edge.sygnl.io',
+ *   autoReconnect: true
+ * });
+ * ```
+ */
+declare class WebSocketTransport implements TalonTransport {
+    private url;
+    private ws;
+    private _state;
+    private autoReconnect;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private connectionTimeout;
+    private debug;
+    private messageHandlers;
+    private stateHandlers;
+    private errorHandlers;
+    private messageQueue;
+    constructor(options: WebSocketTransportOptions);
+    get state(): TransportState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(message: OutboundMessage): Promise<void>;
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Handle WebSocket disconnect
+     */
+    private handleDisconnect;
+    /**
+     * Schedule reconnection attempt with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Flush queued messages
+     */
+    private flushMessageQueue;
+    /**
+     * Set connection state
+     */
+    private setState;
+    /**
+     * Emit error to handlers
+     */
+    private emitError;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/**
+ * Webhook transport options
+ */
+interface WebhookTransportOptions {
+    /** Webhook URL */
+    url: string;
+    /** HTTP method */
+    method?: 'POST' | 'PUT';
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Retry failed requests */
+    retry?: boolean;
+    /** Max retry attempts */
+    maxRetries?: number;
+    /** Retry delay in ms */
+    retryDelay?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Webhook transport for fire-and-forget HTTP requests
+ *
+ * Features:
+ * - One-way communication (no responses)
+ * - HTTP POST/PUT requests
+ * - Optional retry logic
+ * - Custom headers support
+ *
+ * Use this for:
+ * - Server-side event delivery
+ * - Fire-and-forget scenarios
+ * - When WebSocket not available/needed
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebhookTransport({
+ *   url: 'https://edge.sygnl.io/webhook',
+ *   method: 'POST',
+ *   retry: true
+ * });
+ * ```
+ */
+declare class WebhookTransport implements TalonTransport {
+    private url;
+    private method;
+    private headers;
+    private timeout;
+    private retry;
+    private maxRetries;
+    private retryDelay;
+    private debug;
+    private _state;
+    private messageHandlers;
+    private stateHandlers;
+    private errorHandlers;
+    constructor(options: WebhookTransportOptions);
+    get state(): TransportState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(message: OutboundMessage): Promise<void>;
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Send HTTP request
+     */
+    private sendRequest;
+    /**
+     * Set connection state
+     */
+    private setState;
+    /**
+     * Emit error to handlers
+     */
+    private emitError;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+export { WebSocketTransport, type WebSocketTransportOptions, WebhookTransport, type WebhookTransportOptions };

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Message sent TO the edge
+ */
+interface OutboundMessage {
+    /** Message type/event name */
+    type: string;
+    /** Message payload */
+    data: Record<string, unknown>;
+    /** Optional message ID for tracking */
+    id?: string;
+    /** Timestamp */
+    timestamp?: number;
+}
+/**
+ * Message received FROM the edge
+ */
+interface InboundMessage {
+    /** Message type/event name */
+    type: string;
+    /** Message payload */
+    data: Record<string, unknown>;
+    /** Optional message ID */
+    id?: string;
+    /** Timestamp */
+    timestamp?: number;
+}
+/**
+ * Transport connection state
+ */
+type TransportState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Transport interface - all transports must implement this
+ */
+interface TalonTransport {
+    /**
+     * Current connection state
+     */
+    readonly state: TransportState;
+    /**
+     * Connect to the transport
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the transport
+     */
+    disconnect(): void;
+    /**
+     * Send a message to the edge
+     * @param message - Message to send
+     */
+    send(message: OutboundMessage): Promise<void>;
+    /**
+     * Subscribe to messages from the edge
+     * @param handler - Function to call when message received
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    /**
+     * Subscribe to connection state changes
+     * @param handler - Function to call when state changes
+     * @returns Unsubscribe function
+     */
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    /**
+     * Subscribe to errors
+     * @param handler - Function to call when error occurs
+     * @returns Unsubscribe function
+     */
+    onError(handler: (error: Error) => void): () => void;
+}
+
+/**
+ * WebSocket transport options
+ */
+interface WebSocketTransportOptions {
+    /** WebSocket URL */
+    url: string;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
+    reconnectDelay?: number;
+    /** Max reconnect attempts (0 = infinite) */
+    maxReconnectAttempts?: number;
+    /** Connection timeout in ms */
+    connectionTimeout?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * WebSocket transport for bidirectional communication
+ *
+ * Features:
+ * - Real-time bidirectional communication
+ * - Auto-reconnect with exponential backoff
+ * - Connection state management
+ * - Message queuing during disconnection
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketTransport({
+ *   url: 'wss://edge.sygnl.io',
+ *   autoReconnect: true
+ * });
+ * ```
+ */
+declare class WebSocketTransport implements TalonTransport {
+    private url;
+    private ws;
+    private _state;
+    private autoReconnect;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private connectionTimeout;
+    private debug;
+    private messageHandlers;
+    private stateHandlers;
+    private errorHandlers;
+    private messageQueue;
+    constructor(options: WebSocketTransportOptions);
+    get state(): TransportState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(message: OutboundMessage): Promise<void>;
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Handle WebSocket disconnect
+     */
+    private handleDisconnect;
+    /**
+     * Schedule reconnection attempt with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Flush queued messages
+     */
+    private flushMessageQueue;
+    /**
+     * Set connection state
+     */
+    private setState;
+    /**
+     * Emit error to handlers
+     */
+    private emitError;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/**
+ * Webhook transport options
+ */
+interface WebhookTransportOptions {
+    /** Webhook URL */
+    url: string;
+    /** HTTP method */
+    method?: 'POST' | 'PUT';
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Retry failed requests */
+    retry?: boolean;
+    /** Max retry attempts */
+    maxRetries?: number;
+    /** Retry delay in ms */
+    retryDelay?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Webhook transport for fire-and-forget HTTP requests
+ *
+ * Features:
+ * - One-way communication (no responses)
+ * - HTTP POST/PUT requests
+ * - Optional retry logic
+ * - Custom headers support
+ *
+ * Use this for:
+ * - Server-side event delivery
+ * - Fire-and-forget scenarios
+ * - When WebSocket not available/needed
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebhookTransport({
+ *   url: 'https://edge.sygnl.io/webhook',
+ *   method: 'POST',
+ *   retry: true
+ * });
+ * ```
+ */
+declare class WebhookTransport implements TalonTransport {
+    private url;
+    private method;
+    private headers;
+    private timeout;
+    private retry;
+    private maxRetries;
+    private retryDelay;
+    private debug;
+    private _state;
+    private messageHandlers;
+    private stateHandlers;
+    private errorHandlers;
+    constructor(options: WebhookTransportOptions);
+    get state(): TransportState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(message: OutboundMessage): Promise<void>;
+    onMessage(handler: (message: InboundMessage) => void): () => void;
+    onStateChange(handler: (state: TransportState) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Send HTTP request
+     */
+    private sendRequest;
+    /**
+     * Set connection state
+     */
+    private setState;
+    /**
+     * Emit error to handlers
+     */
+    private emitError;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+export { WebSocketTransport, type WebSocketTransportOptions, WebhookTransport, type WebhookTransportOptions };