@persql/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1772 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApprovalRequiredError: () => ApprovalRequiredError,
+  PerSQL: () => PerSQL,
+  PerSQLApprovals: () => PerSQLApprovals,
+  PerSQLBlob: () => PerSQLBlob,
+  PerSQLBranches: () => PerSQLBranches,
+  PerSQLDatabase: () => PerSQLDatabase,
+  PerSQLError: () => PerSQLError,
+  PerSQLProposals: () => PerSQLProposals,
+  PerSQLVectors: () => PerSQLVectors,
+  RateLimitError: () => RateLimitError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/local.ts
+var PROPOSAL_TTL_DEFAULT_SEC = 600;
+var PROPOSAL_TTL_MAX_SEC = 3600;
+function newLocalProposalId() {
+  const buf = new Uint8Array(8);
+  crypto.getRandomValues(buf);
+  let hex = "";
+  for (const b of buf) hex += b.toString(16).padStart(2, "0");
+  return `pmut_local_${hex}`;
+}
+var LocalDriver = class {
+  constructor(path) {
+    this.path = path;
+  }
+  db = null;
+  proposals = /* @__PURE__ */ new Map();
+  async open() {
+    if (this.db) return this.db;
+    const moduleName = "better-sqlite3";
+    let mod;
+    try {
+      mod = await import(moduleName);
+    } catch {
+      throw new Error(
+        "PerSQL local mode requires the `better-sqlite3` peer dep. Install with `npm i -D better-sqlite3` (or pnpm/yarn equivalent)."
+      );
+    }
+    const m = mod;
+    const Ctor = m.default ?? mod;
+    this.db = new Ctor(this.path);
+    this.db.pragma("foreign_keys = ON");
+    return this.db;
+  }
+  async query(sql, params) {
+    const db = await this.open();
+    return runOne(db, sql, params);
+  }
+  async batch(statements, transaction) {
+    const db = await this.open();
+    const exec = () => statements.map((s) => runOne(db, s.sql, s.params ?? []));
+    if (transaction) return db.transaction(exec)();
+    return exec();
+  }
+  async tables() {
+    const db = await this.open();
+    const rows = runOne(
+      db,
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+      []
+    ).rows;
+    return rows.map(([name]) => {
+      const c = runOne(db, `SELECT COUNT(*) FROM "${name.replace(/"/g, '""')}"`, []).rows[0];
+      return { name, rowCount: Number(c?.[0] ?? 0) };
+    });
+  }
+  async explain(sql, params) {
+    const db = await this.open();
+    const r = runOne(db, `EXPLAIN QUERY PLAN ${sql}`, params);
+    return r.rows.map((row) => ({
+      id: Number(row[0]),
+      parent: Number(row[1]),
+      detail: String(row[3])
+    }));
+  }
+  async propose(sql, params, ttlSec) {
+    const db = await this.open();
+    const planRaw = runOne(db, `EXPLAIN QUERY PLAN ${sql}`, params).rows;
+    const plan = planRaw;
+    const ttl = Math.min(
+      Math.max(1, Math.floor(ttlSec ?? PROPOSAL_TTL_DEFAULT_SEC)),
+      PROPOSAL_TTL_MAX_SEC
+    );
+    const expiresAt = Date.now() + ttl * 1e3;
+    const executionToken = newLocalProposalId();
+    this.proposals.set(executionToken, { sql, params, expiresAt });
+    this.gcProposals();
+    return {
+      sql,
+      plan,
+      estimatedAffectedRows: null,
+      executionToken,
+      expiresAt: new Date(expiresAt).toISOString(),
+      action: actionForSql(sql)
+    };
+  }
+  async apply(executionToken) {
+    const rec = this.proposals.get(executionToken);
+    if (!rec) {
+      throw new Error(
+        "PerSQL: executionToken is unknown, expired, or already redeemed"
+      );
+    }
+    this.proposals.delete(executionToken);
+    if (rec.expiresAt < Date.now()) {
+      throw new Error("PerSQL: executionToken has expired");
+    }
+    return this.query(rec.sql, rec.params);
+  }
+  gcProposals() {
+    const now = Date.now();
+    for (const [k, v] of this.proposals) {
+      if (v.expiresAt < now) this.proposals.delete(k);
+    }
+  }
+  close() {
+    if (this.db) {
+      try {
+        this.db.close();
+      } catch {
+      }
+      this.db = null;
+    }
+  }
+};
+function actionForSql(sql) {
+  const head = sql.trim().slice(0, 24).toLowerCase();
+  if (head.startsWith("create") || head.startsWith("drop") || head.startsWith("alter")) {
+    return "admin";
+  }
+  if (head.startsWith("insert") || head.startsWith("update") || head.startsWith("delete") || head.startsWith("replace")) {
+    return "write";
+  }
+  return "read";
+}
+function runOne(db, sql, params) {
+  const stmt = db.prepare(sql);
+  if (stmt.reader) {
+    const cols = stmt.columns().map((c) => c.name);
+    const rows = stmt.raw(true).all(...params);
+    return { columns: cols, rows, rowsRead: rows.length, rowsWritten: 0 };
+  }
+  const info = stmt.run(...params);
+  return { columns: [], rows: [], rowsRead: 0, rowsWritten: info.changes ?? 0 };
+}
+
+// src/index.ts
+var PerSQLError = class extends Error {
+  status;
+  // Set on /v1/query and /v1/batch failures with a parsed envelope
+  // (kind, table, column, hint, etc.) so callers can branch on
+  // `error.detail.kind` instead of string-matching the message.
+  detail;
+  constructor(status, message, detail) {
+    super(message);
+    this.name = "PerSQLError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+var RateLimitError = class extends PerSQLError {
+  retryAfterSeconds;
+  constructor(retryAfterSeconds, message = "Rate limit exceeded") {
+    super(429, message);
+    this.name = "RateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var ApprovalRequiredError = class extends PerSQLError {
+  approvalToken;
+  approvalUrl;
+  hits;
+  expiresAt;
+  constructor(opts) {
+    super(403, opts.message);
+    this.name = "ApprovalRequiredError";
+    this.approvalToken = opts.approvalToken;
+    this.approvalUrl = opts.approvalUrl;
+    this.hits = opts.hits;
+    this.expiresAt = opts.expiresAt;
+  }
+};
+var PerSQL = class _PerSQL {
+  /** @internal — exposed read-only so PerSQLDatabase can build URLs. */
+  token;
+  /** @internal — same. */
+  baseURL;
+  /** @internal — set when running in local mode. */
+  local;
+  _fetch;
+  constructor(opts) {
+    if (opts.local) {
+      this.local = new LocalDriver(opts.local);
+      this.token = "";
+      this.baseURL = "";
+      this._fetch = opts.fetch ?? globalThis.fetch?.bind(globalThis);
+      return;
+    }
+    if (!opts.token) {
+      throw new Error(
+        'PerSQL: token is required (or pass { local: ":memory:" } for tests)'
+      );
+    }
+    this.local = null;
+    this.token = opts.token;
+    this.baseURL = (opts.baseURL ?? "https://api.persql.com").replace(/\/$/, "");
+    this._fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  /** Close the local SQLite connection (no-op in HTTP mode). */
+  close() {
+    this.local?.close();
+  }
+  /**
+   * Redeem a handoff token (`phand_…`) for a regular PerSQL client
+   * scoped to the handed-off (database, branch, role). Single use:
+   * the handoff token is consumed by the call.
+   *
+   * Common pattern — agent A pins a branch and hands the token to
+   * agent B; agent B does:
+   *
+   *   const persql = await PerSQL.fromHandoff(handoffToken);
+   *   const db = persql.database(persql.handedOff!.namespaceSlug, persql.handedOff!.databaseSlug);
+   */
+  static async fromHandoff(handoffToken, opts = {}) {
+    const baseURL = (opts.baseURL ?? "https://api.persql.com").replace(/\/$/, "");
+    const fetcher = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const res = await fetcher(`${baseURL}/v1/handoff/claim`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token: handoffToken, name: opts.name })
+    });
+    const envelope = await res.json().catch(() => null);
+    if (!res.ok || !envelope?.success || !envelope.data) {
+      throw new PerSQLError(
+        res.status,
+        envelope?.error ?? `Handoff claim failed (${res.status})`
+      );
+    }
+    const { plaintext, ...handedOff } = envelope.data;
+    const client = new _PerSQL({ token: plaintext, baseURL, fetch: opts.fetch });
+    return Object.assign(client, { handedOff });
+  }
+  database(a, b) {
+    if (b !== void 0) return new PerSQLDatabase(this, a, b);
+    const [ns, slug] = a.split("/");
+    if (!ns || !slug) {
+      throw new Error('PerSQL: database path must be "<namespace>/<slug>"');
+    }
+    return new PerSQLDatabase(this, ns, slug);
+  }
+  /** @internal */
+  async request(method, path, body, headers) {
+    const res = await this._fetch(`${this.baseURL}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json",
+        ...headers ?? {}
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (res.status === 429) {
+      const retryAfter = Number(res.headers.get("retry-after") ?? "60");
+      throw new RateLimitError(retryAfter);
+    }
+    let envelope = null;
+    try {
+      envelope = await res.json();
+    } catch {
+    }
+    if (!res.ok || !envelope?.success) {
+      const message = envelope?.error ?? `Request failed (${res.status})`;
+      if (res.status === 403 && envelope?.approvalToken && envelope?.approvalUrl && envelope?.expiresAt) {
+        throw new ApprovalRequiredError({
+          message,
+          approvalToken: envelope.approvalToken,
+          approvalUrl: envelope.approvalUrl,
+          hits: envelope.hits ?? [],
+          expiresAt: envelope.expiresAt
+        });
+      }
+      throw new PerSQLError(res.status, message, envelope?.errorDetail);
+    }
+    return envelope.data;
+  }
+  /** @internal — raw upload (e.g. blob PUT) returning the ApiResponse data. */
+  async requestRaw(method, path, body, contentType) {
+    const res = await this._fetch(`${this.baseURL}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": contentType ?? "application/octet-stream"
+      },
+      body,
+      // @ts-expect-error — duplex is required by Node fetch for streaming bodies
+      duplex: "half"
+    });
+    if (res.status === 429) {
+      const retryAfter = Number(res.headers.get("retry-after") ?? "60");
+      throw new RateLimitError(retryAfter);
+    }
+    let envelope = null;
+    try {
+      envelope = await res.json();
+    } catch {
+    }
+    if (!res.ok || !envelope?.success) {
+      const message = envelope?.error ?? `Request failed (${res.status})`;
+      throw new PerSQLError(res.status, message, envelope?.errorDetail);
+    }
+    return envelope.data;
+  }
+  /** @internal — raw fetch returning the underlying Response (used by blob GET). */
+  fetchRaw(method, path) {
+    return this._fetch(`${this.baseURL}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${this.token}` }
+    });
+  }
+};
+var PerSQLDatabase = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /** Run a single SQL statement. */
+  async query(sql, params = [], options = {}) {
+    if (this.client.local) {
+      const raw2 = await this.client.local.query(sql, params);
+      return { ...raw2, data: rowsToObjects(raw2.columns, raw2.rows) };
+    }
+    const headers = {};
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    if (options.planKey) headers["Plan-Key"] = options.planKey;
+    if (options.planStep) headers["Plan-Step"] = options.planStep;
+    const raw = await this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/query`,
+      { sql, params },
+      headers
+    );
+    return {
+      ...raw,
+      data: rowsToObjects(raw.columns, raw.rows)
+    };
+  }
+  /** Run multiple statements in one round-trip, optionally in a transaction. */
+  async batch(statements, options = {}) {
+    if (this.client.local) {
+      const raw2 = await this.client.local.batch(
+        statements,
+        options.transaction ?? false
+      );
+      return raw2.map((r) => ({ ...r, data: rowsToObjects(r.columns, r.rows) }));
+    }
+    const headers = {};
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    if (options.planKey) headers["Plan-Key"] = options.planKey;
+    if (options.planStep) headers["Plan-Step"] = options.planStep;
+    const raw = await this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/batch`,
+      { statements, transaction: options.transaction ?? false },
+      headers
+    );
+    return raw.map((r) => ({ ...r, data: rowsToObjects(r.columns, r.rows) }));
+  }
+  /** Convenience for a transactional batch. */
+  transaction(statements, options = {}) {
+    return this.batch(statements, { ...options, transaction: true });
+  }
+  /**
+   * Engine telemetry — recent /v1/query and /v1/batch calls issued
+   * against this database. Backed by the in-DO `_persql_meta_query_log`
+   * table; 7-day retention. Useful for agents that need to replay
+   * what they (or another agent) did, audit cost, or stream a live
+   * tail via `db.subscribe`.
+   */
+  async queryLog(opts = {}) {
+    if (this.client.local) {
+      throw new Error("PerSQL: queryLog is not available in local mode.");
+    }
+    const qs = new URLSearchParams();
+    if (opts.since) {
+      qs.set(
+        "since",
+        typeof opts.since === "string" ? opts.since : opts.since.toISOString()
+      );
+    }
+    if (opts.until) {
+      qs.set(
+        "until",
+        typeof opts.until === "string" ? opts.until : opts.until.toISOString()
+      );
+    }
+    if (opts.tokenId) qs.set("tokenId", opts.tokenId);
+    if (opts.status) qs.set("status", opts.status);
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    if (opts.pageSize) qs.set("pageSize", String(opts.pageSize));
+    const tail = qs.toString() ? `?${qs.toString()}` : "";
+    const res = await this.client.fetchRaw(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/queries${tail}`
+    );
+    const body = await res.json();
+    if (!res.ok || !body.success) {
+      throw new PerSQLError(res.status, body.error ?? `Request failed (${res.status})`);
+    }
+    return { data: body.data ?? [], nextCursor: body.nextCursor ?? null };
+  }
+  /**
+   * Returns a structured description of the database — columns, FK
+   * graph, and any human-/AI-authored docs persisted via
+   * `db.describe(...)`. The shape is designed for direct injection
+   * into an LLM prompt: one round-trip and the agent has everything
+   * it needs to write correct SQL.
+   */
+  async describe() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: describe is not available in local mode (yet)."
+      );
+    }
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/describe`
+    );
+  }
+  /**
+   * Persist semantic descriptions for the database / tables / columns.
+   * Pass any subset — only the fields you set are updated. Requires
+   * an admin-role token because docs change how every other client
+   * (and every agent) interprets the schema.
+   */
+  async setDescription(input) {
+    if (this.client.local) {
+      throw new Error("PerSQL: setDescription is not available in local mode.");
+    }
+    return this.client.request(
+      "PUT",
+      `/v1/db/${this.namespace}/${this.slug}/describe`,
+      input
+    );
+  }
+  /**
+   * Natural-language ranked search across table names, column names,
+   * and any descriptions you've stored via `setDescription`. Use this
+   * before writing SQL when you don't know the schema cold — one call
+   * narrows a 200-table DB down to the handful that match the intent.
+   */
+  async search(query, opts = {}) {
+    if (this.client.local) {
+      throw new Error("PerSQL: search is not available in local mode.");
+    }
+    const qs = new URLSearchParams({ q: query });
+    if (opts.limit) qs.set("limit", String(opts.limit));
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/search?${qs.toString()}`
+    );
+  }
+  /**
+   * Lints the schema for issues that hurt LLM consumption: missing
+   * primary keys, ambiguous column names ("data", "value"), unindexed
+   * foreign keys, etc. Pure read-only analysis — emits suggestions
+   * for the agent to act on, never modifies the schema itself.
+   */
+  async doctor() {
+    if (this.client.local) {
+      throw new Error("PerSQL: doctor is not available in local mode.");
+    }
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/doctor`
+    );
+  }
+  /** List user-defined tables in this database. */
+  async tables() {
+    if (this.client.local) return this.client.local.tables();
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/tables`
+    );
+  }
+  /**
+   * Returns SQLite's `EXPLAIN QUERY PLAN` output for the given SQL.
+   * Read-only — does not execute the statement.
+   */
+  async explain(sql, params = []) {
+    if (this.client.local) return this.client.local.explain(sql, params);
+    return this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/explain`, { sql, params });
+  }
+  /**
+   * Introspect the database schema. Returns one entry per user table
+   * with column definitions, suitable for codegen tools (the
+   * `persql-codegen` CLI uses this to emit Drizzle schema files).
+   */
+  async schema() {
+    const tables = await this.tables();
+    const out = { tables: [] };
+    for (const t of tables) {
+      const r = await this.query(`PRAGMA table_info("${t.name.replace(/"/g, '""')}")`);
+      out.tables.push({
+        name: t.name,
+        columns: r.data.map((c) => ({
+          name: c.name,
+          type: c.type,
+          notNull: !!c.notnull,
+          primaryKey: !!c.pk,
+          default: c.dflt_value === null ? null : String(c.dflt_value)
+        }))
+      });
+    }
+    return out;
+  }
+  /**
+   * Per-database semantic search via Cloudflare Vectorize. Use
+   * `vectors.upsert` to embed and store rows; `vectors.query` to
+   * retrieve the most similar by free text. Embeddings are computed
+   * server-side using bge-base-en-v1.5 (768 dim, cosine distance).
+   */
+  get vectors() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: vectors require Cloudflare Vectorize and Workers AI \u2014 not available in local mode. Use a server-mode token (psql_live_/psql_test_) to call vectors.upsert/query/delete."
+      );
+    }
+    return new PerSQLVectors(this.client, this.namespace, this.slug);
+  }
+  /**
+   * Manage preview/PR-style branches of this database. Each branch is
+   * its own DO with its own SQLite file; create-or-reset by ref is
+   * idempotent (PUT semantics) so CI pipelines can call it on every
+   * build. Requires an admin-role bearer token for create / delete /
+   * merge; list is open to any role.
+   */
+  get branches() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: branches model fork-by-Durable-Object \u2014 not available in local mode. Use a server-mode token to call branches.upsert/claim/merge, or stub branch isolation in tests by spinning up multiple `new PerSQL({ local: ':memory:' })` instances."
+      );
+    }
+    return new PerSQLBranches(this.client, this.namespace, this.slug);
+  }
+  /**
+   * Redeem an approval that was minted when a write hit a
+   * `require_approval` rule. Throws `ApprovalRequiredError` until a
+   * namespace member decides; on approve, runs the original SQL.
+   */
+  get approvals() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: approvals require a server-side approval gate \u2014 not available in local mode. Local mode runs every statement immediately; use a server-mode token if you need the require_approval rule."
+      );
+    }
+    return new PerSQLApprovals(this.client, this.namespace, this.slug);
+  }
+  /**
+   * Pre-flight a write before running it. `propose()` validates the
+   * SQL via EXPLAIN, estimates affected rows, and returns a single-use
+   * `executionToken` to redeem with `apply()`. Use this when an agent
+   * (or its parent / a human) should review a mutation before it runs.
+   * Works in both HTTP and local modes — local mode keeps the
+   * executionToken in-process.
+   */
+  get proposals() {
+    return new PerSQLProposals(this.client, this.namespace, this.slug);
+  }
+  /**
+   * Per-database BLOB storage backed by R2. Use this for anything
+   * larger than a SQLite cell (images, PDFs, model weights). Each
+   * database has its own private namespace; keys may be hierarchical
+   * (`avatars/2025/foo.jpg`) but never start with `/`.
+   */
+  get blob() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: blob storage is backed by R2 \u2014 not available in local mode. Use a server-mode token, or store blobs in your test fixtures directly."
+      );
+    }
+    return new PerSQLBlob(this.client, this.namespace, this.slug);
+  }
+  /**
+   * Subscribe to row-changes via WebSocket — the SQL equivalent of
+   * Postgres `LISTEN`. The callback fires once per write that
+   * matches the table filter. Returns an `unsubscribe` function;
+   * call it to close the socket.
+   *
+   * ```ts
+   * const off = db.subscribe({
+   *   tables: ["orders"],
+   *   onChange: (e) => console.log(e.kind, e.table),
+   * });
+   * // …later
+   * off();
+   * ```
+   *
+   * Authentication uses the `persql.bearer.<token>` sub-protocol so
+   * the token doesn't leak via URL logs. In environments without
+   * sub-protocol support (some serverless WebSocket clients), the
+   * fallback `?token=` query string is also accepted by the
+   * server.
+   */
+  subscribe(options) {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: subscribe requires the DO's WebSocket fan-out \u2014 not available in local mode. Use a server-mode token to call subscribe()."
+      );
+    }
+    const baseHttp = this.client.baseURL;
+    const wsBase = baseHttp.replace(/^http/, "ws");
+    const tablesParam = options.tables && options.tables.length > 0 ? `?tables=${encodeURIComponent(options.tables.join(","))}` : "";
+    const url = `${wsBase}/v1/db/${this.namespace}/${this.slug}/subscribe${tablesParam}`;
+    const ws = new WebSocket(url, [`persql.bearer.${this.client.token}`]);
+    let closed = false;
+    ws.addEventListener("message", (ev) => {
+      try {
+        const msg = JSON.parse(String(ev.data));
+        if (msg.type === "change" && msg.table && msg.kind) {
+          options.onChange({ table: msg.table, kind: msg.kind });
+        } else if (msg.type === "error") {
+          options.onError?.(new Error(msg.message ?? "Subscription error"));
+        } else if (msg.type === "subscribed") {
+          options.onReady?.(msg.tables ?? "*");
+        }
+      } catch {
+      }
+    });
+    ws.addEventListener("error", () => {
+      options.onError?.(new Error("WebSocket error"));
+    });
+    ws.addEventListener("close", () => {
+      if (!closed) options.onClose?.();
+    });
+    return () => {
+      closed = true;
+      try {
+        ws.close();
+      } catch {
+      }
+    };
+  }
+  /**
+   * Returns the callback shape `drizzle-orm/sqlite-proxy` expects.
+   * Pair with `drizzle()` from that module to get a typed,
+   * fluent ORM client over the PerSQL HTTP API:
+   *
+   * ```ts
+   * import { drizzle } from "drizzle-orm/sqlite-proxy";
+   * import { PerSQL } from "@persql/sdk";
+   *
+   * const persql = new PerSQL({ token });
+   * const db = drizzle(persql.database("acme/orders").driver());
+   * ```
+   *
+   * Drizzle's `prepare` interface maps onto our `query` /
+   * `batch`; `method` tells us how to shape the rows.
+   */
+  driver() {
+    const callback = async (sql, params, method) => {
+      const result = await this.query(sql, params ?? []);
+      if (method === "values" || method === "get") {
+        return { rows: result.rows[0] ?? [] };
+      }
+      return { rows: result.rows };
+    };
+    return callback;
+  }
+  /**
+   * Returns a tool definition for use with Anthropic / OpenAI / function-calling
+   * agents. Pair it with `runTool` to execute the call.
+   */
+  asTool(name = "persql_query") {
+    return {
+      anthropic: {
+        name,
+        description: `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}". Returns up to 1000 rows. Use parameter binding (?) to avoid injection.`,
+        input_schema: {
+          type: "object",
+          properties: {
+            sql: { type: "string", description: "SQLite SQL statement" },
+            params: {
+              type: "array",
+              items: {},
+              description: "Positional parameters for the SQL statement"
+            }
+          },
+          required: ["sql"]
+        }
+      },
+      openai: {
+        type: "function",
+        function: {
+          name,
+          description: `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}".`,
+          parameters: {
+            type: "object",
+            properties: {
+              sql: { type: "string" },
+              params: { type: "array", items: {} }
+            },
+            required: ["sql"]
+          }
+        }
+      }
+    };
+  }
+  /**
+   * Executes a tool-call payload returned from the model. Pair with `asTool`.
+   */
+  runTool(input) {
+    return this.query(input.sql, input.params ?? []);
+  }
+  /**
+   * Generate a *bundle* of typed tools — one per table — instead of one
+   * generic `query` tool. Agents perform dramatically better with narrow
+   * typed surfaces than they do with one fat SQL function. Each table
+   * gets:
+   *   - `select_<table>(where?, limit?, orderBy?)` — typed column filter
+   *   - `count_<table>(where?)` — quick row count
+   *   - `describe_<table>()` — columns, row count, foreign keys
+   * Plus a fallback `sql_query(sql, params)` for anything the typed
+   * tools can't express.
+   *
+   * The returned `run(name, input)` dispatcher executes whichever tool
+   * the model invoked. Format the tools for the LLM via the
+   * `anthropic` or `openai` arrays (matches the shapes of `asTool`).
+   *
+   * ```ts
+   * const tools = await db.asTools();
+   * const reply = await anthropic.messages.create({
+   *   model: "claude-opus-4-7",
+   *   tools: tools.anthropic,
+   *   messages: [...],
+   * });
+   * for (const block of reply.content) {
+   *   if (block.type === "tool_use") {
+   *     const result = await tools.run(block.name, block.input);
+   *   }
+   * }
+   * ```
+   */
+  async asTools() {
+    const schema = await this.schema();
+    const anthropic = [];
+    const openai = [];
+    for (const t of schema.tables) {
+      const safe = sanitizeToolPart(t.name);
+      const columnList = t.columns.map((c) => `${c.name} ${c.type}${c.notNull ? " NOT NULL" : ""}${c.primaryKey ? " PRIMARY KEY" : ""}`).join(", ");
+      const whereProps = {};
+      for (const c of t.columns) {
+        whereProps[c.name] = {
+          type: ["string", "number", "boolean", "null"],
+          description: `Equality filter on ${t.name}.${c.name} (${c.type})`
+        };
+      }
+      const selectName = `select_${safe}`;
+      const selectDesc = `Read rows from ${t.name}. Columns: ${columnList}. Use \`where\` for equality predicates, \`orderBy\` to sort, \`limit\` to bound the result (default 100, max 1000).`;
+      const selectInput = {
+        type: "object",
+        properties: {
+          where: {
+            type: "object",
+            description: "Equality filter \u2014 keys are column names, values are scalars.",
+            properties: whereProps,
+            additionalProperties: false
+          },
+          orderBy: {
+            type: "string",
+            description: "Column name optionally followed by ASC/DESC."
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 1e3,
+            default: 100
+          }
+        },
+        additionalProperties: false
+      };
+      anthropic.push({ name: selectName, description: selectDesc, input_schema: selectInput });
+      openai.push({
+        type: "function",
+        function: { name: selectName, description: selectDesc, parameters: selectInput }
+      });
+      const countName = `count_${safe}`;
+      const countDesc = `Count rows in ${t.name}, optionally filtered by equality on any column.`;
+      const countInput = {
+        type: "object",
+        properties: {
+          where: {
+            type: "object",
+            properties: whereProps,
+            additionalProperties: false
+          }
+        },
+        additionalProperties: false
+      };
+      anthropic.push({ name: countName, description: countDesc, input_schema: countInput });
+      openai.push({
+        type: "function",
+        function: { name: countName, description: countDesc, parameters: countInput }
+      });
+      const descName = `describe_${safe}`;
+      const descDesc = `Return columns, row count, and foreign keys for ${t.name}.`;
+      const descInput = {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      };
+      anthropic.push({ name: descName, description: descDesc, input_schema: descInput });
+      openai.push({
+        type: "function",
+        function: { name: descName, description: descDesc, parameters: descInput }
+      });
+      const valueProps = {};
+      const requiredForInsert = [];
+      for (const c of t.columns) {
+        valueProps[c.name] = {
+          type: ["string", "number", "boolean", "null"],
+          description: `${t.name}.${c.name} (${c.type})${c.notNull ? " NOT NULL" : ""}`
+        };
+        if (c.notNull && !c.primaryKey) {
+          requiredForInsert.push(c.name);
+        }
+      }
+      const insertName = `insert_${safe}`;
+      const insertDesc = `Insert one row into ${t.name}. Provide column values in \`values\`. Required (NOT NULL): ${requiredForInsert.join(", ") || "(none)"}.`;
+      const insertInput = {
+        type: "object",
+        properties: {
+          values: {
+            type: "object",
+            description: "Column \u2192 value map for the new row.",
+            properties: valueProps,
+            required: requiredForInsert,
+            additionalProperties: false
+          }
+        },
+        required: ["values"],
+        additionalProperties: false
+      };
+      anthropic.push({ name: insertName, description: insertDesc, input_schema: insertInput });
+      openai.push({
+        type: "function",
+        function: { name: insertName, description: insertDesc, parameters: insertInput }
+      });
+      const updateName = `update_${safe}`;
+      const updateDesc = `Update rows in ${t.name} matching \`where\` (equality on any column) with the columns provided in \`set\`. Both must be non-empty \u2014 to clear the filter use \`sql_query\`.`;
+      const updateInput = {
+        type: "object",
+        properties: {
+          where: {
+            type: "object",
+            properties: whereProps,
+            additionalProperties: false
+          },
+          set: {
+            type: "object",
+            properties: valueProps,
+            additionalProperties: false
+          }
+        },
+        required: ["where", "set"],
+        additionalProperties: false
+      };
+      anthropic.push({ name: updateName, description: updateDesc, input_schema: updateInput });
+      openai.push({
+        type: "function",
+        function: { name: updateName, description: updateDesc, parameters: updateInput }
+      });
+      const deleteName = `delete_${safe}`;
+      const deleteDesc = `Delete rows from ${t.name} matching \`where\`. \`where\` must be non-empty \u2014 to truncate use \`sql_query\` with an explicit DELETE.`;
+      const deleteInput = {
+        type: "object",
+        properties: {
+          where: {
+            type: "object",
+            properties: whereProps,
+            additionalProperties: false
+          }
+        },
+        required: ["where"],
+        additionalProperties: false
+      };
+      anthropic.push({ name: deleteName, description: deleteDesc, input_schema: deleteInput });
+      openai.push({
+        type: "function",
+        function: { name: deleteName, description: deleteDesc, parameters: deleteInput }
+      });
+    }
+    const sqlName = "sql_query";
+    const sqlDesc = `Run an arbitrary parameterised SQL statement against the PerSQL database "${this.namespace}/${this.slug}". Prefer the table-specific select_/count_/describe_ tools when they fit; fall back to this for joins, aggregates, or DDL.`;
+    const sqlInput = {
+      type: "object",
+      properties: {
+        sql: { type: "string" },
+        params: { type: "array", items: {} }
+      },
+      required: ["sql"],
+      additionalProperties: false
+    };
+    anthropic.push({ name: sqlName, description: sqlDesc, input_schema: sqlInput });
+    openai.push({
+      type: "function",
+      function: { name: sqlName, description: sqlDesc, parameters: sqlInput }
+    });
+    const describeDbName = "describe_database";
+    const describeDbDesc = `Return the full schema graph plus stored semantic descriptions for "${this.namespace}/${this.slug}". Call this FIRST on any unfamiliar database \u2014 it includes table descriptions, column docs, and foreign keys in one shot, sized to JSON-stringify into a system prompt.`;
+    const describeDbInput = {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: describeDbName,
+      description: describeDbDesc,
+      input_schema: describeDbInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: describeDbName,
+        description: describeDbDesc,
+        parameters: describeDbInput
+      }
+    });
+    const searchSchemaName = "search_schema";
+    const searchSchemaDesc = `Natural-language ranked search across table names, column names, and stored descriptions. Use this when you have a goal ("billing addresses", "abandoned carts") but don't know which table holds it.`;
+    const searchSchemaInput = {
+      type: "object",
+      properties: {
+        q: {
+          type: "string",
+          description: "Free-text query \u2014 table/column/description tokens are matched."
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          default: 25
+        }
+      },
+      required: ["q"],
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: searchSchemaName,
+      description: searchSchemaDesc,
+      input_schema: searchSchemaInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: searchSchemaName,
+        description: searchSchemaDesc,
+        parameters: searchSchemaInput
+      }
+    });
+    const doctorName = "schema_doctor";
+    const doctorDesc = `Lint the schema for LLM-hostile patterns \u2014 missing primary keys, ambiguous column names, unindexed foreign keys. Read-only; useful before generating SQL so you know what the schema gets wrong.`;
+    const doctorInput = {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: doctorName,
+      description: doctorDesc,
+      input_schema: doctorInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: doctorName,
+        description: doctorDesc,
+        parameters: doctorInput
+      }
+    });
+    const proposeName = "propose_mutation";
+    const proposeDesc = `Pre-flight a SQL write \u2014 EXPLAIN-validate, estimate affected rows, and return a single-use executionToken. Nothing is mutated until apply_mutation is called with that token. Use for any UPDATE/DELETE that isn't tightly scoped to a single PK, or any INSERT batch you want to verify.`;
+    const proposeInput = {
+      type: "object",
+      properties: {
+        sql: { type: "string", description: "SQLite SQL statement." },
+        params: { type: "array", items: {} },
+        ttlSec: {
+          type: "integer",
+          minimum: 30,
+          maximum: 3600,
+          description: "Token TTL in seconds. Default 600 (10 min)."
+        }
+      },
+      required: ["sql"],
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: proposeName,
+      description: proposeDesc,
+      input_schema: proposeInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: proposeName,
+        description: proposeDesc,
+        parameters: proposeInput
+      }
+    });
+    const applyName = "apply_mutation";
+    const applyDesc = `Redeem an executionToken returned by propose_mutation. Single-use \u2014 calling twice fails. The actual write runs through the same auto-snapshot + query-log + pricing pipeline as a normal SQL call.`;
+    const applyInput = {
+      type: "object",
+      properties: {
+        executionToken: {
+          type: "string",
+          description: "pmut_\u2026 token from propose_mutation."
+        }
+      },
+      required: ["executionToken"],
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: applyName,
+      description: applyDesc,
+      input_schema: applyInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: applyName,
+        description: applyDesc,
+        parameters: applyInput
+      }
+    });
+    const queryLogName = "recent_queries";
+    const queryLogDesc = `Recent /query and /batch calls against this database \u2014 durations, errors, statement counts. Use to debug a failed write you just made, or to spot N+1 patterns in your own behavior.`;
+    const queryLogInput = {
+      type: "object",
+      properties: {
+        since: {
+          type: "string",
+          description: "ISO timestamp lower bound."
+        },
+        status: {
+          type: "string",
+          enum: ["ok", "error"]
+        },
+        pageSize: {
+          type: "integer",
+          minimum: 1,
+          maximum: 200,
+          default: 50
+        }
+      },
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: queryLogName,
+      description: queryLogDesc,
+      input_schema: queryLogInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: queryLogName,
+        description: queryLogDesc,
+        parameters: queryLogInput
+      }
+    });
+    const dbRef = `"${this.namespace}/${this.slug}"`;
+    const branchesList = "branches_list";
+    const branchesListInput = {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    };
+    const branchesListDesc = `List preview branches of ${dbRef}. Each branch is its own SQLite database forked from the parent at create time.`;
+    anthropic.push({
+      name: branchesList,
+      description: branchesListDesc,
+      input_schema: branchesListInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: branchesList,
+        description: branchesListDesc,
+        parameters: branchesListInput
+      }
+    });
+    const branchesCreate = "branches_create";
+    const branchesCreateInput = {
+      type: "object",
+      properties: {
+        ref: {
+          type: "string",
+          description: "Stable identifier for the branch (e.g. 'pr-42' or 'agent-run-7c2f'). PUT semantics \u2014 the same ref re-runs as a reset from the parent's current state."
+        },
+        name: {
+          type: "string",
+          description: "Optional human-readable name."
+        },
+        ttlDays: {
+          type: ["integer", "null"],
+          minimum: 1,
+          maximum: 30,
+          description: "Auto-delete after N days (1..30). Use for ephemeral / scratch experiments."
+        }
+      },
+      required: ["ref"],
+      additionalProperties: false
+    };
+    const branchesCreateDesc = `Create-or-reset a branch of ${dbRef} keyed by ref. Idempotent: repeat the same ref to refresh from the current parent. Requires an admin-role token.`;
+    anthropic.push({
+      name: branchesCreate,
+      description: branchesCreateDesc,
+      input_schema: branchesCreateInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: branchesCreate,
+        description: branchesCreateDesc,
+        parameters: branchesCreateInput
+      }
+    });
+    const branchesDelete = "branches_delete";
+    const branchesDeleteInput = {
+      type: "object",
+      properties: {
+        ref: { type: "string", description: "The branch ref to delete." }
+      },
+      required: ["ref"],
+      additionalProperties: false
+    };
+    const branchesDeleteDesc = `Delete a branch of ${dbRef}. Removes the branch's database and all of its data. Requires an admin-role token.`;
+    anthropic.push({
+      name: branchesDelete,
+      description: branchesDeleteDesc,
+      input_schema: branchesDeleteInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: branchesDelete,
+        description: branchesDeleteDesc,
+        parameters: branchesDeleteInput
+      }
+    });
+    const branchesMergeInput = {
+      type: "object",
+      properties: {
+        ref: { type: "string", description: "The branch ref to apply." },
+        mode: {
+          type: "string",
+          enum: ["schema", "promote"],
+          description: "schema (default): apply the DDL delta \u2014 adds, plus replaces for views/triggers/indexes. Refuses table-shape changes. promote: replace the parent's full contents with the branch's (the parent keeps its identity)."
+        },
+        dropRemoved: {
+          type: "boolean",
+          description: "Schema mode only \u2014 also drop objects present in the parent but absent in the branch."
+        }
+      },
+      required: ["ref"],
+      additionalProperties: false
+    };
+    const branchesPreview = "branches_preview_merge";
+    const branchesPreviewDesc = `Preview merging a branch of ${dbRef} back into its parent \u2014 returns the plan (added/changed/removed objects) without writing. Use this before branches_merge to show the user what will happen.`;
+    anthropic.push({
+      name: branchesPreview,
+      description: branchesPreviewDesc,
+      input_schema: branchesMergeInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: branchesPreview,
+        description: branchesPreviewDesc,
+        parameters: branchesMergeInput
+      }
+    });
+    const claimBranchName = "claim_branch";
+    const claimBranchDesc = `One-shot lease: create a fresh branch of ${dbRef} AND mint a scoped psql_live_ token in the same call. Use this when delegating work to a sub-agent \u2014 return the token to the sub-agent, walk away, and the branch + token both expire when the lease ends. Requires an admin-role token.`;
+    const claimBranchInput = {
+      type: "object",
+      properties: {
+        purpose: {
+          type: "string",
+          description: "Free-text label baked into the auto-generated branch ref (e.g. 'agent-run-fix-issue-742')."
+        },
+        ttlSec: {
+          type: "integer",
+          minimum: 60,
+          maximum: 60 * 60 * 24 * 30,
+          description: "Lease duration in seconds. Default 3600 (1 hour)."
+        },
+        role: {
+          type: "string",
+          enum: ["read", "write", "admin"],
+          description: "Role for the minted token. Default 'write'."
+        }
+      },
+      additionalProperties: false
+    };
+    anthropic.push({
+      name: claimBranchName,
+      description: claimBranchDesc,
+      input_schema: claimBranchInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: claimBranchName,
+        description: claimBranchDesc,
+        parameters: claimBranchInput
+      }
+    });
+    const branchesMerge = "branches_merge";
+    const branchesMergeDesc = `Apply a branch back into ${dbRef}. Auto-snapshots the parent first (rollback via /restore with the returned snapshotId). Requires an admin-role token.`;
+    anthropic.push({
+      name: branchesMerge,
+      description: branchesMergeDesc,
+      input_schema: branchesMergeInput
+    });
+    openai.push({
+      type: "function",
+      function: {
+        name: branchesMerge,
+        description: branchesMergeDesc,
+        parameters: branchesMergeInput
+      }
+    });
+    const tableBySafe = /* @__PURE__ */ new Map();
+    for (const t of schema.tables) tableBySafe.set(sanitizeToolPart(t.name), t);
+    const run = async (name, input = {}) => {
+      if (name === sqlName) {
+        const sql = String(input.sql ?? "");
+        const params2 = Array.isArray(input.params) ? input.params : [];
+        return this.query(sql, params2);
+      }
+      if (name === describeDbName) {
+        return this.describe();
+      }
+      if (name === searchSchemaName) {
+        const q = String(input.q ?? "");
+        if (!q) throw new Error("q is required");
+        const limit2 = typeof input.limit === "number" ? input.limit : void 0;
+        return this.search(q, limit2 !== void 0 ? { limit: limit2 } : {});
+      }
+      if (name === doctorName) {
+        return this.doctor();
+      }
+      if (name === proposeName) {
+        const sql = String(input.sql ?? "");
+        if (!sql) throw new Error("sql is required");
+        const params2 = Array.isArray(input.params) ? input.params : void 0;
+        const ttlSec = typeof input.ttlSec === "number" ? input.ttlSec : void 0;
+        return this.proposals.propose(sql, {
+          params: params2,
+          ttlSec
+        });
+      }
+      if (name === applyName) {
+        const token = String(input.executionToken ?? "");
+        if (!token) throw new Error("executionToken is required");
+        return this.proposals.apply(token);
+      }
+      if (name === queryLogName) {
+        const opts = {};
+        if (typeof input.since === "string") opts.since = input.since;
+        if (input.status === "ok" || input.status === "error")
+          opts.status = input.status;
+        if (typeof input.pageSize === "number") opts.pageSize = input.pageSize;
+        return this.queryLog(opts);
+      }
+      if (name === claimBranchName) {
+        const opts = {};
+        if (typeof input.purpose === "string") opts.purpose = input.purpose;
+        if (typeof input.ttlSec === "number") opts.ttlSec = input.ttlSec;
+        if (input.role === "read" || input.role === "write" || input.role === "admin")
+          opts.role = input.role;
+        return this.branches.claim(opts);
+      }
+      if (name === branchesList) {
+        return this.branches.list();
+      }
+      if (name === branchesCreate) {
+        const ref = String(input.ref ?? "");
+        if (!ref) throw new Error("ref is required");
+        const ttl = input.ttlDays;
+        return this.branches.upsert(ref, {
+          name: typeof input.name === "string" ? input.name : void 0,
+          ttlDays: typeof ttl === "number" ? ttl : ttl === null ? null : void 0
+        });
+      }
+      if (name === branchesDelete) {
+        const ref = String(input.ref ?? "");
+        if (!ref) throw new Error("ref is required");
+        return this.branches.delete(ref);
+      }
+      if (name === branchesPreview || name === branchesMerge) {
+        const ref = String(input.ref ?? "");
+        if (!ref) throw new Error("ref is required");
+        const mode = input.mode === "promote" ? "promote" : "schema";
+        return this.branches.merge(ref, {
+          mode,
+          preview: name === branchesPreview,
+          dropRemoved: input.dropRemoved === true
+        });
+      }
+      const m = name.match(/^(select|count|describe|insert|update|delete)_(.+)$/);
+      if (!m) throw new Error(`Unknown tool: ${name}`);
+      const [, op, tableSafe] = m;
+      const t = tableBySafe.get(tableSafe);
+      if (!t) throw new Error(`Unknown table for tool ${name}`);
+      const ident = quoteIdent(t.name);
+      const colSetForT = new Set(t.columns.map((c) => c.name));
+      if (op === "insert") {
+        const values = input.values ?? {};
+        const cols = Object.keys(values);
+        if (cols.length === 0) throw new Error("values must be non-empty");
+        for (const k of cols) {
+          if (!colSetForT.has(k)) throw new Error(`Unknown column: ${k}`);
+        }
+        const placeholders = cols.map(() => "?").join(", ");
+        const colSql = cols.map(quoteIdent).join(", ");
+        return this.query(
+          `INSERT INTO ${ident} (${colSql}) VALUES (${placeholders})`,
+          cols.map((c) => values[c])
+        );
+      }
+      if (op === "update") {
+        const where2 = input.where ?? {};
+        const setObj = input.set ?? {};
+        const setKeys = Object.keys(setObj);
+        const whereKeys = Object.keys(where2);
+        if (setKeys.length === 0) throw new Error("set must be non-empty");
+        if (whereKeys.length === 0)
+          throw new Error("where must be non-empty \u2014 use sql_query for unfiltered updates");
+        for (const k of [...setKeys, ...whereKeys]) {
+          if (!colSetForT.has(k)) throw new Error(`Unknown column: ${k}`);
+        }
+        const setSql = setKeys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
+        const whereSqlParts = [];
+        const whereParams = [];
+        for (const k of whereKeys) {
+          const v = where2[k];
+          if (v === null) {
+            whereSqlParts.push(`${quoteIdent(k)} IS NULL`);
+          } else {
+            whereSqlParts.push(`${quoteIdent(k)} = ?`);
+            whereParams.push(v);
+          }
+        }
+        return this.query(
+          `UPDATE ${ident} SET ${setSql} WHERE ${whereSqlParts.join(" AND ")}`,
+          [...setKeys.map((k) => setObj[k]), ...whereParams]
+        );
+      }
+      if (op === "delete") {
+        const where2 = input.where ?? {};
+        const whereKeys = Object.keys(where2);
+        if (whereKeys.length === 0)
+          throw new Error("where must be non-empty \u2014 use sql_query for unfiltered deletes");
+        for (const k of whereKeys) {
+          if (!colSetForT.has(k)) throw new Error(`Unknown column: ${k}`);
+        }
+        const whereSqlParts = [];
+        const whereParams = [];
+        for (const k of whereKeys) {
+          const v = where2[k];
+          if (v === null) {
+            whereSqlParts.push(`${quoteIdent(k)} IS NULL`);
+          } else {
+            whereSqlParts.push(`${quoteIdent(k)} = ?`);
+            whereParams.push(v);
+          }
+        }
+        return this.query(
+          `DELETE FROM ${ident} WHERE ${whereSqlParts.join(" AND ")}`,
+          whereParams
+        );
+      }
+      if (op === "describe") {
+        const [info, fks, count] = await Promise.all([
+          this.query(`PRAGMA table_info(${ident})`),
+          this.query(`PRAGMA foreign_key_list(${ident})`),
+          this.query(`SELECT COUNT(*) AS n FROM ${ident}`)
+        ]);
+        return {
+          table: t.name,
+          rowCount: Number(count.rows[0]?.[0] ?? 0),
+          columns: info.data,
+          foreignKeys: fks.data
+        };
+      }
+      const where = input.where ?? {};
+      const colSet = new Set(t.columns.map((c) => c.name));
+      const clauses = [];
+      const params = [];
+      for (const [k, v] of Object.entries(where)) {
+        if (!colSet.has(k)) throw new Error(`Unknown column: ${k}`);
+        if (v === null) {
+          clauses.push(`${quoteIdent(k)} IS NULL`);
+        } else {
+          clauses.push(`${quoteIdent(k)} = ?`);
+          params.push(v);
+        }
+      }
+      const whereSql = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+      if (op === "count") {
+        const r2 = await this.query(`SELECT COUNT(*) AS n FROM ${ident}${whereSql}`, params);
+        return { count: Number(r2.rows[0]?.[0] ?? 0) };
+      }
+      const limit = Math.min(1e3, Math.max(1, Number(input.limit ?? 100)));
+      let orderSql = "";
+      if (typeof input.orderBy === "string" && input.orderBy.trim()) {
+        const ob = input.orderBy.trim();
+        const obMatch = ob.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*(asc|desc)?$/i);
+        if (!obMatch) throw new Error("orderBy must be `<col>` or `<col> ASC|DESC`");
+        const [, col, dir] = obMatch;
+        if (!colSet.has(col)) throw new Error(`Unknown column: ${col}`);
+        orderSql = ` ORDER BY ${quoteIdent(col)} ${(dir ?? "ASC").toUpperCase()}`;
+      }
+      const r = await this.query(
+        `SELECT * FROM ${ident}${whereSql}${orderSql} LIMIT ${limit}`,
+        params
+      );
+      return r;
+    };
+    const aiSdk = () => {
+      const out = {};
+      for (const t of anthropic) {
+        out[t.name] = {
+          description: t.description,
+          inputSchema: t.input_schema,
+          execute: (input) => run(t.name, input)
+        };
+      }
+      return out;
+    };
+    const mastra = () => {
+      const out = {};
+      for (const t of anthropic) {
+        out[t.name] = {
+          id: t.name,
+          description: t.description,
+          inputSchema: t.input_schema,
+          execute: ({ context }) => run(t.name, context)
+        };
+      }
+      return out;
+    };
+    const langchain = () => anthropic.map((t) => ({
+      name: t.name,
+      description: t.description,
+      schema: t.input_schema,
+      invoke: (input) => run(t.name, input)
+    }));
+    const openaiAgents = () => anthropic.map((t) => ({
+      type: "function",
+      name: t.name,
+      description: t.description,
+      parameters: t.input_schema,
+      invoke: (input) => run(t.name, input)
+    }));
+    return { anthropic, openai, run, aiSdk, mastra, langchain, openaiAgents };
+  }
+};
+function sanitizeToolPart(s) {
+  return s.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function quoteIdent(s) {
+  return `"${s.replace(/"/g, '""')}"`;
+}
+var PerSQLBlob = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /** Upload a blob. Body can be ArrayBuffer, Blob, ReadableStream, or string. */
+  async put(key, body, opts = {}) {
+    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
+    return this.client.requestRaw(
+      "PUT",
+      path,
+      body,
+      opts.contentType
+    );
+  }
+  /** Fetch a blob. Returns null if missing. */
+  async get(key) {
+    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
+    const res = await this.client.fetchRaw("GET", path);
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new PerSQLError(res.status, `Blob fetch failed (${res.status})`);
+    }
+    return res;
+  }
+  /** Delete a blob. */
+  async delete(key) {
+    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
+    await this.client.request("DELETE", path);
+  }
+  /** List blobs by prefix. */
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.prefix) params.set("prefix", opts.prefix);
+    if (opts.cursor) params.set("cursor", opts.cursor);
+    if (opts.limit) params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    const path = `/v1/db/${this.namespace}/${this.slug}/blobs` + (qs ? `?${qs}` : "");
+    return this.client.request("GET", path);
+  }
+};
+function encodeBlobKey(key) {
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+var PerSQLVectors = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /** Embed and upsert up to 100 items in one call. */
+  async upsert(items) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/vectors`,
+      { items }
+    );
+  }
+  /** Top-K nearest neighbours by free-text query. */
+  async query(text, opts = {}) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/vectors/query`,
+      { query: text, topK: opts.topK, filter: opts.filter }
+    );
+  }
+  /** Delete vectors by id. Up to 1000 ids per call. */
+  async delete(ids) {
+    return this.client.request(
+      "DELETE",
+      `/v1/db/${this.namespace}/${this.slug}/vectors`,
+      { ids }
+    );
+  }
+};
+var PerSQLApprovals = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /**
+   * Redeem an approved approvalToken. The bearer must be the same one
+   * that minted it, and the request must target the same database.
+   * Returns the result of the originally-blocked query or batch.
+   */
+  async redeem(approvalToken) {
+    const raw = await this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/redeem_approval`, {
+      approvalToken
+    });
+    if (Array.isArray(raw)) {
+      return raw.map((r) => ({
+        ...r,
+        data: rowsToObjects(r.columns, r.rows)
+      }));
+    }
+    return { ...raw, data: rowsToObjects(raw.columns, raw.rows) };
+  }
+};
+var PerSQLProposals = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /**
+   * Pre-flight an SQL statement. EXPLAIN-validates, estimates affected
+   * rows, and returns a single-use `executionToken` valid for 10 min
+   * (override with `ttlSec`, max 1 hour). Nothing is mutated until
+   * `apply()` is called.
+   */
+  async propose(sql, opts = {}) {
+    if (this.client.local) {
+      return this.client.local.propose(sql, opts.params ?? [], opts.ttlSec);
+    }
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/propose`,
+      {
+        sql,
+        params: opts.params ?? [],
+        ttlSec: opts.ttlSec
+      }
+    );
+  }
+  /**
+   * Redeem an `executionToken` from `propose()`. Single-use — calling
+   * twice with the same token throws 404. The token is also pinned to
+   * the originating bearer + database; cross-token redemption throws
+   * 403.
+   */
+  async apply(executionToken) {
+    if (this.client.local) {
+      const raw2 = await this.client.local.apply(executionToken);
+      return { ...raw2, data: rowsToObjects(raw2.columns, raw2.rows) };
+    }
+    const raw = await this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/apply`, { executionToken });
+    return {
+      ...raw,
+      data: rowsToObjects(raw.columns, raw.rows)
+    };
+  }
+};
+var PerSQLBranches = class {
+  constructor(client, namespace, slug) {
+    this.client = client;
+    this.namespace = namespace;
+    this.slug = slug;
+  }
+  /**
+   * One-shot lease — create or reset a branch with a TTL and mint a
+   * scoped token in the same call. Use at the start of an agent run
+   * instead of chaining create + token mint.
+   */
+  async claim(opts = {}) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/claim_branch`,
+      opts
+    );
+  }
+  /** List branches of this database. Any-role token. */
+  async list(opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    if (opts.pageSize) qs.set("pageSize", String(opts.pageSize));
+    const tail = qs.toString() ? `?${qs.toString()}` : "";
+    const res = await this.client.fetchRaw(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/branches${tail}`
+    );
+    const body = await res.json();
+    if (!res.ok || !body.success) {
+      throw new PerSQLError(res.status, body.error ?? `Request failed (${res.status})`);
+    }
+    return { data: body.data ?? [], nextCursor: body.nextCursor ?? null };
+  }
+  /**
+   * Create-or-reset a branch by ref. Idempotent: re-PUTting the same
+   * ref refreshes the branch from the parent's current state.
+   * Requires an admin-role token.
+   */
+  async upsert(ref, opts = {}) {
+    return this.client.request(
+      "PUT",
+      `/v1/db/${this.namespace}/${this.slug}/branches/${encodeURIComponent(ref)}`,
+      {
+        name: opts.name,
+        region: opts.region,
+        ttlDays: opts.ttlDays ?? null
+      }
+    );
+  }
+  /** Delete a branch by ref. Requires an admin-role token. */
+  async delete(ref) {
+    return this.client.request(
+      "DELETE",
+      `/v1/db/${this.namespace}/${this.slug}/branches/${encodeURIComponent(ref)}`
+    );
+  }
+  /**
+   * Apply a branch back into its parent. `preview: true` returns the
+   * plan without writing. Requires an admin-role token.
+   */
+  async merge(ref, opts = {}) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/branches/${encodeURIComponent(ref)}/merge`,
+      {
+        mode: opts.mode ?? "schema",
+        preview: opts.preview === true,
+        dropRemoved: opts.dropRemoved === true,
+        snapshot: opts.snapshot !== false
+      }
+    );
+  }
+  /** Convenience for `merge(ref, { preview: true, ...opts })`. */
+  preview(ref, opts = {}) {
+    return this.merge(ref, { ...opts, preview: true });
+  }
+  /**
+   * Mint a single-use handoff token for this branch. The receiving
+   * agent calls `PerSQL.fromHandoff(token)` to redeem it for a
+   * regular bearer token scoped to exactly this (database, branch,
+   * role) — the agent that minted the handoff never has to share
+   * its own token. Single-use, ≤24h TTL.
+   */
+  async pin(ref, opts = {}) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/branches/${encodeURIComponent(ref)}/pin`,
+      { role: opts.role ?? "write", ttlSec: opts.ttlSec }
+    );
+  }
+  /**
+   * Render the branch's schema delta as a committable SQL migration.
+   * Read-only. Returns `{ name, sql, plan, summary }` — `name` is a
+   * timestamped filename (`YYYYMMDDHHMMSS_branch_<ref>.sql`) safe to
+   * write to disk; `sql` is the migration body wrapped in a single
+   * BEGIN/COMMIT.
+   */
+  async migration(ref, opts = {}) {
+    return this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/branches/${encodeURIComponent(ref)}/migration`,
+      { dropRemoved: opts.dropRemoved === true }
+    );
+  }
+};
+function rowsToObjects(columns, rows) {
+  return rows.map((r) => {
+    const obj = {};
+    for (let i = 0; i < columns.length; i++) obj[columns[i]] = r[i];
+    return obj;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApprovalRequiredError,
+  PerSQL,
+  PerSQLApprovals,
+  PerSQLBlob,
+  PerSQLBranches,
+  PerSQLDatabase,
+  PerSQLError,
+  PerSQLProposals,
+  PerSQLVectors,
+  RateLimitError
+});
+//# sourceMappingURL=index.cjs.map