@pawabase/client 0.1.3 → 0.1.4

package/src/ai.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 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 {
+  constructor(private readonly http: HttpClient) {}
+
+  /** 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);

package/src/functions.ts

@@ -24,55 +24,6 @@ function pass(options: CallOptions): {
   };
 }
 
-export interface FetchOptions extends CallOptions {
-  method?: string;
-  query?: Record<string, QueryValue | QueryValue[]>;
-  /** An object is sent as JSON; strings, `Blob`, `FormData`, buffers and streams as they are. */
-  body?: unknown;
-  /** Run the function deployed on this branch (`x-pawabase-branch`). */
-  branch?: string;
-}
-
-/** Functions you wrote in your project's code, invoked at `/functions/v1/<name>`. */
-export class FunctionsClient {
-  constructor(private readonly http: HttpClient) {}
-
-  /**
-   * Call a function and return what it returned. The API key needs the
-   * `functions:invoke` scope (an unrestricted key has it).
-   */
-  async invoke<T = unknown>(name: string, input?: unknown, options: CallOptions = {}): Promise<T> {
-    const body = await this.http.request<{ data: T } | undefined>({
-      method: "POST",
-      path: `/functions/v1/${encodePath(name)}`,
-      body: input === undefined ? undefined : input,
-      ...pass(options),
-    });
-    return (body as { data: T } | undefined)?.data as T;
-  }
-
-  /**
-   * Call an HTTP function (`functions/<name>/index.ts`) with any method and path, and get its `Response` as it is — status, headers
-   * and a streaming body. An error status is returned, not thrown; the API key and the signed-in user's token are sent as for any call.
-   *
-   * ```ts
-   * const res = await pawabase.functions.fetch("orders", "/42/items", { method: "POST", body: { sku: "A1" } });
-   * if (res.ok) console.log(await res.json());
-   * ```
-   */
-  fetch(name: string, path = "/", options: FetchOptions = {}): Promise<Response> {
-    const rest = path === "/" || path === "" ? "" : path.startsWith("/") ? path : `/${path}`;
-    return this.http.send({
-      method: options.method ?? (options.body === undefined ? "GET" : "POST"),
-      path: `/functions/v1/${encodePath(name)}${rest}`,
-      ...(options.query ? { query: options.query } : {}),
-      ...(options.body !== undefined ? { body: options.body } : {}),
-      ...pass({ ...options, headers: { ...(options.branch ? { "x-pawabase-branch": options.branch } : {}), ...options.headers } }),
-      throwOnError: false,
-    });
-  }
-}
-
 /**
  * Flows with an HTTP trigger that has no path, invoked at `/flows/v1/<name>`.
  * (Flows bound to a path are reached as routes, see {@link RoutesClient}.)

package/src/index.ts

@@ -1,12 +1,15 @@
 export { PawabaseClient, createClient } from "./client.js";
 export type { ClientOptions, DatabaseShape } from "./client.js";
 
+export { AiClient } from "./ai.js";
+export type { AiModelInfo, ChatCompletion, ChatMessage, ChatOptions } from "./ai.js";
 export { AuthClient } from "./auth.js";
 export type {
   AuthChangeEvent,
   AuthListener,
   AuthOptions,
   IssuedToken,
+  MachineToken,
   Passkey,
   PasskeyChallenge,
   SignInResult,
@@ -29,7 +32,7 @@ export type {
   ResourceTypes,
 } from "./data.js";
 
-export { FlowsClient, FunctionsClient, RoutesClient } from "./functions.js";
+export { FlowsClient, RoutesClient } from "./functions.js";
 export type { CallOptions, RouteOptions } from "./functions.js";
 
 export { BucketClient, StorageClient } from "./files.js";

package/src/manage/access.ts

@@ -15,8 +15,8 @@ export class Keys extends Service {
   }
 
   /**
-   * Make a key; the key itself is in the answer once. `scopes` limit what it may do (`resource:read`, `functions:invoke`…),
-   * `allowedIps` and `allowedRoutes` (`"GET /rest/v1/orders"`, `"/functions/v1/*"`) limit where and what it may call.
+   * Make a key; the key itself is in the answer once. `scopes` limit what it may do (`resource:read`, `routes:invoke`…),
+   * `allowedIps` and `allowedRoutes` (`"GET /rest/v1/orders"`, `"/flows/v1/*"`) limit where and what it may call.
    */
   create(name: string, options: { role?: "publishable" | "secret"; scopes?: string[]; expiresAt?: When; allowedIps?: string[]; allowedRoutes?: string[] } = {}): Promise<Api> {
     return this.post("/keys", {
@@ -39,7 +39,7 @@ export class Keys extends Service {
   }
 }
 
-/** Secrets functions and flows read (`ctx.runtime.secret(name)`). Values are never returned. */
+/** Secrets flows read (`ctx.runtime.secret(name)`). Values are never returned. */
 export class Secrets extends Service {
   list(): Promise<Api> {
     return this.get("/secrets");