@persql/sdk 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# @persql/sdk
+
+TypeScript SDK for [PerSQL](https://persql.com) — SQLite databases on the edge, designed for AI agents.
+
+```bash
+npm i @persql/sdk
+```
+
+## Quick start
+
+```ts
+import { PerSQL } from "@persql/sdk";
+
+const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
+const db = persql.database("acme/orders");
+
+// Query — returns rows reshaped as objects.
+const { data } = await db.query<{ id: number; email: string }>(
+  "SELECT id, email FROM customers WHERE id = ?",
+  [42]
+);
+
+// Batch — multiple statements in one round-trip.
+const results = await db.batch([
+  { sql: "INSERT INTO orders (id, total) VALUES (?, ?)", params: ["o-1", 99.5] },
+  { sql: "UPDATE customers SET last_order = ? WHERE id = ?", params: ["o-1", "c-1"] },
+]);
+
+// Transaction — same as batch with rollback on error.
+await db.transaction([
+  { sql: "INSERT INTO accounts (id, balance) VALUES (?, ?)", params: ["a-1", 100] },
+  { sql: "INSERT INTO accounts (id, balance) VALUES (?, ?)", params: ["a-2", 0] },
+]);
+```
+
+## Use as a tool with Anthropic / OpenAI
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { PerSQL } from "@persql/sdk";
+
+const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
+const db = persql.database("acme/orders");
+const tool = db.asTool().anthropic;
+
+const anthropic = new Anthropic();
+const response = await anthropic.messages.create({
+  model: "claude-opus-4-7",
+  max_tokens: 1024,
+  tools: [tool],
+  messages: [{ role: "user", content: "How many orders did we ship last week?" }],
+});
+
+// When the model calls the tool, run it and feed the result back:
+for (const block of response.content) {
+  if (block.type === "tool_use" && block.name === tool.name) {
+    const result = await db.runTool(block.input as { sql: string; params?: unknown[] });
+    // …pass `result` back to the model in the next turn.
+  }
+}
+```
+
+## Use with Drizzle
+
+```bash
+npm i drizzle-orm
+```
+
+```ts
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import { PerSQL } from "@persql/sdk";
+import * as schema from "./db/schema";
+
+const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
+const db = drizzle(persql.database("acme/orders").driver(), { schema });
+
+const recent = await db.select().from(schema.orders).limit(10);
+```
+
+`db.driver()` returns the callback shape `drizzle-orm/sqlite-proxy`
+expects. Generate the schema file once with the bundled
+`persql-codegen` bin:
+
+```bash
+PERSQL_TOKEN=psql_live_… npx persql-codegen --db acme/orders --out src/db/schema.ts
+```
+
+## Local mode (tests)
+
+Run the SDK against a local SQLite file (or `:memory:`) so tests
+don't hit your live database:
+
+```bash
+npm i -D better-sqlite3
+```
+
+```ts
+import { PerSQL } from "@persql/sdk";
+
+const persql = new PerSQL({ local: ":memory:" });   // or "./test.db"
+const db = persql.database("test/db");
+
+await db.query("CREATE TABLE customers (id INTEGER, email TEXT)");
+await db.query("INSERT INTO customers VALUES (?, ?)", [1, "a@b.co"]);
+const { data } = await db.query("SELECT * FROM customers");
+```
+
+`query / batch / transaction / tables / explain / schema` route
+through `better-sqlite3` (lazy-loaded — never required for live use).
+`vectors`, `blob`, and `subscribe` throw — they have no local
+equivalent. The same `db.driver()` works in local mode, so a
+Drizzle-based data layer needs zero changes between tests and prod.
+
+Call `persql.close()` to release the file handle when done.
+
+## Idempotency
+
+Pass an `Idempotency-Key` to make writes safely retryable:
+
+```ts
+await db.query("INSERT INTO events (id, name) VALUES (?, ?)", ["e-1", "click"], {
+  idempotencyKey: "evt-e-1-2026-04-29",
+});
+```
+
+Cached for 24 hours. A retry with the same key returns the cached response.
+
+## Errors
+
+```ts
+import { PerSQLError, RateLimitError } from "@persql/sdk";
+
+try {
+  await db.query("SELECT 1");
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    console.log(`Slow down for ${e.retryAfterSeconds}s`);
+  } else if (e instanceof PerSQLError) {
+    console.log(`API error ${e.status}: ${e.message}`);
+  }
+}
+```
+
+## License
+
+MIT