@amigo-ai/platform-sdk 0.19.0 → 0.22.0

package/api.md

@@ -51,8 +51,8 @@ Notes:
 - Request option types: `AmigoRequestOptions`, `ScopedRequestOptions`
 - Webhooks: `verifyWebhookSignature`, `parseWebhookEvent`, `WebhookVerificationError`
 - Pagination and response helpers: `paginate`, `buildLastResponse`, `extractRequestId`
-- Conversation helpers: `textStreamAuthProtocols`
-- Conversation types: `ConversationDetail`, `ConversationListResponse`, `ConversationSummary`, `ConversationTurn`, `CreateConversationRequest`, `ListConversationsParams`, `TextStreamAuthProtocols` (WebSocket constructor subprotocol tuple), `TextStreamUrlParams`, `TurnRequest`, `TurnResponse`
+- Conversation helpers: `sessionConnectAuthProtocols`, `textStreamAuthProtocols`
+- Conversation types: `ConversationDetail`, `ConversationListResponse`, `ConversationSummary`, `ConversationTurn`, `CreateConversationRequest`, `ListConversationsParams`, `SessionConnectUrlParams`, `TextStreamAuthProtocols` (WebSocket constructor subprotocol tuple), `TextStreamUrlParams`, `TurnDoneEvent`, `TurnErrorEvent`, `TurnMessageEvent`, `TurnRequest`, `TurnResponse`, `TurnStreamEvent`, `TurnThinkingEvent`, `TurnTokenEvent`, `TurnToolCallCompletedEvent`, `TurnToolCallStartedEvent`
 - Response and hook types: `PaginatedList`, `ListParams`, `LastResponseInfo`, `ResponseMetadata`, `WithResponseMetadata`, `AmigoResponse`, `RetryOptions`, `RateLimitInfo`, `ClientHooks`, `RequestHookContext`, `ResponseHookContext`, `ErrorHookContext`
 - Generated OpenAPI types: `paths`, `components`, `operations`
 - Generated API types are produced with `npm run gen-types` from the committed `openapi.json` snapshot.
@@ -241,6 +241,7 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `createTurn`
 - `createTurnStream`
 - `textStreamUrl`
+- `sessionConnectUrl`
 
 ### `phoneNumbers`
 

package/dist/index.cjs

@@ -82,6 +82,7 @@ __export(index_exports, {
   personaId: () => personaId,
   phoneNumberId: () => phoneNumberId,
   serviceId: () => serviceId,
+  sessionConnectAuthProtocols: () => sessionConnectAuthProtocols,
   simulationRunId: () => simulationRunId,
   simulationSessionId: () => simulationSessionId,
   skillId: () => skillId,
@@ -1978,11 +1979,22 @@ var ConversationsResource = class extends WorkspaceScopedResource {
       }
     });
   }
