API Reference - HAIProtocol (HAIP)

New protocol version released: This page may contain outdated information.

Complete reference documentation for all HAIP SDK classes, interfaces, and functions.

Core Exports

createHAIPClient()

Factory function to create a HAIP client instance.

function createHAIPClient(config: HAIPClientConfig): HAIPClient;

config

HAIPClientConfig

required

Client configuration object.

Returns: HAIPClient - Configured client instance Example:

import { createHAIPClient } from "haip-sdk";

const client = createHAIPClient({
  url: "ws://localhost:8080",
  token: "your-jwt-token",
  transport: "websocket",
});

Types

HAIPClientConfig

Configuration for creating a HAIP client.

interface HAIPClientConfig {
  url: string;
  token: string;
  transport?: "websocket" | "sse" | "http-streaming";
  flowControl?: HAIPFlowControlConfig;
  maxConcurrentRuns?: number;
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  heartbeatInterval?: number;
  options?:
    | WebSocketTransportOptions
    | SSETransportOptions
    | HTTPStreamingTransportOptions;
}

HAIPFlowControlConfig

Flow control configuration.

interface HAIPFlowControlConfig {
  initialCredits?: number;
  initialCreditBytes?: number;
  maxCredits?: number;
  maxCreditBytes?: number;
}

HAIPMessage

Core message interface for all HAI Protocol messages.

interface HAIPMessage {
  type: HAIPEventType;
  payload: any;
  envelope?: HAIPEnvelope;
}

HAIPEnvelope

Message envelope containing metadata.

interface HAIPEnvelope {
  session_id?: string;
  run_id?: string;
  thread_id?: string;
  channel?: HAIPChannel;
  sequence?: string;
  timestamp?: string;
  ack?: string;
}

HAIPEventType

All supported HAIP event types.

type HAIPEventType =
  | "HAI" // Handshake
  | "PING" // Heartbeat ping
  | "PONG" // Heartbeat pong
  | "RUN_STARTED" // Run started
  | "RUN_FINISHED" // Run finished
  | "RUN_CANCEL" // Run cancelled
  | "RUN_ERROR" // Run error
  | "MESSAGE_START" // Text message start
  | "MESSAGE_PART" // Text message part
  | "MESSAGE_END" // Text message end
  | "AUDIO_CHUNK" // Audio data chunk
  | "TOOL_CALL" // Tool call
  | "TOOL_UPDATE" // Tool update
  | "TOOL_DONE" // Tool completed
  | "TOOL_CANCEL" // Tool cancelled
  | "TOOL_LIST" // Tool list
  | "TOOL_SCHEMA" // Tool schema
  | "FLOW_UPDATE" // Flow control update
  | "PAUSE_CHANNEL" // Pause channel
  | "RESUME_CHANNEL" // Resume channel
  | "REPLAY_REQUEST" // Replay request
  | "ERROR"; // Error message

HAIPChannel

Supported message channels.

type HAIPChannel = "USER" | "AGENT" | "SYSTEM" | "AUDIO_IN" | "AUDIO_OUT";

Client Interface

HAIPClient

Main client interface for HAI Protocol communication.

interface HAIPClient extends EventEmitter {
  // Connection Management
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  isConnected(): boolean;

  // Run Management
  startRun(threadId?: string, metadata?: Record<string, any>): Promise<string>;
  finishRun(
    runId: string,
    status?: "OK" | "CANCELLED" | "ERROR",
    summary?: string
  ): Promise<void>;
  cancelRun(runId: string): Promise<void>;

  // Messaging
  sendTextMessage(
    channel: HAIPChannel,
    text: string,
    author?: string,
    runId?: string,
    threadId?: string
  ): Promise<string>;
  sendMessage(
    message: HAIPMessage,
    options?: HAIPMessageOptions
  ): Promise<void>;
  sendBinary(data: ArrayBuffer): Promise<void>;

  // Tool Integration
  callTool(
    channel: HAIPChannel,
    tool: string,
    params?: Record<string, any>,
    runId?: string,
    threadId?: string
  ): Promise<string>;
  updateTool(
    channel: HAIPChannel,
    callId: string,
    status: "QUEUED" | "RUNNING" | "CANCELLING",
    progress?: number,
    partial?: any,
    runId?: string,
    threadId?: string
  ): Promise<void>;
  completeTool(
    channel: HAIPChannel,
    callId: string,
    status?: "OK" | "CANCELLED" | "ERROR",
    result?: any,
    runId?: string,
    threadId?: string
  ): Promise<void>;
  cancelTool(
    channel: HAIPChannel,
    callId: string,
    reason?: string,
    runId?: string,
    threadId?: string
  ): Promise<void>;
  listTools(
    channel: HAIPChannel,
    tools: HAIPTool[],
    runId?: string,
    threadId?: string
  ): Promise<void>;
  getToolSchema(
    channel: HAIPChannel,
    tool: string,
    runId?: string,
    threadId?: string
  ): Promise<void>;

  // Flow Control
  sendFlowUpdate(
    channel: string,
    addMessages?: number,
    addBytes?: number
  ): Promise<void>;
  pauseChannel(channel: string): Promise<void>;
  resumeChannel(channel: string): Promise<void>;

