API Reference

function createHAIPClient(config: HAIPClientConfig): HAIPClient;

import { createHAIPClient } from "haip-sdk";

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

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;
}

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

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

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

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

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

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;
}

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;
}

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;
}

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

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

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

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

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;
}

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

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

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

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

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

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

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

  code: string;
  details: any;
}

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

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

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

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

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

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

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

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

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;