@pawabase/client 0.1.4 → 0.3.0

package/src/manage/agents.ts

@@ -0,0 +1,98 @@
+import { Definitions, Service, seg, type Api, type Body, type Query } from "./base.js";
+
+/**
+ * Agents: a model with instructions, tools and knowledge, run on the server with approvals, limits and threads.
+ *
+ * ```ts
+ * await m.agents.create({ name: "support", model: "chat", instructions: "Answer from the docs.", knowledge: ["docs"] });
+ * const run = await m.agents.run("support", "How do I reset a password?");
+ * ```
+ */
+export class Agents extends Definitions {
+  protected override readonly kind = "agents";
+
+  /** Run an agent as the studio would. `thread` carries a conversation on; `background` returns before it finishes. */
+  run(name: string, input: string, options: { thread?: string; background?: boolean } = {}): Promise<Api> {
+    return this.post(seg(this.kind, name, "runs"), { input, thread: options.thread, background: options.background ?? false });
+  }
+}
+
+/** Agent runs: what each did, step by step, and the ones waiting for someone to approve a tool call. */
+export class AgentRuns extends Service {
+  /** Newest first. Filter by `agent`, `status` or `thread`. */
+  list(options: { agent?: string; status?: string; thread?: string; limit?: number; offset?: number } = {}): Promise<Api> {
+    return this.get("/agent-runs", options as Query);
+  }
+
+  getOne(runId: string): Promise<Api> {
+    return this.get(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<Api> {
+    return this.post(seg("agent-runs", runId, "decide"), { decisions: options.decisions ?? {}, approve: options.approve, background: options.background ?? false });
+  }
+
+  remove(runId: string): Promise<Api> {
+    return this.del(seg("agent-runs", runId));
+  }
+
+  /** The tools an agent can be given, by kind. */
+  tools(): Promise<Api> {
+    return this.get("/agent-tools");
+  }
+}
+
+/** Knowledge bases: documents split and embedded so agents can search them by meaning and by words. */
+export class KnowledgeBases extends Definitions {
+  protected override readonly kind = "knowledge-bases";
+
+  documents(name: string, options: { limit?: number; offset?: number } = {}): Promise<Api> {
+    return this.get(seg(this.kind, name, "documents"), options);
+  }
+
+  /** Add text, or a web page to read (`url`). Adding the same `source` again replaces it. */
+  addDocument(name: string, input: { text?: string; url?: string; title?: string; source?: string }): Promise<Api> {
+    return this.post(seg(this.kind, name, "documents"), { 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<Api> {
+    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.post(seg(this.kind, name, "documents"), form);
+  }
+
+  removeDocument(name: string, documentId: string): Promise<Api> {
+    return this.del(seg(this.kind, name, "documents", documentId));
+  }
+
+  /** Split and embed a document again, for one that failed or after changing the base's chunk size. */
+  reindexDocument(name: string, documentId: string): Promise<Api> {
+    return this.post(seg(this.kind, name, "documents", documentId, "reindex"));
+  }
+
+  /** What an agent would find. */
+  search(name: string, query: string, options: { limit?: number } = {}): Promise<Api> {
+    return this.post(seg(this.kind, name, "search"), { query, limit: options.limit ?? 5 });
+  }
+
+  /** Bring in pages from a Notion connection; pages unchanged since last time are skipped. */
+  sync(name: string, connection: string): Promise<Api> {
+    return this.post(seg(this.kind, name, "sync"), { connection });
+  }
+}
+
+/** Connections: stored access to outside services (MCP servers, Notion, web search) that agents use as tools. The secret is sealed on arrival. */
+export class Connections extends Definitions {
+  protected override readonly kind = "connections";
+
+  /** Call the service with the stored key and say what was found, or why it could not be reached. */
+  test(name: string): Promise<Api> {
+    return this.post(seg(this.kind, name, "test"));
+  }
+}
+
+export type { Body };

package/src/manage/base.ts

@@ -55,29 +55,29 @@ export class Service {
 
 /**
  * A kind of definition an environment holds (`flows`, `policies`, `webhooks`…): list, get, create, replace, remove.
- * Pass `branch` to work on a feature branch's draft instead of the live environment. A definition is addressed by its name
+ * A definition is addressed by its name
  * (inbound hooks: their slug).
  */
 export class Definitions extends Service {
   protected readonly kind: string = "";
 
-  list(options: { branch?: string } = {}): Promise<Api> {
-    return this.get(seg(this.kind), { branch: options.branch });
+  list(): Promise<Api> {
+    return this.get(seg(this.kind));
   }
 
-  getOne(key: string, options: { branch?: string } = {}): Promise<Api> {
-    return this.get(seg(this.kind, key), { branch: options.branch });
+  getOne(key: string): Promise<Api> {
+    return this.get(seg(this.kind, key));
   }
 
-  create(body: Body, options: { branch?: string } = {}): Promise<Api> {
-    return this.post(seg(this.kind), body, { branch: options.branch });
+  create(body: Body): Promise<Api> {
+    return this.post(seg(this.kind), body);
   }
 
-  replace(key: string, body: Body, options: { branch?: string } = {}): Promise<Api> {
-    return this.put(seg(this.kind, key), body, { branch: options.branch });
+  replace(key: string, body: Body): Promise<Api> {
+    return this.put(seg(this.kind, key), body);
   }
 
-  remove(key: string, options: { branch?: string } = {}): Promise<Api> {
-    return this.del(seg(this.kind, key), { branch: options.branch });
+  remove(key: string): Promise<Api> {
+    return this.del(seg(this.kind, key));
   }
 }

package/src/manage/data.ts

@@ -110,11 +110,6 @@ export class Schemas extends Definitions {
   protected override readonly kind = "schemas";
 }
 
-/** Transformers that reshape a field's value on the way out (hide, mask, format). */
-export class Transformers extends Definitions {
-  protected override readonly kind = "transformers";
-}
-
 /** Custom HTTP routes under `/rest` that run a flow. */
 export class Routes extends Definitions {
   protected override readonly kind = "routes";
@@ -135,25 +130,25 @@ export class Database extends Service {
     return this.get(seg("database", "tables", table, "rows"), { limit: options.limit, offset: options.offset, sort: options.sort, ...options.filters });
   }
 
-  /** Run one statement. A write needs `allowWrite`; it is audited and clears the environment's caches. */
-  query(sql: string, params: unknown[] = [], options: { allowWrite?: boolean } = {}): Promise<Api> {
-    return this.post("/database/query", { sql, params, allow_write: options.allowWrite ?? false });
+  /** Saved queries: the SQL console's bookmarks. */
+  savedQueries(): Promise<Api> {
+    return this.get("/database/queries");
   }
-}
 
-/** The runtime capabilities a function sees, called remotely (what `pawabase emulate` uses). */
-export class Runtime extends Service {
-  call(method: string, args: unknown[] = [], kwargs: Body = {}, options: { asUser?: Body; branch?: string } = {}): Promise<Api> {
-    return this.post("/runtime/call", { method, args, kwargs, as_user: options.asUser ?? null, branch: options.branch ?? null });
+  saveQuery(input: { name: string; sql: string; description?: string }): Promise<Api> {
+    return this.post("/database/queries", { name: input.name, sql: input.sql, description: input.description ?? "" });
   }
 
-  /** `fetch`, `insert`, `execute`, `begin`, `commit`…, optionally inside a transaction (`tx`). */
-  sql(op: string, fields: Body = {}): Promise<Api> {
-    return this.post("/runtime/db", { op, ...fields });
+  updateQuery(queryId: string, input: { name: string; sql: string; description?: string }): Promise<Api> {
+    return this.put(seg("database", "queries", queryId), { name: input.name, sql: input.sql, description: input.description ?? "" });
   }
 
-  /** Who a user access token belongs to. */
-  identify(token: string | null): Promise<Api> {
-    return this.post("/runtime/identify", { token });
+  deleteQuery(queryId: string): Promise<Api> {
+    return this.del(seg("database", "queries", queryId));
+  }
+
+  /** Run one statement. A write needs `allowWrite`; it is audited and clears the environment's caches. */
+  query(sql: string, params: unknown[] = [], options: { allowWrite?: boolean } = {}): Promise<Api> {
+    return this.post("/database/query", { sql, params, allow_write: options.allowWrite ?? false });
   }
 }

package/src/manage/files.ts

@@ -64,12 +64,23 @@ export class Buckets extends Definitions {
   revokeShare(bucket: string, shareId: string): Promise<Api> {
     return this.del(seg(this.kind, bucket, "shares", shareId));
   }
+
+  /** Make an empty folder (`prefix` like `reports/2026`). */
+  createFolder(bucket: string, prefix: string): Promise<Api> {
+    return this.post(seg(this.kind, bucket, "folders"), { prefix });
+  }
+
+  /** Remove a folder; it must be empty. */
+  deleteFolder(bucket: string, prefix: string): Promise<Api> {
+    return this.del(`${seg(this.kind, bucket, "folders")}/${prefix.split("/").filter(Boolean).map(encodeURIComponent).join("/")}`);
+  }
 }
 
 /** The environment's response cache. */
 export class Cache extends Service {
+  /** The project's cache statistics (not scoped to one environment). */
   stats(): Promise<Api> {
-    return this.get("/cache");
+    return this.project("GET", "/cache");
   }
 
   /** Drop cached responses by tag (`resource:posts`) or for whole resources. */

package/src/manage/index.ts

@@ -14,12 +14,13 @@
 import type { PawabaseClient } from "../client.js";
 import { ConfigError } from "../errors.js";
 import { isSecretKey } from "../util.js";
-import { Domains, Firewall, Keys, Secrets } from "./access.js";
+import { Domains, Keys, Secrets } from "./access.js";
+import { AgentRuns, Agents, Connections, KnowledgeBases } from "./agents.js";
 import { Ai } from "./ai.js";
 import { Events, Flows, InboundHooks, Jobs, Schedules, Subscriptions, Webhooks } from "./automation.js";
-import { Database, Policies, Resources, Routes, Runtime, Schema, Schemas, Transformers } from "./data.js";
+import { Database, Policies, Resources, Routes, Schema, Schemas } from "./data.js";
 import { Buckets, Cache } from "./files.js";
-import { Backups, Environments, Releases } from "./lifecycle.js";
+import { Backups, Environments, Versions } from "./lifecycle.js";
 import { Mail, MailTemplates } from "./mail.js";
 import { Alarms, Health, Observability, StatusPage } from "./observe.js";
 import { Dashboards, RealtimeChannels } from "./realtime.js";
@@ -30,10 +31,8 @@ export class Manage {
   readonly schema: Schema;
   readonly policies: Policies;
   readonly schemas: Schemas;
-  readonly transformers: Transformers;
   readonly routes: Routes;
   readonly database: Database;
-  readonly runtime: Runtime;
   // automation
   readonly flows: Flows;
   readonly schedules: Schedules;
@@ -54,7 +53,6 @@ export class Manage {
   readonly keys: Keys;
   readonly secrets: Secrets;
   readonly domains: Domains;
-  readonly firewall: Firewall;
   // observe
   readonly observability: Observability;
   readonly alarms: Alarms;
@@ -62,9 +60,13 @@ export class Manage {
   readonly health: Health;
   // ai
   readonly ai: Ai;
+  readonly agents: Agents;
+  readonly agentRuns: AgentRuns;
+  readonly knowledgeBases: KnowledgeBases;
+  readonly connections: Connections;
   // lifecycle
   readonly environments: Environments;
-  readonly releases: Releases;
+  readonly versions: Versions;
   readonly backups: Backups;
 
   constructor(
@@ -76,10 +78,8 @@ export class Manage {
     this.schema = new Schema(http, environment);
     this.policies = new Policies(http, environment);
     this.schemas = new Schemas(http, environment);
-    this.transformers = new Transformers(http, environment);
     this.routes = new Routes(http, environment);
     this.database = new Database(http, environment);
-    this.runtime = new Runtime(http, environment);
     this.flows = new Flows(http, environment);
     this.schedules = new Schedules(http, environment);
     this.subscriptions = new Subscriptions(http, environment);
@@ -96,14 +96,17 @@ export class Manage {
     this.keys = new Keys(http, environment);
     this.secrets = new Secrets(http, environment);
     this.domains = new Domains(http, environment);
-    this.firewall = new Firewall(http, environment);
     this.observability = new Observability(http, environment);
     this.alarms = new Alarms(http, environment);
     this.statusPage = new StatusPage(http, environment);
     this.health = new Health(http, environment);
     this.ai = new Ai(http, environment);
+    this.agents = new Agents(http, environment);
+    this.agentRuns = new AgentRuns(http, environment);
+    this.knowledgeBases = new KnowledgeBases(http, environment);
+    this.connections = new Connections(http, environment);
     this.environments = new Environments(http, environment);
-    this.releases = new Releases(http, environment);
+    this.versions = new Versions(http, environment);
     this.backups = new Backups(http, environment);
   }
 

package/src/manage/lifecycle.ts

@@ -1,8 +1,5 @@
 import { Service, seg, type Api, type Body } from "./base.js";
 
-type When = Date | string;
-const iso = (value?: When): string | undefined => (value instanceof Date ? value.toISOString() : value);
-
 /** The project's environments (`development`, `production`, previews…). Most calls here are not scoped to the client's environment. */
 export class Environments extends Service {
   list(): Promise<Api> {
@@ -45,9 +42,9 @@ export class Environments extends Service {
     return this.del(seg("previews", preview));
   }
 
-  /** Copy this environment's definitions (never secrets or keys) to `to`. `include` limits the kinds (`flows`, `policies`, `resources`…). */
-  promote(to: string, options: { include?: string[] } = {}): Promise<Api> {
-    return this.post("/promote", { to, include: options.include });
+  /** Copy this environment's definitions (never secrets or keys) to `to`. `include` limits the kinds; `dryRun` only reports what would change. */
+  promote(to: string, options: { include?: string[]; dryRun?: boolean } = {}): Promise<Api> {
+    return this.post("/promote", { to, include: options.include, dry_run: options.dryRun ?? false });
   }
 
   /** Export definitions, roles and settings as a document another project can apply. */
@@ -66,70 +63,29 @@ export class Environments extends Service {
   }
 }
 
-/** Feature branches of the definitions, immutable revisions, API versions and releases. */
-export class Releases extends Service {
-  branches(): Promise<Api> {
-    return this.get("/branches");
-  }
-
-  createBranch(name: string, options: { fromBranch?: string; fromRevision?: string; protected?: boolean } = {}): Promise<Api> {
-    return this.post("/branches", { name, from_branch: options.fromBranch, from_revision: options.fromRevision, protected: options.protected ?? false });
-  }
-
-  /** The branch's definitions as they stand now. */
-  draft(branch: string): Promise<Api> {
-    return this.get(seg("branches", branch, "draft"));
-  }
-
-  merge(branch: string, options: { target?: string; force?: boolean } = {}): Promise<Api> {
-    return this.post(seg("branches", branch, "merge"), { target: options.target ?? "main", force: options.force ?? false });
-  }
-
-  revisions(): Promise<Api> {
-    return this.get("/revisions");
-  }
-
-  revision(revisionId: string): Promise<Api> {
-    return this.get(seg("revisions", revisionId));
-  }
-
-  /** Freeze the branch's draft as a revision. */
-  commit(branch: string, message = ""): Promise<Api> {
-    return this.post(seg("branches", branch, "revisions"), { message });
-  }
-
-  apiVersions(): Promise<Api> {
-    return this.get("/api-versions");
-  }
-
-  createApiVersion(name: string, options: { isDefault?: boolean } = {}): Promise<Api> {
-    return this.post("/api-versions", { name, is_default: options.isDefault ?? false });
-  }
-
-  /** `status`: draft, active, deprecated, sunset, disabled. */
-  updateApiVersion(name: string, changes: { status?: string; isDefault?: boolean; sunsetAt?: When }): Promise<Api> {
-    return this.patch(seg("api-versions", name), { status: changes.status, is_default: changes.isDefault, sunset_at: iso(changes.sunsetAt) });
-  }
-
-  rollbackApiVersion(name: string): Promise<Api> {
-    return this.post(seg("api-versions", name, "rollback"));
-  }
-
-  releases(): Promise<Api> {
-    return this.get("/releases");
+/**
+ * API versions served side by side. `v1` is always the live API; releasing another environment's definitions as `v2` serves them at
+ * `/rest/v2` over this environment's tables, until you retire it.
+ */
+export class Versions extends Service {
+  /** The live API first, then every released version. */
+  list(): Promise<Api> {
+    return this.get("/versions");
   }
 
-  /** Make a revision the live definitions of an API version. */
-  release(revisionId: string, apiVersion: string, name: string, options: { notes?: string; allowBreaking?: boolean } = {}): Promise<Api> {
-    return this.post("/releases", { revision_id: revisionId, api_version: apiVersion, name, notes: options.notes ?? "", allow_breaking: options.allowBreaking ?? false });
+  /** Whether `fromEnv`'s definitions can be served here as a version, and what would be added or left out. */
+  check(fromEnv: string): Promise<Api> {
+    return this.post("/versions/check", { from_env: fromEnv });
   }
 
-  activate(releaseId: string): Promise<Api> {
-    return this.post(seg("releases", releaseId, "activate"));
+  /** Serve `fromEnv`'s definitions as `/rest/<name>` (`v2`, `v3`…). A name is never reused. */
+  release(name: string, fromEnv: string, options: { notes?: string } = {}): Promise<Api> {
+    return this.post("/versions", { name, from_env: fromEnv, notes: options.notes ?? "" });
   }
 
-  deployments(): Promise<Api> {
-    return this.get("/deployments");
+  /** Stop serving a version. */
+  retire(name: string): Promise<Api> {
+    return this.post(seg("versions", name, "retire"));
   }
 }
 

package/src/manage/mail.ts

@@ -1,11 +1,25 @@
-import { Definitions, Service, type Api } from "./base.js";
+import { Definitions, Service, seg, type Api, type Body } from "./base.js";
 
 /** Templates (subject, HTML, text) for the mail flows and sign-in send. */
 export class MailTemplates extends Definitions {
   protected override readonly kind = "mail-templates";
+
+  /** Rename a template, keeping its versions. */
+  rename(name: string, to: string): Promise<Api> {
+    return this.post(seg(this.kind, name, "rename"), { to });
+  }
 }
 
 export class Mail extends Service {
+  /** The brand kit the template editor uses: brand styles, palettes, reusable blocks and folders. */
+  kit(): Promise<Api> {
+    return this.get("/mail/kit");
+  }
+
+  saveKit(kit: { brand?: Body; palettes?: Body[]; blocks?: Body[]; folders?: string[] }): Promise<Api> {
+    return this.put("/mail/kit", { brand: kit.brand ?? {}, palettes: kit.palettes ?? [], blocks: kit.blocks ?? [], folders: kit.folders ?? [] });
+  }
+
   /** The delivery settings in effect (the password is never returned) and whether mail is being delivered. */
   config(): Promise<Api> {
     return this.get("/mail/config");

package/src/manage/observe.ts

@@ -68,8 +68,9 @@ export class Observability extends Service {
     return this.get("/metric-series", { metric, minutes: options.minutes ?? 60, period: options.period, compare: options.comparePrevious ? "previous" : undefined });
   }
 
+  /** The project's background workers (not scoped to one environment). */
   workers(): Promise<Api> {
-    return this.get("/workers");
+    return this.project("GET", "/workers");
   }
 
   /** What the environment is running with. */
@@ -77,8 +78,14 @@ export class Observability extends Service {
     return this.get("/configuration");
   }
 
+  /** What the project has used against what its plan allows (not scoped to one environment). */
   capacity(): Promise<Api> {
-    return this.get("/capacity");
+    return this.project("GET", "/capacity");
+  }
+
+  /** Bytes received and sent over the last `minutes`, and the endpoints, callers and requests that moved the most. */
+  bandwidth(options: { minutes?: number } = {}): Promise<Api> {
+    return this.get("/observability/bandwidth", options);
   }
 }