  // Replay
  requestReplay(fromSeq: string, toSeq?: string): Promise<void>;

  // Audio
  sendAudioChunk(
    channel: HAIPChannel,
    messageId: string,
    mime: string,
    data: ArrayBuffer,
    durationMs?: number,
    runId?: string,
    threadId?: string
  ): Promise<void>;

  // State Management
  getConnectionState(): HAIPConnectionState;
  getPerformanceMetrics(): HAIPPerformanceMetrics;
  getActiveRuns(): HAIPRun[];
  getRun(runId: string): HAIPRun | undefined;

  // Events
  on(event: "connect", listener: () => void): this;
  on(event: "disconnect", listener: (reason: string) => void): this;
  on(event: "handshake", listener: (payload: any) => void): this;
  on(event: "message", listener: (message: HAIPMessage) => void): this;
  on(event: "binary", listener: (data: ArrayBuffer) => void): this;
  on(event: "error", listener: (error: Error) => void): this;
}

Transport Interfaces

HAIPTransport

Base transport interface.

interface HAIPTransport extends EventEmitter {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(data: string | ArrayBuffer): Promise<void>;
  isConnected(): boolean;

  on(event: "connect", listener: () => void): this;
  on(event: "disconnect", listener: (reason: string) => void): this;
  on(event: "message", listener: (data: string) => void): this;
  on(event: "binary", listener: (data: ArrayBuffer) => void): this;
  on(event: "error", listener: (error: Error) => void): this;
}

WebSocketTransport

WebSocket transport implementation.

class WebSocketTransport implements HAIPTransport {
  constructor(url: string, token: string, options?: WebSocketTransportOptions);

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(data: string | ArrayBuffer): Promise<void>;
  isConnected(): boolean;
}

SSETransport

Server-Sent Events transport implementation.

class SSETransport implements HAIPTransport {
  constructor(config: HAIPTransportConfig);

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(data: string | ArrayBuffer): Promise<void>;
  isConnected(): boolean;
}

HTTPStreamingTransport

HTTP streaming transport implementation.

class HTTPStreamingTransport implements HAIPTransport {
  constructor(config: HAIPTransportConfig);

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(data: string | ArrayBuffer): Promise<void>;
  isConnected(): boolean;
}

Utility Functions

HAIPUtils

Utility functions for HAI Protocol operations.

class HAIPUtils {
  // Message Creation
  static createMessage(
    type: HAIPEventType,
    payload: any,
    envelope?: HAIPEnvelope
  ): HAIPMessage;
  static createTextMessage(
    channel: HAIPChannel,
    text: string,
    author?: string,
    runId?: string,
    threadId?: string
  ): HAIPMessage;
  static createToolCall(
    channel: HAIPChannel,
    tool: string,
    params?: Record<string, any>,
    runId?: string,
    threadId?: string
  ): HAIPMessage;
  static createFlowUpdate(
    channel: string,
    addMessages?: number,
    addBytes?: number
  ): HAIPMessage;

  // Validation
  static validateMessage(message: HAIPMessage): boolean;
  static validateEnvelope(envelope: HAIPEnvelope): boolean;

  // Generation
  static generateUUID(): string;
  static generateTimestamp(): string;
  static generateSequenceNumber(): string;

  // Parsing
  static parseJWT(token: string): any;
  static parseBase64(data: string): ArrayBuffer;
  static encodeBase64(data: ArrayBuffer): string;

  // Flow Control
  static calculateMessageCredits(message: HAIPMessage): number;
  static calculateByteCredits(data: ArrayBuffer): number;

  // Binary
  static arrayBufferToBase64(buffer: ArrayBuffer): string;
  static base64ToArrayBuffer(base64: string): ArrayBuffer;
  static stringToArrayBuffer(str: string): ArrayBuffer;
  static arrayBufferToString(buffer: ArrayBuffer): string;

  // Timing
  static debounce<T extends (...args: any[]) => any>(func: T, wait: number): T;
  static throttle<T extends (...args: any[]) => any>(func: T, limit: number): T;

  // Backoff
  static exponentialBackoff(
    attempt: number,
    baseDelay: number,
    maxDelay: number
  ): number;
}

State Interfaces

HAIPConnectionState

Current connection state information.

interface HAIPConnectionState {
  connected: boolean;
  handshakeCompleted: boolean;
  sessionId: string;
  lastAck: string;
  reconnectAttempts: number;
  credits: Map<HAIPChannel, number>;
  byteCredits: Map<HAIPChannel, number>;
}

HAIPPerformanceMetrics

Performance and usage metrics.

interface HAIPPerformanceMetrics {
  messagesSent: number;
  messagesReceived: number;
  bytesSent: number;
  bytesReceived: number;
  connectionTime: number;
  lastUpdated: number;
}

HAIPRun

Run session information.

interface HAIPRun {
  id: string;
  threadId?: string;
  metadata?: Record<string, any>;
  status: "RUNNING" | "FINISHED" | "CANCELLED" | "ERROR";
  startTime: number;
  endTime?: number;
  summary?: string;
}

