get-db9 0.5.0 → 0.6.1

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,
@@ -56,7 +58,7 @@ var Db9Error = class _Db9Error extends Error {
     let message;
     try {
       const body = await response.json();
-      message = body.message || response.statusText;
+      message = body.message || body.detail || body.error_description || body.error || response.statusText;
     } catch {
       message = response.statusText;
     }
@@ -227,17 +229,7 @@ var FileCredentialStore = class {
     const parsed = (0, import_toml.parse)(content);
     const token = parsed["token"];
     if (typeof token !== "string") return null;
-    const creds = { token };
-    if (typeof parsed["is_anonymous"] === "boolean") {
-      creds.is_anonymous = parsed["is_anonymous"];
-    }
-    if (typeof parsed["anonymous_id"] === "string") {
-      creds.anonymous_id = parsed["anonymous_id"];
-    }
-    if (typeof parsed["anonymous_secret"] === "string") {
-      creds.anonymous_secret = parsed["anonymous_secret"];
-    }
-    return creds;
+    return { token };
   }
   async save(credentials) {
     const fs = await import("fs/promises");
@@ -258,15 +250,6 @@ var FileCredentialStore = class {
       if (err.code !== "ENOENT") throw err;
     }
     data["token"] = credentials.token;
-    if (credentials.is_anonymous !== void 0) {
-      data["is_anonymous"] = credentials.is_anonymous;
-    }
-    if (credentials.anonymous_id !== void 0) {
-      data["anonymous_id"] = credentials.anonymous_id;
-    }
-    if (credentials.anonymous_secret !== void 0) {
-      data["anonymous_secret"] = credentials.anonymous_secret;
-    }
     const toml = (0, import_toml.stringify)(
       data
     );
@@ -288,12 +271,7 @@ var MemoryCredentialStore = class {
     return this.credentials ? { ...this.credentials } : null;
   }
   async save(credentials) {
-    this.credentials = {
-      token: credentials.token,
-      is_anonymous: credentials.is_anonymous ?? this.credentials?.is_anonymous,
-      anonymous_id: credentials.anonymous_id ?? this.credentials?.anonymous_id,
-      anonymous_secret: credentials.anonymous_secret ?? this.credentials?.anonymous_secret
-    };
+    this.credentials = { token: credentials.token };
   }
   async clear() {
     this.credentials = null;
@@ -303,9 +281,303 @@ function defaultCredentialStore() {
   return new FileCredentialStore();
 }
 
+// src/ws.ts
+var import_node_crypto = require("crypto");
+var FsError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FsError";
+    this.code = code;
+  }
+};
+var STREAMING_THRESHOLD = 1024 * 1024;
+var DEFAULT_CHUNK_SIZE = 64 * 1024;
+var nextId = 1;
+function nextRequestId() {
+  return String(nextId++);
+}
+function toBase64(data) {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  return Buffer.from(bytes).toString("base64");
+}
+function fromBase64(b64) {
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+function computeChecksum(data) {
+  const hash = (0, import_node_crypto.createHash)("sha256").update(data).digest("hex");
+  return `sha256:${hash}`;
+}
+function encodeBinaryFrame(streamId, chunk) {
+  const frame = Buffer.alloc(8 + chunk.length);
+  frame.writeBigUInt64BE(BigInt(streamId), 0);
+  frame.set(chunk, 8);
+  return frame;
+}
+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.
+   *
+   * Automatically uses streaming mode for files >= 1 MB to avoid base64
+   * overhead and bypass the 2 MB JSON frame limit.
+   */
+  async writeFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.byteLength >= STREAMING_THRESHOLD) {
+      return this.writeFileStreaming(path, bytes);
+    }
+    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();
+    }
+  }
+  // ── streaming internals ────────────────────────────────────────
+  /**
+   * 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
+   */
+  async writeFileStreaming(path, bytes) {
+    const requestId = nextRequestId();
+    const readyResp = await this.sendAndRecv({
+      id: requestId,
+      op: "write",
+      path,
+      streaming: true,
+      size: bytes.byteLength
+    });
+    this.expectOk(readyResp);
+    const ready = readyResp.data;
+    if (!ready?.ready) {
+      throw new FsError("PROTOCOL", "server not ready for streaming");
+    }
+    const streamId = ready.stream_id;
+    const chunkSize = ready.chunk_size > 0 ? ready.chunk_size : DEFAULT_CHUNK_SIZE;
+    try {
+      for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+        const chunk = bytes.subarray(offset, offset + chunkSize);
+        const frame = encodeBinaryFrame(streamId, chunk);
+        this.ws.send(frame);
+      }
+    } catch (err) {
+      this.tryAbortStream(streamId);
+      throw new FsError("CONNECTION_ERROR", `send chunk: ${err}`);
+    }
+    const checksum = computeChecksum(bytes);
+    const finalResp = await this.sendAndRecv({
+      id: requestId,
+      stream: "end",
+      stream_id: streamId,
+      checksum
+    });
+    this.expectOk(finalResp);
+    const result = finalResp.data;
+    return result?.written ?? bytes.byteLength;
+  }
+  /** Best-effort abort of an in-progress stream so the server can clean up. */
+  tryAbortStream(streamId) {
+    try {
+      this.ws.send(JSON.stringify({ stream: "abort", stream_id: streamId }));
+    } catch {
+    }
+  }
+  // ── 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";
+  const baseUrl = options.baseUrl ?? "https://db9.ai/api";
   let token = options.token;
   let tokenLoaded = !!token;
   const store = options.credentialStore ?? defaultCredentialStore();
