@persql/sdk 0.1.0 → 1.0.0

package/dist/index.d.cts

@@ -71,8 +71,8 @@ interface PerSQLOptions {
      * 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.
+     * network features (`subscribe`) throw — they have no local
+     * equivalent.
      *
      * ```ts
      * const persql = new PerSQL({ local: ":memory:" });
@@ -199,10 +199,73 @@ interface TableInfo {
     name: string;
     rowCount: number;
 }
+/**
+ * Per-statement assertion attached to a `batch` entry. Evaluated
+ * server-side inside the same transactionSync as the statement —
+ * a violation throws, which rolls a transactional batch back. For
+ * non-transactional batches, the rest of the batch does not run.
+ *
+ * Use this to write defensive multi-step writes without a follow-up
+ * read: `UPDATE … WHERE id = ?` with `expect: { rowsWritten: 1 }`
+ * fails fast if zero rows match.
+ *
+ * Shape mirrors `@persql/shared`'s `BatchExpect`. Inlined here so the
+ * published npm package has no monorepo-only deps.
+ */
+interface BatchExpect {
+    /** Result has exactly this many rows. */
+    rows?: number;
+    rowsAtLeast?: number;
+    rowsAtMost?: number;
+    /** Statement wrote exactly this many rows. */
+    rowsWritten?: number;
+    rowsWrittenAtLeast?: number;
+    rowsWrittenAtMost?: number;
+}
 interface Statement {
     sql: string;
     params?: unknown[];
+    expect?: BatchExpect;
+}
+/**
+ * Returned by `client.me()` — the bearer token's namespace, scope, and
+ * current prepaid balance. Agents call this to learn what they're
+ * allowed to touch and how much credit remains before the gate returns
+ * 402.
+ */
+interface WhoamiInfo {
+    namespaceId: string;
+    namespaceSlug: string;
+    tokenId: string;
+    role: "admin" | "readwrite" | "readonly";
+    scopes: unknown[];
+    tableScope: string[] | null;
+    balanceUsdMicros: number | null;
+}
+/** Output of `db.sampleTable(...)`. */
+interface TableSample {
+    table: string;
+    rowCount: number;
+    rows: Array<Record<string, unknown>>;
+    columns: Array<{
+        name: string;
+        type: string;
+        pk: boolean;
+        notNull: boolean;
+        nullCount: number;
+        distinctCount: number;
+        min: unknown;
+        max: unknown;
+    }>;
 }
+/** Output of `db.validate(...)`. */
+type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    errorDetail?: SqlErrorDetail;
+};
 declare class PerSQLError extends Error {
     status: number;
     detail?: SqlErrorDetail;
@@ -249,6 +312,14 @@ declare class PerSQL {
     constructor(opts: PerSQLOptions);
     /** Close the local SQLite connection (no-op in HTTP mode). */
     close(): void;
+    /**
+     * Resolve the bearer token's namespace + live usage. Use this once
+     * per agent run so you know the slug to put in URLs and how much
+     * monthly budget / prepaid balance remains before a 402.
+     *
+     * Throws in local mode — no server, nothing to ask.
+     */
+    me(): Promise<WhoamiInfo>;
     /**
      * Redeem a handoff token (`phand_…`) for a regular PerSQL client
      * scoped to the handed-off (database, branch, role). Single use:
@@ -275,10 +346,42 @@ declare class PerSQL {
     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). */
+    /** @internal — raw fetch returning the underlying Response. */
     fetchRaw(method: "GET", path: string): Promise<Response>;
+    /**
+     * File a support ticket directly from your SDK code. Tickets land in
+     * the customer console at `/support`; staff reply from the admin
+     * app. Useful for agents and background jobs that hit a PerSQL
+     * error and want a human to see it.
+     *
+     * ```ts
+     * try {
+     *   await db.query("UPDATE ...");
+     * } catch (err) {
+     *   await persql.support.createTicket({
+     *     subject: "Branch merge keeps 500ing",
+     *     body: "Repro: ...",
+     *     error: err,
+     *   });
+     * }
+     * ```
+     */
+    get support(): SupportClient;
+}
+interface CreateSupportTicketOptions {
+    subject: string;
+    body: string;
+    /** Optional error to attach for triage (PerSQLError or any throwable). */
+    error?: unknown;
+    /** Caller-supplied extras merged into the ticket's diagnostic context. */
+    errorContext?: Record<string, unknown>;
+}
+declare class SupportClient {
+    private readonly client;
+    constructor(client: PerSQL);
+    createTicket(opts: CreateSupportTicketOptions): Promise<{
+        id: string;
+    }>;
 }
 declare class PerSQLDatabase {
     private readonly client;
@@ -291,6 +394,22 @@ declare class PerSQLDatabase {
     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>[]>;
+    /**
+     * Mint a short-lived session JWT for an end user. The server (which
+     * holds the bearer token) calls this and hands the resulting token
+     * to an untrusted client (browser, mobile app, agent run). The
+     * client uses the JWT to call this database's published `/p/*`
+     * endpoints on behalf of `userId`. TTL defaults to 1 hour; max 24h.
+     */
+    createSession(opts: {
+        userId: string;
+        email?: string;
+        expiresIn?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+        expiresIn: number;
+    }>;
     /**
      * Engine telemetry — recent /v1/query and /v1/batch calls issued
      * against this database. Backed by the in-DO `_persql_meta_query_log`
@@ -361,19 +480,39 @@ declare class PerSQLDatabase {
         parent: number;
         detail: string;
     }>>;
+    /**
+     * Parse + bind-check a SQL statement without executing it. Faster
+     * and cheaper than running the query just to catch unknown columns
+     * or wrong param counts.
+     *
+     * Returns `{ ok: true }` on success or `{ ok: false, error, errorDetail }`
+     * with the same `errorDetail` envelope as `PerSQLError.detail`.
+     */
+    validate(sql: string, params?: unknown[]): Promise<ValidateResult>;
+    /**
+     * Compact text rendering of the database's schema — one line per
+     * table with columns, types, PKs, and FK arrows inlined. Designed
+     * to stuff into an LLM prompt with minimum token overhead. See
+     * `db.describe()` for the structured form.
+     */
+    describeCompact(): Promise<string>;
+    /**
+     * First N rows of a table plus per-column stats (null count,
+     * distinct count, min, max). One call to size up an unfamiliar
+     * table — replaces a hand-rolled `SELECT *`, `COUNT(*)`, and
+     * `PRAGMA table_info` sequence.
+     *
+     * `n` defaults to 10 and is capped at 100.
+     */
+    sampleTable(table: string, opts?: {
+        n?: number;
+    }): Promise<TableSample>;
     /**
      * 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
@@ -388,6 +527,12 @@ declare class PerSQLDatabase {
      * namespace member decides; on approve, runs the original SQL.
      */
     get approvals(): PerSQLApprovals;
+    /**
+     * Manage the require_approval / deny rules for this database. Reads
+     * are open to any bearer with read access; create + delete require
+     * an admin-role bearer token.
+     */
+    get approvalRules(): PerSQLApprovalRules;
     /**
      * Pre-flight a write before running it. `propose()` validates the
      * SQL via EXPLAIN, estimates affected rows, and returns a single-use
@@ -397,13 +542,6 @@ declare class PerSQLDatabase {
      * 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
@@ -444,50 +582,15 @@ declare class PerSQLDatabase {
      */
     driver(): SqliteProxyDriver;
     /**
-     * Returns a tool definition for use with Anthropic / OpenAI / function-calling
-     * agents. Pair it with `runTool` to execute the call.
+     * Returns a single SQL-query tool definition in every shape PerSQL
+     * supports (Anthropic, OpenAI Chat, Vercel AI SDK, Mastra, LangChain,
+     * OpenAI Agents SDK). Same input contract as `asTools()` — the only
+     * difference is one fat `query` tool instead of typed-per-table tools.
+     *
+     * Pair the format-specific fields with `runTool` (or use the bundled
+     * `execute`/`invoke` callbacks, which call `runTool` internally).
      */
-    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[];
-                };
-            };
-        };
-    };
+    asTool(name?: string): SingleToolBundle;
     /**
      * Executes a tool-call payload returned from the model. Pair with `asTool`.
      */
