sqlite-hub 1.0.0 → 1.1.0

package/server/routes/export.js

@@ -1,9 +1,19 @@
 const express = require("express");
-const { route, successResponse } = require("../utils/errors");
+const { route, successResponse, ValidationError } = require("../utils/errors");
 
 function createExportRouter({ exportService }) {
   const router = express.Router();
 
+  function normalizeRequestFormat(format = "csv") {
+    return String(format ?? "csv").toLowerCase();
+  }
+
+  function assertJsonExportFormat(format) {
+    if (normalizeRequestFormat(format) === "parquet") {
+      throw new ValidationError("Parquet exports are binary and must use the download endpoint.");
+    }
+  }
+
   function sendExport(res, result) {
     res.setHeader("Content-Type", result.mimeType || "text/plain; charset=utf-8");
     res.setHeader(
@@ -13,13 +23,13 @@ function createExportRouter({ exportService }) {
     res.send(result.content ?? result.csv ?? "");
   }
 
-  function sendQueryExport(res, sql, format) {
-    const result = exportService.exportQuery(sql, { format });
+  async function sendQueryExport(res, sql, format) {
+    const result = await exportService.exportQueryDownload(sql, { format });
     sendExport(res, result);
   }
 
-  function exportTableFromBody(body, format) {
-    return exportService.exportTable(body?.tableName, {
+  async function exportTableFromBody(body, format) {
+    return exportService.exportTableDownload(body?.tableName, {
       sortColumn: body?.sortColumn,
       sortDirection: body?.sortDirection,
       filterColumn: body?.filterColumn,
@@ -29,13 +39,14 @@ function createExportRouter({ exportService }) {
     });
   }
 
-  function sendTableExport(res, body, format) {
-    sendExport(res, exportTableFromBody(body, format));
+  async function sendTableExport(res, body, format) {
+    sendExport(res, await exportTableFromBody(body, format));
   }
 
   router.post(
     "/query",
     route((req, res) => {
+      assertJsonExportFormat(req.body?.format);
       const result = exportService.exportQuery(req.body?.sql, {
         format: req.body?.format || "csv",
       });
@@ -57,29 +68,51 @@ function createExportRouter({ exportService }) {
 
   router.post(
     "/query.csv",
-    route((req, res) => {
-      sendQueryExport(res, req.body?.sql, "csv");
+    route(async (req, res) => {
+      await sendQueryExport(res, req.body?.sql, "csv");
     })
   );
 
   router.post(
     "/query.tsv",
-    route((req, res) => {
-      sendQueryExport(res, req.body?.sql, "tsv");
+    route(async (req, res) => {
+      await sendQueryExport(res, req.body?.sql, "tsv");
     })
   );
 
   router.post(
     "/query.md",
-    route((req, res) => {
-      sendQueryExport(res, req.body?.sql, "md");
+    route(async (req, res) => {
+      await sendQueryExport(res, req.body?.sql, "md");
+    })
+  );
+
+  router.post(
+    "/query.json",
+    route(async (req, res) => {
+      await sendQueryExport(res, req.body?.sql, "json");
+    })
+  );
+
+  router.post(
+    "/query.parquet",
+    route(async (req, res) => {
+      await sendQueryExport(res, req.body?.sql, "parquet");
     })
   );
 
   router.post(
     "/table",
     route((req, res) => {
-      const result = exportTableFromBody(req.body, req.body?.format || "csv");
+      assertJsonExportFormat(req.body?.format);
+      const result = exportService.exportTable(req.body?.tableName, {
+        sortColumn: req.body?.sortColumn,
+        sortDirection: req.body?.sortDirection,
+        filterColumn: req.body?.filterColumn,
+        filterOperator: req.body?.filterOperator,
+        filterValue: req.body?.filterValue,
+        format: req.body?.format || "csv",
+      });
 
       res.json(
         successResponse({
@@ -98,29 +131,63 @@ function createExportRouter({ exportService }) {
 
   router.post(
     "/table.csv",
-    route((req, res) => {
-      sendTableExport(res, req.body, "csv");
+    route(async (req, res) => {
+      await sendTableExport(res, req.body, "csv");
     })
   );
 
   router.post(
     "/table.tsv",
-    route((req, res) => {
-      sendTableExport(res, req.body, "tsv");
+    route(async (req, res) => {
+      await sendTableExport(res, req.body, "tsv");
     })
   );
 
   router.post(
     "/table.md",
-    route((req, res) => {
-      sendTableExport(res, req.body, "md");
+    route(async (req, res) => {
+      await sendTableExport(res, req.body, "md");
+    })
+  );
+
+  router.post(
+    "/table.json",
+    route(async (req, res) => {
+      await sendTableExport(res, req.body, "json");
+    })
+  );
+
+  router.post(
+    "/table.parquet",
+    route(async (req, res) => {
+      await sendTableExport(res, req.body, "parquet");
     })
   );
 
   router.get(
     "/table/:tableName.csv",
-    route((req, res) => {
-      const result = exportService.exportTable(req.params.tableName);
+    route(async (req, res) => {
+      const result = await exportService.exportTableDownload(req.params.tableName);
+      sendExport(res, result);
+    })
+  );
+
+  router.get(
+    "/table/:tableName.json",
+    route(async (req, res) => {
+      const result = await exportService.exportTableDownload(req.params.tableName, {
+        format: "json",
+      });
+      sendExport(res, result);
+    })
+  );
+
+  router.get(
+    "/table/:tableName.parquet",
+    route(async (req, res) => {
+      const result = await exportService.exportTableDownload(req.params.tableName, {
+        format: "parquet",
+      });
       sendExport(res, result);
     })
   );

package/server/routes/externalApi.js

@@ -1,10 +1,92 @@
 const express = require("express");
 const { createApiTokenAuth } = require("../middleware/apiTokenAuth");
-const { route, successResponse } = require("../utils/errors");
+const { readBearerToken } = require("../middleware/apiTokenAuth");
+const { AuthenticationError, ValidationError, route, successResponse } = require("../utils/errors");
+const { buildAppInfo } = require("../services/appInfoService");
 
-function createExternalApiRouter({ databaseService, tokenService }) {
+function buildRequestBaseUrl(req) {
+  const host = req.get("host") ?? `127.0.0.1:${req.socket.localPort ?? ""}`;
+  return `${req.protocol}://${host}`;
+}
+
+function readDatabaseId(req) {
+  return String(req.body?.databaseId ?? req.query.databaseId ?? "").trim();
+}
+
+function readSqlText(req) {
+  return String(req.body?.sql ?? req.body?.query ?? req.query.sql ?? req.query.query ?? "");
+}
+
+function readStoreName(req) {
+  return String(
+    req.body?.store ??
+      req.body?.storeName ??
+      req.body?.name ??
+      req.query.store ??
+      req.query.storeName ??
+      req.query.name ??
+      ""
+  ).trim();
+}
+
+function authenticateDatabaseRequest(req, tokenService, databaseId) {
+  const token = readBearerToken(req.get("authorization"));
+
+  if (!token) {
+    throw new AuthenticationError("Bearer API token is required.", {
+      code: "API_TOKEN_REQUIRED",
+    });
+  }
+
+  return tokenService.authenticate(databaseId, token);
+}
+
+function createExternalApiRouter({ databaseService, tokenService, appInfoService = buildAppInfo }) {
   const router = express.Router();
 
+  router.get(
+    "/info",
+    route(async (req, res) => {
+      const port = Number(req.socket.localPort);
+      const data = await appInfoService({
+        port: Number.isInteger(port) ? port : null,
+        url: buildRequestBaseUrl(req),
+      });
+
+      res.json(successResponse({ data }));
+    })
+  );
+
+  router.post(
+    "/query",
+    route((req, res) => {
+      const databaseId = readDatabaseId(req);
+      const sql = readSqlText(req);
+      const storeName = readStoreName(req);
+
+      if (!databaseId) {
+        throw new ValidationError("databaseId is required.");
+      }
+
+      authenticateDatabaseRequest(req, tokenService, databaseId);
+
+      const { result } = databaseService.executeRawQuery(databaseId, sql, { storeName });
+
+      res.json(
+        successResponse({
+          message: "SQL executed successfully.",
+          data: result,
+          metadata: {
+            databaseId,
+            stored: Boolean(result.storedQuery),
+          },
+          timingMs: result.timingMs,
+          readOnly: false,
+        })
+      );
+    })
+  );
+
   router.use(
     "/databases/:databaseId",
     createApiTokenAuth({ tokenService })

package/server/routes/settings.js

@@ -1,31 +1,12 @@
 const express = require("express");
-const Database = require("better-sqlite3");
-const fs = require("node:fs");
-const path = require("node:path");
-const { DatabaseRequiredError, route, successResponse } = require("../utils/errors");
-
-function readAppVersion() {
-  const packageJsonPath = path.resolve(__dirname, "..", "..", "package.json");
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-  return packageJson.version ?? "0.0.0";
-}
-
-function readSqliteVersion() {
-  const db = new Database(":memory:");
-
-  try {
-    return db.prepare("SELECT sqlite_version() AS version").get().version ?? "unknown";
-  } finally {
-    db.close();
-  }
-}
-
-function readSettingsMetadata() {
-  return {
-    appVersion: readAppVersion(),
-    sqliteVersion: readSqliteVersion(),
-  };
-}
+const { AppError, DatabaseRequiredError, route, successResponse } = require("../utils/errors");
+const {
+  checkLatestAppVersion,
+  compareSemver,
+  isNewerVersion,
+  readSettingsMetadata,
+  readSqliteVersion,
+} = require("../services/appInfoService");
 
 function getActiveTokenContext({ connectionManager, tokenService }) {
   const activeDatabase = connectionManager?.getActiveConnection?.() ?? null;
@@ -53,9 +34,10 @@ function buildSettingsMetadata(context) {
   };
 }
 
-function createSettingsRouter({ appStateStore, connectionManager, tokenService }) {
+function createSettingsRouter({ appStateStore, connectionManager, tokenService, versionCheckService }) {
   const router = express.Router();
   const context = { connectionManager, tokenService };
+  const checkVersion = versionCheckService ?? checkLatestAppVersion;
 
   router.get(
     "/",
@@ -83,6 +65,30 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService }
     })
   );
 
+  router.get(
+    "/version-check",
+    route(async (req, res) => {
+      try {
+        const result = await checkVersion();
+
+        res.json(
+          successResponse({
+            data: result,
+            metadata: readSettingsMetadata(),
+          })
+        );
+      } catch (error) {
+        throw new AppError("Version check failed. Check your internet connection and try again.", 502, {
+          code: "VERSION_CHECK_FAILED",
+          details: {
+            source: "npm",
+            message: error.message,
+          },
+        });
+      }
+    })
+  );
+
   router.post(
     "/api-tokens",
     route((req, res) => {
@@ -121,6 +127,9 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService }
 module.exports = {
   createSettingsRouter,
   buildSettingsMetadata,
+  checkLatestAppVersion,
+  compareSemver,
+  isNewerVersion,
   readSettingsMetadata,
   readSqliteVersion,
 };

package/server/services/appInfoService.js

@@ -0,0 +1,215 @@
+const Database = require("better-sqlite3");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const VERSION_CHECK_TIMEOUT_MS = 5000;
+
+function readPackageMetadata() {
+  const packageJsonPath = path.resolve(__dirname, "..", "..", "package.json");
+  return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+}
+
+function readAppVersion() {
+  const packageJson = readPackageMetadata();
+  return packageJson.version ?? "0.0.0";
+}
+
+function readPackageName() {
+  const packageJson = readPackageMetadata();
+  return packageJson.name ?? "sqlite-hub";
+}
+
+function parseSemver(value) {
+  const match = String(value ?? "")
+    .trim()
+    .replace(/^v/i, "")
+    .match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1] ?? 0),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0),
+    prerelease: match[4] ?? "",
+  };
+}
+
+function compareSemver(left, right) {
+  const leftVersion = parseSemver(left);
+  const rightVersion = parseSemver(right);
+
+  if (!leftVersion || !rightVersion) {
+    return 0;
+  }
+
+  for (const key of ["major", "minor", "patch"]) {
+    if (leftVersion[key] > rightVersion[key]) {
+      return 1;
+    }
+
+    if (leftVersion[key] < rightVersion[key]) {
+      return -1;
+    }
+  }
+
+  if (leftVersion.prerelease && !rightVersion.prerelease) {
+    return -1;
+  }
+
+  if (!leftVersion.prerelease && rightVersion.prerelease) {
+    return 1;
+  }
+
+  return leftVersion.prerelease.localeCompare(rightVersion.prerelease);
+}
+
+function isNewerVersion(candidateVersion, currentVersion) {
+  return compareSemver(candidateVersion, currentVersion) > 0;
+}
+
+function readSqliteVersion() {
+  const db = new Database(":memory:");
+
+  try {
+    return db.prepare("SELECT sqlite_version() AS version").get().version ?? "unknown";
+  } finally {
+    db.close();
+  }
+}
+
+function readSettingsMetadata() {
+  return {
+    appVersion: readAppVersion(),
+    sqliteVersion: readSqliteVersion(),
+  };
+}
+
+async function fetchJsonWithTimeout(url, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Fetch API is not available in this runtime.");
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? VERSION_CHECK_TIMEOUT_MS);
+
+  try {
+    const response = await fetchImpl(url, {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "SQLite Hub version check",
+      },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Registry responded with HTTP ${response.status}.`);
+    }
+
+    return response.json();
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function checkLatestAppVersion(options = {}) {
+  const packageName = options.packageName ?? readPackageName();
+  const currentVersion = options.currentVersion ?? readAppVersion();
+  const registryUrl =
+    options.registryUrl ??
+    `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
+  const payload = await fetchJsonWithTimeout(registryUrl, options);
+  const latestVersion = String(payload?.version ?? "").trim();
+
+  if (!latestVersion) {
+    throw new Error("Registry response did not include a version.");
+  }
+
+  return {
+    packageName,
+    currentVersion,
+    latestVersion,
+    updateAvailable: isNewerVersion(latestVersion, currentVersion),
+    checkedAt: new Date().toISOString(),
+    source: "npm",
+    releaseUrl: `https://www.npmjs.com/package/${packageName}/v/${latestVersion}`,
+  };
+}
+
+function normalizeVersionCheckStatus(versionCheck) {
+  if (!versionCheck || versionCheck.status === "unknown") {
+    return versionCheck ?? null;
+  }
+
+  if (
+    versionCheck.currentVersion &&
+    versionCheck.latestVersion &&
+    compareSemver(versionCheck.currentVersion, versionCheck.latestVersion) > 0
+  ) {
+    return {
+      ...versionCheck,
+      status: "ahead",
+    };
+  }
+
+  return {
+    ...versionCheck,
+    status: versionCheck.updateAvailable ? "update_available" : "current",
+  };
+}
+
+async function buildAppInfo(options = {}) {
+  const packageName = options.packageName ?? readPackageName();
+  const appVersion = options.currentVersion ?? readAppVersion();
+  const sqliteVersion = options.sqliteVersion ?? readSqliteVersion();
+  let versionCheck = null;
+
+  try {
+    versionCheck = await (options.versionCheckService ?? checkLatestAppVersion)({
+      ...options,
+      packageName,
+      currentVersion: appVersion,
+    });
+    versionCheck = normalizeVersionCheckStatus(versionCheck);
+  } catch (error) {
+    versionCheck = {
+      packageName,
+      currentVersion: appVersion,
+      latestVersion: null,
+      updateAvailable: null,
+      checkedAt: new Date().toISOString(),
+      source: "npm",
+      releaseUrl: null,
+      status: "unknown",
+      error: {
+        message: error.message,
+      },
+    };
+  }
+
+  return {
+    packageName,
+    appVersion,
+    sqliteVersion,
+    port: options.port ?? null,
+    url: options.url ?? null,
+    versionCheck,
+  };
+}
+
+module.exports = {
+  VERSION_CHECK_TIMEOUT_MS,
+  buildAppInfo,
+  checkLatestAppVersion,
+  compareSemver,
+  isNewerVersion,
+  readAppVersion,
+  readPackageMetadata,
+  readPackageName,
+  readSettingsMetadata,
+  readSqliteVersion,
+};

package/server/services/databaseCommandService.js

@@ -1,5 +1,5 @@
 const path = require("node:path");
-const { NotFoundError, ValidationError } = require("../utils/errors");
+const { NotFoundError, ReadOnlyError, ValidationError } = require("../utils/errors");
 const { ConnectionManager } = require("./sqlite/connectionManager");
 const { DataBrowserService } = require("./sqlite/dataBrowserService");
 const { ExportService } = require("./sqlite/exportService");
@@ -16,6 +16,11 @@ function normalizeLookupValue(value, label) {
   return normalized;
 }
 
+function normalizeOptionalValue(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized || null;
+}
+
 function getQueryTitle(item) {
   return item?.title || item?.displayTitle || item?.previewSql || item?.rawSql || "(untitled query)";
 }
@@ -160,7 +165,7 @@ function buildRowJsonObject({ row, columns = [] } = {}) {
 class DatabaseCommandService {
   constructor({ appStateStore, runtimeFactory } = {}) {
     this.appStateStore = appStateStore;
-    this.runtimeFactory = runtimeFactory ?? ((connection) => this.createReadOnlyRuntime(connection));
+    this.runtimeFactory = runtimeFactory ?? ((connection, options) => this.createRuntime(connection, options));
   }
 
   listDatabases() {
@@ -182,7 +187,7 @@ class DatabaseCommandService {
     return connection;
   }
 
-  createReadOnlyRuntime(connection) {
+  createRuntime(connection, { readOnly = true } = {}) {
     const connectionManager = new ConnectionManager({ appStateStore: this.appStateStore });
 
     connectionManager.openConnection({
@@ -191,7 +196,7 @@ class DatabaseCommandService {
       id: connection.id,
       logoPath: connection.logoPath ?? null,
       makeActive: false,
-      readOnly: true,
+      readOnly,
     });
 
     const sqlExecutor = new SqlExecutor({
@@ -215,9 +220,17 @@ class DatabaseCommandService {
     };
   }
 
-  withDatabase(databaseReference, callback) {
+  createReadOnlyRuntime(connection) {
+    return this.createRuntime(connection, { readOnly: true });
+  }
+
+  createWritableRuntime(connection) {
+    return this.createRuntime(connection, { readOnly: false });
+  }
+
+  withDatabase(databaseReference, callback, options = {}) {
     const connection = this.getDatabase(databaseReference);
-    const runtime = this.runtimeFactory(connection);
+    const runtime = this.runtimeFactory(connection, options);
 
     try {
       return callback({ connection, runtime });
@@ -322,6 +335,37 @@ class DatabaseCommandService {
     return { query, result };
   }
 
+  executeRawQuery(databaseReference, sql, options = {}) {
+    const connection = this.getDatabase(databaseReference);
+    const { name = null, storeName = null, ...executeOptions } = options;
+    const normalizedStoreName = normalizeOptionalValue(storeName ?? name);
+
+    if (connection.readOnly) {
+      throw new ReadOnlyError(`Cannot execute raw SQL against a read-only database: ${connection.label}`);
+    }
+
+    const result = this.withDatabase(
+      connection.id,
+      ({ runtime }) => runtime.sqlExecutor.execute(sql, executeOptions),
+      { readOnly: false }
+    );
+    let storedQuery = null;
+
+    if (normalizedStoreName && result.historyId) {
+      this.appStateStore.renameQuery(result.historyId, normalizedStoreName, connection.id);
+      storedQuery = this.appStateStore.toggleSaved(result.historyId, true, connection.id);
+    }
+
+    return {
+      connection,
+      result: {
+        ...result,
+        storedQuery,
+      },
+      storedQuery,
+    };
+  }
+
   exportSavedQuery(databaseReference, queryName, format = "csv") {
     const query = this.requireQuery(databaseReference, queryName);
     const result = this.withDatabase(databaseReference, ({ runtime }) =>