@introspection-sdk/introspection-node 0.4.2 → 0.4.4

package/src/resources/recipes.ts

@@ -0,0 +1,73 @@
+import type {
+  Paginated,
+  Recipe,
+  RecipeCreate,
+  RecipeListParams,
+  RecipeUpdate,
+  Uuid,
+} from "@introspection-sdk/types";
+import type { HttpClient } from "../http.js";
+
+/**
+ * Programmatic CRUD for `/v1/recipes` on the CP.
+ *
+ * Recipes are immutable build artefacts (repository + git ref + commit
+ * sha + optional sub-path). They are referenced by runtimes via
+ * `runtime.recipe_id` and by experiment arms via `arm.recipe_id`.
+ */
+export class RecipesApi {
+  constructor(private readonly http: HttpClient) {}
+
+  list(params: RecipeListParams): Promise<Paginated<Recipe>> {
+    return this.http.request<Paginated<Recipe>>({
+      method: "GET",
+      path: "/v1/recipes",
+      query: params as unknown as Record<string, unknown>,
+    });
+  }
+
+  /** Async-iterate every page that matches `params`. */
+  async *listAll(params: RecipeListParams): AsyncIterable<Recipe> {
+    let next: string | undefined = params.next;
+    do {
+      const page = await this.list({ ...params, next });
+      for (const r of page.records) yield r;
+      next = page.next ?? undefined;
+    } while (next);
+  }
+
+  get(id: Uuid): Promise<Recipe> {
+    return this.http.request<Recipe>({
+      method: "GET",
+      path: `/v1/recipes/${encodeURIComponent(id)}`,
+    });
+  }
+
+  create(input: RecipeCreate): Promise<Recipe> {
+    return this.http.request<Recipe>({
+      method: "POST",
+      path: "/v1/recipes",
+      body: input,
+    });
+  }
+
+  update(id: Uuid, input: RecipeUpdate): Promise<Recipe> {
+    return this.http.request<Recipe>({
+      method: "PATCH",
+      path: `/v1/recipes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+  }
+
+  delete(id: Uuid): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/recipes/${encodeURIComponent(id)}`,
+      expect: "empty",
+    });
+  }
+}
+
+export function attachRecipes(http: HttpClient): RecipesApi {
+  return new RecipesApi(http);
+}

package/src/resources/runtimes.ts

