get-db9 0.4.1 → 0.6.0

package/dist/index.cjs

@@ -35,6 +35,8 @@ __export(index_exports, {
   Db9Error: () => Db9Error,
   Db9NotFoundError: () => Db9NotFoundError,
   FileCredentialStore: () => FileCredentialStore,
+  FsClient: () => FsClient,
+  FsError: () => FsError,
   MemoryCredentialStore: () => MemoryCredentialStore,
   createDb9Client: () => createDb9Client,
   defaultCredentialStore: () => defaultCredentialStore,
@@ -92,6 +94,9 @@ var Db9ConflictError = class extends Db9Error {
 };
 
 // src/http.ts
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createHttpClient(options) {
   const fetchFn = options.fetch ?? globalThis.fetch;
   const baseUrl = options.baseUrl.replace(/\/$/, "");
@@ -100,38 +105,61 @@ function createHttpClient(options) {
     if (params) {
       const searchParams = new URLSearchParams();
       for (const [key, value] of Object.entries(params)) {
-        if (value !== void 0) {
-          searchParams.set(key, value);
-        }
+        if (value !== void 0) searchParams.set(key, value);
       }
       const qs = searchParams.toString();
       if (qs) url += `?${qs}`;
     }
-    const headers = {
+    const reqHeaders = {
       "Content-Type": "application/json",
       ...options.headers
     };
-    const init = { method, headers };
+    const init = { method, headers: reqHeaders };
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
-    const response = await fetchFn(url, init);
-    if (!response.ok) {
-      throw await Db9Error.fromResponse(response);
-    }
-    if (response.status === 204) {
-      return void 0;
+    const maxAttempts = Math.min(options.maxRetries ?? 0, 3) + 1;
+    const baseDelay = options.retryDelay ?? 1e3;
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      let timeoutId;
+      try {
+        const fetchInit = { ...init };
+        if (options.timeout) {
+          const controller = new AbortController();
+          fetchInit.signal = controller.signal;
+          timeoutId = setTimeout(() => controller.abort(), options.timeout);
+        }
+        const response = await fetchFn(url, fetchInit);
+        if (timeoutId) clearTimeout(timeoutId);
+        if (!response.ok) {
+          if (response.status >= 500 && attempt < maxAttempts - 1) {
+            lastError = await Db9Error.fromResponse(response);
+            await delay(baseDelay * Math.pow(2, attempt));
+            continue;
+          }
+          throw await Db9Error.fromResponse(response);
+        }
+        if (response.status === 204) return void 0;
+        return response.json();
+      } catch (err) {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (err instanceof TypeError && attempt < maxAttempts - 1) {
+          lastError = err;
+          await delay(baseDelay * Math.pow(2, attempt));
+          continue;
+        }
+        throw err;
+      }
     }
-    return response.json();
+    throw lastError;
   }
   async function requestRaw(method, path, body, params, customHeaders) {
     let url = `${baseUrl}${path}`;
     if (params) {
       const searchParams = new URLSearchParams();
       for (const [key, value] of Object.entries(params)) {
-        if (value !== void 0) {
-          searchParams.set(key, value);
-        }
+        if (value !== void 0) searchParams.set(key, value);
       }
       const qs = searchParams.toString();
       if (qs) url += `?${qs}`;
@@ -140,15 +168,23 @@ function createHttpClient(options) {
       ...options.headers,
       ...customHeaders
     };
-    const init = { method, headers };
-    if (body !== void 0) {
-      init.body = body;
+    const fetchInit = { method, headers };
+    if (body !== void 0) fetchInit.body = body;
+    let timeoutId;
+    if (options.timeout) {
+      const controller = new AbortController();
+      fetchInit.signal = controller.signal;
+      timeoutId = setTimeout(() => controller.abort(), options.timeout);
     }
-    const response = await fetchFn(url, init);
-    if (!response.ok) {
-      throw await Db9Error.fromResponse(response);
+    try {
+      const response = await fetchFn(url, fetchInit);
+      if (timeoutId) clearTimeout(timeoutId);
+      if (!response.ok) throw await Db9Error.fromResponse(response);
+      return response;
+    } catch (err) {
+      if (timeoutId) clearTimeout(timeoutId);
+      throw err;
     }
-    return response;
   }
   return {
     get: (path, params) => request("GET", path, void 0, params),
@@ -156,7 +192,9 @@ function createHttpClient(options) {
     put: (path, body) => request("PUT", path, body),
     del: (path) => request("DELETE", path),
     getRaw: (path, params) => requestRaw("GET", path, void 0, params),
-    putRaw: (path, body, headers) => requestRaw("PUT", path, body, void 0, headers)
+    putRaw: (path, body, headers) => requestRaw("PUT", path, body, void 0, headers),
+    postRaw: (path, body, headers) => requestRaw("POST", path, body, void 0, headers),
+    delRaw: (path, params) => requestRaw("DELETE", path, void 0, params)
   };
 }
 
@@ -267,6 +305,239 @@ function defaultCredentialStore() {
   return new FileCredentialStore();
 }
 
+// src/ws.ts
+var FsError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FsError";
+    this.code = code;
+  }
+};
+var nextId = 1;
+function nextRequestId() {
+  return String(nextId++);
+}
+function toBase64(data) {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+var FsClient = class _FsClient {
+  ws;
+  pending = /* @__PURE__ */ new Map();
+  closed = false;
+  constructor(ws) {
+    this.ws = ws;
+    ws.onmessage = (ev) => {
+      const text = typeof ev.data === "string" ? ev.data : String(ev.data);
+      let resp;
+      try {
+        resp = JSON.parse(text);
+      } catch {
+        return;
+      }
+      const p = this.pending.get(resp.id);
+      if (p) {
+        this.pending.delete(resp.id);
+        p.resolve(resp);
+      }
+    };
+    ws.onclose = () => {
+      this.closed = true;
+      for (const [, p] of this.pending) {
+        p.reject(new FsError("CONNECTION_CLOSED", "WebSocket connection closed"));
+      }
+      this.pending.clear();
+    };
+    ws.onerror = () => {
+    };
+  }
+  /**
+   * 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, WS) {
+    return new Promise((resolve, reject) => {
+      const ws = new WS(url);
+      ws.onopen = () => {
+        ws.onopen = null;
+        ws.onerror = null;
+        resolve(new _FsClient(ws));
+      };
+      ws.onerror = (ev) => {
+        ws.onopen = null;
+        ws.onerror = null;
+        const msg = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "WebSocket connection failed";
+        reject(new FsError("CONNECTION_ERROR", msg));
+      };
+    });
+  }
+  /** Authenticate with the server. Must be called first after connect. */
+  async authenticate(username, password) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "auth",
+      username,
+      password
+    });
+    if (!resp.ok) {
+      throw new FsError("AUTH_FAILED", this.errorMessage(resp));
+    }
+    const data = resp.data;
+    return {
+      user: String(data?.user ?? ""),
+      tenant: String(data?.tenant ?? ""),
+      keyspace: String(data?.keyspace ?? "")
+    };
+  }
+  /** Get file or directory metadata. */
+  async stat(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "stat",
+      path
+    });
+    this.expectOk(resp);
+    return resp.data;
+  }
+  /** List directory contents. */
+  async readdir(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "readdir",
+      path
+    });
+    this.expectOk(resp);
+    const data = resp.data;
+    return data?.entries ?? [];
+  }
+  /** Create a directory. Always recursive (mkdir -p). */
+  async mkdir(path, recursive = true) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "mkdir",
+      path,
+      recursive
+    });
+    this.expectOk(resp);
+  }
+  /** Read an entire file, returning raw bytes. */
+  async readFile(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "read",
+      path
+    });
+    this.expectOk(resp);
+    const data = resp.data;
+    const content = data?.content;
+    if (typeof content !== "string") {
+      throw new FsError("PROTOCOL", "missing content field in read response");
+    }
+    return fromBase64(content);
+  }
+  /** Write (overwrite) a file. Returns bytes written. */
+  async writeFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "write",
+      path,
+      content: toBase64(bytes),
+      encoding: "base64"
+    });
+    this.expectOk(resp);
+    const result = resp.data;
+    return result?.written ?? bytes.byteLength;
+  }
+  /** Append to a file. Returns bytes written. */
+  async appendFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "append",
+      path,
+      content: toBase64(bytes),
+      encoding: "base64"
+    });
+    this.expectOk(resp);
+    const result = resp.data;
+    return result?.written ?? bytes.byteLength;
+  }
+  /** Remove a file (non-recursive) or directory (recursive). */
+  async rm(path, recursive = false) {
+    const resp = await this.sendAndRecv(
+      recursive ? { id: nextRequestId(), op: "rm", path, recursive: true } : { id: nextRequestId(), op: "unlink", path }
+    );
+    this.expectOk(resp);
+  }
+  /** Rename (move) a file or directory. */
+  async rename(oldPath, newPath) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "rename",
+      old_path: oldPath,
+      new_path: newPath
+    });
+    this.expectOk(resp);
+  }
+  /** Gracefully close the WebSocket connection. */
+  async close() {
+    if (!this.closed) {
+      this.ws.close();
+    }
+  }
+  // ── internals ──────────────────────────────────────────────────
+  sendAndRecv(request) {
+    if (this.closed) {
+      return Promise.reject(new FsError("CONNECTION_CLOSED", "WebSocket is closed"));
+    }
+    return new Promise((resolve, reject) => {
+      const id = request.id;
+      this.pending.set(id, { resolve, reject });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (err) {
+        this.pending.delete(id);
+        reject(new FsError("CONNECTION_ERROR", String(err)));
+      }
+    });
+  }
+  expectOk(resp) {
+    if (!resp.ok) {
+      const detail = resp.error;
+      throw new FsError(
+        detail?.code ?? "UNKNOWN",
+        detail?.message ?? "unknown error"
+      );
+    }
+  }
+  errorMessage(resp) {
+    const detail = resp.error;
+    return detail ? `${detail.code}: ${detail.message}` : "unknown error";
+  }
+};
+
 // src/client.ts
 function createDb9Client(options = {}) {
   const baseUrl = options.baseUrl ?? "https://db9.shared.aws.tidbcloud.com/api";
@@ -276,7 +547,10 @@ function createDb9Client(options = {}) {
   const fetchFn = options.fetch ?? globalThis.fetch;
   const publicClient = createHttpClient({
     baseUrl,
-    fetch: options.fetch
+    fetch: options.fetch,
+    timeout: options.timeout,
+    maxRetries: options.maxRetries,
+    retryDelay: options.retryDelay
   });
   async function getAuthClient() {
     if (!token && !tokenLoaded) {
@@ -299,35 +573,110 @@ function createDb9Client(options = {}) {
     return createHttpClient({
       baseUrl,
       fetch: options.fetch,
-      headers: { Authorization: `Bearer ${token}` }
+      headers: { Authorization: `Bearer ${token}` },
+      timeout: options.timeout,
+      maxRetries: options.maxRetries,
+      retryDelay: options.retryDelay
     });
   }
-  function deriveFs9Url(dbId) {
-    const origin = baseUrl.replace(/\/api\/?$/, "");
-    return `${origin}/fs9/${dbId}`;
+  let refreshPromise = null;
+  async function refreshAnonymousToken() {
+    const creds = await store.load();
+    if (!creds?.anonymous_id || !creds?.anonymous_secret) {
+      throw new Error("Not an anonymous session");
+    }
+    const resp = await publicClient.post(
+      "/customer/anonymous-refresh",
+      {
+        anonymous_id: creds.anonymous_id,
+        anonymous_secret: creds.anonymous_secret
+      }
+    );
+    token = resp.token;
+    await store.save({ ...creds, token: resp.token });
   }
-  async function fsRequest(method, dbId, fsPath, body, contentType) {
-    if (!token && !tokenLoaded) {
-      await getAuthClient();
+  async function withAuthRetry(operation) {
+    const client = await getAuthClient();
+    try {
+      return await operation(client);
+    } catch (err) {
+      if (!(err instanceof Db9Error) || err.statusCode !== 401) {
+        throw err;
+      }
+      try {
+        if (!refreshPromise) {
+          refreshPromise = refreshAnonymousToken();
+        }
+        await refreshPromise;
+      } catch {
+        throw err;
+      } finally {
+        refreshPromise = null;
+      }
+      const newClient = await getAuthClient();
+      return operation(newClient);
     }
-    const fs9Url = deriveFs9Url(dbId);
-    const url = `${fs9Url}/api/v1${fsPath}`;
-    const headers = {};
-    if (token) {
-      headers["Authorization"] = `Bearer ${token}`;
+  }
+  const fsWsPort = options.wsPort ?? 5480;
+  async function resolveFsConn(dbId) {
+    const creds = await withAuthRetry(
+      (client) => client.get(
+        `/customer/databases/${dbId}/credentials`
+      )
+    );
+    const connStr = creds.connection_string;
+    const hostMatch = connStr.match(/@([^:/?]+)/);
+    const host = hostMatch?.[1];
+    if (!host) {
+      throw new Error(`Cannot parse host from connection string for database '${dbId}'`);
     }
-    if (body !== void 0) {
-      headers["Content-Type"] = contentType || "text/plain";
+    const userMatch = connStr.match(/:\/\/([^:@]+)/);
+    const username = userMatch?.[1] ?? creds.admin_user;
+    const protocol = host === "localhost" || host === "127.0.0.1" ? "ws" : "wss";
+    return {
+      wsUrl: `${protocol}://${host}:${fsWsPort}`,
+      username,
+      password: creds.admin_password
+    };
+  }
+  async function withFsClient(dbId, operation) {
+    const WS = options.WebSocket ?? (typeof globalThis !== "undefined" ? globalThis.WebSocket : void 0);
+    if (!WS) {
+      throw new Error(
+        "WebSocket constructor not available. Pass `WebSocket` in Db9ClientOptions, or use Node 21+ / a browser environment with native WebSocket support, or install the `ws` package for Node 18\u201320."
+      );
     }
-    const init = { method, headers };
-    if (body !== void 0) {
-      init.body = body;
+    const conn = await resolveFsConn(dbId);
+    const client = await FsClient.connect(conn.wsUrl, WS);
+    try {
+      await client.authenticate(conn.username, conn.password);
+      return await operation(client);
+    } finally {
+      await client.close();
+    }
+  }
+  function parseSqlError(raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "object" && parsed !== null && typeof parsed.message === "string") {
+        return parsed;
+      }
+    } catch {
     }
-    const response = await fetchFn(url, init);
-    if (!response.ok) {
-      throw await Db9Error.fromResponse(response);
+    const pgMatch = raw.match(/^(?:ERROR:\s*)?(.+?)(?:\s+DETAIL:\s+(.+?))?(?:\s+HINT:\s+(.+?))?(?:\s+\(SQLSTATE\s+(\w+)\))?$/s);
+    if (pgMatch && pgMatch[1]) {
+      const result = { message: pgMatch[1].trim() };
+      if (pgMatch[2]) result.detail = pgMatch[2].trim();
+      if (pgMatch[3]) result.hint = pgMatch[3].trim();
+      if (pgMatch[4]) result.code = pgMatch[4];
+      return result;
     }
-    return response;
+    return { message: raw };
+  }
+  async function fetchAnonymousSecret() {
+    return withAuthRetry(
+      (client) => client.post("/customer/anonymous-secret", {})
+    );
   }
   return {
     auth: {
@@ -342,196 +691,226 @@ function createDb9Client(options = {}) {
         req
       ),
       // Authenticated endpoints
-      me: async () => {
-        const client = await getAuthClient();
-        return client.get("/customer/me");
-      },
-      getAnonymousSecret: async () => {
-        const client = await getAuthClient();
-        return client.get(
-          "/customer/anonymous-secret"
-        );
+      me: async () => withAuthRetry(
+        (client) => client.get("/customer/me")
+      ),
+      getAnonymousSecret: () => {
+        return fetchAnonymousSecret();
       },
-      claim: async (req) => {
-        const client = await getAuthClient();
-        return client.post("/customer/claim", req);
+      claim: async (req) => withAuthRetry(
+        (client) => client.post("/customer/claim", req)
+      ),
+      ensureAnonymousSecret: async () => {
+        const creds = await store.load();
+        if (!creds?.anonymous_id || creds.anonymous_secret) {
+          return;
+        }
+        const resp = await fetchAnonymousSecret();
+        await store.save({
+          ...creds,
+          anonymous_secret: resp.anonymous_secret
+        });
       }
     },
     tokens: {
-      list: async () => {
-        const client = await getAuthClient();
-        return client.get("/customer/tokens");
-      },
-      revoke: async (tokenId) => {
-        const client = await getAuthClient();
-        return client.del(`/customer/tokens/${tokenId}`);
-      }
+      list: async () => withAuthRetry(
+        (client) => client.get("/customer/tokens")
+      ),
+      revoke: async (tokenId) => withAuthRetry(
+        (client) => client.del(`/customer/tokens/${tokenId}`)
+      ),
+      create: async (req) => withAuthRetry(
+        (client) => client.post("/customer/tokens", req)
+      )
     },
     databases: {
       // ── CRUD ──────────────────────────────────────────────────
-      create: async (req) => {
-        const client = await getAuthClient();
-        return client.post("/customer/databases", req);
-      },
-      list: async () => {
-        const client = await getAuthClient();
-        return client.get("/customer/databases");
-      },
-      get: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.get(
+      create: async (req) => withAuthRetry(
+        (client) => client.post("/customer/databases", req)
+      ),
+      list: async () => withAuthRetry(
+        (client) => client.get("/customer/databases")
+      ),
+      get: async (databaseId) => withAuthRetry(
+        (client) => client.get(
           `/customer/databases/${databaseId}`
-        );
-      },
-      delete: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.del(
+        )
+      ),
+      delete: async (databaseId) => withAuthRetry(
+        (client) => client.del(
           `/customer/databases/${databaseId}`
-        );
-      },
-      resetPassword: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.post(
+        )
+      ),
+      resetPassword: async (databaseId) => withAuthRetry(
+        (client) => client.post(
           `/customer/databases/${databaseId}/reset-password`
-        );
-      },
-      observability: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.get(
+        )
+      ),
+      credentials: async (databaseId) => withAuthRetry(
+        (client) => client.get(
+          `/customer/databases/${databaseId}/credentials`
+        )
+      ),
+      observability: async (databaseId) => withAuthRetry(
+        (client) => client.get(
           `/customer/databases/${databaseId}/observability`
-        );
-      },
+        )
+      ),
       // ── SQL Execution ─────────────────────────────────────────
       sql: async (databaseId, query) => {
-        const client = await getAuthClient();
-        return client.post(
-          `/customer/databases/${databaseId}/sql`,
-          { query }
+        const result = await withAuthRetry(
+          (client) => client.post(
+            `/customer/databases/${databaseId}/sql`,
+            { query }
+          )
         );
+        if (result.error && typeof result.error === "string") {
+          result.error = parseSqlError(result.error);
+        }
+        return result;
       },
       sqlFile: async (databaseId, fileContent) => {
-        const client = await getAuthClient();
-        return client.post(
-          `/customer/databases/${databaseId}/sql`,
-          { file_content: fileContent }
+        const result = await withAuthRetry(
+          (client) => client.post(
+            `/customer/databases/${databaseId}/sql`,
+            { file_content: fileContent }
+          )
         );
+        if (result.error && typeof result.error === "string") {
+          result.error = parseSqlError(result.error);
+        }
+        return result;
       },
       // ── Schema & Dump ─────────────────────────────────────────
-      schema: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.get(
+      schema: async (databaseId) => withAuthRetry(
+        (client) => client.get(
           `/customer/databases/${databaseId}/schema`
-        );
-      },
-      dump: async (databaseId, req) => {
-        const client = await getAuthClient();
-        return client.post(
+        )
+      ),
+      dump: async (databaseId, req) => withAuthRetry(
+        (client) => client.post(
           `/customer/databases/${databaseId}/dump`,
           req
-        );
-      },
+        )
+      ),
       // ── Migrations ────────────────────────────────────────────
-      applyMigration: async (databaseId, req) => {
-        const client = await getAuthClient();
-        return client.post(
+      applyMigration: async (databaseId, req) => withAuthRetry(
+        (client) => client.post(
           `/customer/databases/${databaseId}/migrations`,
           req
-        );
-      },
-      listMigrations: async (databaseId) => {
-        const client = await getAuthClient();
-        return client.get(
+        )
+      ),
+      listMigrations: async (databaseId) => withAuthRetry(
+        (client) => client.get(
           `/customer/databases/${databaseId}/migrations`
-        );
-      },
+        )
+      ),
       // ── Branching ─────────────────────────────────────────────
-      branch: async (databaseId, req) => {
-        const client = await getAuthClient();
-        return client.post(
+      branch: async (databaseId, req) => withAuthRetry(
+        (client) => client.post(
           `/customer/databases/${databaseId}/branch`,
           req
-        );
-      },
+        )
+      ),
       // ── User Management ───────────────────────────────────────
       users: {
-        list: async (databaseId) => {
-          const client = await getAuthClient();
-          return client.get(
+        list: async (databaseId) => withAuthRetry(
+          (client) => client.get(
             `/customer/databases/${databaseId}/users`
-          );
-        },
-        create: async (databaseId, req) => {
-          const client = await getAuthClient();
-          return client.post(
+          )
+        ),
+        create: async (databaseId, req) => withAuthRetry(
+          (client) => client.post(
             `/customer/databases/${databaseId}/users`,
             req
-          );
-        },
-        delete: async (databaseId, username) => {
-          const client = await getAuthClient();
-          return client.del(
+          )
+        ),
+        delete: async (databaseId, username) => withAuthRetry(
+          (client) => client.del(
             `/customer/databases/${databaseId}/users/${username}`
-          );
-        }
+          )
+        )
       }
     },
     fs: {
-      list: async (dbId, path, options2) => {
-        const params = new URLSearchParams({ path });
-        if (options2?.recursive) params.set("recursive", "true");
-        const response = await fsRequest(
-          "GET",
-          dbId,
-          `/readdir?${params.toString()}`
-        );
-        return response.json();
-      },
-      read: async (dbId, path) => {
-        const params = new URLSearchParams({ path });
-        const response = await fsRequest(
-          "GET",
-          dbId,
-          `/download?${params.toString()}`
-        );
-        return response.text();
+      /**
+       * Open a persistent WebSocket connection for multiple fs operations.
+       * Caller is responsible for calling `client.close()` when done.
+       */
+      connect: async (dbId) => {
+        const WS = options.WebSocket ?? (typeof globalThis !== "undefined" ? globalThis.WebSocket : void 0);
+        if (!WS) {
+          throw new Error(
+            "WebSocket constructor not available. Pass `WebSocket` in Db9ClientOptions, or use Node 21+ / a browser environment with native WebSocket support, or install the `ws` package for Node 18\u201320."
+          );
+        }
+        const conn = await resolveFsConn(dbId);
+        const client = await FsClient.connect(conn.wsUrl, WS);
+        await client.authenticate(conn.username, conn.password);
+        return client;
       },
+      /** List directory contents. */
+      list: async (dbId, path) => withFsClient(dbId, (client) => client.readdir(path)),
+      /** Read a file as text (UTF-8). */
+      read: async (dbId, path) => withFsClient(dbId, async (client) => {
+        const bytes = await client.readFile(path);
+        return new TextDecoder().decode(bytes);
+      }),
+      /** Read a file as raw bytes. */
+      readBinary: async (dbId, path) => withFsClient(dbId, (client) => client.readFile(path)),
+      /** Write (overwrite) a file. Accepts string, ArrayBuffer, or Uint8Array. */
       write: async (dbId, path, content) => {
-        const params = new URLSearchParams({ path });
-        await fsRequest("PUT", dbId, `/upload?${params.toString()}`, content);
+        await withFsClient(dbId, (client) => client.writeFile(path, content));
       },
-      stat: async (dbId, path) => {
-        const params = new URLSearchParams({ path });
-        const response = await fsRequest(
-          "GET",
-          dbId,
-          `/stat?${params.toString()}`
-        );
-        return response.json();
+      /** Append to a file. Returns bytes written. */
+      append: async (dbId, path, content) => withFsClient(dbId, (client) => client.appendFile(path, content)),
+      /** Get file or directory metadata. */
+      stat: async (dbId, path) => withFsClient(dbId, (client) => client.stat(path)),
+      /** Check if a file or directory exists. */
+      exists: async (dbId, path) => {
+        try {
+          await withFsClient(dbId, (client) => client.stat(path));
+          return true;
+        } catch (err) {
+          if (err instanceof FsError && err.code === "ENOENT") {
+            return false;
+          }
+          throw err;
+        }
       },
+      /** Create a directory (recursive by default). */
       mkdir: async (dbId, path) => {
-        const openResp = await fsRequest(
-          "POST",
-          dbId,
-          "/open",
-          JSON.stringify({
-            path,
-            flags: { create: true, directory: true }
-          }),
-          "application/json"
-        );
-        const { handle_id } = await openResp.json();
-        await fsRequest(
-          "POST",
-          dbId,
-          "/close",
-          JSON.stringify({ handle_id }),
-          "application/json"
-        );
+        await withFsClient(dbId, (client) => client.mkdir(path, true));
       },
-      remove: async (dbId, path) => {
-        const params = new URLSearchParams({ path });
-        await fsRequest("DELETE", dbId, `/remove?${params.toString()}`);
+      /** Remove a file or directory. */
+      remove: async (dbId, path, opts) => {
+        await withFsClient(dbId, (client) => client.rm(path, opts?.recursive ?? false));
+      },
+      /** Rename (move) a file or directory. */
+      rename: async (dbId, oldPath, newPath) => {
+        await withFsClient(dbId, (client) => client.rename(oldPath, newPath));
       }
+    },
+    // ── Device Auth Flow ─────────────────────────────────────────
+    deviceAuth: {
+      /** Start device code flow. Returns codes for user to authorize. */
+      createDeviceCode: () => publicClient.post("/customer/device-code"),
+      /** Poll for device token after user authorizes. Returns token or error status. */
+      pollDeviceToken: async (req) => {
+        try {
+          return await publicClient.post("/customer/device-token", req);
+        } catch (err) {
+          if (err instanceof Db9Error && err.statusCode === 400) {
+            const errorType = err.message;
+            if (errorType === "authorization_pending" || errorType === "expired_token" || errorType === "access_denied") {
+              return { error: errorType };
+            }
+          }
+          throw err;
+        }
+      },
+      /** Submit device verification with user credentials. */
+      verifyDevice: (req) => publicClient.post("/customer/device-verify", req)
     }
   };
 }
@@ -542,7 +921,10 @@ async function instantDatabase(options = {}) {
   const client = createDb9Client({
     baseUrl: options.baseUrl,
     fetch: options.fetch,
-    credentialStore: options.credentialStore
+    credentialStore: options.credentialStore,
+    timeout: options.timeout,
+    maxRetries: options.maxRetries,
+    retryDelay: options.retryDelay
   });
   const existing = await client.databases.list();
   const found = existing.find((db) => db.name === dbName);
@@ -574,6 +956,8 @@ function toResult(db) {
   Db9Error,
   Db9NotFoundError,
   FileCredentialStore,
+  FsClient,
+  FsError,
   MemoryCredentialStore,
   createDb9Client,
   defaultCredentialStore,