@@ -324,16 +596,10 @@ function createDb9Client(options = {}) {
       tokenLoaded = true;
     }
     if (!token) {
-      const reg = await publicClient.post(
-        "/customer/anonymous-register"
+      throw new Db9Error(
+        "No token available. Run `db9 login` or pass a token via Db9ClientOptions.",
+        401
       );
-      token = reg.token;
-      await store.save({
-        token: reg.token,
-        is_anonymous: reg.is_anonymous,
-        anonymous_id: reg.anonymous_id,
-        anonymous_secret: reg.anonymous_secret
-      });
     }
     return createHttpClient({
       baseUrl,
@@ -344,82 +610,46 @@ function createDb9Client(options = {}) {
       retryDelay: options.retryDelay
     });
   }
-  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 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);
-    }
+    return operation(client);
   }
-  function deriveFs9Url(dbId) {
-    const origin = baseUrl.replace(/\/api\/?$/, "");
-    return `${origin}/fs9/${dbId}`;
-  }
-  function getFsClient(dbId) {
-    const fs9Base = deriveFs9Url(dbId) + "/api/v1";
-    return createHttpClient({
-      baseUrl: fs9Base,
-      fetch: options.fetch,
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
-      timeout: options.timeout,
-      maxRetries: options.maxRetries,
-      retryDelay: options.retryDelay
-    });
+  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}'`);
+    }
+    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 withFsAuthRetry(dbId, operation) {
-    if (!token && !tokenLoaded) {
-      await getAuthClient();
+  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 client = getFsClient(dbId);
+    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);
-    } 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 = getFsClient(dbId);
-      return operation(newClient);
+    } finally {
+      await client.close();
     }
   }
   function parseSqlError(raw) {
@@ -440,50 +670,11 @@ function createDb9Client(options = {}) {
     }
     return { message: raw };
   }
