get-db9 0.5.0 → 0.6.1
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 +212 -6
- package/dist/{client-UKXFQNll.d.cts → client-sRIN-o-Q.d.cts} +185 -70
- package/dist/{client-UKXFQNll.d.ts → client-sRIN-o-Q.d.ts} +185 -70
- package/dist/client.cjs +380 -188
- 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 +380 -188
- package/dist/client.js.map +1 -1
- package/dist/index.cjs +385 -194
- 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 +383 -194
- package/dist/index.js.map +1 -1
- package/package.json +10 -6
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,12 +31,12 @@ 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
|
-
import { createDb9Client } from 'get-db9
|
|
37
|
+
import { createDb9Client } from 'get-db9';
|
|
38
38
|
|
|
39
|
-
//
|
|
39
|
+
// Uses the credential store if present, or auto-registers an anonymous session.
|
|
40
40
|
const client = createDb9Client();
|
|
41
41
|
|
|
42
42
|
// Create a database
|
|
@@ -57,6 +57,139 @@ 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';
|
|
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
|
+
## Anonymous + Claim
|
|
150
|
+
|
|
151
|
+
If no credentials are available, the SDK auto-registers an anonymous session on the first authenticated call and stores `token`, `is_anonymous`, `anonymous_id`, and `anonymous_secret` in the configured credential store (`~/.db9/credentials` by default).
|
|
152
|
+
|
|
153
|
+
- Run `db9 claim` (or `db9 claim --id-token <AUTH0_ID_TOKEN>`) to upgrade that account to
|
|
154
|
+
a verified Auth0 identity.
|
|
155
|
+
- After claim, continue using the stored token or create named API tokens for CI/CD and agents.
|
|
156
|
+
|
|
157
|
+
## Database Credentials
|
|
158
|
+
|
|
159
|
+
Retrieve stored admin credentials without resetting the password:
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
const client = createDb9Client();
|
|
163
|
+
const dbId = 'your-database-id';
|
|
164
|
+
|
|
165
|
+
// Get stored credentials (no password reset)
|
|
166
|
+
const creds = await client.databases.credentials(dbId);
|
|
167
|
+
console.log(creds.admin_user); // admin username
|
|
168
|
+
console.log(creds.admin_password); // current password
|
|
169
|
+
console.log(creds.connection_string); // full connection string
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## SQL Error Handling
|
|
173
|
+
|
|
174
|
+
SQL results include structured error details when queries fail:
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
const result = await client.databases.sql(dbId, 'SELECT * FROM nonexistent');
|
|
178
|
+
|
|
179
|
+
if (result.error) {
|
|
180
|
+
// result.error is a SqlErrorDetail object:
|
|
181
|
+
// {
|
|
182
|
+
// message: "relation \"nonexistent\" does not exist",
|
|
183
|
+
// code: "42P01", // PostgreSQL error code
|
|
184
|
+
// detail: "...", // optional
|
|
185
|
+
// hint: "...", // optional
|
|
186
|
+
// position: 15 // optional cursor position
|
|
187
|
+
// }
|
|
188
|
+
console.log(result.error.message);
|
|
189
|
+
console.log(result.error.code);
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
60
193
|
## Configuration
|
|
61
194
|
|
|
62
195
|
### instantDatabase options
|
|
@@ -69,6 +202,9 @@ await client.databases.applyMigration(db.id, {
|
|
|
69
202
|
| `credentialStore` | `CredentialStore` | `FileCredentialStore` | Credential storage |
|
|
70
203
|
| `seed` | `string` | — | SQL to run after creation |
|
|
71
204
|
| `seedFile` | `string` | — | SQL file content to run |
|
|
205
|
+
| `timeout` | `number` | — | Request timeout in ms |
|
|
206
|
+
| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
|
|
207
|
+
| `retryDelay` | `number` | — | Delay between retries in ms |
|
|
72
208
|
|
|
73
209
|
### Db9 client options
|
|
74
210
|
|
|
@@ -78,13 +214,18 @@ await client.databases.applyMigration(db.id, {
|
|
|
78
214
|
| `token` | `string` | — | Bearer token (optional) |
|
|
79
215
|
| `fetch` | `FetchFn` | `globalThis.fetch` | Custom fetch |
|
|
80
216
|
| `credentialStore` | `CredentialStore` | `FileCredentialStore` | Load/save token |
|
|
217
|
+
| `timeout` | `number` | — | Request timeout in ms |
|
|
218
|
+
| `maxRetries` | `number` | `3` (max) | Retry count for failed requests |
|
|
219
|
+
| `retryDelay` | `number` | — | Delay between retries in ms |
|
|
220
|
+
| `WebSocket` | `WebSocketConstructor` | `globalThis.WebSocket` | WebSocket impl for fs operations |
|
|
221
|
+
| `wsPort` | `number` | `5480` | WebSocket port for fs9 server |
|
|
81
222
|
|
|
82
223
|
## Zero-config client
|
|
83
224
|
|
|
84
225
|
```typescript
|
|
85
226
|
import { createDb9Client } from 'get-db9';
|
|
86
227
|
|
|
87
|
-
//
|
|
228
|
+
// Loads existing credentials or auto-registers an anonymous session
|
|
88
229
|
const client = createDb9Client();
|
|
89
230
|
const db = await client.databases.create({ name: 'myapp' });
|
|
90
231
|
```
|
|
@@ -92,7 +233,14 @@ const db = await client.databases.create({ name: 'myapp' });
|
|
|
92
233
|
## Error Handling
|
|
93
234
|
|
|
94
235
|
```typescript
|
|
95
|
-
import {
|
|
236
|
+
import {
|
|
237
|
+
createDb9Client,
|
|
238
|
+
Db9Error,
|
|
239
|
+
Db9AuthError,
|
|
240
|
+
Db9NotFoundError,
|
|
241
|
+
} from 'get-db9';
|
|
242
|
+
|
|
243
|
+
const client = createDb9Client();
|
|
96
244
|
|
|
97
245
|
try {
|
|
98
246
|
await client.databases.get('nonexistent');
|
|
@@ -107,6 +255,8 @@ try {
|
|
|
107
255
|
}
|
|
108
256
|
```
|
|
109
257
|
|
|
258
|
+
> **Note:** If you rely on `instanceof`, import `createDb9Client` and the error classes from the same entrypoint: `get-db9`.
|
|
259
|
+
|
|
110
260
|
## Credential Storage
|
|
111
261
|
|
|
112
262
|
Credentials are stored in `~/.db9/credentials` (TOML format), shared with the db9 CLI.
|
|
@@ -124,6 +274,62 @@ const customStore = new FileCredentialStore('/path/to/credentials');
|
|
|
124
274
|
const memStore = new MemoryCredentialStore();
|
|
125
275
|
```
|
|
126
276
|
|
|
277
|
+
## API Reference
|
|
278
|
+
|
|
279
|
+
### `client.auth`
|
|
280
|
+
|
|
281
|
+
| Method | Description |
|
|
282
|
+
|--------|-------------|
|
|
283
|
+
| `me()` | Get current user profile |
|
|
284
|
+
|
|
285
|
+
### `client.tokens`
|
|
286
|
+
|
|
287
|
+
| Method | Description |
|
|
288
|
+
|--------|-------------|
|
|
289
|
+
| `create(req)` | Create a named API token (`{ name?, expires_in_days? }`) |
|
|
290
|
+
| `list()` | List all tokens |
|
|
291
|
+
| `revoke(tokenId)` | Revoke a token by ID |
|
|
292
|
+
|
|
293
|
+
### `client.databases`
|
|
294
|
+
|
|
295
|
+
| Method | Description |
|
|
296
|
+
|--------|-------------|
|
|
297
|
+
| `create(req)` | Create a new database |
|
|
298
|
+
| `list()` | List all databases |
|
|
299
|
+
| `get(id)` | Get database details |
|
|
300
|
+
| `delete(id)` | Delete a database |
|
|
301
|
+
| `resetPassword(id)` | Reset admin password |
|
|
302
|
+
| `credentials(id)` | Get stored admin credentials without resetting |
|
|
303
|
+
| `observability(id)` | Get TPS, latency, connection stats |
|
|
304
|
+
| `sql(id, query)` | Execute SQL query (errors returned as `SqlErrorDetail`) |
|
|
305
|
+
| `sqlFile(id, content)` | Execute SQL from file content |
|
|
306
|
+
| `schema(id)` | Get schema metadata |
|
|
307
|
+
| `dump(id, req?)` | Export schema/data as SQL |
|
|
308
|
+
| `applyMigration(id, req)` | Apply a migration |
|
|
309
|
+
| `listMigrations(id)` | List applied migrations |
|
|
310
|
+
| `branch(id, req)` | Create a database branch |
|
|
311
|
+
| `users.list(id)` | List database users |
|
|
312
|
+
| `users.create(id, req)` | Create database user |
|
|
313
|
+
| `users.delete(id, username)` | Delete database user |
|
|
314
|
+
|
|
315
|
+
### `client.fs`
|
|
316
|
+
|
|
317
|
+
All methods auto-resolve database credentials and connect via WebSocket.
|
|
318
|
+
|
|
319
|
+
| Method | Description |
|
|
320
|
+
|--------|-------------|
|
|
321
|
+
| `connect(dbId)` | Open a persistent `FsClient` WebSocket connection |
|
|
322
|
+
| `read(dbId, path)` | Read file as text (UTF-8) |
|
|
323
|
+
| `readBinary(dbId, path)` | Read file as `Uint8Array` |
|
|
324
|
+
| `write(dbId, path, content)` | Write file (string, ArrayBuffer, or Uint8Array) |
|
|
325
|
+
| `append(dbId, path, content)` | Append to a file, returns bytes written |
|
|
326
|
+
| `list(dbId, path)` | List directory contents (returns `FileInfo[]`) |
|
|
327
|
+
| `stat(dbId, path)` | Get file metadata (`FileInfo`) |
|
|
328
|
+
| `exists(dbId, path)` | Check if file exists (returns boolean) |
|
|
329
|
+
| `mkdir(dbId, path)` | Create directory recursively |
|
|
330
|
+
| `remove(dbId, path, opts?)` | Remove file or directory (`{ recursive?: boolean }`) |
|
|
331
|
+
| `rename(dbId, old, new)` | Rename (move) a file or directory |
|
|
332
|
+
|
|
127
333
|
## Requirements
|
|
128
334
|
|
|
129
335
|
- Node.js >= 18 (native fetch)
|
|
@@ -22,9 +22,6 @@ interface HttpClient {
|
|
|
22
22
|
/** Credential fields stored in `~/.db9/credentials` (TOML). */
|
|
23
23
|
interface Credentials {
|
|
24
24
|
token: string;
|
|
25
|
-
is_anonymous?: boolean;
|
|
26
|
-
anonymous_id?: string;
|
|
27
|
-
anonymous_secret?: string;
|
|
28
25
|
}
|
|
29
26
|
/** Async credential persistence abstraction. */
|
|
30
27
|
interface CredentialStore {
|
|
@@ -54,24 +51,163 @@ declare class MemoryCredentialStore implements CredentialStore {
|
|
|
54
51
|
/** Returns a FileCredentialStore with the default path (`~/.db9/credentials`). */
|
|
55
52
|
declare function defaultCredentialStore(): CredentialStore;
|
|
56
53
|
|
|
57
|
-
/**
|
|
58
|
-
interface
|
|
54
|
+
/** File or directory metadata returned by `stat` and `readdir`. */
|
|
55
|
+
interface FileInfo {
|
|
59
56
|
path: string;
|
|
57
|
+
type: 'file' | 'dir';
|
|
60
58
|
size: number;
|
|
61
|
-
file_type: 'regular' | 'directory' | 'symlink';
|
|
62
59
|
mode: number;
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
/** Options for fs9 list operation */
|
|
72
|
-
interface Fs9ListOptions {
|
|
60
|
+
mtime: string;
|
|
61
|
+
}
|
|
62
|
+
/** Options for listing directory contents. */
|
|
63
|
+
interface FsListOptions {
|
|
64
|
+
recursive?: boolean;
|
|
65
|
+
}
|
|
66
|
+
/** Options for removing files/directories. */
|
|
67
|
+
interface FsRemoveOptions {
|
|
73
68
|
recursive?: boolean;
|
|
74
69
|
}
|
|
70
|
+
/** Base shape for all WS requests. */
|
|
71
|
+
interface FsWsRequest {
|
|
72
|
+
id: string;
|
|
73
|
+
op: string;
|
|
74
|
+
[key: string]: unknown;
|
|
75
|
+
}
|
|
76
|
+
/** Successful WS response. */
|
|
77
|
+
interface FsWsResponse {
|
|
78
|
+
id: string;
|
|
79
|
+
ok: boolean;
|
|
80
|
+
data?: unknown;
|
|
81
|
+
error?: FsWsError;
|
|
82
|
+
}
|
|
83
|
+
/** Error detail from a failed WS response. */
|
|
84
|
+
interface FsWsError {
|
|
85
|
+
code: string;
|
|
86
|
+
message: string;
|
|
87
|
+
}
|
|
88
|
+
/** Auth response data. */
|
|
89
|
+
interface FsAuthInfo {
|
|
90
|
+
user: string;
|
|
91
|
+
tenant: string;
|
|
92
|
+
keyspace: string;
|
|
93
|
+
}
|
|
94
|
+
/** Options for connecting to the fs9 WebSocket server. */
|
|
95
|
+
interface FsConnectOptions {
|
|
96
|
+
/** WebSocket URL (e.g. `wss://host:5480`). */
|
|
97
|
+
wsUrl: string;
|
|
98
|
+
/** Username in `{tenant_id}.{admin_user}` format. */
|
|
99
|
+
username: string;
|
|
100
|
+
/** Admin password. */
|
|
101
|
+
password: string;
|
|
102
|
+
}
|
|
103
|
+
/** @deprecated Use `FileInfo` instead. */
|
|
104
|
+
type Fs9FileEntry = FileInfo;
|
|
105
|
+
/** @deprecated Use `FsListOptions` instead. */
|
|
106
|
+
type Fs9ListOptions = FsListOptions;
|
|
107
|
+
/** Server response when ready to accept streaming binary frames. */
|
|
108
|
+
interface StreamWriteReady {
|
|
109
|
+
ready: boolean;
|
|
110
|
+
stream_id: number;
|
|
111
|
+
chunk_size: number;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* WebSocket client for the fs9 filesystem protocol.
|
|
116
|
+
*
|
|
117
|
+
* Mirrors db9-cli/src/fssh/client.rs — each public method maps to a single
|
|
118
|
+
* request–response round-trip over a JSON text WebSocket.
|
|
119
|
+
*
|
|
120
|
+
* For files >= 1 MB, writeFile() automatically switches to streaming mode
|
|
121
|
+
* using binary WebSocket frames to bypass the 2 MB JSON frame limit and
|
|
122
|
+
* eliminate base64 encoding overhead.
|
|
123
|
+
*
|
|
124
|
+
* Node-only: requires the `ws` package or Node 21+ native WebSocket.
|
|
125
|
+
*/
|
|
126
|
+
|
|
127
|
+
/** Minimal WebSocket interface we depend on (compatible with `ws` package). */
|
|
128
|
+
interface WebSocketLike {
|
|
129
|
+
readonly readyState: number;
|
|
130
|
+
send(data: string | Buffer | Uint8Array): void;
|
|
131
|
+
close(code?: number, reason?: string): void;
|
|
132
|
+
onopen: ((ev: unknown) => void) | null;
|
|
133
|
+
onclose: ((ev: unknown) => void) | null;
|
|
134
|
+
onerror: ((ev: unknown) => void) | null;
|
|
135
|
+
onmessage: ((ev: {
|
|
136
|
+
data: unknown;
|
|
137
|
+
}) => void) | null;
|
|
138
|
+
}
|
|
139
|
+
/** Constructor for a W3C-compatible WebSocket. */
|
|
140
|
+
type WebSocketConstructor = new (url: string) => WebSocketLike;
|
|
141
|
+
/** Error from an fs9 WebSocket operation. */
|
|
142
|
+
declare class FsError extends Error {
|
|
143
|
+
readonly code: string;
|
|
144
|
+
constructor(code: string, message: string);
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Async WebSocket client for fs9 file operations.
|
|
148
|
+
*
|
|
149
|
+
* Usage:
|
|
150
|
+
* ```ts
|
|
151
|
+
* const client = await FsClient.connect('wss://host:5480', WebSocket);
|
|
152
|
+
* await client.authenticate('tenant.admin', 'password');
|
|
153
|
+
* const entries = await client.readdir('/');
|
|
154
|
+
* await client.close();
|
|
155
|
+
* ```
|
|
156
|
+
*/
|
|
157
|
+
declare class FsClient {
|
|
158
|
+
private ws;
|
|
159
|
+
private pending;
|
|
160
|
+
private closed;
|
|
161
|
+
private constructor();
|
|
162
|
+
/**
|
|
163
|
+
* Connect to an fs9 WebSocket server.
|
|
164
|
+
*
|
|
165
|
+
* @param url WebSocket URL, e.g. `wss://host:5480`
|
|
166
|
+
* @param WS WebSocket constructor (native or from `ws` package)
|
|
167
|
+
*/
|
|
168
|
+
static connect(url: string, WS: WebSocketConstructor): Promise<FsClient>;
|
|
169
|
+
/** Authenticate with the server. Must be called first after connect. */
|
|
170
|
+
authenticate(username: string, password: string): Promise<FsAuthInfo>;
|
|
171
|
+
/** Get file or directory metadata. */
|
|
172
|
+
stat(path: string): Promise<FileInfo>;
|
|
173
|
+
/** List directory contents. */
|
|
174
|
+
readdir(path: string): Promise<FileInfo[]>;
|
|
175
|
+
/** Create a directory. Always recursive (mkdir -p). */
|
|
176
|
+
mkdir(path: string, recursive?: boolean): Promise<void>;
|
|
177
|
+
/** Read an entire file, returning raw bytes. */
|
|
178
|
+
readFile(path: string): Promise<Uint8Array>;
|
|
179
|
+
/**
|
|
180
|
+
* Write (overwrite) a file. Returns bytes written.
|
|
181
|
+
*
|
|
182
|
+
* Automatically uses streaming mode for files >= 1 MB to avoid base64
|
|
183
|
+
* overhead and bypass the 2 MB JSON frame limit.
|
|
184
|
+
*/
|
|
185
|
+
writeFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
|
|
186
|
+
/** Append to a file. Returns bytes written. */
|
|
187
|
+
appendFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
|
|
188
|
+
/** Remove a file (non-recursive) or directory (recursive). */
|
|
189
|
+
rm(path: string, recursive?: boolean): Promise<void>;
|
|
190
|
+
/** Rename (move) a file or directory. */
|
|
191
|
+
rename(oldPath: string, newPath: string): Promise<void>;
|
|
192
|
+
/** Gracefully close the WebSocket connection. */
|
|
193
|
+
close(): Promise<void>;
|
|
194
|
+
/**
|
|
195
|
+
* Write a file using streaming mode (binary frames, no base64).
|
|
196
|
+
*
|
|
197
|
+
* Protocol:
|
|
198
|
+
* 1. Send streaming write request with file size
|
|
199
|
+
* 2. Receive ready response with stream_id and chunk_size
|
|
200
|
+
* 3. Send binary frames: [8-byte stream_id BE][chunk_data]
|
|
201
|
+
* 4. Send stream end with checksum
|
|
202
|
+
* 5. Receive final write confirmation
|
|
203
|
+
*/
|
|
204
|
+
private writeFileStreaming;
|
|
205
|
+
/** Best-effort abort of an in-progress stream so the server can clean up. */
|
|
206
|
+
private tryAbortStream;
|
|
207
|
+
private sendAndRecv;
|
|
208
|
+
private expectOk;
|
|
209
|
+
private errorMessage;
|
|
210
|
+
}
|
|
75
211
|
|
|
76
212
|
interface Endpoint {
|
|
77
213
|
host: string;
|
|
@@ -260,14 +396,6 @@ interface TenantObservabilityResponse {
|
|
|
260
396
|
summary: ObservabilitySummary;
|
|
261
397
|
samples: QuerySample[];
|
|
262
398
|
}
|
|
263
|
-
interface RegisterRequest {
|
|
264
|
-
email: string;
|
|
265
|
-
password: string;
|
|
266
|
-
}
|
|
267
|
-
interface LoginRequest {
|
|
268
|
-
email: string;
|
|
269
|
-
password: string;
|
|
270
|
-
}
|
|
271
399
|
interface CreateDatabaseRequest {
|
|
272
400
|
name: string;
|
|
273
401
|
region?: string;
|
|
@@ -288,14 +416,6 @@ interface MigrationApplyRequest {
|
|
|
288
416
|
interface BranchRequest {
|
|
289
417
|
name: string;
|
|
290
418
|
}
|
|
291
|
-
interface ClaimRequest {
|
|
292
|
-
email: string;
|
|
293
|
-
password: string;
|
|
294
|
-
}
|
|
295
|
-
interface AnonymousRefreshRequest {
|
|
296
|
-
anonymous_id: string;
|
|
297
|
-
anonymous_secret: string;
|
|
298
|
-
}
|
|
299
419
|
interface CreateUserRequest {
|
|
300
420
|
username: string;
|
|
301
421
|
password: string;
|
|
@@ -310,34 +430,11 @@ interface CustomerResponse {
|
|
|
310
430
|
created_at: string;
|
|
311
431
|
status: string;
|
|
312
432
|
}
|
|
313
|
-
interface LoginResponse {
|
|
314
|
-
token: string;
|
|
315
|
-
expires_at: string;
|
|
316
|
-
}
|
|
317
|
-
interface AnonymousRegisterResponse {
|
|
318
|
-
token: string;
|
|
319
|
-
expires_at: string;
|
|
320
|
-
is_anonymous: boolean;
|
|
321
|
-
anonymous_id: string;
|
|
322
|
-
anonymous_secret: string;
|
|
323
|
-
}
|
|
324
|
-
interface AnonymousRefreshResponse {
|
|
325
|
-
token: string;
|
|
326
|
-
expires_at: string;
|
|
327
|
-
}
|
|
328
|
-
interface AnonymousSecretResponse {
|
|
329
|
-
anonymous_id: string;
|
|
330
|
-
anonymous_secret: string;
|
|
331
|
-
}
|
|
332
|
-
interface ClaimResponse {
|
|
333
|
-
id: string;
|
|
334
|
-
email: string;
|
|
335
|
-
claimed: boolean;
|
|
336
|
-
}
|
|
337
433
|
interface DatabaseResponse {
|
|
338
434
|
id: string;
|
|
339
435
|
name: string;
|
|
340
436
|
state: string;
|
|
437
|
+
parent_database_id?: string;
|
|
341
438
|
region?: string;
|
|
342
439
|
endpoints?: Endpoint[];
|
|
343
440
|
admin_user?: string;
|
|
@@ -396,6 +493,7 @@ interface MigrationMetadata {
|
|
|
396
493
|
applied_at: string;
|
|
397
494
|
sql_preview: string;
|
|
398
495
|
}
|
|
496
|
+
/** @deprecated Fs9 events are not available in the WebSocket protocol. */
|
|
399
497
|
interface Fs9EventEntry {
|
|
400
498
|
id: string;
|
|
401
499
|
type: string;
|
|
@@ -405,6 +503,7 @@ interface Fs9EventEntry {
|
|
|
405
503
|
size?: number;
|
|
406
504
|
metadata?: Record<string, unknown>;
|
|
407
505
|
}
|
|
506
|
+
/** @deprecated Fs9 events are not available in the WebSocket protocol. */
|
|
408
507
|
interface Fs9EventOptions {
|
|
409
508
|
limit?: number;
|
|
410
509
|
offset?: number;
|
|
@@ -421,17 +520,14 @@ interface Db9ClientOptions {
|
|
|
421
520
|
timeout?: number;
|
|
422
521
|
maxRetries?: number;
|
|
423
522
|
retryDelay?: number;
|
|
523
|
+
/** WebSocket constructor for fs operations (native WebSocket, or `ws` package for Node 18–20). */
|
|
524
|
+
WebSocket?: WebSocketConstructor;
|
|
525
|
+
/** WebSocket port for fs9 server (default: 5480). */
|
|
526
|
+
wsPort?: number;
|
|
424
527
|
}
|
|
425
528
|
declare function createDb9Client(options?: Db9ClientOptions): {
|
|
426
529
|
auth: {
|
|
427
|
-
register: (req: RegisterRequest) => Promise<CustomerResponse>;
|
|
428
|
-
login: (req: LoginRequest) => Promise<LoginResponse>;
|
|
429
|
-
anonymousRegister: () => Promise<AnonymousRegisterResponse>;
|
|
430
|
-
anonymousRefresh: (req: AnonymousRefreshRequest) => Promise<AnonymousRefreshResponse>;
|
|
431
530
|
me: () => Promise<CustomerResponse>;
|
|
432
|
-
getAnonymousSecret: () => Promise<AnonymousSecretResponse>;
|
|
433
|
-
claim: (req: ClaimRequest) => Promise<ClaimResponse>;
|
|
434
|
-
ensureAnonymousSecret: () => Promise<void>;
|
|
435
531
|
};
|
|
436
532
|
tokens: {
|
|
437
533
|
list: () => Promise<TokenResponse[]>;
|
|
@@ -444,6 +540,7 @@ declare function createDb9Client(options?: Db9ClientOptions): {
|
|
|
444
540
|
get: (databaseId: string) => Promise<DatabaseResponse>;
|
|
445
541
|
delete: (databaseId: string) => Promise<MessageResponse>;
|
|
446
542
|
resetPassword: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
|
|
543
|
+
credentials: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
|
|
447
544
|
observability: (databaseId: string) => Promise<TenantObservabilityResponse>;
|
|
448
545
|
sql: (databaseId: string, query: string) => Promise<SqlResult>;
|
|
449
546
|
sqlFile: (databaseId: string, fileContent: string) => Promise<SqlResult>;
|
|
@@ -459,17 +556,35 @@ declare function createDb9Client(options?: Db9ClientOptions): {
|
|
|
459
556
|
};
|
|
460
557
|
};
|
|
461
558
|
fs: {
|
|
462
|
-
|
|
559
|
+
/**
|
|
560
|
+
* Open a persistent WebSocket connection for multiple fs operations.
|
|
561
|
+
* Caller is responsible for calling `client.close()` when done.
|
|
562
|
+
*/
|
|
563
|
+
connect: (dbId: string) => Promise<FsClient>;
|
|
564
|
+
/** List directory contents. */
|
|
565
|
+
list: (dbId: string, path: string) => Promise<FileInfo[]>;
|
|
566
|
+
/** Read a file as text (UTF-8). */
|
|
463
567
|
read: (dbId: string, path: string) => Promise<string>;
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
568
|
+
/** Read a file as raw bytes. */
|
|
569
|
+
readBinary: (dbId: string, path: string) => Promise<Uint8Array>;
|
|
570
|
+
/** Write (overwrite) a file. Accepts string, ArrayBuffer, or Uint8Array. */
|
|
571
|
+
write: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<void>;
|
|
572
|
+
/** Append to a file. Returns bytes written. */
|
|
573
|
+
append: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<number>;
|
|
574
|
+
/** Get file or directory metadata. */
|
|
575
|
+
stat: (dbId: string, path: string) => Promise<FileInfo>;
|
|
576
|
+
/** Check if a file or directory exists. */
|
|
467
577
|
exists: (dbId: string, path: string) => Promise<boolean>;
|
|
578
|
+
/** Create a directory (recursive by default). */
|
|
468
579
|
mkdir: (dbId: string, path: string) => Promise<void>;
|
|
469
|
-
|
|
470
|
-
|
|
580
|
+
/** Remove a file or directory. */
|
|
581
|
+
remove: (dbId: string, path: string, opts?: {
|
|
582
|
+
recursive?: boolean;
|
|
583
|
+
}) => Promise<void>;
|
|
584
|
+
/** Rename (move) a file or directory. */
|
|
585
|
+
rename: (dbId: string, oldPath: string, newPath: string) => Promise<void>;
|
|
471
586
|
};
|
|
472
587
|
};
|
|
473
588
|
type Db9Client = ReturnType<typeof createDb9Client>;
|
|
474
589
|
|
|
475
|
-
export { type
|
|
590
|
+
export { type MigrationMetadata as $, type AdminCreateUserRequest as A, type BatchCreateRequest as B, type CredentialStore as C, type DatabaseResponse as D, type Endpoint as E, type FetchFn as F, type Fs9EventEntry as G, type Fs9EventOptions as H, type Fs9FileEntry as I, type Fs9ListOptions as J, type FsAuthInfo as K, FsClient as L, type FsConnectOptions as M, FsError as N, type FsListOptions as O, type FsRemoveOptions as P, type FsWsError as Q, type FsWsRequest as R, type FsWsResponse as S, type HealthResponse as T, type HttpClient as U, type HttpClientOptions as V, type ListTenantsParams as W, MemoryCredentialStore as X, type MessageResponse as Y, type MigrationApplyRequest as Z, type MigrationApplyResponse as _, type AuditLogParams as a, type ObservabilitySummary as a0, type PasswordResetResponse as a1, type QuerySample as a2, type SchemaResponse as a3, type SqlErrorDetail as a4, type SqlExecuteRequest as a5, type SqlQueryRequest as a6, type SqlQueryResponse as a7, type SqlResult as a8, type StreamWriteReady as a9, type TableMetadata as aa, type TenantConnectRequest as ab, type TenantConnectResponse as ac, type TenantListResponse as ad, type TenantObservabilityResponse as ae, type TenantResponse as af, type TenantState as ag, type TenantUpdateRequest as ah, type TokenResponse as ai, type UserCreateResponse as aj, type UserResponse as ak, type ViewMetadata as al, type WebSocketConstructor as am, type WebSocketLike as an, createDb9Client as ao, defaultCredentialStore as ap, type AuditLogResponse as b, type BatchCreateResponse as c, type BatchDeleteRequest as d, type BatchDeleteResponse as e, type BatchItemError as f, type BatchUpdateRequest as g, type BatchUpdateResponse as h, type BranchRequest as i, type ColumnInfo as j, type ColumnMetadata as k, type CreateDatabaseRequest as l, type CreateTenantRequest as m, type CreateTenantResponse as n, type CreateTokenRequest as o, type CreateTokenResponse as p, type CreateUserRequest as q, type Credentials as r, type CustomerPasswordResetResponse as s, type CustomerResponse as t, type Db9Client as u, type Db9ClientOptions as v, type DumpRequest as w, type DumpResponse as x, FileCredentialStore as y, type FileInfo as z };
|