@getsupervisor/agents-studio-sdk 1.41.2-patch.9 → 1.42.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@
 
 - 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.
 
+## [1.42.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.41.0...v1.42.0) (2026-06-03)
+
+
+### Features
+
+* add agent call statistics including total calls, operational da… ([f2ceddb](https://github.com/julio-supervisor/agents-studio-be/commit/f2ceddbc914f0a69975e90bd42c22511115553be))
+* add agent call statistics including total calls, operational days, and goal achievement percentage ([3841bb3](https://github.com/julio-supervisor/agents-studio-be/commit/3841bb3bd1deb83fbc247d73acf093dea70b5342))
+* add catalog metadata structure to tools ([cd482f7](https://github.com/julio-supervisor/agents-studio-be/commit/cd482f756c9404d815df16bdc7fcf2abfcbc87fc))
+* add CloneAgentRequest schema and cloning endpoint ([36d3ff9](https://github.com/julio-supervisor/agents-studio-be/commit/36d3ff955472df6b801ceaee99affa535020f4e5))
+* add CloneAgentRequest schema and cloning endpoint ([5b97daf](https://github.com/julio-supervisor/agents-studio-be/commit/5b97daf5bde28c653cd7898fb6c0313370080849))
+* add descriptionUsage and usageExample fields to tool connection schemas ([7f1cc63](https://github.com/julio-supervisor/agents-studio-be/commit/7f1cc6335c5a588275aeec91684cb49f42a31beb))
+* add optional description field to agent DTOs and schemas ([e3e336e](https://github.com/julio-supervisor/agents-studio-be/commit/e3e336e0b6613b54b7df4f6d3f7a2693e025a5dc))
+* add output variables support to agent blueprints ([093fa95](https://github.com/julio-supervisor/agents-studio-be/commit/093fa9533c459f54fe162ae082d57ce5555f8a37))
+* add output variables support to agent blueprints ([7345f47](https://github.com/julio-supervisor/agents-studio-be/commit/7345f470ab6cebbd9ed2a4d9c0614c5f313b9e0f))
+* add output variables support to agent blueprints and update related documentation ([19e67ea](https://github.com/julio-supervisor/agents-studio-be/commit/19e67eae361ea982188bb6cdc34d0bd16563ef03))
+* add SIP trunks CRUD to public-api with direct Kamailio DB access ([a9e80dd](https://github.com/julio-supervisor/agents-studio-be/commit/a9e80dd49c3290d5ac1144b93172f276da56d256))
+* add tool connections API endpoints and listing service ([6736347](https://github.com/julio-supervisor/agents-studio-be/commit/67363479fc929dcd93018e1e6a62e01787e25ea2))
+* add visibility flag to tools and update related components ([e00e201](https://github.com/julio-supervisor/agents-studio-be/commit/e00e201888f856002bbbf79f529f33dd9dc6450a))
+* **api:** enhance workspace resolution to support API key authentication ([2f151cd](https://github.com/julio-supervisor/agents-studio-be/commit/2f151cd223a74f4a7a2a68cf5e680393097e2869))
+* Billing & Usage module ([9300bcc](https://github.com/julio-supervisor/agents-studio-be/commit/9300bccc302c4ae7f3aad05caef331f0d4866460))
+* **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))
+* **calls:** add durationBucket, goalStatus, and query parameters to calls API and SDK documentation ([9423b7f](https://github.com/julio-supervisor/agents-studio-be/commit/9423b7f4b990887dd6593e97203b4e15f580dc27))
+* **calls:** implement TypeORM repository and specifications for call management ([30c9b71](https://github.com/julio-supervisor/agents-studio-be/commit/30c9b71c56fbcea3688585e66b12229a8db62215))
+* **calls:** implement TypeORM repository and specifications for call… ([47803ce](https://github.com/julio-supervisor/agents-studio-be/commit/47803cea9d3751b953a3d9f7147869bb94a32798))
+* **campaigns:** export CSV de executions + persistencia de outcome por intento ([17366c6](https://github.com/julio-supervisor/agents-studio-be/commit/17366c6c7cabd751ede8ad8fdb57166ed1e4645c))
+* **campaigns:** lifecycle completo con retries, pause/resume/cancel y paralelismo ([3954e48](https://github.com/julio-supervisor/agents-studio-be/commit/3954e483adc0890b04eb7e830af395e6fdb4086a))
+* **campaigns:** outcome classification, lifecycle quiescence y filtros E2E ([0afe803](https://github.com/julio-supervisor/agents-studio-be/commit/0afe8033919c2420551ce9c4073f3ced3bd29024))
+* enforce title as a required field in blueprint stages and related DTOs ([e90a84e](https://github.com/julio-supervisor/agents-studio-be/commit/e90a84eeb4c1c3f82e8027da30991673d2fbabac))
+* enhance Tool and Connection Models with Connection Key ([8471499](https://github.com/julio-supervisor/agents-studio-be/commit/847149931138a5786e2c9f7314a346fbcf27e67e))
+* enhance Tool and Connection Models with Connection Key ([6379fdf](https://github.com/julio-supervisor/agents-studio-be/commit/6379fdf34ffe67fc841db58d8778012d20696396))
+* **errors:** enhance error handling and type safety for API errors in SDK ([7848c61](https://github.com/julio-supervisor/agents-studio-be/commit/7848c615c20951a66fdeb4b8d9c465d8cc542721))
+* **errors:** enhance ErrorResponse structure with detailed descriptions and subcode ([044d022](https://github.com/julio-supervisor/agents-studio-be/commit/044d0227331c650fff7b4294344420a1302ae9cb))
+* implement Retell tool execution signature service and update re… ([a783e91](https://github.com/julio-supervisor/agents-studio-be/commit/a783e9123104b8398841223bcdb1ecede5c8ded2))
+* refactor workspace enabling API to use API key and update related documentation ([38505ab](https://github.com/julio-supervisor/agents-studio-be/commit/38505ab4bbb9ac3d22bf4c7335c51ed0fe3700e2))
+* **sdk:** add billing and usage API modules ([97e7e44](https://github.com/julio-supervisor/agents-studio-be/commit/97e7e4455e00fd99420fa04f7e0a2dc6b591c938))
+* SIP load balancer with Kamailio Dispatcher and autoscaling ([20a918c](https://github.com/julio-supervisor/agents-studio-be/commit/20a918cb2e3d6092cc5f30ec6a7a58043357838e))
+* SIP trunks CRUD in public-api with direct Kamailio DB ([25af230](https://github.com/julio-supervisor/agents-studio-be/commit/25af230afea0e4c2326dd22d5df30930dc2897a9))
+* update agent stages tools to support partial payloads and enhance functionality ([99346db](https://github.com/julio-supervisor/agents-studio-be/commit/99346db032b985ebed4fdf6ca17271f68d527b33))
+* **usage:** add aggregations to usage agents meta with totalUsage and planLimit ([0f2e6c8](https://github.com/julio-supervisor/agents-studio-be/commit/0f2e6c8eed21cce74babad77e4450b1b9d8f1aad))
+* **webhooks:** add method field to OpenAPI spec and implement SDKs ([2cd6908](https://github.com/julio-supervisor/agents-studio-be/commit/2cd6908175b9935ab1e960e1b72e6c9cc5fb23bc))
+* **webhooks:** add webhook deliveries functionality ([c552636](https://github.com/julio-supervisor/agents-studio-be/commit/c5526369b9a6e7467f0ed7fdd4185e8c508bdd73))
+* **workspaces:** add WorkspacesEnableTool and related command for enabling workspaces ([215b36b](https://github.com/julio-supervisor/agents-studio-be/commit/215b36bb44beb3d433564cdcf72a4571a5e0145b))
+
+
+### Bug Fixes
+
+* add missing commas in various TypeScript files for consistency and syntax correctness ([66b912b](https://github.com/julio-supervisor/agents-studio-be/commit/66b912bb43aecdb368c08f357325ce8ea20af528))
+* **sdk:** agregar eslint flat config y corregir lint del paquete ([5956d7e](https://github.com/julio-supervisor/agents-studio-be/commit/5956d7e1f2ae3371331136c6eb132f8318b3ef15))
+* **sdk:** listExecutions debe propagar filter y sort ([f351896](https://github.com/julio-supervisor/agents-studio-be/commit/f351896e3e76aa36093a5875d5265bb186c38d13))
+* **sdk:** update yarn.lock after pinning openapi-typescript to 6.7.6 ([c0ca89a](https://github.com/julio-supervisor/agents-studio-be/commit/c0ca89a9113805df9f9d779315405ddfeaca751f))
+* serialize date filters as ISO 8601 with local timezone support ([c0c2b37](https://github.com/julio-supervisor/agents-studio-be/commit/c0c2b37062955c630906b35cd81de723007a5c6a))
+
 ## v1.41.0
 
 ## [1.41.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.40.0...v1.41.0) (2025-12-07)

package/README.md

@@ -397,6 +397,45 @@ npx tsx examples/custom-tool-connection.ts
 
 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.
 
+## SIP Trunks
+
+Namespace: `client.sip`
+
+Gestiona trunks SIP para conectar agentes de voz a carriers PSTN (Twilio, ccc2.uno, etc.).
+
+Operaciones disponibles:
+
+- `sip.list()` — lista todos los SIP trunks del workspace.
+- `sip.get(trunkId)` — obtiene un trunk por ID.
+- `sip.create(payload)` — crea un trunk (devuelve `password` solo en la creación).
+- `sip.update(trunkId, payload)` — actualiza un trunk (campos parciales).
+- `sip.delete(trunkId)` — elimina un trunk y su subscriber asociado.
+
+Ejemplo:
+
+```ts
+// crear un trunk SIP
+const trunk = await client.sip.create({
+  name: 'Twilio Production',
+  carrierAddress: 'my-trunk.pstn.twilio.com',
+  // opcionales: carrierPort (default 5060), carrierTransport (default 'udp'), phoneNumbers
+});
+
+console.log(trunk.username); // auto-generado para SIP digest auth
+console.log(trunk.password); // solo visible en la creación
+
+// listar trunks del workspace
+const trunks = await client.sip.list();
+
+// actualizar
+await client.sip.update(trunk.id, { name: 'Twilio Staging' });
+
+// eliminar
+await client.sip.delete(trunk.id);
+```
+
+Scopes requeridos: `sip:read` para lectura, `sip:write` para escritura.
+
 ## Configuración
 
 ```ts

package/dist/index.cjs

@@ -43,13 +43,16 @@ __export(index_exports, {
   createAgentVersionsApi: () => createAgentVersionsApi,
   createAgentsApi: () => createAgentsApi,
   createApiKeysApi: () => createApiKeysApi,
+  createBillingApi: () => createBillingApi,
   createCallsApi: () => createCallsApi,
   createCampaignsApi: () => createCampaignsApi,
   createCatalogTemplatesApi: () => createCatalogTemplatesApi,
   createCatalogsApi: () => createCatalogsApi,
   createClient: () => createClient,
   createHttp: () => createHttp,
+  createSipTrunksApi: () => createSipTrunksApi,
   createToolsApi: () => createToolsApi,
+  createUsageApi: () => createUsageApi,
   createVoicesApi: () => createVoicesApi,
   createWebhooksApi: () => createWebhooksApi,
   createWorkspacesApi: () => createWorkspacesApi,
@@ -239,7 +242,8 @@ function createHttp(cfg) {
         }
         return res;
       } catch (e) {
-        if (e.name === "AbortError") throw new TimeoutError(timeout, targetUrl);
+        if (e?.name === "AbortError")
+          throw new TimeoutError(timeout, targetUrl);
         if (e instanceof HttpError) throw e;
         throw new NetworkError(e, targetUrl);
       }
@@ -1379,6 +1383,19 @@ function createApiKeysApi(cfg) {
   };
 }
 
+// src/api/billing.ts
+function createBillingApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  return {
+    async getBalance() {
+      const res = await doFetch(`${base}/billing/balance`, {
+        method: "GET"
+      });
+      return res.json();
+    }
+  };
+}
+
 // src/api/calls.ts
 function createCallsApi(cfg) {
   const { base, doFetch } = createHttp(cfg);
@@ -1457,10 +1474,7 @@ function createCampaignsApi(cfg) {
     return res.json();
   };
   const fetchExecutionsPage = async (campaignId, options = {}) => {
-    const query = serializeListOptions({
-      page: options.page,
-      limit: options.limit
-    });
+    const query = serializeListOptions(options ?? {});
     const res = await doFetch(`${base}/campaigns/${campaignId}/executions`, {
       method: "GET",
       query
@@ -1514,6 +1528,51 @@ function createCampaignsApi(cfg) {
       const response = await fetchExecutionsPage(campaignId, normalizedOptions);
       const fetchPage = (opts) => fetchExecutionsPage(campaignId, opts);
       return attachPaginator(response, fetchPage, normalizedOptions);
+    },
+    /**
+     * Pausa una campaña en curso. Los reintentos ya programados se
+     * reagendan al ejecutarse (sin consumir intentos) hasta `resume()`.
+     */
+    async pause(campaignId) {
+      const res = await doFetch(`${base}/campaigns/${campaignId}/pause`, {
+        method: "POST"
+      });
+      return res.json();
+    },
+    /**
+     * Reanuda una campaña pausada. Re-encola los reintentos pendientes
+     * según su `nextRetryAt`.
+     */
+    async resume(campaignId) {
+      const res = await doFetch(`${base}/campaigns/${campaignId}/resume`, {
+        method: "POST"
+      });
+      return res.json();
+    },
+    /**
+     * Cancela definitivamente una campaña no terminal. Los reintentos
+     * pendientes se descartan — operación destructiva.
+     */
+    async cancel(campaignId) {
+      const res = await doFetch(`${base}/campaigns/${campaignId}/cancel`, {
+        method: "POST"
+      });
+      return res.json();
+    },
+    /**
+     * Descarga el CSV con todas las ejecuciones de la campaña. Devuelve un
+     * `Blob` con `text/csv; charset=utf-8` (BOM UTF-8 incluido). Para
+     * campañas > 20,000 filas la API responde 413.
+     */
+    async exportExecutions(campaignId) {
+      const res = await doFetch(
+        `${base}/campaigns/${campaignId}/executions/export`,
+        {
+          method: "GET",
+          headers: { Accept: "text/csv" }
+        }
+      );
+      return res.blob();
     }
   };
 }
@@ -1594,6 +1653,42 @@ function createCatalogsApi(cfg) {
   };
 }
 
+// src/api/sip-trunks.ts
+function createSipTrunksApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  return {
+    async list() {
+      const res = await doFetch(`${base}/sip/trunks`, { method: "GET" });
+      return res.json();
+    },
+    async get(trunkId) {
+      const res = await doFetch(`${base}/sip/trunks/${trunkId}`, {
+        method: "GET"
+      });
+      return res.json();
+    },
+    async create(body) {
+      const res = await doFetch(`${base}/sip/trunks`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      return res.json();
+    },
+    async update(trunkId, body) {
+      const res = await doFetch(`${base}/sip/trunks/${trunkId}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      return res.json();
+    },
+    async delete(trunkId) {
+      await doFetch(`${base}/sip/trunks/${trunkId}`, { method: "DELETE" });
+    }
+  };
+}
+
 // src/api/tools.ts
 var IDEMPOTENCY_HEADER = "Idempotency-Key";
 var generateIdempotencyKey = (explicit) => {
@@ -1783,6 +1878,74 @@ function createToolsApi(cfg) {
   };
 }
 
+// src/api/usage.ts
+var import_api_query_builder = require("@getsupervisor/api-query-builder");
+function createUsageApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  const fetchUsageAgentsPage = async (options = {}) => {
+    const { resource, from, to, ...listOptions } = options;
+    const query = serializeListOptions({
+      ...listOptions,
+      filter: resolveFilter(
+        buildUsageFilter(resource, from, to),
+        listOptions.filter
+      )
+    });
+    const res = await doFetch(`${base}/usage/agents`, {
+      method: "GET",
+      query
+    });
+    return res.json();
+  };
+  return {
+    async agents(options = {}) {
+      const normalizedOptions = {
+        ...options
+      };
+      const response = await fetchUsageAgentsPage(normalizedOptions);
+      return attachPaginator(response, fetchUsageAgentsPage, normalizedOptions);
+    }
+  };
+}
+function resolveFilter(usageFilter, fallback) {
+  if (usageFilter) {
+    return usageFilter;
+  }
+  return fallback;
+}
+function appendCondition(query, factory) {
+  if (query) {
+    query.and(factory);
+    return query;
+  }
+  return new import_api_query_builder.Query(factory);
+}
+var DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+function toISOString(value) {
+  const input = DATE_ONLY.test(value) ? `${value}T00:00:00` : value;
+  const date = new Date(input);
+  if (Number.isNaN(date.getTime())) {
+    return value;
+  }
+  return date.toISOString();
+}
+function buildUsageFilter(resource, from, to) {
+  let query;
+  if (resource) {
+    query = appendCondition(query, (qb) => qb.eq("resource", resource));
+  }
+  if (from) {
+    query = appendCondition(
+      query,
+      (qb) => qb.mte("createdAt", toISOString(from))
+    );
+  }
+  if (to) {
+    query = appendCondition(query, (qb) => qb.lt("createdAt", toISOString(to)));
+  }
+  return query;
+}
+
 // src/utils/catalog-voices.ts
 var FALLBACK_LOCALE = "und";
 var FALLBACK_PROVIDER = "catalog";
@@ -1841,9 +2004,9 @@ function pickGender(value) {
 }
 
 // src/utils/catalog-filter.ts
-var import_api_query_builder = require("@getsupervisor/api-query-builder");
+var import_api_query_builder2 = require("@getsupervisor/api-query-builder");
 function createCatalogTypeQuery(type) {
-  return new import_api_query_builder.Query((qb) => qb.eq("type", type));
+  return new import_api_query_builder2.Query((qb) => qb.eq("type", type));
 }
 function ensureCatalogTypeFilter(filter, type) {
   const requiredQuery = createCatalogTypeQuery(type);
@@ -2079,6 +2242,35 @@ function createWebhooksApi(cfg) {
         `${base}/webhooks/${webhookId}/subscriptions/${subscriptionId}`,
         { method: "DELETE" }
       );
+    },
+    // Deliveries
+    async listDeliveries(webhookId, options = {}) {
+      const fetchPage = async (opts) => {
+        const query = serializeListOptions({
+          page: opts.page,
+          limit: opts.limit,
+          sort: opts.sort,
+          fields: opts.fields,
+          include: opts.include,
+          search: opts.search,
+          filter: opts.filter
+        });
+        const res = await doFetch(`${base}/webhooks/${webhookId}/deliveries`, {
+          method: "GET",
+          query
+        });
+        return res.json();
+      };
+      const normalized = { ...options ?? {} };
+      const response = await fetchPage(normalized);
+      return attachPaginator(response, fetchPage, normalized);
+    },
+    async getDelivery(webhookId, deliveryId) {
+      const res = await doFetch(
+        `${base}/webhooks/${webhookId}/deliveries/${deliveryId}`,
+        { method: "GET" }
+      );
+      return res.json();
     }
   };
 }
@@ -2261,7 +2453,10 @@ function createClient(initialCfg) {
     campaigns: createCampaignsApi(runtimeCfg),
     voices: voicesApi,
     apiKeys: apiKeysApi,
+    billing: createBillingApi(runtimeCfg),
     calls: callsApi,
+    usage: createUsageApi(runtimeCfg),
+    sip: createSipTrunksApi(runtimeCfg),
     webhooks: webhooksApi
   };
   return {
@@ -2345,13 +2540,16 @@ function createClient(initialCfg) {
   createAgentVersionsApi,
   createAgentsApi,
   createApiKeysApi,
+  createBillingApi,
   createCallsApi,
   createCampaignsApi,
   createCatalogTemplatesApi,
   createCatalogsApi,
   createClient,
   createHttp,
+  createSipTrunksApi,
   createToolsApi,
+  createUsageApi,
   createVoicesApi,
   createWebhooksApi,
   createWorkspacesApi,