@introspection-sdk/introspection-browser 0.5.1 → 0.5.3

package/src/api/client.ts

@@ -0,0 +1,106 @@
+/**
+ * Browser-side Introspection API client.
+ *
+ * Lets a single-page app create and stream Introspection tasks directly
+ * from the browser, with no API key in JavaScript. The auth boundary:
+ *
+ *   1. The SPA's own backend ("broker") mints an Introspection access
+ *      token — via RFC 8693 token-exchange of the partner IdP token, a
+ *      PKCE `authorization_code`, or `client_credentials`. The IdP
+ *      secret never leaves the backend. The SPA fetches that token
+ *      through the `getToken` callback.
+ *   2. `connect()` redeems the token at the DP `POST /v1/oauth/exchange`
+ *      for the HttpOnly `intro_dp_session` cookie.
+ *   3. Every subsequent call rides that cookie (`credentials: "include"`)
+ *      — `client.tasks.start(...)`, `.get(...)`, run streaming, etc.
+ *
+ * When the session cookie expires, an in-flight request gets a 401, and
+ * the client transparently re-runs `getToken` + the DP exchange once
+ * before retrying.
+ */
+
+import { BrowserHttpClient, stripTrailingSlash, toApiError } from "./http.js";
+import { TasksClient } from "./tasks.js";
+import { FilesClient } from "./files.js";
+import { ConversationsClient } from "./conversations.js";
+
+export interface IntrospectionApiClientOptions {
+  /** Data Plane REST base URL (e.g. `https://dp.us.introspection.dev`). */
+  dpUrl: string;
+  /** Project the session is scoped to. */
+  projectId: string;
+  /**
+   * Returns a fresh Introspection access token from the app's broker
+   * (its own backend). Called on `connect()` and again whenever the DP
+   * session cookie needs re-minting after a 401.
+   */
+  getToken: () => string | Promise<string>;
+  /** Custom `fetch` (for tests or non-standard runtimes). */
+  fetch?: typeof fetch;
+  /** Extra headers merged into every DP request. */
+  additionalHeaders?: Record<string, string>;
+}
+
+export class IntrospectionApiClient {
+  /** `/v1/tasks` operations bound to the DP session cookie. */
+  readonly tasks: TasksClient;
+  /** `/v1/files` operations bound to the DP session cookie. */
+  readonly files: FilesClient;
+  /** Read-only `/v1/conversations` projection bound to the session cookie. */
+  readonly conversations: ConversationsClient;
+
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly opts: IntrospectionApiClientOptions) {
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "global fetch is unavailable; pass `fetch` or run in a modern browser",
+      );
+    }
+    const http = new BrowserHttpClient({
+      apiUrl: opts.dpUrl,
+      additionalHeaders: opts.additionalHeaders,
+      fetch: opts.fetch,
+      onUnauthorized: () => this.reexchange(),
+    });
+    this.tasks = new TasksClient(http);
+    this.files = new FilesClient(http);
+    this.conversations = new ConversationsClient(http);
+  }
+
+  /**
+   * Mint a token via `getToken` and redeem it at the DP for the
+   * `intro_dp_session` cookie. Call once before issuing task requests.
+   */
+  async connect(): Promise<void> {
+    await this.exchange();
+  }
+
+  private async exchange(): Promise<void> {
+    const token = await this.opts.getToken();
+    const res = await this.fetchImpl(
+      `${stripTrailingSlash(this.opts.dpUrl)}/v1/oauth/exchange`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...(this.opts.additionalHeaders ?? {}),
+        },
+        body: JSON.stringify({ token, project_id: this.opts.projectId }),
+        credentials: "include",
+      },
+    );
+    if (!res.ok) throw await toApiError(res);
+  }
+
+  /** 401 recovery: re-exchange, reporting success so the call can retry. */
+  private async reexchange(): Promise<boolean> {
+    try {
+      await this.exchange();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/api/conversations.ts

@@ -0,0 +1,214 @@
+/**
+ * Cookie-authenticated, read-only Conversations client for the browser
+ * (`/v1/conversations`).
+ *
+ * Mirrors the Node SDK's runner-bound `ConversationsApi`, but rides the
+ * DP `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads conversation history with the
+ * same identity session it uses for tasks and files. Conversations are a
+ * projection over the immutable telemetry store: list summaries, walk a
+ * conversation's items, or `retrieve()` the resolved state of one turn.
+ */
+
+import type {
+  ConversationItem,
+  ConversationItemInclude,
+  ConversationItemList,
+  ConversationItemListParams,
+  ConversationListParams,
+  ConversationResponse,
+  ConversationSummary,
+  MessagePart,
+  Paginated,
+  ToolCallResponsePart,
+} from "@introspection-sdk/types";
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+
+/** Includes requested when building a {@link ConversationResponse}. */
+const RESPONSE_INCLUDES: ConversationItemInclude[] = [
+  "gen_ai.input.messages",
+  "gen_ai.system_instructions",
+  "gen_ai.tool.definitions",
+];
+
+/**
+ * Items of a conversation (`/v1/conversations/{id}/items`). Read-only.
+ *
+ * Paging is OpenAI-style underneath: the envelope has NO `next` token —
+ * `list()` drives `after` = the previous page's `last_id` while
+ * `has_more` is true.
+ */
+export class ConversationItemsClient {
+  constructor(private readonly http: BrowserHttpClient) {}
+
+  /**
+   * List items of a conversation. `await` the result for the first page
+   * (an OpenAI-style {@link ConversationItemList} envelope), or
+   * `for await` it to stream every item across pages (fetched lazily —
+   * `limit` sets the page size, `after` the starting cursor; stop early to
+   * stop fetching). Pass `order: "asc"` to walk the transcript from the
+   * start.
+   *
+   * Items carry the turn-local delta in `input_messages` — only the
+   * messages new to that turn. Use `get()` for the full input history.
+   */
+  list(
+    conversationId: string,
+    params?: ConversationItemListParams,
+  ): Paginator<ConversationItem, ConversationItemList> {
+    return new Paginator(
+      {
+        fetch: (after) =>
+          this.http.request<ConversationItemList>({
+            method: "GET",
+            path: `/v1/conversations/${encodeURIComponent(conversationId)}/items`,
+            query: { ...params, after } as Record<string, unknown>,
+          }),
+        items: (page) => page.data,
+        next: (page) =>
+          page.has_more && page.last_id !== null ? page.last_id : undefined,
+      },
+      params?.after,
+    );
+  }
+
+  /**
+   * Fetch a single conversation item. Unlike the list route, the
+   * detail's `input_messages` is the FULL input history for that span.
+   */
+  get(
+    conversationId: string,
+    itemId: string,
+    params?: { include?: ConversationItemInclude[] },
+  ): Promise<ConversationItem> {
+    return this.http.request<ConversationItem>({
+      method: "GET",
+      path: `/v1/conversations/${encodeURIComponent(conversationId)}/items/${encodeURIComponent(itemId)}`,
+      query: params as Record<string, unknown> | undefined,
+    });
+  }
+}
+
+/**
+ * Read-only Conversations client (`/v1/conversations`).
+ *
+ * Both `list()` and `items.list()` are auto-paging, but they drive
+ * different wire protocols underneath: `list()` walks the standard
+ * Introspection cursor envelope's opaque `next` token, while
+ * `items.list()` walks an OpenAI-style envelope via `after` = the
+ * previous page's `last_id` while `has_more` is true.
+ */
+export class ConversationsClient {
+  /** Items of a conversation — `conversations.items.list(...)` etc. */
+  readonly items: ConversationItemsClient;
+
+  constructor(private readonly http: BrowserHttpClient) {
+    this.items = new ConversationItemsClient(http);
+  }
+
+  /**
+   * List conversation summaries matching `params`. `await` the result for
+   * the first page, or `for await` it to stream every summary across
+   * pages (fetched lazily — `limit` sets the page size, `next` the
+   * starting cursor; stop early to stop fetching).
+   */
+  list(params?: ConversationListParams): Paginator<ConversationSummary> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<ConversationSummary>>({
+          method: "GET",
+          path: "/v1/conversations",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
+  }
+
+  /**
+   * Responses-API-style retrieve: load the state of a conversation as of
+   * one item — the full input history, output, system instructions, and
+   * tool definitions of that turn.
+   *
+   * When `itemId` is omitted, the latest LLM turn is used: the first
+   * item (in descending order) whose `node_type` is `"assistant"` or
+   * whose `operation_name` is `"chat"`, falling back to the first item
+   * with a non-null `output_message`. Returns `null` when the
+   * conversation has no items.
+   *
+   * For the full per-turn transcript instead, iterate
+   * `items.list(conversationId, { order: "asc" })`.
+   */
+  async retrieve(
+    conversationId: string,
+    itemId?: string,
+  ): Promise<ConversationResponse | null> {
+    const targetId = itemId ?? (await this.findLatestTurnId(conversationId));
+    if (targetId === null) return null;
+
+    const detail = await this.items.get(conversationId, targetId, {
+      include: RESPONSE_INCLUDES,
+    });
+    const outputMessages =
+      detail.gen_ai_output_messages ??
+      (detail.output_message ? [detail.output_message] : []);
+    return {
+      conversation_id: conversationId,
+      response_id: detail.response_id ?? null,
+      item_id: detail.id,
+      created_at: detail.created_at,
+      model:
+        detail.model_name ??
+        detail.response_model ??
+        detail.request_model ??
+        null,
+      provider_name: detail.provider_name ?? null,
+      // The single-item route returns the FULL input history here.
+      input_messages: normalizeMessages(detail.input_messages),
+      output_messages: normalizeMessages(outputMessages),
+      system_instructions: detail.system_instructions ?? null,
+      tool_definitions: detail.tool_definitions ?? null,
+    };
+  }
+
+  /** Scan items in descending order for the most recent LLM turn. */
+  private async findLatestTurnId(
+    conversationId: string,
+  ): Promise<string | null> {
+    let fallback: ConversationItem | null = null;
+    for await (const item of this.items.list(conversationId, {
+      order: "desc",
+    })) {
+      if (item.node_type === "assistant" || item.operation_name === "chat") {
+        return item.id;
+      }
+      if (fallback === null && item.output_message != null) fallback = item;
+    }
+    return fallback?.id ?? null;
+  }
+}
+
+/**
+ * Defensive normalization for {@link ConversationsClient.retrieve} only:
+ * older DP deployments emitted `tool_call_response` parts with a legacy
+ * `result` key instead of the semconv `response` key. Map it across so
+ * replayed history is always semconv-shaped.
+ */
+function normalizeMessages<T extends { parts: MessagePart[] }>(
+  messages: T[],
+): T[] {
+  return messages.map((message) => ({
+    ...message,
+    parts: message.parts.map(normalizePart),
+  }));
+}
+
+function normalizePart(part: MessagePart): MessagePart {
+  if (part.type !== "tool_call_response") return part;
+  const legacy = part as ToolCallResponsePart & { result?: unknown };
+  if (legacy.response !== undefined || legacy.result === undefined) {
+    return part;
+  }
+  const { result, ...rest } = legacy;
+  return { ...rest, response: result };
+}

package/src/api/files.ts

@@ -0,0 +1,196 @@
+/**
+ * Cookie-authenticated Files client for the browser (`/v1/files`).
+ *
+ * Mirrors the Node SDK's runner-bound `FilesApi`, but rides the DP
+ * `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads and writes files with the
+ * same identity session it uses for tasks and conversations. The DP
+ * derives the owning `identity_key` from the session JWT; per-identity
+ * file visibility is enforced server-side.
+ */
+
+import type {
+  File as FileResource,
+  FileCreateOptions,
+  FileCreateTextParams,
+  FileListParams,
+  FileType,
+  FileUpdateParams,
+  ListParams,
+  Paginated,
+} from "@introspection-sdk/types";
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+
+export type FileUploadBody =
+  | { file: Blob; name?: string; file_type?: FileType }
+  | {
+      file: Uint8Array;
+      name: string;
+      file_type?: FileType;
+      contentType?: string;
+    };
+
+/** Versions of a file (`/v1/files/{id}/versions`). */
+export class FileVersionsClient {
+  constructor(private readonly http: BrowserHttpClient) {}
+
+  /**
+   * List versions of a file. `await` the result for the first page, or
+   * `for await` it to stream every version across pages (fetched lazily;
+   * stop early to stop fetching).
+   */
+  list(fileId: string, params?: ListParams): Paginator<FileResource> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<FileResource>>({
+          method: "GET",
+          path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
+  }
+
+  get(fileId: string, versionId: string): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/versions/${encodeURIComponent(versionId)}`,
+    });
+  }
+
+  create(
+    fileId: string,
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+      body: form,
+    });
+  }
+}
+
+/**
+ * Cookie-authenticated `/v1/files` client. Mirrors the Node SDK's
+ * `FilesApi` shape but is bound to a DP session cookie rather than a
+ * bearer token.
+ */
+export class FilesClient {
+  readonly versions: FileVersionsClient;
+
+  constructor(private readonly http: BrowserHttpClient) {
+    this.versions = new FileVersionsClient(http);
+  }
+
+  /**
+   * List files matching `params`. `await` the result for the first page,
+   * or `for await` it to stream every file across pages (fetched lazily —
+   * `limit` sets the page size, `next` the starting cursor; stop early to
+   * stop fetching).
+   */
+  list(params?: FileListParams): Paginator<FileResource> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<FileResource>>({
+          method: "GET",
+          path: "/v1/files",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
+  }
+
+  upload(
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: form,
+    });
+  }
+
+  createText(
+    body: FileCreateTextParams,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: options?.visibility
+        ? { ...body, visibility: options.visibility }
+        : body,
+    });
+  }
+
+  get(fileId: string): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+    });
+  }
+
+  update(fileId: string, body: FileUpdateParams): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "PATCH",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+      body,
+    });
+  }
+
+  delete(fileId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+      expect: "empty",
+    });
+  }
+
+  download(fileId: string): Promise<Uint8Array> {
+    return this.http.request<Uint8Array>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+      expect: "bytes",
+    });
+  }
+
+  downloadStream(fileId: string): Promise<ReadableStream<Uint8Array>> {
+    return this.http.request<ReadableStream<Uint8Array>>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+      expect: "stream",
+    });
+  }
+}
+
+function toFormData(
+  body: FileUploadBody,
+  options?: FileCreateOptions,
+): FormData {
+  const fd = new FormData();
+  if ("file" in body && body.file instanceof Blob) {
+    fd.append("file", body.file, body.name);
+  } else {
+    // Uint8Array branch — copy into a fresh ArrayBuffer so the Blob
+    // constructor sees a concrete ArrayBuffer (not ArrayBufferLike,
+    // which TS rejects under nodenext lib).
+    const u8 = (body as { file: Uint8Array }).file;
+    const ct =
+      (body as { contentType?: string }).contentType ??
+      "application/octet-stream";
+    const ab = u8.buffer.slice(
+      u8.byteOffset,
+      u8.byteOffset + u8.byteLength,
+    ) as ArrayBuffer;
+    fd.append("file", new Blob([ab], { type: ct }), body.name);
+  }
+  if (body.name) fd.append("name", body.name);
+  if (body.file_type) fd.append("file_type", body.file_type);
+  if (options?.visibility) fd.append("visibility", options.visibility);
+  return fd;
+}

package/src/api/http.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser HTTP transport for the Introspection Data Plane `/v1` surface.
+ *
+ * The request/response machinery — URL joining, query building, body
+ * serialization, error mapping, SSE — lives in the shared
+ * `@introspection-sdk/http` {@link BaseHttpClient}. This module pins the
+ * browser auth strategy on top of it: the DP is reached with the HttpOnly
+ * `intro_dp_session` cookie minted by `POST /v1/oauth/exchange`, so every
+ * request opts into `credentials: "include"` and sends NO bearer token —
+ * no Introspection credential ever lives in JavaScript. A 401 (expired
+ * session cookie) triggers a single `onUnauthorized` refresh + retry.
+ */
+
+import {
+  BaseHttpClient,
+  stripTrailingSlash,
+  toApiError,
+} from "@introspection-sdk/http";
+
+// Re-exported for `client.ts`, which redeems the DP session on `connect()`.
+export { stripTrailingSlash, toApiError };
+
+export interface BrowserHttpConfig {
+  /** DP REST base URL every request is prefixed with. */
+  apiUrl: string;
+  /** Extra headers merged into every request. */
+  additionalHeaders?: Record<string, string>;
+  /** Custom `fetch` (for tests or non-standard runtimes). */
+  fetch?: typeof fetch;
+  /**
+   * Invoked when a request comes back `401`. Return `true` if the DP
+   * session was refreshed and the request should be retried once;
+   * `false` to surface the original error.
+   */
+  onUnauthorized?: () => Promise<boolean>;
+}
+
+/**
+ * Cookie-authenticated HTTP wrapper bound to one DP endpoint. Has no
+ * opinion about which resource it serves — the caller picks the path.
+ */
+export class BrowserHttpClient extends BaseHttpClient {
+  constructor(cfg: BrowserHttpConfig) {
+    super({
+      apiUrl: cfg.apiUrl,
+      additionalHeaders: cfg.additionalHeaders,
+      fetch: cfg.fetch,
+      transport: {
+        authHeaders: () => ({}),
+        credentials: "include",
+        onUnauthorized: cfg.onUnauthorized,
+      },
+    });
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Introspection Browser API surface — `@introspection-sdk/introspection-browser/api`.
+ *
+ * A cookie-authenticated client for creating and streaming Introspection
+ * tasks directly from a single-page app, with no API key in the browser.
+ * Separate from the package's default telemetry export so apps only pull
+ * in what they use.
+ *
+ * @example
+ * ```typescript
+ * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
+ *
+ * const client = new IntrospectionApiClient({
+ *   dpUrl: "https://dp.us.introspection.dev",
+ *   projectId: "proj_…",
+ *   // your backend mints the Introspection access token
+ *   getToken: () => fetch("/api/introspection/token").then((r) => r.text()),
+ * });
+ *
+ * await client.connect(); // → intro_dp_session cookie
+ * const run = await client.tasks.start({
+ *   prompt: "Summarize my latest order",
+ *   agent_name: "support-agent",
+ *   identity: { user_id: "u_42" },
+ * });
+ * for await (const ev of run.stream()) console.log(ev.event, ev.data);
+ * ```
+ */
+
+export {
+  IntrospectionApiClient,
+  type IntrospectionApiClientOptions,
+} from "./client.js";
+export {
+  TasksClient,
+  TaskRunsClient,
+  RunHandle,
+  type CreateTaskParams,
+  type StartTaskParams,
+} from "./tasks.js";
+export {
+  FilesClient,
+  FileVersionsClient,
+  type FileUploadBody,
+} from "./files.js";
+export {
+  ConversationsClient,
+  ConversationItemsClient,
+} from "./conversations.js";
+export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
+export { parseSse } from "./sse.js";
+export {
+  Paginator,
+  cursorPaginate,
+  type PageSource,
+} from "@introspection-sdk/http";
+
+// Re-exported wire types for convenience.
+export type {
+  Task,
+  TaskRun,
+  TaskStatus,
+  TaskVisibility,
+  TaskCreateResponse,
+  TaskListParams,
+  TaskUpdateParams,
+  TaskRunCreateParams,
+  TaskCancelResponse,
+  RunIdentityInput,
+  Paginated,
+  SseEvent,
+  File,
+  FileType,
+  FileListParams,
+  FileUpdateParams,
+  FileCreateTextParams,
+  FileCreateOptions,
+  ListParams,
+  ConversationSummary,
+  ConversationItem,
+  ConversationItemList,
+  ConversationListParams,
+  ConversationItemListParams,
+  ConversationItemInclude,
+  ConversationResponse,
+} from "@introspection-sdk/types";
+export {
+  IntrospectionAPIError,
+  AuthenticationError,
+  InsufficientScopeError,
+  NotFoundError,
+  NetworkError,
+} from "@introspection-sdk/types";

package/src/api/sse.ts

@@ -0,0 +1,6 @@
+/**
+ * SSE parsing now lives in the shared `@introspection-sdk/http` core so
+ * the browser and Node SDKs stay byte-for-byte identical. Re-exported
+ * here to keep the existing `./sse.js` import path stable.
+ */
+export { parseSse } from "@introspection-sdk/http";