@persql/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,926 @@
+interface RawQueryResult {
+    columns: string[];
+    rows: unknown[][];
+    rowsRead: number;
+    rowsWritten: number;
+}
+declare class LocalDriver {
+    private readonly path;
+    private db;
+    private readonly proposals;
+    constructor(path: string);
+    private open;
+    query(sql: string, params: unknown[]): Promise<RawQueryResult>;
+    batch(statements: Statement[], transaction: boolean): Promise<RawQueryResult[]>;
+    tables(): Promise<Array<{
+        name: string;
+        rowCount: number;
+    }>>;
+    explain(sql: string, params: unknown[]): Promise<Array<{
+        id: number;
+        parent: number;
+        detail: string;
+    }>>;
+    propose(sql: string, params: unknown[], ttlSec?: number): Promise<{
+        sql: string;
+        plan: unknown[][];
+        estimatedAffectedRows: number | null;
+        executionToken: string;
+        expiresAt: string;
+        action: "read" | "write" | "admin";
+    }>;
+    apply(executionToken: string): Promise<RawQueryResult>;
+    private gcProposals;
+    close(): void;
+}
+
+/**
+ * @persql/sdk — Talk to your PerSQL databases from anywhere.
+ *
+ * @example
+ *   const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
+ *   const db = persql.database("acme/orders");
+ *   const rows = await db.query<{ id: number; email: string }>(
+ *     "SELECT id, email FROM customers WHERE id = ?",
+ *     [42]
+ *   );
+ */
+
+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";
+interface SqlErrorDetail {
+    kind: SqlErrorKind;
+    message: string;
+    table?: string;
+    column?: string;
+    columns?: Array<{
+        table: string;
+        column: string;
+    }>;
+    constraint?: string;
+    near?: string;
+    hint?: string;
+}
+interface PerSQLOptions {
+    /** Bearer token. Get one at https://console.persql.com → Tokens. */
+    token?: string;
+    /** API base URL. Defaults to https://api.persql.com */
+    baseURL?: string;
+    /** Custom fetch implementation (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /**
+     * Run against a local SQLite file (via the `better-sqlite3` peer
+     * dependency) instead of the HTTP API. Pass `":memory:"` for an
+     * in-memory test database. When set, `token` is not required and
+     * network features (`vectors`, `blob`, `subscribe`) throw —
+     * they have no local equivalent.
+     *
+     * ```ts
+     * const persql = new PerSQL({ local: ":memory:" });
+     * const db = persql.database("test/db");
+     * await db.query("CREATE TABLE t (id INTEGER)");
+     * ```
+     */
+    local?: string;
+}
+interface QueryResult<T = Record<string, unknown>> {
+    /** Column names in result-set order. */
+    columns: string[];
+    /** Rows as positional arrays (faster wire format). */
+    rows: unknown[][];
+    /** Rows reshaped as objects keyed by column name. */
+    data: T[];
+    rowsRead: number;
+    rowsWritten: number;
+}
+interface BatchOptions {
+    /** Wrap all statements in BEGIN/COMMIT. Rolls back on first error. */
+    transaction?: boolean;
+    /** Pass an Idempotency-Key for safe retries. */
+    idempotencyKey?: string;
+    /**
+     * Multi-step plan idempotency. Pair `planKey` (stable across the
+     * agent's plan) with `planStep` (stable per step). On retry, every
+     * step that already succeeded replays from cache; failed and
+     * never-reached steps re-run.
+     */
+    planKey?: string;
+    planStep?: string;
+}
+/**
+ * Metadata returned by `PerSQL.fromHandoff` describing what the
+ * minted token can touch. The token itself is already wired into the
+ * returned client; this is just the handoff's resource info so the
+ * agent doesn't have to round-trip again to know its scope.
+ */
+interface HandoffClaim {
+    tokenId: string;
+    databaseId: string;
+    databaseSlug: string;
+    namespaceSlug: string;
+    branchRef: string | null;
+    role: "read" | "write" | "admin";
+}
+/**
+ * Engine telemetry row — one entry per /v1/query or /v1/batch call.
+ * Returned by `db.queryLog()`. The same data is also exposed inside
+ * the DO as `_persql_meta_query_log` so agents can SELECT/JOIN it
+ * alongside their own tables.
+ */
+interface QueryLogEntry {
+    id: string;
+    ts: number;
+    sqlText: string;
+    paramsJson: string | null;
+    status: "ok" | "error";
+    errorMessage: string | null;
+    rowsRead: number;
+    rowsWritten: number;
+    durationMs: number;
+    statementCount: number;
+    tokenId: string | null;
+    snapshotId: string | null;
+}
+/**
+ * Output of `db.describe()`. Mirrors the schema graph with any
+ * stored semantic docs folded in. Designed to be JSON-stringified
+ * straight into an LLM prompt.
+ */
+interface DescribeBundle {
+    databaseDescription: string | null;
+    tables: Array<{
+        table: string;
+        description: string;
+        columns: Array<{
+            name: string;
+            type: string;
+            pk: boolean;
+            notNull: boolean;
+            description: string;
+        }>;
+        foreignKeys: Array<{
+            from: string;
+            toTable: string;
+            toColumn: string;
+        }>;
+    }>;
+}
+/** Output of `db.search(query)`. */
+interface SchemaSearchResponse {
+    query: string;
+    hits: Array<{
+        kind: "table" | "column";
+        table: string;
+        column: string | null;
+        description: string;
+        score: number;
+    }>;
+}
+/** Output of `db.doctor()`. */
+interface SchemaDoctorReport {
+    findings: Array<{
+        code: string;
+        severity: "info" | "warning" | "error";
+        table: string;
+        column: string | null;
+        message: string;
+        suggestion: string;
+    }>;
+    tablesScanned: number;
+    generatedAt: string;
+}
+interface QueryOptions {
+    idempotencyKey?: string;
+    /** See `BatchOptions.planKey`. */
+    planKey?: string;
+    /** See `BatchOptions.planStep`. */
+    planStep?: string;
+}
+interface TableInfo {
+    name: string;
+    rowCount: number;
+}
+interface Statement {
+    sql: string;
+    params?: unknown[];
+}
+declare class PerSQLError extends Error {
+    status: number;
+    detail?: SqlErrorDetail;
+    constructor(status: number, message: string, detail?: SqlErrorDetail);
+}
+declare class RateLimitError extends PerSQLError {
+    retryAfterSeconds: number;
+    constructor(retryAfterSeconds: number, message?: string);
+}
+interface ApprovalRuleHit {
+    ruleId: string;
+    tableGlob: string;
+    action: "require_approval" | "deny";
+    matchedTable: string;
+    note: string | null;
+}
+/**
+ * Thrown when a write hits an approval rule. The agent can either
+ * stop and surface `approvalUrl` to a human, or poll
+ * `db.approvals.poll(approvalToken)` until a member decides; once
+ * approved, redeem with `db.approvals.redeem(approvalToken)`.
+ */
+declare class ApprovalRequiredError extends PerSQLError {
+    approvalToken: string;
+    approvalUrl: string;
+    hits: ApprovalRuleHit[];
+    expiresAt: string;
+    constructor(opts: {
+        message: string;
+        approvalToken: string;
+        approvalUrl: string;
+        hits: ApprovalRuleHit[];
+        expiresAt: string;
+    });
+}
+declare class PerSQL {
+    /** @internal — exposed read-only so PerSQLDatabase can build URLs. */
+    readonly token: string;
+    /** @internal — same. */
+    readonly baseURL: string;
+    /** @internal — set when running in local mode. */
+    readonly local: LocalDriver | null;
+    private readonly _fetch;
+    constructor(opts: PerSQLOptions);
+    /** Close the local SQLite connection (no-op in HTTP mode). */
+    close(): void;
+    /**
+     * 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 fromHandoff(handoffToken: string, opts?: {
+        baseURL?: string;
+        name?: string;
+        fetch?: typeof fetch;
+    }): Promise<PerSQL & {
+        handedOff: HandoffClaim;
+    }>;
+    /**
+     * Reference a database by its `<namespace>/<slug>` path.
+     * Both forms work: `db("acme/orders")` or `db("acme", "orders")`.
+     */
+    database(path: string): PerSQLDatabase;
+    database(namespace: string, slug: string): PerSQLDatabase;
+    /** @internal */
+    request<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** @internal — raw upload (e.g. blob PUT) returning the ApiResponse data. */
+    requestRaw<T>(method: "PUT" | "POST", path: string, body: ArrayBuffer | Blob | ReadableStream | string, contentType?: string): Promise<T>;
+    /** @internal — raw fetch returning the underlying Response (used by blob GET). */
+    fetchRaw(method: "GET", path: string): Promise<Response>;
+}
+declare class PerSQLDatabase {
+    private readonly client;
+    readonly namespace: string;
+    readonly slug: string;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /** Run a single SQL statement. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[], options?: QueryOptions): Promise<QueryResult<T>>;
+    /** Run multiple statements in one round-trip, optionally in a transaction. */
+    batch<T = Record<string, unknown>>(statements: Statement[], options?: BatchOptions): Promise<QueryResult<T>[]>;
+    /** Convenience for a transactional batch. */
+    transaction<T = Record<string, unknown>>(statements: Statement[], options?: Omit<BatchOptions, "transaction">): Promise<QueryResult<T>[]>;
+    /**
+     * 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`.
+     */
+    queryLog(opts?: {
+        since?: string | Date;
+        until?: string | Date;
+        tokenId?: string;
+        status?: "ok" | "error";
+        cursor?: string;
+        pageSize?: number;
+    }): Promise<{
+        data: QueryLogEntry[];
+        nextCursor: string | 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.
+     */
+    describe(): Promise<DescribeBundle>;
+    /**
+     * 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.
+     */
+    setDescription(input: {
+        databaseDescription?: string;
+        tables?: Array<{
+            table: string;
+            description?: string;
+            columns?: Array<{
+                column: string;
+                description: string;
+            }>;
+        }>;
+    }): Promise<DescribeBundle>;
+    /**
+     * 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.
+     */
+    search(query: string, opts?: {
+        limit?: number;
+    }): Promise<SchemaSearchResponse>;
+    /**
+     * 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.
+     */
+    doctor(): Promise<SchemaDoctorReport>;
+    /** List user-defined tables in this database. */
+    tables(): Promise<TableInfo[]>;
+    /**
+     * Returns SQLite's `EXPLAIN QUERY PLAN` output for the given SQL.
+     * Read-only — does not execute the statement.
+     */
+    explain(sql: string, params?: unknown[]): Promise<Array<{
+        id: number;
+        parent: number;
+        detail: string;
+    }>>;
+    /**
+     * 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).
+     */
+    schema(): Promise<DatabaseSchema>;
+    /**
+     * 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(): PerSQLVectors;
+    /**
+     * 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(): PerSQLBranches;
+    /**
+     * 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(): PerSQLApprovals;
+    /**
+     * 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(): PerSQLProposals;
+    /**
+     * 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(): PerSQLBlob;
+    /**
+     * 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: SubscribeOptions): () => void;
+    /**
+     * 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(): SqliteProxyDriver;
+    /**
+     * Returns a tool definition for use with Anthropic / OpenAI / function-calling
+     * agents. Pair it with `runTool` to execute the call.
+     */
+    asTool(name?: string): {
+        anthropic: {
+            name: string;
+            description: string;
+            input_schema: {
+                type: string;
+                properties: {
+                    sql: {
+                        type: string;
+                        description: string;
+                    };
+                    params: {
+                        type: string;
+                        items: {};
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        openai: {
+            type: "function";
+            function: {
+                name: string;
+                description: string;
+                parameters: {
+                    type: string;
+                    properties: {
+                        sql: {
+                            type: string;
+                        };
+                        params: {
+                            type: string;
+                            items: {};
+                        };
+                    };
+                    required: string[];
+                };
+            };
+        };
+    };
+    /**
+     * Executes a tool-call payload returned from the model. Pair with `asTool`.
+     */
+    runTool(input: {
+        sql: string;
+        params?: unknown[];
+    }): Promise<QueryResult<Record<string, unknown>>>;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    asTools(): Promise<DatabaseToolBundle>;
+}
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface OpenAiTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface DatabaseToolBundle {
+    /** Tool definitions in Anthropic shape — pass as `tools` to messages.create. */
+    anthropic: AnthropicTool[];
+    /** Tool definitions in OpenAI shape — pass as `tools` to chat.completions.create. */
+    openai: OpenAiTool[];
+    /** Dispatch a model-emitted tool call back to the database. */
+    run: (name: string, input?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Vercel AI SDK shape — record of `{ [toolName]: { description, inputSchema, execute } }`.
+     * Spread into `streamText({ tools: { ...db.asTools().aiSdk() } })`. The
+     * `inputSchema` field is JSON Schema; pass through `jsonSchema()` from
+     * the `ai` package if your version of AI SDK requires it explicitly.
+     */
+    aiSdk: () => Record<string, AiSdkTool>;
+    /**
+     * Mastra shape — record of `{ [toolName]: { id, description, inputSchema, execute } }`.
+     * Useful for `createTool({...})` callsites. `inputSchema` is JSON Schema;
+     * if Mastra's runtime needs a Zod schema, run it through `json-schema-to-zod`
+     * or your preferred converter.
+     */
+    mastra: () => Record<string, MastraTool>;
+    /**
+     * LangChain shape — array of `{ name, description, schema, invoke }`.
+     * Wrap with `DynamicStructuredTool` or pass `invoke` directly to a
+     * custom agent loop.
+     */
+    langchain: () => LangChainTool[];
+    /**
+     * OpenAI Agents SDK shape — array of `{ type, name, description, parameters, invoke }`.
+     * Hand to `Agent({ tools: [...] })`.
+     */
+    openaiAgents: () => OpenAiAgentsTool[];
+}
+interface AiSdkTool {
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: Record<string, unknown>) => Promise<unknown>;
+}
+interface MastraTool {
+    id: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (context: {
+        context: Record<string, unknown>;
+    }) => Promise<unknown>;
+}
+/**
+ * LangChain shape — pass to `DynamicStructuredTool` or use `invoke`
+ * directly inside a custom agent. `schema` is JSON Schema; if your
+ * LangChain version requires Zod, convert with `json-schema-to-zod`.
+ */
+interface LangChainTool {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    invoke: (input: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * OpenAI Agents SDK shape — assign as a tool in `Agent` config. The
+ * Agents SDK uses `parameters` (JSON Schema) and a callable; our
+ * `invoke` matches the `function_tool` callback signature.
+ */
+interface OpenAiAgentsTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    invoke: (input: Record<string, unknown>) => Promise<unknown>;
+}
+type SubscribeChangeKind = "update" | "insert" | "delete" | "schema" | "unknown";
+interface SubscribeChange {
+    table: string;
+    kind: SubscribeChangeKind;
+}
+interface SubscribeOptions {
+    /** Tables to listen to. Omit / empty / `["*"]` = all tables. */
+    tables?: string[];
+    onChange: (change: SubscribeChange) => void;
+    /** Fires once when the server confirms the subscription. */
+    onReady?: (tables: string[] | "*") => void;
+    onError?: (error: Error) => void;
+    onClose?: () => void;
+}
+interface BlobListItem {
+    key: string;
+    sizeBytes: number;
+    etag: string;
+    uploadedAt: string;
+    contentType?: string;
+}
+interface BlobListResponse {
+    items: BlobListItem[];
+    truncated: boolean;
+    cursor?: string;
+}
+declare class PerSQLBlob {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /** Upload a blob. Body can be ArrayBuffer, Blob, ReadableStream, or string. */
+    put(key: string, body: ArrayBuffer | Blob | ReadableStream | string, opts?: {
+        contentType?: string;
+    }): Promise<{
+        key: string;
+        sizeBytes: number;
+        etag: string;
+    }>;
+    /** Fetch a blob. Returns null if missing. */
+    get(key: string): Promise<Response | null>;
+    /** Delete a blob. */
+    delete(key: string): Promise<void>;
+    /** List blobs by prefix. */
+    list(opts?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<BlobListResponse>;
+}
+interface VectorUpsertItem {
+    id: string;
+    text: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface VectorMatch {
+    id: string;
+    score: number;
+    metadata: Record<string, unknown>;
+}
+declare class PerSQLVectors {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /** Embed and upsert up to 100 items in one call. */
+    upsert(items: VectorUpsertItem[]): Promise<{
+        count: number;
+    }>;
+    /** Top-K nearest neighbours by free-text query. */
+    query(text: string, opts?: {
+        topK?: number;
+        filter?: Record<string, string | number | boolean>;
+    }): Promise<VectorMatch[]>;
+    /** Delete vectors by id. Up to 1000 ids per call. */
+    delete(ids: string[]): Promise<{
+        count: number;
+    }>;
+}
+/**
+ * Database row as returned by /v1 list/upsert branch responses.
+ * Mirrors the `Database` DTO from @persql/shared but kept narrow on
+ * purpose so the SDK doesn't drift if the server adds fields.
+ */
+interface BranchInfo {
+    id: string;
+    namespaceId: string;
+    slug: string;
+    name: string;
+    status: string;
+    region: string;
+    branchRef: string | null;
+    forkedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    forkedFrom?: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}
+type BranchMergeMode = "schema" | "promote";
+type BranchMergePlanStep = {
+    op: "create";
+    type: string;
+    name: string;
+    sql: string;
+} | {
+    op: "drop";
+    type: string;
+    name: string;
+} | {
+    op: "replace";
+    type: string;
+    name: string;
+    beforeSql: string;
+    afterSql: string;
+};
+interface BranchMergeResult {
+    mode: BranchMergeMode;
+    preview: boolean;
+    applied: number;
+    snapshotId: string | null;
+    plan?: BranchMergePlanStep[];
+    summary?: {
+        added: number;
+        changed: number;
+        removed: number;
+    };
+    note?: string;
+}
+interface BranchUpsertOptions {
+    /** Human-readable name. Defaults to `<parent name> (<ref>)`. */
+    name?: string;
+    /** Region hint: auto, wnam, enam, weur, eeur, apac. Default: auto. */
+    region?: string;
+    /** Auto-delete after N days (1..30). Null/undefined = keep until deleted. */
+    ttlDays?: number | null;
+}
+interface BranchMergeOptions {
+    /** Default `schema`. `promote` replaces parent contents wholesale. */
+    mode?: BranchMergeMode;
+    /** If true, returns the plan without writing. */
+    preview?: boolean;
+    /** Schema mode only — drop objects present in parent but not in branch. */
+    dropRemoved?: boolean;
+    /** Default true — captures `pre-merge:<ref>` snapshot of the parent. */
+    snapshot?: boolean;
+}
+interface ProposalPlan {
+    sql: string;
+    plan: unknown[][];
+    estimatedAffectedRows: number | null;
+    executionToken: string;
+    expiresAt: string;
+    action: "read" | "write" | "admin";
+}
+interface ProposeOptions {
+    params?: unknown[];
+    ttlSec?: number;
+}
+declare class PerSQLApprovals {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /**
+     * 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.
+     */
+    redeem<T = Record<string, unknown>>(approvalToken: string): Promise<QueryResult<T> | QueryResult<T>[]>;
+}
+declare class PerSQLProposals {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /**
+     * 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.
+     */
+    propose(sql: string, opts?: ProposeOptions): Promise<ProposalPlan>;
+    /**
+     * 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.
+     */
+    apply<T = Record<string, unknown>>(executionToken: string): Promise<QueryResult<T>>;
+}
+interface ClaimedBranch {
+    branchRef: string;
+    databaseId: string;
+    databaseSlug: string;
+    namespaceSlug: string;
+    /** Plaintext psql_live_/psql_test_ token. Returned once. */
+    token: string;
+    tokenId: string;
+    role: "read" | "write" | "admin";
+    expiresAt: string;
+    outcome: "created" | "reset";
+}
+interface ClaimBranchOptions {
+    /** Explicit ref. Omit to auto-generate from `purpose`. */
+    ref?: string;
+    /** Free-form label baked into the auto-ref + token name. */
+    purpose?: string;
+    /** Lease length in seconds. Default 3600 (1 hour), max 30 days. */
+    ttlSec?: number;
+    /** Default "write". */
+    role?: "read" | "write" | "admin";
+    region?: string;
+}
+declare class PerSQLBranches {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    /**
+     * 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.
+     */
+    claim(opts?: ClaimBranchOptions): Promise<ClaimedBranch>;
+    /** List branches of this database. Any-role token. */
+    list(opts?: {
+        cursor?: string;
+        pageSize?: number;
+    }): Promise<{
+        data: BranchInfo[];
+        nextCursor: string | 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.
+     */
+    upsert(ref: string, opts?: BranchUpsertOptions): Promise<BranchInfo>;
+    /** Delete a branch by ref. Requires an admin-role token. */
+    delete(ref: string): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Apply a branch back into its parent. `preview: true` returns the
+     * plan without writing. Requires an admin-role token.
+     */
+    merge(ref: string, opts?: BranchMergeOptions): Promise<BranchMergeResult>;
+    /** Convenience for `merge(ref, { preview: true, ...opts })`. */
+    preview(ref: string, opts?: Omit<BranchMergeOptions, "preview">): Promise<BranchMergeResult>;
+    /**
+     * 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.
+     */
+    pin(ref: string, opts?: {
+        role?: "read" | "write" | "admin";
+        ttlSec?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+        role: "read" | "write" | "admin";
+        databaseId: string;
+        branchRef: string | null;
+    }>;
+    /**
+     * 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.
+     */
+    migration(ref: string, opts?: {
+        dropRemoved?: boolean;
+    }): Promise<{
+        name: string;
+        sql: string;
+        plan: BranchMergePlanStep[];
+        summary: {
+            added: number;
+            changed: number;
+            removed: number;
+        };
+    }>;
+}
+/**
+ * Schema returned by `db.schema()`. One entry per user table.
+ */
+interface DatabaseSchema {
+    tables: Array<{
+        name: string;
+        columns: Array<{
+            name: string;
+            /** SQLite column type (TEXT, INTEGER, REAL, BLOB, NUMERIC). */
+            type: string;
+            notNull: boolean;
+            primaryKey: boolean;
+            default: string | null;
+        }>;
+    }>;
+}
+/**
+ * Callback shape used by Drizzle's `drizzle-orm/sqlite-proxy`.
+ * Returned by `db.driver()` so callers can plug PerSQL into Drizzle
+ * without taking a hard dep on it.
+ */
+type SqliteProxyDriver = (sql: string, params: unknown[], method: "all" | "run" | "get" | "values") => Promise<{
+    rows: unknown;
+}>;
+
+export { type AiSdkTool, type AnthropicTool, ApprovalRequiredError, type ApprovalRuleHit, type BatchOptions, type BlobListItem, type BlobListResponse, type BranchInfo, type BranchMergeMode, type BranchMergeOptions, type BranchMergePlanStep, type BranchMergeResult, type BranchUpsertOptions, type ClaimBranchOptions, type ClaimedBranch, type DatabaseSchema, type DatabaseToolBundle, type DescribeBundle, type HandoffClaim, type LangChainTool, type MastraTool, type OpenAiAgentsTool, type OpenAiTool, PerSQL, PerSQLApprovals, PerSQLBlob, PerSQLBranches, PerSQLDatabase, PerSQLError, type PerSQLOptions, PerSQLProposals, PerSQLVectors, type ProposalPlan, type ProposeOptions, type QueryLogEntry, type QueryOptions, type QueryResult, RateLimitError, type RawQueryResult, type SchemaDoctorReport, type SchemaSearchResponse, type SqlErrorDetail, type SqlErrorKind, type SqliteProxyDriver, type Statement, type SubscribeChange, type SubscribeChangeKind, type SubscribeOptions, type TableInfo, type VectorMatch, type VectorUpsertItem };