@persql/sdk 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,9 +1,13 @@
+/** Wire-shape query result — columns plus positional rows, before the SDK reshapes rows into objects. */
 interface RawQueryResult {
     columns: string[];
     rows: unknown[][];
     rowsRead: number;
     rowsWritten: number;
+    changes?: number;
+    lastInsertRowid?: number;
 }
+/** In-process driver backing `new PerSQL({ local })` — runs SQL through `better-sqlite3` instead of the HTTP API. */
 declare class LocalDriver {
     private readonly path;
     private db;
@@ -46,7 +50,14 @@ declare class LocalDriver {
  *   );
  */
 
+/** Machine-readable category of a SQL failure, parsed from the engine's error message. */
 type SqlErrorKind = "unique_violation" | "not_null_violation" | "fk_violation" | "check_violation" | "unknown_table" | "unknown_column" | "syntax_error" | "type_mismatch" | "database_locked" | "too_many_params" | "readonly" | "unknown";
+/**
+ * Structured SQL error envelope — the failure kind plus the table,
+ * column, constraint, and hint parsed from the engine message.
+ * Available as `PerSQLError.detail` so callers can branch on
+ * `detail.kind` instead of string-matching messages.
+ */
 interface SqlErrorDetail {
     kind: SqlErrorKind;
     message: string;
@@ -60,6 +71,7 @@ interface SqlErrorDetail {
     near?: string;
     hint?: string;
 }
+/** Constructor options for `PerSQL`. */
 interface PerSQLOptions {
     /** Bearer token. Get one at https://console.persql.com → Tokens. */
     token?: string;
@@ -82,6 +94,10 @@ interface PerSQLOptions {
      */
     local?: string;
 }
+/**
+ * Result of a SQL statement — column names, positional rows, and the
+ * same rows reshaped as objects (`data`).
+ */
 interface QueryResult<T = Record<string, unknown>> {
     /** Column names in result-set order. */
     columns: string[];
@@ -91,6 +107,14 @@ interface QueryResult<T = Record<string, unknown>> {
     data: T[];
     rowsRead: number;
     rowsWritten: number;
+    /**
+     * SQLite `changes()` after a write statement — the exact affected-row
+     * count ORMs expect (`rowsWritten` also counts index writes). Absent
+     * on reads, DDL, and servers older than this field.
+     */
+    changes?: number;
+    /** SQLite `last_insert_rowid()` after a write statement. Absent on reads and DDL. */
+    lastInsertRowid?: number;
     /**
      * Per-call usage and cost the server echoes on `query()`. Undefined in
      * local mode (no server) and on the per-statement results of `batch()`
@@ -116,6 +140,7 @@ interface QueryMeta {
     } | null;
     queryLogId: string;
 }
+/** Options for `db.batch()` — transaction wrapping and idempotency / plan-replay keys. */
 interface BatchOptions {
     /** Wrap all statements in BEGIN/COMMIT. Rolls back on first error. */
     transaction?: boolean;
@@ -212,6 +237,7 @@ interface SchemaDoctorReport {
     tablesScanned: number;
     generatedAt: string;
 }
+/** Per-call options for `db.query()` — idempotency and plan-replay keys. */
 interface QueryOptions {
     idempotencyKey?: string;
     /** See `BatchOptions.planKey`. */
@@ -219,6 +245,7 @@ interface QueryOptions {
     /** See `BatchOptions.planStep`. */
     planStep?: string;
 }
+/** One user table and its row count, as returned by `db.tables()`. */
 interface TableInfo {
     name: string;
     rowCount: number;
@@ -246,6 +273,7 @@ interface BatchExpect {
     rowsWrittenAtLeast?: number;
     rowsWrittenAtMost?: number;
 }
+/** One entry of a `db.batch()` call — SQL, positional params, and an optional server-side assertion. */
 interface Statement {
     sql: string;
     params?: unknown[];
@@ -290,15 +318,22 @@ type ValidateResult = {
     error: string;
     errorDetail?: SqlErrorDetail;
 };
+/**
+ * Thrown for any failed API call. `status` carries the HTTP status;
+ * `detail` (set on /query and /batch failures) is the parsed SQL
+ * error envelope.
+ */
 declare class PerSQLError extends Error {
     status: number;
     detail?: SqlErrorDetail;
     constructor(status: number, message: string, detail?: SqlErrorDetail);
 }
+/** Thrown on HTTP 429. `retryAfterSeconds` echoes the server's Retry-After header. */
 declare class RateLimitError extends PerSQLError {
     retryAfterSeconds: number;
     constructor(retryAfterSeconds: number, message?: string);
 }
+/** One approval rule a blocked write matched — which glob hit which table, and whether it requires approval or denies outright. */
 interface ApprovalRuleHit {
     ruleId: string;
     tableGlob: string;
@@ -325,6 +360,16 @@ declare class ApprovalRequiredError extends PerSQLError {
         expiresAt: string;
     });
 }
+/**
+ * Entry point of the SDK. Construct with a bearer token — or with
+ * `{ local: ":memory:" }` for an in-process SQLite test database —
+ * then call `database()` for a handle to query.
+ *
+ * ```ts
+ * const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
+ * const db = persql.database("acme/orders");
+ * ```
+ */
 declare class PerSQL {
     /** @internal — exposed read-only so PerSQLDatabase can build URLs. */
     readonly token: string;
@@ -406,6 +451,7 @@ declare class PerSQL {
      */
     get support(): SupportClient;
 }
+/** Input for `persql.support.createTicket()`. */
 interface CreateSupportTicketOptions {
     subject: string;
     body: string;
@@ -414,6 +460,7 @@ interface CreateSupportTicketOptions {
     /** Caller-supplied extras merged into the ticket's diagnostic context. */
     errorContext?: Record<string, unknown>;
 }
+/** Files support tickets from SDK code. Reached via `persql.support`. */
 declare class SupportClient {
     private readonly client;
     constructor(client: PerSQL);
@@ -421,6 +468,7 @@ declare class SupportClient {
         id: string;
     }>;
 }
+/** Database metadata as returned by `persql.databases.create()` and `list()`. */
 interface DatabaseInfo {
     id: string;
     namespaceId: string;
@@ -435,6 +483,7 @@ interface DatabaseInfo {
     createdAt: string;
     updatedAt: string;
 }
+/** Input for `persql.databases.create()`. */
 interface CreateDatabaseOptions {
     /** Display name, 1-50 chars. */
     name: string;
@@ -466,6 +515,11 @@ declare class PerSQLDatabases {
         nextCursor: string | null;
     }>;
 }
+/**
+ * Handle to one database, addressed as `<namespace>/<slug>`. Obtained
+ * via `persql.database(...)`; all query, schema, branch, approval, and
+ * tool helpers live here.
+ */
 declare class PerSQLDatabase {
     private readonly client;
     readonly namespace: string;
@@ -730,7 +784,7 @@ declare class PerSQLDatabase {
     runTool(input: {
         sql: string;
         params?: unknown[];
-    }): Promise<QueryResult<Record<string, unknown>>>;
+    }): Promise<QueryResult>;
     /**
      * Generate a *bundle* of typed tools — one per table — instead of one
      * generic `query` tool. Agents perform dramatically better with narrow
@@ -762,11 +816,13 @@ declare class PerSQLDatabase {
      */
     asTools(): Promise<DatabaseToolBundle>;
 }
+/** Tool definition in the Anthropic Messages API shape — one `tools` entry for `messages.create`. */
 interface AnthropicTool {
     name: string;
     description: string;
     input_schema: Record<string, unknown>;
 }
+/** Tool definition in the OpenAI Chat Completions shape — one `tools` entry for `chat.completions.create`. */
 interface OpenAiTool {
     type: "function";
     function: {
@@ -775,6 +831,7 @@ interface OpenAiTool {
         parameters: Record<string, unknown>;
     };
 }
+/** Output of `db.asTool()` — one SQL-query tool rendered in every supported framework shape. */
 interface SingleToolBundle {
     /** Anthropic shape — pass as one entry of `tools` to messages.create. */
     anthropic: AnthropicTool;
@@ -789,6 +846,7 @@ interface SingleToolBundle {
     /** OpenAI Agents SDK shape — hand to `Agent({ tools: [...] })`. */
     openaiAgents: () => OpenAiAgentsTool[];
 }
+/** Output of `db.asTools()` — typed per-table tools plus the `run` dispatcher, in every supported framework shape. */
 interface DatabaseToolBundle {
     /** Tool definitions in Anthropic shape — pass as `tools` to messages.create. */
     anthropic: AnthropicTool[];
@@ -822,11 +880,13 @@ interface DatabaseToolBundle {
      */
     openaiAgents: () => OpenAiAgentsTool[];
 }
+/** Tool shape for the Vercel AI SDK — spread into `streamText({ tools })`. */
 interface AiSdkTool {
     description: string;
     inputSchema: Record<string, unknown>;
     execute: (input: Record<string, unknown>) => Promise<unknown>;
 }
+/** Tool shape for Mastra — wrap with `createTool()` if you need the Mastra envelope. */
 interface MastraTool {
     id: string;
     description: string;
@@ -858,11 +918,14 @@ interface OpenAiAgentsTool {
     parameters: Record<string, unknown>;
     invoke: (input: Record<string, unknown>) => Promise<unknown>;
 }
+/** Kind of row change reported by `db.subscribe()` and `db.changes()`. */
 type SubscribeChangeKind = "update" | "insert" | "delete" | "schema" | "unknown";
+/** One row-change event delivered to `SubscribeOptions.onChange`. */
 interface SubscribeChange {
     table: string;
     kind: SubscribeChangeKind;
 }
+/** Options for `db.subscribe()` — table filter and event callbacks. */
 interface SubscribeOptions {
     /** Tables to listen to. Omit / empty / `["*"]` = all tables. */
     tables?: string[];
@@ -895,7 +958,12 @@ interface BranchInfo {
         name: string;
     };
 }
+/**
+ * How a branch is applied back to its parent: `schema` applies the DDL
+ * delta; `promote` replaces the parent's contents wholesale.
+ */
 type BranchMergeMode = "schema" | "promote";
+/** One DDL operation in a branch-merge plan: create, drop, or replace. */
 type BranchMergePlanStep = {
     op: "create";
     type: string;
@@ -912,6 +980,7 @@ type BranchMergePlanStep = {
     beforeSql: string;
     afterSql: string;
 };
+/** Outcome of `db.branches.merge()` — what was applied, the pre-merge snapshot, and the plan when previewing. */
 interface BranchMergeResult {
     mode: BranchMergeMode;
     preview: boolean;
@@ -925,6 +994,7 @@ interface BranchMergeResult {
     };
     note?: string;
 }
+/** Options for `db.branches.upsert()`. */
 interface BranchUpsertOptions {
     /** Human-readable name. Defaults to `<parent name> (<ref>)`. */
     name?: string;
@@ -933,6 +1003,7 @@ interface BranchUpsertOptions {
     /** Auto-delete after N days (1..30). Null/undefined = keep until deleted. */
     ttlDays?: number | null;
 }
+/** Options for `db.branches.merge()`. */
 interface BranchMergeOptions {
     /** Default `schema`. `promote` replaces parent contents wholesale. */
     mode?: BranchMergeMode;
@@ -943,6 +1014,7 @@ interface BranchMergeOptions {
     /** Default true — captures `pre-merge:<ref>` snapshot of the parent. */
     snapshot?: boolean;
 }
+/** Output of `db.proposals.propose()` — the EXPLAIN plan, estimated affected rows, and the single-use execution token. */
 interface ProposalPlan {
     sql: string;
     plan: unknown[][];
@@ -951,10 +1023,12 @@ interface ProposalPlan {
     expiresAt: string;
     action: "read" | "write" | "admin";
 }
+/** Options for `db.proposals.propose()`. */
 interface ProposeOptions {
     params?: unknown[];
     ttlSec?: number;
 }
+/** Lifecycle state of an approval token, as returned by `db.approvals.get()` and `poll()`. */
 interface ApprovalStatus {
     status: "pending" | "approved" | "denied";
     hits: ApprovalRuleHit[];
@@ -962,6 +1036,7 @@ interface ApprovalStatus {
     expiresAt: string;
     decidedAt: string | null;
 }
+/** Pacing and cancellation options for `db.approvals.poll()`. */
 interface PollApprovalOptions {
     /** Default 2000ms. */
     intervalMs?: number;
@@ -970,6 +1045,7 @@ interface PollApprovalOptions {
     /** Cancellation signal. */
     signal?: AbortSignal;
 }
+/** Callbacks and pacing for `db.approvals.subscribe()`. */
 interface SubscribeApprovalOptions {
     onApprovalRequired?: (event: ApprovalEvent) => void;
     onApprovalResolved?: (event: ApprovalEvent) => void;
@@ -980,11 +1056,17 @@ interface SubscribeApprovalOptions {
     /** Logged-by-default error sink. */
     onError?: (err: Error) => void;
 }
+/** One approval state change delivered by `db.approvals.subscribe()`. */
 interface ApprovalEvent {
     approvalToken: string;
     status: "pending" | "approved" | "denied";
     hits: ApprovalRuleHit[];
 }
+/**
+ * Approval-token lifecycle for writes blocked by a require_approval
+ * rule — look up, poll, subscribe, and redeem. Reached via
+ * `db.approvals`.
+ */
 declare class PerSQLApprovals {
     private readonly client;
     private readonly namespace;
@@ -1023,6 +1105,7 @@ declare class PerSQLApprovals {
      */
     redeem<T = Record<string, unknown>>(approvalToken: string): Promise<QueryResult<T> | QueryResult<T>[]>;
 }
+/** A require_approval / deny rule on a database, as returned by `db.approvalRules.list()`. */
 interface ApprovalRule {
     id: string;
     databaseId: string;
@@ -1032,11 +1115,13 @@ interface ApprovalRule {
     createdById: string;
     createdAt: string;
 }
+/** Input for `db.approvalRules.create()`. */
 interface CreateApprovalRuleInput {
     tableGlob: string;
     action: "require_approval" | "deny";
     note?: string;
 }
+/** Manage the require_approval / deny rules of a database. Reached via `db.approvalRules`. */
 declare class PerSQLApprovalRules {
     private readonly client;
     private readonly namespace;
@@ -1050,6 +1135,11 @@ declare class PerSQLApprovalRules {
         deleted: true;
     }>;
 }
+/**
+ * Two-phase writes: `propose()` pre-flights the SQL and mints a
+ * single-use execution token; `apply()` redeems it. Reached via
+ * `db.proposals`.
+ */
 declare class PerSQLProposals {
     private readonly client;
     private readonly namespace;
@@ -1075,6 +1165,7 @@ declare class PerSQLProposals {
      */
     apply<T = Record<string, unknown>>(executionToken: string): Promise<QueryResult<T>>;
 }
+/** Output of `db.branches.claim()` — the fresh branch plus the scoped token minted for it. */
 interface ClaimedBranch {
     branchRef: string;
     databaseId: string;
@@ -1087,6 +1178,7 @@ interface ClaimedBranch {
     expiresAt: string;
     outcome: "created" | "reset";
 }
+/** Options for `db.branches.claim()`. */
 interface ClaimBranchOptions {
     /** Explicit ref. Omit to auto-generate from `purpose`. */
     ref?: string;
@@ -1098,6 +1190,11 @@ interface ClaimBranchOptions {
     role?: "read" | "write" | "admin";
     region?: string;
 }
+/**
+ * Branch management for one database — list, create-or-reset, delete,
+ * merge, pin (handoff), claim (lease), and migration rendering.
+ * Reached via `db.branches`.
+ */
 declare class PerSQLBranches {
     private readonly client;
     private readonly namespace;

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   PerSQLProposals,
   RateLimitError,
   SupportClient
-} from "./chunk-GH75ERQ6.js";
+} from "./chunk-SIJU2P7U.js";
 export {
   ApprovalRequiredError,
   PerSQL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persql/sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "TypeScript SDK for PerSQL — SQLite databases on the edge for AI agents",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "vitest": "^3.1.1"
   },
   "peerDependencies": {
-    "better-sqlite3": "^11.0.0"
+    "better-sqlite3": "^11.0.0 || ^12.0.0"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {