@getsupervisor/agents-studio-sdk 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## v1.25.0
+
+## [1.25.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.24.0...v1.25.0) (2025-11-06)
+
+### Features
+
+* enhance blueprint stage functionality with goalPrompt and promptInstructions attributes ([9d13681](https://github.com/julio-supervisor/agents-studio-be/commit/9d13681346f9ea48f5dd6b9c16ab90c95a81356d))
+* implement blueprint stages and triggers ([b94e0d9](https://github.com/julio-supervisor/agents-studio-be/commit/b94e0d9723bf6406a9163d3d9dc998ada06be10a))
+* refactor agent creation and blueprint building for improved test clarity and functionality ([136d5b1](https://github.com/julio-supervisor/agents-studio-be/commit/136d5b12a725d65e6d2fd77e224cc6615e3707d1))
+* update blueprint stage to use goalPrompt and promptInstructions ([0e7bf89](https://github.com/julio-supervisor/agents-studio-be/commit/0e7bf89ed94853ad856c155e0f71e1ba1dafea84))
+
+
+## v1.24.0
+
+## [1.24.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.23.0...v1.24.0) (2025-11-05)
+
+### Features
+
+* add optional avatarUrl and debounceDelayMs to agent schema ([b909f45](https://github.com/julio-supervisor/agents-studio-be/commit/b909f457ef82df455e77ae8ec772a4ff1de3b763))
+* 
+## v1.23.0
+
+## [1.23.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.22.2...v1.23.0) (2025-11-05)
+
+### Features
+
+* implement Agent Stages and Triggers API ([c0b997f](https://github.com/julio-supervisor/agents-studio-be/commit/c0b997fd233f8cb1fb4fc2f43b36344e46675191))
+
+## v1.22.2
+
+## [1.22.2](https://github.com/julio-supervisor/agents-studio-be/compare/v1.22.1...v1.22.2) (2025-11-03)
+
+### Bug Fixes
+
+* update API base URL to production endpoint across multiple files ([7491ce7](https://github.com/julio-supervisor/agents-studio-be/commit/7491ce700f348682d6559a5f3e9cf93f4aa9bc70))
+
+
 ## v1.22.1
 
 ## [1.22.1](https://github.com/julio-supervisor/agents-studio-be/compare/v1.22.0...v1.22.1) (2025-11-03)

package/README.md

@@ -34,22 +34,20 @@ await client.agents
 
 // administrar blueprints por versión
 const blueprints = client.agents.blueprints(agent.agentId);
-await blueprints
-  .version('version-1')
-  .create({
-    languageId: 'es-MX',
-    personalityName: 'Embajador de marca',
-    personalityRole: 'Consultor de adopción',
-    targetAudience: 'Usuarios nuevos',
-    mainGoal: 'Incrementar la activación',
-    personalityInitialGreeting: '¡Hola! Soy tu asistente de onboarding.',
-    personalityMessageStyleId: 'style-uuid',
-    personalityToneStyleId: 'tone-uuid',
-    requiredData: [{ key: 'industry', label: 'Industria' }],
-    criticalRules: ['Nunca compartas precios internos'],
-    topicsAllowed: ['onboarding', 'soporte'],
-    topicsForbidden: ['facturación'],
-  });
+await blueprints.version('version-1').create({
+  languageId: 'es-MX',
+  personalityName: 'Embajador de marca',
+  personalityRole: 'Consultor de adopción',
+  targetAudience: 'Usuarios nuevos',
+  mainGoal: 'Incrementar la activación',
+  personalityInitialGreeting: '¡Hola! Soy tu asistente de onboarding.',
+  personalityMessageStyleId: 'style-uuid',
+  personalityToneStyleId: 'tone-uuid',
+  requiredData: [{ key: 'industry', label: 'Industria' }],
+  criticalRules: ['Nunca compartas precios internos'],
+  topicsAllowed: ['onboarding', 'soporte'],
+  topicsForbidden: ['facturación'],
+});
 
 // los helpers del entity también exponen blueprints
 const agentBlueprint = await agent.blueprints.version('version-1').get();
@@ -164,6 +162,55 @@ const v2 = await client.agentVersions.clone(agent.agentId, active.id);
 
 Estados soportados: `draft`, `active`, `archived`.
 
+## Stages del blueprint
+
+Modela el flujo conversacional de cada agente con los helpers `client.agents.stages(agentId)`, indicando siempre qué blueprint deseas administrar.
+
+```ts
+const stages = client.agents.stages(agent.agentId);
+const activeBlueprint = await client.agents.blueprints(agent.agentId).list();
+const blueprintId = activeBlueprint.data[0].blueprint.id;
+
+// Paginar stages existentes
+const page = await stages.list(blueprintId, { limit: 10, search: 'greeting' });
+console.log(page.meta.total);
+
+// También puedes obtener un helper con el blueprint preseleccionado
+const blueprintStages = stages(blueprintId);
+
+// Crear un stage
+const created = await blueprintStages.create({
+  name: 'proposal',
+  title: 'Propuesta y cierre',
+  goalPrompt:
+    'Explica la solución recomendada y ofrece una llamada con humano.',
+  order: 2,
+  metadata: { requiresSupervisor: false },
+});
+
+// Actualizar y reordenar
+await blueprintStages.update(created.id, {
+  goalPrompt: 'Resume beneficios en < 3 bullets y ofrece agendar demo.',
+});
+
+await stages.reorder(blueprintId, {
+  stageIds: [page.data[0].id, created.id],
+  startingStageName: 'greeting',
+});
+
+// Triggers por stage
+const triggers = stages.triggers(blueprintId, created.id);
+await triggers.create({
+  condition: { type: 'intent', value: 'schedule_call' },
+  nextStageName: 'handoff',
+});
+
+const listing = await triggers.list();
+console.log(listing.data[0].condition);
+```
+
+Los métodos de triggers permiten `list`, `get`, `create`, `update` y `delete`. Recuerda habilitar los scopes `blueprint-stages:*` y `stage-triggers:*` en la credencial utilizada.
+
 ## Horarios del agente (Agent Schedules)
 
 Namespaces: `client.agentSchedule` y `client.agentScheduleExceptions`
@@ -309,7 +356,9 @@ client.workspace.get(); // 'ws-123'
 client.workspace.set('ws-456');
 
 // o delegar en un getter dinámico (por ejemplo, almacenamiento local)
-client.workspace.useGetter(() => sessionStorage.getItem('workspace') ?? undefined);
+client.workspace.useGetter(
+  () => sessionStorage.getItem('workspace') ?? undefined,
+);
 
 // crear un cliente aislado para otro workspace
 const scoped = client.workspace.scoped('ws-789');
@@ -399,26 +448,26 @@ const { key, ...metadata } = await http
 
 ### Scopes disponibles (octubre 2025)
 
-| Scope | Permiso principal |
-|-------|-------------------|
-| `agents:read` | Consultar agentes, versiones, instrucciones, teléfonos y blueprints asociados. |
-| `agents:write` | Crear, actualizar o eliminar agentes, versiones, teléfonos y su configuración operativa. |
-| `agent-instructions:read` | Leer instrucciones tanto a nivel agente como por versión publicada. |
-| `agent-instructions:write` | Crear, actualizar o borrar instrucciones personalizadas. |
-| `agent-blueprints:read` | Consultar blueprint y resúmenes sincronizados con proveedores externos. |
-| `agent-blueprints:write` | Editar blueprint, personalidad y reglas de cada versión. |
-| `agent-schedules:read` | Consultar horario semanal y excepciones vigentes. |
-| `agent-schedules:write` | Crear o modificar horarios y excepciones. |
-| `catalogs:read` | Navegar catálogos globales y por workspace (idiomas, estilos, voces, etc.). |
-| `catalogs:write` | Registrar o ajustar ítems de catálogo. |
-| `tools:read` | Descubrir tools disponibles, recursos y capacidades declaradas. |
-| `tools:connections:write` | Crear conexiones entre agentes y tools (p. ej. `voice.calls`). |
-| `tools:execute` | Ejecutar acciones de una tool (`startCall`, `reload`, etc.). |
-| `webhooks:read` | Listar webhooks y sus suscripciones activas. |
-| `webhooks:write` | Crear, actualizar o eliminar webhooks y suscripciones. |
-| `api-keys:read` | Listar credenciales existentes y revelar su valor. |
-| `api-keys:write` | Emitir o revocar API Keys. |
-| `workspaces:read` | Consultar metadatos y estado de habilitación de un workspace. |
+| Scope                      | Permiso principal                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `agents:read`              | Consultar agentes, versiones, instrucciones, teléfonos y blueprints asociados.           |
+| `agents:write`             | Crear, actualizar o eliminar agentes, versiones, teléfonos y su configuración operativa. |
+| `agent-instructions:read`  | Leer instrucciones tanto a nivel agente como por versión publicada.                      |
+| `agent-instructions:write` | Crear, actualizar o borrar instrucciones personalizadas.                                 |
+| `agent-blueprints:read`    | Consultar blueprint y resúmenes sincronizados con proveedores externos.                  |
+| `agent-blueprints:write`   | Editar blueprint, personalidad y reglas de cada versión.                                 |
+| `agent-schedules:read`     | Consultar horario semanal y excepciones vigentes.                                        |
+| `agent-schedules:write`    | Crear o modificar horarios y excepciones.                                                |
+| `catalogs:read`            | Navegar catálogos globales y por workspace (idiomas, estilos, voces, etc.).              |
+| `catalogs:write`           | Registrar o ajustar ítems de catálogo.                                                   |
+| `tools:read`               | Descubrir tools disponibles, recursos y capacidades declaradas.                          |
+| `tools:connections:write`  | Crear conexiones entre agentes y tools (p. ej. `voice.calls`).                           |
+| `tools:execute`            | Ejecutar acciones de una tool (`startCall`, `reload`, etc.).                             |
+| `webhooks:read`            | Listar webhooks y sus suscripciones activas.                                             |
+| `webhooks:write`           | Crear, actualizar o eliminar webhooks y suscripciones.                                   |
+| `api-keys:read`            | Listar credenciales existentes y revelar su valor.                                       |
+| `api-keys:write`           | Emitir o revocar API Keys.                                                               |
+| `workspaces:read`          | Consultar metadatos y estado de habilitación de un workspace.                            |
 
 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.
 
@@ -427,6 +476,7 @@ Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para validar scopes adicional
 - **Guías de uso para voice.calls**: las conexiones creadas con `client.tools.connect('voice.calls', ...)` ahora devuelven valores predeterminados en `descriptionUsage` y `usageExample` (ver `docs/mcp/tools_execution.md`).
 - **Gestión de API Keys desde el SDK**: `client.apiKeys` expone helpers tipados para listar, crear y revocar credenciales con el mismo manejo de cabeceras, timeouts y reintentos del resto del cliente.
 - **Scopes documentados**: tabla de scopes disponibles y recomendaciones para definir permisos mínimos por workspace.
+- **Blueprint stages y triggers**: nuevos helpers `client.agents.stages(agentId)` y `stages.triggers(stageId)` para CRUD completo y reordenamiento del flujo conversacional.
 - **Mejoras de gobernanza**: se incorporaron pautas de rotación, almacenamiento seguro y segmentación por entorno directamente en la guía del SDK.
 - **Catálogos**: nuevo namespace `client.catalogs` con CRUD y paginación para `language`, `message_style`, `tone_style`, `tag` y `voice`.
 - **Versiones de agente**: namespace `client.agentVersions` con operaciones para crear, clonar, publicar y gestionar instrucciones por versión.

package/dist/index.cjs

@@ -661,7 +661,7 @@ function createAgentScheduleApi(cfg) {
 function createAgentStageTriggersApi(cfg) {
   const { base, doFetch } = createHttp(cfg);
   const jsonHeaders = { "content-type": "application/json" };
-  const fetchTriggerPage = async (agentId, stageId, options = {}) => {
+  const fetchTriggerPage = async (agentId, blueprintId, stageId, options = {}) => {
     const normalizedOptions = {
       page: options.page,
       limit: options.limit,
@@ -674,7 +674,7 @@ function createAgentStageTriggersApi(cfg) {
     };
     const query = serializeListOptions(normalizedOptions);
     const res = await doFetch(
-      `${base}/agents/${agentId}/stages/${stageId}/triggers`,
+      `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}/triggers`,
       {
         method: "GET",
         query
@@ -683,26 +683,26 @@ function createAgentStageTriggersApi(cfg) {
     return res.json();
   };
   return {
-    async list(agentId, stageId, options = {}) {
+    async list(agentId, blueprintId, stageId, options = {}) {
       const normalized = {
         ...options ?? {}
       };
-      const fetchPage = (opts) => fetchTriggerPage(agentId, stageId, opts);
+      const fetchPage = (opts) => fetchTriggerPage(agentId, blueprintId, stageId, opts);
       const response = await fetchPage(normalized);
       return attachPaginator(response, fetchPage, normalized);
     },
-    async get(agentId, stageId, triggerId) {
+    async get(agentId, blueprintId, stageId, triggerId) {
       const res = await doFetch(
-        `${base}/agents/${agentId}/stages/${stageId}/triggers/${triggerId}`,
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}/triggers/${triggerId}`,
         {
           method: "GET"
         }
       );
       return res.json();
     },
-    async create(agentId, stageId, payload) {
+    async create(agentId, blueprintId, stageId, payload) {
       const res = await doFetch(
-        `${base}/agents/${agentId}/stages/${stageId}/triggers`,
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}/triggers`,
         {
           method: "POST",
           headers: jsonHeaders,
@@ -711,9 +711,9 @@ function createAgentStageTriggersApi(cfg) {
       );
       return res.json();
     },
-    async update(agentId, stageId, triggerId, payload) {
+    async update(agentId, blueprintId, stageId, triggerId, payload) {
       const res = await doFetch(
-        `${base}/agents/${agentId}/stages/${stageId}/triggers/${triggerId}`,
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}/triggers/${triggerId}`,
         {
           method: "PATCH",
           headers: jsonHeaders,
@@ -722,9 +722,9 @@ function createAgentStageTriggersApi(cfg) {
       );
       return res.json();
     },
-    async delete(agentId, stageId, triggerId) {
+    async delete(agentId, blueprintId, stageId, triggerId) {
       await doFetch(
-        `${base}/agents/${agentId}/stages/${stageId}/triggers/${triggerId}`,
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}/triggers/${triggerId}`,
         {
           method: "DELETE"
         }
@@ -737,7 +737,7 @@ function createAgentStageTriggersApi(cfg) {
 function createAgentStagesApi(cfg) {
   const { base, doFetch } = createHttp(cfg);
   const jsonHeaders = { "content-type": "application/json" };
-  const fetchStagePage = async (agentId, options = {}) => {
+  const fetchStagePage = async (agentId, blueprintId, options = {}) => {
     const normalizedOptions = {
       page: options.page,
       limit: options.limit,
@@ -746,52 +746,70 @@ function createAgentStagesApi(cfg) {
       search: options.search
     };
     const query = serializeListOptions(normalizedOptions);
-    const res = await doFetch(`${base}/agents/${agentId}/stages`, {
-      method: "GET",
-      query
-    });
+    const res = await doFetch(
+      `${base}/agents/${agentId}/blueprints/${blueprintId}/stages`,
+      {
+        method: "GET",
+        query
+      }
+    );
     return res.json();
   };
   return {
-    async list(agentId, options = {}) {
+    async list(agentId, blueprintId, options = {}) {
       const normalized = { ...options ?? {} };
-      const fetchPage = (opts) => fetchStagePage(agentId, opts);
+      const fetchPage = (opts) => fetchStagePage(agentId, blueprintId, opts);
       const response = await fetchPage(normalized);
       return attachPaginator(response, fetchPage, normalized);
     },
-    async get(agentId, stageId) {
-      const res = await doFetch(`${base}/agents/${agentId}/stages/${stageId}`, {
-        method: "GET"
-      });
+    async get(agentId, blueprintId, stageId) {
+      const res = await doFetch(
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}`,
+        {
+          method: "GET"
+        }
+      );
       return res.json();
     },
-    async create(agentId, payload) {
-      const res = await doFetch(`${base}/agents/${agentId}/stages`, {
-        method: "POST",
-        headers: jsonHeaders,
-        body: JSON.stringify(payload)
-      });
+    async create(agentId, blueprintId, payload) {
+      const res = await doFetch(
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages`,
+        {
+          method: "POST",
+          headers: jsonHeaders,
+          body: JSON.stringify(payload)
+        }
+      );
       return res.json();
     },
-    async update(agentId, stageId, payload) {
-      const res = await doFetch(`${base}/agents/${agentId}/stages/${stageId}`, {
-        method: "PATCH",
-        headers: jsonHeaders,
-        body: JSON.stringify(payload)
-      });
+    async update(agentId, blueprintId, stageId, payload) {
+      const res = await doFetch(
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}`,
+        {
+          method: "PATCH",
+          headers: jsonHeaders,
+          body: JSON.stringify(payload)
+        }
+      );
       return res.json();
     },
-    async delete(agentId, stageId) {
-      await doFetch(`${base}/agents/${agentId}/stages/${stageId}`, {
-        method: "DELETE"
-      });
+    async delete(agentId, blueprintId, stageId) {
+      await doFetch(
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages/${stageId}`,
+        {
+          method: "DELETE"
+        }
+      );
     },
-    async reorder(agentId, payload) {
-      const res = await doFetch(`${base}/agents/${agentId}/stages:reorder`, {
-        method: "POST",
-        headers: jsonHeaders,
-        body: JSON.stringify(payload)
-      });
+    async reorder(agentId, blueprintId, payload) {
+      const res = await doFetch(
+        `${base}/agents/${agentId}/blueprints/${blueprintId}/stages:reorder`,
+        {
+          method: "POST",
+          headers: jsonHeaders,
+          body: JSON.stringify(payload)
+        }
+      );
       return res.json();
     }
   };
@@ -949,46 +967,71 @@ var bindAgentInstructions = (api, agentId) => ({
     return api.delete(agentId, instructionId);
   }
 });
-var bindAgentStageTriggers = (api, agentId, stageId) => ({
+var bindAgentStageTriggers = (api, agentId, blueprintId, stageId) => ({
   list(opts) {
-    return api.list(agentId, stageId, opts);
+    return api.list(agentId, blueprintId, stageId, opts);
   },
   get(triggerId) {
-    return api.get(agentId, stageId, triggerId);
+    return api.get(agentId, blueprintId, stageId, triggerId);
   },
   create(payload) {
-    return api.create(agentId, stageId, payload);
+    return api.create(agentId, blueprintId, stageId, payload);
   },
   update(triggerId, payload) {
-    return api.update(agentId, stageId, triggerId, payload);
+    return api.update(agentId, blueprintId, stageId, triggerId, payload);
   },
   delete(triggerId) {
-    return api.delete(agentId, stageId, triggerId);
-  }
-});
-var bindAgentStages = (stagesApi, triggersApi, agentId) => ({
-  list(opts) {
-    return stagesApi.list(agentId, opts);
-  },
-  get(stageId) {
-    return stagesApi.get(agentId, stageId);
-  },
-  create(payload) {
-    return stagesApi.create(agentId, payload);
-  },
-  update(stageId, payload) {
-    return stagesApi.update(agentId, stageId, payload);
-  },
-  delete(stageId) {
-    return stagesApi.delete(agentId, stageId);
-  },
-  reorder(payload) {
-    return stagesApi.reorder(agentId, payload);
-  },
-  triggers(stageId) {
-    return bindAgentStageTriggers(triggersApi, agentId, stageId);
+    return api.delete(agentId, blueprintId, stageId, triggerId);
   }
 });
+var bindAgentStages = (stagesApi, triggersApi, agentId) => {
+  const forBlueprint = (blueprintId) => ({
+    list(opts) {
+      return stagesApi.list(agentId, blueprintId, opts);
+    },
+    get(stageId) {
+      return stagesApi.get(agentId, blueprintId, stageId);
+    },
+    create(payload) {
+      return stagesApi.create(agentId, blueprintId, payload);
+    },
+    update(stageId, payload) {
+      return stagesApi.update(agentId, blueprintId, stageId, payload);
+    },
+    delete(stageId) {
+      return stagesApi.delete(agentId, blueprintId, stageId);
+    },
+    reorder(payload) {
+      return stagesApi.reorder(agentId, blueprintId, payload);
+    },
+    triggers(stageId) {
+      return bindAgentStageTriggers(triggersApi, agentId, blueprintId, stageId);
+    }
+  });
+  return Object.assign(forBlueprint, {
+    list(blueprintId, opts) {
+      return stagesApi.list(agentId, blueprintId, opts);
+    },
+    get(blueprintId, stageId) {
+      return stagesApi.get(agentId, blueprintId, stageId);
+    },
+    create(blueprintId, payload) {
+      return stagesApi.create(agentId, blueprintId, payload);
+    },
+    update(blueprintId, stageId, payload) {
+      return stagesApi.update(agentId, blueprintId, stageId, payload);
+    },
+    delete(blueprintId, stageId) {
+      return stagesApi.delete(agentId, blueprintId, stageId);
+    },
+    reorder(blueprintId, payload) {
+      return stagesApi.reorder(agentId, blueprintId, payload);
+    },
+    triggers(blueprintId, stageId) {
+      return bindAgentStageTriggers(triggersApi, agentId, blueprintId, stageId);
+    }
+  });
+};
 var bindAgentTags = (api, agentId) => ({
   add(tagId) {
     return api.add(agentId, { tagId });
@@ -1884,7 +1927,7 @@ function createClient(initialCfg) {
     blueprintsApi
   );
   const stageTriggersNamespace = Object.assign(
-    (agentId, stageId) => bindAgentStageTriggers(stageTriggersApi, agentId, stageId),
+    (agentId, blueprintId, stageId) => bindAgentStageTriggers(stageTriggersApi, agentId, blueprintId, stageId),
     stageTriggersApi
   );
   const stagesNamespace = Object.assign(