@teneo-protocol/sdk 1.0.0

package/dist/constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Timeout constants for various SDK operations
+ */
+export declare const TIMEOUTS: {
+    /** Wait time for cached auth response */
+    readonly CACHED_AUTH_WAIT: 1000;
+    /** WebSocket ping interval */
+    readonly PING_INTERVAL: 30000;
+    /** Default message response timeout */
+    readonly DEFAULT_MESSAGE_TIMEOUT: 30000;
+    /** Authentication timeout */
+    readonly AUTH_TIMEOUT: 30000;
+    /** Initial connection timeout */
+    readonly CONNECTION_TIMEOUT: 30000;
+    /** Webhook delivery timeout */
+    readonly WEBHOOK_TIMEOUT: 10000;
+    /** Auth state polling interval */
+    readonly AUTH_POLL_INTERVAL: 100;
+};
+/**
+ * Retry and backoff constants
+ */
+export declare const RETRY: {
+    /** Base delay for exponential backoff */
+    readonly BASE_DELAY: 1000;
+    /** Maximum retry delay */
+    readonly MAX_DELAY: 30000;
+    /** Maximum webhook retry delay */
+    readonly MAX_WEBHOOK_DELAY: 30000;
+    /** Maximum reconnection delay */
+    readonly MAX_RECONNECT_DELAY: 60000;
+};
+/**
+ * Limits and constraints
+ */
+export declare const LIMITS: {
+    /** Maximum message size (2MB) */
+    readonly MAX_MESSAGE_SIZE: number;
+    /** Random jitter for reconnection */
+    readonly MAX_JITTER: 1000;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,QAAQ;IACnB,yCAAyC;;IAEzC,8BAA8B;;IAE9B,uCAAuC;;IAEvC,6BAA6B;;IAE7B,iCAAiC;;IAEjC,+BAA+B;;IAE/B,kCAAkC;;CAE1B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,KAAK;IAChB,yCAAyC;;IAEzC,0BAA0B;;IAE1B,kCAAkC;;IAElC,iCAAiC;;CAEzB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB,iCAAiC;;IAEjC,qCAAqC;;CAE7B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIMITS = exports.RETRY = exports.TIMEOUTS = void 0;
+/**
+ * Timeout constants for various SDK operations
+ */
+exports.TIMEOUTS = {
+    /** Wait time for cached auth response */
+    CACHED_AUTH_WAIT: 1000,
+    /** WebSocket ping interval */
+    PING_INTERVAL: 30000,
+    /** Default message response timeout */
+    DEFAULT_MESSAGE_TIMEOUT: 30000,
+    /** Authentication timeout */
+    AUTH_TIMEOUT: 30000,
+    /** Initial connection timeout */
+    CONNECTION_TIMEOUT: 30000,
+    /** Webhook delivery timeout */
+    WEBHOOK_TIMEOUT: 10000,
+    /** Auth state polling interval */
+    AUTH_POLL_INTERVAL: 100
+};
+/**
+ * Retry and backoff constants
+ */
+exports.RETRY = {
+    /** Base delay for exponential backoff */
+    BASE_DELAY: 1000,
+    /** Maximum retry delay */
+    MAX_DELAY: 30000,
+    /** Maximum webhook retry delay */
+    MAX_WEBHOOK_DELAY: 30000,
+    /** Maximum reconnection delay */
+    MAX_RECONNECT_DELAY: 60000
+};
+/**
+ * Limits and constraints
+ */
+exports.LIMITS = {
+    /** Maximum message size (2MB) */
+    MAX_MESSAGE_SIZE: 2 * 1024 * 1024,
+    /** Random jitter for reconnection */
+    MAX_JITTER: 1000
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACU,QAAA,QAAQ,GAAG;IACtB,yCAAyC;IACzC,gBAAgB,EAAE,IAAI;IACtB,8BAA8B;IAC9B,aAAa,EAAE,KAAM;IACrB,uCAAuC;IACvC,uBAAuB,EAAE,KAAM;IAC/B,6BAA6B;IAC7B,YAAY,EAAE,KAAM;IACpB,iCAAiC;IACjC,kBAAkB,EAAE,KAAM;IAC1B,+BAA+B;IAC/B,eAAe,EAAE,KAAM;IACvB,kCAAkC;IAClC,kBAAkB,EAAE,GAAG;CACf,CAAC;AAEX;;GAEG;AACU,QAAA,KAAK,GAAG;IACnB,yCAAyC;IACzC,UAAU,EAAE,IAAI;IAChB,0BAA0B;IAC1B,SAAS,EAAE,KAAM;IACjB,kCAAkC;IAClC,iBAAiB,EAAE,KAAM;IACzB,iCAAiC;IACjC,mBAAmB,EAAE,KAAM;CACnB,CAAC;AAEX;;GAEG;AACU,QAAA,MAAM,GAAG;IACpB,iCAAiC;IACjC,gBAAgB,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;IACjC,qCAAqC;IACrC,UAAU,EAAE,IAAI;CACR,CAAC"}

package/dist/core/websocket-client.d.ts

@@ -0,0 +1,261 @@
+/**
+ * WebSocket client implementation for Teneo Protocol SDK
+ * Handles connection, authentication, and message management with Zod validation
+ */
+import { EventEmitter } from "eventemitter3";
+import { SDKConfig, ConnectionState, AuthenticationState, BaseMessage } from "../types";
+import { SDKEvents } from "../types/events";
+export declare class WebSocketClient extends EventEmitter<SDKEvents> {
+    private ws?;
+    private config;
+    private logger;
+    private account?;
+    private secureKey?;
+    private ownsSecureKey;
+    private handlerRegistry;
+    private rateLimiter?;
+    private signatureVerifier?;
+    private deduplicationCache?;
+    private reconnectPolicy;
+    private roomManager?;
+    private connectionState;
+    private authState;
+    private messageQueue;
+    private pendingMessages;
+    private reconnectTimer?;
+    private pingTimer?;
+    private connectionTimer?;
+    constructor(config: SDKConfig);
+    /**
+     * Set the RoomManager instance for handler context
+     * Called by TeneoSDK after initialization
+     */
+    setRoomManager(roomManager: any): void;
+    /**
+     * Establishes a WebSocket connection to the Teneo server.
+     * Handles connection timeout, authentication challenge-response flow,
+     * and automatic message queue processing after successful connection.
+     * Emits 'connection:open', 'auth:challenge', 'auth:success', and 'ready' events.
+     *
+     * @returns Promise that resolves when connection and authentication are complete
+     * @throws {TimeoutError} If connection times out (default: 30 seconds)
+     * @throws {ConnectionError} If WebSocket connection fails
+     * @throws {AuthenticationError} If authentication fails or times out
+     *
+     * @example
+     * ```typescript
+     * const wsClient = new WebSocketClient(config);
+     * await wsClient.connect();
+     * console.log('Connected and authenticated');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the WebSocket server and cleans up all resources.
+     * Stops reconnection attempts, clears all timers, rejects pending messages,
+     * and updates connection state. Emits 'disconnect' event.
+     *
+     * @example
+     * ```typescript
+     * wsClient.disconnect();
+     * console.log('Disconnected from server');
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * Sends a message to the WebSocket server with validation and queueing support.
+     * Validates message with Zod schema, enforces size limits, and queues messages
+     * during reconnection. Adds timestamp if not present. Emits 'message:sent' event.
+     *
+     * @param message - The message to send
+     * @returns Promise that resolves when message is sent successfully
+     * @throws {ValidationError} If message fails Zod validation
+     * @throws {MessageError} If message size exceeds limit
+     * @throws {ConnectionError} If not connected and reconnection is disabled
+     *
+     * @example
+     * ```typescript
+     * const message = createUserMessage('Hello', 'general', walletAddress);
+     * await wsClient.sendMessage(message);
+     * console.log('Message sent');
+     * ```
+     */
+    sendMessage(message: BaseMessage): Promise<void>;
+    /**
+     * Sends a message and waits for a response with the same message ID.
+     * Implements request-response pattern over WebSocket with timeout support.
+     * Message is automatically assigned a unique ID for correlation.
+     *
+     * @template T - Expected response type
+     * @param message - The message to send
+     * @param timeout - Optional timeout in milliseconds (default: from config or 60000)
+     * @returns Promise that resolves with the response message
+     * @throws {TimeoutError} If response is not received within timeout
+     * @throws {ValidationError} If message fails validation
+     * @throws {MessageError} If message sending fails
+     *
+     * @example
+     * ```typescript
+     * const requestMessage = createRequestChallenge('user', walletAddress);
+     * const response = await wsClient.sendMessageWithResponse(requestMessage, 30000);
+     * console.log('Response received:', response);
+     * ```
+     */
+    sendMessageWithResponse<T = any>(message: BaseMessage, timeout?: number): Promise<T>;
+    /**
+     * Authenticate with the server
+     */
+    private authenticate;
+    /**
+     * Create handler context with all dependencies
+     */
+    private createHandlerContext;
+    /**
+     * Handle incoming messages using the handler registry
+     */
+    private handleMessage;
+    /**
+     * Verify message signature if signature verification is enabled (SEC-2)
+     * Returns true if message should be processed, false if it should be rejected
+     */
+    private verifyMessageSignature;
+    /**
+     * Handle reconnection logic with configurable retry strategy (REL-3)
+     */
+    private handleReconnection;
+    /**
+     * Calculate reconnection delay using retry policy (REL-3)
+     */
+    private calculateReconnectDelay;
+    /**
+     * Start ping interval to keep connection alive
+     */
+    private startPingInterval;
+    /**
+     * Stop ping interval
+     */
+    private stopPingInterval;
+    /**
+     * Process queued messages after reconnection
+     */
+    private processMessageQueue;
+    /**
+     * Update connection state with validation
+     */
+    private updateConnectionState;
+    /**
+     * Update authentication state with validation
+     */
+    private updateAuthState;
+    /**
+     * Create default logger using pino
+     */
+    private createDefaultLogger;
+    /**
+     * Quick check for whether the WebSocket connection is currently active.
+     * This getter provides immediate connection status without full state details.
+     *
+     * @returns True if WebSocket is connected, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (wsClient.isConnected) {
+     *   await wsClient.sendMessage(message);
+     * }
+     * ```
+     */
+    get isConnected(): boolean;
+    /**
+     * Quick check for whether authentication is complete.
+     * This getter provides immediate authentication status without full state details.
+     *
+     * @returns True if authenticated, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (wsClient.isAuthenticated) {
+     *   console.log('Ready to communicate with agents');
+     * }
+     * ```
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Gets a copy of the current connection state including detailed status information.
+     * Returns a shallow copy to prevent external modification of internal state.
+     *
+     * @returns Copy of connection state with connection status, reconnection info, and timestamps
+     *
+     * @example
+     * ```typescript
+     * const state = wsClient.getConnectionState();
+     * console.log(`Connected: ${state.connected}`);
+     * console.log(`Reconnecting: ${state.reconnecting}`);
+     * console.log(`Attempts: ${state.reconnectAttempts}`);
+     * ```
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Gets a copy of the current authentication state including wallet and room information.
+     * Returns a shallow copy to prevent external modification of internal state.
+     *
+     * @returns Copy of authentication state with wallet address, challenge, and room access
+     *
+     * @example
+     * ```typescript
+     * const authState = wsClient.getAuthState();
+     * console.log(`Authenticated: ${authState.authenticated}`);
+     * console.log(`Wallet: ${authState.walletAddress}`);
+     * console.log(`Rooms: ${authState.rooms?.length}`);
+     * ```
+     */
+    getAuthState(): AuthenticationState;
+    /**
+     * Gets the current rate limiter status including available tokens and configuration.
+     * Useful for monitoring rate limiting behavior and detecting potential throttling.
+     * Returns undefined if rate limiting is not configured.
+     *
+     * @returns Rate limiter status object, or undefined if not configured
+     * @returns {number} returns.availableTokens - Tokens currently available for consumption
+     * @returns {number} returns.tokensPerSecond - Configured rate limit (operations per second)
+     * @returns {number} returns.maxBurst - Maximum burst capacity
+     *
+     * @example
+     * ```typescript
+     * const status = wsClient.getRateLimiterStatus();
+     * if (status) {
+     *   console.log(`Available: ${status.availableTokens}/${status.maxBurst}`);
+     *   console.log(`Rate: ${status.tokensPerSecond}/sec`);
+     * }
+     * ```
+     */
+    getRateLimiterStatus(): {
+        availableTokens: number;
+        tokensPerSecond: number;
+        maxBurst: number;
+    } | undefined;
+    /**
+     * Gets the current message deduplication cache status (CB-4).
+     * Useful for monitoring deduplication behavior and cache health.
+     * Returns undefined if deduplication is not configured.
+     *
+     * @returns Deduplication cache status object, or undefined if not configured
+     * @returns {number} returns.cacheSize - Number of message IDs currently cached
+     * @returns {number} returns.ttl - Time-to-live for cache entries in milliseconds
+     * @returns {number} returns.maxSize - Maximum cache size
+     *
+     * @example
+     * ```typescript
+     * const status = wsClient.getDeduplicationStatus();
+     * if (status) {
+     *   console.log(`Cache: ${status.cacheSize}/${status.maxSize}`);
+     *   console.log(`TTL: ${status.ttl}ms`);
+     * }
+     * ```
+     */
+    getDeduplicationStatus(): {
+        cacheSize: number;
+        ttl: number;
+        maxSize: number;
+    } | undefined;
+}
+//# sourceMappingURL=websocket-client.d.ts.map

package/dist/core/websocket-client.d.ts.map

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