@@ -539,6 +642,20 @@ interface OpenAiTool {
         parameters: Record<string, unknown>;
     };
 }
+interface SingleToolBundle {
+    /** Anthropic shape — pass as one entry of `tools` to messages.create. */
+    anthropic: AnthropicTool;
+    /** OpenAI Chat shape — pass as one entry of `tools` to chat.completions.create. */
+    openai: OpenAiTool;
+    /** Vercel AI SDK shape — spread into `streamText({ tools: { ...db.asTool().aiSdk() } })`. */
+    aiSdk: () => Record<string, AiSdkTool>;
+    /** Mastra shape — wrap with `createTool()` if you need the Mastra envelope. */
+    mastra: () => Record<string, MastraTool>;
+    /** LangChain/LangGraph shape — pass to `DynamicStructuredTool` or use `invoke` directly. */
+    langchain: () => LangChainTool[];
+    /** OpenAI Agents SDK shape — hand to `Agent({ tools: [...] })`. */
+    openaiAgents: () => OpenAiAgentsTool[];
+}
 interface DatabaseToolBundle {
     /** Tool definitions in Anthropic shape — pass as `tools` to messages.create. */
     anthropic: AnthropicTool[];
@@ -622,71 +739,6 @@ interface SubscribeOptions {
     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
@@ -770,11 +822,67 @@ interface ProposeOptions {
     params?: unknown[];
     ttlSec?: number;
 }
+interface ApprovalStatus {
+    status: "pending" | "approved" | "denied";
+    hits: ApprovalRuleHit[];
+    createdAt: string;
+    expiresAt: string;
+    decidedAt: string | null;
+}
+interface PollApprovalOptions {
+    /** Default 2000ms. */
+    intervalMs?: number;
+    /** Default 10 minutes. */
+    timeoutMs?: number;
+    /** Cancellation signal. */
+    signal?: AbortSignal;
+}
+interface SubscribeApprovalOptions {
+    onApprovalRequired?: (event: ApprovalEvent) => void;
+    onApprovalResolved?: (event: ApprovalEvent) => void;
+    /** Poll interval. Default 5000ms. */
+    intervalMs?: number;
+    /** Cancellation signal. */
+    signal?: AbortSignal;
+    /** Logged-by-default error sink. */
+    onError?: (err: Error) => void;
+}
+interface ApprovalEvent {
+    approvalToken: string;
+    status: "pending" | "approved" | "denied";
+    hits: ApprovalRuleHit[];
+}
 declare class PerSQLApprovals {
     private readonly client;
     private readonly namespace;
     private readonly slug;
+    private readonly seen;
     constructor(client: PerSQL, namespace: string, slug: string);
+    /**
+     * Look up the status of an approval token without consuming it. The
+     * bearer must match the one that minted the original 403; cross-bearer
+     * lookup returns 403.
+     */
+    get(approvalToken: string): Promise<ApprovalStatus>;
+    /**
+     * Poll until a reviewer decides (or the token expires). Resolves with
+     * the final status — `approved` is your green light for `redeem()`.
+     */
+    poll(approvalToken: string, opts?: PollApprovalOptions): Promise<ApprovalStatus>;
+    /**
+     * Long-running poll subscription for new approval events on this
+     * database. Returns a `stop()` handle. Webhook delivery is the push
+     * path (events `approval_required` / `approval_resolved`); subscribe
+     * is the pull fallback for clients that can't host a webhook.
+     *
+     * Today this iterates over a known set of tokens supplied by the
+     * caller; an SDK-only client that wants discovery should pair this
+     * with the webhook path. Pass tokens you already hold (e.g. from a
+     * prior `ApprovalRequiredError`).
+     */
+    subscribe(tokens: string[], opts: SubscribeApprovalOptions): {
+        stop: () => void;
+    };
     /**
      * Redeem an approved approvalToken. The bearer must be the same one
      * that minted it, and the request must target the same database.
@@ -782,6 +890,33 @@ declare class PerSQLApprovals {
      */
     redeem<T = Record<string, unknown>>(approvalToken: string): Promise<QueryResult<T> | QueryResult<T>[]>;
 }
+interface ApprovalRule {
+    id: string;
+    databaseId: string;
+    tableGlob: string;
+    action: "require_approval" | "deny";
+    note: string | null;
+    createdById: string;
+    createdAt: string;
+}
+interface CreateApprovalRuleInput {
+    tableGlob: string;
+    action: "require_approval" | "deny";
+    note?: string;
+}
+declare class PerSQLApprovalRules {
+    private readonly client;
+    private readonly namespace;
+    private readonly slug;
+    constructor(client: PerSQL, namespace: string, slug: string);
+    list(): Promise<ApprovalRule[]>;
+    /** Requires an admin-role bearer token. */
+    create(input: CreateApprovalRuleInput): Promise<ApprovalRule>;
+    /** Requires an admin-role bearer token. */
+    delete(ruleId: string): Promise<{
+        deleted: true;
+    }>;
+}
 declare class PerSQLProposals {
     private readonly client;
     private readonly namespace;
@@ -923,4 +1058,4 @@ type SqliteProxyDriver = (sql: string, params: unknown[], method: "all" | "run"
     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 };
+export { type AiSdkTool, type AnthropicTool, type ApprovalEvent, ApprovalRequiredError, type ApprovalRule, type ApprovalRuleHit, type ApprovalStatus, type BatchExpect, type BatchOptions, type BranchInfo, type BranchMergeMode, type BranchMergeOptions, type BranchMergePlanStep, type BranchMergeResult, type BranchUpsertOptions, type ClaimBranchOptions, type ClaimedBranch, type CreateApprovalRuleInput, type CreateSupportTicketOptions, type DatabaseSchema, type DatabaseToolBundle, type DescribeBundle, type HandoffClaim, type LangChainTool, type MastraTool, type OpenAiAgentsTool, type OpenAiTool, PerSQL, PerSQLApprovalRules, PerSQLApprovals, PerSQLBranches, PerSQLDatabase, PerSQLError, type PerSQLOptions, PerSQLProposals, type PollApprovalOptions, type ProposalPlan, type ProposeOptions, type QueryLogEntry, type QueryOptions, type QueryResult, RateLimitError, type RawQueryResult, type SchemaDoctorReport, type SchemaSearchResponse, type SingleToolBundle, type SqlErrorDetail, type SqlErrorKind, type SqliteProxyDriver, type Statement, type SubscribeApprovalOptions, type SubscribeChange, type SubscribeChangeKind, type SubscribeOptions, SupportClient, type TableInfo, type TableSample, type ValidateResult, type WhoamiInfo };