@introspection-sdk/introspection-node 0.5.0 → 0.5.2

package/src/http.ts

@@ -1,8 +1,4 @@
-import {
-  IntrospectionAPIError,
-  NetworkError,
-  apiErrorFromResponse,
-} from "@introspection-sdk/types";
+import { BaseHttpClient } from "@introspection-sdk/http";
 
 export interface ResolvedApiConfig {
   /**
@@ -17,147 +13,21 @@ export interface ResolvedApiConfig {
   fetch?: typeof fetch;
 }
 
-function joinUrl(base: string, path: string): string {
-  const b = base.replace(/\/+$/, "");
-  const p = path.startsWith("/") ? path : `/${path}`;
-  return `${b}${p}`;
-}
-
-function buildQuery(params?: Record<string, unknown>): string {
-  if (!params) return "";
-  const sp = new URLSearchParams();
-  for (const [k, v] of Object.entries(params)) {
-    if (v === undefined || v === null) continue;
-    if (Array.isArray(v)) {
-      for (const item of v) sp.append(k, String(item));
-    } else {
-      sp.set(k, String(v));
-    }
-  }
-  const q = sp.toString();
-  return q ? `?${q}` : "";
-}
-
 /**
- * Thin HTTP wrapper used by both the CP-bound IntrospectionClient and
- * each DP-bound Runner. Has no opinion on which one it is — the caller
- * picks the base URL and the token.
+ * Bearer-token HTTP client used by both the CP-bound IntrospectionClient
+ * and each DP-bound Runner. The request/response machinery lives in the
+ * shared {@link BaseHttpClient}; this only pins the auth strategy —
+ * `Authorization: Bearer <token>` on every request, no cookie credentials.
  */
-export class HttpClient {
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(private readonly cfg: ResolvedApiConfig) {
-    this.fetchImpl = cfg.fetch ?? globalThis.fetch;
-    if (!this.fetchImpl) {
-      throw new Error(
-        "global fetch is unavailable; pass `advanced.fetch` or run on Node 18+",
-      );
-    }
-  }
-
-  private headers(extra?: Record<string, string>): Record<string, string> {
-    return {
-      Authorization: `Bearer ${this.cfg.token}`,
-      ...(this.cfg.additionalHeaders ?? {}),
-      ...(extra ?? {}),
-    };
-  }
-
-  async request<T>(opts: {
-    method: string;
-    path: string;
-    query?: Record<string, unknown>;
-    body?: unknown;
-    headers?: Record<string, string>;
-    expect?: "json" | "empty" | "bytes" | "stream";
-  }): Promise<T> {
-    const url = joinUrl(this.cfg.apiUrl, opts.path) + buildQuery(opts.query);
-    let body: BodyInit | undefined;
-    const headers = this.headers(opts.headers);
-    if (opts.body instanceof FormData) {
-      body = opts.body;
-      // let fetch set the multipart boundary
-    } else if (opts.body !== undefined) {
-      headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
-      body = JSON.stringify(opts.body);
-    }
-    let res: Response;
-    try {
-      res = await this.fetchImpl(url, {
-        method: opts.method,
-        headers,
-        body,
-      });
-    } catch (err) {
-      throw new NetworkError({
-        message: err instanceof Error ? err.message : "network request failed",
-        code: null,
-        requestId: null,
-        body: err,
-      });
-    }
-    if (!res.ok) throw await toApiError(res);
-    const expect = opts.expect ?? "json";
-    if (expect === "empty") return undefined as T;
-    if (expect === "bytes") return new Uint8Array(await res.arrayBuffer()) as T;
-    if (expect === "stream") return res.body as T;
-    return (await res.json()) as T;
-  }
-
-  async stream(opts: {
-    path: string;
-    query?: Record<string, unknown>;
-  }): Promise<Response> {
-    const url = joinUrl(this.cfg.apiUrl, opts.path) + buildQuery(opts.query);
-    let res: Response;
-    try {
-      res = await this.fetchImpl(url, {
-        method: "GET",
-        headers: this.headers({ Accept: "text/event-stream" }),
-      });
-    } catch (err) {
-      throw new NetworkError({
-        message: err instanceof Error ? err.message : "network request failed",
-        code: null,
-        requestId: null,
-        body: err,
-      });
-    }
-    if (!res.ok) throw await toApiError(res);
-    return res;
-  }
-}
-
-async function toApiError(res: Response): Promise<IntrospectionAPIError> {
-  let body: unknown = undefined;
-  let message = `HTTP ${res.status}`;
-  let code: string | null = null;
-  const ct = res.headers.get("content-type") ?? "";
-  if (ct.includes("json")) {
-    body = await res.json().catch(() => undefined);
-    if (body && typeof body === "object") {
-      const obj = body as Record<string, unknown>;
-      if (typeof obj.detail === "string") message = obj.detail;
-      if (typeof obj.code === "string") code = obj.code;
-      if (typeof obj.message === "string" && message === `HTTP ${res.status}`) {
-        message = obj.message;
-      }
-    }
-  } else {
-    body = await res.text().catch(() => undefined);
-  }
-  const retryAfterHeader = res.headers.get("retry-after");
-  let retryAfter: number | null = null;
-  if (retryAfterHeader) {
-    const n = Number(retryAfterHeader);
-    if (Number.isFinite(n)) retryAfter = n;
+export class HttpClient extends BaseHttpClient {
+  constructor(cfg: ResolvedApiConfig) {
+    super({
+      apiUrl: cfg.apiUrl,
+      additionalHeaders: cfg.additionalHeaders,
+      fetch: cfg.fetch,
+      transport: {
+        authHeaders: () => ({ Authorization: `Bearer ${cfg.token}` }),
+      },
+    });
   }
-  return apiErrorFromResponse({
-    status: res.status,
-    message,
-    code,
-    requestId: res.headers.get("x-request-id"),
-    body,
-    retryAfter,
-  });
 }

package/src/pagination.ts

@@ -0,0 +1,10 @@
+/**
+ * Cursor pagination now lives in the shared `@introspection-sdk/http`
+ * core so the browser and Node SDKs share one `Paginator`. Re-exported
+ * here to keep the existing `./pagination.js` import path stable.
+ */
+export {
+  Paginator,
+  cursorPaginate,
+  type PageSource,
+} from "@introspection-sdk/http";

package/src/resources/experiments.ts

@@ -11,6 +11,7 @@ import type {
 } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
 import type { IntrospectionClient } from "../client.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { Runner, type RunnerSource } from "../runner.js";
 
 interface ExperimentRunRequestBody {
@@ -37,21 +38,21 @@ export class ExperimentsApi {
   ) {}
 
   /**
-   * Iterate experiments matching `params`. Pages are fetched lazily as
-   * the iterator is consumed (`limit` sets the page size, `next` the
-   * starting cursor); stop early to stop fetching.
+   * List experiments matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every experiment across pages
+   * (fetched lazily — `limit` sets the page size, `next` the starting
+   * cursor; stop early to stop fetching).
    */
-  async *list(params: ExperimentListParams): AsyncIterable<Experiment> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.http.request<Paginated<Experiment>>({
-        method: "GET",
-        path: "/v1/experiments",
-        query: { ...params, next } as unknown as Record<string, unknown>,
-      });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  list(params: ExperimentListParams): Paginator<Experiment> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Experiment>>({
+          method: "GET",
+          path: "/v1/experiments",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid): Promise<Experiment> {

package/src/resources/recipes.ts

@@ -7,6 +7,7 @@ import type {
   Uuid,
 } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 
 /**
  * Programmatic CRUD for `/v1/recipes` on the CP.
@@ -19,21 +20,21 @@ export class RecipesApi {
   constructor(private readonly http: HttpClient) {}
 
   /**
-   * Iterate recipes matching `params`. Pages are fetched lazily as the
-   * iterator is consumed (`limit` sets the page size, `next` the
-   * starting cursor); stop early to stop fetching.
+   * List recipes matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every recipe across pages (fetched
+   * lazily — `limit` sets the page size, `next` the starting cursor; stop
+   * early to stop fetching).
    */
-  async *list(params: RecipeListParams): AsyncIterable<Recipe> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.http.request<Paginated<Recipe>>({
-        method: "GET",
-        path: "/v1/recipes",
-        query: { ...params, next } as unknown as Record<string, unknown>,
-      });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  list(params: RecipeListParams): Paginator<Recipe> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Recipe>>({
+          method: "GET",
+          path: "/v1/recipes",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid): Promise<Recipe> {

package/src/resources/runtimes.ts

@@ -12,6 +12,7 @@ import type {
 import { NotFoundError } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
 import type { IntrospectionClient } from "../client.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { Runner, type RunnerSource } from "../runner.js";
 
 const UUID_RE =
@@ -51,21 +52,21 @@ export class RuntimesApi {
   ) {}
 
   /**
-   * Iterate runtimes matching `params`. Pages are fetched lazily as the
-   * iterator is consumed (`limit` sets the page size, `next` the
-   * starting cursor); stop early to stop fetching.
+   * List runtimes matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every runtime across pages (fetched
+   * lazily — `limit` sets the page size, `next` the starting cursor; stop
+   * early to stop fetching).
    */
-  async *list(params: RuntimeListParams): AsyncIterable<Runtime> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.http.request<Paginated<Runtime>>({
-        method: "GET",
-        path: "/v1/runtimes",
-        query: { ...params, next } as unknown as Record<string, unknown>,
-      });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  list(params: RuntimeListParams): Paginator<Runtime> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Runtime>>({
+          method: "GET",
+          path: "/v1/runtimes",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid, params: { project_id?: Uuid }): Promise<Runtime> {

package/src/runner-resources/conversations.ts

@@ -11,6 +11,7 @@ import type {
   ToolCallResponsePart,
 } from "@introspection-sdk/types";
 import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 
 /** Includes requested when building a {@link ConversationResponse}. */
 const RESPONSE_INCLUDES: ConversationItemInclude[] = [
@@ -30,29 +31,34 @@ export class ConversationItemsApi {
   constructor(private readonly http: HttpClient) {}
 
   /**
-   * Iterate items of a conversation. Pages are fetched lazily as the
-   * iterator is consumed (`limit` sets the page size, `after` the
-   * starting cursor); stop early to stop fetching. Pass
-   * `order: "asc"` to walk the transcript from the start.
+   * 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.
    */
-  async *list(
+  list(
     conversationId: string,
     params?: ConversationItemListParams,
-  ): AsyncIterable<ConversationItem> {
-    let after: string | undefined = params?.after;
-    for (;;) {
-      const page = await this.http.request<ConversationItemList>({
-        method: "GET",
-        path: `/v1/conversations/${encodeURIComponent(conversationId)}/items`,
-        query: { ...params, after } as Record<string, unknown>,
-      });
-      for (const item of page.data) yield item;
-      if (!page.has_more || page.last_id === null) return;
-      after = page.last_id;
-    }
+  ): 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,
+    );
   }
 
   /**
@@ -90,23 +96,21 @@ export class ConversationsApi {
   }
 
   /**
-   * Iterate conversation summaries matching `params`. Pages are fetched
-   * lazily as the iterator is consumed (`limit` sets the page size,
-   * `next` the starting cursor); stop early to stop fetching.
+   * 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).
    */
-  async *list(
-    params?: ConversationListParams,
-  ): AsyncIterable<ConversationSummary> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.http.request<Paginated<ConversationSummary>>({
-        method: "GET",
-        path: "/v1/conversations",
-        query: { ...params, next } as Record<string, unknown>,
-      });
-      for (const c of page.records) yield c;
-      next = page.next ?? undefined;
-    } while (next);
+  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,
+    );
   }
 
   /**

package/src/runner-resources/files.ts

@@ -1,5 +1,6 @@
 import type {
   File as FileResource,
+  FileCreateOptions,
   FileCreateTextParams,
   FileListParams,
   FileType,
@@ -8,6 +9,7 @@ import type {
   Paginated,
 } from "@introspection-sdk/types";
 import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 
 export type FileUploadBody =
   | { file: Blob; name?: string; file_type?: FileType }
@@ -22,23 +24,20 @@ export class FileVersionsApi {
   constructor(private readonly http: HttpClient) {}
 
   /**
-   * Iterate versions of a file. Pages are fetched lazily as the
-   * iterator is consumed; stop early to stop fetching.
+   * 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).
    */
-  async *list(
-    fileId: string,
-    params?: ListParams,
-  ): AsyncIterable<FileResource> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.http.request<Paginated<FileResource>>({
-        method: "GET",
-        path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
-        query: { ...params, next } as Record<string, unknown>,
-      });
-      for (const f of page.records) yield f;
-      next = page.next ?? undefined;
-    } while (next);
+  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> {
@@ -48,8 +47,12 @@ export class FileVersionsApi {
     });
   }
 
-  create(fileId: string, body: FileUploadBody): Promise<FileResource> {
-    const form = toFormData(body);
+  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`,
@@ -66,25 +69,28 @@ export class FilesApi {
   }
 
   /**
-   * Iterate files matching `params`. Pages are fetched lazily as the
-   * iterator is consumed (`limit` sets the page size, `next` the
-   * starting cursor); stop early to stop fetching.
+   * 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).
    */
-  async *list(params?: FileListParams): AsyncIterable<FileResource> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.http.request<Paginated<FileResource>>({
-        method: "GET",
-        path: "/v1/files",
-        query: { ...params, next } as Record<string, unknown>,
-      });
-      for (const f of page.records) yield f;
-      next = page.next ?? undefined;
-    } while (next);
+  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): Promise<FileResource> {
-    const form = toFormData(body);
+  upload(
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
     return this.http.request<FileResource>({
       method: "POST",
       path: "/v1/files",
@@ -92,11 +98,16 @@ export class FilesApi {
     });
   }
 
-  createText(body: FileCreateTextParams): Promise<FileResource> {
+  createText(
+    body: FileCreateTextParams,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
     return this.http.request<FileResource>({
       method: "POST",
       path: "/v1/files",
-      body,
+      body: options?.visibility
+        ? { ...body, visibility: options.visibility }
+        : body,
     });
   }
 
@@ -140,7 +151,10 @@ export class FilesApi {
   }
 }
 
-function toFormData(body: FileUploadBody): FormData {
+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);
@@ -160,5 +174,6 @@ function toFormData(body: FileUploadBody): FormData {
   }
   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/runner-resources/tasks.ts

@@ -12,6 +12,7 @@ import type {
   TaskUpdateParams,
 } from "@introspection-sdk/types";
 import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { parseSse } from "../streaming.js";
 
 export interface StartParams extends TaskCreateParams {
@@ -85,21 +86,21 @@ export class TasksApi {
   }
 
   /**
-   * Iterate tasks matching `params`. Pages are fetched lazily as the
-   * iterator is consumed (`limit` sets the page size, `next` the
-   * starting cursor); stop early to stop fetching.
+   * List tasks matching `params`. `await` the result for the first page,
+   * or `for await` it to stream every task across pages (fetched lazily —
+   * `limit` sets the page size, `next` the starting cursor; stop early to
+   * stop fetching).
    */
-  async *list(params?: TaskListParams): AsyncIterable<Task> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.http.request<Paginated<Task>>({
-        method: "GET",
-        path: "/v1/tasks",
-        query: { ...params, next } as Record<string, unknown>,
-      });
-      for (const t of page.records) yield t;
-      next = page.next ?? undefined;
-    } while (next);
+  list(params?: TaskListParams): Paginator<Task> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Task>>({
+          method: "GET",
+          path: "/v1/tasks",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
   }
 
   create(body: TaskCreateParams): Promise<TaskCreateResponse> {