get-db9 0.4.1 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # get-db9
 
-TypeScript SDK for [pg-tikv](https://github.com/pgtikv/pg-tikv) — instant PostgreSQL-compatible databases on TiKV.
+TypeScript SDK for [db9-backend](https://github.com/c4pt0r/db9-backend) — instant PostgreSQL-compatible databases on TiKV.
 
 ## Install
 
@@ -31,7 +31,7 @@ const db = await instantDatabase({
 
 ## Db9 Client
 
-Full typed client for the API (register, databases, SQL, migrations).
+Full typed client for the API — databases, SQL, file storage, tokens, migrations, and more.
 
 ```typescript
 import { createDb9Client } from 'get-db9/client';
@@ -57,6 +57,167 @@ await client.databases.applyMigration(db.id, {
 });
 ```
 
+## File Storage (fs9)
+
+Each database includes a built-in file system accessible via **WebSocket**.
+The SDK connects to the fs9 WebSocket server, authenticates, and provides a
+high-level API for file operations.
+
+> **Note:** File storage requires a WebSocket implementation. Browsers, Deno,
+> Bun, and Node 21+ have native `WebSocket`. For Node 18–20, install the `ws` package
+> and pass it via the `WebSocket` option.
+
+```typescript
+import { createDb9Client } from 'get-db9/client';
+import WebSocket from 'ws'; // Node 18–20 only
+
+const client = createDb9Client({ WebSocket: WebSocket as any });
+const dbId = 'your-database-id';
+
+// Write a file (string, ArrayBuffer, or Uint8Array)
+await client.fs.write(dbId, '/data/hello.txt', 'Hello, world!');
+
+// Read file as text
+const text = await client.fs.read(dbId, '/data/hello.txt');
+
+// Read file as raw bytes (Uint8Array)
+const bytes = await client.fs.readBinary(dbId, '/data/image.png');
+
+// List files in a directory
+const files = await client.fs.list(dbId, '/data');
+
+// Check if file exists
+const exists = await client.fs.exists(dbId, '/data/hello.txt');
+
+// Get file metadata (type, size, mode, mtime)
+const stat = await client.fs.stat(dbId, '/data/hello.txt');
+console.log(stat.type, stat.size); // 'file', 1024
+
+// Create directory (recursive)
+await client.fs.mkdir(dbId, '/data/nested/dir');
+
+// Append to a file
+await client.fs.append(dbId, '/data/log.txt', 'new line\n');
+
+// Rename (move) a file
+await client.fs.rename(dbId, '/data/old.txt', '/data/new.txt');
+
+// Delete a file
+await client.fs.remove(dbId, '/data/hello.txt');
+
+// Delete a directory recursively
+await client.fs.remove(dbId, '/data/old-dir', { recursive: true });
+```
+
+### Persistent Connection
+
+For multiple operations on the same database, use `fs.connect()` to hold a
+single WebSocket connection and avoid reconnecting per-call:
+
+```typescript
+const fs = await client.fs.connect(dbId);
+try {
+  await fs.mkdir('/batch');
+  await fs.writeFile('/batch/a.txt', 'file A');
+  await fs.writeFile('/batch/b.txt', 'file B');
+  const entries = await fs.readdir('/batch');
+  console.log(entries); // [{path: '/batch/a.txt', ...}, ...]
+} finally {
+  await fs.close();
+}
+```
+
+## Token Management
+
+```typescript
+const client = createDb9Client();
+
+// Create a named API token
+const token = await client.tokens.create({
+  name: 'ci-deploy',
+  expires_in_days: 90,
+});
+console.log(token.token); // Use this for CI/CD
+
+// List all tokens
+const tokens = await client.tokens.list();
+
+// Revoke a token
+await client.tokens.revoke(token.id);
+```
+
+## Database Credentials
+
+Retrieve stored admin credentials without resetting the password:
+
+```typescript
+const client = createDb9Client();
+const dbId = 'your-database-id';
+
+// Get stored credentials (no password reset)
+const creds = await client.databases.credentials(dbId);
+console.log(creds.admin_user);         // admin username
+console.log(creds.admin_password);     // current password
+console.log(creds.connection_string);  // full connection string
+```
+
+## Device Authorization (CLI flow)
+
+Authorize a CLI or device using the OAuth device code flow:
+
+```typescript
+const client = createDb9Client();
+
+// 1. Start device code flow
+const code = await client.deviceAuth.createDeviceCode();
+console.log(`Visit: ${code.verification_uri}`);
+console.log(`Code: ${code.user_code}`);
+
+// 2. Poll for authorization (user approves in browser)
+const poll = async () => {
+  while (true) {
+    const result = await client.deviceAuth.pollDeviceToken({
+      device_code: code.device_code,
+    });
+    if ('token' in result) {
+      return result; // { token, expires_at }
+    }
+    if (result.error === 'access_denied') {
+      throw new Error('User denied authorization');
+    }
+    if (result.error === 'expired_token') {
+      throw new Error('Device code expired');
+    }
+    // authorization_pending — wait and retry
+    await new Promise((r) => setTimeout(r, code.interval * 1000));
+  }
+};
+
+const auth = await poll();
+console.log(auth.token);
+```
+
+## SQL Error Handling
+
+SQL results include structured error details when queries fail:
+
+```typescript
+const result = await client.databases.sql(dbId, 'SELECT * FROM nonexistent');
+
+if (result.error) {
+  // result.error is a SqlErrorDetail object:
+  // {
+  //   message: "relation \"nonexistent\" does not exist",
+  //   code: "42P01",         // PostgreSQL error code
+  //   detail: "...",         // optional
+  //   hint: "...",           // optional
+  //   position: 15           // optional cursor position
+  // }
+  console.log(result.error.message);
+  console.log(result.error.code);
+}
+```
+
 ## Configuration
 
 ### instantDatabase options
@@ -69,6 +230,9 @@ await client.databases.applyMigration(db.id, {
 | `credentialStore` | `CredentialStore` | `FileCredentialStore` | Credential storage |
 | `seed` | `string` | — | SQL to run after creation |
 | `seedFile` | `string` | — | SQL file content to run |
+| `timeout` | `number` | — | Request timeout in ms |
+| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
+| `retryDelay` | `number` | — | Delay between retries in ms |
 
 ### Db9 client options
 
@@ -78,6 +242,11 @@ await client.databases.applyMigration(db.id, {
 | `token` | `string` | — | Bearer token (optional) |
 | `fetch` | `FetchFn` | `globalThis.fetch` | Custom fetch |
 | `credentialStore` | `CredentialStore` | `FileCredentialStore` | Load/save token |
+| `timeout` | `number` | — | Request timeout in ms |
+| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
+| `retryDelay` | `number` | — | Delay between retries in ms |
+| `WebSocket` | `WebSocketConstructor` | `globalThis.WebSocket` | WebSocket impl for fs operations |
+| `wsPort` | `number` | `5480` | WebSocket port for fs9 server |
 
 ## Zero-config client
 
@@ -107,6 +276,8 @@ try {
 }
 ```
 
+> **Note:** 401 errors are automatically retried with a fresh token for anonymous sessions. You typically won't see `Db9AuthError` unless the refresh itself fails.
+
 ## Credential Storage
 
 Credentials are stored in `~/.db9/credentials` (TOML format), shared with the db9 CLI.
@@ -124,6 +295,77 @@ const customStore = new FileCredentialStore('/path/to/credentials');
 const memStore = new MemoryCredentialStore();
 ```
 
+## API Reference
+
+### `client.auth`
+
+| Method | Description |
+|--------|-------------|
+| `register(req)` | Create account with email/password |
+| `login(req)` | Login and get bearer token |
+| `me()` | Get current user profile |
+| `anonymousRegister()` | Register anonymously (auto-called) |
+| `anonymousRefresh(req)` | Refresh anonymous token |
+| `getAnonymousSecret()` | Retrieve anonymous secret for token refresh |
+| `ensureAnonymousSecret()` | Ensure anonymous secret is saved to credential store |
+| `claim(req)` | Claim anonymous account with email/password |
+
+### `client.tokens`
+
+| Method | Description |
+|--------|-------------|
+| `create(req)` | Create a named API token (`{ name?, expires_in_days? }`) |
+| `list()` | List all tokens |
+| `revoke(tokenId)` | Revoke a token by ID |
+
+### `client.databases`
+
+| Method | Description |
+|--------|-------------|
+| `create(req)` | Create a new database |
+| `list()` | List all databases |
+| `get(id)` | Get database details |
+| `delete(id)` | Delete a database |
+| `resetPassword(id)` | Reset admin password |
+| `credentials(id)` | Get stored admin credentials without resetting |
+| `observability(id)` | Get TPS, latency, connection stats |
+| `sql(id, query)` | Execute SQL query (errors returned as `SqlErrorDetail`) |
+| `sqlFile(id, content)` | Execute SQL from file content |
+| `schema(id)` | Get schema metadata |
+| `dump(id, req?)` | Export schema/data as SQL |
+| `applyMigration(id, req)` | Apply a migration |
+| `listMigrations(id)` | List applied migrations |
+| `branch(id, req)` | Create a database branch |
+| `users.list(id)` | List database users |
+| `users.create(id, req)` | Create database user |
+| `users.delete(id, username)` | Delete database user |
+
+### `client.fs`
+
+All methods auto-resolve database credentials and connect via WebSocket.
+
+| Method | Description |
+|--------|-------------|
+| `connect(dbId)` | Open a persistent `FsClient` WebSocket connection |
+| `read(dbId, path)` | Read file as text (UTF-8) |
+| `readBinary(dbId, path)` | Read file as `Uint8Array` |
+| `write(dbId, path, content)` | Write file (string, ArrayBuffer, or Uint8Array) |
+| `append(dbId, path, content)` | Append to a file, returns bytes written |
+| `list(dbId, path)` | List directory contents (returns `FileInfo[]`) |
+| `stat(dbId, path)` | Get file metadata (`FileInfo`) |
+| `exists(dbId, path)` | Check if file exists (returns boolean) |
+| `mkdir(dbId, path)` | Create directory recursively |
+| `remove(dbId, path, opts?)` | Remove file or directory (`{ recursive?: boolean }`) |
+| `rename(dbId, old, new)` | Rename (move) a file or directory |
+
+### `client.deviceAuth`
+
+| Method | Description |
+|--------|-------------|
+| `createDeviceCode()` | Start OAuth device code flow |
+| `pollDeviceToken(req)` | Poll for token after user authorizes |
+| `verifyDevice(req)` | Submit device verification with email/password |
+
 ## Requirements
 
 - Node.js >= 18 (native fetch)