get-db9 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +244 -2
- package/dist/{client-UKXFQNll.d.cts → client-B3NUYqOc.d.cts} +188 -20
- package/dist/{client-UKXFQNll.d.ts → client-B3NUYqOc.d.ts} +188 -20
- package/dist/client.cjs +332 -88
- package/dist/client.cjs.map +1 -1
- package/dist/client.d.cts +1 -1
- package/dist/client.d.ts +1 -1
- package/dist/client.js +332 -88
- package/dist/client.js.map +1 -1
- package/dist/index.cjs +336 -88
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +334 -88
- package/dist/index.js.map +1 -1
- package/package.json +7 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# get-db9
|
|
2
2
|
|
|
3
|
-
TypeScript SDK for [
|
|
3
|
+
TypeScript SDK for [db9-backend](https://github.com/c4pt0r/db9-backend) — instant PostgreSQL-compatible databases on TiKV.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -31,7 +31,7 @@ const db = await instantDatabase({
|
|
|
31
31
|
|
|
32
32
|
## Db9 Client
|
|
33
33
|
|
|
34
|
-
Full typed client for the API
|
|
34
|
+
Full typed client for the API — databases, SQL, file storage, tokens, migrations, and more.
|
|
35
35
|
|
|
36
36
|
```typescript
|
|
37
37
|
import { createDb9Client } from 'get-db9/client';
|
|
@@ -57,6 +57,167 @@ await client.databases.applyMigration(db.id, {
|
|
|
57
57
|
});
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
+
## File Storage (fs9)
|
|
61
|
+
|
|
62
|
+
Each database includes a built-in file system accessible via **WebSocket**.
|
|
63
|
+
The SDK connects to the fs9 WebSocket server, authenticates, and provides a
|
|
64
|
+
high-level API for file operations.
|
|
65
|
+
|
|
66
|
+
> **Note:** File storage requires a WebSocket implementation. Browsers, Deno,
|
|
67
|
+
> Bun, and Node 21+ have native `WebSocket`. For Node 18–20, install the `ws` package
|
|
68
|
+
> and pass it via the `WebSocket` option.
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
import { createDb9Client } from 'get-db9/client';
|
|
72
|
+
import WebSocket from 'ws'; // Node 18–20 only
|
|
73
|
+
|
|
74
|
+
const client = createDb9Client({ WebSocket: WebSocket as any });
|
|
75
|
+
const dbId = 'your-database-id';
|
|
76
|
+
|
|
77
|
+
// Write a file (string, ArrayBuffer, or Uint8Array)
|
|
78
|
+
await client.fs.write(dbId, '/data/hello.txt', 'Hello, world!');
|
|
79
|
+
|
|
80
|
+
// Read file as text
|
|
81
|
+
const text = await client.fs.read(dbId, '/data/hello.txt');
|
|
82
|
+
|
|
83
|
+
// Read file as raw bytes (Uint8Array)
|
|
84
|
+
const bytes = await client.fs.readBinary(dbId, '/data/image.png');
|
|
85
|
+
|
|
86
|
+
// List files in a directory
|
|
87
|
+
const files = await client.fs.list(dbId, '/data');
|
|
88
|
+
|
|
89
|
+
// Check if file exists
|
|
90
|
+
const exists = await client.fs.exists(dbId, '/data/hello.txt');
|
|
91
|
+
|
|
92
|
+
// Get file metadata (type, size, mode, mtime)
|
|
93
|
+
const stat = await client.fs.stat(dbId, '/data/hello.txt');
|
|
94
|
+
console.log(stat.type, stat.size); // 'file', 1024
|
|
95
|
+
|
|
96
|
+
// Create directory (recursive)
|
|
97
|
+
await client.fs.mkdir(dbId, '/data/nested/dir');
|
|
98
|
+
|
|
99
|
+
// Append to a file
|
|
100
|
+
await client.fs.append(dbId, '/data/log.txt', 'new line\n');
|
|
101
|
+
|
|
102
|
+
// Rename (move) a file
|
|
103
|
+
await client.fs.rename(dbId, '/data/old.txt', '/data/new.txt');
|
|
104
|
+
|
|
105
|
+
// Delete a file
|
|
106
|
+
await client.fs.remove(dbId, '/data/hello.txt');
|
|
107
|
+
|
|
108
|
+
// Delete a directory recursively
|
|
109
|
+
await client.fs.remove(dbId, '/data/old-dir', { recursive: true });
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Persistent Connection
|
|
113
|
+
|
|
114
|
+
For multiple operations on the same database, use `fs.connect()` to hold a
|
|
115
|
+
single WebSocket connection and avoid reconnecting per-call:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
const fs = await client.fs.connect(dbId);
|
|
119
|
+
try {
|
|
120
|
+
await fs.mkdir('/batch');
|
|
121
|
+
await fs.writeFile('/batch/a.txt', 'file A');
|
|
122
|
+
await fs.writeFile('/batch/b.txt', 'file B');
|
|
123
|
+
const entries = await fs.readdir('/batch');
|
|
124
|
+
console.log(entries); // [{path: '/batch/a.txt', ...}, ...]
|
|
125
|
+
} finally {
|
|
126
|
+
await fs.close();
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Token Management
|
|
131
|
+
|
|
132
|
+
```typescript
|
|
133
|
+
const client = createDb9Client();
|
|
134
|
+
|
|
135
|
+
// Create a named API token
|
|
136
|
+
const token = await client.tokens.create({
|
|
137
|
+
name: 'ci-deploy',
|
|
138
|
+
expires_in_days: 90,
|
|
139
|
+
});
|
|
140
|
+
console.log(token.token); // Use this for CI/CD
|
|
141
|
+
|
|
142
|
+
// List all tokens
|
|
143
|
+
const tokens = await client.tokens.list();
|
|
144
|
+
|
|
145
|
+
// Revoke a token
|
|
146
|
+
await client.tokens.revoke(token.id);
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Database Credentials
|
|
150
|
+
|
|
151
|
+
Retrieve stored admin credentials without resetting the password:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
const client = createDb9Client();
|
|
155
|
+
const dbId = 'your-database-id';
|
|
156
|
+
|
|
157
|
+
// Get stored credentials (no password reset)
|
|
158
|
+
const creds = await client.databases.credentials(dbId);
|
|
159
|
+
console.log(creds.admin_user); // admin username
|
|
160
|
+
console.log(creds.admin_password); // current password
|
|
161
|
+
console.log(creds.connection_string); // full connection string
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Device Authorization (CLI flow)
|
|
165
|
+
|
|
166
|
+
Authorize a CLI or device using the OAuth device code flow:
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
const client = createDb9Client();
|
|
170
|
+
|
|
171
|
+
// 1. Start device code flow
|
|
172
|
+
const code = await client.deviceAuth.createDeviceCode();
|
|
173
|
+
console.log(`Visit: ${code.verification_uri}`);
|
|
174
|
+
console.log(`Code: ${code.user_code}`);
|
|
175
|
+
|
|
176
|
+
// 2. Poll for authorization (user approves in browser)
|
|
177
|
+
const poll = async () => {
|
|
178
|
+
while (true) {
|
|
179
|
+
const result = await client.deviceAuth.pollDeviceToken({
|
|
180
|
+
device_code: code.device_code,
|
|
181
|
+
});
|
|
182
|
+
if ('token' in result) {
|
|
183
|
+
return result; // { token, expires_at }
|
|
184
|
+
}
|
|
185
|
+
if (result.error === 'access_denied') {
|
|
186
|
+
throw new Error('User denied authorization');
|
|
187
|
+
}
|
|
188
|
+
if (result.error === 'expired_token') {
|
|
189
|
+
throw new Error('Device code expired');
|
|
190
|
+
}
|
|
191
|
+
// authorization_pending — wait and retry
|
|
192
|
+
await new Promise((r) => setTimeout(r, code.interval * 1000));
|
|
193
|
+
}
|
|
194
|
+
};
|
|
195
|
+
|
|
196
|
+
const auth = await poll();
|
|
197
|
+
console.log(auth.token);
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## SQL Error Handling
|
|
201
|
+
|
|
202
|
+
SQL results include structured error details when queries fail:
|
|
203
|
+
|
|
204
|
+
```typescript
|
|
205
|
+
const result = await client.databases.sql(dbId, 'SELECT * FROM nonexistent');
|
|
206
|
+
|
|
207
|
+
if (result.error) {
|
|
208
|
+
// result.error is a SqlErrorDetail object:
|
|
209
|
+
// {
|
|
210
|
+
// message: "relation \"nonexistent\" does not exist",
|
|
211
|
+
// code: "42P01", // PostgreSQL error code
|
|
212
|
+
// detail: "...", // optional
|
|
213
|
+
// hint: "...", // optional
|
|
214
|
+
// position: 15 // optional cursor position
|
|
215
|
+
// }
|
|
216
|
+
console.log(result.error.message);
|
|
217
|
+
console.log(result.error.code);
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
60
221
|
## Configuration
|
|
61
222
|
|
|
62
223
|
### instantDatabase options
|
|
@@ -69,6 +230,9 @@ await client.databases.applyMigration(db.id, {
|
|
|
69
230
|
| `credentialStore` | `CredentialStore` | `FileCredentialStore` | Credential storage |
|
|
70
231
|
| `seed` | `string` | — | SQL to run after creation |
|
|
71
232
|
| `seedFile` | `string` | — | SQL file content to run |
|
|
233
|
+
| `timeout` | `number` | — | Request timeout in ms |
|
|
234
|
+
| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
|
|
235
|
+
| `retryDelay` | `number` | — | Delay between retries in ms |
|
|
72
236
|
|
|
73
237
|
### Db9 client options
|
|
74
238
|
|
|
@@ -78,6 +242,11 @@ await client.databases.applyMigration(db.id, {
|
|
|
78
242
|
| `token` | `string` | — | Bearer token (optional) |
|
|
79
243
|
| `fetch` | `FetchFn` | `globalThis.fetch` | Custom fetch |
|
|
80
244
|
| `credentialStore` | `CredentialStore` | `FileCredentialStore` | Load/save token |
|
|
245
|
+
| `timeout` | `number` | — | Request timeout in ms |
|
|
246
|
+
| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
|
|
247
|
+
| `retryDelay` | `number` | — | Delay between retries in ms |
|
|
248
|
+
| `WebSocket` | `WebSocketConstructor` | `globalThis.WebSocket` | WebSocket impl for fs operations |
|
|
249
|
+
| `wsPort` | `number` | `5480` | WebSocket port for fs9 server |
|
|
81
250
|
|
|
82
251
|
## Zero-config client
|
|
83
252
|
|
|
@@ -107,6 +276,8 @@ try {
|
|
|
107
276
|
}
|
|
108
277
|
```
|
|
109
278
|
|
|
279
|
+
> **Note:** 401 errors are automatically retried with a fresh token for anonymous sessions. You typically won't see `Db9AuthError` unless the refresh itself fails.
|
|
280
|
+
|
|
110
281
|
## Credential Storage
|
|
111
282
|
|
|
112
283
|
Credentials are stored in `~/.db9/credentials` (TOML format), shared with the db9 CLI.
|
|
@@ -124,6 +295,77 @@ const customStore = new FileCredentialStore('/path/to/credentials');
|
|
|
124
295
|
const memStore = new MemoryCredentialStore();
|
|
125
296
|
```
|
|
126
297
|
|
|
298
|
+
## API Reference
|
|
299
|
+
|
|
300
|
+
### `client.auth`
|
|
301
|
+
|
|
302
|
+
| Method | Description |
|
|
303
|
+
|--------|-------------|
|
|
304
|
+
| `register(req)` | Create account with email/password |
|
|
305
|
+
| `login(req)` | Login and get bearer token |
|
|
306
|
+
| `me()` | Get current user profile |
|
|
307
|
+
| `anonymousRegister()` | Register anonymously (auto-called) |
|
|
308
|
+
| `anonymousRefresh(req)` | Refresh anonymous token |
|
|
309
|
+
| `getAnonymousSecret()` | Retrieve anonymous secret for token refresh |
|
|
310
|
+
| `ensureAnonymousSecret()` | Ensure anonymous secret is saved to credential store |
|
|
311
|
+
| `claim(req)` | Claim anonymous account with email/password |
|
|
312
|
+
|
|
313
|
+
### `client.tokens`
|
|
314
|
+
|
|
315
|
+
| Method | Description |
|
|
316
|
+
|--------|-------------|
|
|
317
|
+
| `create(req)` | Create a named API token (`{ name?, expires_in_days? }`) |
|
|
318
|
+
| `list()` | List all tokens |
|
|
319
|
+
| `revoke(tokenId)` | Revoke a token by ID |
|
|
320
|
+
|
|
321
|
+
### `client.databases`
|
|
322
|
+
|
|
323
|
+
| Method | Description |
|
|
324
|
+
|--------|-------------|
|
|
325
|
+
| `create(req)` | Create a new database |
|
|
326
|
+
| `list()` | List all databases |
|
|
327
|
+
| `get(id)` | Get database details |
|
|
328
|
+
| `delete(id)` | Delete a database |
|
|
329
|
+
| `resetPassword(id)` | Reset admin password |
|
|
330
|
+
| `credentials(id)` | Get stored admin credentials without resetting |
|
|
331
|
+
| `observability(id)` | Get TPS, latency, connection stats |
|
|
332
|
+
| `sql(id, query)` | Execute SQL query (errors returned as `SqlErrorDetail`) |
|
|
333
|
+
| `sqlFile(id, content)` | Execute SQL from file content |
|
|
334
|
+
| `schema(id)` | Get schema metadata |
|
|
335
|
+
| `dump(id, req?)` | Export schema/data as SQL |
|
|
336
|
+
| `applyMigration(id, req)` | Apply a migration |
|
|
337
|
+
| `listMigrations(id)` | List applied migrations |
|
|
338
|
+
| `branch(id, req)` | Create a database branch |
|
|
339
|
+
| `users.list(id)` | List database users |
|
|
340
|
+
| `users.create(id, req)` | Create database user |
|
|
341
|
+
| `users.delete(id, username)` | Delete database user |
|
|
342
|
+
|
|
343
|
+
### `client.fs`
|
|
344
|
+
|
|
345
|
+
All methods auto-resolve database credentials and connect via WebSocket.
|
|
346
|
+
|
|
347
|
+
| Method | Description |
|
|
348
|
+
|--------|-------------|
|
|
349
|
+
| `connect(dbId)` | Open a persistent `FsClient` WebSocket connection |
|
|
350
|
+
| `read(dbId, path)` | Read file as text (UTF-8) |
|
|
351
|
+
| `readBinary(dbId, path)` | Read file as `Uint8Array` |
|
|
352
|
+
| `write(dbId, path, content)` | Write file (string, ArrayBuffer, or Uint8Array) |
|
|
353
|
+
| `append(dbId, path, content)` | Append to a file, returns bytes written |
|
|
354
|
+
| `list(dbId, path)` | List directory contents (returns `FileInfo[]`) |
|
|
355
|
+
| `stat(dbId, path)` | Get file metadata (`FileInfo`) |
|
|
356
|
+
| `exists(dbId, path)` | Check if file exists (returns boolean) |
|
|
357
|
+
| `mkdir(dbId, path)` | Create directory recursively |
|
|
358
|
+
| `remove(dbId, path, opts?)` | Remove file or directory (`{ recursive?: boolean }`) |
|
|
359
|
+
| `rename(dbId, old, new)` | Rename (move) a file or directory |
|
|
360
|
+
|
|
361
|
+
### `client.deviceAuth`
|
|
362
|
+
|
|
363
|
+
| Method | Description |
|
|
364
|
+
|--------|-------------|
|
|
365
|
+
| `createDeviceCode()` | Start OAuth device code flow |
|
|
366
|
+
| `pollDeviceToken(req)` | Poll for token after user authorizes |
|
|
367
|
+
| `verifyDevice(req)` | Submit device verification with email/password |
|
|
368
|
+
|
|
127
369
|
## Requirements
|
|
128
370
|
|
|
129
371
|
- Node.js >= 18 (native fetch)
|
|
@@ -54,24 +54,137 @@ declare class MemoryCredentialStore implements CredentialStore {
|
|
|
54
54
|
/** Returns a FileCredentialStore with the default path (`~/.db9/credentials`). */
|
|
55
55
|
declare function defaultCredentialStore(): CredentialStore;
|
|
56
56
|
|
|
57
|
-
/**
|
|
58
|
-
interface
|
|
57
|
+
/** File or directory metadata returned by `stat` and `readdir`. */
|
|
58
|
+
interface FileInfo {
|
|
59
59
|
path: string;
|
|
60
|
+
type: 'file' | 'dir';
|
|
60
61
|
size: number;
|
|
61
|
-
file_type: 'regular' | 'directory' | 'symlink';
|
|
62
62
|
mode: number;
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
/** Options for fs9 list operation */
|
|
72
|
-
interface Fs9ListOptions {
|
|
63
|
+
mtime: string;
|
|
64
|
+
}
|
|
65
|
+
/** Options for listing directory contents. */
|
|
66
|
+
interface FsListOptions {
|
|
67
|
+
recursive?: boolean;
|
|
68
|
+
}
|
|
69
|
+
/** Options for removing files/directories. */
|
|
70
|
+
interface FsRemoveOptions {
|
|
73
71
|
recursive?: boolean;
|
|
74
72
|
}
|
|
73
|
+
/** Base shape for all WS requests. */
|
|
74
|
+
interface FsWsRequest {
|
|
75
|
+
id: string;
|
|
76
|
+
op: string;
|
|
77
|
+
[key: string]: unknown;
|
|
78
|
+
}
|
|
79
|
+
/** Successful WS response. */
|
|
80
|
+
interface FsWsResponse {
|
|
81
|
+
id: string;
|
|
82
|
+
ok: boolean;
|
|
83
|
+
data?: unknown;
|
|
84
|
+
error?: FsWsError;
|
|
85
|
+
}
|
|
86
|
+
/** Error detail from a failed WS response. */
|
|
87
|
+
interface FsWsError {
|
|
88
|
+
code: string;
|
|
89
|
+
message: string;
|
|
90
|
+
}
|
|
91
|
+
/** Auth response data. */
|
|
92
|
+
interface FsAuthInfo {
|
|
93
|
+
user: string;
|
|
94
|
+
tenant: string;
|
|
95
|
+
keyspace: string;
|
|
96
|
+
}
|
|
97
|
+
/** Options for connecting to the fs9 WebSocket server. */
|
|
98
|
+
interface FsConnectOptions {
|
|
99
|
+
/** WebSocket URL (e.g. `wss://host:5480`). */
|
|
100
|
+
wsUrl: string;
|
|
101
|
+
/** Username in `{tenant_id}.{admin_user}` format. */
|
|
102
|
+
username: string;
|
|
103
|
+
/** Admin password. */
|
|
104
|
+
password: string;
|
|
105
|
+
}
|
|
106
|
+
/** @deprecated Use `FileInfo` instead. */
|
|
107
|
+
type Fs9FileEntry = FileInfo;
|
|
108
|
+
/** @deprecated Use `FsListOptions` instead. */
|
|
109
|
+
type Fs9ListOptions = FsListOptions;
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* WebSocket client for the fs9 filesystem protocol.
|
|
113
|
+
*
|
|
114
|
+
* Mirrors db9-cli/src/fssh/client.rs — each public method maps to a single
|
|
115
|
+
* request–response round-trip over a JSON text WebSocket.
|
|
116
|
+
*
|
|
117
|
+
* The client is environment-agnostic: pass any W3C-compatible WebSocket
|
|
118
|
+
* constructor (native `WebSocket` in browsers/Deno/Bun/Node 21+, or the
|
|
119
|
+
* `ws` npm package for Node 18–20).
|
|
120
|
+
*/
|
|
121
|
+
|
|
122
|
+
/** Minimal W3C WebSocket interface we depend on. */
|
|
123
|
+
interface WebSocketLike {
|
|
124
|
+
readonly readyState: number;
|
|
125
|
+
send(data: string): void;
|
|
126
|
+
close(code?: number, reason?: string): void;
|
|
127
|
+
onopen: ((ev: unknown) => void) | null;
|
|
128
|
+
onclose: ((ev: unknown) => void) | null;
|
|
129
|
+
onerror: ((ev: unknown) => void) | null;
|
|
130
|
+
onmessage: ((ev: {
|
|
131
|
+
data: unknown;
|
|
132
|
+
}) => void) | null;
|
|
133
|
+
}
|
|
134
|
+
/** Constructor for a W3C-compatible WebSocket. */
|
|
135
|
+
type WebSocketConstructor = new (url: string) => WebSocketLike;
|
|
136
|
+
/** Error from an fs9 WebSocket operation. */
|
|
137
|
+
declare class FsError extends Error {
|
|
138
|
+
readonly code: string;
|
|
139
|
+
constructor(code: string, message: string);
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Async WebSocket client for fs9 file operations.
|
|
143
|
+
*
|
|
144
|
+
* Usage:
|
|
145
|
+
* ```ts
|
|
146
|
+
* const client = await FsClient.connect('wss://host:5480', WebSocket);
|
|
147
|
+
* await client.authenticate('tenant.admin', 'password');
|
|
148
|
+
* const entries = await client.readdir('/');
|
|
149
|
+
* await client.close();
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
152
|
+
declare class FsClient {
|
|
153
|
+
private ws;
|
|
154
|
+
private pending;
|
|
155
|
+
private closed;
|
|
156
|
+
private constructor();
|
|
157
|
+
/**
|
|
158
|
+
* Connect to an fs9 WebSocket server.
|
|
159
|
+
*
|
|
160
|
+
* @param url WebSocket URL, e.g. `wss://host:5480`
|
|
161
|
+
* @param WS WebSocket constructor (native or from `ws` package)
|
|
162
|
+
*/
|
|
163
|
+
static connect(url: string, WS: WebSocketConstructor): Promise<FsClient>;
|
|
164
|
+
/** Authenticate with the server. Must be called first after connect. */
|
|
165
|
+
authenticate(username: string, password: string): Promise<FsAuthInfo>;
|
|
166
|
+
/** Get file or directory metadata. */
|
|
167
|
+
stat(path: string): Promise<FileInfo>;
|
|
168
|
+
/** List directory contents. */
|
|
169
|
+
readdir(path: string): Promise<FileInfo[]>;
|
|
170
|
+
/** Create a directory. Always recursive (mkdir -p). */
|
|
171
|
+
mkdir(path: string, recursive?: boolean): Promise<void>;
|
|
172
|
+
/** Read an entire file, returning raw bytes. */
|
|
173
|
+
readFile(path: string): Promise<Uint8Array>;
|
|
174
|
+
/** Write (overwrite) a file. Returns bytes written. */
|
|
175
|
+
writeFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
|
|
176
|
+
/** Append to a file. Returns bytes written. */
|
|
177
|
+
appendFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
|
|
178
|
+
/** Remove a file (non-recursive) or directory (recursive). */
|
|
179
|
+
rm(path: string, recursive?: boolean): Promise<void>;
|
|
180
|
+
/** Rename (move) a file or directory. */
|
|
181
|
+
rename(oldPath: string, newPath: string): Promise<void>;
|
|
182
|
+
/** Gracefully close the WebSocket connection. */
|
|
183
|
+
close(): Promise<void>;
|
|
184
|
+
private sendAndRecv;
|
|
185
|
+
private expectOk;
|
|
186
|
+
private errorMessage;
|
|
187
|
+
}
|
|
75
188
|
|
|
76
189
|
interface Endpoint {
|
|
77
190
|
host: string;
|
|
@@ -396,6 +509,7 @@ interface MigrationMetadata {
|
|
|
396
509
|
applied_at: string;
|
|
397
510
|
sql_preview: string;
|
|
398
511
|
}
|
|
512
|
+
/** @deprecated Fs9 events are not available in the WebSocket protocol. */
|
|
399
513
|
interface Fs9EventEntry {
|
|
400
514
|
id: string;
|
|
401
515
|
type: string;
|
|
@@ -405,12 +519,35 @@ interface Fs9EventEntry {
|
|
|
405
519
|
size?: number;
|
|
406
520
|
metadata?: Record<string, unknown>;
|
|
407
521
|
}
|
|
522
|
+
/** @deprecated Fs9 events are not available in the WebSocket protocol. */
|
|
408
523
|
interface Fs9EventOptions {
|
|
409
524
|
limit?: number;
|
|
410
525
|
offset?: number;
|
|
411
526
|
path?: string;
|
|
412
527
|
type?: string;
|
|
413
528
|
}
|
|
529
|
+
interface DeviceCodeResponse {
|
|
530
|
+
device_code: string;
|
|
531
|
+
user_code: string;
|
|
532
|
+
verification_uri: string;
|
|
533
|
+
expires_in: number;
|
|
534
|
+
interval: number;
|
|
535
|
+
}
|
|
536
|
+
interface DeviceTokenRequest {
|
|
537
|
+
device_code: string;
|
|
538
|
+
}
|
|
539
|
+
interface DeviceTokenResponse {
|
|
540
|
+
token: string;
|
|
541
|
+
expires_at: string;
|
|
542
|
+
}
|
|
543
|
+
interface DeviceTokenErrorResponse {
|
|
544
|
+
error: 'authorization_pending' | 'expired_token' | 'access_denied';
|
|
545
|
+
}
|
|
546
|
+
interface DeviceVerifyRequest {
|
|
547
|
+
user_code: string;
|
|
548
|
+
email: string;
|
|
549
|
+
password: string;
|
|
550
|
+
}
|
|
414
551
|
type TenantState = 'CREATING' | 'ACTIVE' | 'DISABLING' | 'DISABLED' | 'CREATE_FAILED';
|
|
415
552
|
|
|
416
553
|
interface Db9ClientOptions {
|
|
@@ -421,6 +558,10 @@ interface Db9ClientOptions {
|
|
|
421
558
|
timeout?: number;
|
|
422
559
|
maxRetries?: number;
|
|
423
560
|
retryDelay?: number;
|
|
561
|
+
/** WebSocket constructor for fs operations (native WebSocket, or `ws` package for Node 18–20). */
|
|
562
|
+
WebSocket?: WebSocketConstructor;
|
|
563
|
+
/** WebSocket port for fs9 server (default: 5480). */
|
|
564
|
+
wsPort?: number;
|
|
424
565
|
}
|
|
425
566
|
declare function createDb9Client(options?: Db9ClientOptions): {
|
|
426
567
|
auth: {
|
|
@@ -444,6 +585,7 @@ declare function createDb9Client(options?: Db9ClientOptions): {
|
|
|
444
585
|
get: (databaseId: string) => Promise<DatabaseResponse>;
|
|
445
586
|
delete: (databaseId: string) => Promise<MessageResponse>;
|
|
446
587
|
resetPassword: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
|
|
588
|
+
credentials: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
|
|
447
589
|
observability: (databaseId: string) => Promise<TenantObservabilityResponse>;
|
|
448
590
|
sql: (databaseId: string, query: string) => Promise<SqlResult>;
|
|
449
591
|
sqlFile: (databaseId: string, fileContent: string) => Promise<SqlResult>;
|
|
@@ -459,17 +601,43 @@ declare function createDb9Client(options?: Db9ClientOptions): {
|
|
|
459
601
|
};
|
|
460
602
|
};
|
|
461
603
|
fs: {
|
|
462
|
-
|
|
604
|
+
/**
|
|
605
|
+
* Open a persistent WebSocket connection for multiple fs operations.
|
|
606
|
+
* Caller is responsible for calling `client.close()` when done.
|
|
607
|
+
*/
|
|
608
|
+
connect: (dbId: string) => Promise<FsClient>;
|
|
609
|
+
/** List directory contents. */
|
|
610
|
+
list: (dbId: string, path: string) => Promise<FileInfo[]>;
|
|
611
|
+
/** Read a file as text (UTF-8). */
|
|
463
612
|
read: (dbId: string, path: string) => Promise<string>;
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
613
|
+
/** Read a file as raw bytes. */
|
|
614
|
+
readBinary: (dbId: string, path: string) => Promise<Uint8Array>;
|
|
615
|
+
/** Write (overwrite) a file. Accepts string, ArrayBuffer, or Uint8Array. */
|
|
616
|
+
write: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<void>;
|
|
617
|
+
/** Append to a file. Returns bytes written. */
|
|
618
|
+
append: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<number>;
|
|
619
|
+
/** Get file or directory metadata. */
|
|
620
|
+
stat: (dbId: string, path: string) => Promise<FileInfo>;
|
|
621
|
+
/** Check if a file or directory exists. */
|
|
467
622
|
exists: (dbId: string, path: string) => Promise<boolean>;
|
|
623
|
+
/** Create a directory (recursive by default). */
|
|
468
624
|
mkdir: (dbId: string, path: string) => Promise<void>;
|
|
469
|
-
|
|
470
|
-
|
|
625
|
+
/** Remove a file or directory. */
|
|
626
|
+
remove: (dbId: string, path: string, opts?: {
|
|
627
|
+
recursive?: boolean;
|
|
628
|
+
}) => Promise<void>;
|
|
629
|
+
/** Rename (move) a file or directory. */
|
|
630
|
+
rename: (dbId: string, oldPath: string, newPath: string) => Promise<void>;
|
|
631
|
+
};
|
|
632
|
+
deviceAuth: {
|
|
633
|
+
/** Start device code flow. Returns codes for user to authorize. */
|
|
634
|
+
createDeviceCode: () => Promise<DeviceCodeResponse>;
|
|
635
|
+
/** Poll for device token after user authorizes. Returns token or error status. */
|
|
636
|
+
pollDeviceToken: (req: DeviceTokenRequest) => Promise<DeviceTokenResponse | DeviceTokenErrorResponse>;
|
|
637
|
+
/** Submit device verification with user credentials. */
|
|
638
|
+
verifyDevice: (req: DeviceVerifyRequest) => Promise<MessageResponse>;
|
|
471
639
|
};
|
|
472
640
|
};
|
|
473
641
|
type Db9Client = ReturnType<typeof createDb9Client>;
|
|
474
642
|
|
|
475
|
-
export { type
|
|
643
|
+
export { type FsWsError as $, type AdminCreateUserRequest as A, type BatchCreateRequest as B, type CredentialStore as C, type DatabaseResponse as D, type Db9Client as E, type FetchFn as F, type Db9ClientOptions as G, type DeviceCodeResponse as H, type DeviceTokenErrorResponse as I, type DeviceTokenRequest as J, type DeviceTokenResponse as K, type DeviceVerifyRequest as L, type DumpRequest as M, type DumpResponse as N, type Endpoint as O, FileCredentialStore as P, type FileInfo as Q, type Fs9EventEntry as R, type Fs9EventOptions as S, type Fs9FileEntry as T, type Fs9ListOptions as U, type FsAuthInfo as V, FsClient as W, type FsConnectOptions as X, FsError as Y, type FsListOptions as Z, type FsRemoveOptions as _, type AnonymousRefreshRequest as a, type FsWsRequest as a0, type FsWsResponse as a1, type HealthResponse as a2, type HttpClient as a3, type HttpClientOptions as a4, type ListTenantsParams as a5, type LoginRequest as a6, type LoginResponse as a7, MemoryCredentialStore as a8, type MessageResponse as a9, type WebSocketLike as aA, createDb9Client as aB, defaultCredentialStore as aC, type MigrationApplyRequest as aa, type MigrationApplyResponse as ab, type MigrationMetadata as ac, type ObservabilitySummary as ad, type PasswordResetResponse as ae, type QuerySample as af, type RegisterRequest as ag, type SchemaResponse as ah, type SqlErrorDetail as ai, type SqlExecuteRequest as aj, type SqlQueryRequest as ak, type SqlQueryResponse as al, type SqlResult as am, type TableMetadata as an, type TenantConnectRequest as ao, type TenantConnectResponse as ap, type TenantListResponse as aq, type TenantObservabilityResponse as ar, type TenantResponse as as, type TenantState as at, type TenantUpdateRequest as au, type TokenResponse as av, type UserCreateResponse as aw, type UserResponse as ax, type ViewMetadata as ay, type WebSocketConstructor as az, type AnonymousRefreshResponse as b, type AnonymousRegisterResponse as c, type AnonymousSecretResponse as d, type AuditLogParams as e, type AuditLogResponse as f, type BatchCreateResponse as g, type BatchDeleteRequest as h, type BatchDeleteResponse as i, type BatchItemError as j, type BatchUpdateRequest as k, type BatchUpdateResponse as l, type BranchRequest as m, type ClaimRequest as n, type ClaimResponse as o, type ColumnInfo as p, type ColumnMetadata as q, type CreateDatabaseRequest as r, type CreateTenantRequest as s, type CreateTenantResponse as t, type CreateTokenRequest as u, type CreateTokenResponse as v, type CreateUserRequest as w, type Credentials as x, type CustomerPasswordResetResponse as y, type CustomerResponse as z };
|