@@ -0,0 +1,231 @@
+import type {
+  Paginated,
+  Recipe,
+  RunRequest,
+  Runtime,
+  RuntimeCreate,
+  RuntimeListParams,
+  RuntimeUpdate,
+  RunnerSpec,
+  Uuid,
+} from "@introspection-sdk/types";
+import { NotFoundError } from "@introspection-sdk/types";
+import type { HttpClient } from "../http.js";
+import type { IntrospectionClient } from "../client.js";
+import { Runner, type RunnerSource } from "../runner.js";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+export interface RuntimeRunRequestBody {
+  identity?: {
+    user_id?: string;
+    anonymous_id?: string;
+    conversation_id?: string;
+  };
+  ttl_seconds?: number;
+  recipe_id?: Uuid;
+}
+
+function toRunBody(opts?: RunRequest): RuntimeRunRequestBody | undefined {
+  if (!opts) return undefined;
+  const out: RuntimeRunRequestBody = {};
+  if (opts.identity) out.identity = opts.identity;
+  if (opts.ttl_seconds !== undefined) out.ttl_seconds = opts.ttl_seconds;
+  if (opts.recipe_id !== undefined) out.recipe_id = opts.recipe_id;
+  return out;
+}
+
+/**
+ * Programmatic CRUD for `/v1/runtimes` on the CP. Mounted on the
+ * IntrospectionClient as a callable hybrid (see `RuntimeHandleFactory`).
+ */
+export class RuntimesApi {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly client: IntrospectionClient,
+  ) {}
+
+  list(params: RuntimeListParams): Promise<Paginated<Runtime>> {
+    return this.http.request<Paginated<Runtime>>({
+      method: "GET",
+      path: "/v1/runtimes",
+      query: params as unknown as Record<string, unknown>,
+    });
+  }
+
+  async *listAll(params: RuntimeListParams): AsyncIterable<Runtime> {
+    let next: string | undefined = params.next;
+    do {
+      const page = await this.list({ ...params, next });
+      for (const r of page.records) yield r;
+      next = page.next ?? undefined;
+    } while (next);
+  }
+
+  get(id: Uuid, params: { project_id?: Uuid }): Promise<Runtime> {
+    return this.http.request<Runtime>({
+      method: "GET",
+      path: `/v1/runtimes/${encodeURIComponent(id)}`,
+      query: params as Record<string, unknown>,
+    });
+  }
+
+  create(input: RuntimeCreate): Promise<Runtime> {
+    return this.http.request<Runtime>({
+      method: "POST",
+      path: "/v1/runtimes",
+      body: input,
+    });
+  }
+
+  update(id: Uuid, input: RuntimeUpdate): Promise<Runtime> {
+    return this.http.request<Runtime>({
+      method: "PATCH",
+      path: `/v1/runtimes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+  }
+
+  delete(id: Uuid): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/runtimes/${encodeURIComponent(id)}`,
+      expect: "empty",
+    });
+  }
+
+  /** Resolve a name to a runtime by querying `/v1/runtimes?name=…`. */
+  async resolveByName(name: string, projectId?: Uuid): Promise<Runtime> {
+    const page = await this.list({ project_id: projectId, name, limit: 2 });
+    const match = page.records.find((r) => r.name === name);
+    if (!match) {
+      throw new NotFoundError({
+        message: `Runtime '${name}' not found${projectId ? ` in project ${projectId}` : ""}`,
+        status: 404,
+        code: "not_found",
+      });
+    }
+    return match;
+  }
+
+  /** POST `/v1/runtimes/{id}/run` and wrap the result in a `Runner`. */
+  async runById(id: Uuid, opts?: RunRequest): Promise<Runner> {
+    const spec = await this.http.request<RunnerSpec>({
+      method: "POST",
+      path: `/v1/runtimes/${encodeURIComponent(id)}/run`,
+      body: toRunBody(opts) ?? {},
+    });
+    const source: RunnerSource = {
+      kind: "runtime",
+      id,
+      options: opts,
+    };
+    return new Runner(this.client, source, spec);
+  }
+
+  async activateById(
+    id: Uuid,
+    params?: { project_id?: Uuid },
+  ): Promise<Runtime> {
+    return this.http.request<Runtime>({
+      method: "POST",
+      path: `/v1/runtimes/${encodeURIComponent(id)}/activate`,
+      query: params as Record<string, unknown> | undefined,
+      body: {},
+    });
+  }
+}
+
+/**
+ * Handle returned by `client.runtimes(idOrName)`. Resolves the underlying
+ * runtime id lazily — if you pass a UUID, no extra lookup happens; if you
+ * pass a name, the first call that needs the id will hit
+ * `/v1/runtimes?name=…`.
+ */
+export class RuntimeHandle {
+  private resolvedId: Uuid | null;
+  private readonly pinnedRecipeId: Uuid | null;
+
+  constructor(
+    private readonly api: RuntimesApi,
+    private readonly client: IntrospectionClient,
+    private readonly idOrName: string,
+    pinnedRecipeId: Uuid | null = null,
+  ) {
+    this.resolvedId = isUuid(idOrName) ? idOrName : null;
+    this.pinnedRecipeId = pinnedRecipeId;
+  }
+
+  private async resolveId(): Promise<Uuid> {
+    if (this.resolvedId) return this.resolvedId;
+    const runtime = await this.api.resolveByName(
+      this.idOrName,
+      this.client.projectId,
+    );
+    this.resolvedId = runtime.id;
+    return runtime.id;
+  }
+
+  /**
+   * Pin to a specific recipe — canary a previous version. Subsequent
+   * `.run()` calls on the returned handle open a runner against the
+   * runtime row in this name whose `recipe_id` matches `recipe.id`
+   * (resolved server-side by CP).
+   *
+   * Returns a new child {@link RuntimeHandle}; the original handle is
+   * unaffected. Accepts a {@link Recipe} object (uses `.id`) or a
+   * recipe id string.
+   */
+  pin(recipe: Recipe | string): RuntimeHandle {
+    const recipeId = typeof recipe === "string" ? recipe : recipe.id;
+    return new RuntimeHandle(this.api, this.client, this.idOrName, recipeId);
+  }
+
+  async run(opts?: RunRequest): Promise<Runner> {
+    const id = await this.resolveId();
+    const merged: RunRequest | undefined =
+      this.pinnedRecipeId !== null
+        ? { ...(opts ?? {}), recipe_id: this.pinnedRecipeId }
+        : opts;
+    return this.api.runById(id, merged);
+  }
+
+  async activate(params?: { projectId?: Uuid }): Promise<Runtime> {
+    const id = await this.resolveId();
+    return this.api.activateById(id, { project_id: params?.projectId });
+  }
+}
+
+/**
+ * Callable hybrid: `client.runtimes` exposes the CRUD methods of
+ * `RuntimesApi` AND can be invoked as a function returning a
+ * `RuntimeHandle`. Realised by `attachRuntimes` below.
+ */
+export type RuntimeHandleFactory = (idOrName: string) => RuntimeHandle;
+
+export function attachRuntimes(
+  client: IntrospectionClient,
+  http: HttpClient,
+): RuntimesApi & RuntimeHandleFactory {
+  const api = new RuntimesApi(http, client);
+  const factory: RuntimeHandleFactory = (idOrName: string) =>
+    new RuntimeHandle(api, client, idOrName);
+  // Mount the API methods on the factory function. Using bound copies so
+  // the methods can be invoked off the proxy without losing `this`.
+  const hybrid = factory as RuntimesApi & RuntimeHandleFactory;
+  hybrid.list = api.list.bind(api);
+  hybrid.listAll = api.listAll.bind(api);
+  hybrid.get = api.get.bind(api);
+  hybrid.create = api.create.bind(api);
+  hybrid.update = api.update.bind(api);
+  hybrid.delete = api.delete.bind(api);
+  hybrid.resolveByName = api.resolveByName.bind(api);
+  hybrid.runById = api.runById.bind(api);
+  hybrid.activateById = api.activateById.bind(api);
+  return hybrid;
+}

