@persql/sdk 1.0.0 → 1.1.0

package/dist/cli.js

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

package/dist/index.cjs

@@ -802,6 +802,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 +887,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 +898,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 +1860,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) {