@amigo-ai/platform-sdk 0.57.0 → 0.58.0

package/README.md

@@ -126,6 +126,56 @@ const client = new AmigoClient({ apiKey: result.accessToken, workspaceId: result
 
 See [`examples/auth/device-code-login.ts`](./examples/auth/device-code-login.ts) for a complete working example.
 
+### Exchange an API key for a JWT
+
+Use `client.tokens.exchangeApiKey()` to swap a long-lived API key for a
+short-lived identity-issued JWT. This is useful when you want to mint a
+narrowly scoped, time-bound token from a privileged server (for example to
+forward to a browser via a BFF proxy, or to call the platform from a runtime
+that can't safely hold the raw API key).
+
+The call posts to `POST /token` on the configured `baseUrl` and is **not**
+workspace-scoped — `workspaceId` is still required on the client because it
+governs every other resource call on the same instance, but `POST /token`
+itself ignores it. The SDK also unconditionally strips the configured
+`Authorization` header for this one request and sends the exchange key only
+as the `api_key` form field, so the configured client key is never sent over
+the wire on the exchange call.
+
+```typescript
+import { AmigoClient } from '@amigo-ai/platform-sdk'
+
+const apiKey = process.env.AMIGO_API_KEY
+const workspaceId = process.env.AMIGO_WORKSPACE_ID
+if (!apiKey || !workspaceId) {
+  throw new Error('AMIGO_API_KEY and AMIGO_WORKSPACE_ID must be set')
+}
+
+const client = new AmigoClient({ apiKey, workspaceId })
+
+const { access_token, expires_in, scope } = await client.tokens.exchangeApiKey({
+  apiKey,
+  // Optional: request a narrower scope on the issued JWT. Enforcement is
+  // server-side — the SDK just forwards the value as a form field.
+  scope: 'entities:read agents:read',
+})
+
+console.log(`Got JWT, expires in ${expires_in}s with scope "${scope}"`)
+
+// Use the JWT in a second client. JWTs are passed as `apiKey` — Bearer auth.
+const scopedClient = new AmigoClient({ apiKey: access_token, workspaceId })
+
+const { items: agents } = await scopedClient.agents.list({ limit: 5 })
+console.log(agents.map((agent) => agent.name))
+```
+
+The response is the standard OAuth-style token payload (`access_token`,
+`token_type`, `expires_in`, `scope`, plus optional `session_id` /
+`refresh_token` when applicable). The `apiKey` you pass to
+`exchangeApiKey()` can be a different key than the one configured on the
+client — the configured key is not used to authenticate the exchange
+request itself.
+
 ## Configuration
 
 | Option        | Type           | Required | Description                                                          |
@@ -280,6 +330,19 @@ const client = new AmigoClient({
 
 ## Resources
 
+### Tokens
+
+Exchange a long-lived API key for a short-lived identity-issued JWT. See
+[Exchange an API key for a JWT](#exchange-an-api-key-for-a-jwt) under
+Authentication for the full walkthrough.
+
+```typescript
+const { access_token, expires_in } = await client.tokens.exchangeApiKey({
+  apiKey: process.env.AMIGO_API_KEY!,
+  scope: 'entities:read agents:read',
+})
+```
+
 ### Agents
 
 ```typescript

package/api.md

@@ -90,6 +90,10 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `revoke`
 - `rotate`
 
+### `tokens`
+
+- `exchangeApiKey`
+
 ### `agents`
 
 - `create`
@@ -270,9 +274,13 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `get`
 - `update`
 - `delete`
+- `listEndpoints`
+- `listEndpointsAutoPaging`
+- `getEndpoint`
+- `createEndpoint`
+- `updateEndpoint`
+- `deleteEndpoint`
 - `testEndpoint`
-- `testConnection`
-- `getHealthCheck`
 
 ### `analytics`
 

package/dist/core/branded-types.js

@@ -9,6 +9,7 @@ export const contextGraphId = (id) => id;
 export const callId = (id) => id;
 export const phoneNumberId = (id) => id;
 export const integrationId = (id) => id;
+export const integrationEndpointId = (id) => id;
 export const entityId = (id) => id;
 export const eventId = (id) => id;
 export const surfaceId = (id) => id;

package/dist/core/branded-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"branded-types.js","sourceRoot":"","sources":["../../src/core/branded-types.ts"],"names":[],"mappings":"AA+BA,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAU,EAAe,EAAE,CAAC,EAAiB,CAAA;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAAU,EAAkB,EAAE,CAAC,EAAoB,CAAA;AAClF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,EAAY,CAAA;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,EAAmB,CAAA;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,EAAmB,CAAA;AAC/E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAc,EAAE,CAAC,EAAgB,CAAA;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAU,EAAmB,EAAE,CAAC,EAAqB,CAAA;AACrF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,EAAU,EAAuB,EAAE,CAAC,EAAyB,CAAA;AACjG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAU,EAAmB,EAAE,CAAC,EAAqB,CAAA;AACrF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAc,EAAE,CAAC,EAAgB,CAAA;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAU,EAAgB,EAAE,CAAC,EAAkB,CAAA"}
+{"version":3,"file":"branded-types.js","sourceRoot":"","sources":["../../src/core/branded-types.ts"],"names":[],"mappings":"AAgCA,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAU,EAAe,EAAE,CAAC,EAAiB,CAAA;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAAU,EAAkB,EAAE,CAAC,EAAoB,CAAA;AAClF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,EAAY,CAAA;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,EAAmB,CAAA;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,EAAmB,CAAA;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,EAAU,EAAyB,EAAE,CACzE,EAA2B,CAAA;AAC7B,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,EAAc,CAAA;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAc,EAAE,CAAC,EAAgB,CAAA;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAU,EAAa,EAAE,CAAC,EAAe,CAAA;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAU,EAAmB,EAAE,CAAC,EAAqB,CAAA;AACrF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,EAAU,EAAuB,EAAE,CAAC,EAAyB,CAAA;AACjG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAU,EAAmB,EAAE,CAAC,EAAqB,CAAA;AACrF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAc,EAAE,CAAC,EAAgB,CAAA;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAU,EAAgB,EAAE,CAAC,EAAkB,CAAA"}

package/dist/index.cjs

@@ -56,6 +56,7 @@ __export(index_exports, {
   ServiceUnavailableError: () => ServiceUnavailableError,
   SesSetupResource: () => SesSetupResource,
   TokenManager: () => TokenManager,
+  TokensResource: () => TokensResource,
   ValidationError: () => ValidationError,
   WebhookVerificationError: () => WebhookVerificationError,
   WorkspaceEventStreamError: () => WorkspaceEventStreamError,
@@ -74,6 +75,7 @@ __export(index_exports, {
   formatDeviceCodeLink: () => formatDeviceCodeLink,
   formatWorkspaceList: () => formatWorkspaceList,
   functionId: () => functionId,
+  integrationEndpointId: () => integrationEndpointId,
   integrationId: () => integrationId,
   isAmigoError: () => isAmigoError,
   isAuthenticationError: () => isAuthenticationError,
@@ -1157,6 +1159,36 @@ var ApiKeysResource = class extends WorkspaceScopedResource {
   }
 };
 
+// src/resources/tokens.ts
+var omitAuthorizationHeader = {
+  onRequest({ request }) {
+    request.headers.delete("Authorization");
+    return request;
+  }
+};
+var TokensResource = class extends WorkspaceScopedResource {
+  /** Exchange an API key for an identity-issued JWT access token. */
+  async exchangeApiKey(request) {
+    const body = {
+      grant_type: "api_key",
+      api_key: request.apiKey
+    };
+    if (request.scope) {
+      body.scope = request.scope;
+    }
+    return extractData(
+      await this.client.POST(
+        "/token",
+        {
+          body,
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          middleware: [omitAuthorizationHeader]
+        }
+      )
+    );
+  }
+};
+
 // src/resources/agents.ts
 var AgentsResource = class extends WorkspaceScopedResource {
   async create(body) {
@@ -2611,7 +2643,8 @@ var ChannelsResource = class extends WorkspaceScopedResource {
 
 // src/resources/integrations.ts
 var IntegrationsResource = class extends WorkspaceScopedResource {
-  /** Create a new integration */
+  // ─── Integrations ─────────────────────────────────────────────────────────
+  /** Create a new REST integration */
   async create(body) {
     return extractData(
       await this.client.POST("/v1/{workspace_id}/integrations", {
@@ -2620,7 +2653,7 @@ var IntegrationsResource = class extends WorkspaceScopedResource {
       })
     );
   }
-  /** List integrations */
+  /** List integrations (REST + desktop) */
   async list(params) {
     return extractData(
       await this.client.GET("/v1/{workspace_id}/integrations", {
@@ -2639,35 +2672,76 @@ var IntegrationsResource = class extends WorkspaceScopedResource {
       })
     );
   }
-  /** Update integration configuration */
+  /** Patch a REST integration. Pass `auth: null` to clear auth. */
   async update(integrationId2, body) {
     return extractData(
-      await this.client.PUT("/v1/{workspace_id}/integrations/{integration_id}", {
+      await this.client.PATCH("/v1/{workspace_id}/integrations/{integration_id}", {
         params: { path: { workspace_id: this.workspaceId, integration_id: integrationId2 } },
         body
       })
     );
   }
-  /** Delete an integration */
+  /** Delete a REST integration */
   async delete(integrationId2) {
     await this.client.DELETE("/v1/{workspace_id}/integrations/{integration_id}", {
       params: { path: { workspace_id: this.workspaceId, integration_id: integrationId2 } }
     });
   }
-  /**
-   * Test a specific endpoint on an integration with given params.
-   * Used in the developer console to validate integration config.
-   */
-  async testEndpoint(integrationId2, endpointName, body) {
+  // ─── Endpoints ────────────────────────────────────────────────────────────
+  /** List endpoints on a REST integration */
+  async listEndpoints(integrationId2, params) {
     return extractData(
-      await this.client.POST(
-        "/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_name}/test",
+      await this.client.GET("/v1/{workspace_id}/integrations/{integration_id}/endpoints", {
+        params: {
+          path: { workspace_id: this.workspaceId, integration_id: integrationId2 },
+          query: params
+        }
+      })
+    );
+  }
+  listEndpointsAutoPaging(integrationId2, params) {
+    return this.iteratePaginatedList(
+      (pageParams) => this.listEndpoints(integrationId2, pageParams),
+      params
+    );
+  }
+  /** Get a single endpoint */
+  async getEndpoint(integrationId2, endpointId) {
+    return extractData(
+      await this.client.GET(
+        "/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}",
+        {
+          params: {
+            path: {
+              workspace_id: this.workspaceId,
+              integration_id: integrationId2,
+              endpoint_id: endpointId
+            }
+          }
+        }
+      )
+    );
+  }
+  /** Add an endpoint to a REST integration */
+  async createEndpoint(integrationId2, body) {
+    return extractData(
+      await this.client.POST("/v1/{workspace_id}/integrations/{integration_id}/endpoints", {
+        params: { path: { workspace_id: this.workspaceId, integration_id: integrationId2 } },
+        body
+      })
+    );
+  }
+  /** Patch an endpoint. The endpoint `name` is immutable. */
+  async updateEndpoint(integrationId2, endpointId, body) {
+    return extractData(
+      await this.client.PATCH(
+        "/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}",
         {
           params: {
             path: {
               workspace_id: this.workspaceId,
               integration_id: integrationId2,
-              endpoint_name: endpointName
+              endpoint_id: endpointId
             }
           },
           body
@@ -2675,44 +2749,42 @@ var IntegrationsResource = class extends WorkspaceScopedResource {
       )
     );
   }
+  /** Delete an endpoint from a REST integration */
+  async deleteEndpoint(integrationId2, endpointId) {
+    await this.client.DELETE(
+      "/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}",
+      {
+        params: {
+          path: {
+            workspace_id: this.workspaceId,
+            integration_id: integrationId2,
+            endpoint_id: endpointId
+          }
+        }
+      }
+    );
+  }
   /**
-   * Probe an integration's connection + auth without invoking any specific
-   * endpoint. Exercises auth resolution end-to-end (SSM lookups, OAuth2 token
-   * mints, JWT signing) and sends a HEAD request to ``base_url`` (REST/FHIR)
-   * or ``mcp_url`` (MCP). Safe on production integrations — HEAD carries no
-   * side effects.
-   *
-   * The most recent probe outcome is persisted on the integration so
-   * subsequent ``get`` / ``list`` responses surface ``last_tested_at`` +
-   * ``last_test_status`` without re-probing.
-   *
-   * @returns ``status`` is one of ``healthy`` / ``auth_failed`` /
-   *   ``unreachable`` / ``timeout`` / ``ssl_error`` / ``misconfigured``,
-   *   each mapping to a distinct, actionable user message.
+   * Execute an endpoint with test parameters and return the full response
+   * pipeline breakdown. Used by the developer console to validate config.
    */
-  async testConnection(integrationId2) {
+  async testEndpoint(integrationId2, endpointId, body) {
     return extractData(
       await this.client.POST(
-        "/v1/{workspace_id}/integrations/{integration_id}/test-connection",
+        "/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test",
         {
           params: {
             path: {
               workspace_id: this.workspaceId,
-              integration_id: integrationId2
+              integration_id: integrationId2,
+              endpoint_id: endpointId
             }
-          }
+          },
+          body
         }
       )
     );
   }
-  /** Check health of all integrations in the workspace */
-  async getHealthCheck() {
-    return extractData(
-      await this.client.GET("/v1/{workspace_id}/integrations/health-check", {
-        params: { path: { workspace_id: this.workspaceId } }
-      })
-    );
-  }
 };
 
 // src/resources/analytics.ts
@@ -5213,6 +5285,7 @@ var contextGraphId = (id) => id;
 var callId = (id) => id;
 var phoneNumberId = (id) => id;
 var integrationId = (id) => id;
+var integrationEndpointId = (id) => id;
 var entityId = (id) => id;
 var eventId = (id) => id;
 var simulationRunId = (id) => id;
@@ -5836,6 +5909,7 @@ var AmigoClient = class _AmigoClient {
   workspaces;
   me;
   apiKeys;
+  tokens;
   agents;
   /** @deprecated Use `actions` instead */
   skills;
@@ -5974,6 +6048,7 @@ var AmigoClient = class _AmigoClient {
     mutable.workspaces = new WorkspacesResource(client, workspaceId2);
     mutable.me = new MeResource(client, "_account");
     mutable.apiKeys = new ApiKeysResource(client, workspaceId2);
+    mutable.tokens = new TokensResource(client, "_identity");
     mutable.agents = new AgentsResource(client, workspaceId2);
     mutable.skills = new SkillsResource(client, workspaceId2);
     mutable.actions = new ActionsResource(client, workspaceId2);