@getsupervisor/agents-studio-sdk 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 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)
+
+### Features
+
+* add Agent Versions controller and related DTOs, enhance publish functionality with notes ([9227708](https://github.com/julio-supervisor/agents-studio-be/commit/92277085c8441fefba4fb52d6859441269132de1))
+* agregar funcionalidades para clonar, publicar y actualizar notas de versiones de agentes, y ajustar esquemas y rutas en la API ([7a01fa0](https://github.com/julio-supervisor/agents-studio-be/commit/7a01fa03ff30e9fd6a9b4358a2df2f709a61c189))
+* agregar mapeo de módulos para la ruta de versiones de agentes en jest.config.js ([11c4e34](https://github.com/julio-supervisor/agents-studio-be/commit/11c4e340608de1b91f2461912b23e3c484e92f59))
+* agregar mapeo de módulos para la ruta de versiones de agentes en package.json ([a63586e](https://github.com/julio-supervisor/agents-studio-be/commit/a63586eb845c21c276776e0d023719a37f4896e5))
+* implement Agent Version Management with TypeORM ([736ed04](https://github.com/julio-supervisor/agents-studio-be/commit/736ed045a4e395674a4ee1c623d44d265421b386))
+
+
 ## v1.13.0
 
 ## [1.13.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.12.0...v1.13.0) (2025-10-20)

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

@@ -26,6 +26,7 @@ __export(index_exports, {
   bindAgentInstructions: () => bindAgentInstructions,
   bindAgentPhones: () => bindAgentPhones,
   bindAgentSchedule: () => bindAgentSchedule,
+  bindAgentScheduleExceptions: () => bindAgentScheduleExceptions,
   bindAgentTags: () => bindAgentTags,
   bindAgentVersions: () => bindAgentVersions,
   createAgentBlueprintsApi: () => createAgentBlueprintsApi,
@@ -33,10 +34,12 @@ __export(index_exports, {
   createAgentInstructionsApi: () => createAgentInstructionsApi,
   createAgentPhonesApi: () => createAgentPhonesApi,
   createAgentScheduleApi: () => createAgentScheduleApi,
+  createAgentScheduleExceptionsApi: () => createAgentScheduleExceptionsApi,
   createAgentTagsApi: () => createAgentTagsApi,
   createAgentVersionsApi: () => createAgentVersionsApi,
   createAgentsApi: () => createAgentsApi,
   createApiKeysApi: () => createApiKeysApi,
+  createCatalogsApi: () => createCatalogsApi,
   createClient: () => createClient,
   createHttp: () => createHttp,
   createToolsApi: () => createToolsApi,
@@ -570,6 +573,14 @@ function createAgentScheduleApi(cfg) {
       });
       return res.json();
     },
+    async create(agentId, payload) {
+      const res = await doFetch(`${base}/v1/agents/${agentId}/schedule`, {
+        method: "POST",
+        headers: jsonHeaders,
+        body: JSON.stringify(payload)
+      });
+      return res.json();
+    },
     async update(agentId, payload) {
       const res = await doFetch(`${base}/v1/agents/${agentId}/schedule`, {
         method: "PUT",
@@ -581,6 +592,72 @@ function createAgentScheduleApi(cfg) {
   };
 }
 
+// src/api/agent-schedule-exceptions.ts
+function createAgentScheduleExceptionsApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  const jsonHeaders = { "content-type": "application/json" };
+  const fetchExceptionsPage = async (agentId, options = {}) => {
+    const query = serializeListOptions(options ?? {});
+    const res = await doFetch(
+      `${base}/v1/agents/${agentId}/schedule/exceptions`,
+      {
+        method: "GET",
+        query
+      }
+    );
+    return res.json();
+  };
+  return {
+    async list(agentId, options = {}) {
+      const normalizedOptions = {
+        ...options ?? {}
+      };
+      const fetchPage = (pageOptions) => fetchExceptionsPage(agentId, pageOptions);
+      const response = await fetchPage(normalizedOptions);
+      return attachPaginator(response, fetchPage, normalizedOptions);
+    },
+    async get(agentId, exceptionId) {
+      const res = await doFetch(
+        `${base}/v1/agents/${agentId}/schedule/exceptions/${exceptionId}`,
+        {
+          method: "GET"
+        }
+      );
+      return res.json();
+    },
+    async create(agentId, payload) {
+      const res = await doFetch(
+        `${base}/v1/agents/${agentId}/schedule/exceptions`,
+        {
+          method: "POST",
+          headers: jsonHeaders,
+          body: JSON.stringify(payload)
+        }
+      );
+      return res.json();
+    },
+    async update(agentId, exceptionId, payload) {
+      const res = await doFetch(
+        `${base}/v1/agents/${agentId}/schedule/exceptions/${exceptionId}`,
+        {
+          method: "PATCH",
+          headers: jsonHeaders,
+          body: JSON.stringify(payload)
+        }
+      );
+      return res.json();
+    },
+    async delete(agentId, exceptionId) {
+      await doFetch(
+        `${base}/v1/agents/${agentId}/schedule/exceptions/${exceptionId}`,
+        {
+          method: "DELETE"
+        }
+      );
+    }
+  };
+}
+
 // src/api/agent-tags.ts
 function createAgentTagsApi(cfg) {
   const { base, doFetch } = createHttp(cfg);
@@ -749,13 +826,34 @@ var bindAgentPhones = (api, agentId) => ({
     return api.disconnect(agentId, phoneId);
   }
 });
-var bindAgentSchedule = (api, agentId) => ({
+var bindAgentScheduleExceptions = (api, agentId) => ({
+  list(opts) {
+    return api.list(agentId, opts);
+  },
+  get(exceptionId) {
+    return api.get(agentId, exceptionId);
+  },
+  create(payload) {
+    return api.create(agentId, payload);
+  },
+  update(exceptionId, payload) {
+    return api.update(agentId, exceptionId, payload);
+  },
+  delete(exceptionId) {
+    return api.delete(agentId, exceptionId);
+  }
+});
+var bindAgentSchedule = (scheduleApi, exceptionsApi, agentId) => ({
   get() {
-    return api.get(agentId);
+    return scheduleApi.get(agentId);
+  },
+  create(payload) {
+    return scheduleApi.create(agentId, payload);
   },
   update(payload) {
-    return api.update(agentId, payload);
-  }
+    return scheduleApi.update(agentId, payload);
+  },
+  exceptions: bindAgentScheduleExceptions(exceptionsApi, agentId)
 });
 var bindAgentVersions = (api, agentId) => ({
   list(opts) {
@@ -822,6 +920,7 @@ var createAgentEntity = (dto, options) => {
     tagsApi,
     phonesApi,
     scheduleApi,
+    scheduleExceptionsApi,
     versionsApi,
     blueprintsApi,
     reload,
@@ -833,7 +932,11 @@ var createAgentEntity = (dto, options) => {
     instructions: bindAgentInstructions(instructionsApi, dto.agentId),
     tagAssignments: bindAgentTags(tagsApi, dto.agentId),
     phones: bindAgentPhones(phonesApi, dto.agentId),
-    schedule: bindAgentSchedule(scheduleApi, dto.agentId),
+    schedule: bindAgentSchedule(
+      scheduleApi,
+      scheduleExceptionsApi,
+      dto.agentId
+    ),
     versions: bindAgentVersions(versionsApi, dto.agentId),
     blueprints: bindAgentBlueprints(blueprintsApi, dto.agentId),
     async save(patch) {
@@ -917,6 +1020,7 @@ function createAgentsApi(cfg, relatedApis) {
     tagsApi: relatedApis.tagsApi,
     phonesApi: relatedApis.phonesApi,
     scheduleApi: relatedApis.scheduleApi,
+    scheduleExceptionsApi: relatedApis.scheduleExceptionsApi,
     versionsApi: relatedApis.versionsApi,
     blueprintsApi: relatedApis.blueprintsApi,
     reload: async (agentId) => {
@@ -992,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;
@@ -1207,15 +1357,18 @@ function createClient(initialCfg) {
   const tagsApi = createAgentTagsApi(runtimeCfg);
   const phonesApi = createAgentPhonesApi(runtimeCfg);
   const scheduleApi = createAgentScheduleApi(runtimeCfg);
+  const scheduleExceptionsApi = createAgentScheduleExceptionsApi(runtimeCfg);
   const versionsApi = createAgentVersionsApi(runtimeCfg);
   const blueprintsApi = createAgentBlueprintsApi(runtimeCfg);
   const voicesApi = createVoicesApi(runtimeCfg);
   const apiKeysApi = createApiKeysApi(runtimeCfg);
+  const catalogsApi = createCatalogsApi(runtimeCfg);
   const agentsApi = createAgentsApi(runtimeCfg, {
     instructionsApi,
     tagsApi,
     phonesApi,
     scheduleApi,
+    scheduleExceptionsApi,
     versionsApi,
     blueprintsApi
   });
@@ -1231,9 +1384,16 @@ function createClient(initialCfg) {
     (agentId) => bindAgentPhones(phonesApi, agentId),
     phonesApi
   );
+  const scheduleExceptionsNamespace = Object.assign(
+    (agentId) => bindAgentScheduleExceptions(scheduleExceptionsApi, agentId),
+    scheduleExceptionsApi
+  );
   const scheduleNamespace = Object.assign(
-    (agentId) => bindAgentSchedule(scheduleApi, agentId),
-    scheduleApi
+    (agentId) => bindAgentSchedule(scheduleApi, scheduleExceptionsApi, agentId),
+    {
+      ...scheduleApi,
+      exceptions: scheduleExceptionsNamespace
+    }
   );
   const versionsNamespace = Object.assign(
     (agentId) => bindAgentVersions(versionsApi, agentId),
@@ -1255,6 +1415,7 @@ function createClient(initialCfg) {
     },
     workspaces: createWorkspacesApi(runtimeCfg),
     tools: createToolsApi(runtimeCfg),
+    catalogs: catalogsApi,
     voices: voicesApi,
     apiKeys: apiKeysApi
   };
@@ -1322,6 +1483,7 @@ function createClient(initialCfg) {
   bindAgentInstructions,
   bindAgentPhones,
   bindAgentSchedule,
+  bindAgentScheduleExceptions,
   bindAgentTags,
   bindAgentVersions,
   createAgentBlueprintsApi,
@@ -1329,10 +1491,12 @@ function createClient(initialCfg) {
   createAgentInstructionsApi,
   createAgentPhonesApi,
   createAgentScheduleApi,
+  createAgentScheduleExceptionsApi,
   createAgentTagsApi,
   createAgentVersionsApi,
   createAgentsApi,
   createApiKeysApi,
+  createCatalogsApi,
   createClient,
   createHttp,
   createToolsApi,