@persql/sdk 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -91,6 +91,30 @@ 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;
 }
 interface BatchOptions {
     /** Wrap all statements in BEGIN/COMMIT. Rolls back on first error. */
@@ -344,8 +368,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>;
     /**
@@ -383,6 +421,51 @@ declare class SupportClient {
         id: string;
     }>;
 }
+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;
+}
+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;
+    }>;
+}
 declare class PerSQLDatabase {
     private readonly client;
     readonly namespace: string;
@@ -564,6 +647,56 @@ declare class PerSQLDatabase {
      * server.
      */
     subscribe(options: SubscribeOptions): () => void;
+    /**
+     * 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.
+     */
+    waitForChanges(opts?: {
+        since?: number;
+        waitMs?: number;
+        tables?: string[];
+    }): Promise<{
+        changes: Array<{
+            seq: number;
+            ts: number;
+            table: string;
+            kind: SubscribeChangeKind;
+        }>;
+        cursor: number;
+        restarted: boolean;
+    }>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    changes(opts?: {
+        since?: number;
+        tables?: string[];
+        waitMs?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
+        changes: Array<{
+            seq: number;
+            ts: number;
+            table: string;
+            kind: SubscribeChangeKind;
+        }>;
+        cursor: number;
+        restarted: boolean;
+    }>;
     /**
      * Returns the callback shape `drizzle-orm/sqlite-proxy` expects.
      * Pair with `drizzle()` from that module to get a typed,
@@ -927,6 +1060,11 @@ declare class PerSQLProposals {
      * 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.
      */
     propose(sql: string, opts?: ProposeOptions): Promise<ProposalPlan>;
     /**
@@ -1058,4 +1196,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 };

package/dist/index.d.ts

@@ -91,6 +91,30 @@ 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;
 }
 interface BatchOptions {
     /** Wrap all statements in BEGIN/COMMIT. Rolls back on first error. */
@@ -344,8 +368,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>;
     /**
@@ -383,6 +421,51 @@ declare class SupportClient {
         id: string;
     }>;
 }
+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;
+}
+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;
+    }>;
+}
 declare class PerSQLDatabase {
     private readonly client;
     readonly namespace: string;
@@ -564,6 +647,56 @@ declare class PerSQLDatabase {
      * server.
      */
     subscribe(options: SubscribeOptions): () => void;
+    /**
+     * 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.
+     */
+    waitForChanges(opts?: {
+        since?: number;
+        waitMs?: number;
+        tables?: string[];
+    }): Promise<{
+        changes: Array<{
+            seq: number;
+            ts: number;
+            table: string;
+            kind: SubscribeChangeKind;
+        }>;
+        cursor: number;
+        restarted: boolean;
+    }>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    changes(opts?: {
+        since?: number;
+        tables?: string[];
+        waitMs?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
+        changes: Array<{
+            seq: number;
+            ts: number;
+            table: string;
+            kind: SubscribeChangeKind;
+        }>;
+        cursor: number;
+        restarted: boolean;
+    }>;
     /**
      * Returns the callback shape `drizzle-orm/sqlite-proxy` expects.
      * Pair with `drizzle()` from that module to get a typed,
@@ -927,6 +1060,11 @@ declare class PerSQLProposals {
      * 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.
      */
     propose(sql: string, opts?: ProposeOptions): Promise<ProposalPlan>;
     /**
@@ -1058,4 +1196,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 };

package/dist/index.js

@@ -5,11 +5,12 @@ import {
   PerSQLApprovals,
   PerSQLBranches,
   PerSQLDatabase,
+  PerSQLDatabases,
   PerSQLError,
   PerSQLProposals,
   RateLimitError,
   SupportClient
-} from "./chunk-ZRZANHPI.js";
+} from "./chunk-GH75ERQ6.js";
 export {
   ApprovalRequiredError,
   PerSQL,
@@ -17,6 +18,7 @@ export {
   PerSQLApprovals,
   PerSQLBranches,
   PerSQLDatabase,
+  PerSQLDatabases,
   PerSQLError,
   PerSQLProposals,
   RateLimitError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persql/sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "TypeScript SDK for PerSQL — SQLite databases on the edge for AI agents",
   "license": "MIT",
   "type": "module",