Skip to main content
Version: 3.2.x

Overview

The Optave JavaScript SDK (@optave/client-sdk) is a production-ready library designed to facilitate real-time communication between your application and Optave's AI-powered backend services via WebSocket connections. It provides a robust, secure, and type-safe way to authenticate, manage connections, handle AI-powered interactions, and process responses with ease.

Key Features​

  • WebSocket-First Architecture: Real-time bidirectional communication with request-response correlation via correlationId
  • Dual Authentication Patterns: OAuth2 client credentials for servers, token provider pattern for browsers
  • Multi-Build Support: Optimized builds for browser (ESM/UMD) and server (ESM/UMD) environments with CSP compliance
  • Event-Driven Architecture: Leverages Node.js EventEmitter for flexible asynchronous event handling
  • Type-Safe: Full TypeScript support with generated types from AsyncAPI specification
  • Structured Error Handling: Categorized errors (AUTHENTICATION, VALIDATION, ORCHESTRATOR, WEBSOCKET) with recovery suggestions
  • Schema Validation: Optional AJV-based validation (server builds) with CSP-safe fallback (browser builds)
  • Security-First Design: Client secrets never exposed in browser builds, subprotocol authentication support
  • Production-Ready: Built-in connection timeout, request timeout, automatic correlation, and payload size enforcement (128KB limit)

Communication Protocol​

The SDK uses WebSocket Secure (WSS) as the exclusive communication protocol. All messages are sent over a single persistent WebSocket connection with:

  • JSON message envelopes containing headers and structured payloads
  • Request-response correlation via UUIDv7 correlation IDs
  • Real-time bidirectional messaging for AI operations (adjust, summarize, translate, recommend, insights, etc.)
  • Automatic message routing based on action types and schema references

Multi-Build Support​

The SDK provides four optimized builds (Browser ESM/UMD, Server ESM/UMD) for different deployment scenarios. Browser builds exclude client secrets for security, while server builds support OAuth2 client credentials flow.

See Installation & Configuration for detailed build information, usage examples, and framework-specific integration guides.