@openserv-labs/sdk 1.8.2 → 2.0.0

package/dist/tunnel.d.ts

@@ -0,0 +1,189 @@
+/**
+ * All possible states for the tunnel connection.
+ */
+export type TunnelState = 'idle' | 'starting' | 'connecting' | 'authenticating' | 'connected' | 'awaiting_reconnect_ack' | 'reconnect_delay' | 'stopping' | 'failed' | 'stopped';
+/**
+ * Events that can trigger state transitions.
+ */
+export type TunnelEvent = 'START' | 'SETUP_COMPLETE' | 'SETUP_FAILED' | 'STOP' | 'CLEANUP_COMPLETE' | 'GRACEFUL_RECONNECT' | 'WS_OPEN' | 'WS_CLOSE' | 'WS_ERROR' | 'AUTH_SUCCESS' | 'AUTH_ERROR' | 'RECONNECT_ACK' | 'DELAY_COMPLETE' | 'ACK_TIMEOUT' | 'MAX_RETRIES';
+export interface RequestData {
+    id: string;
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface ResponseData {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+export interface OpenServTunnelOptions {
+    /**
+     * The OpenServ API key for authentication.
+     * Required unless OPENSERV_API_KEY environment variable is set.
+     */
+    apiKey?: string;
+    /**
+     * The proxy server URL.
+     * Defaults to OPENSERV_PROXY_URL env var or 'https://agents-proxy.openserv.ai'
+     */
+    proxyUrl?: string;
+    /**
+     * Called when tunnel is connected/reconnected.
+     */
+    onConnected?: (isReconnect: boolean) => void | Promise<void>;
+    /**
+     * Called when a request is received through the tunnel.
+     */
+    onRequest?: (method: string, path: string) => void;
+    /**
+     * Called when an error occurs.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * OpenServ Tunnel
+ *
+ * Connects local agent servers to the OpenServ proxy service.
+ *
+ * @example
+ * ```typescript
+ * const tunnel = new OpenServTunnel({
+ *   apiKey: process.env.OPENSERV_API_KEY
+ * })
+ *
+ * await tunnel.start(7378)
+ * console.log('Tunnel connected')
+ *
+ * // Later...
+ * await tunnel.stop()
+ * ```
+ */
+export declare class OpenServTunnel {
+    private proxyUrl;
+    private apiKey;
+    private localPort;
+    private ws;
+    private state;
+    private context;
+    private delayTimeoutId;
+    private ackTimeoutId;
+    private pendingStart;
+    private pendingGracefulReconnect;
+    private pendingStop;
+    private onConnected?;
+    private onRequest?;
+    private onError?;
+    constructor(options?: OpenServTunnelOptions);
+    /**
+     * Get the current state of the tunnel.
+     */
+    getState(): TunnelState;
+    /**
+     * Attempt to transition to a new state based on an event.
+     * Returns true if the transition was valid and executed, false otherwise.
+     */
+    private transition;
+    /**
+     * Actions to perform when exiting a state.
+     */
+    private exitState;
+    /**
+     * Actions to perform when entering a state.
+     */
+    private enterState;
+    /**
+     * Entry action for 'starting' state: validate and initialize.
+     * Resets context and validates API key before proceeding to connect.
+     */
+    private doStarting;
+    /**
+     * Entry action for 'connecting' state: create WebSocket connection.
+     */
+    private doConnect;
+    /**
+     * Entry action for 'authenticating' state: send auth message.
+     */
+    private doAuthenticate;
+    /**
+     * Entry action for 'connected' state: resolve promises, call callbacks.
+     */
+    private doConnected;
+    /**
+     * Entry action for 'awaiting_reconnect_ack' state: send will-reconnect and start timeout.
+     */
+    private doAwaitReconnectAck;
+    /**
+     * Entry action for 'reconnect_delay' state: calculate backoff and start timer.
+     */
+    private doReconnectDelay;
+    /**
+     * Entry action for 'stopping' state: clean up resources.
+     * Handles async WebSocket cleanup and transitions to 'stopped' when done.
+     */
+    private doStopping;
+    /**
+     * Entry action for 'failed' state: reject promises, call error callback.
+     */
+    private doFailed;
+    /**
+     * Entry action for 'stopped' state: resolve/reject pending promises.
+     * Cleanup has already been done in 'stopping' state.
+     */
+    private doStopped;
+    /**
+     * Start the tunnel and connect to the proxy.
+     * @param port - The local port to expose
+     */
+    start(port: number): Promise<void>;
+    /**
+     * Stop the tunnel and clean up resources.
+     * Returns a promise that resolves when cleanup is complete.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the tunnel is currently connected and authenticated.
+     * Returns true only after the tunnel has successfully registered with the proxy.
+     */
+    isConnected(): boolean;
+    private setupWebSocket;
+    /**
+     * Handle WebSocket 'open' event - dispatch WS_OPEN event.
+     */
+    private handleWsOpen;
+    /**
+     * Handle WebSocket 'message' event - dispatch appropriate events based on message type.
+     */
+    private handleWsMessage;
+    /**
+     * Handle protocol-level error message from server.
+     */
+    private handleProtocolError;
+    /**
+     * Handle will-reconnect-ack message from server.
+     */
+    private handleReconnectAck;
+    /**
+     * Handle incoming request through the tunnel.
+     */
+    private handleRequest;
+    /**
+     * Handle WebSocket 'close' event - dispatch WS_CLOSE event.
+     */
+    private handleWsClose;
+    /**
+     * Handle WebSocket 'error' event - dispatch WS_ERROR event (informational).
+     */
+    private handleWsError;
+    private logTunnelError;
+    private logConnectionErrorHint;
+    private forwardRequest;
+    /**
+     * Initiate a graceful reconnection to the proxy server.
+     * This notifies the server before disconnecting, allowing it to buffer requests.
+     * Returns a promise that resolves when the reconnection is complete.
+     */
+    gracefulReconnect(): Promise<void>;
+}
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/tunnel.d.ts.map

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