@getsupervisor/agents-studio-sdk 1.41.2 → 1.42.0

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.
Files changed (9) hide show
  1. package/CHANGELOG.md +56 -4
  2. package/README.md +69 -20
  3. package/dist/index.cjs +319 -10
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +399 -18
  6. package/dist/index.d.ts +399 -18
  7. package/dist/index.js +315 -10
  8. package/dist/index.js.map +1 -1
  9. package/package.json +11 -6
package/CHANGELOG.md CHANGED
@@ -4,6 +4,58 @@
4
4
 
5
5
  - SDK endpoints no longer include the `/v1` prefix. Backends now serve routes without that versioned segment, so existing consumers must drop `/v1` from any custom base URLs or proxy rewrites. The `/v1` paths are no longer supported, making this a hard breaking change that requires all clients to update their configuration before upgrading the SDK.
6
6
 
7
+ ## [1.42.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.41.0...v1.42.0) (2026-06-03)
8
+
9
+
10
+ ### Features
11
+
12
+ * add agent call statistics including total calls, operational da… ([f2ceddb](https://github.com/julio-supervisor/agents-studio-be/commit/f2ceddbc914f0a69975e90bd42c22511115553be))
13
+ * add agent call statistics including total calls, operational days, and goal achievement percentage ([3841bb3](https://github.com/julio-supervisor/agents-studio-be/commit/3841bb3bd1deb83fbc247d73acf093dea70b5342))
14
+ * add catalog metadata structure to tools ([cd482f7](https://github.com/julio-supervisor/agents-studio-be/commit/cd482f756c9404d815df16bdc7fcf2abfcbc87fc))
15
+ * add CloneAgentRequest schema and cloning endpoint ([36d3ff9](https://github.com/julio-supervisor/agents-studio-be/commit/36d3ff955472df6b801ceaee99affa535020f4e5))
16
+ * add CloneAgentRequest schema and cloning endpoint ([5b97daf](https://github.com/julio-supervisor/agents-studio-be/commit/5b97daf5bde28c653cd7898fb6c0313370080849))
17
+ * add descriptionUsage and usageExample fields to tool connection schemas ([7f1cc63](https://github.com/julio-supervisor/agents-studio-be/commit/7f1cc6335c5a588275aeec91684cb49f42a31beb))
18
+ * add optional description field to agent DTOs and schemas ([e3e336e](https://github.com/julio-supervisor/agents-studio-be/commit/e3e336e0b6613b54b7df4f6d3f7a2693e025a5dc))
19
+ * add output variables support to agent blueprints ([093fa95](https://github.com/julio-supervisor/agents-studio-be/commit/093fa9533c459f54fe162ae082d57ce5555f8a37))
20
+ * add output variables support to agent blueprints ([7345f47](https://github.com/julio-supervisor/agents-studio-be/commit/7345f470ab6cebbd9ed2a4d9c0614c5f313b9e0f))
21
+ * add output variables support to agent blueprints and update related documentation ([19e67ea](https://github.com/julio-supervisor/agents-studio-be/commit/19e67eae361ea982188bb6cdc34d0bd16563ef03))
22
+ * add SIP trunks CRUD to public-api with direct Kamailio DB access ([a9e80dd](https://github.com/julio-supervisor/agents-studio-be/commit/a9e80dd49c3290d5ac1144b93172f276da56d256))
23
+ * add tool connections API endpoints and listing service ([6736347](https://github.com/julio-supervisor/agents-studio-be/commit/67363479fc929dcd93018e1e6a62e01787e25ea2))
24
+ * add visibility flag to tools and update related components ([e00e201](https://github.com/julio-supervisor/agents-studio-be/commit/e00e201888f856002bbbf79f529f33dd9dc6450a))
25
+ * **api:** enhance workspace resolution to support API key authentication ([2f151cd](https://github.com/julio-supervisor/agents-studio-be/commit/2f151cd223a74f4a7a2a68cf5e680393097e2869))
26
+ * Billing & Usage module ([9300bcc](https://github.com/julio-supervisor/agents-studio-be/commit/9300bccc302c4ae7f3aad05caef331f0d4866460))
27
+ * **calls:** add durationBucket and goalStatus parameters to calls API and SDK, update related documentation ([981ed9d](https://github.com/julio-supervisor/agents-studio-be/commit/981ed9d6a8335614e5a1acd4da808f01417bc28d))
28
+ * **calls:** add durationBucket, goalStatus, and query parameters to calls API and SDK documentation ([9423b7f](https://github.com/julio-supervisor/agents-studio-be/commit/9423b7f4b990887dd6593e97203b4e15f580dc27))
29
+ * **calls:** implement TypeORM repository and specifications for call management ([30c9b71](https://github.com/julio-supervisor/agents-studio-be/commit/30c9b71c56fbcea3688585e66b12229a8db62215))
30
+ * **calls:** implement TypeORM repository and specifications for call… ([47803ce](https://github.com/julio-supervisor/agents-studio-be/commit/47803cea9d3751b953a3d9f7147869bb94a32798))
31
+ * **campaigns:** export CSV de executions + persistencia de outcome por intento ([17366c6](https://github.com/julio-supervisor/agents-studio-be/commit/17366c6c7cabd751ede8ad8fdb57166ed1e4645c))
32
+ * **campaigns:** lifecycle completo con retries, pause/resume/cancel y paralelismo ([3954e48](https://github.com/julio-supervisor/agents-studio-be/commit/3954e483adc0890b04eb7e830af395e6fdb4086a))
33
+ * **campaigns:** outcome classification, lifecycle quiescence y filtros E2E ([0afe803](https://github.com/julio-supervisor/agents-studio-be/commit/0afe8033919c2420551ce9c4073f3ced3bd29024))
34
+ * enforce title as a required field in blueprint stages and related DTOs ([e90a84e](https://github.com/julio-supervisor/agents-studio-be/commit/e90a84eeb4c1c3f82e8027da30991673d2fbabac))
35
+ * enhance Tool and Connection Models with Connection Key ([8471499](https://github.com/julio-supervisor/agents-studio-be/commit/847149931138a5786e2c9f7314a346fbcf27e67e))
36
+ * enhance Tool and Connection Models with Connection Key ([6379fdf](https://github.com/julio-supervisor/agents-studio-be/commit/6379fdf34ffe67fc841db58d8778012d20696396))
37
+ * **errors:** enhance error handling and type safety for API errors in SDK ([7848c61](https://github.com/julio-supervisor/agents-studio-be/commit/7848c615c20951a66fdeb4b8d9c465d8cc542721))
38
+ * **errors:** enhance ErrorResponse structure with detailed descriptions and subcode ([044d022](https://github.com/julio-supervisor/agents-studio-be/commit/044d0227331c650fff7b4294344420a1302ae9cb))
39
+ * implement Retell tool execution signature service and update re… ([a783e91](https://github.com/julio-supervisor/agents-studio-be/commit/a783e9123104b8398841223bcdb1ecede5c8ded2))
40
+ * refactor workspace enabling API to use API key and update related documentation ([38505ab](https://github.com/julio-supervisor/agents-studio-be/commit/38505ab4bbb9ac3d22bf4c7335c51ed0fe3700e2))
41
+ * **sdk:** add billing and usage API modules ([97e7e44](https://github.com/julio-supervisor/agents-studio-be/commit/97e7e4455e00fd99420fa04f7e0a2dc6b591c938))
42
+ * SIP load balancer with Kamailio Dispatcher and autoscaling ([20a918c](https://github.com/julio-supervisor/agents-studio-be/commit/20a918cb2e3d6092cc5f30ec6a7a58043357838e))
43
+ * SIP trunks CRUD in public-api with direct Kamailio DB ([25af230](https://github.com/julio-supervisor/agents-studio-be/commit/25af230afea0e4c2326dd22d5df30930dc2897a9))
44
+ * update agent stages tools to support partial payloads and enhance functionality ([99346db](https://github.com/julio-supervisor/agents-studio-be/commit/99346db032b985ebed4fdf6ca17271f68d527b33))
45
+ * **usage:** add aggregations to usage agents meta with totalUsage and planLimit ([0f2e6c8](https://github.com/julio-supervisor/agents-studio-be/commit/0f2e6c8eed21cce74babad77e4450b1b9d8f1aad))
46
+ * **webhooks:** add method field to OpenAPI spec and implement SDKs ([2cd6908](https://github.com/julio-supervisor/agents-studio-be/commit/2cd6908175b9935ab1e960e1b72e6c9cc5fb23bc))
47
+ * **webhooks:** add webhook deliveries functionality ([c552636](https://github.com/julio-supervisor/agents-studio-be/commit/c5526369b9a6e7467f0ed7fdd4185e8c508bdd73))
48
+ * **workspaces:** add WorkspacesEnableTool and related command for enabling workspaces ([215b36b](https://github.com/julio-supervisor/agents-studio-be/commit/215b36bb44beb3d433564cdcf72a4571a5e0145b))
49
+
50
+
51
+ ### Bug Fixes
52
+
53
+ * add missing commas in various TypeScript files for consistency and syntax correctness ([66b912b](https://github.com/julio-supervisor/agents-studio-be/commit/66b912bb43aecdb368c08f357325ce8ea20af528))
54
+ * **sdk:** agregar eslint flat config y corregir lint del paquete ([5956d7e](https://github.com/julio-supervisor/agents-studio-be/commit/5956d7e1f2ae3371331136c6eb132f8318b3ef15))
55
+ * **sdk:** listExecutions debe propagar filter y sort ([f351896](https://github.com/julio-supervisor/agents-studio-be/commit/f351896e3e76aa36093a5875d5265bb186c38d13))
56
+ * **sdk:** update yarn.lock after pinning openapi-typescript to 6.7.6 ([c0ca89a](https://github.com/julio-supervisor/agents-studio-be/commit/c0ca89a9113805df9f9d779315405ddfeaca751f))
57
+ * serialize date filters as ISO 8601 with local timezone support ([c0c2b37](https://github.com/julio-supervisor/agents-studio-be/commit/c0c2b37062955c630906b35cd81de723007a5c6a))
58
+
7
59
  ## v1.41.0
8
60
 
9
61
  ## [1.41.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.40.0...v1.41.0) (2025-12-07)
@@ -93,7 +145,7 @@
93
145
 
94
146
  ### Features
95
147
 
96
- - add default language constant and update RetellBlueprintMapper to use it ([85d2d8c](https://github.com/julio-supervisor/agents-studio-be/commit/85d2d8ccc908254d351855158ecc09f14dbf6c6f))
148
+ - add default language constant and update blueprint mapper to use it ([85d2d8c](https://github.com/julio-supervisor/agents-studio-be/commit/85d2d8ccc908254d351855158ecc09f14dbf6c6f))
97
149
  - implement delete instruction functionality with command handler and controller ([af983f5](https://github.com/julio-supervisor/agents-studio-be/commit/af983f5254055d35d3972d0bcbdb12a52b48c785))
98
150
 
99
151
  ## v1.34.0
@@ -102,8 +154,8 @@
102
154
 
103
155
  ### Features
104
156
 
105
- - enhance instruction management by adding active and non-deleted filtering, and integrate instructions into the Retell blueprint mapping ([baadb5f](https://github.com/julio-supervisor/agents-studio-be/commit/baadb5f561749d441c4757435fb920bb48556d7d))
106
- - implement VoiceBlueprintSyncService for Retell synchronization ([6b8f03f](https://github.com/julio-supervisor/agents-studio-be/commit/6b8f03f77ca1d2b91a9628db055e2799aa039f53))
157
+ - enhance instruction management by adding active and non-deleted filtering, and integrate instructions into the agent blueprint mapping ([baadb5f](https://github.com/julio-supervisor/agents-studio-be/commit/baadb5f561749d441c4757435fb920bb48556d7d))
158
+ - implement VoiceBlueprintSyncService for blueprint synchronization ([6b8f03f](https://github.com/julio-supervisor/agents-studio-be/commit/6b8f03f77ca1d2b91a9628db055e2799aa039f53))
107
159
  - introduce buildClientMock helper for consistent workspaceId handling in tests ([ae6eb30](https://github.com/julio-supervisor/agents-studio-be/commit/ae6eb305b16f677dea03a21bdfc8559c13cc641a))
108
160
 
109
161
  ## v1.33.0
@@ -277,7 +329,7 @@
277
329
 
278
330
  ### Features
279
331
 
280
- - Agrega `RetellToolGuidelinesService` y lineamientos de uso para voice calls dentro del SDK, permitiendo mostrar requisitos y recomendaciones antes de ejecutar herramientas de voz ([db0e013](https://github.com/julio-supervisor/agents-studio-be/commit/db0e013d8f09d2a0a794efccb7700729ad752fd4)).
332
+ - Agrega `ToolGuidelinesService` y lineamientos de uso para voice calls dentro del SDK, permitiendo mostrar requisitos y recomendaciones antes de ejecutar herramientas de voz ([db0e013](https://github.com/julio-supervisor/agents-studio-be/commit/db0e013d8f09d2a0a794efccb7700729ad752fd4)).
281
333
 
282
334
  ## [1.19.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.18.0...v1.19.0) (2025-10-29)
283
335
 
package/README.md CHANGED
@@ -397,6 +397,45 @@ npx tsx examples/custom-tool-connection.ts
397
397
 
398
398
  El script envía la metadata de conexión (URL, método, headers) y, sobre todo, almacena un `configSchema` específico del workspace dentro de `tool_agent_connections.metadata`. Ese esquema describe los campos que el agente debe solicitar (en el ejemplo `agentId` y `customerName`) y coincide con la acción `triggerWorkflow` que expone el seed `custom.http.workflow`. Después de conectar la tool ejecuta `client.tools.execute('custom.http.workflow', { action: 'triggerWorkflow', args: { ... } })` respetando el schema definido en tu metadata.
399
399
 
400
+ ## SIP Trunks
401
+
402
+ Namespace: `client.sip`
403
+
404
+ Gestiona trunks SIP para conectar agentes de voz a carriers PSTN (Twilio, ccc2.uno, etc.).
405
+
406
+ Operaciones disponibles:
407
+
408
+ - `sip.list()` — lista todos los SIP trunks del workspace.
409
+ - `sip.get(trunkId)` — obtiene un trunk por ID.
410
+ - `sip.create(payload)` — crea un trunk (devuelve `password` solo en la creación).
411
+ - `sip.update(trunkId, payload)` — actualiza un trunk (campos parciales).
412
+ - `sip.delete(trunkId)` — elimina un trunk y su subscriber asociado.
413
+
414
+ Ejemplo:
415
+
416
+ ```ts
417
+ // crear un trunk SIP
418
+ const trunk = await client.sip.create({
419
+ name: 'Twilio Production',
420
+ carrierAddress: 'my-trunk.pstn.twilio.com',
421
+ // opcionales: carrierPort (default 5060), carrierTransport (default 'udp'), phoneNumbers
422
+ });
423
+
424
+ console.log(trunk.username); // auto-generado para SIP digest auth
425
+ console.log(trunk.password); // solo visible en la creación
426
+
427
+ // listar trunks del workspace
428
+ const trunks = await client.sip.list();
429
+
430
+ // actualizar
431
+ await client.sip.update(trunk.id, { name: 'Twilio Staging' });
432
+
433
+ // eliminar
434
+ await client.sip.delete(trunk.id);
435
+ ```
436
+
437
+ Scopes requeridos: `sip:read` para lectura, `sip:write` para escritura.
438
+
400
439
  ## Configuración
401
440
 
402
441
  ```ts
@@ -524,26 +563,36 @@ const { key, ...metadata } = await http
524
563
 
525
564
  ### Scopes disponibles (octubre 2025)
526
565
 
527
- | Scope | Permiso principal |
528
- | -------------------------- | ---------------------------------------------------------------------------------------- |
529
- | `agents:read` | Consultar agentes, versiones, instrucciones, teléfonos y blueprints asociados. |
530
- | `agents:write` | Crear, actualizar o eliminar agentes, versiones, teléfonos y su configuración operativa. |
531
- | `agent-instructions:read` | Leer instrucciones tanto a nivel agente como por versión publicada. |
532
- | `agent-instructions:write` | Crear, actualizar o borrar instrucciones personalizadas. |
533
- | `agent-blueprints:read` | Consultar blueprint y resúmenes sincronizados con proveedores externos. |
534
- | `agent-blueprints:write` | Editar blueprint, personalidad y reglas de cada versión. |
535
- | `agent-schedules:read` | Consultar horario semanal y excepciones vigentes. |
536
- | `agent-schedules:write` | Crear o modificar horarios y excepciones. |
537
- | `catalogs:read` | Navegar catálogos globales y por workspace (idiomas, estilos, voces, etc.). |
538
- | `catalogs:write` | Registrar o ajustar ítems de catálogo. |
539
- | `tools:read` | Descubrir tools disponibles, recursos y capacidades declaradas. |
540
- | `tools:connections:write` | Crear conexiones entre agentes y tools (p. ej. `voice.calls`). |
541
- | `tools:execute` | Ejecutar acciones de una tool (`startCall`, `reload`, etc.). |
542
- | `webhooks:read` | Listar webhooks y sus suscripciones activas. |
543
- | `webhooks:write` | Crear, actualizar o eliminar webhooks y suscripciones. |
544
- | `api-keys:read` | Listar credenciales existentes y revelar su valor. |
545
- | `api-keys:write` | Emitir o revocar API Keys. |
546
- | `workspaces:read` | Consultar metadatos y estado de habilitación de un workspace. |
566
+ | Scope | Permiso principal |
567
+ | -------------------------- | ------------------------------------------------------------------------- |
568
+ | `agents:read` | Listar y consultar agentes del workspace. |
569
+ | `agents:write` | Crear/actualizar/eliminar agentes y gestionar su configuración operativa. |
570
+ | `agent-versions:read` | Listar y consultar versiones de un agente. |
571
+ | `agent-versions:write` | Crear, clonar, restaurar y publicar versiones de un agente. |
572
+ | `agent-instructions:read` | Leer instrucciones (a nivel agente y por versión). |
573
+ | `agent-instructions:write` | Crear, actualizar o borrar instrucciones personalizadas. |
574
+ | `agent-blueprints:read` | Consultar el blueprint (personalidad) de una versión de agente. |
575
+ | `agent-blueprints:write` | Editar blueprint: personalidad, reglas, audiencia, objetivos, etc. |
576
+ | `blueprint-stages:read` | Listar y consultar stages del blueprint. |
577
+ | `blueprint-stages:write` | Crear, actualizar o reordenar stages del blueprint. |
578
+ | `stage-triggers:read` | Consultar triggers que conectan stages y sus condiciones. |
579
+ | `stage-triggers:write` | Crear, actualizar o eliminar triggers entre stages. |
580
+ | `agent-schedules:read` | Consultar horario semanal y excepciones vigentes. |
581
+ | `agent-schedules:write` | Crear o modificar horarios y excepciones. |
582
+ | `campaigns:read` | Consultar campañas y sus ejecuciones. |
583
+ | `campaigns:write` | Crear y disparar campañas batch. |
584
+ | `calls:read` | Consultar llamadas (Speech Analytics) del workspace. |
585
+ | `catalogs:read` | Navegar catálogos globales y por workspace (idiomas, tonos, voces, etc.). |
586
+ | `catalogs:write` | Registrar o ajustar ítems de catálogo. |
587
+ | `tools:read` | Descubrir tools disponibles, recursos y capacidades declaradas. |
588
+ | `tools:connections:read` | Listar conexiones configuradas entre agentes y tools. |
589
+ | `tools:connections:write` | Crear o actualizar conexiones entre agentes y tools. |
590
+ | `tools:execute` | Ejecutar acciones de una tool. |
591
+ | `webhooks:read` | Listar webhooks y sus suscripciones activas. |
592
+ | `webhooks:write` | Crear, actualizar o eliminar webhooks y suscripciones. |
593
+ | `api-keys:read` | Listar credenciales existentes y revelar su valor. |
594
+ | `api-keys:write` | Emitir o revocar API Keys. |
595
+ | `workspaces:read` | Consultar workspaces disponibles y sus metadatos. |
547
596
 
548
597
  Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para validar scopes adicionales (por ejemplo, específicos de conocimientos o teléfonos) y su mapeo exacto por operación.
549
598