@getsupervisor/agents-studio-sdk 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## v1.12.0
+
+## [1.12.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.11.0...v1.12.0) (2025-10-20)
+
+### Features
+
+* **api-keys:** implement API key management endpoints and client integration ([1eceb00](https://github.com/julio-supervisor/agents-studio-be/commit/1eceb002c296ba017a71516f4710d28bbee6a235))
+* **ci:** add pull request permissions for CI jobs ([1adef4a](https://github.com/julio-supervisor/agents-studio-be/commit/1adef4af2e459b2cd44f156ac6771a7e18d45b68))
+* **ci:** update coverage badge generation to create a pull request ([967d1a0](https://github.com/julio-supervisor/agents-studio-be/commit/967d1a0f8c207db2929f36e686bb2ab327b413f5))
+* **ci:** update coverage badge PR creation to include branch and base parameters ([769c696](https://github.com/julio-supervisor/agents-studio-be/commit/769c696c438d5945043bf9bcd6d001c10285e3b3))
+* expose api key reveal flow ([612cf69](https://github.com/julio-supervisor/agents-studio-be/commit/612cf695ff9cad480cafc27daf831095290eccfa))
+
+### Bug Fixes
+
+* **ci:** agregar badges a la lista de rutas ignoradas en eventos de push y pull_request ([4928c13](https://github.com/julio-supervisor/agents-studio-be/commit/4928c1324e26d0e0db7ba62784b3df159ca48488))
+* **ci:** agregar rutas ignoradas para badges en eventos de push ([f99328a](https://github.com/julio-supervisor/agents-studio-be/commit/f99328ae76e953d1254f068dd4675f2843ac1587))
+* **ci:** change contents permission from write to read for unit tests ([2cb24e0](https://github.com/julio-supervisor/agents-studio-be/commit/2cb24e0b33fd6e62d02a8f642669255e94b6b3bd))
+* **ci:** update permissions for unit tests to include write access for contents, issues, and id-token ([a5078db](https://github.com/julio-supervisor/agents-studio-be/commit/a5078dbbe52b1f6406848f30bd470231c22ce2c9))
+
+
+## v1.11.0
+
+## [1.11.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.10.0...v1.11.0) (2025-10-19)
+
+### Features
+
+* **agent-blueprints:** add module implementation and tests ([d631ce5](https://github.com/julio-supervisor/agents-studio-be/commit/d631ce59cf439306020d7e06fe561a808d1f2753))
+* **blueprints:** implement agent blueprints API and integrate with client ([d166104](https://github.com/julio-supervisor/agents-studio-be/commit/d166104f04951d434f5cf89d068babff76ceb42d))
+
+
 ## v1.10.0
 
 ## [1.10.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.9.0...v1.10.0) (2025-10-17)

package/README.md

@@ -123,60 +123,77 @@ await scoped.agents.get('agentId');
 
 ## 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.
+Los endpoints `/v1/api-keys` permiten listar, crear y revocar credenciales por workspace. Desde la versión 1.10 el SDK expone un namespace dedicado para gestionar el ciclo de vida completo de las claves sin escribir boilerplate adicional.
 
 > 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.
 
+### Cliente dedicado: `client.apiKeys`
+
 ```ts
-import { createHttp } from '@getsupervisor/agents-studio-sdk';
+import { createClient } from '@getsupervisor/agents-studio-sdk';
 
-const http = createHttp({
+const client = createClient({
   baseUrl: 'https://public-api.getsupervisor.ai',
   headers: { Authorization: `Bearer ${token}` },
   workspaceId: 'ws-123',
 });
-```
 
-### Listar API Keys activas
+// 1. Listar credenciales activas
+const keys = await client.apiKeys.list();
 
-```ts
-const res = await http.doFetch(`${http.base}/v1/api-keys`, { method: 'GET' });
-const apiKeys = await res.json();
+// 2. Emitir una nueva credencial (recuerda guardar el valor completo)
+const created = await client.apiKeys.create({
+  name: 'Backend Integration',
+  environment: 'production',
+  scopes: ['agents:read', 'api-keys:read'],
+});
+console.log(created.key); // sólo se entrega una vez
+
+// 3. Revelar el valor completo cuando necesites consultarlo de nuevo
+const revealed = await client.apiKeys.show(created.id);
+console.log(revealed.key); // también incluye metadatos actualizados
 
-// apiKeys: ApiKeySummary[]
+// 4. Revocar cuando deje de ser necesaria
+await client.apiKeys.revoke(created.id);
 ```
 
-Cada entrada incluye `id`, `name`, `environment`, `scopes`, fechas de auditoría y un `keyPreview` para validar qué credencial usas en producción o sandbox.
+Cada entrada (`ApiKeySummary`) incluye `id`, `name`, `environment`, `scopes`, fechas de auditoría y un `keyPreview` para identificar la credencial sin exponerla por completo.
 
-### Crear una API Key con scopes personalizados
+### Usar API Keys dinámicas
+
+Puedes rotar claves en caliente con los helpers de autenticación:
 
 ```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'],
-  }),
-});
+client.auth.setApiKey('sk_prod_live');
 
-const { key, ...metadata } = await res.json();
-// Guarda "key" inmediatamente; no vuelve a enviarse en respuestas posteriores.
+client.auth.useApiKey(() => readSecretFromVault());
+
+client.auth.clearApiKey();
 ```
 
-- 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.
+El SDK enviará siempre el header `X-API-Key`; si lo borras, retomará la autenticación configurada en `headers`.
+
+### Alternativa low-level con `createHttp`
 
-### Revocar una API Key
+Si necesitas controlar manualmente las peticiones (por ejemplo, en un entorno con fetch custom), puedes reutilizar la misma librería interna:
 
 ```ts
-await http.doFetch(`${http.base}/v1/api-keys/${apiKeyId}`, { method: 'DELETE' });
-```
+import { createHttp } from '@getsupervisor/agents-studio-sdk';
 
-La revocación invalida la credencial de forma inmediata. Cualquier uso posterior regresará `401 Unauthorized`.
+const http = createHttp({
+  baseUrl: 'https://public-api.getsupervisor.ai',
+  headers: { Authorization: `Bearer ${token}` },
+  workspaceId: 'ws-123',
+});
+
+const { key, ...metadata } = await http
+  .doFetch(`${http.base}/v1/api-keys`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'Automation', scopes: ['agents:read'] }),
+  })
+  .then((res) => res.json());
+```
 
 ### Buenas prácticas
 
@@ -198,7 +215,7 @@ Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para revisar nuevos scopes co
 
 ## Novedades (octubre 2025)
 
-- **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`.
+- **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.
 

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   createAgentTagsApi: () => createAgentTagsApi,
   createAgentVersionsApi: () => createAgentVersionsApi,
   createAgentsApi: () => createAgentsApi,
+  createApiKeysApi: () => createApiKeysApi,
   createClient: () => createClient,
   createHttp: () => createHttp,
   createToolsApi: () => createToolsApi,
@@ -147,8 +148,10 @@ function createHttp(cfg) {
   const retry = cfg.retry;
   const WORKSPACE_HEADER = "x-workspace-id";
   const API_KEY_HEADER = "x-api-key";
+  const AUTHORIZATION_HEADER = "authorization";
   const resolveWorkspaceId = () => cfg.getWorkspaceId?.() ?? cfg.workspaceId ?? void 0;
   const resolveApiKey = () => cfg.getApiKey?.() ?? cfg.apiKey ?? void 0;
+  const resolveAccessToken = () => cfg.getAccessToken?.() ?? cfg.accessToken ?? void 0;
   const normalizeHeaders = (headers) => {
     if (!headers) {
       return {};
@@ -174,10 +177,15 @@ function createHttp(cfg) {
     const headersWithWorkspace = workspaceId ? { [WORKSPACE_HEADER]: workspaceId } : {};
     const apiKey = resolveApiKey();
     const headersWithApiKey = apiKey ? { [API_KEY_HEADER]: apiKey } : {};
+    const accessToken = resolveAccessToken();
+    const headersWithAuthorization = accessToken ? {
+      [AUTHORIZATION_HEADER]: accessToken.startsWith("Bearer ") ? accessToken : `Bearer ${accessToken}`
+    } : {};
     return {
       ...baseHeaders,
       ...headersWithWorkspace,
       ...headersWithApiKey,
+      ...headersWithAuthorization,
       ...normalizedExtra
     };
   };
@@ -219,7 +227,8 @@ function createHttp(cfg) {
     doFetch,
     buildHeaders,
     resolveWorkspaceId,
-    resolveApiKey
+    resolveApiKey,
+    resolveAccessToken
   };
 }
 
@@ -930,6 +939,37 @@ function createAgentsApi(cfg, relatedApis) {
   };
 }
 
+// src/api/api-keys.ts
+function createApiKeysApi(cfg) {
+  const { base, doFetch } = createHttp(cfg);
+  const jsonHeaders = { "content-type": "application/json" };
+  return {
+    async list() {
+      const res = await doFetch(`${base}/v1/api-keys`, { method: "GET" });
+      return res.json();
+    },
+    async create(payload) {
+      const res = await doFetch(`${base}/v1/api-keys`, {
+        method: "POST",
+        headers: jsonHeaders,
+        body: JSON.stringify(payload)
+      });
+      return res.json();
+    },
+    async revoke(apiKeyId) {
+      await doFetch(`${base}/v1/api-keys/${apiKeyId}`, {
+        method: "DELETE"
+      });
+    },
+    async show(apiKeyId) {
+      const res = await doFetch(`${base}/v1/api-keys/${apiKeyId}/show`, {
+        method: "GET"
+      });
+      return res.json();
+    }
+  };
+}
+
 // src/api/tools.ts
 var isFormData = (value) => {
   return typeof FormData !== "undefined" && value instanceof FormData;
@@ -1122,6 +1162,7 @@ function createClient(initialCfg) {
   };
   const resolveWorkspaceId = () => runtimeCfg.workspaceId ?? runtimeCfg.getWorkspaceId?.();
   const resolveApiKey = () => runtimeCfg.apiKey ?? runtimeCfg.getApiKey?.();
+  const resolveAccessToken = () => runtimeCfg.accessToken ?? runtimeCfg.getAccessToken?.();
   const setWorkspaceId = (workspaceId) => {
     runtimeCfg.workspaceId = workspaceId;
   };
@@ -1134,6 +1175,12 @@ function createClient(initialCfg) {
   const setApiKeyGetter = (getter) => {
     runtimeCfg.getApiKey = getter;
   };
+  const setAccessToken = (token) => {
+    runtimeCfg.accessToken = token;
+  };
+  const setAccessTokenGetter = (getter) => {
+    runtimeCfg.getAccessToken = getter;
+  };
   const instructionsApi = createAgentInstructionsApi(runtimeCfg);
   const tagsApi = createAgentTagsApi(runtimeCfg);
   const phonesApi = createAgentPhonesApi(runtimeCfg);
@@ -1141,6 +1188,7 @@ function createClient(initialCfg) {
   const versionsApi = createAgentVersionsApi(runtimeCfg);
   const blueprintsApi = createAgentBlueprintsApi(runtimeCfg);
   const voicesApi = createVoicesApi(runtimeCfg);
+  const apiKeysApi = createApiKeysApi(runtimeCfg);
   const agentsApi = createAgentsApi(runtimeCfg, {
     instructionsApi,
     tagsApi,
@@ -1185,7 +1233,8 @@ function createClient(initialCfg) {
     },
     workspaces: createWorkspacesApi(runtimeCfg),
     tools: createToolsApi(runtimeCfg),
-    voices: voicesApi
+    voices: voicesApi,
+    apiKeys: apiKeysApi
   };
   return {
     ...apis,
@@ -1201,6 +1250,18 @@ function createClient(initialCfg) {
       clearApiKey() {
         setApiKeyGetter(void 0);
         setApiKey(void 0);
+      },
+      getAccessToken: resolveAccessToken,
+      setAccessToken(token) {
+        setAccessTokenGetter(void 0);
+        setAccessToken(token);
+      },
+      useAccessToken(getter) {
+        setAccessTokenGetter(getter);
+      },
+      clearAccessToken() {
+        setAccessTokenGetter(void 0);
+        setAccessToken(void 0);
       }
     },
     workspace: {
@@ -1222,7 +1283,9 @@ function createClient(initialCfg) {
           workspaceId: id,
           getWorkspaceId: void 0,
           apiKey: runtimeCfg.apiKey,
-          getApiKey: runtimeCfg.getApiKey
+          getApiKey: runtimeCfg.getApiKey,
+          accessToken: runtimeCfg.accessToken,
+          getAccessToken: runtimeCfg.getAccessToken
         });
       }
     }
@@ -1247,6 +1310,7 @@ function createClient(initialCfg) {
   createAgentTagsApi,
   createAgentVersionsApi,
   createAgentsApi,
+  createApiKeysApi,
   createClient,
   createHttp,
   createToolsApi,