-  async function fsStat(dbId, path) {
-    return withFsAuthRetry(
-      dbId,
-      (client) => client.get("/stat", { path })
-    );
-  }
-  async function fetchAnonymousSecret() {
-    return withAuthRetry(
-      (client) => client.post("/customer/anonymous-secret", {})
-    );
-  }
   return {
     auth: {
-      // Public endpoints (no token required)
-      register: (req) => publicClient.post("/customer/register", req),
-      login: (req) => publicClient.post("/customer/login", req),
-      anonymousRegister: () => publicClient.post(
-        "/customer/anonymous-register"
-      ),
-      anonymousRefresh: (req) => publicClient.post(
-        "/customer/anonymous-refresh",
-        req
-      ),
-      // Authenticated endpoints
       me: async () => withAuthRetry(
         (client) => client.get("/customer/me")
-      ),
-      getAnonymousSecret: () => {
-        return fetchAnonymousSecret();
-      },
-      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 () => withAuthRetry(
@@ -519,6 +710,11 @@ function createDb9Client(options = {}) {
           `/customer/databases/${databaseId}/reset-password`
         )
       ),
+      credentials: async (databaseId) => withAuthRetry(
+        (client) => client.get(
+          `/customer/databases/${databaseId}/credentials`
+        )
+      ),
       observability: async (databaseId) => withAuthRetry(
         (client) => client.get(
           `/customer/databases/${databaseId}/observability`
@@ -601,69 +797,62 @@ function createDb9Client(options = {}) {
       }
     },
     fs: {
-      list: async (dbId, path, options2) => {
-        const params = { path };
-        if (options2?.recursive) params.recursive = "true";
-        return withFsAuthRetry(
-          dbId,
-          (client) => client.get("/readdir", params)
-        );
-      },
-      read: async (dbId, path) => {
-        return withFsAuthRetry(dbId, async (client) => {
-          const resp = await client.getRaw("/download", { path });
-          return resp.text();
-        });
-      },
-      readBinary: async (dbId, path) => {
-        return withFsAuthRetry(dbId, async (client) => {
-          const resp = await client.getRaw("/download", { path });
-          return resp.arrayBuffer();
-        });
+      /**
+       * 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 contentType = typeof content === "string" ? "text/plain" : "application/octet-stream";
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.putRaw(`/upload?${new URLSearchParams({ path })}`, content, { "Content-Type": contentType })
-        );
-      },
-      stat: (dbId, path) => {
-        return fsStat(dbId, path);
+        await withFsClient(dbId, (client) => client.writeFile(path, content));
       },
+      /** 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 fsStat(dbId, path);
+          await withFsClient(dbId, (client) => client.stat(path));
           return true;
         } catch (err) {
-          if (err instanceof Db9Error && err.statusCode === 404) {
+          if (err instanceof FsError && err.code === "ENOENT") {
             return false;
           }
           throw err;
         }
       },
+      /** Create a directory (recursive by default). */
       mkdir: async (dbId, path) => {
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.postRaw(`/mkdir?${new URLSearchParams({ path, recursive: "true" })}`)
-        );
+        await withFsClient(dbId, (client) => client.mkdir(path, true));
       },
-      remove: async (dbId, path) => {
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.delRaw("/remove", { path })
-        );
+      /** Remove a file or directory. */
+      remove: async (dbId, path, opts) => {
+        await withFsClient(dbId, (client) => client.rm(path, opts?.recursive ?? false));
       },
-      events: async (dbId, options2) => {
-        const params = {};
-        if (options2?.limit !== void 0) params.limit = String(options2.limit);
-        if (options2?.offset !== void 0) params.offset = String(options2.offset);
-        if (options2?.path) params.path = options2.path;
-        if (options2?.type) params.type = options2.type;
-        return withFsAuthRetry(
-          dbId,
-          (client) => client.get("/events", params)
-        );
+      /** Rename (move) a file or directory. */
+      rename: async (dbId, oldPath, newPath) => {
+        await withFsClient(dbId, (client) => client.rename(oldPath, newPath));
       }
     }
   };
@@ -710,6 +899,8 @@ function toResult(db) {
   Db9Error,
   Db9NotFoundError,
   FileCredentialStore,
+  FsClient,
+  FsError,
   MemoryCredentialStore,
   createDb9Client,
   defaultCredentialStore,