@kivox/client 0.1.0-beta.4 → 0.1.0-beta.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,447 +1,2109 @@
1
+ import createClient from "openapi-fetch";
1
2
  /**
2
- * Configuration for HTTP transport.
3
+ * This file was auto-generated by openapi-typescript.
4
+ * Do not make direct changes to the file.
3
5
  */
4
- type HttpTransportConfig = {
5
- /** Base URL for all requests */
6
- baseUrl: string
7
- /** Optional default headers */
8
- headers?: Record<string, string>
9
- };
10
- /**
11
- * Error thrown by HTTP transport operations.
12
- */
13
- declare class HttpTransportError extends Error {
14
- readonly status: number;
15
- readonly statusText: string;
16
- readonly body?: unknown;
17
- constructor(message: string, status: number, statusText: string, body?: unknown);
6
+ interface paths {
7
+ "/auth/signup": {
8
+ parameters: {
9
+ query?: never
10
+ header?: never
11
+ path?: never
12
+ cookie?: never
13
+ }
14
+ get?: never
15
+ put?: never
16
+ /** Register a new user account */
17
+ post: operations["signup"]
18
+ delete?: never
19
+ options?: never
20
+ head?: never
21
+ patch?: never
22
+ trace?: never
23
+ };
24
+ "/auth/sessions": {
25
+ parameters: {
26
+ query?: never
27
+ header?: never
28
+ path?: never
29
+ cookie?: never
30
+ }
31
+ get?: never
32
+ put?: never
33
+ /** Log in and start a session */
34
+ post: operations["createSession"]
35
+ /** Log out of all sessions */
36
+ delete: operations["revokeAllSessions"]
37
+ options?: never
38
+ head?: never
39
+ patch?: never
40
+ trace?: never
41
+ };
42
+ "/auth/sessions/me": {
43
+ parameters: {
44
+ query?: never
45
+ header?: never
46
+ path?: never
47
+ cookie?: never
48
+ }
49
+ get?: never
50
+ put?: never
51
+ post?: never
52
+ /** Log out of the current session */
53
+ delete: operations["revokeSession"]
54
+ options?: never
55
+ head?: never
56
+ patch?: never
57
+ trace?: never
58
+ };
59
+ "/auth/password/recover": {
60
+ parameters: {
61
+ query?: never
62
+ header?: never
63
+ path?: never
64
+ cookie?: never
65
+ }
66
+ get?: never
67
+ put?: never
68
+ /**
69
+ * Request a password reset email
70
+ * @description Always returns 204 regardless of whether the email exists,
71
+ * to prevent email enumeration.
72
+ */
73
+ post: operations["recoverPassword"]
74
+ delete?: never
75
+ options?: never
76
+ head?: never
77
+ patch?: never
78
+ trace?: never
79
+ };
80
+ "/auth/password/reset": {
81
+ parameters: {
82
+ query?: never
83
+ header?: never
84
+ path?: never
85
+ cookie?: never
86
+ }
87
+ get?: never
88
+ put?: never
89
+ /**
90
+ * Reset password using a recovery token
91
+ * @description Consumes the token and updates the password.
92
+ * All existing sessions are revoked on success.
93
+ */
94
+ post: operations["resetPassword"]
95
+ delete?: never
96
+ options?: never
97
+ head?: never
98
+ patch?: never
99
+ trace?: never
100
+ };
101
+ "/auth/api-keys": {
102
+ parameters: {
103
+ query?: never
104
+ header?: never
105
+ path?: never
106
+ cookie?: never
107
+ }
108
+ /** List API keys owned by the authenticated user */
109
+ get: operations["listAPIKeys"]
110
+ put?: never
111
+ /** Create a new API key */
112
+ post: operations["createAPIKey"]
113
+ delete?: never
114
+ options?: never
115
+ head?: never
116
+ patch?: never
117
+ trace?: never
118
+ };
119
+ "/auth/api-keys/{keyID}": {
120
+ parameters: {
121
+ query?: never
122
+ header?: never
123
+ path: {
124
+ keyID: components["parameters"]["KeyID"]
125
+ }
126
+ cookie?: never
127
+ }
128
+ get?: never
129
+ put?: never
130
+ post?: never
131
+ /** Revoke an API key */
132
+ delete: operations["revokeAPIKey"]
133
+ options?: never
134
+ head?: never
135
+ patch?: never
136
+ trace?: never
137
+ };
138
+ "/users/me": {
139
+ parameters: {
140
+ query?: never
141
+ header?: never
142
+ path?: never
143
+ cookie?: never
144
+ }
145
+ /** Get the authenticated user's profile */
146
+ get: operations["getMe"]
147
+ put?: never
148
+ post?: never
149
+ /** Soft-delete the authenticated user's account */
150
+ delete: operations["deleteMe"]
151
+ options?: never
152
+ head?: never
153
+ /** Update the authenticated user's profile */
154
+ patch: operations["updateMe"]
155
+ trace?: never
156
+ };
157
+ "/users/me/email": {
158
+ parameters: {
159
+ query?: never
160
+ header?: never
161
+ path?: never
162
+ cookie?: never
163
+ }
164
+ get?: never
165
+ put?: never
166
+ post?: never
167
+ delete?: never
168
+ options?: never
169
+ head?: never
170
+ /** Update the authenticated user's email address */
171
+ patch: operations["updateMyEmail"]
172
+ trace?: never
173
+ };
174
+ "/orgs": {
175
+ parameters: {
176
+ query?: never
177
+ header?: never
178
+ path?: never
179
+ cookie?: never
180
+ }
181
+ /** List organizations the authenticated user belongs to */
182
+ get: operations["listOrgs"]
183
+ put?: never
184
+ /** Create a new organization */
185
+ post: operations["createOrg"]
186
+ delete?: never
187
+ options?: never
188
+ head?: never
189
+ patch?: never
190
+ trace?: never
191
+ };
192
+ "/orgs/{orgSlug}": {
193
+ parameters: {
194
+ query?: never
195
+ header?: never
196
+ path: {
197
+ /** @description URL-safe organization identifier. */
198
+ orgSlug: components["parameters"]["OrgSlug"]
199
+ }
200
+ cookie?: never
201
+ }
202
+ /** Get an organization by slug */
203
+ get: operations["getOrg"]
204
+ put?: never
205
+ post?: never
206
+ /** Soft-delete an organization (requires owner) */
207
+ delete: operations["deleteOrg"]
208
+ options?: never
209
+ head?: never
210
+ /** Update an organization (requires admin) */
211
+ patch: operations["updateOrg"]
212
+ trace?: never
213
+ };
214
+ "/orgs/{orgSlug}/members": {
215
+ parameters: {
216
+ query?: never
217
+ header?: never
218
+ path: {
219
+ /** @description URL-safe organization identifier. */
220
+ orgSlug: components["parameters"]["OrgSlug"]
221
+ }
222
+ cookie?: never
223
+ }
224
+ /** List members of an organization (requires viewer) */
225
+ get: operations["listOrgMembers"]
226
+ put?: never
227
+ /** Add a member to an organization (requires admin) */
228
+ post: operations["addOrgMember"]
229
+ delete?: never
230
+ options?: never
231
+ head?: never
232
+ patch?: never
233
+ trace?: never
234
+ };
235
+ "/orgs/{orgSlug}/members/{userID}": {
236
+ parameters: {
237
+ query?: never
238
+ header?: never
239
+ path: {
240
+ /** @description URL-safe organization identifier. */
241
+ orgSlug: components["parameters"]["OrgSlug"]
242
+ userID: components["parameters"]["UserID"]
243
+ }
244
+ cookie?: never
245
+ }
246
+ get?: never
247
+ put?: never
248
+ post?: never
249
+ /** Remove a member (admin required, unless removing self) */
250
+ delete: operations["removeOrgMember"]
251
+ options?: never
252
+ head?: never
253
+ /** Update a member's role (requires admin) */
254
+ patch: operations["updateOrgMember"]
255
+ trace?: never
256
+ };
257
+ "/users/me/agents": {
258
+ parameters: {
259
+ query?: never
260
+ header?: never
261
+ path?: never
262
+ cookie?: never
263
+ }
264
+ /** List agents owned by the authenticated user */
265
+ get: operations["listUserAgents"]
266
+ put?: never
267
+ /** Create an agent owned by the authenticated user */
268
+ post: operations["createUserAgent"]
269
+ delete?: never
270
+ options?: never
271
+ head?: never
272
+ patch?: never
273
+ trace?: never
274
+ };
275
+ "/orgs/{orgSlug}/agents": {
276
+ parameters: {
277
+ query?: never
278
+ header?: never
279
+ path: {
280
+ /** @description URL-safe organization identifier. */
281
+ orgSlug: components["parameters"]["OrgSlug"]
282
+ }
283
+ cookie?: never
284
+ }
285
+ /** List agents owned by an organization (requires viewer) */
286
+ get: operations["listOrgAgents"]
287
+ put?: never
288
+ /** Create an agent owned by an organization (requires member) */
289
+ post: operations["createOrgAgent"]
290
+ delete?: never
291
+ options?: never
292
+ head?: never
293
+ patch?: never
294
+ trace?: never
295
+ };
296
+ "/agents/{agentID}": {
297
+ parameters: {
298
+ query?: never
299
+ header?: never
300
+ path: {
301
+ agentID: components["parameters"]["AgentID"]
302
+ }
303
+ cookie?: never
304
+ }
305
+ /** Get an agent by ID (requires viewer) */
306
+ get: operations["getAgent"]
307
+ put?: never
308
+ post?: never
309
+ /** Soft-delete an agent (requires admin) */
310
+ delete: operations["deleteAgent"]
311
+ options?: never
312
+ head?: never
313
+ /** Update an agent's config, secrets, or blueprint (requires member) */
314
+ patch: operations["updateAgent"]
315
+ trace?: never
316
+ };
317
+ "/agents/{agentID}/status": {
318
+ parameters: {
319
+ query?: never
320
+ header?: never
321
+ path: {
322
+ agentID: components["parameters"]["AgentID"]
323
+ }
324
+ cookie?: never
325
+ }
326
+ get?: never
327
+ put?: never
328
+ post?: never
329
+ delete?: never
330
+ options?: never
331
+ head?: never
332
+ /** Transition an agent's status (requires admin) */
333
+ patch: operations["updateAgentStatus"]
334
+ trace?: never
335
+ };
336
+ "/agents/{agentID}/lint": {
337
+ parameters: {
338
+ query?: never
339
+ header?: never
340
+ path: {
341
+ agentID: components["parameters"]["AgentID"]
342
+ }
343
+ cookie?: never
344
+ }
345
+ get?: never
346
+ put?: never
347
+ /**
348
+ * Lint an agent's blueprint (requires viewer)
349
+ * @description Pass a `blueprint` in the request body to lint that instead of the
350
+ * agent's saved blueprint. Useful for pre-save validation in the editor.
351
+ */
352
+ post: operations["lintAgent"]
353
+ delete?: never
354
+ options?: never
355
+ head?: never
356
+ patch?: never
357
+ trace?: never
358
+ };
359
+ "/agents/{agentID}/conversations": {
360
+ parameters: {
361
+ query?: never
362
+ header?: never
363
+ path: {
364
+ agentID: components["parameters"]["AgentID"]
365
+ }
366
+ cookie?: never
367
+ }
368
+ /** List conversations for an agent (requires viewer) */
369
+ get: operations["listAgentConversations"]
370
+ put?: never
371
+ post?: never
372
+ delete?: never
373
+ options?: never
374
+ head?: never
375
+ patch?: never
376
+ trace?: never
377
+ };
378
+ "/conversations/{conversationID}": {
379
+ parameters: {
380
+ query?: never
381
+ header?: never
382
+ path: {
383
+ conversationID: components["parameters"]["ConversationID"]
384
+ }
385
+ cookie?: never
386
+ }
387
+ /** Get a conversation by ID (requires viewer on the parent agent) */
388
+ get: operations["getConversation"]
389
+ put?: never
390
+ post?: never
391
+ /** Soft-delete a conversation (requires admin on the parent agent) */
392
+ delete: operations["deleteConversation"]
393
+ options?: never
394
+ head?: never
395
+ patch?: never
396
+ trace?: never
397
+ };
398
+ "/conversations/{conversationID}/messages": {
399
+ parameters: {
400
+ query?: never
401
+ header?: never
402
+ path: {
403
+ conversationID: components["parameters"]["ConversationID"]
404
+ }
405
+ cookie?: never
406
+ }
407
+ /** List messages in a conversation (requires viewer on the parent agent) */
408
+ get: operations["listConversationMessages"]
409
+ put?: never
410
+ post?: never
411
+ delete?: never
412
+ options?: never
413
+ head?: never
414
+ patch?: never
415
+ trace?: never
416
+ };
417
+ "/users/me/templates": {
418
+ parameters: {
419
+ query?: never
420
+ header?: never
421
+ path?: never
422
+ cookie?: never
423
+ }
424
+ /** List templates owned by the authenticated user */
425
+ get: operations["listUserTemplates"]
426
+ put?: never
427
+ /** Create a template owned by the authenticated user */
428
+ post: operations["createUserTemplate"]
429
+ delete?: never
430
+ options?: never
431
+ head?: never
432
+ patch?: never
433
+ trace?: never
434
+ };
435
+ "/orgs/{orgSlug}/templates": {
436
+ parameters: {
437
+ query?: never
438
+ header?: never
439
+ path: {
440
+ /** @description URL-safe organization identifier. */
441
+ orgSlug: components["parameters"]["OrgSlug"]
442
+ }
443
+ cookie?: never
444
+ }
445
+ /** List templates owned by an organization (requires viewer) */
446
+ get: operations["listOrgTemplates"]
447
+ put?: never
448
+ /** Create a template owned by an organization (requires member) */
449
+ post: operations["createOrgTemplate"]
450
+ delete?: never
451
+ options?: never
452
+ head?: never
453
+ patch?: never
454
+ trace?: never
455
+ };
456
+ "/templates/{templateID}": {
457
+ parameters: {
458
+ query?: never
459
+ header?: never
460
+ path: {
461
+ templateID: components["parameters"]["TemplateID"]
462
+ }
463
+ cookie?: never
464
+ }
465
+ /** Get a template by ID */
466
+ get: operations["getTemplate"]
467
+ put?: never
468
+ post?: never
469
+ /** Soft-delete a template (requires admin if org-owned) */
470
+ delete: operations["deleteTemplate"]
471
+ options?: never
472
+ head?: never
473
+ /** Update a template (requires member if org-owned) */
474
+ patch: operations["updateTemplate"]
475
+ trace?: never
476
+ };
18
477
  }
19
- /**
20
- * Shared HTTP transport layer for REST API requests.
21
- * Handles request/response cycles with automatic JSON parsing.
22
- */
23
- declare class HttpTransport {
24
- private readonly config;
25
- constructor(config: HttpTransportConfig);
26
- /**
27
- * Makes an HTTP request to the specified path.
28
- *
29
- * @param path API path (e.g., '/agents')
30
- * @param init Fetch request options
31
- * @returns Parsed JSON response
32
- * @throws {HttpTransportError} If request fails
33
- */
34
- request<T>(path: string, init?: RequestInit): Promise<T>;
35
- /**
36
- * Makes a GET request.
37
- */
38
- get<T>(path: string, params?: Record<string, string>): Promise<T>;
39
- /**
40
- * Makes a POST request.
41
- */
42
- post<T>(path: string, body?: unknown): Promise<T>;
43
- /**
44
- * Makes a PUT request.
45
- */
46
- put<T>(path: string, body?: unknown): Promise<T>;
47
- /**
48
- * Makes a PATCH request.
49
- */
50
- patch<T>(path: string, body?: unknown): Promise<T>;
51
- /**
52
- * Makes a DELETE request.
53
- */
54
- delete<T>(path: string): Promise<T>;
55
- }
56
- /**
57
- * Paginated represents a paginated response containing items and metadata.
58
- */
59
- type Paginated<T> = {
60
- items: T
61
- total: number
62
- page: number
63
- page_size: number
64
- total_pages: number
65
- };
66
- type AgentStatus = "live" | "draft" | "archived";
67
- type Agent = {
68
- id: string
69
- template_id: string
70
- config: AgentConfig
71
- blueprint: AgentBlueprint
72
- status: AgentStatus
73
- created_at: Date
74
- updated_at: Date
75
- };
76
- type AgentConfig = {
77
- name: string
78
- description: string
79
- system_prompt: string
80
- language: string
81
- max_session_duration_minutes: number
82
- max_silence_timeout_seconds: number
83
- allow_interruptions: boolean
84
- };
85
- type AgentBlueprint<
86
- NodeType = unknown,
87
- EdgeType = unknown
88
- > = {
89
- nodes: NodeType[]
90
- edges: EdgeType[]
91
- };
92
- type AgentCreate = Partial<Pick<Agent, "config" | "blueprint" | "status" | "template_id">>;
93
- type AgentUpdate = Partial<Pick<AgentCreate, "config" | "blueprint">>;
94
- 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";
95
- type Node = {
96
- id: string
97
- type: NodeType
98
- position: NodePosition
99
- measured: NodeDimensions
100
- data: Record<string, unknown>
101
- };
102
- type NodePosition = {
103
- x: number
104
- y: number
105
- };
106
- type NodeDimensions = {
107
- width: number
108
- height: number
109
- };
110
- type Edge = {
111
- id: string
112
- source: string
113
- target: string
114
- label: string
115
- };
116
- /**
117
- * Configuration for listing agents.
118
- */
119
- type AgentListParams = {
120
- /** Number of results per page */
121
- limit?: number
122
- /** Page number (1-indexed) */
123
- page?: number
124
- /** Search query */
125
- search?: string
126
- };
127
- /**
128
- * Client for interacting with KIVOX agents.
129
- *
130
- * @example
131
- * ```ts
132
- * const agents = await kivox.agents.list({ limit: 20 });
133
- * const agent = await kivox.agents.get('019bb51e-e45f-75e3-b828-94fdf231711e');
134
- * ```
135
- */
136
- declare class AgentClient {
137
- private readonly http;
138
- constructor(http: HttpTransport);
139
- /**
140
- * Lists all agents with optional filtering and pagination.
141
- *
142
- * @param params List configuration
143
- * @returns Paginated list of agents
144
- */
145
- list(params?: AgentListParams): Promise<Paginated<Agent[]>>;
146
- /**
147
- * Lists all live agents with optional filtering and pagination.
148
- *
149
- * @param params List configuration
150
- * @returns Paginated list of live agents
151
- */
152
- listLive(params?: AgentListParams): Promise<Paginated<Agent[]>>;
153
- /**
154
- * Lists all draft agents with optional filtering and pagination.
155
- *
156
- * @param params List configuration
157
- * @returns Paginated list of draft agents
158
- */
159
- listDraft(params?: AgentListParams): Promise<Paginated<Agent[]>>;
160
- /**
161
- * Lists all archived agents with optional filtering and pagination.
162
- *
163
- * @param params List configuration
164
- * @returns Paginated list of archived agents
165
- */
166
- listArchived(params?: AgentListParams): Promise<Paginated<Agent[]>>;
167
- /**
168
- * Gets a single agent by ID.
169
- *
170
- * @param id Agent ID
171
- * @returns Agent details
172
- */
173
- get(id: string): Promise<Agent>;
174
- /**
175
- * Creates a new agent.
176
- *
177
- * @param data Agent data
178
- * @returns Created agent
179
- */
180
- create(data: AgentCreate): Promise<Agent>;
181
- /**
182
- * Updates an existing agent.
183
- *
184
- * @param id Agent ID
185
- * @param data Updated agent data
186
- * @returns Updated agent
187
- */
188
- update(id: string, data: AgentUpdate): Promise<Agent>;
189
- /**
190
- * Marks an agent as live.
191
- *
192
- * @param id Agent ID
193
- * @returns Updated agent
194
- */
195
- markAsLive(id: string): Promise<Agent>;
196
- /**
197
- * Marks an agent as draft.
198
- *
199
- * @param id Agent ID
200
- * @returns Updated agent
201
- */
202
- markAsDraft(id: string): Promise<Agent>;
203
- /**
204
- * Marks an agent as archived.
205
- *
206
- * @param id Agent ID
207
- * @returns Updated agent
208
- */
209
- markAsArchived(id: string): Promise<Agent>;
210
- /**
211
- * Deletes an agent.
212
- *
213
- * @param id Agent ID
214
- */
215
- delete(id: string): Promise<Agent>;
216
- /**
217
- * Parses a list of agents with stringified config and blueprint fields.
218
- *
219
- * @returns List of parsed agents.
220
- */
221
- private static parseAgents;
222
- /**
223
- * Parses an agent with stringified config and blueprint fields.
224
- *
225
- * @returns Agent with parsed config and blueprint.
226
- */
227
- private static parseAgent;
478
+ interface components {
479
+ schemas: {
480
+ Error: {
481
+ /**
482
+ * @description Stable dot-notation error identifier, e.g. `resource.not_found`.
483
+ * Use this for programmatic handling; never parse `message`.
484
+ * @example resource.not_found
485
+ */
486
+ code: string
487
+ /** @description Localized, human-readable description of the error. */
488
+ message: string
489
+ /**
490
+ * Format: uri
491
+ * @description Link to the canonical documentation page for this error code.
492
+ * @example https://kivox.com.co/docs/reference/errors#resource-not-found
493
+ */
494
+ doc_url: string
495
+ /**
496
+ * @description Named interpolation values used to render `message`.
497
+ * Present only when the error carries contextual parameters.
498
+ */
499
+ params?: {
500
+ [key: string]: unknown
501
+ }
502
+ }
503
+ SignupRequest: {
504
+ /** Format: email */
505
+ email: string
506
+ password: string
507
+ name: string
508
+ }
509
+ LoginRequest: {
510
+ /** Format: email */
511
+ email: string
512
+ password: string
513
+ }
514
+ RecoverPasswordRequest: {
515
+ /** Format: email */
516
+ email: string
517
+ }
518
+ ResetPasswordRequest: {
519
+ token: string
520
+ password: string
521
+ }
522
+ /**
523
+ * @description Returned after a successful login or signup.
524
+ * The session token is delivered as an HttpOnly cookie (`kivox_session`),
525
+ * not in this response body.
526
+ */
527
+ AuthSessionResponse: {
528
+ /** Format: date-time */
529
+ expires_at: string
530
+ }
531
+ /** @description API key record. The raw key value is never returned after creation. */
532
+ AuthAPIKey: {
533
+ /** Format: uuid */
534
+ id: string
535
+ /** Format: uuid */
536
+ owner_user_id?: string
537
+ /** Format: uuid */
538
+ owner_org_id?: string
539
+ /** Format: uuid */
540
+ created_by_user_id: string
541
+ name: string
542
+ /** @example sk_live */
543
+ prefix: string
544
+ scopes: string[]
545
+ /** Format: date-time */
546
+ last_used_at?: string
547
+ /** Format: date-time */
548
+ expires_at?: string
549
+ /** Format: date-time */
550
+ created_at: string
551
+ }
552
+ /**
553
+ * @description Returned **once** when an API key is created.
554
+ * The `key` field contains the full raw value. Store it now, it will not be shown again.
555
+ */
556
+ AuthAPIKeyResponse: {
557
+ /** Format: uuid */
558
+ id: string
559
+ name: string
560
+ prefix: string
561
+ /**
562
+ * @description Full API key. Only present in this creation response.
563
+ * @example sk_live_xxxxxxxxxxxx
564
+ */
565
+ key: string
566
+ scopes: string[]
567
+ /** Format: date-time */
568
+ expires_at?: string
569
+ /** Format: date-time */
570
+ created_at: string
571
+ }
572
+ CreateAPIKeyRequest: {
573
+ name: string
574
+ scopes?: string[]
575
+ /** Format: date-time */
576
+ expires_at?: string
577
+ }
578
+ User: {
579
+ /** Format: uuid */
580
+ id: string
581
+ /** Format: email */
582
+ email: string
583
+ name: string
584
+ /** Format: uri */
585
+ avatar_url?: string
586
+ /** Format: date-time */
587
+ created_at: string
588
+ /** Format: date-time */
589
+ updated_at: string
590
+ }
591
+ UpdateUserRequest: {
592
+ name?: string
593
+ /** Format: uri */
594
+ avatar_url?: string
595
+ }
596
+ UpdateEmailRequest: {
597
+ /** Format: email */
598
+ email: string
599
+ }
600
+ Org: {
601
+ /** Format: uuid */
602
+ id: string
603
+ /** Format: uuid */
604
+ created_by?: string
605
+ name: string
606
+ description?: string
607
+ /** Format: uri */
608
+ avatar_url?: string
609
+ slug: string
610
+ tier: components["schemas"]["OrgTier"]
611
+ /** Format: date-time */
612
+ created_at: string
613
+ /** Format: date-time */
614
+ updated_at: string
615
+ }
616
+ OrgMember: {
617
+ /** Format: uuid */
618
+ org_id: string
619
+ /** Format: uuid */
620
+ user_id: string
621
+ role: components["schemas"]["MemberRole"]
622
+ /** Format: date-time */
623
+ created_at: string
624
+ /** Format: date-time */
625
+ updated_at: string
626
+ }
627
+ /**
628
+ * @description Role hierarchy (highest → lowest): `owner > admin > member > viewer`.
629
+ * @enum {string}
630
+ */
631
+ MemberRole: "owner" | "admin" | "member" | "viewer"
632
+ CreateOrgRequest: {
633
+ name: string
634
+ description?: string
635
+ slug: string
636
+ }
637
+ UpdateOrgRequest: {
638
+ name?: string
639
+ description?: string
640
+ /** Format: uri */
641
+ avatar_url?: string
642
+ }
643
+ AddMemberRequest: {
644
+ /** Format: uuid */
645
+ user_id: string
646
+ /** @enum {string} */
647
+ role: "admin" | "member" | "viewer"
648
+ }
649
+ UpdateMemberRequest: {
650
+ role: components["schemas"]["MemberRole"]
651
+ }
652
+ Agent: {
653
+ /** Format: uuid */
654
+ id: string
655
+ /** Format: uuid */
656
+ owner_user_id?: string
657
+ /** Format: uuid */
658
+ owner_org_id?: string
659
+ /** Format: uuid */
660
+ template_id?: string
661
+ config: components["schemas"]["AgentConfig"]
662
+ secrets: components["schemas"]["AgentSecret"][]
663
+ blueprint: components["schemas"]["Blueprint"]
664
+ status: components["schemas"]["AgentStatus"]
665
+ /** Format: date-time */
666
+ created_at: string
667
+ /** Format: date-time */
668
+ updated_at: string
669
+ }
670
+ /** @enum {string} */
671
+ AgentStatus: "draft" | "live" | "archived"
672
+ /** @enum {string} */
673
+ AgentLLMEngine: "deepseek" | "mistral" | "gemini" | "openai"
674
+ AgentConfig: {
675
+ /** Format: uri */
676
+ avatar_url?: string
677
+ name: string
678
+ description?: string
679
+ /** @example es */
680
+ language?: string
681
+ /** @example UTC */
682
+ timezone?: string
683
+ global_system_prompt?: string
684
+ max_session_duration_minutes?: number
685
+ max_silence_timeout_seconds?: number
686
+ allow_interruptions?: boolean
687
+ llm_engine?: components["schemas"]["AgentLLMEngine"]
688
+ llm_model?: string
689
+ }
690
+ AgentSecret: {
691
+ key: string
692
+ value: string
693
+ description?: string
694
+ }
695
+ AgentLintDiagnostics: {
696
+ errors: string[]
697
+ }
698
+ CreateAgentRequest: {
699
+ /** Format: uuid */
700
+ template_id?: string
701
+ config?: components["schemas"]["AgentConfig"]
702
+ secrets?: components["schemas"]["AgentSecret"][]
703
+ blueprint?: components["schemas"]["Blueprint"]
704
+ }
705
+ UpdateAgentRequest: {
706
+ config?: components["schemas"]["AgentConfig"]
707
+ secrets?: components["schemas"]["AgentSecret"][]
708
+ blueprint?: components["schemas"]["Blueprint"]
709
+ }
710
+ UpdateAgentStatusRequest: {
711
+ status: components["schemas"]["AgentStatus"]
712
+ }
713
+ LintAgentRequest: {
714
+ blueprint?: components["schemas"]["Blueprint"]
715
+ }
716
+ AgentPage: {
717
+ items: components["schemas"]["Agent"][]
718
+ total: number
719
+ limit: number
720
+ page: number
721
+ }
722
+ Blueprint: {
723
+ /** @default 1 */
724
+ version: string
725
+ entries: {
726
+ name: string
727
+ workflow: {
728
+ nodes: components["schemas"]["BlueprintNode"][]
729
+ edges: components["schemas"]["BlueprintEdge"][]
730
+ }
731
+ }[]
732
+ }
733
+ BlueprintNode: {
734
+ id: string
735
+ type: string
736
+ data: {
737
+ [key: string]: unknown
738
+ }
739
+ } & {
740
+ [key: string]: unknown
741
+ }
742
+ BlueprintEdge: {
743
+ source: string
744
+ target: string
745
+ } & {
746
+ [key: string]: unknown
747
+ }
748
+ Conversation: {
749
+ /** Format: uuid */
750
+ id: string
751
+ /** Format: uuid */
752
+ agent_id: string
753
+ status: components["schemas"]["ConversationStatus"]
754
+ summary?: string
755
+ /** Format: date-time */
756
+ started_at: string
757
+ /** Format: date-time */
758
+ ended_at?: string
759
+ end_reason?: components["schemas"]["ConversationEndReason"]
760
+ }
761
+ ConversationMessage: {
762
+ /** Format: uuid */
763
+ id: string
764
+ /** Format: uuid */
765
+ conversation_id: string
766
+ role: components["schemas"]["ConversationMessageRole"]
767
+ content: string
768
+ /** Format: date-time */
769
+ created_at: string
770
+ }
771
+ /** @enum {string} */
772
+ ConversationStatus: "active" | "ended"
773
+ /** @enum {string} */
774
+ ConversationEndReason: "user_exit" | "timeout" | "script_terminate" | "socket_shutdown" | "error" | "flow_end" | "client_end" | "agent_transfer"
775
+ /** @enum {string} */
776
+ ConversationMessageRole: "user" | "assistant" | "system" | "tool"
777
+ ConversationPage: {
778
+ items: components["schemas"]["Conversation"][]
779
+ next_cursor: string
780
+ has_more: boolean
781
+ }
782
+ ConversationMessagePage: {
783
+ items: components["schemas"]["ConversationMessage"][]
784
+ next_cursor: string
785
+ has_more: boolean
786
+ }
787
+ Template: {
788
+ /** Format: uuid */
789
+ id: string
790
+ /** Format: uuid */
791
+ owner_user_id?: string
792
+ /** Format: uuid */
793
+ owner_org_id?: string
794
+ name: string
795
+ description?: string
796
+ config: components["schemas"]["AgentConfig"]
797
+ blueprint: components["schemas"]["Blueprint"]
798
+ /** Format: date-time */
799
+ created_at: string
800
+ /** Format: date-time */
801
+ updated_at: string
802
+ }
803
+ CreateTemplateRequest: {
804
+ name: string
805
+ description?: string
806
+ config?: components["schemas"]["AgentConfig"]
807
+ secrets?: components["schemas"]["AgentSecret"][]
808
+ blueprint?: components["schemas"]["Blueprint"]
809
+ }
810
+ UpdateTemplateRequest: {
811
+ name?: string
812
+ description?: string
813
+ config?: components["schemas"]["AgentConfig"]
814
+ secrets?: components["schemas"]["AgentSecret"][]
815
+ blueprint?: components["schemas"]["Blueprint"]
816
+ }
817
+ TemplatePage: {
818
+ items: components["schemas"]["Template"][]
819
+ total: number
820
+ limit: number
821
+ page: number
822
+ }
823
+ /** @enum {string} */
824
+ OrgTier: "free" | "enterprise"
825
+ };
826
+ responses: {
827
+ /** @description Not authenticated. */
828
+ Unauthorized: {
829
+ headers: {
830
+ [name: string]: unknown
831
+ }
832
+ content: {
833
+ "application/json": components["schemas"]["Error"]
834
+ }
835
+ }
836
+ /** @description Insufficient permissions. */
837
+ Forbidden: {
838
+ headers: {
839
+ [name: string]: unknown
840
+ }
841
+ content: {
842
+ "application/json": components["schemas"]["Error"]
843
+ }
844
+ }
845
+ /** @description Resource not found. */
846
+ NotFound: {
847
+ headers: {
848
+ [name: string]: unknown
849
+ }
850
+ content: {
851
+ "application/json": components["schemas"]["Error"]
852
+ }
853
+ }
854
+ /** @description Resource already exists or state conflict. */
855
+ Conflict: {
856
+ headers: {
857
+ [name: string]: unknown
858
+ }
859
+ content: {
860
+ "application/json": components["schemas"]["Error"]
861
+ }
862
+ }
863
+ /** @description Request body failed validation. */
864
+ UnprocessableEntity: {
865
+ headers: {
866
+ [name: string]: unknown
867
+ }
868
+ content: {
869
+ "application/json": components["schemas"]["Error"]
870
+ }
871
+ }
872
+ /** @description An unexpected error occurred. */
873
+ DefaultError: {
874
+ headers: {
875
+ [name: string]: unknown
876
+ }
877
+ content: {
878
+ "application/json": components["schemas"]["Error"]
879
+ }
880
+ }
881
+ };
882
+ parameters: {
883
+ /** @description URL-safe organization identifier. */
884
+ OrgSlug: string
885
+ AgentID: string
886
+ KeyID: string
887
+ ConversationID: string
888
+ TemplateID: string
889
+ UserID: string
890
+ LimitParam: number
891
+ PageParam: number
892
+ /** @description Opaque cursor returned in the previous response's `next_cursor`. */
893
+ AfterParam: string
894
+ /** @description Full-text search filter. */
895
+ SearchParam: string
896
+ };
897
+ requestBodies: never;
898
+ headers: never;
899
+ pathItems: never;
228
900
  }
229
- /**
230
- * Configuration for WebSocket transport.
231
- */
232
- type WebSocketTransportConfig = {
233
- /** Base WebSocket URL */
234
- baseUrl: string
235
- /** Optional default headers (for protocol support) */
236
- headers?: Record<string, string>
237
- };
238
- /**
239
- * Shared WebSocket transport layer.
240
- * Provides WebSocket connection creation.
241
- */
242
- declare class WebSocketTransport {
243
- private readonly config;
244
- constructor(config: WebSocketTransportConfig);
245
- /**
246
- * Creates a WebSocket connection to the specified path.
247
- *
248
- * @param path WebSocket path (e.g., '/conversations/websocket')
249
- * @returns Raw WebSocket instance
250
- */
251
- connect(path: string): WebSocket;
901
+ interface operations {
902
+ signup: {
903
+ parameters: {
904
+ query?: never
905
+ header: {
906
+ /** @description Cloudflare Turnstile challenge token. */
907
+ "X-Turnstile-Token": string
908
+ }
909
+ path?: never
910
+ cookie?: never
911
+ }
912
+ requestBody: {
913
+ content: {
914
+ "application/json": components["schemas"]["SignupRequest"]
915
+ }
916
+ }
917
+ responses: {
918
+ /** @description Account created. Session cookie is set in `Set-Cookie`. */
919
+ 201: {
920
+ headers: {
921
+ "Set-Cookie"?: string
922
+ [name: string]: unknown
923
+ }
924
+ content: {
925
+ "application/json": components["schemas"]["AuthSessionResponse"]
926
+ }
927
+ }
928
+ default: components["responses"]["DefaultError"]
929
+ }
930
+ };
931
+ createSession: {
932
+ parameters: {
933
+ query?: never
934
+ header: {
935
+ "X-Turnstile-Token": string
936
+ }
937
+ path?: never
938
+ cookie?: never
939
+ }
940
+ requestBody: {
941
+ content: {
942
+ "application/json": components["schemas"]["LoginRequest"]
943
+ }
944
+ }
945
+ responses: {
946
+ /** @description Session created. Session cookie is set in `Set-Cookie`. */
947
+ 201: {
948
+ headers: {
949
+ "Set-Cookie"?: string
950
+ [name: string]: unknown
951
+ }
952
+ content: {
953
+ "application/json": components["schemas"]["AuthSessionResponse"]
954
+ }
955
+ }
956
+ default: components["responses"]["DefaultError"]
957
+ }
958
+ };
959
+ revokeAllSessions: {
960
+ parameters: {
961
+ query?: never
962
+ header?: never
963
+ path?: never
964
+ cookie?: never
965
+ }
966
+ requestBody?: never
967
+ responses: {
968
+ /** @description All sessions revoked. */
969
+ 204: {
970
+ headers: {
971
+ [name: string]: unknown
972
+ }
973
+ content?: never
974
+ }
975
+ default: components["responses"]["DefaultError"]
976
+ }
977
+ };
978
+ revokeSession: {
979
+ parameters: {
980
+ query?: never
981
+ header?: never
982
+ path?: never
983
+ cookie?: never
984
+ }
985
+ requestBody?: never
986
+ responses: {
987
+ /** @description Session revoked. */
988
+ 204: {
989
+ headers: {
990
+ [name: string]: unknown
991
+ }
992
+ content?: never
993
+ }
994
+ default: components["responses"]["DefaultError"]
995
+ }
996
+ };
997
+ recoverPassword: {
998
+ parameters: {
999
+ query?: never
1000
+ header: {
1001
+ "X-Turnstile-Token": string
1002
+ }
1003
+ path?: never
1004
+ cookie?: never
1005
+ }
1006
+ requestBody: {
1007
+ content: {
1008
+ "application/json": components["schemas"]["RecoverPasswordRequest"]
1009
+ }
1010
+ }
1011
+ responses: {
1012
+ /** @description Reset email sent (or silently dropped if email not found). */
1013
+ 204: {
1014
+ headers: {
1015
+ [name: string]: unknown
1016
+ }
1017
+ content?: never
1018
+ }
1019
+ default: components["responses"]["DefaultError"]
1020
+ }
1021
+ };
1022
+ resetPassword: {
1023
+ parameters: {
1024
+ query?: never
1025
+ header?: never
1026
+ path?: never
1027
+ cookie?: never
1028
+ }
1029
+ requestBody: {
1030
+ content: {
1031
+ "application/json": components["schemas"]["ResetPasswordRequest"]
1032
+ }
1033
+ }
1034
+ responses: {
1035
+ /** @description Password updated; all sessions revoked. */
1036
+ 204: {
1037
+ headers: {
1038
+ [name: string]: unknown
1039
+ }
1040
+ content?: never
1041
+ }
1042
+ default: components["responses"]["DefaultError"]
1043
+ }
1044
+ };
1045
+ listAPIKeys: {
1046
+ parameters: {
1047
+ query?: never
1048
+ header?: never
1049
+ path?: never
1050
+ cookie?: never
1051
+ }
1052
+ requestBody?: never
1053
+ responses: {
1054
+ /** @description OK */
1055
+ 200: {
1056
+ headers: {
1057
+ [name: string]: unknown
1058
+ }
1059
+ content: {
1060
+ "application/json": components["schemas"]["AuthAPIKey"][]
1061
+ }
1062
+ }
1063
+ default: components["responses"]["DefaultError"]
1064
+ }
1065
+ };
1066
+ createAPIKey: {
1067
+ parameters: {
1068
+ query?: never
1069
+ header?: never
1070
+ path?: never
1071
+ cookie?: never
1072
+ }
1073
+ requestBody: {
1074
+ content: {
1075
+ "application/json": components["schemas"]["CreateAPIKeyRequest"]
1076
+ }
1077
+ }
1078
+ responses: {
1079
+ /**
1080
+ * @description API key created. The `key` field contains the full raw value.
1081
+ * It will **not** be returned again.
1082
+ */
1083
+ 201: {
1084
+ headers: {
1085
+ [name: string]: unknown
1086
+ }
1087
+ content: {
1088
+ "application/json": components["schemas"]["AuthAPIKeyResponse"]
1089
+ }
1090
+ }
1091
+ default: components["responses"]["DefaultError"]
1092
+ }
1093
+ };
1094
+ revokeAPIKey: {
1095
+ parameters: {
1096
+ query?: never
1097
+ header?: never
1098
+ path: {
1099
+ keyID: components["parameters"]["KeyID"]
1100
+ }
1101
+ cookie?: never
1102
+ }
1103
+ requestBody?: never
1104
+ responses: {
1105
+ /** @description Key revoked. */
1106
+ 204: {
1107
+ headers: {
1108
+ [name: string]: unknown
1109
+ }
1110
+ content?: never
1111
+ }
1112
+ default: components["responses"]["DefaultError"]
1113
+ }
1114
+ };
1115
+ getMe: {
1116
+ parameters: {
1117
+ query?: never
1118
+ header?: never
1119
+ path?: never
1120
+ cookie?: never
1121
+ }
1122
+ requestBody?: never
1123
+ responses: {
1124
+ /** @description OK */
1125
+ 200: {
1126
+ headers: {
1127
+ [name: string]: unknown
1128
+ }
1129
+ content: {
1130
+ "application/json": components["schemas"]["User"]
1131
+ }
1132
+ }
1133
+ default: components["responses"]["DefaultError"]
1134
+ }
1135
+ };
1136
+ deleteMe: {
1137
+ parameters: {
1138
+ query?: never
1139
+ header?: never
1140
+ path?: never
1141
+ cookie?: never
1142
+ }
1143
+ requestBody?: never
1144
+ responses: {
1145
+ /** @description Account deleted. */
1146
+ 204: {
1147
+ headers: {
1148
+ [name: string]: unknown
1149
+ }
1150
+ content?: never
1151
+ }
1152
+ default: components["responses"]["DefaultError"]
1153
+ }
1154
+ };
1155
+ updateMe: {
1156
+ parameters: {
1157
+ query?: never
1158
+ header?: never
1159
+ path?: never
1160
+ cookie?: never
1161
+ }
1162
+ requestBody: {
1163
+ content: {
1164
+ "application/json": components["schemas"]["UpdateUserRequest"]
1165
+ }
1166
+ }
1167
+ responses: {
1168
+ /** @description Updated. */
1169
+ 200: {
1170
+ headers: {
1171
+ [name: string]: unknown
1172
+ }
1173
+ content: {
1174
+ "application/json": components["schemas"]["User"]
1175
+ }
1176
+ }
1177
+ default: components["responses"]["DefaultError"]
1178
+ }
1179
+ };
1180
+ updateMyEmail: {
1181
+ parameters: {
1182
+ query?: never
1183
+ header?: never
1184
+ path?: never
1185
+ cookie?: never
1186
+ }
1187
+ requestBody: {
1188
+ content: {
1189
+ "application/json": components["schemas"]["UpdateEmailRequest"]
1190
+ }
1191
+ }
1192
+ responses: {
1193
+ /** @description Email updated. */
1194
+ 200: {
1195
+ headers: {
1196
+ [name: string]: unknown
1197
+ }
1198
+ content: {
1199
+ "application/json": components["schemas"]["User"]
1200
+ }
1201
+ }
1202
+ default: components["responses"]["DefaultError"]
1203
+ }
1204
+ };
1205
+ listOrgs: {
1206
+ parameters: {
1207
+ query?: never
1208
+ header?: never
1209
+ path?: never
1210
+ cookie?: never
1211
+ }
1212
+ requestBody?: never
1213
+ responses: {
1214
+ /** @description OK */
1215
+ 200: {
1216
+ headers: {
1217
+ [name: string]: unknown
1218
+ }
1219
+ content: {
1220
+ "application/json": components["schemas"]["Org"][]
1221
+ }
1222
+ }
1223
+ default: components["responses"]["DefaultError"]
1224
+ }
1225
+ };
1226
+ createOrg: {
1227
+ parameters: {
1228
+ query?: never
1229
+ header?: never
1230
+ path?: never
1231
+ cookie?: never
1232
+ }
1233
+ requestBody: {
1234
+ content: {
1235
+ "application/json": components["schemas"]["CreateOrgRequest"]
1236
+ }
1237
+ }
1238
+ responses: {
1239
+ /** @description Organization created. */
1240
+ 201: {
1241
+ headers: {
1242
+ [name: string]: unknown
1243
+ }
1244
+ content: {
1245
+ "application/json": components["schemas"]["Org"]
1246
+ }
1247
+ }
1248
+ default: components["responses"]["DefaultError"]
1249
+ }
1250
+ };
1251
+ getOrg: {
1252
+ parameters: {
1253
+ query?: never
1254
+ header?: never
1255
+ path: {
1256
+ /** @description URL-safe organization identifier. */
1257
+ orgSlug: components["parameters"]["OrgSlug"]
1258
+ }
1259
+ cookie?: never
1260
+ }
1261
+ requestBody?: never
1262
+ responses: {
1263
+ /** @description OK */
1264
+ 200: {
1265
+ headers: {
1266
+ [name: string]: unknown
1267
+ }
1268
+ content: {
1269
+ "application/json": components["schemas"]["Org"]
1270
+ }
1271
+ }
1272
+ default: components["responses"]["DefaultError"]
1273
+ }
1274
+ };
1275
+ deleteOrg: {
1276
+ parameters: {
1277
+ query?: never
1278
+ header?: never
1279
+ path: {
1280
+ /** @description URL-safe organization identifier. */
1281
+ orgSlug: components["parameters"]["OrgSlug"]
1282
+ }
1283
+ cookie?: never
1284
+ }
1285
+ requestBody?: never
1286
+ responses: {
1287
+ /** @description Organization deleted. */
1288
+ 204: {
1289
+ headers: {
1290
+ [name: string]: unknown
1291
+ }
1292
+ content?: never
1293
+ }
1294
+ default: components["responses"]["DefaultError"]
1295
+ }
1296
+ };
1297
+ updateOrg: {
1298
+ parameters: {
1299
+ query?: never
1300
+ header?: never
1301
+ path: {
1302
+ /** @description URL-safe organization identifier. */
1303
+ orgSlug: components["parameters"]["OrgSlug"]
1304
+ }
1305
+ cookie?: never
1306
+ }
1307
+ requestBody: {
1308
+ content: {
1309
+ "application/json": components["schemas"]["UpdateOrgRequest"]
1310
+ }
1311
+ }
1312
+ responses: {
1313
+ /** @description Updated. */
1314
+ 200: {
1315
+ headers: {
1316
+ [name: string]: unknown
1317
+ }
1318
+ content: {
1319
+ "application/json": components["schemas"]["Org"]
1320
+ }
1321
+ }
1322
+ default: components["responses"]["DefaultError"]
1323
+ }
1324
+ };
1325
+ listOrgMembers: {
1326
+ parameters: {
1327
+ query?: never
1328
+ header?: never
1329
+ path: {
1330
+ /** @description URL-safe organization identifier. */
1331
+ orgSlug: components["parameters"]["OrgSlug"]
1332
+ }
1333
+ cookie?: never
1334
+ }
1335
+ requestBody?: never
1336
+ responses: {
1337
+ /** @description OK */
1338
+ 200: {
1339
+ headers: {
1340
+ [name: string]: unknown
1341
+ }
1342
+ content: {
1343
+ "application/json": components["schemas"]["OrgMember"][]
1344
+ }
1345
+ }
1346
+ default: components["responses"]["DefaultError"]
1347
+ }
1348
+ };
1349
+ addOrgMember: {
1350
+ parameters: {
1351
+ query?: never
1352
+ header?: never
1353
+ path: {
1354
+ /** @description URL-safe organization identifier. */
1355
+ orgSlug: components["parameters"]["OrgSlug"]
1356
+ }
1357
+ cookie?: never
1358
+ }
1359
+ requestBody: {
1360
+ content: {
1361
+ "application/json": components["schemas"]["AddMemberRequest"]
1362
+ }
1363
+ }
1364
+ responses: {
1365
+ /** @description Member added. */
1366
+ 201: {
1367
+ headers: {
1368
+ [name: string]: unknown
1369
+ }
1370
+ content: {
1371
+ "application/json": components["schemas"]["OrgMember"]
1372
+ }
1373
+ }
1374
+ default: components["responses"]["DefaultError"]
1375
+ }
1376
+ };
1377
+ removeOrgMember: {
1378
+ parameters: {
1379
+ query?: never
1380
+ header?: never
1381
+ path: {
1382
+ /** @description URL-safe organization identifier. */
1383
+ orgSlug: components["parameters"]["OrgSlug"]
1384
+ userID: components["parameters"]["UserID"]
1385
+ }
1386
+ cookie?: never
1387
+ }
1388
+ requestBody?: never
1389
+ responses: {
1390
+ /** @description Member removed. */
1391
+ 204: {
1392
+ headers: {
1393
+ [name: string]: unknown
1394
+ }
1395
+ content?: never
1396
+ }
1397
+ default: components["responses"]["DefaultError"]
1398
+ }
1399
+ };
1400
+ updateOrgMember: {
1401
+ parameters: {
1402
+ query?: never
1403
+ header?: never
1404
+ path: {
1405
+ /** @description URL-safe organization identifier. */
1406
+ orgSlug: components["parameters"]["OrgSlug"]
1407
+ userID: components["parameters"]["UserID"]
1408
+ }
1409
+ cookie?: never
1410
+ }
1411
+ requestBody: {
1412
+ content: {
1413
+ "application/json": components["schemas"]["UpdateMemberRequest"]
1414
+ }
1415
+ }
1416
+ responses: {
1417
+ /** @description Role updated. */
1418
+ 200: {
1419
+ headers: {
1420
+ [name: string]: unknown
1421
+ }
1422
+ content: {
1423
+ "application/json": components["schemas"]["OrgMember"]
1424
+ }
1425
+ }
1426
+ default: components["responses"]["DefaultError"]
1427
+ }
1428
+ };
1429
+ listUserAgents: {
1430
+ parameters: {
1431
+ query?: {
1432
+ limit?: components["parameters"]["LimitParam"]
1433
+ page?: components["parameters"]["PageParam"]
1434
+ /** @description Full-text search filter. */
1435
+ search?: components["parameters"]["SearchParam"]
1436
+ }
1437
+ header?: never
1438
+ path?: never
1439
+ cookie?: never
1440
+ }
1441
+ requestBody?: never
1442
+ responses: {
1443
+ /** @description OK */
1444
+ 200: {
1445
+ headers: {
1446
+ [name: string]: unknown
1447
+ }
1448
+ content: {
1449
+ "application/json": components["schemas"]["AgentPage"]
1450
+ }
1451
+ }
1452
+ default: components["responses"]["DefaultError"]
1453
+ }
1454
+ };
1455
+ createUserAgent: {
1456
+ parameters: {
1457
+ query?: never
1458
+ header?: never
1459
+ path?: never
1460
+ cookie?: never
1461
+ }
1462
+ requestBody: {
1463
+ content: {
1464
+ "application/json": components["schemas"]["CreateAgentRequest"]
1465
+ }
1466
+ }
1467
+ responses: {
1468
+ /** @description Agent created. */
1469
+ 201: {
1470
+ headers: {
1471
+ [name: string]: unknown
1472
+ }
1473
+ content: {
1474
+ "application/json": components["schemas"]["Agent"]
1475
+ }
1476
+ }
1477
+ default: components["responses"]["DefaultError"]
1478
+ }
1479
+ };
1480
+ listOrgAgents: {
1481
+ parameters: {
1482
+ query?: {
1483
+ limit?: components["parameters"]["LimitParam"]
1484
+ page?: components["parameters"]["PageParam"]
1485
+ /** @description Full-text search filter. */
1486
+ search?: components["parameters"]["SearchParam"]
1487
+ }
1488
+ header?: never
1489
+ path: {
1490
+ /** @description URL-safe organization identifier. */
1491
+ orgSlug: components["parameters"]["OrgSlug"]
1492
+ }
1493
+ cookie?: never
1494
+ }
1495
+ requestBody?: never
1496
+ responses: {
1497
+ /** @description OK */
1498
+ 200: {
1499
+ headers: {
1500
+ [name: string]: unknown
1501
+ }
1502
+ content: {
1503
+ "application/json": components["schemas"]["AgentPage"]
1504
+ }
1505
+ }
1506
+ default: components["responses"]["DefaultError"]
1507
+ }
1508
+ };
1509
+ createOrgAgent: {
1510
+ parameters: {
1511
+ query?: never
1512
+ header?: never
1513
+ path: {
1514
+ /** @description URL-safe organization identifier. */
1515
+ orgSlug: components["parameters"]["OrgSlug"]
1516
+ }
1517
+ cookie?: never
1518
+ }
1519
+ requestBody: {
1520
+ content: {
1521
+ "application/json": components["schemas"]["CreateAgentRequest"]
1522
+ }
1523
+ }
1524
+ responses: {
1525
+ /** @description Agent created. */
1526
+ 201: {
1527
+ headers: {
1528
+ [name: string]: unknown
1529
+ }
1530
+ content: {
1531
+ "application/json": components["schemas"]["Agent"]
1532
+ }
1533
+ }
1534
+ default: components["responses"]["DefaultError"]
1535
+ }
1536
+ };
1537
+ getAgent: {
1538
+ parameters: {
1539
+ query?: never
1540
+ header?: never
1541
+ path: {
1542
+ agentID: components["parameters"]["AgentID"]
1543
+ }
1544
+ cookie?: never
1545
+ }
1546
+ requestBody?: never
1547
+ responses: {
1548
+ /** @description OK */
1549
+ 200: {
1550
+ headers: {
1551
+ [name: string]: unknown
1552
+ }
1553
+ content: {
1554
+ "application/json": components["schemas"]["Agent"]
1555
+ }
1556
+ }
1557
+ default: components["responses"]["DefaultError"]
1558
+ }
1559
+ };
1560
+ deleteAgent: {
1561
+ parameters: {
1562
+ query?: never
1563
+ header?: never
1564
+ path: {
1565
+ agentID: components["parameters"]["AgentID"]
1566
+ }
1567
+ cookie?: never
1568
+ }
1569
+ requestBody?: never
1570
+ responses: {
1571
+ /** @description Agent deleted. */
1572
+ 204: {
1573
+ headers: {
1574
+ [name: string]: unknown
1575
+ }
1576
+ content?: never
1577
+ }
1578
+ default: components["responses"]["DefaultError"]
1579
+ }
1580
+ };
1581
+ updateAgent: {
1582
+ parameters: {
1583
+ query?: never
1584
+ header?: never
1585
+ path: {
1586
+ agentID: components["parameters"]["AgentID"]
1587
+ }
1588
+ cookie?: never
1589
+ }
1590
+ requestBody: {
1591
+ content: {
1592
+ "application/json": components["schemas"]["UpdateAgentRequest"]
1593
+ }
1594
+ }
1595
+ responses: {
1596
+ /** @description Updated. */
1597
+ 200: {
1598
+ headers: {
1599
+ [name: string]: unknown
1600
+ }
1601
+ content: {
1602
+ "application/json": components["schemas"]["Agent"]
1603
+ }
1604
+ }
1605
+ default: components["responses"]["DefaultError"]
1606
+ }
1607
+ };
1608
+ updateAgentStatus: {
1609
+ parameters: {
1610
+ query?: never
1611
+ header?: never
1612
+ path: {
1613
+ agentID: components["parameters"]["AgentID"]
1614
+ }
1615
+ cookie?: never
1616
+ }
1617
+ requestBody: {
1618
+ content: {
1619
+ "application/json": components["schemas"]["UpdateAgentStatusRequest"]
1620
+ }
1621
+ }
1622
+ responses: {
1623
+ /** @description Status updated. */
1624
+ 200: {
1625
+ headers: {
1626
+ [name: string]: unknown
1627
+ }
1628
+ content: {
1629
+ "application/json": components["schemas"]["Agent"]
1630
+ }
1631
+ }
1632
+ default: components["responses"]["DefaultError"]
1633
+ }
1634
+ };
1635
+ lintAgent: {
1636
+ parameters: {
1637
+ query?: never
1638
+ header?: never
1639
+ path: {
1640
+ agentID: components["parameters"]["AgentID"]
1641
+ }
1642
+ cookie?: never
1643
+ }
1644
+ requestBody: {
1645
+ content: {
1646
+ "application/json": components["schemas"]["LintAgentRequest"]
1647
+ }
1648
+ }
1649
+ responses: {
1650
+ /** @description Lint result. An empty `errors` array means the blueprint is valid. */
1651
+ 200: {
1652
+ headers: {
1653
+ [name: string]: unknown
1654
+ }
1655
+ content: {
1656
+ "application/json": components["schemas"]["AgentLintDiagnostics"]
1657
+ }
1658
+ }
1659
+ default: components["responses"]["DefaultError"]
1660
+ }
1661
+ };
1662
+ listAgentConversations: {
1663
+ parameters: {
1664
+ query?: {
1665
+ /** @description Opaque cursor returned in the previous response's `next_cursor`. */
1666
+ after?: components["parameters"]["AfterParam"]
1667
+ limit?: components["parameters"]["LimitParam"]
1668
+ }
1669
+ header?: never
1670
+ path: {
1671
+ agentID: components["parameters"]["AgentID"]
1672
+ }
1673
+ cookie?: never
1674
+ }
1675
+ requestBody?: never
1676
+ responses: {
1677
+ /** @description OK */
1678
+ 200: {
1679
+ headers: {
1680
+ [name: string]: unknown
1681
+ }
1682
+ content: {
1683
+ "application/json": components["schemas"]["ConversationPage"]
1684
+ }
1685
+ }
1686
+ default: components["responses"]["DefaultError"]
1687
+ }
1688
+ };
1689
+ getConversation: {
1690
+ parameters: {
1691
+ query?: never
1692
+ header?: never
1693
+ path: {
1694
+ conversationID: components["parameters"]["ConversationID"]
1695
+ }
1696
+ cookie?: never
1697
+ }
1698
+ requestBody?: never
1699
+ responses: {
1700
+ /** @description OK */
1701
+ 200: {
1702
+ headers: {
1703
+ [name: string]: unknown
1704
+ }
1705
+ content: {
1706
+ "application/json": components["schemas"]["Conversation"]
1707
+ }
1708
+ }
1709
+ default: components["responses"]["DefaultError"]
1710
+ }
1711
+ };
1712
+ deleteConversation: {
1713
+ parameters: {
1714
+ query?: never
1715
+ header?: never
1716
+ path: {
1717
+ conversationID: components["parameters"]["ConversationID"]
1718
+ }
1719
+ cookie?: never
1720
+ }
1721
+ requestBody?: never
1722
+ responses: {
1723
+ /** @description Conversation deleted. */
1724
+ 204: {
1725
+ headers: {
1726
+ [name: string]: unknown
1727
+ }
1728
+ content?: never
1729
+ }
1730
+ default: components["responses"]["DefaultError"]
1731
+ }
1732
+ };
1733
+ listConversationMessages: {
1734
+ parameters: {
1735
+ query?: {
1736
+ /** @description Opaque cursor returned in the previous response's `next_cursor`. */
1737
+ after?: components["parameters"]["AfterParam"]
1738
+ limit?: components["parameters"]["LimitParam"]
1739
+ }
1740
+ header?: never
1741
+ path: {
1742
+ conversationID: components["parameters"]["ConversationID"]
1743
+ }
1744
+ cookie?: never
1745
+ }
1746
+ requestBody?: never
1747
+ responses: {
1748
+ /** @description OK */
1749
+ 200: {
1750
+ headers: {
1751
+ [name: string]: unknown
1752
+ }
1753
+ content: {
1754
+ "application/json": components["schemas"]["ConversationMessagePage"]
1755
+ }
1756
+ }
1757
+ default: components["responses"]["DefaultError"]
1758
+ }
1759
+ };
1760
+ listUserTemplates: {
1761
+ parameters: {
1762
+ query?: {
1763
+ limit?: components["parameters"]["LimitParam"]
1764
+ page?: components["parameters"]["PageParam"]
1765
+ }
1766
+ header?: never
1767
+ path?: never
1768
+ cookie?: never
1769
+ }
1770
+ requestBody?: never
1771
+ responses: {
1772
+ /** @description OK */
1773
+ 200: {
1774
+ headers: {
1775
+ [name: string]: unknown
1776
+ }
1777
+ content: {
1778
+ "application/json": components["schemas"]["TemplatePage"]
1779
+ }
1780
+ }
1781
+ default: components["responses"]["DefaultError"]
1782
+ }
1783
+ };
1784
+ createUserTemplate: {
1785
+ parameters: {
1786
+ query?: never
1787
+ header?: never
1788
+ path?: never
1789
+ cookie?: never
1790
+ }
1791
+ requestBody: {
1792
+ content: {
1793
+ "application/json": components["schemas"]["CreateTemplateRequest"]
1794
+ }
1795
+ }
1796
+ responses: {
1797
+ /** @description Template created. */
1798
+ 201: {
1799
+ headers: {
1800
+ [name: string]: unknown
1801
+ }
1802
+ content: {
1803
+ "application/json": components["schemas"]["Template"]
1804
+ }
1805
+ }
1806
+ default: components["responses"]["DefaultError"]
1807
+ }
1808
+ };
1809
+ listOrgTemplates: {
1810
+ parameters: {
1811
+ query?: {
1812
+ limit?: components["parameters"]["LimitParam"]
1813
+ page?: components["parameters"]["PageParam"]
1814
+ }
1815
+ header?: never
1816
+ path: {
1817
+ /** @description URL-safe organization identifier. */
1818
+ orgSlug: components["parameters"]["OrgSlug"]
1819
+ }
1820
+ cookie?: never
1821
+ }
1822
+ requestBody?: never
1823
+ responses: {
1824
+ /** @description OK */
1825
+ 200: {
1826
+ headers: {
1827
+ [name: string]: unknown
1828
+ }
1829
+ content: {
1830
+ "application/json": components["schemas"]["TemplatePage"]
1831
+ }
1832
+ }
1833
+ default: components["responses"]["DefaultError"]
1834
+ }
1835
+ };
1836
+ createOrgTemplate: {
1837
+ parameters: {
1838
+ query?: never
1839
+ header?: never
1840
+ path: {
1841
+ /** @description URL-safe organization identifier. */
1842
+ orgSlug: components["parameters"]["OrgSlug"]
1843
+ }
1844
+ cookie?: never
1845
+ }
1846
+ requestBody: {
1847
+ content: {
1848
+ "application/json": components["schemas"]["CreateTemplateRequest"]
1849
+ }
1850
+ }
1851
+ responses: {
1852
+ /** @description Template created. */
1853
+ 201: {
1854
+ headers: {
1855
+ [name: string]: unknown
1856
+ }
1857
+ content: {
1858
+ "application/json": components["schemas"]["Template"]
1859
+ }
1860
+ }
1861
+ default: components["responses"]["DefaultError"]
1862
+ }
1863
+ };
1864
+ getTemplate: {
1865
+ parameters: {
1866
+ query?: never
1867
+ header?: never
1868
+ path: {
1869
+ templateID: components["parameters"]["TemplateID"]
1870
+ }
1871
+ cookie?: never
1872
+ }
1873
+ requestBody?: never
1874
+ responses: {
1875
+ /** @description OK */
1876
+ 200: {
1877
+ headers: {
1878
+ [name: string]: unknown
1879
+ }
1880
+ content: {
1881
+ "application/json": components["schemas"]["Template"]
1882
+ }
1883
+ }
1884
+ default: components["responses"]["DefaultError"]
1885
+ }
1886
+ };
1887
+ deleteTemplate: {
1888
+ parameters: {
1889
+ query?: never
1890
+ header?: never
1891
+ path: {
1892
+ templateID: components["parameters"]["TemplateID"]
1893
+ }
1894
+ cookie?: never
1895
+ }
1896
+ requestBody?: never
1897
+ responses: {
1898
+ /** @description Template deleted. */
1899
+ 204: {
1900
+ headers: {
1901
+ [name: string]: unknown
1902
+ }
1903
+ content?: never
1904
+ }
1905
+ default: components["responses"]["DefaultError"]
1906
+ }
1907
+ };
1908
+ updateTemplate: {
1909
+ parameters: {
1910
+ query?: never
1911
+ header?: never
1912
+ path: {
1913
+ templateID: components["parameters"]["TemplateID"]
1914
+ }
1915
+ cookie?: never
1916
+ }
1917
+ requestBody: {
1918
+ content: {
1919
+ "application/json": components["schemas"]["UpdateTemplateRequest"]
1920
+ }
1921
+ }
1922
+ responses: {
1923
+ /** @description Updated. */
1924
+ 200: {
1925
+ headers: {
1926
+ [name: string]: unknown
1927
+ }
1928
+ content: {
1929
+ "application/json": components["schemas"]["Template"]
1930
+ }
1931
+ }
1932
+ default: components["responses"]["DefaultError"]
1933
+ }
1934
+ };
252
1935
  }
253
1936
  /**
254
- * Represents a handshake offer initiated by the client.
1937
+ * Initializes a new conversational session.
1938
+ * It must be the first message sent after connection establishment.
255
1939
  */
256
- type ClientSessionHandshakeOffer = {
257
- type: "session.handshake.offer"
1940
+ type ClientHandshake = {
1941
+ type: "handshake"
258
1942
  agent_id: string
1943
+ channel?: "web-text" | "web-voice" | "mobile-text" | "mobile-voice" | (string & {})
1944
+ render_directive?: string
259
1945
  };
260
1946
  /**
261
- * Signals that the client has ended the session.
262
- */
263
- type ClientSessionEnd = {
264
- type: "session.end"
265
- conversation_id: string
266
- };
267
- /**
268
- * Sends a text input from the client to the server.
1947
+ * Carries a single user text message.
269
1948
  */
270
1949
  type ClientInputText = {
271
- type: "input.text"
272
- conversation_id: string
1950
+ type: "input_text"
273
1951
  text: string
274
1952
  };
275
1953
  /**
276
- * Indicates that the client is starting an audio input.
1954
+ * Signals that audio input will begin.
1955
+ * Typically followed by one or more binary WebSocket frames.
277
1956
  */
278
1957
  type ClientInputAudio = {
279
- type: "input.audio"
280
- conversation_id: string
1958
+ type: "input_audio"
281
1959
  };
282
1960
  /**
283
- * Represents a continuous stream of audio data from the client.
1961
+ * Signals that a streamed audio chunk will follow in the next binary frame.
284
1962
  */
285
1963
  type ClientInputAudioStream = {
286
- type: "input.audio.stream"
287
- conversation_id: string
1964
+ type: "input_audio_stream"
288
1965
  };
289
1966
  /**
290
- * Signals that the client has cancelled a request.
1967
+ * Requests interruption of the current streaming response.
291
1968
  */
292
- type ClientRequestCancel = {
293
- type: "request.cancel"
294
- conversation_id: string
1969
+ type ClientCancel = {
1970
+ type: "cancel"
295
1971
  };
296
1972
  /**
297
- * Union type for all messages sent from the client to the server.
1973
+ * Requests graceful session termination.
298
1974
  */
299
- type ClientMessage = ClientSessionHandshakeOffer | ClientSessionEnd | ClientInputText | ClientInputAudio | ClientInputAudioStream | ClientRequestCancel;
300
- /**
301
- * Sent by the server when a handshake offer is accepted.
302
- */
303
- type ServerSessionHandshakeAccept = {
304
- type: "session.handshake.accept"
305
- agent_id: string
306
- conversation_id: string
1975
+ type ClientEndSession = {
1976
+ type: "end"
307
1977
  };
308
1978
  /**
309
- * Sent by the server when a handshake offer is rejected.
1979
+ * Union type for all JSON messages sent from the client to the server.
310
1980
  */
311
- type ServerSessionHandshakeReject = {
312
- type: "session.handshake.reject"
313
- reason: string
314
- };
1981
+ type ClientMessage = ClientHandshake | ClientInputText | ClientInputAudio | ClientInputAudioStream | ClientCancel | ClientEndSession;
315
1982
  /**
316
- * Signals that the session has officially started.
1983
+ * Confirms successful session initialization.
317
1984
  */
318
- type ServerSessionStart = {
319
- type: "session.start"
1985
+ type ServerHandshakeOK = {
1986
+ type: "handshake_ok"
320
1987
  conversation_id: string
321
- start_time: number
322
- end_time: number
323
- max_duration_ms: number
324
1988
  };
325
1989
  /**
326
- * Signals that the server has ended the session.
1990
+ * Indicates that the session could not be created.
327
1991
  */
328
- type ServerSessionEnd = {
329
- type: "session.end"
330
- conversation_id: string
1992
+ type ServerHandshakeError = {
1993
+ type: "handshake_error"
1994
+ reason: string
331
1995
  };
332
1996
  /**
333
- * Periodic update from the server regarding session timing.
1997
+ * Carries a full text message generated by the runtime.
334
1998
  */
335
- type ServerSessionTick = {
336
- type: "session.tick"
337
- conversation_id: string
338
- max_duration_ms: number
339
- remaining_time_ms: number
340
- elapsed_time_ms: number
1999
+ type ServerTextFull = {
2000
+ type: "text_full"
2001
+ content: string
341
2002
  };
342
2003
  /**
343
- * Sent when a session ends due to inactivity or exceeding max duration.
2004
+ * Carries a streamed text fragment generated by the runtime.
344
2005
  */
345
- type ServerSessionTimeout = {
346
- type: "session.timeout"
347
- conversation_id: string
2006
+ type ServerTextDelta = {
2007
+ type: "text_delta"
2008
+ chunk: string
348
2009
  };
349
2010
  /**
350
- * Signals that the server has detected the start of speech.
2011
+ * Carries metadata for a streamed audio fragment generated by the runtime.
2012
+ * The actual binary audio data is delivered in the immediately following binary frame
2013
+ * and merged into this object by the transport layer.
351
2014
  */
352
- type ServerSpeechStart = {
353
- type: "speech.start"
354
- conversation_id: string
2015
+ type ServerAudioDelta = {
2016
+ type: "audio_delta"
2017
+ /** Expected size of the incoming binary payload in bytes */
2018
+ size: number
2019
+ /** The binary audio data attached dynamically by the transport layer */
2020
+ audio: Blob
355
2021
  };
356
2022
  /**
357
- * Signals that the server has detected the end of speech.
2023
+ * Signals that the runtime has completed its turn and is awaiting further user input.
358
2024
  */
359
- type ServerSpeechEnd = {
360
- type: "speech.end"
361
- conversation_id: string
2025
+ type ServerTurnComplete = {
2026
+ type: "turn_complete"
362
2027
  };
363
2028
  /**
364
- * A partial text response chunk sent by the server.
2029
+ * Signals that the conversation flow reached its exit node.
2030
+ * The session will close shortly after this event.
365
2031
  */
366
- type ServerResponseDeltaText = {
367
- type: "response.delta.text"
368
- conversation_id: string
369
- chunk: string
2032
+ type ServerFlowComplete = {
2033
+ type: "flow_complete"
370
2034
  };
371
2035
  /**
372
- * A partial audio response chunk sent by the server.
2036
+ * Relays a signal from the runtime to the client.
373
2037
  */
374
- type ServerResponseDeltaAudio = {
375
- type: "response.delta.audio"
376
- conversation_id: string
377
- size: number
378
- audio: Blob
379
- };
380
- /**
381
- * Signals that the full response (text or audio) has been delivered.
382
- */
383
- type ServerResponseComplete = {
384
- type: "response.complete"
385
- conversation_id: string
2038
+ type ServerSignal = {
2039
+ type: "signal"
2040
+ name: string
2041
+ data: Record<string, unknown>
386
2042
  };
387
2043
  /**
388
- * Sent when an ongoing response is cancelled successfully.
2044
+ * Indicates that the session is being transferred to another agent.
2045
+ * The client should initiate a new session with the provided AgentID.
389
2046
  */
390
- type ServerResponseCancel = {
391
- type: "response.cancel"
392
- conversation_id: string
2047
+ type ServerTransfer = {
2048
+ type: "transfer"
2049
+ agent_id: string
2050
+ reason: string
393
2051
  };
394
2052
  /**
395
- * Sent when an error occurs during processing a request.
2053
+ * Represents a non-fatal execution or protocol error.
2054
+ * The session remains active unless followed by a SessionClosed event.
396
2055
  */
397
- type ServerResponseError = {
398
- type: "response.error"
399
- conversation_id: string
2056
+ type ServerError = {
2057
+ type: "error"
400
2058
  code: string
401
2059
  message: string
402
2060
  };
403
2061
  /**
404
- * Union type for all messages sent from the server to the client.
2062
+ * Provides periodic timing information for the active session.
405
2063
  */
406
- type ServerMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart | ServerSessionEnd | ServerSessionTick | ServerSessionTimeout | ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
2064
+ type ServerTick = {
2065
+ type: "tick"
2066
+ /** Milliseconds until the session times out */
2067
+ remaining_ms: number
2068
+ /** Milliseconds elapsed since the session started */
2069
+ elapsed_ms: number
2070
+ };
407
2071
  /**
408
- * Union type for all messages sent from the client to the server before the session is established.
2072
+ * Indicates that the session is closing.
409
2073
  */
410
- type ServerConnectionMessage = ServerSessionHandshakeAccept | ServerSessionHandshakeReject | ServerSessionStart;
2074
+ type ServerSessionClosed = {
2075
+ type: "session_closed"
2076
+ reason: string
2077
+ };
411
2078
  /**
412
- * Union type for all messages sent from the server to the client during the session lifecycle.
2079
+ * Union type for all messages sent from the server to the client.
413
2080
  */
414
- type ServerSessionLifecycleMessage = ServerSessionEnd | ServerSessionTick | ServerSessionTimeout;
2081
+ type ServerMessage = ServerHandshakeOK | ServerHandshakeError | ServerTextFull | ServerTextDelta | ServerAudioDelta | ServerTurnComplete | ServerFlowComplete | ServerSignal | ServerTransfer | ServerError | ServerTick | ServerSessionClosed;
415
2082
  /**
416
- * Union type for all messages sent from the server to the client during the session activity.
2083
+ * Messages related to the initial connection phase.
417
2084
  */
418
- type ServerSessionActivityMessage = ServerSpeechStart | ServerSpeechEnd | ServerResponseDeltaText | ServerResponseDeltaAudio | ServerResponseComplete | ServerResponseCancel | ServerResponseError;
2085
+ type ServerConnectionMessage = ServerHandshakeOK | ServerHandshakeError;
419
2086
  /**
420
- * Synthetic event emitted when the connection to the server is lost.
2087
+ * Synthetic event emitted when the WebSocket connection to the server drops unexpectedly.
421
2088
  */
422
2089
  type SessionConnectionLostEvent = {
423
- type: "session.connection.lost"
424
- conversation_id: string
2090
+ type: "connection_lost"
425
2091
  reason: "socket_closed" | "socket_error"
426
2092
  };
427
2093
  /**
428
- * Events emitted during an active session
429
- *
430
- * @remarks
431
- * Connection messages are handled internally during connection establishment
432
- * and are not exposed through the session's `onEvent` callback.
2094
+ * Union type of all events that can be emitted during an active conversation session.
433
2095
  */
434
- type ServerSessionEvent = ServerSessionLifecycleMessage | ServerSessionActivityMessage | SessionConnectionLostEvent;
2096
+ type ServerSessionEvent = ServerTextFull | ServerTextDelta | ServerAudioDelta | ServerTurnComplete | ServerFlowComplete | ServerSignal | ServerTransfer | ServerError | ServerTick | ServerSessionClosed | SessionConnectionLostEvent;
435
2097
  /**
436
- * Error thrown by the transport layer.
2098
+ * Error thrown by the transport layer when connection or state issues occur.
437
2099
  */
438
2100
  declare class ConversationTransportError extends Error {
439
2101
  readonly code: string;
440
2102
  constructor(message: string, code?: string);
441
2103
  }
442
2104
  /**
443
- * Low-level WebSocket transport for conversation protocol.
444
- * Handles connection lifecycle and binary/JSON message routing.
2105
+ * Low-level WebSocket transport for the conversation protocol.
2106
+ * Handles connection lifecycle and distinct routing for JSON and binary messages.
445
2107
  */
446
2108
  declare class ConversationTransport {
447
2109
  private;
@@ -451,356 +2113,238 @@ declare class ConversationTransport {
451
2113
  private _onBinary;
452
2114
  private _onError;
453
2115
  private _onClose;
2116
+ /**
2117
+ * Creates a new ConversationTransport.
2118
+ * @param _ws The underlying WebSocket instance to wrap.
2119
+ */
454
2120
  constructor(_ws: WebSocket);
455
2121
  /**
456
- * Waits for WebSocket to open.
457
- * @throws {ConversationTransportError} If already connected or connection fails
2122
+ * Waits for the WebSocket connection to fully open.
2123
+ * @throws {ConversationTransportError} If the socket is already connected, closing, or fails to connect.
458
2124
  */
459
2125
  connect(): Promise<void>;
460
2126
  /**
461
- * Sends a JSON message to the server.
462
- * @throws {ConversationTransportError} If not connected
2127
+ * Sends a structured JSON message to the server.
2128
+ * @param message The client message to send.
2129
+ * @throws {ConversationTransportError} If the WebSocket is not currently open.
463
2130
  */
464
2131
  send(message: ClientMessage): void;
465
2132
  /**
466
- * Sends binary data (audio) to the server.
467
- * @throws {ConversationTransportError} If not connected
2133
+ * Sends binary data (like raw audio) to the server via a pure binary WebSocket frame.
2134
+ * @param data The Blob representing the binary data.
2135
+ * @throws {ConversationTransportError} If the WebSocket is not currently open.
468
2136
  */
469
2137
  sendBinary(data: Blob): Promise<void>;
470
2138
  /**
471
- * Registers a callback for incoming JSON messages.
2139
+ * Registers a callback to be invoked when a JSON message is received from the server.
2140
+ * @param handler The callback function.
472
2141
  */
473
2142
  onMessage(handler: (msg: ServerMessage) => void): void;
474
2143
  /**
475
- * Registers a callback for incoming binary data.
2144
+ * Registers a callback to be invoked when a pure binary frame is received from the server.
2145
+ * @param handler The callback function.
476
2146
  */
477
2147
  onBinary(handler: (blob: Blob) => void): void;
478
2148
  /**
479
- * Registers a callback for connection errors.
2149
+ * Registers a callback to be invoked if a WebSocket error occurs.
2150
+ * @param handler The callback function.
480
2151
  */
481
2152
  onError(handler: (error: Error) => void): void;
482
2153
  /**
483
- * Registers a callback for connection closure.
2154
+ * Registers a callback to be invoked when the WebSocket connection is closed.
2155
+ * @param handler The callback function.
484
2156
  */
485
2157
  onClose(handler: () => void): void;
486
2158
  /**
487
- * Closes the WebSocket connection and cleans up resources.
2159
+ * Closes the underlying WebSocket connection and cleans up resources.
488
2160
  */
489
2161
  close(): void;
490
2162
  }
491
2163
  /**
492
- * Configuration for a conversation session.
2164
+ * Configuration options provided when establishing a conversation session.
493
2165
  */
494
2166
  type ConversationSessionConfig = {
495
2167
  /**
496
- * Event handler for all server messages.
2168
+ * A callback function invoked whenever an event is emitted by the server during the session.
497
2169
  *
498
2170
  * @remarks
499
- * Important: `response.delta.audio` events combine the audio `Blob` and the metadata.
2171
+ * For `audio_delta` events, the SDK automatically waits for the subsequent binary WebSocket frame
2172
+ * and attaches the resulting `Blob` to the event object before triggering this callback.
500
2173
  */
501
2174
  onEvent?: (event: ServerSessionEvent) => void
502
2175
  };
503
2176
  /**
504
- * Represents an active conversation session with a KIVOX agent.
505
- * Provides methods to send messages and audio, and a callback to handle all server events.
2177
+ * Represents an active, real-time conversation session with a Kivox agent.
2178
+ * Provides methods to dispatch user inputs and lifecycle commands, as well as tracking basic session state.
506
2179
  */
507
2180
  declare class ConversationSession {
508
2181
  private;
509
2182
  private _transport;
510
2183
  private _conversationId;
511
- private _maxDurationMs;
512
- private _startTime;
513
- private _endTime;
514
2184
  private _closed;
515
- private _pendingAudioMetadata;
516
2185
  private _onEvent;
517
- /** The unique conversation identifier */
2186
+ private _pendingAudioMetadata;
2187
+ private _remainingMs;
2188
+ private _elapsedMs;
2189
+ /**
2190
+ * The unique server-generated ID for this active conversation.
2191
+ */
518
2192
  get conversationId(): string;
519
- /** Maximum session duration in milliseconds */
520
- get maxDurationMs(): number;
521
- /** Unix timestamp when session started */
522
- get startTime(): number;
523
- /** Unix timestamp when session will end */
524
- get endTime(): number;
525
- /** Whether the session has been closed */
2193
+ /**
2194
+ * The number of milliseconds remaining until the engine enforces a session timeout.
2195
+ * This value is periodically synced via server 'tick' events.
2196
+ */
2197
+ get remainingMs(): number;
2198
+ /**
2199
+ * The number of milliseconds elapsed since the session was initiated.
2200
+ * This value is periodically synced via server 'tick' events.
2201
+ */
2202
+ get elapsedMs(): number;
2203
+ /**
2204
+ * Indicates whether the session has been permanently closed.
2205
+ */
526
2206
  get closed(): boolean;
527
- constructor(transport: ConversationTransport, conversationId: string, maxDurationMs: number, startTime: number, endTime: number, config: ConversationSessionConfig);
528
2207
  /**
529
- * Sends a text message to the agent.
530
- * @param text The message text to send
2208
+ * Constructs a new active ConversationSession.
2209
+ * Normally called internally by `ConversationClient.connect()`.
2210
+ *
2211
+ * @param transport The underlying active WebSocket transport.
2212
+ * @param conversationId The ID assigned by the server during the handshake.
2213
+ * @param config User-provided configuration options (e.g., event handlers).
2214
+ */
2215
+ constructor(transport: ConversationTransport, conversationId: string, config: ConversationSessionConfig);
2216
+ /**
2217
+ * Sends a single textual user input to the agent.
2218
+ *
2219
+ * @param text The textual payload provided by the user.
531
2220
  */
532
2221
  sendText(text: string): void;
533
2222
  /**
534
- * Sends a complete audio message to the agent.
535
- * @param audio Audio blob to send
2223
+ * Sends a complete, recorded audio buffer to the agent.
2224
+ * First sends an `input_audio` header, then dispatches the binary frame.
2225
+ *
2226
+ * @param audio The raw binary audio file/buffer.
536
2227
  */
537
2228
  sendAudio(audio: Blob): void;
538
2229
  /**
539
- * Streams an audio chunk to the agent (for real-time audio input).
540
- * @param chunk Audio chunk to stream
2230
+ * Streams a fragment of real-time audio to the agent.
2231
+ * First sends an `input_audio_stream` header, then dispatches the binary frame.
2232
+ *
2233
+ * @param chunk The raw binary audio fragment.
541
2234
  */
542
2235
  streamAudio(chunk: Blob): void;
543
2236
  /**
544
- * Requests the session to be cancelled.
545
- * The 'session.cancel' event will be triggered when complete.
2237
+ * Requests that the server immediately halt the currently streaming assistant response.
2238
+ * The session remains open and the agent will await the next user input.
546
2239
  */
547
2240
  cancelRequest(): void;
548
2241
  /**
549
- * Requests the session to end gracefully.
550
- * The 'session.end' event will be triggered when complete.
2242
+ * Instructs the server to gracefully terminate the conversation.
2243
+ * Wait for the resulting `session_closed` event to confirm termination.
551
2244
  */
552
2245
  end(): void;
553
2246
  /**
554
- * Immediately closes the session and transport.
555
- * No further events will be received.
2247
+ * Immediately tears down the underlying WebSocket transport and marks the session closed locally.
2248
+ * Does not wait for a graceful server acknowledgment.
556
2249
  */
557
2250
  close(): void;
558
2251
  }
559
- type Conversation = {
560
- id: string
561
- agent_id: string
562
- started_at: Date
563
- ended_at?: Date
564
- };
565
- /**
566
- * Configuration for listing conversations.
567
- */
568
- type ConversationListParams = {
569
- /** Agent ID to filter by */
570
- agentId: string
571
- /** Number of results per page */
572
- limit?: number
573
- /** Page number (1-indexed) */
574
- page?: number
575
- };
576
- /**
577
- * Extended configuration for the connect method.
578
- */
579
- type ConversationConnectParams = ConversationSessionConfig & {
580
- /** Agent ID to connect to */
581
- agentId: string
582
- /**
583
- * Optional callback for connection events.
584
- * Called during connection establishment, before the session is created.
585
- */
2252
+ type ConversationConnectParams = Omit<ClientHandshake, "type"> & ConversationSessionConfig & {
2253
+ /** Optional callback invoked during the initial handshake phase */
586
2254
  onConnection?: (event: ServerConnectionMessage) => void
587
2255
  };
588
2256
  /**
589
- * Client for managing conversations and establishing sessions.
2257
+ * Provides real-time WebSocket session management for Kivox agents.
2258
+ * REST operations (list, get) are handled directly via the Kiota client.
590
2259
  *
591
2260
  * @example
592
2261
  * ```ts
593
- * // List past conversations
594
- * const conversations = await kivox.conversations.list();
595
- *
596
- * // Connect to an agent
597
- * const session = await kivox.conversations.connect({
2262
+ * const session = await kivox.realtime.connect({
598
2263
  * agentId: 'agent-123',
599
2264
  * onEvent: (event) => {
600
- * switch (event.type) {
601
- * case 'response.delta.text':
602
- * console.log(event.chunk);
603
- * break;
604
- * case 'response.delta.audio':
605
- * audioPlayer.enqueue(event.audio);
606
- * break;
607
- * }
2265
+ * if (event.type === 'text_delta') console.log(event.chunk);
608
2266
  * }
609
2267
  * });
610
- *
611
2268
  * session.sendText('Hello!');
612
2269
  * ```
613
2270
  */
614
- declare class ConversationClient {
615
- private readonly http;
616
- private readonly ws;
617
- constructor(http: HttpTransport, ws: WebSocketTransport);
618
- /**
619
- * Lists conversations with optional filtering and pagination.
620
- *
621
- * @param params List configuration
622
- * @returns Paginated list of conversations
623
- */
624
- list(params: ConversationListParams): Promise<Paginated<Conversation[]>>;
625
- /**
626
- * Gets a single conversation by ID.
627
- *
628
- * @param id Conversation ID
629
- * @returns Conversation details
630
- */
631
- get(id: string): Promise<Conversation>;
2271
+ declare class RealtimeClient {
2272
+ private;
2273
+ /** @internal */
2274
+ constructor(baseUrl: string);
632
2275
  /**
633
- * Connects to an agent and establishes a conversation session.
2276
+ * Establishes a real-time WebSocket session with a Kivox agent.
2277
+ * Authentication is passed as a query parameter since browser WebSockets
2278
+ * do not support custom headers.
634
2279
  *
635
- * @param params Connection configuration
636
- * @returns Active conversation session
637
- * @throws {Error} If handshake fails or connection is lost
2280
+ * @param params - Connection and session configuration.
2281
+ * @returns A promise resolving to an active {@link ConversationSession}.
2282
+ * @throws {Error} If the handshake fails or the connection drops during negotiation.
638
2283
  */
639
2284
  connect(params: ConversationConnectParams): Promise<ConversationSession>;
640
2285
  }
641
- type MessageRole = "system" | "user" | "assistant";
642
- type Message = {
643
- id: string
644
- conversation_id: string
645
- role: MessageRole
646
- content: string
647
- created_at: Date
648
- };
649
2286
  /**
650
- * Configuration for listing messages.
651
- */
652
- type MessageListParams = {
653
- /** Conversation ID to filter by */
654
- conversationId?: string
655
- /** Number of results per page */
656
- limit?: number
657
- /** Page number (1-indexed) */
658
- page?: number
659
- };
660
- /**
661
- * Client for interacting with conversation messages.
2287
+ * Extract a schema type from `components.schemas` by key.
662
2288
  *
663
- * @example
664
- * ```ts
665
- * const messages = await kivox.messages.list({
666
- * conversationId: 'conv-123'
667
- * });
668
- * ```
2289
+ * @typeParam T - Schema name
669
2290
  */
670
- declare class MessageClient {
671
- private readonly http;
672
- constructor(http: HttpTransport);
673
- /**
674
- * Lists messages with optional filtering and pagination.
675
- *
676
- * @param params List configuration
677
- * @returns Paginated list of messages
678
- */
679
- list(params?: MessageListParams): Promise<Paginated<Message[]>>;
680
- /**
681
- * Gets a single message by ID.
682
- *
683
- * @param id Message ID
684
- * @returns Message details
685
- */
686
- get(id: string): Promise<Message>;
687
- }
688
- type Template = {
689
- id: string
690
- name: string
691
- description?: string
692
- blueprint: AgentBlueprint
693
- created_at: Date
694
- updated_at: Date
695
- };
696
- type TemplateCreate = Pick<Template, "name" | "description" | "blueprint">;
697
- type TemplateUpdate = Partial<TemplateCreate>;
2291
+ type ApiSchema<T extends keyof components["schemas"]> = components["schemas"][T];
698
2292
  /**
699
- * Configuration for listing templates.
2293
+ * Extract the JSON request body type for an operation.
2294
+ *
2295
+ * Returns `never` if no JSON body is defined.
2296
+ *
2297
+ * @typeParam T - Operation name
700
2298
  */
701
- type TemplateListParams = {
702
- /** Number of results per page */
703
- limit?: number
704
- /** Page number (1-indexed) */
705
- page?: number
706
- };
2299
+ type ApiRequest<T extends keyof operations> = operations[T] extends {
2300
+ requestBody?: {
2301
+ content: {
2302
+ "application/json": infer Body
2303
+ }
2304
+ }
2305
+ } ? Body : never;
707
2306
  /**
708
- * Client for interacting with KIVOX templates.
2307
+ * Extract the JSON response type for an operation.
709
2308
  *
710
- * @example
711
- * ```ts
712
- * const templates = await kivox.templates.list();
713
- * const template = await kivox.templates.get('template-123');
714
- * ```
2309
+ * Supports `200` and `201` responses. Returns `never` if neither exists.
2310
+ *
2311
+ * @typeParam T - Operation name
715
2312
  */
716
- declare class TemplateClient {
717
- private readonly http;
718
- constructor(http: HttpTransport);
719
- /**
720
- * Lists all templates with optional filtering and pagination.
721
- *
722
- * @param params List configuration
723
- * @returns Paginated list of templates
724
- */
725
- list(params?: TemplateListParams): Promise<Paginated<Template[]>>;
726
- /**
727
- * Gets a single template by ID.
728
- *
729
- * @param id Template ID
730
- * @returns Template details
731
- */
732
- get(id: string): Promise<Template>;
733
- /**
734
- * Creates a new template.
735
- *
736
- * @param data Template data
737
- * @returns Created template
738
- */
739
- create(data: TemplateCreate): Promise<Template>;
740
- /**
741
- * Updates an existing template.
742
- *
743
- * @param id Template ID
744
- * @param data Updated template data
745
- * @returns Updated template
746
- */
747
- update(id: string, data: TemplateUpdate): Promise<Template>;
748
- /**
749
- * Deletes a template.
750
- *
751
- * @param id Template ID
752
- */
753
- delete(id: string): Promise<void>;
754
- }
2313
+ type ApiResponse<T extends keyof operations> = operations[T] extends {
2314
+ responses: {
2315
+ 200: {
2316
+ content: {
2317
+ "application/json": infer Res
2318
+ }
2319
+ }
2320
+ }
2321
+ } ? Res : operations[T] extends {
2322
+ responses: {
2323
+ 201: {
2324
+ content: {
2325
+ "application/json": infer Res
2326
+ }
2327
+ }
2328
+ }
2329
+ } ? Res : never;
2330
+ type KivoxFetchClient = ReturnType<typeof createClient<paths>>;
2331
+ type KivoxClient = {
2332
+ api: KivoxFetchClient
2333
+ realtime: RealtimeClient
2334
+ };
2335
+ type SessionClientOptions = {
2336
+ baseUrl?: string
2337
+ };
2338
+ type BearerClientOptions = {
2339
+ bearerToken: string
2340
+ baseUrl?: string
2341
+ };
755
2342
  /**
756
- * Configuration for the Kivox client.
2343
+ * Browser/Studio client. Authenticates via HttpOnly session cookie.
757
2344
  */
758
- type KivoxConfig = {
759
- /**
760
- * Base URL of your self-hosted KIVOX instance.
761
- * @example 'http://localhost:8787'
762
- * @example 'https://api.kivox.io'
763
- */
764
- baseUrl: string
765
- /**
766
- * Optional headers to include with all requests.
767
- * @example { Authorization: 'Bearer token' }
768
- */
769
- headers?: Record<string, string>
770
- };
2345
+ declare function createSessionClient({ baseUrl }?: SessionClientOptions): KivoxClient;
771
2346
  /**
772
- * Main KIVOX client.
773
- * Provides unified access to all KIVOX resources.
774
- *
775
- * @example
776
- * ```ts
777
- * import { KivoxClient } from '@kivox/client';
778
- *
779
- * const kivox = new KivoxClient({
780
- * baseUrl: 'http://localhost:8787',
781
- * });
782
- *
783
- * // List agents
784
- * const agents = await kivox.agents.list();
785
- *
786
- * // Start a conversation
787
- * const session = await kivox.conversations.connect({
788
- * agentId: '019bb51e-e45f-75e3-b828-94fdf231711e',
789
- * onEvent: (event) => {
790
- * console.log(event);
791
- * }
792
- * });
793
- * ```
2347
+ * Server-side / programmatic client. Authenticates via Bearer token.
794
2348
  */
795
- declare class KivoxClient {
796
- /** Agent resource client */
797
- readonly agents: AgentClient;
798
- /** Conversation resource client */
799
- readonly conversations: ConversationClient;
800
- /** Template resource client */
801
- readonly templates: TemplateClient;
802
- /** Message resource client */
803
- readonly messages: MessageClient;
804
- constructor(config: KivoxConfig);
805
- }
806
- 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 };
2349
+ declare function createBearerClient({ bearerToken, baseUrl }: BearerClientOptions): KivoxClient;
2350
+ export { paths, operations, createSessionClient, createBearerClient, components, SessionConnectionLostEvent, SessionClientOptions, ServerTurnComplete, ServerTransfer, ServerTick, ServerTextFull, ServerTextDelta, ServerSignal, ServerSessionEvent, ServerSessionClosed, ServerMessage, ServerHandshakeOK, ServerHandshakeError, ServerFlowComplete, ServerError, ServerConnectionMessage, ServerAudioDelta, KivoxFetchClient, KivoxClient, ConversationTransportError, ConversationSessionConfig, ConversationSession, ClientMessage, ClientInputText, ClientInputAudioStream, ClientInputAudio, ClientHandshake, ClientEndSession, ClientCancel, BearerClientOptions, ApiSchema, ApiResponse, ApiRequest };