get-db9 0.4.1 → 0.6.0

package/dist/client-B3NUYqOc.d.ts

@@ -0,0 +1,643 @@
+type FetchFn = typeof globalThis.fetch;
+type BodyInit = string | Blob | ArrayBuffer | FormData | URLSearchParams | ReadableStream<Uint8Array>;
+interface HttpClientOptions {
+    baseUrl: string;
+    fetch?: FetchFn;
+    headers?: Record<string, string>;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface HttpClient {
+    get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    del<T>(path: string): Promise<T>;
+    getRaw(path: string, params?: Record<string, string | undefined>): Promise<Response>;
+    putRaw(path: string, body: BodyInit, headers?: Record<string, string>): Promise<Response>;
+    postRaw(path: string, body?: BodyInit, headers?: Record<string, string>): Promise<Response>;
+    delRaw(path: string, params?: Record<string, string | undefined>): Promise<Response>;
+}
+
+/** 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 {
+    load(): Promise<Credentials | null>;
+    save(credentials: Credentials): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class FileCredentialStore implements CredentialStore {
+    private readonly customPath;
+    /**
+     * @param path — Override the credential file location.
+     *               Defaults to `~/.db9/credentials` (resolved lazily).
+     */
+    constructor(path?: string);
+    /** Resolve the credential file path (lazy to avoid top-level `os` import). */
+    private resolvePath;
+    load(): Promise<Credentials | null>;
+    save(credentials: Credentials): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class MemoryCredentialStore implements CredentialStore {
+    private credentials;
+    load(): Promise<Credentials | null>;
+    save(credentials: Credentials): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Returns a FileCredentialStore with the default path (`~/.db9/credentials`). */
+declare function defaultCredentialStore(): CredentialStore;
+
+/** File or directory metadata returned by `stat` and `readdir`. */
+interface FileInfo {
+    path: string;
+    type: 'file' | 'dir';
+    size: number;
+    mode: number;
+    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;
+    port: number;
+    type: string;
+    region?: string;
+    priority: number;
+    description?: string;
+    enabled: boolean;
+}
+interface MessageResponse {
+    message: string;
+}
+interface HealthResponse {
+    status: string;
+    pd_healthy: boolean;
+}
+interface ColumnInfo {
+    name: string;
+    type: string;
+}
+interface SqlErrorDetail {
+    message: string;
+    code?: string;
+    position?: number;
+    hint?: string;
+    detail?: string;
+}
+interface SqlResult {
+    columns: ColumnInfo[];
+    rows: unknown[][];
+    row_count: number;
+    command: string;
+    error?: string | SqlErrorDetail;
+}
+interface CreateTenantRequest {
+    admin_user?: string;
+    admin_password?: string;
+}
+interface TenantConnectRequest {
+    admin_user: string;
+    admin_password: string;
+}
+interface TenantUpdateRequest {
+    notes?: string;
+    tags?: string[];
+}
+interface AdminCreateUserRequest {
+    username: string;
+    password?: string;
+    superuser?: boolean;
+}
+interface SqlQueryRequest {
+    sql: string;
+}
+interface ListTenantsParams {
+    page?: number;
+    size?: number;
+    state?: string;
+    q?: string;
+    cursor?: string;
+    tag?: string;
+}
+interface BatchCreateRequest {
+    count: number;
+    admin_user?: string;
+    admin_password?: string;
+}
+interface BatchDeleteRequest {
+    ids: string[];
+}
+interface BatchUpdateRequest {
+    ids: string[];
+    notes?: string;
+    tags?: string[];
+}
+interface AuditLogParams {
+    tenant_id?: string;
+    operation_type?: string;
+    resource_type?: string;
+    success?: boolean;
+    limit?: number;
+    offset?: number;
+}
+interface TenantResponse {
+    id: string;
+    state: string;
+    created_at?: string;
+    created_by?: string;
+    notes?: string;
+    tags?: string[];
+    updated_at?: string;
+    state_reason?: string;
+    endpoints?: Endpoint[];
+}
+interface TenantListResponse {
+    items: TenantResponse[];
+    total: number;
+    page: number;
+    size: number;
+    next_cursor?: string;
+}
+interface CreateTenantResponse {
+    id: string;
+    admin_user: string;
+    admin_password: string;
+    connection_string: string;
+    created_at: string;
+}
+interface TenantConnectResponse {
+    session_id: string;
+    expires_at: string;
+}
+interface BatchCreateResponse {
+    created: CreateTenantResponse[];
+    failed: BatchItemError[];
+    total_requested: number;
+    total_created: number;
+}
+interface BatchDeleteResponse {
+    deleted: string[];
+    failed: BatchItemError[];
+}
+interface BatchUpdateResponse {
+    updated: string[];
+    failed: BatchItemError[];
+}
+interface BatchItemError {
+    id: string;
+    error: string;
+}
+interface UserResponse {
+    name: string;
+    is_superuser: boolean;
+    can_login: boolean;
+    can_create_db: boolean;
+    can_create_role: boolean;
+}
+interface UserCreateResponse {
+    username: string;
+    password: string;
+    connection: string;
+}
+interface PasswordResetResponse {
+    username: string;
+    password: string;
+}
+interface SqlQueryResponse {
+    success: boolean;
+    result?: string;
+    error?: string;
+}
+interface AuditLogResponse {
+    id: string;
+    timestamp: string;
+    operation_type: string;
+    resource_type: string;
+    resource_name: string;
+    tenant_id?: string;
+    operator?: string;
+    success: boolean;
+    error_message?: string;
+    extra_metadata?: unknown;
+}
+interface ObservabilitySummary {
+    window_seconds: number;
+    statement_count: number;
+    txn_commit_count: number;
+    error_count: number;
+    qps: number;
+    tps: number;
+    latency_avg_ms: number;
+    latency_p99_ms: number;
+    active_connections: number;
+}
+interface QuerySample {
+    query: string;
+    sample_count: number;
+    error_count: number;
+    latency_avg_ms: number;
+    latency_p99_ms: number;
+    latency_max_ms: number;
+    last_seen_ms_ago: number;
+}
+interface TenantObservabilityResponse {
+    summary: ObservabilitySummary;
+    samples: QuerySample[];
+}
+interface RegisterRequest {
+    email: string;
+    password: string;
+}
+interface LoginRequest {
+    email: string;
+    password: string;
+}
+interface CreateDatabaseRequest {
+    name: string;
+    region?: string;
+    admin_password?: string;
+}
+interface SqlExecuteRequest {
+    query?: string;
+    file_content?: string;
+}
+interface DumpRequest {
+    ddl_only?: boolean;
+}
+interface MigrationApplyRequest {
+    name: string;
+    sql: string;
+    checksum: string;
+}
+interface BranchRequest {
+    name: string;
+}
+interface ClaimRequest {
+    email: string;
+    password: string;
+}
+interface AnonymousRefreshRequest {
+    anonymous_id: string;
+    anonymous_secret: string;
+}
+interface CreateUserRequest {
+    username: string;
+    password: string;
+}
+interface CreateTokenRequest {
+    name?: string;
+    expires_in_days?: number;
+}
+interface CustomerResponse {
+    id: string;
+    email: string;
+    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;
+    region?: string;
+    endpoints?: Endpoint[];
+    admin_user?: string;
+    admin_password?: string;
+    created_at: string;
+    connection_string?: string;
+}
+interface CustomerPasswordResetResponse {
+    admin_user: string;
+    admin_password: string;
+    connection_string: string;
+}
+interface TokenResponse {
+    id: string;
+    name: string;
+    created_at: string;
+    expires_at?: string;
+}
+interface CreateTokenResponse {
+    id: string;
+    name: string;
+    token: string;
+    expires_at?: string;
+    created_at: string;
+}
+interface DumpResponse {
+    sql: string;
+    object_count: number;
+}
+interface SchemaResponse {
+    tables: TableMetadata[];
+    views: ViewMetadata[];
+}
+interface TableMetadata {
+    name: string;
+    schema: string;
+    columns: ColumnMetadata[];
+}
+interface ColumnMetadata {
+    name: string;
+    type: string;
+    nullable: boolean;
+    default_value?: string;
+}
+interface ViewMetadata {
+    name: string;
+    schema: string;
+}
+interface MigrationApplyResponse {
+    status: string;
+    name: string;
+}
+interface MigrationMetadata {
+    name: string;
+    checksum: string;
+    applied_at: string;
+    sql_preview: string;
+}
+/** @deprecated Fs9 events are not available in the WebSocket protocol. */
+interface Fs9EventEntry {
+    id: string;
+    type: string;
+    path: string;
+    timestamp: string;
+    user_id?: string;
+    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 {
+    baseUrl?: string;
+    token?: string;
+    fetch?: FetchFn;
+    credentialStore?: CredentialStore;
+    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[]>;
+        revoke: (tokenId: string) => Promise<MessageResponse>;
+        create: (req: CreateTokenRequest) => Promise<CreateTokenResponse>;
+    };
+    databases: {
+        create: (req: CreateDatabaseRequest) => Promise<DatabaseResponse>;
+        list: () => Promise<DatabaseResponse[]>;
+        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>;
+        schema: (databaseId: string) => Promise<SchemaResponse>;
+        dump: (databaseId: string, req?: DumpRequest) => Promise<DumpResponse>;
+        applyMigration: (databaseId: string, req: MigrationApplyRequest) => Promise<MigrationApplyResponse>;
+        listMigrations: (databaseId: string) => Promise<MigrationMetadata[]>;
+        branch: (databaseId: string, req: BranchRequest) => Promise<DatabaseResponse>;
+        users: {
+            list: (databaseId: string) => Promise<UserResponse[]>;
+            create: (databaseId: string, req: CreateUserRequest) => Promise<MessageResponse>;
+            delete: (databaseId: string, username: string) => Promise<MessageResponse>;
+        };
+    };
+    fs: {
+        /**
+         * 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>;
+        /** 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 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 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 };