@kivox/client 0.1.0-beta.1

package/README.md

@@ -0,0 +1,91 @@
+# KIVOX JavaScript client
+
+`@kivox/client` is the official JavaScript/TypeScript client for interacting with KIVOX. It provides the necessary abstractions and bindings to handle sessions, real-time events, audio, and communication with agents.
+
+## Features
+
+- Unified client for the Kivox API
+- Conversation and voice session management
+- WebSockets, events, and real-time state
+- Audio recording and playback
+- Strongly typed contracts and types in TypeScript
+- Framework-agnostic (Svelte, React, Angular, Vue, Vanilla, etc.)
+
+## Documentation
+
+<https://kivox.ju4n97.workers.dev/docs/clients/kivox-js>
+
+## Installation
+
+```bash
+# NPM
+npm install @kivox/client
+
+# PNPM
+pnpm add @kivox/client
+
+# Yarn
+yarn add @kivox/client
+
+# Bun
+bun add @kivox/client
+```
+
+## Basic example
+
+```ts
+import { KivoxClient } from '@kivox/client';
+
+const kivox = new KivoxClient({
+  baseUrl: 'http://localhost:8787',
+});
+
+// List agents
+const agents = await kivox.agents.list();
+
+// Connect to an agent
+const session = await kivox.conversations.connect({
+  agentId: '019bb51e-e45f-75e3-b828-94fdf231711e',
+  onEvent: (event) => {
+    switch (event.type) {
+      case 'response.delta.text':
+        console.log('Text:', event.chunk);
+        break;
+      case 'response.delta.audio':        
+        audioPlayer.enqueue(event.audio);
+        break;
+      case 'response.complete':
+        console.log('Response complete');
+        break;
+    }
+  }
+});
+
+// Send a message
+session.sendText('Hello, how can you help me?');
+```
+
+## Authentication
+
+```ts
+import { KivoxClient } from '@kivox/client';
+
+const kivox = new KivoxClient({
+  baseUrl: 'http://localhost:8787',
+  headers: {
+    Authorization: 'Bearer token',
+  },
+});
+```
+
+## Other examples
+
+- [alpine-chat-app](https://github.com/ekisa-team/kivox/tree/main/examples/alpine-chat-app)
+
+## Contributing
+
+[https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md](https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md)
+
+## License
+
+[LICENSE](https://github.com/ekisa-team/kivox/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,806 @@
+/**
+* Configuration for HTTP transport.
+*/
+type HttpTransportConfig = {
+	/** Base URL for all requests */
+	baseUrl: string
+	/** Optional default headers */
+	headers?: Record<string, string>
+};
+/**
+* Error thrown by HTTP transport operations.
+*/
+declare class HttpTransportError extends Error {
+	readonly status: number;
+	readonly statusText: string;
+	readonly body?: unknown;
+	constructor(message: string, status: number, statusText: string, body?: unknown);
+}
+/**
+* Shared HTTP transport layer for REST API requests.
+* Handles request/response cycles with automatic JSON parsing.
+*/
+declare class HttpTransport {
+	private readonly config;
+	constructor(config: HttpTransportConfig);
+	/**
+	* Makes an HTTP request to the specified path.
+	*
+	* @param path API path (e.g., '/agents')
+	* @param init Fetch request options
+	* @returns Parsed JSON response
+	* @throws {HttpTransportError} If request fails
+	*/
+	request<T>(path: string, init?: RequestInit): Promise<T>;
+	/**
+	* Makes a GET request.
+	*/
+	get<T>(path: string, params?: Record<string, string>): Promise<T>;
+	/**
+	* Makes a POST request.
+	*/
+	post<T>(path: string, body?: unknown): Promise<T>;
+	/**
+	* Makes a PUT request.
+	*/
+	put<T>(path: string, body?: unknown): Promise<T>;
+	/**
+	* Makes a PATCH request.
+	*/
+	patch<T>(path: string, body?: unknown): Promise<T>;
+	/**
+	* Makes a DELETE request.
+	*/
+	delete<T>(path: string): Promise<T>;
+}
+/**
+* Paginated represents a paginated response containing items and metadata.
+*/
+type Paginated<T> = {
+	items: T
+	total: number
+	page: number
+	page_size: number
+	total_pages: number
+};
+type AgentStatus = "live" | "draft" | "archived";
+type Agent = {
+	id: string
+	template_id: string
+	config: AgentConfig
+	blueprint: AgentBlueprint
+	status: AgentStatus
+	created_at: Date
+	updated_at: Date
+};
+type AgentConfig = {
+	name: string
+	description: string
+	system_prompt: string
+	language: string
+	max_session_duration_minutes: number
+	max_silence_timeout_seconds: number
+	allow_interruptions: boolean
+};
+type AgentBlueprint<
+	NodeType = unknown,
+	EdgeType = unknown
+> = {
+	nodes: NodeType[]
+	edges: EdgeType[]
+};
+type AgentCreate = Partial<Pick<Agent, "config" | "blueprint" | "status" | "template_id">>;
+type AgentUpdate = Partial<Pick<AgentCreate, "config" | "blueprint">>;
+type NodeType = "CONTROL.START" | "CONTROL.DIALOG" | "CONTROL.END" | "LOGICAL.EVAL" | "FUNCTION.SET_VAR" | "FUNCTION.WEBHOOK" | "FUNCTION.EMAIL_NOTIFY" | "FUNCTION.KIBOT_NOTIFY" | "FUNCTION.TRANSFER" | "FUNCTION.TERMINATE";
+type Node = {
+	id: string
+	type: NodeType
+	position: NodePosition
+	measured: NodeDimensions
+	data: Record<string, unknown>
+};
+type NodePosition = {
+	x: number
+	y: number
+};
+type NodeDimensions = {
+	width: number
+	height: number
+};
+type Edge = {
+	id: string
+	source: string
+	target: string
+	label: string
+};
+/**
+* Configuration for listing agents.
+*/
+type AgentListParams = {
+	/** Number of results per page */
+	limit?: number
+	/** Page number (1-indexed) */
+	page?: number
+	/** Search query */
+	search?: string
+};
+/**
+* Client for interacting with KIVOX agents.
+*
+* @example
+* ```ts
+* const agents = await kivox.agents.list({ limit: 20 });
+* const agent = await kivox.agents.get('019bb51e-e45f-75e3-b828-94fdf231711e');
+* ```
+*/
+declare class AgentClient {
+	private readonly http;
+	constructor(http: HttpTransport);
+	/**
+	* Lists all agents with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of agents
+	*/
+	list(params?: AgentListParams): Promise<Paginated<Agent[]>>;
+	/**
+	* Lists all live agents with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of live agents
+	*/
+	listLive(params?: AgentListParams): Promise<Paginated<Agent[]>>;
+	/**
+	* Lists all draft agents with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of draft agents
+	*/
+	listDraft(params?: AgentListParams): Promise<Paginated<Agent[]>>;
+	/**
+	* Lists all archived agents with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of archived agents
+	*/
+	listArchived(params?: AgentListParams): Promise<Paginated<Agent[]>>;
+	/**
+	* Gets a single agent by ID.
+	*
+	* @param id Agent ID
+	* @returns Agent details
+	*/
+	get(id: string): Promise<Agent>;
+	/**
+	* Creates a new agent.
+	*
+	* @param data Agent data
+	* @returns Created agent
+	*/
+	create(data: AgentCreate): Promise<Agent>;
+	/**
+	* Updates an existing agent.
+	*
+	* @param id Agent ID
+	* @param data Updated agent data
+	* @returns Updated agent
+	*/
+	update(id: string, data: AgentUpdate): Promise<Agent>;
+	/**
+	* Marks an agent as live.
+	*
+	* @param id Agent ID
+	* @returns Updated agent
+	*/
+	markAsLive(id: string): Promise<Agent>;
+	/**
+	* Marks an agent as draft.
+	*
+	* @param id Agent ID
+	* @returns Updated agent
+	*/
+	markAsDraft(id: string): Promise<Agent>;
+	/**
+	* Marks an agent as archived.
+	*
+	* @param id Agent ID
+	* @returns Updated agent
+	*/
+	markAsArchived(id: string): Promise<Agent>;
+	/**
+	* Deletes an agent.
+	*
+	* @param id Agent ID
+	*/
+	delete(id: string): Promise<Agent>;
+	/**
+	* Parses a list of agents with stringified config and blueprint fields.
+	*
+	* @returns List of parsed agents.
+	*/
+	private static parseAgents;
+	/**
+	* Parses an agent with stringified config and blueprint fields.
+	*
+	* @returns Agent with parsed config and blueprint.
+	*/
+	private static parseAgent;
+}
+/**
+* Configuration for WebSocket transport.
+*/
+type WebSocketTransportConfig = {
+	/** Base WebSocket URL */
+	baseUrl: string
+	/** Optional default headers (for protocol support) */
+	headers?: Record<string, string>
+};
+/**
+* Shared WebSocket transport layer.
+* Provides WebSocket connection creation.
+*/
+declare class WebSocketTransport {
+	private readonly config;
+	constructor(config: WebSocketTransportConfig);
+	/**
+	* Creates a WebSocket connection to the specified path.
+	*
+	* @param path WebSocket path (e.g., '/conversations/websocket')
+	* @returns Raw WebSocket instance
+	*/
+	connect(path: string): WebSocket;
+}
+/**
+* Represents a handshake offer initiated by the client.
+*/
+type ClientSessionHandshakeOffer = {
+	type: "session.handshake.offer"
+	agent_id: string
+};
+/**
+* Signals that the client has ended the session.
+*/
+type ClientSessionEnd = {
+	type: "session.end"
+	conversation_id: string
+};
+/**
+* Sends a text input from the client to the server.
+*/
+type ClientInputText = {
+	type: "input.text"
+	conversation_id: string
+	text: string
+};
+/**
+* Indicates that the client is starting an audio input.
+*/
+type ClientInputAudio = {
+	type: "input.audio"
+	conversation_id: string
+};
+/**
+* Represents a continuous stream of audio data from the client.
+*/
+type ClientInputAudioStream = {
+	type: "input.audio.stream"
+	conversation_id: string
+};
+/**
+* Signals that the client has cancelled a request.
+*/
+type ClientRequestCancel = {
+	type: "request.cancel"
+	conversation_id: string
+};
+/**
+* Union type for all messages sent from the client to the server.
+*/
+type ClientMessage = ClientSessionHandshakeOffer | ClientSessionEnd | ClientInputText | ClientInputAudio | ClientInputAudioStream | ClientRequestCancel;
+/**
+* Sent by the server when a handshake offer is accepted.
+*/
+type ServerSessionHandshakeAccept = {
+	type: "session.handshake.accept"
+	agent_id: string
+	conversation_id: string
+};
+/**
+* Sent by the server when a handshake offer is rejected.
+*/
+type ServerSessionHandshakeReject = {
+	type: "session.handshake.reject"
+	reason: string
+};
+/**
+* Signals that the session has officially started.
+*/
+type ServerSessionStart = {
+	type: "session.start"
+	conversation_id: string
+	start_time: number
+	end_time: number
+	max_duration_ms: number
+};
+/**
+* Signals that the server has ended the session.
+*/
+type ServerSessionEnd = {
+	type: "session.end"
+	conversation_id: string
+};
+/**
+* Periodic update from the server regarding session timing.
+*/
+type ServerSessionTick = {
+	type: "session.tick"
+	conversation_id: string
+	max_duration_ms: number
+	remaining_time_ms: number
+	elapsed_time_ms: number
+};
+/**
+* Sent when a session ends due to inactivity or exceeding max duration.
+*/
+type ServerSessionTimeout = {
+	type: "session.timeout"
+	conversation_id: string
+};
+/**
+* Signals that the server has detected the start of speech.
+*/
+type ServerSpeechStart = {
+	type: "speech.start"
+	conversation_id: string
+};
+/**
+* Signals that the server has detected the end of speech.
+*/
+type ServerSpeechEnd = {
+	type: "speech.end"
+	conversation_id: string
+};
+/**
+* A partial text response chunk sent by the server.
+*/
+type ServerResponseDeltaText = {
+	type: "response.delta.text"
+	conversation_id: string
+	chunk: string
+};
+/**
+* A partial audio response chunk sent by the server.
+*/
+type ServerResponseDeltaAudio = {
+	type: "response.delta.audio"
+	conversation_id: string
+	size: number
+	audio: Blob
+};
+/**
+* Signals that the full response (text or audio) has been delivered.
+*/
+type ServerResponseComplete = {
+	type: "response.complete"
+	conversation_id: string
+};
+/**
+* Sent when an ongoing response is cancelled successfully.
+*/
+type ServerResponseCancel = {
+	type: "response.cancel"
+	conversation_id: string
+};
+/**
+* Sent when an error occurs during processing a request.
+*/
+type ServerResponseError = {
+	type: "response.error"
+	conversation_id: string
+	code: string
+	message: string
+};
+/**
+* Union type for all messages sent from the server to the client.
+*/
+type ServerMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart | ServerSessionEnd | ServerSessionTick | ServerSessionTimeout | ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
+/**
+* Union type for all messages sent from the client to the server before the session is established.
+*/
+type ServerConnectionMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart;
+/**
+* Union type for all messages sent from the server to the client during the session lifecycle.
+*/
+type ServerSessionLifecycleMessage = ServerSessionEnd | ServerSessionTick | ServerSessionTimeout;
+/**
+* Union type for all messages sent from the server to the client during the session activity.
+*/
+type ServerSessionActivityMessage = ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
+/**
+* Synthetic event emitted when the connection to the server is lost.
+*/
+type SessionConnectionLostEvent = {
+	type: "session.connection.lost"
+	conversation_id: string
+	reason: "socket_closed" | "socket_error"
+};
+/**
+* Events emitted during an active session
+*
+* @remarks
+* Connection messages are handled internally during connection establishment
+* and are not exposed through the session's `onEvent` callback.
+*/
+type ServerSessionEvent = ServerSessionLifecycleMessage | ServerSessionActivityMessage | SessionConnectionLostEvent;
+/**
+* Error thrown by the transport layer.
+*/
+declare class ConversationTransportError extends Error {
+	readonly code: string;
+	constructor(message: string, code?: string);
+}
+/**
+* Low-level WebSocket transport for conversation protocol.
+* Handles connection lifecycle and binary/JSON message routing.
+*/
+declare class ConversationTransport {
+	private;
+	private readonly _ws;
+	private _closed;
+	private _onMessage;
+	private _onBinary;
+	private _onError;
+	private _onClose;
+	constructor(_ws: WebSocket);
+	/**
+	* Waits for WebSocket to open.
+	* @throws {ConversationTransportError} If already connected or connection fails
+	*/
+	connect(): Promise<void>;
+	/**
+	* Sends a JSON message to the server.
+	* @throws {ConversationTransportError} If not connected
+	*/
+	send(message: ClientMessage): void;
+	/**
+	* Sends binary data (audio) to the server.
+	* @throws {ConversationTransportError} If not connected
+	*/
+	sendBinary(data: Blob): Promise<void>;
+	/**
+	* Registers a callback for incoming JSON messages.
+	*/
+	onMessage(handler: (msg: ServerMessage) => void): void;
+	/**
+	* Registers a callback for incoming binary data.
+	*/
+	onBinary(handler: (blob: Blob) => void): void;
+	/**
+	* Registers a callback for connection errors.
+	*/
+	onError(handler: (error: Error) => void): void;
+	/**
+	* Registers a callback for connection closure.
+	*/
+	onClose(handler: () => void): void;
+	/**
+	* Closes the WebSocket connection and cleans up resources.
+	*/
+	close(): void;
+}
+/**
+* Configuration for a conversation session.
+*/
+type ConversationSessionConfig = {
+	/**
+	* Event handler for all server messages.
+	*
+	* @remarks
+	* Important: `response.delta.audio` events combine the audio `Blob` and the metadata.
+	*/
+	onEvent?: (event: ServerSessionEvent) => void
+};
+/**
+* Represents an active conversation session with a KIVOX agent.
+* Provides methods to send messages and audio, and a callback to handle all server events.
+*/
+declare class ConversationSession {
+	private;
+	private _transport;
+	private _conversationId;
+	private _maxDurationMs;
+	private _startTime;
+	private _endTime;
+	private _closed;
+	private _pendingAudioMetadata;
+	private _onEvent;
+	/** The unique conversation identifier */
+	get conversationId(): string;
+	/** Maximum session duration in milliseconds */
+	get maxDurationMs(): number;
+	/** Unix timestamp when session started */
+	get startTime(): number;
+	/** Unix timestamp when session will end */
+	get endTime(): number;
+	/** Whether the session has been closed */
+	get closed(): boolean;
+	constructor(transport: ConversationTransport, conversationId: string, maxDurationMs: number, startTime: number, endTime: number, config: ConversationSessionConfig);
+	/**
+	* Sends a text message to the agent.
+	* @param text The message text to send
+	*/
+	sendText(text: string): void;
+	/**
+	* Sends a complete audio message to the agent.
+	* @param audio Audio blob to send
+	*/
+	sendAudio(audio: Blob): void;
+	/**
+	* Streams an audio chunk to the agent (for real-time audio input).
+	* @param chunk Audio chunk to stream
+	*/
+	streamAudio(chunk: Blob): void;
+	/**
+	* Requests the session to be cancelled.
+	* The 'session.cancel' event will be triggered when complete.
+	*/
+	cancelRequest(): void;
+	/**
+	* Requests the session to end gracefully.
+	* The 'session.end' event will be triggered when complete.
+	*/
+	end(): void;
+	/**
+	* Immediately closes the session and transport.
+	* No further events will be received.
+	*/
+	close(): void;
+}
+type Conversation = {
+	id: string
+	agent_id: string
+	started_at: Date
+	ended_at?: Date
+};
+/**
+* Configuration for listing conversations.
+*/
+type ConversationListParams = {
+	/** Agent ID to filter by */
+	agentId: string
+	/** Number of results per page */
+	limit?: number
+	/** Page number (1-indexed) */
+	page?: number
+};
+/**
+* Extended configuration for the connect method.
+*/
+type ConversationConnectParams = ConversationSessionConfig & {
+	/** Agent ID to connect to */
+	agentId: string
+	/**
+	* Optional callback for connection events.
+	* Called during connection establishment, before the session is created.
+	*/
+	onConnection?: (event: ServerConnectionMessage) => void
+};
+/**
+* Client for managing conversations and establishing sessions.
+*
+* @example
+* ```ts
+* // List past conversations
+* const conversations = await kivox.conversations.list();
+*
+* // Connect to an agent
+* const session = await kivox.conversations.connect({
+*   agentId: 'agent-123',
+*   onEvent: (event) => {
+*     switch (event.type) {
+*       case 'response.delta.text':
+*         console.log(event.chunk);
+*         break;
+*       case 'response.delta.audio':
+*         audioPlayer.enqueue(event.audio);
+*         break;
+*     }
+*   }
+* });
+*
+* session.sendText('Hello!');
+* ```
+*/
+declare class ConversationClient {
+	private readonly http;
+	private readonly ws;
+	constructor(http: HttpTransport, ws: WebSocketTransport);
+	/**
+	* Lists conversations with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of conversations
+	*/
+	list(params: ConversationListParams): Promise<Paginated<Conversation[]>>;
+	/**
+	* Gets a single conversation by ID.
+	*
+	* @param id Conversation ID
+	* @returns Conversation details
+	*/
+	get(id: string): Promise<Conversation>;
+	/**
+	* Connects to an agent and establishes a conversation session.
+	*
+	* @param params Connection configuration
+	* @returns Active conversation session
+	* @throws {Error} If handshake fails or connection is lost
+	*/
+	connect(params: ConversationConnectParams): Promise<ConversationSession>;
+}
+type MessageRole = "system" | "user" | "assistant";
+type Message = {
+	id: string
+	conversation_id: string
+	role: MessageRole
+	content: string
+	created_at: Date
+};
+/**
+* Configuration for listing messages.
+*/
+type MessageListParams = {
+	/** Conversation ID to filter by */
+	conversationId?: string
+	/** Number of results per page */
+	limit?: number
+	/** Page number (1-indexed) */
+	page?: number
+};
+/**
+* Client for interacting with conversation messages.
+*
+* @example
+* ```ts
+* const messages = await kivox.messages.list({
+*   conversationId: 'conv-123'
+* });
+* ```
+*/
+declare class MessageClient {
+	private readonly http;
+	constructor(http: HttpTransport);
+	/**
+	* Lists messages with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of messages
+	*/
+	list(params?: MessageListParams): Promise<Paginated<Message[]>>;
+	/**
+	* Gets a single message by ID.
+	*
+	* @param id Message ID
+	* @returns Message details
+	*/
+	get(id: string): Promise<Message>;
+}
+type Template = {
+	id: string
+	name: string
+	description?: string
+	blueprint: AgentBlueprint
+	created_at: Date
+	updated_at: Date
+};
+type TemplateCreate = Pick<Template, "name" | "description" | "blueprint">;
+type TemplateUpdate = Partial<TemplateCreate>;
+/**
+* Configuration for listing templates.
+*/
+type TemplateListParams = {
+	/** Number of results per page */
+	limit?: number
+	/** Page number (1-indexed) */
+	page?: number
+};
+/**
+* Client for interacting with KIVOX templates.
+*
+* @example
+* ```ts
+* const templates = await kivox.templates.list();
+* const template = await kivox.templates.get('template-123');
+* ```
+*/
+declare class TemplateClient {
+	private readonly http;
+	constructor(http: HttpTransport);
+	/**
+	* Lists all templates with optional filtering and pagination.
+	*
+	* @param params List configuration
+	* @returns Paginated list of templates
+	*/
+	list(params?: TemplateListParams): Promise<Paginated<Template[]>>;
+	/**
+	* Gets a single template by ID.
+	*
+	* @param id Template ID
+	* @returns Template details
+	*/
+	get(id: string): Promise<Template>;
+	/**
+	* Creates a new template.
+	*
+	* @param data Template data
+	* @returns Created template
+	*/
+	create(data: TemplateCreate): Promise<Template>;
+	/**
+	* Updates an existing template.
+	*
+	* @param id Template ID
+	* @param data Updated template data
+	* @returns Updated template
+	*/
+	update(id: string, data: TemplateUpdate): Promise<Template>;
+	/**
+	* Deletes a template.
+	*
+	* @param id Template ID
+	*/
+	delete(id: string): Promise<void>;
+}
+/**
+* Configuration for the Kivox client.
+*/
+type KivoxConfig = {
+	/**
+	* Base URL of your self-hosted KIVOX instance.
+	* @example 'http://localhost:8787'
+	* @example 'https://api.kivox.io'
+	*/
+	baseUrl: string
+	/**
+	* Optional headers to include with all requests.
+	* @example { Authorization: 'Bearer token' }
+	*/
+	headers?: Record<string, string>
+};
+/**
+* Main KIVOX client.
+* Provides unified access to all KIVOX resources.
+*
+* @example
+* ```ts
+* import { KivoxClient } from '@kivox/client';
+*
+* const kivox = new KivoxClient({
+*   baseUrl: 'http://localhost:8787',
+* });
+*
+* // List agents
+* const agents = await kivox.agents.list();
+*
+* // Start a conversation
+* const session = await kivox.conversations.connect({
+*   agentId: '019bb51e-e45f-75e3-b828-94fdf231711e',
+*   onEvent: (event) => {
+*     console.log(event);
+*   }
+* });
+* ```
+*/
+declare class KivoxClient {
+	/** Agent resource client */
+	readonly agents: AgentClient;
+	/** Conversation resource client */
+	readonly conversations: ConversationClient;
+	/** Template resource client */
+	readonly templates: TemplateClient;
+	/** Message resource client */
+	readonly messages: MessageClient;
+	constructor(config: KivoxConfig);
+}
+export { TemplateUpdate, TemplateCreate, Template, SessionConnectionLostEvent, ServerSpeechStart, ServerSpeechEnd, ServerSessionTimeout, ServerSessionTick, ServerSessionStart, ServerSessionLifecycleMessage, ServerSessionHandshakeReject, ServerSessionHandshakeAccept, ServerSessionEvent, ServerSessionEnd, ServerSessionActivityMessage, ServerResponseError, ServerResponseDeltaText, ServerResponseDeltaAudio, ServerResponseComplete, ServerResponseCancel, ServerMessage, ServerConnectionMessage, Paginated, NodeType, NodePosition, NodeDimensions, Node, MessageRole, Message, KivoxConfig, KivoxClient, HttpTransportError, Edge, ConversationTransportError, ConversationSessionConfig, ConversationSession, Conversation, ClientSessionHandshakeOffer, ClientSessionEnd, ClientRequestCancel, ClientMessage, ClientInputText, ClientInputAudioStream, ClientInputAudio, AgentUpdate, AgentStatus, AgentCreate, AgentConfig, AgentBlueprint, Agent };

package/dist/index.js

@@ -0,0 +1 @@
+class J{http;constructor(x){this.http=x}async list(x={}){let K={limit:(x.limit??10).toString(),page:(x.page??1).toString()};if(x.search)K.search=x.search;let B=await this.http.get("/agents",K);return{...B,items:J.parseAgents(B.items)}}async listLive(x={}){let K={limit:(x.limit??10).toString(),page:(x.page??1).toString()};if(x.search)K.search=x.search;let B=await this.http.get("/agents/live",K);return{...B,items:J.parseAgents(B.items)}}async listDraft(x={}){let K={limit:(x.limit??10).toString(),page:(x.page??1).toString()};if(x.search)K.search=x.search;let B=await this.http.get("/agents/draft",K);return{...B,items:J.parseAgents(B.items)}}async listArchived(x={}){let K={limit:(x.limit??10).toString(),page:(x.page??1).toString()};if(x.search)K.search=x.search;let B=await this.http.get("/agents/archived",K);return{...B,items:J.parseAgents(B.items)}}async get(x){let K=await this.http.get(`/agents/${x}`);return J.parseAgent(K)}async create(x){let K=await this.http.post("/agents",x);return J.parseAgent(K)}async update(x,K){let B=await this.http.put(`/agents/${x}`,K);return J.parseAgent(B)}async markAsLive(x){let K=await this.http.patch(`/agents/${x}/live`);return J.parseAgent(K)}async markAsDraft(x){let K=await this.http.patch(`/agents/${x}/draft`);return J.parseAgent(K)}async markAsArchived(x){let K=await this.http.patch(`/agents/${x}/archived`);return J.parseAgent(K)}async delete(x){let K=await this.http.delete(`/agents/${x}`);return J.parseAgent(K)}static parseAgents(x){return x.map(J.parseAgent)}static parseAgent(x){return{...x,config:JSON.parse(x.config),blueprint:JSON.parse(x.blueprint)}}}class _{_transport;_conversationId;_maxDurationMs;_startTime;_endTime;_closed=!1;_pendingAudioMetadata=null;_onEvent;get conversationId(){return this._conversationId}get maxDurationMs(){return this._maxDurationMs}get startTime(){return this._startTime}get endTime(){return this._endTime}get closed(){return this._closed}constructor(x,K,B,F,Q,Y){this._transport=x,this._conversationId=K,this._maxDurationMs=B,this._startTime=F,this._endTime=Q,this._onEvent=Y.onEvent,this.#x()}sendText(x){if(this._closed){console.warn("Cannot send text: session is closed");return}this._transport.send({type:"input.text",conversation_id:this._conversationId,text:x})}sendAudio(x){if(this._closed){console.warn("Cannot send audio: session is closed");return}this._transport.send({type:"input.audio",conversation_id:this._conversationId}),this._transport.sendBinary(x)}streamAudio(x){if(this._closed){console.warn("Cannot stream audio: session is closed");return}this._transport.send({type:"input.audio.stream",conversation_id:this._conversationId}),this._transport.sendBinary(x)}cancelRequest(){if(this._closed){console.warn("Cannot cancel session: session is closed");return}this._transport.send({type:"request.cancel",conversation_id:this._conversationId})}end(){if(this._closed){console.warn("Cannot end session: session is closed");return}this._transport.send({type:"session.end",conversation_id:this._conversationId})}close(){if(this._closed)return;this._closed=!0,this._transport.close()}#x(){this._transport.onMessage((x)=>{let K=x;if(K.type==="response.delta.audio"){this._pendingAudioMetadata={conversation_id:K.conversation_id,size:K.size};return}if(K.type==="session.end"||K.type==="session.timeout"||K.type==="session.connection.lost")this._closed=!0;this._onEvent?.(K)}),this._transport.onBinary((x)=>{if(this._pendingAudioMetadata){let K={type:"response.delta.audio",conversation_id:this._pendingAudioMetadata.conversation_id,size:this._pendingAudioMetadata.size,audio:x};this._pendingAudioMetadata=null,this._onEvent?.(K)}}),this._transport.onClose(()=>{if(this._closed)return;this._closed=!0,this._onEvent?.({type:"session.connection.lost",conversation_id:this._conversationId,reason:"socket_closed"})}),this._transport.onError(()=>{if(this._closed)return;this._closed=!0,this._onEvent?.({type:"session.connection.lost",conversation_id:this._conversationId,reason:"socket_error"})})}}class Z extends Error{code;constructor(x,K="TRANSPORT_ERROR"){super(x);this.code=K;this.name="ConversationTransportError"}}class ${_ws;_closed=!1;_onMessage=null;_onBinary=null;_onError=null;_onClose=null;constructor(x){this._ws=x}async connect(){if(this._ws.readyState===WebSocket.OPEN)throw new Z("Already connected","ALREADY_CONNECTED");if(this._ws.readyState===WebSocket.CLOSING||this._ws.readyState===WebSocket.CLOSED)throw new Z("Socket is closing or closed","SOCKET_CLOSED");return new Promise((x,K)=>{let B=()=>{this._ws.removeEventListener("open",B),this._ws.removeEventListener("error",F),this.#x(),x()},F=()=>{this._ws.removeEventListener("open",B),this._ws.removeEventListener("error",F),K(new Z("Connection failed","CONNECTION_FAILED"))};this._ws.addEventListener("open",B),this._ws.addEventListener("error",F)})}send(x){if(this._ws.readyState!==WebSocket.OPEN)throw new Z("Not connected","NOT_CONNECTED");this._ws.send(JSON.stringify(x))}async sendBinary(x){if(this._ws.readyState!==WebSocket.OPEN)throw new Z("Not connected","NOT_CONNECTED");let K=await x.arrayBuffer();this._ws.send(K)}onMessage(x){this._onMessage=x}onBinary(x){this._onBinary=x}onError(x){this._onError=x}onClose(x){this._onClose=x}close(){if(this._closed)return;if(this._closed=!0,this._ws.readyState===WebSocket.OPEN||this._ws.readyState===WebSocket.CONNECTING)this._ws.close();this._onClose?.()}#x(){this._ws.addEventListener("message",(x)=>{if(x.data instanceof Blob)this._onBinary?.(x.data);else if(x.data instanceof ArrayBuffer)this._onBinary?.(new Blob([x.data]));else try{let K=JSON.parse(x.data);this._onMessage?.(K)}catch(K){console.warn("Failed to parse message:",x.data,K)}}),this._ws.addEventListener("error",()=>{if(this._closed)return;this._onError?.(new Z("WebSocket error")),this.close()}),this._ws.addEventListener("close",()=>{if(this._closed)return;this.close()})}}class z{http;ws;constructor(x,K){this.http=x;this.ws=K}async list(x){let K={limit:(x.limit??20).toString(),page:(x.page??1).toString()};return this.http.get(`/agents/${x.agentId}/conversations`,K)}async get(x){return this.http.get(`/conversations/${x}`)}async connect(x){let K=this.ws.connect("/conversations/websocket"),B=new $(K);return await B.connect(),B.send({type:"session.handshake.offer",agent_id:x.agentId}),new Promise((F,Q)=>{let Y=!1;B.onMessage((N)=>{switch(N.type){case"session.handshake.accept":x.onConnection?.(N);break;case"session.handshake.reject":Y=!0,x.onConnection?.(N),B.close(),Q(Error(`Handshake rejected: ${N.reason}`));break;case"session.start":{Y=!0,x.onConnection?.(N);let W=new _(B,N.conversation_id,N.max_duration_ms,N.start_time,N.end_time,x);F(W);break}default:break}}),B.onError((N)=>{if(!Y)Q(N)}),B.onClose(()=>{if(!Y)Q(Error("WebSocket connection lost during handshake"))})})}}function O(x){let K=new URL(x),B=K.protocol==="https:"?"wss:":"ws:";return{rest:`${K.origin}/v1`,ws:`${B}//${K.host}/v1`}}class G extends Error{status;statusText;body;constructor(x,K,B,F){super(x);this.status=K;this.statusText=B;this.body=F;this.name="HttpTransportError"}}class V{config;constructor(x){this.config=x}async request(x,K){let B=`${this.config.baseUrl}${x}`,F=await fetch(B,{...K,headers:{"Content-Type":"application/json",...this.config.headers,...K?.headers}});if(!F.ok){let Q=await F.text();throw new G(`HTTP ${F.status}: ${F.statusText}`,F.status,F.statusText,Q)}return F.json()}async get(x,K){let B=new URL(`${this.config.baseUrl}${x}`);if(K){let F=Object.entries(K);for(let[Q,Y]of F)B.searchParams.set(Q,Y)}return this.request(x+B.search,{method:"GET"})}async post(x,K){return this.request(x,{method:"POST",body:K?JSON.stringify(K):void 0})}async put(x,K){return this.request(x,{method:"PUT",body:K?JSON.stringify(K):void 0})}async patch(x,K){return this.request(x,{method:"PATCH",body:K?JSON.stringify(K):void 0})}async delete(x){return this.request(x,{method:"DELETE"})}}class X{config;constructor(x){this.config=x}connect(x){let K=`${this.config.baseUrl}${x}`;return new WebSocket(K)}}class L{http;constructor(x){this.http=x}async list(x={}){let K={limit:(x.limit??50).toString(),page:(x.page??1).toString()};if(x.conversationId)K.conversation_id=x.conversationId;return this.http.get("/messages",K)}async get(x){return this.http.get(`/messages/${x}`)}}class H{http;constructor(x){this.http=x}async list(x={}){let K={limit:(x.limit??10).toString(),page:(x.page??1).toString()};return this.http.get("/templates",K)}async get(x){return this.http.get(`/templates/${x}`)}async create(x){return this.http.post("/templates",x)}async update(x,K){return this.http.put(`/templates/${x}`,K)}async delete(x){return this.http.delete(`/templates/${x}`)}}class U{agents;conversations;templates;messages;constructor(x){let K=O(x.baseUrl),B=new V({baseUrl:K.rest,headers:x.headers}),F=new X({baseUrl:K.ws,headers:x.headers});this.agents=new J(B),this.templates=new H(B),this.conversations=new z(B,F),this.messages=new L(B)}}export{U as KivoxClient,G as HttpTransportError,Z as ConversationTransportError,_ as ConversationSession};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kivox/client",
+  "version": "0.1.0-beta.1",
+  "description": "JavaScript/TypeScript client for KIVOX",
+  "homepage": "https://github.com/ekisa-team/kivox#readme",
+  "bugs": {
+    "url": "https://github.com/ekisa-team/kivox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekisa-team/kivox.git"
+  },
+  "author": {
+    "name": "Juan Mesa",
+    "email": "ju4n97@proton.me",
+    "url": "https://github.com/ju4n97"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "bun-dts": "^0.1.70",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}