@persql/sdk 1.1.0 → 1.2.1

package/dist/index.d.cts

@@ -1,9 +1,11 @@
+/** 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;
 }
+/** 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 +48,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 +69,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 +92,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,7 +105,32 @@ interface QueryResult<T = Record<string, unknown>> {
     data: T[];
     rowsRead: number;
     rowsWritten: 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()`
+     * (a batch reports one aggregate meta, not one per statement).
+     */
+    meta?: QueryMeta;
 }
+/**
+ * Usage and cost the server attaches to a query response. `costUsd` is
+ * computed from the public rate card — the same numbers the spend report
+ * uses. `snapshot` is set when the auto-snapshot pipeline took a labeled
+ * bookmark before a destructive call.
+ */
+interface QueryMeta {
+    rowsRead: number;
+    rowsWritten: number;
+    durationMs: number;
+    statementCount: number;
+    costUsd: number;
+    snapshot: {
+        id: string;
+        label: string;
+    } | 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;
@@ -188,6 +227,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`. */
@@ -195,6 +235,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;
@@ -222,6 +263,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[];
@@ -266,15 +308,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;
@@ -301,6 +350,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;
@@ -344,8 +403,22 @@ declare class PerSQL {
      */
     database(path: string): PerSQLDatabase;
     database(namespace: string, slug: string): PerSQLDatabase;
+    /**
+     * 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(): PerSQLDatabases;
     /** @internal */
     request<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * @internal — like `request`, but also surfaces the response `meta`
+     * envelope (usage + `costUsd`) that the data-only `request` drops.
+     */
+    requestWithMeta<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown, headers?: Record<string, string>): Promise<{
+        data: T;
+        meta?: QueryMeta;
+    }>;
     /** @internal — raw fetch returning the underlying Response. */
     fetchRaw(method: "GET", path: string): Promise<Response>;
     /**
@@ -368,6 +441,7 @@ declare class PerSQL {
      */
     get support(): SupportClient;
 }
+/** Input for `persql.support.createTicket()`. */
 interface CreateSupportTicketOptions {
     subject: string;
     body: string;
@@ -376,6 +450,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);
@@ -383,6 +458,58 @@ declare class SupportClient {
         id: string;
     }>;
 }
+/** Database metadata as returned by `persql.databases.create()` and `list()`. */
+interface DatabaseInfo {
+    id: string;
+    namespaceId: string;
+    slug: string;
+    name: string;
+    status: string;
+    region: string;
+    forkedFromId: string | null;
+    forkedAt: string | null;
+    expiresAt: string | null;
+    branchRef: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input for `persql.databases.create()`. */
+interface CreateDatabaseOptions {
+    /** Display name, 1-50 chars. */
+    name: string;
+    /** URL slug; derived from `name` when omitted. */
+    slug?: 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;
+}
+/**
+ * Namespace-level database management. Reached via `persql.databases`.
+ * Both calls require a server-mode (non-local) client.
+ */
+declare class PerSQLDatabases {
+    private readonly client;
+    constructor(client: PerSQL);
+    /**
+     * Provision a new isolated database and return its metadata. Requires
+     * an unscoped admin token (scoped tokens can't create databases).
+     */
+    create(opts: CreateDatabaseOptions): Promise<DatabaseInfo>;
+    /** List databases in the token's namespace, newest first (paginated). */
+    list(opts?: {
+        cursor?: string;
+        pageSize?: number;
+    }): Promise<{
+        data: DatabaseInfo[];
+        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;
@@ -647,7 +774,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
@@ -679,11 +806,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: {
@@ -692,6 +821,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;
@@ -706,6 +836,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[];
@@ -739,11 +870,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;
@@ -775,11 +908,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[];
@@ -812,7 +948,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;
@@ -829,6 +970,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;
@@ -842,6 +984,7 @@ interface BranchMergeResult {
     };
     note?: string;
 }
+/** Options for `db.branches.upsert()`. */
 interface BranchUpsertOptions {
     /** Human-readable name. Defaults to `<parent name> (<ref>)`. */
     name?: string;
@@ -850,6 +993,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;
@@ -860,6 +1004,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[][];
@@ -868,10 +1013,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[];
@@ -879,6 +1026,7 @@ interface ApprovalStatus {
     expiresAt: string;
     decidedAt: string | null;
 }
+/** Pacing and cancellation options for `db.approvals.poll()`. */
 interface PollApprovalOptions {
     /** Default 2000ms. */
     intervalMs?: number;
@@ -887,6 +1035,7 @@ interface PollApprovalOptions {
     /** Cancellation signal. */
     signal?: AbortSignal;
 }
+/** Callbacks and pacing for `db.approvals.subscribe()`. */
 interface SubscribeApprovalOptions {
     onApprovalRequired?: (event: ApprovalEvent) => void;
     onApprovalResolved?: (event: ApprovalEvent) => void;
@@ -897,11 +1046,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;
@@ -940,6 +1095,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;
@@ -949,11 +1105,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;
@@ -967,6 +1125,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;
@@ -992,6 +1155,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;
@@ -1004,6 +1168,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;
@@ -1015,6 +1180,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;
@@ -1113,4 +1283,4 @@ type SqliteProxyDriver = (sql: string, params: unknown[], method: "all" | "run"
     rows: unknown;
 }>;
 
-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 };
+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 CreateDatabaseOptions, type CreateSupportTicketOptions, type DatabaseInfo, type DatabaseSchema, type DatabaseToolBundle, type DescribeBundle, type HandoffClaim, type LangChainTool, type MastraTool, type OpenAiAgentsTool, type OpenAiTool, PerSQL, PerSQLApprovalRules, PerSQLApprovals, PerSQLBranches, PerSQLDatabase, PerSQLDatabases, PerSQLError, type PerSQLOptions, PerSQLProposals, type PollApprovalOptions, type ProposalPlan, type ProposeOptions, type QueryLogEntry, type QueryMeta, 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 };