@persql/sdk 1.0.0 → 1.2.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   PerSQL
-} from "./chunk-ZRZANHPI.js";
+} from "./chunk-GH75ERQ6.js";
 
 // src/cli.ts
 import { writeFile } from "fs/promises";

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   PerSQLApprovals: () => PerSQLApprovals,
   PerSQLBranches: () => PerSQLBranches,
   PerSQLDatabase: () => PerSQLDatabase,
+  PerSQLDatabases: () => PerSQLDatabases,
   PerSQLError: () => PerSQLError,
   PerSQLProposals: () => PerSQLProposals,
   RateLimitError: () => RateLimitError,
@@ -316,8 +317,23 @@ var PerSQL = class _PerSQL {
     }
     return new PerSQLDatabase(this, ns, slug);
   }
+  /**
+   * Provision and list databases in the token's namespace. `create`
+   * needs an unscoped admin token; `database()` then gives you a handle
+   * to query the result.
+   */
+  get databases() {
+    return new PerSQLDatabases(this);
+  }
   /** @internal */
   async request(method, path, body, headers) {
+    return (await this.requestWithMeta(method, path, body, headers)).data;
+  }
+  /**
+   * @internal — like `request`, but also surfaces the response `meta`
+   * envelope (usage + `costUsd`) that the data-only `request` drops.
+   */
+  async requestWithMeta(method, path, body, headers) {
     const res = await this._fetch(`${this.baseURL}${path}`, {
       method,
       headers: {
@@ -349,7 +365,7 @@ var PerSQL = class _PerSQL {
       }
       throw new PerSQLError(res.status, message, envelope?.errorDetail);
     }
-    return envelope.data;
+    return { data: envelope.data, meta: envelope.meta };
   }
   /** @internal — raw fetch returning the underlying Response. */
   fetchRaw(method, path) {
@@ -420,6 +436,44 @@ var SupportClient = class {
     );
   }
 };
+var PerSQLDatabases = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Provision a new isolated database and return its metadata. Requires
+   * an unscoped admin token (scoped tokens can't create databases).
+   */
+  async create(opts) {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: databases.create() needs a server-mode token. Pass a real token to `new PerSQL({ token })` to provision databases."
+      );
+    }
+    return this.client.request("POST", "/v1/databases", {
+      name: opts.name,
+      slug: opts.slug,
+      region: opts.region,
+      ttlDays: opts.ttlDays
+    });
+  }
+  /** List databases in the token's namespace, newest first (paginated). */
+  async list(opts = {}) {
+    if (this.client.local) {
+      throw new Error("PerSQL: databases.list() needs a server-mode token.");
+    }
+    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/databases${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 };
+  }
+};
 var PerSQLDatabase = class {
   constructor(client, namespace, slug) {
     this.client = client;
@@ -436,7 +490,7 @@ var PerSQLDatabase = class {
     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(
+    const { data: raw, meta } = await this.client.requestWithMeta(
       "POST",
       `/v1/db/${this.namespace}/${this.slug}/query`,
       { sql, params },
@@ -444,7 +498,8 @@ var PerSQLDatabase = class {
     );
     return {
       ...raw,
-      data: rowsToObjects(raw.columns, raw.rows)
+      data: rowsToObjects(raw.columns, raw.rows),
+      meta
     };
   }
   /** Run multiple statements in one round-trip, optionally in a transaction. */
@@ -802,6 +857,55 @@ var PerSQLDatabase = class {
       }
     };
   }
+  /**
+   * Long-poll for row-changes on this database. Returns immediately
+   * if changes newer than `since` are already buffered; otherwise
+   * blocks server-side for up to `waitMs` (default 25s, max 25s).
+   *
+   * Most callers want `changes()` instead — an async iterator that
+   * loops `waitForChanges` forever, surfacing each batch as it
+   * arrives.
+   */
+  async waitForChanges(opts = {}) {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: waitForChanges requires the DO change ring \u2014 not available in local mode."
+      );
+    }
+    const qs = new URLSearchParams();
+    if (typeof opts.since === "number") qs.set("since", String(opts.since));
+    if (typeof opts.waitMs === "number") qs.set("waitMs", String(opts.waitMs));
+    if (opts.tables && opts.tables.length > 0) qs.set("tables", opts.tables.join(","));
+    const q = qs.toString();
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/changes${q ? `?${q}` : ""}`
+    );
+  }
+  /**
+   * Async-iterator change feed. Loops `waitForChanges` forever and
+   * yields one batch per server response. Pass an `AbortSignal` to
+   * stop the loop cleanly.
+   *
+   * ```ts
+   * const ctl = new AbortController();
+   * for await (const batch of db.changes({ signal: ctl.signal })) {
+   *   for (const c of batch.changes) console.log(c.kind, c.table);
+   * }
+   * ```
+   */
+  async *changes(opts = {}) {
+    let cursor = opts.since ?? 0;
+    while (!opts.signal?.aborted) {
+      const batch = await this.waitForChanges({
+        since: cursor,
+        waitMs: opts.waitMs,
+        tables: opts.tables
+      });
+      cursor = batch.cursor;
+      yield batch;
+    }
+  }
   /**
    * Returns the callback shape `drizzle-orm/sqlite-proxy` expects.
    * Pair with `drizzle()` from that module to get a typed,
@@ -838,7 +942,7 @@ var PerSQLDatabase = class {
    * `execute`/`invoke` callbacks, which call `runTool` internally).
    */
   asTool(name = "persql_query") {
-    const description = `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}". Returns up to 1000 rows. Use parameter binding (?) to avoid injection.`;
+    const description = `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}". A single result is capped at 100,000 rows and the query errors above that \u2014 add a LIMIT for large tables. Use parameter binding (?) to avoid injection.`;
     const inputSchema = {
       type: "object",
       properties: {
@@ -849,7 +953,10 @@ var PerSQLDatabase = class {
           description: "Positional parameters for the SQL statement"
         }
       },
-      required: ["sql"]
+      required: ["sql"],
+      // OpenAI strict function-calling rejects a schema without this; the
+      // per-table asTools() schemas already set it. Keep them consistent.
+      additionalProperties: false
     };
     const execute = (input) => this.runTool({
       sql: String(input.sql ?? ""),
@@ -1808,6 +1915,11 @@ var PerSQLProposals = class {
    * rows, and returns a single-use `executionToken` valid for 10 min
    * (override with `ttlSec`, max 1 hour). Nothing is mutated until
    * `apply()` is called.
+   *
+   * Local mode keeps the token in-process: single-use still holds, but
+   * `estimatedAffectedRows` is always `null` (no server estimator) and a
+   * stale/unknown token throws a plain `Error` rather than the HTTP
+   * 404/403 of the server path.
    */
   async propose(sql, opts = {}) {
     if (this.client.local) {
@@ -1962,6 +2074,7 @@ function rowsToObjects(columns, rows) {
   PerSQLApprovals,
   PerSQLBranches,
   PerSQLDatabase,
+  PerSQLDatabases,
   PerSQLError,
   PerSQLProposals,
   RateLimitError,