package/src/runner-resources/files.ts

@@ -0,0 +1,163 @@
+import type {
+  File as FileResource,
+  FileCreateTextParams,
+  FileListParams,
+  FileType,
+  FileUpdateParams,
+  ListParams,
+  Paginated,
+} from "@introspection-sdk/types";
+import { HttpClient } from "../http.js";
+
+export type FileUploadBody =
+  | { file: Blob; name?: string; file_type?: FileType }
+  | {
+      file: Uint8Array;
+      name: string;
+      file_type?: FileType;
+      contentType?: string;
+    };
+
+export class FileVersionsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  list(fileId: string, params?: ListParams): Promise<Paginated<FileResource>> {
+    return this.http.request<Paginated<FileResource>>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+      query: params as Record<string, unknown> | undefined,
+    });
+  }
+
+  async *listAll(
+    fileId: string,
+    params?: ListParams,
+  ): AsyncIterable<FileResource> {
+    let next: string | undefined = params?.next;
+    do {
+      const page = await this.list(fileId, { ...params, next });
+      for (const f of page.records) yield f;
+      next = page.next ?? undefined;
+    } while (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): Promise<FileResource> {
+    const form = toFormData(body);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+      body: form,
+    });
+  }
+}
+
+export class FilesApi {
+  readonly versions: FileVersionsApi;
+
+  constructor(private readonly http: HttpClient) {
+    this.versions = new FileVersionsApi(http);
+  }
+
+  list(params?: FileListParams): Promise<Paginated<FileResource>> {
+    return this.http.request<Paginated<FileResource>>({
+      method: "GET",
+      path: "/v1/files",
+      query: params as Record<string, unknown> | undefined,
+    });
+  }
+
+  async *listAll(params?: FileListParams): AsyncIterable<FileResource> {
+    let next: string | undefined = params?.next;
+    do {
+      const page = await this.list({ ...params, next });
+      for (const f of page.records) yield f;
+      next = page.next ?? undefined;
+    } while (next);
+  }
+
+  upload(body: FileUploadBody): Promise<FileResource> {
+    const form = toFormData(body);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: form,
+    });
+  }
+
+  createText(body: FileCreateTextParams): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      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): 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);
+  return fd;
+}

