@getsupervisor/agents-studio-sdk 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## v1.15.0
+
+## [1.15.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.14.0...v1.15.0) (2025-10-21)
+
+### Features
+
+* agregar manejador y comando para la creación de horarios de agentes, incluyendo pruebas unitarias y mapeo de comandos ([682411b](https://github.com/julio-supervisor/agents-studio-be/commit/682411bc016f09adc8928f5b284af111c82764e5))
+* agregar manejo de excepciones en horarios de agentes, incluyendo operaciones para obtener, actualizar, eliminar y listar excepciones ([1beacf6](https://github.com/julio-supervisor/agents-studio-be/commit/1beacf69ff17246e43d9ba7e8cfba73e4cb1f872))
+* agregar pruebas para el manejo de excepciones en horarios de agentes ([3d6f8b4](https://github.com/julio-supervisor/agents-studio-be/commit/3d6f8b45a663cfd64725be4f6671d844b55b3cb2))
+* agregar pruebas unitarias para el mapeo y la gestión de excepciones de horarios de agentes ([6bfc2f9](https://github.com/julio-supervisor/agents-studio-be/commit/6bfc2f96721166cb8b7bf14501a0bd48e5e4b25d))
+* agregar pruebas unitarias para la fábrica de especificaciones de versiones de agentes, incluyendo filtros y manejo de excepciones ([8868f78](https://github.com/julio-supervisor/agents-studio-be/commit/8868f78aa2307a39750dd08d932c8c3bf69b4112))
+* agregar pruebas unitarias para la gestión de excepciones y horarios de agentes, incluyendo especificaciones de tipo ORM ([592c016](https://github.com/julio-supervisor/agents-studio-be/commit/592c01673be38d7e1188a89f8103e226b05a4e47))
+* agregar pruebas unitarias para la gestión de versiones de agentes y especificaciones de tipo ORM ([898350f](https://github.com/julio-supervisor/agents-studio-be/commit/898350f17ce4d9390d47adb66d8f00066ee25f82))
+* Enhance ListAgentScheduleExceptionsHandler to support combined filter and or conditions ([bf6e881](https://github.com/julio-supervisor/agents-studio-be/commit/bf6e881d61895ffac98c3cfd9e2b2c35d7745274))
+* implement agent schedule and exception management ([3502cf6](https://github.com/julio-supervisor/agents-studio-be/commit/3502cf623a4fd4440ae8a9cd2b3acbcf982fe15e))
+* implementar API para excepciones de horarios de agentes, incluyendo métodos para listar, obtener, crear, actualizar y eliminar excepciones ([154ddee](https://github.com/julio-supervisor/agents-studio-be/commit/154ddeed944c7905a40ed71e697773ee28ffa5ce))
+
+
 ## v1.14.0
 
 ## [1.14.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.13.0...v1.14.0) (2025-10-21)

package/README.md

@@ -63,6 +63,164 @@ await client.tools.uploadResource(tools.data[0].identifier, formData);
 await client.agents.delete(agent.agentId);
 ```
 
+## Catálogos (Catalogs)
+
+Los catálogos exponen valores normalizados reutilizables (idiomas, estilos de mensaje, estilos de tono, etiquetas y voces).
+
+Namespace: `client.catalogs`
+
+Operaciones disponibles:
+
+- `catalogs.list(options?)` — lista items paginados con filtros y búsqueda.
+- `catalogs.get(itemId)` — obtiene el detalle de un item.
+- `catalogs.create(payload)` — crea un nuevo item de catálogo.
+- `catalogs.remove(itemId)` — elimina (soft-delete) un item.
+
+Ejemplos:
+
+```ts
+// listar idiomas globales con búsqueda y paginación
+const page1 = await client.catalogs.list({
+  search: 'spanish',
+  filter: { type: 'language', scope: 'global' },
+  limit: 20,
+});
+
+const page2 = await page1.next();
+
+// crear un idioma global
+const language = await client.catalogs.create({
+  type: 'language',
+  scope: 'global',
+  name: 'Español (México)',
+  description: 'Variante de español latino con modismos mexicanos',
+  metadata: { code: 'es', locale: 'es-MX' },
+});
+
+// crear una voz por workspace (requiere workspaceId)
+const voice = await client.catalogs.create({
+  type: 'voice',
+  scope: 'workspace',
+  workspaceId: client.workspace.get(),
+  name: 'Brand Voice A',
+  description: 'Voz femenina, cálida',
+  metadata: {
+    language: 'es',
+    gender: 'female',
+    tone: 'warm',
+    provider: 'elevenlabs',
+    previewUrl: 'https://cdn.example.com/voices/brand-a.mp3',
+  },
+});
+
+// eliminar por id
+await client.catalogs.remove(language.data.id);
+```
+
+Notas:
+
+- Campos `type` válidos: `language`, `message_style`, `tone_style`, `tag`, `voice`.
+- `scope` puede ser `global` o `workspace`. Si es `workspace`, envía `workspaceId`.
+- El shape de `metadata` depende de `type` (ver ejemplos arriba).
+
+## Versiones de agente (Agent Versions)
+
+Namespace: `client.agentVersions`
+
+Operaciones clave:
+
+- `agentVersions.list(agentId, { page, limit, filter })`
+- `agentVersions.get(agentId, versionId)`
+- `agentVersions.create(agentId, payload?)` — crea versión en `draft`.
+- `agentVersions.clone(agentId, versionId)` — clona una versión.
+- `agentVersions.publish(agentId, versionId, payload?)` — publica y marca como `active`.
+- `agentVersions.updateNotes(agentId, versionId, { notes })`
+- Instrucciones por versión:
+  - `agentVersions.listInstructions(agentId, versionId, opts?)`
+  - `agentVersions.createInstruction(agentId, versionId, dto)`
+  - `agentVersions.updateInstruction(agentId, versionId, instructionId, dto)`
+  - `agentVersions.deleteInstruction(agentId, versionId, instructionId)`
+
+Ejemplo:
+
+```ts
+// crear una nueva versión draft
+const v1 = await client.agentVersions.create(agent.agentId);
+
+// agregar instrucciones a la versión
+await client.agentVersions.createInstruction(agent.agentId, v1.id, {
+  order: 0,
+  content: 'Saluda con empatía y brevedad',
+});
+
+// publicar la versión
+const active = await client.agentVersions.publish(agent.agentId, v1.id, {
+  notes: 'Primera publicación estable',
+});
+
+// clonar una versión activa (crea un nuevo draft)
+const v2 = await client.agentVersions.clone(agent.agentId, active.id);
+```
+
+Estados soportados: `draft`, `active`, `archived`.
+
+## Horarios del agente (Agent Schedules)
+
+Namespaces: `client.agentSchedule` y `client.agentScheduleExceptions`
+
+Operaciones de horario semanal (`agentSchedule`):
+
+- `get(agentId)` — obtiene el horario semanal.
+- `create(agentId, dto)` — crea/establece horario.
+- `update(agentId, dto)` — actualiza horario.
+
+Ejemplo de horario:
+
+```ts
+// activar horario de lunes a viernes con timezone America/Mexico_City
+await client.agentSchedule.create(agent.agentId, {
+  timezone: 'America/Mexico_City',
+  isEnabled: true,
+  monday: { enabled: true, start: '09:00', end: '18:00' },
+  tuesday: { enabled: true, start: '09:00', end: '18:00' },
+  wednesday: { enabled: true, start: '09:00', end: '18:00' },
+  thursday: { enabled: true, start: '09:00', end: '18:00' },
+  friday: { enabled: true, start: '09:00', end: '18:00' },
+  saturday: { enabled: false },
+  sunday: { enabled: false },
+  outOfHoursBehavior: 'offline',
+  outOfHoursMessage: 'Nuestro equipo está fuera de horario. Vuelve más tarde.',
+});
+```
+
+Operaciones de excepciones por fecha (`agentScheduleExceptions`):
+
+- `list(agentId, opts?)` — paginado con filtros (por rango de fechas, etc.).
+- `get(agentId, exceptionId)`
+- `create(agentId, dto)` — soporte para `isClosed` o ventana `startTime`/`endTime`.
+- `update(agentId, exceptionId, dto)`
+- `delete(agentId, exceptionId)`
+
+Ejemplo de excepciones:
+
+```ts
+// feriado: cerrado todo el día
+await client.agentScheduleExceptions.create(agent.agentId, {
+  exceptionDate: '2025-11-20',
+  isClosed: true,
+  reason: 'Día de la Revolución',
+});
+
+// media jornada en una fecha específica
+await client.agentScheduleExceptions.create(agent.agentId, {
+  exceptionDate: '2025-12-24',
+  isClosed: false,
+  startTime: '09:00',
+  endTime: '13:00',
+  reason: 'Nochebuena',
+});
+```
+
 ### Ejemplo de CRUD completo
 
 Consulta el archivo `examples/agents-crud.ts` para ver un flujo end-to-end que:
@@ -218,6 +376,9 @@ Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para revisar nuevos scopes co
 - **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.
 - **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.
+- **Horarios del agente**: namespaces `client.agentSchedule` y `client.agentScheduleExceptions` para configurar disponibilidad semanal y excepciones por fecha.
 
 ## Errores tipados y reintentos
 

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   createAgentVersionsApi: () => createAgentVersionsApi,
   createAgentsApi: () => createAgentsApi,
   createApiKeysApi: () => createApiKeysApi,
+  createCatalogsApi: () => createCatalogsApi,
   createClient: () => createClient,
   createHttp: () => createHttp,
   createToolsApi: () => createToolsApi,
@@ -1095,6 +1096,52 @@ function createApiKeysApi(cfg) {
   };
 }
 
+// src/api/catalogs.ts
+function createCatalogsApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  const jsonHeaders = { "content-type": "application/json" };
+  const fetchCatalogItemsPage = async (options = {}) => {
+    const query = serializeListOptions(options ?? {});
+    const res = await doFetch(`${base}/v1/catalogs/items`, {
+      method: "GET",
+      query
+    });
+    return res.json();
+  };
+  return {
+    async list(options = {}) {
+      const normalizedOptions = {
+        ...options ?? {}
+      };
+      const response = await fetchCatalogItemsPage(normalizedOptions);
+      return attachPaginator(
+        response,
+        fetchCatalogItemsPage,
+        normalizedOptions
+      );
+    },
+    async get(itemId) {
+      const res = await doFetch(`${base}/v1/catalogs/items/${itemId}`, {
+        method: "GET"
+      });
+      return res.json();
+    },
+    async create(payload) {
+      const res = await doFetch(`${base}/v1/catalogs/items`, {
+        method: "POST",
+        headers: jsonHeaders,
+        body: JSON.stringify(payload)
+      });
+      return res.json();
+    },
+    async remove(itemId) {
+      await doFetch(`${base}/v1/catalogs/items/${itemId}`, {
+        method: "DELETE"
+      });
+    }
+  };
+}
+
 // src/api/tools.ts
 var isFormData = (value) => {
   return typeof FormData !== "undefined" && value instanceof FormData;
@@ -1315,6 +1362,7 @@ function createClient(initialCfg) {
   const blueprintsApi = createAgentBlueprintsApi(runtimeCfg);
   const voicesApi = createVoicesApi(runtimeCfg);
   const apiKeysApi = createApiKeysApi(runtimeCfg);
+  const catalogsApi = createCatalogsApi(runtimeCfg);
   const agentsApi = createAgentsApi(runtimeCfg, {
     instructionsApi,
     tagsApi,
@@ -1367,6 +1415,7 @@ function createClient(initialCfg) {
     },
     workspaces: createWorkspacesApi(runtimeCfg),
     tools: createToolsApi(runtimeCfg),
+    catalogs: catalogsApi,
     voices: voicesApi,
     apiKeys: apiKeysApi
   };
@@ -1447,6 +1496,7 @@ function createClient(initialCfg) {
   createAgentVersionsApi,
   createAgentsApi,
   createApiKeysApi,
+  createCatalogsApi,
   createClient,
   createHttp,
   createToolsApi,