@persql/sdk 1.2.1 → 1.4.0

package/dist/index.d.cts

@@ -4,6 +4,8 @@ interface RawQueryResult {
     rows: unknown[][];
     rowsRead: number;
     rowsWritten: number;
+    changes?: number;
+    lastInsertRowid?: number;
 }
 /** In-process driver backing `new PerSQL({ local })` — runs SQL through `better-sqlite3` instead of the HTTP API. */
 declare class LocalDriver {
@@ -36,6 +38,60 @@ declare class LocalDriver {
     close(): void;
 }
 
+interface AuthorizeUrlOptions {
+    /** The OAuth app's client_id (`psqlrp_…`). */
+    clientId: string;
+    /** Exact-match redirect URI registered for the app (HTTPS or loopback). */
+    redirectUri: string;
+    /**
+     * Space-separated scopes. Defaults to `"database"`; add `"openid"`
+     * (`"openid database"`) to also receive an `id_token` for sign-in.
+     */
+    scope?: string;
+    /** API origin. Defaults to https://api.persql.com */
+    baseURL?: string;
+    /** CSRF state. Defaults to a random value (returned so you can match it). */
+    state?: string;
+    /** Bring your own PKCE verifier. Defaults to a fresh random one. */
+    codeVerifier?: string;
+}
+interface AuthorizeRequest {
+    /** Open this in a browser / in-app browser / AuthSession. */
+    url: string;
+    /** Stash this until the redirect comes back — it's required to exchange the code. */
+    codeVerifier: string;
+    /** Compare against the `state` on the redirect to defeat CSRF. */
+    state: string;
+}
+interface ExchangeCodeOptions {
+    clientId: string;
+    redirectUri: string;
+    /** The `code` query param from the redirect. */
+    code: string;
+    /** The verifier from the matching {@link AuthorizeRequest}. */
+    codeVerifier: string;
+    baseURL?: string;
+    /** Confidential (server-side) clients only — never ship a secret in an app. */
+    clientSecret?: string;
+    fetch?: typeof fetch;
+}
+interface DatabaseGrant {
+    /** A `psql_live_…` token scoped to exactly this user's database. */
+    accessToken: string;
+    /** `"<namespace>/<database>"` — pass straight to `persql.database(...)`. */
+    database: string;
+    /** API base URL to construct the client with. */
+    apiUrl: string;
+    /** The scopes actually granted. */
+    scope: string;
+    /** Present only when `openid` was requested. */
+    idToken?: string;
+    /** The signed-in user's email (RFC 6749 §5.1 extra member). */
+    userEmail?: string;
+}
+declare function createAuthorizeUrl(opts: AuthorizeUrlOptions): Promise<AuthorizeRequest>;
+declare function exchangeAuthorizationCode(opts: ExchangeCodeOptions): Promise<DatabaseGrant>;
+
 /**
  * @persql/sdk — Talk to your PerSQL databases from anywhere.
  *
@@ -105,6 +161,14 @@ interface QueryResult<T = Record<string, unknown>> {
     data: T[];
     rowsRead: number;
     rowsWritten: number;
+    /**
+     * SQLite `changes()` after a write statement — the exact affected-row
+     * count ORMs expect (`rowsWritten` also counts index writes). Absent
+     * on reads, DDL, and servers older than this field.
+     */
+    changes?: number;
+    /** SQLite `last_insert_rowid()` after a write statement. Absent on reads and DDL. */
+    lastInsertRowid?: number;
     /**
      * Per-call usage and cost the server echoes on `query()`. Undefined in
      * local mode (no server) and on the per-statement results of `batch()`
@@ -397,6 +461,30 @@ declare class PerSQL {
     }): Promise<PerSQL & {
         handedOff: HandoffClaim;
     }>;
+    /**
+     * Step 1 of the `database`-scope sign-in (user-owned app databases):
+     * build the `/oauth/authorize` URL plus the PKCE verifier + state to
+     * keep. Open `url` in a browser / in-app browser / Expo AuthSession,
+     * then call {@link PerSQL.completeConnect} with the returned `code`.
+     *
+     *   const req = await PerSQL.beginConnect({
+     *     clientId, redirectUri, scope: "openid database",
+     *   });
+     *   // open req.url, capture { code, state }; verify state === req.state
+     */
+    static beginConnect(opts: AuthorizeUrlOptions): Promise<AuthorizeRequest>;
+    /**
+     * Step 2: exchange the redirect's `code` for a scoped database token and
+     * get back a ready client. The granted database is on `.grant.database`.
+     *
+     *   const persql = await PerSQL.completeConnect({
+     *     clientId, redirectUri, code, codeVerifier: req.codeVerifier,
+     *   });
+     *   const db = persql.database(persql.grant.database);
+     */
+    static completeConnect(opts: ExchangeCodeOptions): Promise<PerSQL & {
+        grant: DatabaseGrant;
+    }>;
     /**
      * Reference a database by its `<namespace>/<slug>` path.
      * Both forms work: `db("acme/orders")` or `db("acme", "orders")`.
@@ -1283,4 +1371,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 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 };
+export { type AiSdkTool, type AnthropicTool, type ApprovalEvent, ApprovalRequiredError, type ApprovalRule, type ApprovalRuleHit, type ApprovalStatus, type AuthorizeRequest, type AuthorizeUrlOptions, 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 DatabaseGrant, type DatabaseInfo, type DatabaseSchema, type DatabaseToolBundle, type DescribeBundle, type ExchangeCodeOptions, 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, createAuthorizeUrl, exchangeAuthorizationCode };

package/dist/index.d.ts

@@ -4,6 +4,8 @@ interface RawQueryResult {
     rows: unknown[][];
     rowsRead: number;
     rowsWritten: number;
+    changes?: number;
+    lastInsertRowid?: number;
 }
 /** In-process driver backing `new PerSQL({ local })` — runs SQL through `better-sqlite3` instead of the HTTP API. */
 declare class LocalDriver {
@@ -36,6 +38,60 @@ declare class LocalDriver {
     close(): void;
 }
 
+interface AuthorizeUrlOptions {
+    /** The OAuth app's client_id (`psqlrp_…`). */
+    clientId: string;
+    /** Exact-match redirect URI registered for the app (HTTPS or loopback). */
+    redirectUri: string;
+    /**
+     * Space-separated scopes. Defaults to `"database"`; add `"openid"`
+     * (`"openid database"`) to also receive an `id_token` for sign-in.
+     */
+    scope?: string;
+    /** API origin. Defaults to https://api.persql.com */
+    baseURL?: string;
+    /** CSRF state. Defaults to a random value (returned so you can match it). */
+    state?: string;
+    /** Bring your own PKCE verifier. Defaults to a fresh random one. */
+    codeVerifier?: string;
+}
+interface AuthorizeRequest {
+    /** Open this in a browser / in-app browser / AuthSession. */
+    url: string;
+    /** Stash this until the redirect comes back — it's required to exchange the code. */
+    codeVerifier: string;
+    /** Compare against the `state` on the redirect to defeat CSRF. */
+    state: string;
+}
+interface ExchangeCodeOptions {
+    clientId: string;
+    redirectUri: string;
+    /** The `code` query param from the redirect. */
+    code: string;
+    /** The verifier from the matching {@link AuthorizeRequest}. */
+    codeVerifier: string;
+    baseURL?: string;
+    /** Confidential (server-side) clients only — never ship a secret in an app. */
+    clientSecret?: string;
+    fetch?: typeof fetch;
+}
+interface DatabaseGrant {
+    /** A `psql_live_…` token scoped to exactly this user's database. */
+    accessToken: string;
+    /** `"<namespace>/<database>"` — pass straight to `persql.database(...)`. */
+    database: string;
+    /** API base URL to construct the client with. */
+    apiUrl: string;
+    /** The scopes actually granted. */
+    scope: string;
+    /** Present only when `openid` was requested. */
+    idToken?: string;
+    /** The signed-in user's email (RFC 6749 §5.1 extra member). */
+    userEmail?: string;
+}
+declare function createAuthorizeUrl(opts: AuthorizeUrlOptions): Promise<AuthorizeRequest>;
+declare function exchangeAuthorizationCode(opts: ExchangeCodeOptions): Promise<DatabaseGrant>;
+
 /**
  * @persql/sdk — Talk to your PerSQL databases from anywhere.
  *
@@ -105,6 +161,14 @@ interface QueryResult<T = Record<string, unknown>> {
     data: T[];
     rowsRead: number;
     rowsWritten: number;
+    /**
+     * SQLite `changes()` after a write statement — the exact affected-row
+     * count ORMs expect (`rowsWritten` also counts index writes). Absent
+     * on reads, DDL, and servers older than this field.
+     */
+    changes?: number;
+    /** SQLite `last_insert_rowid()` after a write statement. Absent on reads and DDL. */
+    lastInsertRowid?: number;
     /**
      * Per-call usage and cost the server echoes on `query()`. Undefined in
      * local mode (no server) and on the per-statement results of `batch()`
@@ -397,6 +461,30 @@ declare class PerSQL {
     }): Promise<PerSQL & {
         handedOff: HandoffClaim;
     }>;
+    /**
+     * Step 1 of the `database`-scope sign-in (user-owned app databases):
+     * build the `/oauth/authorize` URL plus the PKCE verifier + state to
+     * keep. Open `url` in a browser / in-app browser / Expo AuthSession,
+     * then call {@link PerSQL.completeConnect} with the returned `code`.
+     *
+     *   const req = await PerSQL.beginConnect({
+     *     clientId, redirectUri, scope: "openid database",
+     *   });
+     *   // open req.url, capture { code, state }; verify state === req.state
+     */
+    static beginConnect(opts: AuthorizeUrlOptions): Promise<AuthorizeRequest>;
+    /**
+     * Step 2: exchange the redirect's `code` for a scoped database token and
+     * get back a ready client. The granted database is on `.grant.database`.
+     *
+     *   const persql = await PerSQL.completeConnect({
+     *     clientId, redirectUri, code, codeVerifier: req.codeVerifier,
+     *   });
+     *   const db = persql.database(persql.grant.database);
+     */
+    static completeConnect(opts: ExchangeCodeOptions): Promise<PerSQL & {
+        grant: DatabaseGrant;
+    }>;
     /**
      * Reference a database by its `<namespace>/<slug>` path.
      * Both forms work: `db("acme/orders")` or `db("acme", "orders")`.
@@ -1283,4 +1371,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 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 };
+export { type AiSdkTool, type AnthropicTool, type ApprovalEvent, ApprovalRequiredError, type ApprovalRule, type ApprovalRuleHit, type ApprovalStatus, type AuthorizeRequest, type AuthorizeUrlOptions, 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 DatabaseGrant, type DatabaseInfo, type DatabaseSchema, type DatabaseToolBundle, type DescribeBundle, type ExchangeCodeOptions, 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, createAuthorizeUrl, exchangeAuthorizationCode };

package/dist/index.js

@@ -9,8 +9,10 @@ import {
   PerSQLError,
   PerSQLProposals,
   RateLimitError,
-  SupportClient
-} from "./chunk-VJ776W3K.js";
+  SupportClient,
+  createAuthorizeUrl,
+  exchangeAuthorizationCode
+} from "./chunk-5ELQCDXS.js";
 export {
   ApprovalRequiredError,
   PerSQL,
@@ -22,6 +24,8 @@ export {
   PerSQLError,
   PerSQLProposals,
   RateLimitError,
-  SupportClient
+  SupportClient,
+  createAuthorizeUrl,
+  exchangeAuthorizationCode
 };
 //# sourceMappingURL=index.js.map

package/package.json

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