get-db9 0.5.0 → 0.6.1

package/dist/{client-UKXFQNll.d.ts → client-sRIN-o-Q.d.ts}

@@ -22,9 +22,6 @@ interface HttpClient {
 /** Credential fields stored in `~/.db9/credentials` (TOML). */
 interface Credentials {
     token: string;
-    is_anonymous?: boolean;
-    anonymous_id?: string;
-    anonymous_secret?: string;
 }
 /** Async credential persistence abstraction. */
 interface CredentialStore {
@@ -54,24 +51,163 @@ declare class MemoryCredentialStore implements CredentialStore {
 /** Returns a FileCredentialStore with the default path (`~/.db9/credentials`). */
 declare function defaultCredentialStore(): CredentialStore;
 
-/** A file or directory entry from fs9 readdir/stat API */
-interface Fs9FileEntry {
+/** File or directory metadata returned by `stat` and `readdir`. */
+interface FileInfo {
     path: string;
+    type: 'file' | 'dir';
     size: number;
-    file_type: 'regular' | 'directory' | 'symlink';
     mode: number;
-    uid: number;
-    gid: number;
-    atime: number;
-    mtime: number;
-    ctime: number;
-    etag: string;
-    symlink_target?: string;
-}
-/** Options for fs9 list operation */
-interface Fs9ListOptions {
+    mtime: string;
+}
+/** Options for listing directory contents. */
+interface FsListOptions {
+    recursive?: boolean;
+}
+/** Options for removing files/directories. */
+interface FsRemoveOptions {
     recursive?: boolean;
 }
+/** Base shape for all WS requests. */
+interface FsWsRequest {
+    id: string;
+    op: string;
+    [key: string]: unknown;
+}
+/** Successful WS response. */
+interface FsWsResponse {
+    id: string;
+    ok: boolean;
+    data?: unknown;
+    error?: FsWsError;
+}
+/** Error detail from a failed WS response. */
+interface FsWsError {
+    code: string;
+    message: string;
+}
+/** Auth response data. */
+interface FsAuthInfo {
+    user: string;
+    tenant: string;
+    keyspace: string;
+}
+/** Options for connecting to the fs9 WebSocket server. */
+interface FsConnectOptions {
+    /** WebSocket URL (e.g. `wss://host:5480`). */
+    wsUrl: string;
+    /** Username in `{tenant_id}.{admin_user}` format. */
+    username: string;
+    /** Admin password. */
+    password: string;
+}
+/** @deprecated Use `FileInfo` instead. */
+type Fs9FileEntry = FileInfo;
+/** @deprecated Use `FsListOptions` instead. */
+type Fs9ListOptions = FsListOptions;
+/** Server response when ready to accept streaming binary frames. */
+interface StreamWriteReady {
+    ready: boolean;
+    stream_id: number;
+    chunk_size: number;
+}
+
+/**
+ * WebSocket client for the fs9 filesystem protocol.
+ *
+ * Mirrors db9-cli/src/fssh/client.rs — each public method maps to a single
+ * request–response round-trip over a JSON text WebSocket.
+ *
+ * For files >= 1 MB, writeFile() automatically switches to streaming mode
+ * using binary WebSocket frames to bypass the 2 MB JSON frame limit and
+ * eliminate base64 encoding overhead.
+ *
+ * Node-only: requires the `ws` package or Node 21+ native WebSocket.
+ */
+
+/** Minimal WebSocket interface we depend on (compatible with `ws` package). */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string | Buffer | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+/** Constructor for a W3C-compatible WebSocket. */
+type WebSocketConstructor = new (url: string) => WebSocketLike;
+/** Error from an fs9 WebSocket operation. */
+declare class FsError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Async WebSocket client for fs9 file operations.
+ *
+ * Usage:
+ * ```ts
+ * const client = await FsClient.connect('wss://host:5480', WebSocket);
+ * await client.authenticate('tenant.admin', 'password');
+ * const entries = await client.readdir('/');
+ * await client.close();
+ * ```
+ */
+declare class FsClient {
+    private ws;
+    private pending;
+    private closed;
+    private constructor();
+    /**
+     * Connect to an fs9 WebSocket server.
+     *
+     * @param url WebSocket URL, e.g. `wss://host:5480`
+     * @param WS  WebSocket constructor (native or from `ws` package)
+     */
+    static connect(url: string, WS: WebSocketConstructor): Promise<FsClient>;
+    /** Authenticate with the server. Must be called first after connect. */
+    authenticate(username: string, password: string): Promise<FsAuthInfo>;
+    /** Get file or directory metadata. */
+    stat(path: string): Promise<FileInfo>;
+    /** List directory contents. */
+    readdir(path: string): Promise<FileInfo[]>;
+    /** Create a directory. Always recursive (mkdir -p). */
+    mkdir(path: string, recursive?: boolean): Promise<void>;
+    /** Read an entire file, returning raw bytes. */
+    readFile(path: string): Promise<Uint8Array>;
+    /**
+     * Write (overwrite) a file. Returns bytes written.
+     *
+     * Automatically uses streaming mode for files >= 1 MB to avoid base64
+     * overhead and bypass the 2 MB JSON frame limit.
+     */
+    writeFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
+    /** Append to a file. Returns bytes written. */
+    appendFile(path: string, data: Uint8Array | ArrayBuffer | string): Promise<number>;
+    /** Remove a file (non-recursive) or directory (recursive). */
+    rm(path: string, recursive?: boolean): Promise<void>;
+    /** Rename (move) a file or directory. */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /** Gracefully close the WebSocket connection. */
+    close(): Promise<void>;
+    /**
+     * Write a file using streaming mode (binary frames, no base64).
+     *
+     * Protocol:
+     * 1. Send streaming write request with file size
+     * 2. Receive ready response with stream_id and chunk_size
+     * 3. Send binary frames: [8-byte stream_id BE][chunk_data]
+     * 4. Send stream end with checksum
+     * 5. Receive final write confirmation
+     */
+    private writeFileStreaming;
+    /** Best-effort abort of an in-progress stream so the server can clean up. */
+    private tryAbortStream;
+    private sendAndRecv;
+    private expectOk;
+    private errorMessage;
+}
 
 interface Endpoint {
     host: string;
@@ -260,14 +396,6 @@ interface TenantObservabilityResponse {
     summary: ObservabilitySummary;
     samples: QuerySample[];
 }
-interface RegisterRequest {
-    email: string;
-    password: string;
-}
-interface LoginRequest {
-    email: string;
-    password: string;
-}
 interface CreateDatabaseRequest {
     name: string;
     region?: string;
@@ -288,14 +416,6 @@ interface MigrationApplyRequest {
 interface BranchRequest {
     name: string;
 }
-interface ClaimRequest {
-    email: string;
-    password: string;
-}
-interface AnonymousRefreshRequest {
-    anonymous_id: string;
-    anonymous_secret: string;
-}
 interface CreateUserRequest {
     username: string;
     password: string;
@@ -310,34 +430,11 @@ interface CustomerResponse {
     created_at: string;
     status: string;
 }
-interface LoginResponse {
-    token: string;
-    expires_at: string;
-}
-interface AnonymousRegisterResponse {
-    token: string;
-    expires_at: string;
-    is_anonymous: boolean;
-    anonymous_id: string;
-    anonymous_secret: string;
-}
-interface AnonymousRefreshResponse {
-    token: string;
-    expires_at: string;
-}
-interface AnonymousSecretResponse {
-    anonymous_id: string;
-    anonymous_secret: string;
-}
-interface ClaimResponse {
-    id: string;
-    email: string;
-    claimed: boolean;
-}
 interface DatabaseResponse {
     id: string;
     name: string;
     state: string;
+    parent_database_id?: string;
     region?: string;
     endpoints?: Endpoint[];
     admin_user?: string;
@@ -396,6 +493,7 @@ interface MigrationMetadata {
     applied_at: string;
     sql_preview: string;
 }
+/** @deprecated Fs9 events are not available in the WebSocket protocol. */
 interface Fs9EventEntry {
     id: string;
     type: string;
@@ -405,6 +503,7 @@ interface Fs9EventEntry {
     size?: number;
     metadata?: Record<string, unknown>;
 }
+/** @deprecated Fs9 events are not available in the WebSocket protocol. */
 interface Fs9EventOptions {
     limit?: number;
     offset?: number;
@@ -421,17 +520,14 @@ interface Db9ClientOptions {
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;
+    /** WebSocket constructor for fs operations (native WebSocket, or `ws` package for Node 18–20). */
+    WebSocket?: WebSocketConstructor;
+    /** WebSocket port for fs9 server (default: 5480). */
+    wsPort?: number;
 }
 declare function createDb9Client(options?: Db9ClientOptions): {
     auth: {
-        register: (req: RegisterRequest) => Promise<CustomerResponse>;
-        login: (req: LoginRequest) => Promise<LoginResponse>;
-        anonymousRegister: () => Promise<AnonymousRegisterResponse>;
-        anonymousRefresh: (req: AnonymousRefreshRequest) => Promise<AnonymousRefreshResponse>;
         me: () => Promise<CustomerResponse>;
-        getAnonymousSecret: () => Promise<AnonymousSecretResponse>;
-        claim: (req: ClaimRequest) => Promise<ClaimResponse>;
-        ensureAnonymousSecret: () => Promise<void>;
     };
     tokens: {
         list: () => Promise<TokenResponse[]>;
@@ -444,6 +540,7 @@ declare function createDb9Client(options?: Db9ClientOptions): {
         get: (databaseId: string) => Promise<DatabaseResponse>;
         delete: (databaseId: string) => Promise<MessageResponse>;
         resetPassword: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
+        credentials: (databaseId: string) => Promise<CustomerPasswordResetResponse>;
         observability: (databaseId: string) => Promise<TenantObservabilityResponse>;
         sql: (databaseId: string, query: string) => Promise<SqlResult>;
         sqlFile: (databaseId: string, fileContent: string) => Promise<SqlResult>;
@@ -459,17 +556,35 @@ declare function createDb9Client(options?: Db9ClientOptions): {
         };
     };
     fs: {
-        list: (dbId: string, path: string, options?: Fs9ListOptions) => Promise<Fs9FileEntry[]>;
+        /**
+         * Open a persistent WebSocket connection for multiple fs operations.
+         * Caller is responsible for calling `client.close()` when done.
+         */
+        connect: (dbId: string) => Promise<FsClient>;
+        /** List directory contents. */
+        list: (dbId: string, path: string) => Promise<FileInfo[]>;
+        /** Read a file as text (UTF-8). */
         read: (dbId: string, path: string) => Promise<string>;
-        readBinary: (dbId: string, path: string) => Promise<ArrayBuffer>;
-        write: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array | Blob) => Promise<void>;
-        stat: (dbId: string, path: string) => Promise<Fs9FileEntry>;
+        /** Read a file as raw bytes. */
+        readBinary: (dbId: string, path: string) => Promise<Uint8Array>;
+        /** Write (overwrite) a file. Accepts string, ArrayBuffer, or Uint8Array. */
+        write: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<void>;
+        /** Append to a file. Returns bytes written. */
+        append: (dbId: string, path: string, content: string | ArrayBuffer | Uint8Array) => Promise<number>;
+        /** Get file or directory metadata. */
+        stat: (dbId: string, path: string) => Promise<FileInfo>;
+        /** Check if a file or directory exists. */
         exists: (dbId: string, path: string) => Promise<boolean>;
+        /** Create a directory (recursive by default). */
         mkdir: (dbId: string, path: string) => Promise<void>;
-        remove: (dbId: string, path: string) => Promise<void>;
-        events: (dbId: string, options?: Fs9EventOptions) => Promise<Fs9EventEntry[]>;
+        /** Remove a file or directory. */
+        remove: (dbId: string, path: string, opts?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+        /** Rename (move) a file or directory. */
+        rename: (dbId: string, oldPath: string, newPath: string) => Promise<void>;
     };
 };
 type Db9Client = ReturnType<typeof createDb9Client>;
 
-export { type RegisterRequest 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 DumpRequest as H, type DumpResponse as I, type Endpoint as J, FileCredentialStore as K, type Fs9EventEntry as L, type Fs9EventOptions as M, type HealthResponse as N, type HttpClient as O, type HttpClientOptions as P, type ListTenantsParams as Q, type LoginRequest as R, type LoginResponse as S, MemoryCredentialStore as T, type MessageResponse as U, type MigrationApplyRequest as V, type MigrationApplyResponse as W, type MigrationMetadata as X, type ObservabilitySummary as Y, type PasswordResetResponse as Z, type QuerySample as _, type AnonymousRefreshRequest as a, type SchemaResponse as a0, type SqlErrorDetail as a1, type SqlExecuteRequest as a2, type SqlQueryRequest as a3, type SqlQueryResponse as a4, type SqlResult as a5, type TableMetadata as a6, type TenantConnectRequest as a7, type TenantConnectResponse as a8, type TenantListResponse as a9, type TenantObservabilityResponse as aa, type TenantResponse as ab, type TenantState as ac, type TenantUpdateRequest as ad, type TokenResponse as ae, type UserCreateResponse as af, type UserResponse as ag, type ViewMetadata as ah, createDb9Client as ai, defaultCredentialStore as aj, 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 };
+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 };