@kivox/client 0.1.0-beta.2 → 0.1.0-beta.21

package/README.md

@@ -1,6 +1,6 @@
-# KIVOX JavaScript client
+# 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.
+`@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
 
@@ -13,7 +13,7 @@
 
 ## Documentation
 
-<https://kivox.ju4n97.workers.dev/docs/clients/kivox-js>
+<https://docs.kivox.com.co/packages/kivox-client>
 
 ## Installation
 
@@ -84,7 +84,7 @@ const kivox = new KivoxClient({
 
 ## Contributing
 
-[https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md](https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md)
 
 ## License
 

package/dist/index.d.ts

@@ -68,50 +68,34 @@ type Agent = {
 	id: string
 	template_id: string
 	config: AgentConfig
-	blueprint: AgentBlueprint
+	secrets: AgentSecret[]
+	ork_source: string
 	status: AgentStatus
 	created_at: Date
 	updated_at: Date
 };
 type AgentConfig = {
+	avatar_url?: string
 	name: string
+	description?: string
+	language?: string
+	global_system_prompt?: string
+	max_session_duration_minutes?: number
+	max_silence_timeout_seconds?: number
+	allow_interruptions?: boolean
+	llm_engine?: string
+	llm_model?: string
+};
+type AgentSecret = {
+	key: string
+	value: 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
+type AgentCreate = Partial<Pick<Agent, "config" | "secrets" | "ork_source" | "status" | "template_id">>;
+type AgentUpdate = Partial<Pick<AgentCreate, "config" | "secrets" | "ork_source">>;
+type AgentCompilationDiagnostic = {
+	errors: string[]
+	warnings: string[]
 };
 /**
 * Configuration for listing agents.
@@ -125,7 +109,7 @@ type AgentListParams = {
 	search?: string
 };
 /**
-* Client for interacting with KIVOX agents.
+* Client for interacting with Kivox agents.
 *
 * @example
 * ```ts