package/src/runner-resources/tasks.ts

@@ -0,0 +1,156 @@
+import type {
+  Paginated,
+  SseEvent,
+  Task,
+  TaskCancelResponse,
+  TaskCreateParams,
+  TaskCreateResponse,
+  TaskListParams,
+  TaskRun,
+  TaskRunCreateParams,
+  TaskRunResponse,
+  TaskUpdateParams,
+} from "@introspection-sdk/types";
+import { HttpClient } from "../http.js";
+import { parseSse } from "../streaming.js";
+
+export interface StartParams extends TaskCreateParams {
+  prompt: string; // required for the cursor-style sugar
+}
+
+export class RunHandle {
+  constructor(
+    public readonly task: Task | null,
+    public readonly run: TaskRun,
+    private readonly runs: TaskRunsApi,
+  ) {}
+
+  stream(): AsyncIterable<SseEvent> {
+    return this.runs.stream(this.run.task_id, this.run.id);
+  }
+
+  cancel(): Promise<TaskCancelResponse> {
+    return this.runs.cancel(this.run.task_id, this.run.id);
+  }
+
+  /** Convenience: collect `data` from `event: text`-style frames into a string. */
+  async text(): Promise<string> {
+    let out = "";
+    for await (const ev of this.stream()) {
+      if (ev.event === "text" || ev.event === "message") out += ev.data;
+    }
+    return out;
+  }
+}
+
+export class TaskRunsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  async create(taskId: string, body: TaskRunCreateParams): Promise<RunHandle> {
+    const res = await this.http.request<TaskRunResponse>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs`,
+      body,
+    });
+    return new RunHandle(null, res.run, this);
+  }
+
+  get(taskId: string, runId: string): Promise<TaskRun> {
+    return this.http.request<TaskRun>({
+      method: "GET",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}`,
+    });
+  }
+
+  cancel(taskId: string, runId: string): Promise<TaskCancelResponse> {
+    return this.http.request<TaskCancelResponse>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/cancel`,
+    });
+  }
+
+  async *stream(taskId: string, runId: string): AsyncIterable<SseEvent> {
+    const res = await this.http.stream({
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/stream`,
+    });
+    yield* parseSse(res);
+  }
+}
+
+export class TasksApi {
+  readonly runs: TaskRunsApi;
+
+  constructor(private readonly http: HttpClient) {
+    this.runs = new TaskRunsApi(http);
+  }
+
+  list(params?: TaskListParams): Promise<Paginated<Task>> {
+    return this.http.request<Paginated<Task>>({
+      method: "GET",
+      path: "/v1/tasks",
+      query: params as Record<string, unknown> | undefined,
+    });
+  }
+
+  async *listAll(params?: TaskListParams): AsyncIterable<Task> {
+    let next: string | undefined = params?.next;
+    do {
+      const page = await this.list({ ...params, next });
+      for (const t of page.records) yield t;
+      next = page.next ?? undefined;
+    } while (next);
+  }
+
+  create(body: TaskCreateParams): Promise<TaskCreateResponse> {
+    return this.http.request<TaskCreateResponse>({
+      method: "POST",
+      path: "/v1/tasks",
+      body,
+    });
+  }
+
+  get(taskId: string): Promise<Task> {
+    return this.http.request<Task>({
+      method: "GET",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+    });
+  }
+
+  update(taskId: string, body: TaskUpdateParams): Promise<Task> {
+    return this.http.request<Task>({
+      method: "PATCH",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+      body,
+    });
+  }
+
+  delete(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+      expect: "empty",
+    });
+  }
+
+  archive(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/archive`,
+      expect: "empty",
+    });
+  }
+
+  unarchive(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/unarchive`,
+      expect: "empty",
+    });
+  }
+
+  /** Cursor-style sugar: create a task + return a handle on its initial run. */
+  async start(params: StartParams): Promise<RunHandle> {
+    const res = await this.create(params);
+    return new RunHandle(res.task, res.run, this.runs);
+  }
+}