-  async createTurn(conversationId, request) {
+  /**
+   * Send a user message and receive the agent's synchronous JSON response.
+   *
+   * Pass `options.includeToolCalls: true` to request tool-call metadata
+   * alongside the response turns. Server-side default is `false` — without
+   * this opt-in the `tool_calls` array on the `TurnResponse` will be empty
+   * even when the agent invoked tools during the turn.
+   */
+  async createTurn(conversationId, request, options) {
     return extractData(
       await this.client.POST("/v1/{workspace_id}/conversations/{conversation_id}/turns", {
         params: {
-          path: { workspace_id: this.workspaceId, conversation_id: conversationId }
+          path: { workspace_id: this.workspaceId, conversation_id: conversationId },
+          ...options?.includeToolCalls !== void 0 && {
+            query: { include_tool_calls: options.includeToolCalls }
+          }
         },
         body: request,
         headers: { Accept: "application/json" }
@@ -2034,6 +2046,32 @@ var ConversationsResource = class extends WorkspaceScopedResource {
     });
     return url.toString();
   }
+  /**
+   * Build the URL for the workspace-scoped session-connect WebSocket
+   * (``WS /v1/{workspace_id}/sessions/connect``).
+   *
+   * Pair the returned URL with {@link sessionConnectAuthProtocols} so the
+   * bearer token is delivered via the ``Sec-WebSocket-Protocol`` header — the
+   * endpoint rejects query-param tokens to keep credentials out of URLs.
+   *
+   * @example
+   * ```ts
+   * const url = client.conversations.sessionConnectUrl({
+   *   serviceId: SERVICE_ID,
+   *   entityId: ENTITY_ID,
+   *   conversationId: existingConversationId, // optional resume
+   * });
+   * const ws = new WebSocket(url, sessionConnectAuthProtocols(apiKey));
+   * ```
+   */
+  sessionConnectUrl(params) {
+    const url = buildSessionConnectUrl({
+      baseUrl: this.platformBaseUrl,
+      workspaceId: this.workspaceId,
+      ...params
+    });
+    return url.toString();
+  }
 };
 function textStreamAuthProtocols(apiKey) {
   const token = validateTextStreamAuthToken(apiKey, "apiKey");
@@ -2045,6 +2083,9 @@ function textStreamAuthProtocols(apiKey) {
   }
   return ["auth", token];
 }
+function sessionConnectAuthProtocols(apiKey) {
+  return textStreamAuthProtocols(apiKey);
+}
 function buildTextStreamUrl({
   baseUrl,
   workspaceId: workspaceId2,
@@ -2120,6 +2161,66 @@ function deriveTextStreamUrl(baseUrl) {
   url.hash = "";
   return url;
 }
+function buildSessionConnectUrl({
+  baseUrl,
+  workspaceId: workspaceId2,
+  serviceId: serviceId2,
+  entityId: entityId2,
+  conversationId,
+  toolEvents,
+  sessionConnectUrl: sessionConnectUrlOverride
+}) {
+  const url = sessionConnectUrlOverride ? parseSessionConnectUrlOverride(sessionConnectUrlOverride) : deriveSessionConnectUrl(baseUrl, workspaceId2);
+  url.searchParams.set("service_id", serviceId2);
+  url.searchParams.set("entity_id", entityId2);
+  if (conversationId) url.searchParams.set("conversation_id", conversationId);
+  if (toolEvents === false) url.searchParams.set("tool_events", "false");
+  return url;
+}
+function parseSessionConnectUrlOverride(sessionConnectUrl) {
+  try {
+    const url = new URL(sessionConnectUrl);
+    if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+      throw new ConfigurationError("sessionConnectUrl overrides must use ws: or wss: URLs");
+    }
+    if (url.search || url.hash) {
+      throw new ConfigurationError(
+        "sessionConnectUrl overrides must not include query parameters or fragments; pass SDK-managed fields through sessionConnectUrl() options"
+      );
+    }
+    return url;
+  } catch (cause) {
+    if (cause instanceof ConfigurationError) throw cause;
+    throw new ConfigurationError(
+      `sessionConnectUrl must be an absolute URL for session-connect overrides: ${String(cause)}`
+    );
+  }
+}
+function deriveSessionConnectUrl(baseUrl, workspaceId2) {
+  if (!/^[a-z][a-z\d+.-]*:\/\//i.test(baseUrl)) {
+    throw new ConfigurationError(
+      "sessionConnectUrl cannot be derived from a relative baseUrl; pass sessionConnectUrl explicitly"
+    );
+  }
+  const url = new URL(baseUrl);
+  if (url.protocol === "ws:" || url.protocol === "wss:") {
+  } else if (url.protocol === "http:" || url.protocol === "https:") {
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  } else {
+    throw new ConfigurationError(
+      "sessionConnectUrl can only be derived from an http, https, ws, or wss baseUrl; pass sessionConnectUrl explicitly"
+    );
+  }
+  if (url.pathname !== "/" && url.pathname !== "") {
+    throw new ConfigurationError(
+      "sessionConnectUrl can only be derived from an origin-only baseUrl; pass sessionConnectUrl explicitly when using path-prefixed gateways"
+    );
+  }
+  url.pathname = `/v1/${workspaceId2}/sessions/connect`;
+  url.search = "";
+  url.hash = "";
+  return url;
+}
 function describeInvalidSubprotocolChars(token) {
   const chars = /* @__PURE__ */ new Set();
   for (const char of token) {