@@ -214,6 +198,14 @@ declare class AgentClient {
 	*/
 	delete(id: string): Promise<Agent>;
 	/**
+	* Compiles the Ork source code of an agent.
+	*
+	* @param id Agent ID
+	* @param orkSource Updated Ork source code. If not provided, the current Ork source code is used.
+	* @returns Compiled agent
+	*/
+	compile(id: string, orkSource?: string): Promise<AgentCompilationDiagnostic>;
+	/**
 	* Parses a list of agents with stringified config and blueprint fields.
 	*
 	* @returns List of parsed agents.
@@ -251,197 +243,157 @@ declare class WebSocketTransport {
 	connect(path: string): WebSocket;
 }
 /**
-* Represents a handshake offer initiated by the client.
+* Initializes a new conversational session.
+* It must be the first message sent after connection establishment.
 */
-type ClientSessionHandshakeOffer = {
-	type: "session.handshake.offer"
+type ClientHandshake = {
+	type: "handshake"
 	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.
+* Carries a single user text message.
 */
 type ClientInputText = {
-	type: "input.text"
-	conversation_id: string
+	type: "input_text"
 	text: string
 };
 /**
-* Indicates that the client is starting an audio input.
+* Signals that audio input will begin.
+* Typically followed by one or more binary WebSocket frames.
 */
 type ClientInputAudio = {
-	type: "input.audio"
-	conversation_id: string
+	type: "input_audio"
 };
 /**
-* Represents a continuous stream of audio data from the client.
+* Signals that a streamed audio chunk will follow in the next binary frame.
 */
 type ClientInputAudioStream = {
-	type: "input.audio.stream"
-	conversation_id: string
+	type: "input_audio_stream"
 };
 /**
-* Signals that the client has cancelled a request.
+* Requests interruption of the current streaming response.
 */
-type ClientRequestCancel = {
-	type: "request.cancel"
-	conversation_id: string
+type ClientCancel = {
+	type: "cancel"
 };
 /**
-* Union type for all messages sent from the client to the server.
+* Requests graceful session termination.
 */
-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
+type ClientEndSession = {
+	type: "end"
 };
 /**
-* Signals that the session has officially started.
+* Union type for all JSON messages sent from the client to the server.
 */
-type ServerSessionStart = {
-	type: "session.start"
-	conversation_id: string
-	start_time: number
-	end_time: number
-	max_duration_ms: number
-};
+type ClientMessage = ClientHandshake | ClientInputText | ClientInputAudio | ClientInputAudioStream | ClientCancel | ClientEndSession;
 /**
-* Signals that the server has ended the session.
+* Confirms successful session initialization.
 */
-type ServerSessionEnd = {
-	type: "session.end"
+type ServerHandshakeOK = {
+	type: "handshake_ok"
 	conversation_id: string
 };
 /**
-* Periodic update from the server regarding session timing.
+* Indicates that the session could not be created.
 */
-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
+type ServerHandshakeError = {
+	type: "handshake_error"
+	reason: string
 };
 /**
-* Signals that the server has detected the end of speech.
+* Carries a full text message generated by the runtime.
 */
-type ServerSpeechEnd = {
-	type: "speech.end"
-	conversation_id: string
+type ServerTextFull = {
+	type: "text_full"
+	content: string
 };
 /**
-* A partial text response chunk sent by the server.
+* Carries a streamed text fragment generated by the runtime.
 */
-type ServerResponseDeltaText = {
-	type: "response.delta.text"
-	conversation_id: string
+type ServerTextDelta = {
+	type: "text_delta"
 	chunk: string
 };
 /**
-* A partial audio response chunk sent by the server.
+* Carries metadata for a streamed audio fragment generated by the runtime.
+* The actual binary audio data is delivered in the immediately following binary frame
+* and merged into this object by the transport layer.
 */
-type ServerResponseDeltaAudio = {
-	type: "response.delta.audio"
-	conversation_id: string
+type ServerAudioDelta = {
+	type: "audio_delta"
+	/** Expected size of the incoming binary payload in bytes */
 	size: number
+	/** The binary audio data attached dynamically by the transport layer */
 	audio: Blob
 };
 /**
-* Signals that the full response (text or audio) has been delivered.
+* Signals that the runtime has completed its turn and is awaiting further user input.
 */
-type ServerResponseComplete = {
-	type: "response.complete"
-	conversation_id: string
+type ServerTurnComplete = {
+	type: "turn_complete"
 };
 /**
-* Sent when an ongoing response is cancelled successfully.
+* Signals that the conversation flow reached its exit node.
+* The session will close shortly after this event.
 */
-type ServerResponseCancel = {
-	type: "response.cancel"
-	conversation_id: string
+type ServerFlowComplete = {
+	type: "flow_complete"
 };
 /**
-* Sent when an error occurs during processing a request.
+* Represents a non-fatal execution or protocol error.
+* The session remains active unless followed by a SessionClosed event.
 */
-type ServerResponseError = {
-	type: "response.error"
-	conversation_id: string
+type ServerError = {
+	type: "error"
 	code: string
 	message: string
 };
 /**
-* Union type for all messages sent from the server to the client.
+* Provides periodic timing information for the active session.
 */
-type ServerMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart | ServerSessionEnd | ServerSessionTick | ServerSessionTimeout | ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
+type ServerTick = {
+	type: "tick"
+	/** Milliseconds until the session times out */
+	remaining_ms: number
+	/** Milliseconds elapsed since the session started */
+	elapsed_ms: number
+};
 /**
-* Union type for all messages sent from the client to the server before the session is established.
+* Indicates that the session is closing.
 */
-type ServerConnectionMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart;
+type ServerSessionClosed = {
+	type: "session_closed"
+	reason: string
+};
 /**
-* Union type for all messages sent from the server to the client during the session lifecycle.
+* Union type for all messages sent from the server to the client.
 */
-type ServerSessionLifecycleMessage = ServerSessionEnd | ServerSessionTick | ServerSessionTimeout;
+type ServerMessage = ServerHandshakeOK | ServerHandshakeError | ServerTextFull | ServerTextDelta | ServerAudioDelta | ServerTurnComplete | ServerFlowComplete | ServerError | ServerTick | ServerSessionClosed;
 /**
-* Union type for all messages sent from the server to the client during the session activity.
+* Messages related to the initial connection phase.
 */
-type ServerSessionActivityMessage = ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
+type ServerConnectionMessage = ServerHandshakeOK | ServerHandshakeError;
 /**
-* Synthetic event emitted when the connection to the server is lost.
+* Synthetic event emitted when the WebSocket connection to the server drops unexpectedly.
 */
 type SessionConnectionLostEvent = {
-	type: "session.connection.lost"
-	conversation_id: string
+	type: "connection_lost"
 	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.
+* Union type of all events that can be emitted during an active conversation session.
 */
-type ServerSessionEvent = ServerSessionLifecycleMessage | ServerSessionActivityMessage | SessionConnectionLostEvent;
+type ServerSessionEvent = ServerTextFull | ServerTextDelta | ServerAudioDelta | ServerTurnComplete | ServerFlowComplete | ServerError | ServerTick | ServerSessionClosed | SessionConnectionLostEvent;
 /**
-* Error thrown by the transport layer.
+* Error thrown by the transport layer when connection or state issues occur.
 */
 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.
+* Low-level WebSocket transport for the conversation protocol.
+* Handles connection lifecycle and distinct routing for JSON and binary messages.
 */
 declare class ConversationTransport {
 	private;
@@ -451,108 +403,139 @@ declare class ConversationTransport {
 	private _onBinary;
 	private _onError;
 	private _onClose;
+	/**
+	* Creates a new ConversationTransport.
+	* @param _ws The underlying WebSocket instance to wrap.
+	*/
 	constructor(_ws: WebSocket);
 	/**
-	* Waits for WebSocket to open.
-	* @throws {ConversationTransportError} If already connected or connection fails
+	* Waits for the WebSocket connection to fully open.
+	* @throws {ConversationTransportError} If the socket is already connected, closing, or fails to connect.
 	*/
 	connect(): Promise<void>;
 	/**
-	* Sends a JSON message to the server.
-	* @throws {ConversationTransportError} If not connected
+	* Sends a structured JSON message to the server.
+	* @param message The client message to send.
+	* @throws {ConversationTransportError} If the WebSocket is not currently open.
 	*/
 	send(message: ClientMessage): void;
 	/**
-	* Sends binary data (audio) to the server.
-	* @throws {ConversationTransportError} If not connected
+	* Sends binary data (like raw audio) to the server via a pure binary WebSocket frame.
+	* @param data The Blob representing the binary data.
+	* @throws {ConversationTransportError} If the WebSocket is not currently open.
 	*/
 	sendBinary(data: Blob): Promise<void>;
 	/**
-	* Registers a callback for incoming JSON messages.
+	* Registers a callback to be invoked when a JSON message is received from the server.
+	* @param handler The callback function.
 	*/
 	onMessage(handler: (msg: ServerMessage) => void): void;
 	/**
-	* Registers a callback for incoming binary data.
+	* Registers a callback to be invoked when a pure binary frame is received from the server.
+	* @param handler The callback function.
 	*/
 	onBinary(handler: (blob: Blob) => void): void;
 	/**
-	* Registers a callback for connection errors.
+	* Registers a callback to be invoked if a WebSocket error occurs.
+	* @param handler The callback function.
 	*/
 	onError(handler: (error: Error) => void): void;
 	/**
-	* Registers a callback for connection closure.
+	* Registers a callback to be invoked when the WebSocket connection is closed.
+	* @param handler The callback function.
 	*/
 	onClose(handler: () => void): void;
 	/**
-	* Closes the WebSocket connection and cleans up resources.
+	* Closes the underlying WebSocket connection and cleans up resources.
 	*/
 	close(): void;
 }
 /**
-* Configuration for a conversation session.
+* Configuration options provided when establishing a conversation session.
 */
 type ConversationSessionConfig = {
 	/**
-	* Event handler for all server messages.
+	* A callback function invoked whenever an event is emitted by the server during the session.
 	*
 	* @remarks
-	* Important: `response.delta.audio` events combine the audio `Blob` and the metadata.
+	* For `audio_delta` events, the SDK automatically waits for the subsequent binary WebSocket frame
+	* and attaches the resulting `Blob` to the event object before triggering this callback.
 	*/
 	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.
+* Represents an active, real-time conversation session with a Kivox agent.
+* Provides methods to dispatch user inputs and lifecycle commands, as well as tracking basic session state.
 */
 declare class ConversationSession {
 	private;
 	private _transport;
 	private _conversationId;
-	private _maxDurationMs;
-	private _startTime;
-	private _endTime;
 	private _closed;
-	private _pendingAudioMetadata;
 	private _onEvent;
-	/** The unique conversation identifier */
+	private _pendingAudioMetadata;
+	private _remainingMs;
+	private _elapsedMs;
+	/**
+	* The unique server-generated ID for this active conversation.
+	*/
 	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 */
+	/**
+	* The number of milliseconds remaining until the engine enforces a session timeout.
+	* This value is periodically synced via server 'tick' events.
+	*/
+	get remainingMs(): number;
+	/**
+	* The number of milliseconds elapsed since the session was initiated.
+	* This value is periodically synced via server 'tick' events.
+	*/
+	get elapsedMs(): number;
+	/**
+	* Indicates whether the session has been permanently 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
+	* Constructs a new active ConversationSession.
+	* Normally called internally by `ConversationClient.connect()`.
+	*
+	* @param transport The underlying active WebSocket transport.
+	* @param conversationId The ID assigned by the server during the handshake.
+	* @param config User-provided configuration options (e.g., event handlers).
+	*/
+	constructor(transport: ConversationTransport, conversationId: string, config: ConversationSessionConfig);
+	/**
+	* Sends a single textual user input to the agent.
+	*
+	* @param text The textual payload provided by the user.
 	*/
 	sendText(text: string): void;
 	/**
-	* Sends a complete audio message to the agent.
-	* @param audio Audio blob to send
+	* Sends a complete, recorded audio buffer to the agent.
+	* First sends an `input_audio` header, then dispatches the binary frame.
+	*
+	* @param audio The raw binary audio file/buffer.
 	*/
 	sendAudio(audio: Blob): void;
 	/**
-	* Streams an audio chunk to the agent (for real-time audio input).
-	* @param chunk Audio chunk to stream
+	* Streams a fragment of real-time audio to the agent.
+	* First sends an `input_audio_stream` header, then dispatches the binary frame.
+	*
+	* @param chunk The raw binary audio fragment.
 	*/
 	streamAudio(chunk: Blob): void;
 	/**
-	* Requests the session to be cancelled.
-	* The 'session.cancel' event will be triggered when complete.
+	* Requests that the server immediately halt the currently streaming assistant response.
+	* The session remains open and the agent will await the next user input.
 	*/
 	cancelRequest(): void;
 	/**
-	* Requests the session to end gracefully.
-	* The 'session.end' event will be triggered when complete.
+	* Instructs the server to gracefully terminate the conversation.
+	* Wait for the resulting `session_closed` event to confirm termination.
 	*/
 	end(): void;
 	/**
-	* Immediately closes the session and transport.
-	* No further events will be received.
+	* Immediately tears down the underlying WebSocket transport and marks the session closed locally.
+	* Does not wait for a graceful server acknowledgment.
 	*/
 	close(): void;
 }
@@ -563,49 +546,43 @@ type Conversation = {
 	ended_at?: Date
 };
 /**
-* Configuration for listing conversations.
+* Configuration parameters for fetching a list of past conversations.
 */
 type ConversationListParams = {
-	/** Agent ID to filter by */
+	/** Agent ID to filter the conversations by */
 	agentId: string
-	/** Number of results per page */
+	/** Number of results per page (defaults to 20) */
 	limit?: number
-	/** Page number (1-indexed) */
+	/** Page number, 1-indexed (defaults to 1) */
 	page?: number
 };
 /**
-* Extended configuration for the connect method.
+* Configuration parameters for connecting to an agent and establishing a session.
 */
 type ConversationConnectParams = ConversationSessionConfig & {
-	/** Agent ID to connect to */
+	/** The unique ID of the agent to connect to */
 	agentId: string
 	/**
-	* Optional callback for connection events.
-	* Called during connection establishment, before the session is created.
+	* Optional callback invoked during the initial handshake phase.
+	* Can be used to hook into successful or failed connection attempts before the session object is returned.
 	*/
 	onConnection?: (event: ServerConnectionMessage) => void
 };
 /**
-* Client for managing conversations and establishing sessions.
+* Client service for managing conversational records and establishing real-time WebSocket sessions.
 *
 * @example
 * ```ts
-* // List past conversations
-* const conversations = await kivox.conversations.list();
-*
-* // Connect to an agent
+* // Connect to a Kivox 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;
-*     }
-*   }
+* agentId: 'agent-123',
+* onEvent: (event) => {
+* if (event.type === 'text_delta') {
+* console.log(event.chunk);
+* } else if (event.type === 'audio_delta') {
+* audioPlayer.enqueue(event.audio);
+* }
+* }
 * });
 *
 * session.sendText('Hello!');
@@ -614,27 +591,33 @@ type ConversationConnectParams = ConversationSessionConfig & {
 declare class ConversationClient {
 	private readonly http;
 	private readonly ws;
+	/**
+	* Instantiates a new ConversationClient.
+	* @param http The HTTP transport for REST endpoints.
+	* @param ws The WebSocket transport factory.
+	*/
 	constructor(http: HttpTransport, ws: WebSocketTransport);
 	/**
-	* Lists conversations with optional filtering and pagination.
+	* Retrieves a paginated list of past conversations for a specific agent.
 	*
-	* @param params List configuration
-	* @returns Paginated list of conversations
+	* @param params Query parameters for pagination and filtering.
+	* @returns A promise resolving to a paginated list of conversations.
 	*/
 	list(params: ConversationListParams): Promise<Paginated<Conversation[]>>;
 	/**
-	* Gets a single conversation by ID.
+	* Retrieves the details of a single conversation by its ID.
 	*
-	* @param id Conversation ID
-	* @returns Conversation details
+	* @param id The unique identifier of the conversation.
+	* @returns A promise resolving to the conversation data.
 	*/
 	get(id: string): Promise<Conversation>;
 	/**
-	* Connects to an agent and establishes a conversation session.
+	* Establishes a real-time WebSocket session with an agent.
+	* Handles the handshake protocol and returns an active session instance.
 	*
-	* @param params Connection configuration
-	* @returns Active conversation session
-	* @throws {Error} If handshake fails or connection is lost
+	* @param params Configuration for the connection and subsequent session.
+	* @returns A promise resolving to an active `ConversationSession`.
+	* @throws {Error} If the handshake fails or the connection drops during negotiation.
 	*/
 	connect(params: ConversationConnectParams): Promise<ConversationSession>;
 }
@@ -689,11 +672,11 @@ type Template = {
 	id: string
 	name: string
 	description?: string
-	blueprint: AgentBlueprint
+	ork_source: string
 	created_at: Date
 	updated_at: Date
 };
-type TemplateCreate = Pick<Template, "name" | "description" | "blueprint">;
+type TemplateCreate = Pick<Template, "name" | "description" | "ork_source">;
 type TemplateUpdate = Partial<TemplateCreate>;
 /**
 * Configuration for listing templates.
@@ -705,7 +688,7 @@ type TemplateListParams = {
 	page?: number
 };
 /**
-* Client for interacting with KIVOX templates.
+* Client for interacting with Kivox templates.
 *
 * @example
 * ```ts
@@ -757,7 +740,7 @@ declare class TemplateClient {
 */
 type KivoxConfig = {
 	/**
-	* Base URL of your self-hosted KIVOX instance.
+	* Base URL of your self-hosted Kivox instance.
 	* @example 'http://localhost:8787'
 	* @example 'https://api.kivox.io'
 	*/
@@ -769,8 +752,8 @@ type KivoxConfig = {
 	headers?: Record<string, string>
 };
 /**
-* Main KIVOX client.
-* Provides unified access to all KIVOX resources.
+* Main Kivox client.
+* Provides unified access to all Kivox resources.
 *
 * @example
 * ```ts
@@ -803,4 +786,4 @@ declare class KivoxClient {
 	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 };
+export { TemplateUpdate, TemplateCreate, Template, SessionConnectionLostEvent, ServerTurnComplete, ServerTick, ServerTextFull, ServerTextDelta, ServerSessionEvent, ServerSessionClosed, ServerMessage, ServerHandshakeOK, ServerHandshakeError, ServerFlowComplete, ServerError, ServerConnectionMessage, ServerAudioDelta, Paginated, MessageRole, Message, KivoxConfig, KivoxClient, HttpTransportError, ConversationTransportError, ConversationSessionConfig, ConversationSession, Conversation, ClientMessage, ClientInputText, ClientInputAudioStream, ClientInputAudio, ClientHandshake, ClientEndSession, ClientCancel, AgentUpdate, AgentStatus, AgentSecret, AgentCreate, AgentConfig, AgentCompilationDiagnostic, Agent };

package/dist/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kivox/client",
-  "version": "0.1.0-beta.2",
-  "description": "JavaScript/TypeScript client for KIVOX",
+  "version": "0.1.0-beta.21",
+  "description": "JavaScript/TypeScript client for Kivox",
   "homepage": "https://github.com/ekisa-team/kivox#readme",
   "bugs": {
     "url": "https://github.com/ekisa-team/kivox/issues"
@@ -15,7 +15,6 @@
     "email": "ju4n97@proton.me",
     "url": "https://github.com/ju4n97"
   },
-  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -42,6 +41,7 @@
     "typescript": "5.9.3"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "latest"
   }
 }