@pawabase/client 0.1.3 → 0.2.0

package/src/agents.ts

@@ -0,0 +1,184 @@
+/**
+ * Agents and knowledge bases, run from your app: the signed-in user's access rules decide which agents they may run and which
+ * knowledge bases they may search.
+ *
+ * ```ts
+ * const run = await pawabase.ai.agents.run("support", "How do I reset my password?");
+ * console.log(run.output);
+ * for await (const event of pawabase.ai.agents.stream("support", "Summarise my open tickets")) console.log(event);
+ * const hits = await pawabase.ai.knowledge.search("docs", "reset password");
+ * ```
+ */
+import { ApiError } from "./errors.js";
+import type { HttpClient } from "./http.js";
+
+export type AgentRunStatus = "running" | "waiting" | "finished" | "failed" | "cancelled" | (string & {});
+
+/** One run of an agent. A run that stopped to ask permission has `status: "waiting"` and lists what it is waiting on. */
+export interface AgentRun {
+  id: string;
+  agent: string;
+  status: AgentRunStatus;
+  /** The agent's answer, once it has one. */
+  output?: string;
+  thread?: string;
+  error?: string;
+  [field: string]: unknown;
+}
+
+/** One step of a streamed run (`type` says which: text pieces, tool calls and results, approvals, `error`). */
+export interface AgentEvent {
+  type: string;
+  [field: string]: unknown;
+}
+
+export interface AgentRunOptions {
+  /** Carry on a conversation: the `thread` of an earlier run. */
+  thread?: string;
+  /** Return at once; poll `get()` or start a flow from `agent.run.finished`. */
+  background?: boolean;
+  signal?: AbortSignal | null;
+}
+
+export interface KnowledgeHit {
+  [field: string]: unknown;
+}
+
+export interface KnowledgeDocument {
+  id: string;
+  status: "pending" | "ready" | "failed" | (string & {});
+  title?: string;
+  error?: string;
+  chunks?: number;
+}
+
+const seg = (...parts: string[]) => "/" + parts.map(encodeURIComponent).join("/");
+
+export class AgentsClient {
+  constructor(private readonly http: HttpClient) {}
+
+  /** The agents the caller may run. */
+  async list(): Promise<Array<{ name: string; description: string }>> {
+    const body = await this.http.request<{ data: Array<{ name: string; description: string }> }>({ path: "/ai/v1/agents" });
+    return body.data;
+  }
+
+  /** Send `input` and wait for the run (or, with `background`, only for it to start). */
+  run(name: string, input: string, options: AgentRunOptions = {}): Promise<AgentRun> {
+    return this.http.request<AgentRun>({
+      method: "POST",
+      path: `/ai/v1${seg("agents", name, "runs")}`,
+      body: { input, thread: options.thread, background: options.background ?? false },
+      signal: options.signal ?? undefined,
+    });
+  }
+
+  /** Each step of a run as it happens. */
+  async *stream(name: string, input: string, options: Omit<AgentRunOptions, "background"> = {}): AsyncGenerator<AgentEvent, void, void> {
+    const stream = await this.http.request<ReadableStream<Uint8Array> | null>({
+      method: "POST",
+      path: `/ai/v1${seg("agents", name, "runs")}`,
+      body: { input, thread: options.thread, stream: true },
+      parse: "stream",
+      signal: options.signal ?? undefined,
+    });
+    if (!stream) return;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let end: number;
+        while ((end = buffer.indexOf("\n\n")) >= 0) {
+          const event = buffer.slice(0, end);
+          buffer = buffer.slice(end + 2);
+          for (const line of event.split("\n")) {
+            if (!line.startsWith("data:")) continue;
+            const data = line.slice(5).trim();
+            if (data === "[DONE]") return;
+            let parsed: AgentEvent;
+            try {
+              parsed = JSON.parse(data);
+            } catch {
+              continue;
+            }
+            if (parsed.type === "error") {
+              throw new ApiError({ status: 502, code: "agent_error", message: String(parsed.message ?? "the run stopped") });
+            }
+            yield parsed;
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /** A run of yours: its status and answer, and what it is waiting on if it stopped to ask. */
+  get(runId: string): Promise<AgentRun> {
+    return this.http.request<AgentRun>({ path: `/ai/v1${seg("agent-runs", runId)}` });
+  }
+
+  /** Approve or decline what a run is waiting on: a decision per call id, and `approve` for any not named. */
+  decide(runId: string, options: { decisions?: Record<string, boolean>; approve?: boolean; background?: boolean } = {}): Promise<AgentRun> {
+    return this.http.request<AgentRun>({
+      method: "POST",
+      path: `/ai/v1${seg("agent-runs", runId, "decide")}`,
+      body: { decisions: options.decisions ?? {}, approve: options.approve, background: options.background ?? false },
+    });
+  }
+
+  /** Poll a background run until it is no longer running (a waiting run is returned too, so you can decide it). */
+  async wait(runId: string, options: { intervalMs?: number; timeoutMs?: number; signal?: AbortSignal | null } = {}): Promise<AgentRun> {
+    const interval = options.intervalMs ?? 1000;
+    const deadline = Date.now() + (options.timeoutMs ?? 5 * 60_000);
+    for (;;) {
+      const run = await this.get(runId);
+      if (run.status !== "running") return run;
+      if (options.signal?.aborted) throw options.signal.reason ?? new Error("aborted");
+      if (Date.now() >= deadline) throw new Error(`run ${runId} was still running after ${options.timeoutMs ?? 5 * 60_000} ms`);
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}
+
+export class KnowledgeClient {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Search by meaning and by words together. Documents kept private to someone else are left out. */
+  async search(name: string, query: string, options: { limit?: number; signal?: AbortSignal | null } = {}): Promise<KnowledgeHit[]> {
+    const body = await this.http.request<{ data: KnowledgeHit[] }>({
+      method: "POST",
+      path: `/ai/v1${seg("knowledge", name, "search")}`,
+      body: { query, limit: options.limit ?? 5 },
+      signal: options.signal ?? undefined,
+    });
+    return body.data;
+  }
+
+  /** Add text, or a web page to read (`url`). A signed-in user's documents are found only by them. Adding the same `source` again replaces it. */
+  addDocument(name: string, input: { text?: string; url?: string; title?: string; source?: string }): Promise<KnowledgeDocument> {
+    return this.http.request<KnowledgeDocument>({
+      method: "POST",
+      path: `/ai/v1${seg("knowledge", name, "documents")}`,
+      body: { title: input.title ?? "", source: input.source ?? "", text: input.text, url: input.url },
+    });
+  }
+
+  /** Add a file (PDF, Word, HTML or text). */
+  addFile(name: string, file: Blob, options: { title?: string; source?: string; filename?: string } = {}): Promise<KnowledgeDocument> {
+    const form = new FormData();
+    form.append("file", file, options.filename ?? (file as File).name ?? "document");
+    if (options.title) form.append("title", options.title);
+    if (options.source) form.append("source", options.source);
+    return this.http.request<KnowledgeDocument>({ method: "POST", path: `/ai/v1${seg("knowledge", name, "documents")}`, body: form });
+  }
+
+  /** Whether a document is ready to search, and why not if it failed. */
+  document(name: string, documentId: string): Promise<KnowledgeDocument> {
+    return this.http.request<KnowledgeDocument>({ path: `/ai/v1${seg("knowledge", name, "documents", documentId)}` });
+  }
+}

package/src/ai.ts

@@ -0,0 +1,164 @@
+/**
+ * The AI gateway: chat and embedding models your environment has connected, behind one OpenAI-compatible API.
+ *
+ * ```ts
+ * const answer = await pawabase.ai.chat("chat", "Summarise this ticket: …");
+ * for await (const piece of pawabase.ai.stream("chat", "Tell me a story")) process.stdout.write(piece);
+ * const vector = await pawabase.ai.embed("embed", "hello");
+ * ```
+ *
+ * Models are called by the name your environment gave them. Who may call each is the model's policy; servers (a secret key) always may.
+ */
+import { ApiError } from "./errors.js";
+import { AgentsClient, KnowledgeClient } from "./agents.js";
+import type { HttpClient } from "./http.js";
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant" | "tool" | "developer";
+  content: string | null;
+  tool_calls?: Array<{ id: string; type: "function"; function: { name: string; arguments: string } }>;
+  tool_call_id?: string;
+  name?: string;
+}
+
+export interface ChatOptions {
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  stop?: string | string[];
+  /** Functions the model may ask you to call (OpenAI's `tools` format). */
+  tools?: unknown[];
+  toolChoice?: unknown;
+  /** `{ type: "json_object" }` asks for JSON back, where the provider supports it. */
+  responseFormat?: { type: string; [key: string]: unknown };
+  /** Any other parameter, passed through as given. */
+  extra?: Record<string, unknown>;
+  signal?: AbortSignal | null;
+}
+
+export interface ChatCompletion {
+  id: string;
+  object: "chat.completion";
+  model: string;
+  choices: Array<{ index: number; message: ChatMessage; finish_reason: string | null }>;
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+}
+
+export interface AiModelInfo {
+  id: string;
+  kind: "chat" | "embedding";
+  description: string;
+  dimensions?: number;
+}
+
+function asMessages(input: string | ChatMessage[]): ChatMessage[] {
+  return typeof input === "string" ? [{ role: "user", content: input }] : input;
+}
+
+function bodyOf(model: string, input: string | ChatMessage[], options: ChatOptions): Record<string, unknown> {
+  return {
+    ...(options.extra ?? {}),
+    model,
+    messages: asMessages(input),
+    ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    ...(options.topP !== undefined ? { top_p: options.topP } : {}),
+    ...(options.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {}),
+    ...(options.stop !== undefined ? { stop: options.stop } : {}),
+    ...(options.tools !== undefined ? { tools: options.tools } : {}),
+    ...(options.toolChoice !== undefined ? { tool_choice: options.toolChoice } : {}),
+    ...(options.responseFormat !== undefined ? { response_format: options.responseFormat } : {}),
+  };
+}
+
+export class AiClient {
+  /** Agents the caller may run: `run`, `stream`, `get`, `decide`, `wait`. */
+  readonly agents: AgentsClient;
+  /** Knowledge bases the caller may search or add documents to. */
+  readonly knowledge: KnowledgeClient;
+
+  constructor(private readonly http: HttpClient) {
+    this.agents = new AgentsClient(http);
+    this.knowledge = new KnowledgeClient(http);
+  }
+
+  /** The models the caller may use. */
+  async models(): Promise<AiModelInfo[]> {
+    const body = await this.http.request<{ data: AiModelInfo[] }>({ path: "/ai/v1/models" });
+    return body.data;
+  }
+
+  /** The full chat completion, in OpenAI's shape (tool calls, usage and all). */
+  complete(model: string, input: string | ChatMessage[], options: ChatOptions = {}): Promise<ChatCompletion> {
+    return this.http.request<ChatCompletion>({
+      method: "POST",
+      path: "/ai/v1/chat/completions",
+      body: bodyOf(model, input, options),
+      signal: options.signal ?? undefined,
+    });
+  }
+
+  /** Ask a model and get its answer as text. */
+  async chat(model: string, input: string | ChatMessage[], options: ChatOptions = {}): Promise<string> {
+    const completion = await this.complete(model, input, options);
+    return completion.choices[0]?.message?.content ?? "";
+  }
+
+  /** The answer as it is written: an async iterator of text pieces. */
+  async *stream(model: string, input: string | ChatMessage[], options: ChatOptions = {}): AsyncGenerator<string, void, void> {
+    const stream = await this.http.request<ReadableStream<Uint8Array> | null>({
+      method: "POST",
+      path: "/ai/v1/chat/completions",
+      body: { ...bodyOf(model, input, options), stream: true },
+      parse: "stream",
+      signal: options.signal ?? undefined,
+    });
+    if (!stream) return;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let end: number;
+        while ((end = buffer.indexOf("\n\n")) >= 0) {
+          const event = buffer.slice(0, end);
+          buffer = buffer.slice(end + 2);
+          for (const line of event.split("\n")) {
+            if (!line.startsWith("data:")) continue;
+            const data = line.slice(5).trim();
+            if (data === "[DONE]") return;
+            let parsed: { choices?: Array<{ delta?: { content?: string } }>; error?: { message?: string; code?: string } };
+            try {
+              parsed = JSON.parse(data);
+            } catch {
+              continue;
+            }
+            if (parsed.error) {
+              throw new ApiError({ status: 502, code: parsed.error.code ?? "provider_error", message: parsed.error.message ?? "the model stopped answering" });
+            }
+            const piece = parsed.choices?.[0]?.delta?.content;
+            if (piece) yield piece;
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /** The vector for one text, or one vector per text when given a list. */
+  embed(model: string, input: string, options?: { signal?: AbortSignal | null }): Promise<number[]>;
+  embed(model: string, input: string[], options?: { signal?: AbortSignal | null }): Promise<number[][]>;
+  async embed(model: string, input: string | string[], options: { signal?: AbortSignal | null } = {}): Promise<number[] | number[][]> {
+    const body = await this.http.request<{ data: Array<{ index: number; embedding: number[] }> }>({
+      method: "POST",
+      path: "/ai/v1/embeddings",
+      body: { model, input },
+      signal: options.signal ?? undefined,
+    });
+    const vectors = [...body.data].sort((a, b) => a.index - b.index).map((row) => row.embedding);
+    return typeof input === "string" ? (vectors[0] ?? []) : vectors;
+  }
+}

package/src/auth.ts

@@ -149,6 +149,8 @@ export class AuthClient implements TokenProvider {
   readonly devices: AuthDevices;
   /** Keys a user makes for themselves to call the API as themselves. */
   readonly apiKeys: AuthApiKeys;
+  /** Sign a machine (a service or an AI agent) in with its client id and key. */
+  readonly machine: AuthMachine;
   /** Passkeys (WebAuthn): register one, sign in with one. */
   readonly passkeys: AuthPasskeys;
 
@@ -167,6 +169,7 @@ export class AuthClient implements TokenProvider {
     this.orgs = new AuthOrgs(http);
     this.devices = new AuthDevices(http);
     this.apiKeys = new AuthApiKeys(http);
+    this.machine = new AuthMachine(http);
     this.passkeys = new AuthPasskeys(http, (wire) => this.adopt(wire));
     this.ready = this.initialize();
     this.ready.catch(() => undefined);
@@ -747,6 +750,33 @@ export class AuthClient implements TokenProvider {
     return user;
   }
 
+  /**
+   * Set the signed-in user's picture from an image (PNG, JPEG, WebP or GIF). It is stored in the environment's public avatar
+   * bucket and `avatar_url` points at it; the previous picture is removed. Resolves the updated user.
+   */
+  async setAvatar(image: Blob | ArrayBuffer | ArrayBufferView, options: { contentType?: string } = {}): Promise<User> {
+    await this.ready;
+    const declared = options.contentType ?? (typeof Blob !== "undefined" && image instanceof Blob && image.type ? image.type : "");
+    await this.http.request({
+      method: "PUT",
+      path: "/auth/v1/user/avatar",
+      body: image,
+      headers: { "content-type": declared || "application/octet-stream" },
+    });
+    const user = await this.getUser();
+    this.emit("USER_UPDATED");
+    return user;
+  }
+
+  /** Remove the signed-in user's picture. */
+  async removeAvatar(): Promise<User> {
+    await this.ready;
+    await this.http.request({ method: "DELETE", path: "/auth/v1/user/avatar" });
+    const user = await this.getUser();
+    this.emit("USER_UPDATED");
+    return user;
+  }
+
   /** Send the confirmation email again. Always resolves the same way. */
   async resendVerification(input: { email: string; redirectTo?: string }): Promise<void> {
     await this.http.request({
@@ -1080,6 +1110,46 @@ class AuthDevices {
   }
 }
 
+/** What a machine gets for its credentials. */
+export interface MachineToken {
+  accessToken: string;
+  tokenType: "Bearer";
+  /** Seconds the token lives. */
+  expiresIn: number;
+  /** The permissions the token carries, space-separated. */
+  scope: string;
+  machine: { id: string; name: string; kind: "service" | "agent" };
+}
+
+class AuthMachine {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * The OAuth `client_credentials` grant: exchange a machine's id and one of its keys (`pbm_…`) for a short-lived access token.
+   * `scope` (space-separated permissions) asks for fewer permissions than the key allows; it never grants more. Keeps no session.
+   */
+  async token(input: { clientId: string; clientSecret: string; scope?: string }): Promise<MachineToken> {
+    const wire = await this.http.request<{
+      access_token: string;
+      token_type: "Bearer";
+      expires_in: number;
+      scope: string;
+      machine: MachineToken["machine"];
+    }>({
+      method: "POST",
+      path: "/auth/v1/token",
+      body: {
+        grant_type: "client_credentials",
+        client_id: input.clientId,
+        client_secret: input.clientSecret,
+        ...(input.scope ? { scope: input.scope } : {}),
+      },
+      auth: "none",
+    });
+    return { accessToken: wire.access_token, tokenType: wire.token_type, expiresIn: wire.expires_in, scope: wire.scope, machine: wire.machine };
+  }
+}
+
 class AuthApiKeys {
   constructor(private readonly http: HttpClient) {}
 

package/src/client.ts

@@ -1,8 +1,9 @@
+import { AiClient } from "./ai.js";
 import { AuthClient, type AuthOptions } from "./auth.js";
 import { ResourceClient, type AnyRow, type ResourceTypes } from "./data.js";
 import { ConfigError } from "./errors.js";
 import { StorageClient } from "./files.js";
-import { FlowsClient, FunctionsClient, RoutesClient } from "./functions.js";
+import { FlowsClient, RoutesClient } from "./functions.js";
 import { HttpClient, type FetchLike, type Hooks, type RetryOptions, type TokenProvider } from "./http.js";
 import { RealtimeClient, type RealtimeOptions } from "./realtime.js";
 import { MemoryStorage } from "./session-store.js";
@@ -72,8 +73,8 @@ export class PawabaseClient<DB extends DatabaseShape = Untyped> {
   readonly auth: AuthClient;
   /** Storage buckets. */
   readonly storage: StorageClient;
-  /** Functions: `/functions/v1`. */
-  readonly functions: FunctionsClient;
+  /** The AI gateway: chat and embedding models. */
+  readonly ai: AiClient;
   /** Flows with a pathless HTTP trigger: `/flows/v1`. */
   readonly flows: FlowsClient;
   /** Custom routes: `/rest/v1/<path>`. */
@@ -126,7 +127,7 @@ export class PawabaseClient<DB extends DatabaseShape = Untyped> {
     });
     config.tokens = stateless ? staticTokens(options.accessToken as NonNullable<ClientOptions["accessToken"]>) : this.auth;
     this.storage = new StorageClient(this.http);
-    this.functions = new FunctionsClient(this.http);
+    this.ai = new AiClient(this.http);
     this.flows = new FlowsClient(this.http);
     this.routes = new RoutesClient(this.http);
     this.realtime = new RealtimeClient(this.http, stateless ? null : this.auth, {
@@ -156,6 +157,32 @@ export class PawabaseClient<DB extends DatabaseShape = Untyped> {
     return new PawabaseClient<DB>({ ...this.options, accessToken });
   }
 
+  /**
+   * A client that acts as a machine (a service or an AI agent). It signs in with the machine's id and key, keeps the token until shortly
+   * before it expires, and signs in again when it must. It keeps no user session.
+   *
+   * ```ts
+   * const agent = pawabase.asMachine({ clientId: process.env.PB_MACHINE_ID!, clientSecret: process.env.PB_MACHINE_KEY! });
+   * await agent.from("orders").eq("status", "open");
+   * ```
+   */
+  asMachine(input: { clientId: string; clientSecret: string; scope?: string }): PawabaseClient<DB> {
+    let cached: { token: string; until: number } | null = null;
+    let pending: Promise<string> | null = null;
+    const fetchToken = async (): Promise<string> => {
+      const got = await this.auth.machine.token(input);
+      cached = { token: got.accessToken, until: Date.now() + Math.max(got.expiresIn - 30, 1) * 1000 };
+      return got.accessToken;
+    };
+    return this.asUser(async () => {
+      if (cached && cached.until > Date.now()) return cached.token;
+      pending ??= fetchToken().finally(() => {
+        pending = null;
+      });
+      return pending;
+    });
+  }
+
   /**
    * A raw request to any path on the gateway, with the key and the user's token attached,
    * the retry policy and the typed errors applied. For endpoints the client has no method for.

package/src/data.ts

@@ -47,6 +47,8 @@ interface State {
   expand: string[];
   page: number;
   perPage: number | null;
+  /** False asks for every match in one response. */
+  paginate: boolean;
   /** An `in ()` with no values matches nothing: answered locally. */
   empty: boolean;
 }
@@ -121,6 +123,7 @@ export class QueryBuilder<Row = AnyRow> implements PromiseLike<Page<Row>> {
       expand: [],
       page: 1,
       perPage: null,
+      paginate: true,
       empty: false,
     },
     private readonly options: QueryOptions = {},
@@ -248,6 +251,14 @@ export class QueryBuilder<Row = AnyRow> implements PromiseLike<Page<Row>> {
     return this.with({ perPage });
   }
 
+  /**
+   * Turn paging off with `paginate(false)`: the response holds every match (up to 5000; the server refuses more, so narrow
+   * with filters). `page` and `per_page` come back `null`.
+   */
+  paginate(paginate = true): QueryBuilder<Row> {
+    return this.with({ paginate });
+  }
+
   /** Alias of {@link perPage}. */
   limit(count: number): QueryBuilder<Row> {
     return this.perPage(count);
@@ -266,15 +277,20 @@ export class QueryBuilder<Row = AnyRow> implements PromiseLike<Page<Row>> {
     if (this.state.sort.length) params["sort"] = this.state.sort.join(",");
     if (this.state.select) params["select"] = this.state.select.join(",");
     if (this.state.expand.length) params["expand"] = [...new Set(this.state.expand)].join(",");
-    if (this.state.page !== 1) params["page"] = this.state.page;
-    if (this.state.perPage !== null) params["per_page"] = this.state.perPage;
+    if (!this.state.paginate) params["paginate"] = "false";
+    else {
+      if (this.state.page !== 1) params["page"] = this.state.page;
+      if (this.state.perPage !== null) params["per_page"] = this.state.perPage;
+    }
     return params;
   }
 
   /** Run the query and return one page. `await`ing the builder does the same. */
   async execute(): Promise<Page<Row>> {
     if (this.state.empty) {
-      return { data: [], page: this.state.page, per_page: this.state.perPage ?? 20, total: 0 };
+      return this.state.paginate
+        ? { data: [], page: this.state.page, per_page: this.state.perPage ?? 20, total: 0 }
+        : { data: [], page: null, per_page: null, total: 0 };
     }
     return this.http.request<Page<Row>>({
       path: `/rest/v1/${encodePath(this.resource)}`,
@@ -341,13 +357,13 @@ export class QueryBuilder<Row = AnyRow> implements PromiseLike<Page<Row>> {
       seen += page.data.length;
       if (options.maxRecords !== undefined && seen >= options.maxRecords) return;
       if (page.total !== null) {
-        if (page.page * page.per_page >= page.total) return;
+        if ((page.page ?? 1) * (page.per_page ?? 0) >= page.total) return;
       } else {
         // Unknown total: a per-row policy filters after the page is read, so a short page proves nothing.
         empties = page.data.length === 0 ? empties + 1 : 0;
         if (empties >= stopAfterEmpty) return;
       }
-      query = query.page(page.page + 1);
+      query = query.page((page.page ?? 1) + 1);
     }
   }
 
@@ -392,6 +408,34 @@ export class ResourceClient<
     return id === undefined ? base : `${base}/${encodeURIComponent(String(id))}`;
   }
 
+  /**
+   * Records closest in meaning, closest first, each with a `distance` (smaller is closer). Give `text` (turned into a vector by the
+   * field's embedding model) or a `vector`. Vector fields are left out of the records unless you ask for them.
+   */
+  async similar(input: {
+    text?: string;
+    vector?: number[];
+    field?: string;
+    metric?: "cosine" | "l2" | "ip";
+    limit?: number;
+    maxDistance?: number;
+    signal?: AbortSignal | null;
+  }): Promise<{ data: Array<Row & { distance: number }>; metric: string; count: number }> {
+    return this.http.request({
+      method: "POST",
+      path: `${this.path()}/similar`,
+      body: {
+        ...(input.text !== undefined ? { text: input.text } : {}),
+        ...(input.vector !== undefined ? { vector: input.vector } : {}),
+        ...(input.field ? { field: input.field } : {}),
+        metric: input.metric ?? "cosine",
+        limit: input.limit ?? 10,
+        ...(input.maxDistance !== undefined ? { max_distance: input.maxDistance } : {}),
+      },
+      signal: input.signal ?? undefined,
+    });
+  }
+
   /** Start a query. Every filter and shape method below is a shortcut for `query().…`. */
   query(): QueryBuilder<Row> {
     return new QueryBuilder<Row>(this.http, this.name);
@@ -405,6 +449,8 @@ export class ResourceClient<
     expand?: string[];
     page?: number;
     perPage?: number;
+    /** `false` returns every match in one response (up to 5000). */
+    paginate?: boolean;
     signal?: AbortSignal | null;
   } = {}): Promise<Page<Row>> {
     let query = this.query();
@@ -417,6 +463,7 @@ export class ResourceClient<
     if (params.expand) query = query.expand(...params.expand);
     if (params.page) query = query.page(params.page);
     if (params.perPage) query = query.perPage(params.perPage);
+    if (params.paginate === false) query = query.paginate(false);
     if (params.signal) query = query.withOptions({ signal: params.signal });
     return query.execute();
   }

package/src/errors.ts

@@ -3,7 +3,7 @@
  *
  * Pawabase answers errors in several shapes: a bare string (most `4xx`), a bare
  * array of validation issues (`422`), an `{error, message, details}` object
- * (functions, flows, the gateway) and Akountz's own `{detail}` bodies. The
+ * (flows, the gateway) and Akountz's own `{detail}` bodies. The
  * client normalises all of them into one class hierarchy, so application code
  * checks `error.status`, `error.code` or `instanceof` and never parses a body.
  */
@@ -277,6 +277,11 @@ export function errorFromResponse(input: {
     else if (typeof body["code"] === "string") code = body["code"] as string;
     if (typeof body["message"] === "string") message = body["message"] as string;
     else if (typeof detail === "string") message = detail;
+    // OpenAI-style bodies, which the AI gateway answers with: { error: { message, type, code } }.
+    if (isRecord(named)) {
+      if (!message && typeof named["message"] === "string") message = named["message"] as string;
+      if (typeof named["code"] === "string") code = named["code"] as string;
+    }
     if (Array.isArray(detail)) {
       issues = toIssues(detail);
       message ||= summarise(issues);