@getsupervisor/agents-studio-sdk 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,3 +1,48 @@
+## v1.8.0
+
+## [1.8.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.7.0...v1.8.0) (2025-10-15)
+
+### Features
+
+* add complete CRUD example for agents in the SDK ([4e07584](https://github.com/julio-supervisor/agents-studio-be/commit/4e07584aac8537c5050cdaac20722c5d23d4e841))
+* agent module ([6ba4512](https://github.com/julio-supervisor/agents-studio-be/commit/6ba4512a07d2deda71d24a448bef5523e8e06542))
+* agregar argumento de construcción NODE_AUTH_TOKEN en el flujo de trabajo de despliegue ([f2d4923](https://github.com/julio-supervisor/agents-studio-be/commit/f2d4923a3e332fc3c660033f63d24bd0907beb85))
+* agregar configuración de Node.js en flujos de trabajo de despliegue ([dd7a194](https://github.com/julio-supervisor/agents-studio-be/commit/dd7a194d168a1ceb71731cf572f069eb838d1ae1))
+* agregar depuración de autenticación npm y visibilidad de paquetes en los flujos de trabajo de despliegue ([9e25cd9](https://github.com/julio-supervisor/agents-studio-be/commit/9e25cd989123f8b9640a8e51973f9ee6a8abd5df))
+* agregar guía de despliegue con GitHub Actions para el backend de Agents Studio ([0196448](https://github.com/julio-supervisor/agents-studio-be/commit/01964486b7c038ee46bd014379842d8e5c28c754))
+* agregar soporte para NODE_AUTH_TOKEN en el Dockerfile para la instalación de dependencias ([d47a299](https://github.com/julio-supervisor/agents-studio-be/commit/d47a2996d9f89d3860cc7d7c54f61fe71a0e6e9d))
+* **ci:** agregar pasos de depuración para la autenticación de npm y visibilidad de paquetes ([17c8aed](https://github.com/julio-supervisor/agents-studio-be/commit/17c8aed6d071a6b0c034bd88588b930fdd26ab05))
+
+### Bug Fixes
+
+* **tsconfig:** corregir la ruta del dominio de agentes en la configuración de TypeScript ([d3480c8](https://github.com/julio-supervisor/agents-studio-be/commit/d3480c815c220491061d8e44debcab4ffdd40f96))
+
+
+## v1.7.0
+
+## [1.7.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.6.0...v1.7.0) (2025-10-13)
+
+### Features
+
+* **migrations:** agregar migraciones para renombrar tablas y actualizar esquemas de agentes ([04353a2](https://github.com/julio-supervisor/agents-studio-be/commit/04353a27ec0a8f3a14ebf1c86a80dc37e2b6ad81))
+
+## v1.6.0
+
+## [1.6.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.5.0...v1.6.0) (2025-10-13)
+
+### Features
+
+* **api:** add endpoints for managing agents, agent versions, instructions, and tools ([60a5b8f](https://github.com/julio-supervisor/agents-studio-be/commit/60a5b8f18bbd315b5caeb2191240c28a1540bb62))
+
+## v1.5.0
+
+## [1.5.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.4.0...v1.5.0) (2025-10-13)
+
+### Features
+
+* add agent tags management API for associating and removing tags from agents ([88e5b87](https://github.com/julio-supervisor/agents-studio-be/commit/88e5b87c256d3671ad27d503c954bc41c6175811))
+
+
 ## v1.4.0
 
 ## [1.4.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.3.0...v1.4.0) (2025-10-12)

package/README.md

@@ -22,6 +22,10 @@ const client = createClient({
 const { data: agents } = await client.agents.list({ limit: 10 });
 const agent = await client.agents.get('agent-123');
 
+// helpers de agente sin repetir IDs
+const instructions = client.agents.instructions(agent.agentId);
+await instructions.create({ order: 1, content: 'Responde en español neutro' });
+
 // administrar versiones e instrucciones
 await client.agents
   .versions(agent.agentId)
@@ -36,12 +40,32 @@ await client.tools.uploadResource(tools.data[0].identifier, formData);
 await client.agents.delete(agent.agentId);
 ```
 
+### Ejemplo de CRUD completo
+
+Consulta el archivo `examples/agents-crud.ts` para ver un flujo end-to-end que:
+
+- crea un agente temporal,
+- lista agentes con paginación,
+- actualiza los campos con `save` y `update`, y
+- elimina el recurso al finalizar.
+
+Ejecuta el ejemplo definiendo `API_BASE_URL`, `WORKSPACE_ID` y `API_TOKEN`:
+
+```bash
+API_BASE_URL=https://public-api.getsupervisor.ai \
+WORKSPACE_ID=ws-123 \
+API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
+npx tsx examples/agents-crud.ts
+```
+
 ## Configuración
 
 ```ts
 createClient({
   baseUrl: '...',
   headers: { Authorization: 'Bearer ...' },
+  // opcional: usa API Keys en lugar de Bearer
+  // apiKey: 'sk_live_...',
   timeoutMs: 35000,
   retry: { maxRetries: 2, baseDelayMs: 300 },
   workspaceId: 'ws-123',
@@ -74,13 +98,86 @@ const scoped = client.workspace.scoped('ws-789');
 await scoped.agents.get('agentId');
 ```
 
-## Novedades (septiembre 2024)
+## Gestión de API Keys
+
+Los endpoints `/v1/api-keys` permiten listar, crear y revocar credenciales por workspace. Mientras publicamos helpers específicos en el cliente, puedes usar la utilidad `createHttp` para firmar peticiones con el mismo manejo de cabeceras, timeouts y reintentos del SDK.
+
+> También puedes consumir el CRUD de agentes con API Keys pasando `apiKey` a `createClient` o usando `client.auth.setApiKey('sk_...')`. El SDK enviará el header `X-API-Key` automáticamente en cada llamada.
+
+```ts
+import { createHttp } from '@getsupervisor/agents-studio-sdk';
+
+const http = createHttp({
+  baseUrl: 'https://public-api.getsupervisor.ai',
+  headers: { Authorization: `Bearer ${token}` },
+  workspaceId: 'ws-123',
+});
+```
+
+### Listar API Keys activas
+
+```ts
+const res = await http.doFetch(`${http.base}/v1/api-keys`, { method: 'GET' });
+const apiKeys = await res.json();
+
+// apiKeys: ApiKeySummary[]
+```
+
+Cada entrada incluye `id`, `name`, `environment`, `scopes`, fechas de auditoría y un `keyPreview` para validar qué credencial usas en producción o sandbox.
+
+### Crear una API Key con scopes personalizados
+
+```ts
+const res = await http.doFetch(`${http.base}/v1/api-keys`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    name: 'Backend Integration',
+    description: 'Sincronización nocturna de métricas',
+    environment: 'production',
+    scopes: ['agents:read', 'api-keys:read'],
+  }),
+});
+
+const { key, ...metadata } = await res.json();
+// Guarda "key" inmediatamente; no vuelve a enviarse en respuestas posteriores.
+```
+
+- Si omites `environment`, se usa la configuración por defecto (`production` salvo que sobrescribas `API_KEYS_ENVIRONMENT`).
+- Si omites `scopes`, el servicio aplica los scopes configurados como `API_KEYS_DEFAULT_SCOPES` (p. ej. `api-keys:read`).
+- Combina scopes mínimos necesarios para limitar el alcance siguiendo el principio de menor privilegio.
+
+### Revocar una API Key
+
+```ts
+await http.doFetch(`${http.base}/v1/api-keys/${apiKeyId}`, { method: 'DELETE' });
+```
+
+La revocación invalida la credencial de forma inmediata. Cualquier uso posterior regresará `401 Unauthorized`.
+
+### Buenas prácticas
+
+- Segmenta las API Keys por entorno (`production`, `sandbox`, `staging`, `development`) y flujo de negocio.
+- Registra un owner o nota descriptiva en `name` para acelerar auditorías.
+- Almacena el valor completo (`key`) en un gestor de secretos y evita incluirlo en logs o repositorios.
+- Programa rotaciones periódicas y revoca claves cuando detectes inactividad o incidentes.
+
+### Scopes disponibles (octubre 2025)
+
+| Scope | Permiso |
+|-------|---------|
+| `agents:read` | Lectura de catálogos de agentes, versiones e instrucciones. |
+| `workspaces:read` | Lectura de metadatos y recursos de workspace. |
+| `api-keys:read` | Listar y consultar API Keys activas. |
+| `api-keys:write` | Crear o revocar API Keys. |
+
+Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para revisar nuevos scopes conforme se publiquen más operaciones protegidas.
+
+## Novedades (octubre 2025)
 
-- **Sincronización completa con el OpenAPI más reciente**: se regeneraron los tipos `openapi-types.ts` y se actualizó la superficie pública para reflejar nuevos contratos.
-- **Instrucciones por versión**: ahora puedes gestionar instrucciones directamente sobre versiones (`client.agents.versions(...).instructions(...)`) incluyendo operaciones de listar, crear, actualizar y eliminar.
-- **Catálogo y recursos de tools**: soporte para listar tools filtrando por `agentType`, subir/eliminar/recargar recursos y establecer conexiones (`connect`) de manera tipada.
-- **Deprecación de knowledge en agentes**: las rutas de knowledge fueron removidas del API. El helper anterior arroja un error explícito y los tipos asociados ya no se exportan.
-- **Pruebas actualizadas**: la suite de Vitest se ajustó para cubrir helpers de versiones e instrucciones; `npm test` reporta 11 pruebas exitosas.
+- **Gestión de API Keys desde el SDK**: ejemplos oficiales para listar, emitir y revocar claves con `createHttp`, alineados con los endpoints `/v1/api-keys`.
+- **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.
 
 ## Errores tipados y reintentos
 

package/dist/index.cjs

@@ -236,7 +236,9 @@ function createHttp(cfg) {
   const log = cfg.logger ?? {};
   const retry = cfg.retry;
   const WORKSPACE_HEADER = "x-workspace-id";
+  const API_KEY_HEADER = "x-api-key";
   const resolveWorkspaceId = () => cfg.getWorkspaceId?.() ?? cfg.workspaceId ?? void 0;
+  const resolveApiKey = () => cfg.getApiKey?.() ?? cfg.apiKey ?? void 0;
   const normalizeHeaders = (headers) => {
     if (!headers) {
       return {};
@@ -260,9 +262,12 @@ function createHttp(cfg) {
     const workspaceId = resolveWorkspaceId();
     const normalizedExtra = normalizeHeaders(extra);
     const headersWithWorkspace = workspaceId ? { [WORKSPACE_HEADER]: workspaceId } : {};
+    const apiKey = resolveApiKey();
+    const headersWithApiKey = apiKey ? { [API_KEY_HEADER]: apiKey } : {};
     return {
       ...baseHeaders,
       ...headersWithWorkspace,
+      ...headersWithApiKey,
       ...normalizedExtra
     };
   };
@@ -303,7 +308,8 @@ function createHttp(cfg) {
     retry,
     doFetch,
     buildHeaders,
-    resolveWorkspaceId
+    resolveWorkspaceId,
+    resolveApiKey
   };
 }
 
@@ -744,7 +750,12 @@ function createAgentsApi(cfg, relatedApis) {
   const { base, doFetch } = createHttp(cfg);
   const jsonHeaders = { "content-type": "application/json" };
   const fetchAgentsPage = async (options = {}) => {
-    const query = serializeListOptions(options);
+    const sanitizedOptions = {
+      page: options.page,
+      limit: options.limit,
+      filter: options.filter
+    };
+    const query = serializeListOptions(sanitizedOptions);
     const res = await doFetch(`${base}/v1/agents`, {
       method: "GET",
       query
@@ -1036,12 +1047,19 @@ function createClient(initialCfg) {
     ...initialCfg
   };
   const resolveWorkspaceId = () => runtimeCfg.workspaceId ?? runtimeCfg.getWorkspaceId?.();
+  const resolveApiKey = () => runtimeCfg.apiKey ?? runtimeCfg.getApiKey?.();
   const setWorkspaceId = (workspaceId) => {
     runtimeCfg.workspaceId = workspaceId;
   };
   const setWorkspaceGetter = (getter) => {
     runtimeCfg.getWorkspaceId = getter;
   };
+  const setApiKey = (apiKey) => {
+    runtimeCfg.apiKey = apiKey;
+  };
+  const setApiKeyGetter = (getter) => {
+    runtimeCfg.getApiKey = getter;
+  };
   const instructionsApi = createAgentInstructionsApi(runtimeCfg);
   const tagsApi = createAgentTagsApi(runtimeCfg);
   const phonesApi = createAgentPhonesApi(runtimeCfg);
@@ -1055,14 +1073,34 @@ function createClient(initialCfg) {
     scheduleApi,
     versionsApi
   });
+  const instructionsNamespace = Object.assign(
+    (agentId) => bindAgentInstructions(instructionsApi, agentId),
+    instructionsApi
+  );
+  const tagsNamespace = Object.assign(
+    (agentId) => bindAgentTags(tagsApi, agentId),
+    tagsApi
+  );
+  const phonesNamespace = Object.assign(
+    (agentId) => bindAgentPhones(phonesApi, agentId),
+    phonesApi
+  );
+  const scheduleNamespace = Object.assign(
+    (agentId) => bindAgentSchedule(scheduleApi, agentId),
+    scheduleApi
+  );
+  const versionsNamespace = Object.assign(
+    (agentId) => bindAgentVersions(versionsApi, agentId),
+    versionsApi
+  );
   const apis = {
     agents: {
       ...agentsApi,
-      instructions: instructionsApi,
-      tags: tagsApi,
-      phones: phonesApi,
-      schedule: scheduleApi,
-      versions: versionsApi
+      instructions: instructionsNamespace,
+      tags: tagsNamespace,
+      phones: phonesNamespace,
+      schedule: scheduleNamespace,
+      versions: versionsNamespace
     },
     workspaces: createWorkspacesApi(runtimeCfg),
     tools: createToolsApi(runtimeCfg),
@@ -1070,6 +1108,20 @@ function createClient(initialCfg) {
   };
   return {
     ...apis,
+    auth: {
+      getApiKey: resolveApiKey,
+      setApiKey(key) {
+        setApiKeyGetter(void 0);
+        setApiKey(key);
+      },
+      useApiKey(getter) {
+        setApiKeyGetter(getter);
+      },
+      clearApiKey() {
+        setApiKeyGetter(void 0);
+        setApiKey(void 0);
+      }
+    },
     workspace: {
       get: resolveWorkspaceId,
       set(id) {
@@ -1087,7 +1139,9 @@ function createClient(initialCfg) {
         return createClient({
           ...initialCfg,
           workspaceId: id,
-          getWorkspaceId: void 0
+          getWorkspaceId: void 0,
+          apiKey: runtimeCfg.apiKey,
+          getApiKey: runtimeCfg.getApiKey
         });
       }
     }