get-db9 0.5.0 → 0.6.0

package/dist/{client-UKXFQNll.d.ts → client-B3NUYqOc.d.ts}

@@ -54,24 +54,137 @@ 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;
+
+/**
+ * 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.
+ *
+ * The client is environment-agnostic: pass any W3C-compatible WebSocket
+ * constructor (native `WebSocket` in browsers/Deno/Bun/Node 21+, or the
+ * `ws` npm package for Node 18–20).
+ */
+
+/** Minimal W3C WebSocket interface we depend on. */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): 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. */
+    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>;
+    private sendAndRecv;
+    private expectOk;
+    private errorMessage;
+}
 
 interface Endpoint {
     host: string;
@@ -396,6 +509,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,12 +519,35 @@ interface Fs9EventEntry {
     size?: number;
     metadata?: Record<string, unknown>;
 }
+/** @deprecated Fs9 events are not available in the WebSocket protocol. */
 interface Fs9EventOptions {
     limit?: number;
     offset?: number;
     path?: string;
     type?: string;
 }
+interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+}
+interface DeviceTokenRequest {
+    device_code: string;
+}
+interface DeviceTokenResponse {
+    token: string;
+    expires_at: string;
+}
+interface DeviceTokenErrorResponse {
+    error: 'authorization_pending' | 'expired_token' | 'access_denied';
+}
+interface DeviceVerifyRequest {
+    user_code: string;
+    email: string;
+    password: string;
+}
 type TenantState = 'CREATING' | 'ACTIVE' | 'DISABLING' | 'DISABLED' | 'CREATE_FAILED';
 
 interface Db9ClientOptions {
@@ -421,6 +558,10 @@ 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: {
@@ -444,6 +585,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 +601,43 @@ 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>;
+    };
+    deviceAuth: {
+        /** Start device code flow. Returns codes for user to authorize. */
+        createDeviceCode: () => Promise<DeviceCodeResponse>;
+        /** Poll for device token after user authorizes. Returns token or error status. */
+        pollDeviceToken: (req: DeviceTokenRequest) => Promise<DeviceTokenResponse | DeviceTokenErrorResponse>;
+        /** Submit device verification with user credentials. */
+        verifyDevice: (req: DeviceVerifyRequest) => Promise<MessageResponse>;
     };
 };
 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 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 };