Tool Interfaces

HAIPTool

Tool definition for MCP integration.

interface HAIPTool {
  name: string;
  description: string;
  parameters?: Record<string, any>;
  returns?: Record<string, any>;
}

HAIPToolCall

Tool call information.

interface HAIPToolCall {
  call_id: string;
  tool: string;
  params?: Record<string, any>;
}

HAIPToolResult

Tool execution result.

interface HAIPToolResult {
  call_id: string;
  status: "OK" | "CANCELLED" | "ERROR";
  result?: any;
  error?: string;
}

Error Types

HAIPError

Base error class for HAIP SDK errors.

class HAIPError extends Error {
  constructor(message: string, code?: string, details?: any);

  code: string;
  details: any;
}

HAIPConnectionError

Connection-related errors.

class HAIPConnectionError extends HAIPError {
  constructor(message: string, details?: any);
}

HAIPAuthenticationError

Authentication-related errors.

class HAIPAuthenticationError extends HAIPError {
  constructor(message: string, details?: any);
}

HAIPFlowControlError

Flow control-related errors.

class HAIPFlowControlError extends HAIPError {
  constructor(message: string, details?: any);
}

Configuration Types

WebSocketTransportOptions

WebSocket-specific configuration options.

interface WebSocketTransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  heartbeatInterval?: number;
  binaryType?: "arraybuffer" | "blob";
}

SSETransportOptions

SSE-specific configuration options.

interface SSETransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  withCredentials?: boolean;
  headers?: Record<string, string>;
}

HTTPStreamingTransportOptions

HTTP streaming-specific configuration options.

interface HTTPStreamingTransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  timeout?: number;
  headers?: Record<string, string>;
}

Event Types

HAIPClientEvents

Events emitted by the HAIP client.

interface HAIPClientEvents {
  connect: () => void;
  disconnect: (reason: string) => void;
  handshake: (payload: any) => void;
  message: (message: HAIPMessage) => void;
  binary: (data: ArrayBuffer) => void;
  error: (error: Error) => void;
}

HAIPTransportEvents

Events emitted by transport implementations.

interface HAIPTransportEvents {
  connect: () => void;
  disconnect: (reason: string) => void;
  message: (data: string) => void;
  binary: (data: ArrayBuffer) => void;
  error: (error: Error) => void;
}

Constants

HAIPConstants

Protocol constants and default values.

const HAIPConstants = {
  PROTOCOL_VERSION: "1.1.2",
  DEFAULT_CREDITS: 10,
  DEFAULT_CREDIT_BYTES: 1024 * 1024,
  DEFAULT_HEARTBEAT_INTERVAL: 30000,
  DEFAULT_RECONNECT_DELAY: 1000,
  DEFAULT_MAX_RECONNECT_ATTEMPTS: 5,
  DEFAULT_MAX_CONCURRENT_RUNS: 5,
  WEBSOCKET_READY_STATE: {
    CONNECTING: 0,
    OPEN: 1,
    CLOSING: 2,
    CLOSED: 3,
  },
} as const;

Next Steps

Client API

Learn about the client interface and methods.

Examples

See practical examples of API usage.

Types

Explore detailed type definitions.

Utilities

Learn about utility functions and helpers.

​Core Exports

​createHAIPClient()

​Types

​HAIPClientConfig

​HAIPFlowControlConfig

​HAIPMessage

​HAIPEnvelope

​HAIPEventType

​HAIPChannel

​Client Interface

​HAIPClient

​Transport Interfaces

​HAIPTransport

​WebSocketTransport

​SSETransport

​HTTPStreamingTransport

​Utility Functions

​HAIPUtils

​State Interfaces

​HAIPConnectionState

​HAIPPerformanceMetrics

​HAIPRun

​Tool Interfaces

​HAIPTool

​HAIPToolCall

​HAIPToolResult

​Error Types

​HAIPError

​HAIPConnectionError

​HAIPAuthenticationError

​HAIPFlowControlError

​Configuration Types

​WebSocketTransportOptions

​SSETransportOptions

​HTTPStreamingTransportOptions

​Event Types

​HAIPClientEvents

​HAIPTransportEvents

​Constants

​HAIPConstants

​Next Steps

Client API

Examples

Types

Utilities

Core Exports

createHAIPClient()

Types

HAIPClientConfig

HAIPFlowControlConfig

HAIPMessage

HAIPEnvelope

HAIPEventType

HAIPChannel

Client Interface

HAIPClient

Transport Interfaces

HAIPTransport

WebSocketTransport

SSETransport

HTTPStreamingTransport

Utility Functions

HAIPUtils

State Interfaces

HAIPConnectionState

HAIPPerformanceMetrics

HAIPRun

Tool Interfaces

HAIPTool

HAIPToolCall

HAIPToolResult

Error Types

HAIPError

HAIPConnectionError

HAIPAuthenticationError

HAIPFlowControlError

Configuration Types

WebSocketTransportOptions

SSETransportOptions

HTTPStreamingTransportOptions

Event Types

HAIPClientEvents

HAIPTransportEvents

Constants

HAIPConstants

Next Steps