@amigo-ai/platform-sdk 0.17.3 → 0.21.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.
@@ -239,7 +239,9 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `get`
 - `close`
 - `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,
@@ -1984,10 +1985,47 @@ var ConversationsResource = class extends WorkspaceScopedResource {
         params: {
           path: { workspace_id: this.workspaceId, conversation_id: conversationId }
         },
-        body: request
+        body: request,
+        headers: { Accept: "application/json" }
       })
     );
   }
+  /**
+   * Send a message and receive the agent's response as an SSE stream.
+   *
+   * Returns a `ReadableStream` of SSE bytes. Use `EventSourceParserStream`
+   * (from `eventsource-parser/stream`) to parse into typed `TurnStreamEvent`.
+   *
+   * @example
+   * ```ts
+   * const stream = await client.conversations.createTurnStream(convId, { message: "Hello" });
+   * const events = stream
+   *   .pipeThrough(new TextDecoderStream())
+   *   .pipeThrough(new EventSourceParserStream());
+   * for await (const event of events) {
+   *   const parsed = JSON.parse(event.data) as TurnStreamEvent;
+   *   if (parsed.event === "token") console.log(parsed.text);
+   * }
+   * ```
+   */
+  async createTurnStream(conversationId, request, options) {
+    const result = await this.client.POST(
+      "/v1/{workspace_id}/conversations/{conversation_id}/turns",
+      {
+        params: {
+          path: { workspace_id: this.workspaceId, conversation_id: conversationId }
+        },
+        body: request,
+        headers: { Accept: "text/event-stream" },
+        parseAs: "stream",
+        signal: options?.signal
+      }
+    );
+    if (result.error !== void 0) {
+      throw new Error(`API error: ${JSON.stringify(result.error)}`);
+    }
+    return result.data;
+  }
   /** Build the real-time text WebSocket URL for browser or custom clients. */
   textStreamUrl(params) {
     const url = buildTextStreamUrl({
@@ -1997,6 +2035,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");
@@ -2008,6 +2072,9 @@ function textStreamAuthProtocols(apiKey) {
   }
   return ["auth", token];
 }
+function sessionConnectAuthProtocols(apiKey) {
+  return textStreamAuthProtocols(apiKey);
+}
 function buildTextStreamUrl({
   baseUrl,
   workspaceId: workspaceId2,
@@ -2083,6 +2150,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) {