database-devtools 0.1.0

package/dist/client/index.cjs

@@ -0,0 +1,947 @@
+'use strict';
+
+// src/types/protocol.ts
+var DevToolsRole = {
+  MOBILE: "mobile",
+  BROWSER: "browser"
+};
+var MessageType = {
+  REGISTER: "register",
+  PING: "ping",
+  PONG: "pong",
+  DEVICE_STATUS: "deviceStatus",
+  REFRESH_REQUEST: "refreshRequest",
+  SNAPSHOT_UPLOAD_REQUESTED: "snapshotUploadRequested",
+  REFRESH_STATUS: "refreshStatus",
+  SNAPSHOT_READY: "snapshotReady",
+  REFRESH_ERROR: "refreshError",
+  EXPORT_SNAPSHOT_REQUEST: "exportSnapshotRequest",
+  EXPORT_SNAPSHOT_ERROR: "exportSnapshotError",
+  BEGIN_TRANSACTION_REQUEST: "beginTransactionRequest",
+  COMMIT_TRANSACTION_REQUEST: "commitTransactionRequest",
+  ROLLBACK_TRANSACTION_REQUEST: "rollbackTransactionRequest",
+  WRITE_REQUEST: "writeRequest",
+  BEGIN_TRANSACTION: "beginTransaction",
+  COMMIT_TRANSACTION: "commitTransaction",
+  ROLLBACK_TRANSACTION: "rollbackTransaction",
+  EXECUTE_WRITE: "executeWrite",
+  TRANSACTION_ACK: "transactionAck",
+  WRITE_ACK: "writeAck",
+  TRANSACTION_STATUS: "transactionStatus",
+  WRITE_RESULT: "writeResult",
+  WRITE_ERROR: "writeError"
+};
+var DEVTOOLS_WS_PATH = "/ws";
+var DEFAULT_DEVTOOLS_PORT = 3847;
+var DEVICE_SNAPSHOT_API_PATH = "/api/devices";
+var PROJECT_DATABASE_API_PATH = "/api/project/database";
+var PROJECT_DATABASE_META_API_PATH = "/api/project/database/meta";
+var PROJECT_DATABASES_API_PATH = "/api/project/databases";
+var PROJECT_DEVICE_EXPORTS_API_PATH = "/api/project/devices";
+function buildDevToolsWsUrl(host = "localhost", port = DEFAULT_DEVTOOLS_PORT) {
+  return `ws://${host}:${port}${DEVTOOLS_WS_PATH}`;
+}
+function buildDeviceSnapshotUrl(httpBaseUrl, deviceId) {
+  const base = httpBaseUrl.replace(/\/$/, "");
+  return `${base}${DEVICE_SNAPSHOT_API_PATH}/${encodeURIComponent(deviceId)}/snapshot`;
+}
+function wsUrlToHttpUrl(wsUrl) {
+  const url = new URL(wsUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function hasMessageType(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function isSnapshotUploadRequestedMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.SNAPSHOT_UPLOAD_REQUESTED) {
+    return false;
+  }
+  const message = value;
+  return typeof message.deviceId === "string" && message.refreshType === "snapshot";
+}
+function isRefreshStatusMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.REFRESH_STATUS) {
+    return false;
+  }
+  const message = value;
+  return typeof message.deviceId === "string" && typeof message.state === "string";
+}
+function isSnapshotReadyMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.SNAPSHOT_READY) {
+    return false;
+  }
+  const message = value;
+  return typeof message.deviceId === "string" && typeof message.size === "number" && typeof message.exportedAt === "number" && typeof message.kind === "string" && typeof message.mimeType === "string";
+}
+function isRefreshErrorMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.REFRESH_ERROR) {
+    return false;
+  }
+  const message = value;
+  return typeof message.deviceId === "string" && typeof message.code === "string";
+}
+function isExportSnapshotErrorMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.EXPORT_SNAPSHOT_ERROR) {
+    return false;
+  }
+  const message = value;
+  return typeof message.code === "string" && typeof message.message === "string";
+}
+function isPingMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.PING) {
+    return false;
+  }
+  const message = value;
+  return typeof message.pingId === "string";
+}
+function isDeviceStatusMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.DEVICE_STATUS) {
+    return false;
+  }
+  const message = value;
+  return typeof message.payload === "object" && message.payload !== null;
+}
+function isBeginTransactionMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.BEGIN_TRANSACTION) {
+    return false;
+  }
+  const message = value;
+  return typeof message.transactionId === "string";
+}
+function isCommitTransactionMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.COMMIT_TRANSACTION) {
+    return false;
+  }
+  const message = value;
+  return typeof message.transactionId === "string";
+}
+function isRollbackTransactionMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.ROLLBACK_TRANSACTION) {
+    return false;
+  }
+  const message = value;
+  return typeof message.transactionId === "string";
+}
+function isExecuteWriteMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.EXECUTE_WRITE) {
+    return false;
+  }
+  const message = value;
+  return typeof message.writeId === "string" && typeof message.transactionId === "string" && typeof message.operation === "object" && message.operation !== null;
+}
+function isTransactionStatusMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.TRANSACTION_STATUS) {
+    return false;
+  }
+  const message = value;
+  return typeof message.transactionId === "string" && typeof message.deviceId === "string" && typeof message.state === "string";
+}
+function isWriteResultMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.WRITE_RESULT) {
+    return false;
+  }
+  const message = value;
+  return typeof message.writeId === "string" && typeof message.transactionId === "string" && typeof message.rowsAffected === "number";
+}
+function isWriteErrorMessage(value) {
+  if (!hasMessageType(value) || value.type !== MessageType.WRITE_ERROR) {
+    return false;
+  }
+  const message = value;
+  return typeof message.transactionId === "string" && typeof message.code === "string";
+}
+
+// src/utils/ids.ts
+function generateDeviceId() {
+  return generateUniqueId("device");
+}
+function generateTransactionId() {
+  return generateUniqueId("txn");
+}
+function generateWriteId() {
+  return generateUniqueId("write");
+}
+function generateUniqueId(prefix) {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return `${prefix}-${crypto.randomUUID()}`;
+  }
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${Date.now()}-${random}`;
+}
+
+// src/utils/reconnect.ts
+var DEFAULT_BASE_MS = 1e3;
+var DEFAULT_MAX_MS = 3e4;
+var DEFAULT_JITTER_MS = 500;
+function calculateBackoffDelay(attempt, options = {}) {
+  const baseMs = options.baseMs ?? DEFAULT_BASE_MS;
+  const maxMs = options.maxMs ?? DEFAULT_MAX_MS;
+  const jitterMs = options.jitterMs ?? DEFAULT_JITTER_MS;
+  const exponential = baseMs * 2 ** attempt;
+  const capped = Math.min(exponential, maxMs);
+  const jitter = Math.floor(Math.random() * jitterMs);
+  return capped + jitter;
+}
+var ReconnectScheduler = class {
+  attempt = 0;
+  timer = null;
+  onReconnect;
+  options;
+  constructor({ onReconnect, ...options }) {
+    this.onReconnect = onReconnect;
+    this.options = options;
+  }
+  schedule() {
+    if (this.timer !== null) {
+      return;
+    }
+    const delay = calculateBackoffDelay(this.attempt, this.options);
+    this.attempt += 1;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.onReconnect();
+    }, delay);
+  }
+  reset() {
+    this.attempt = 0;
+    this.cancel();
+  }
+  cancel() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/client/createDevToolsClient.ts
+var WRITE_TIMEOUT_MS = 3e4;
+function createDevToolsClient(options = {}) {
+  const role = options.role ?? DevToolsRole.MOBILE;
+  const WebSocketImpl = options.WebSocketImpl ?? globalThis.WebSocket;
+  if (!WebSocketImpl) {
+    throw new Error("WebSocket is not available in this environment.");
+  }
+  let socket = null;
+  let deviceStatus = null;
+  let connectionState = "disconnected";
+  let lastConnectionError = null;
+  let intentionalDisconnect = false;
+  let transactionState = "idle";
+  let activeTransactionId = null;
+  let activeDeviceId = null;
+  const pendingTransaction = /* @__PURE__ */ new Map();
+  const pendingWrites = /* @__PURE__ */ new Map();
+  const deviceId = role === DevToolsRole.MOBILE ? options.deviceId ?? generateDeviceId() : void 0;
+  let wsUrl = options.serverUrl ?? buildDevToolsWsUrl("localhost", DEFAULT_DEVTOOLS_PORT);
+  const setConnectionState = (state) => {
+    if (connectionState === state) {
+      return;
+    }
+    connectionState = state;
+    options.onConnectionStateChange?.(state);
+  };
+  const setTransactionState = (state) => {
+    if (transactionState === state) {
+      return;
+    }
+    transactionState = state;
+    options.onTransactionStateChange?.(state);
+  };
+  const resetTransaction = () => {
+    setTransactionState("idle");
+    activeTransactionId = null;
+    activeDeviceId = null;
+  };
+  const rejectPendingTransaction = (transactionId, error) => {
+    const pending = pendingTransaction.get(transactionId);
+    if (pending) {
+      pending.reject(error);
+      pendingTransaction.delete(transactionId);
+    }
+  };
+  const rejectAllPending = (error) => {
+    for (const [id, pending] of pendingTransaction) {
+      pending.reject(error);
+      pendingTransaction.delete(id);
+    }
+    for (const [id, pending] of pendingWrites) {
+      pending.reject(error);
+      pendingWrites.delete(id);
+    }
+    resetTransaction();
+  };
+  const reconnectScheduler = new ReconnectScheduler({
+    onReconnect: () => {
+      openSocket();
+    }
+  });
+  const send = (message) => {
+    if (!socket || socket.readyState !== WebSocketImpl.OPEN) {
+      return;
+    }
+    socket.send(JSON.stringify({ ...message, timestamp: Date.now() }));
+  };
+  const sendRegister = () => {
+    send({
+      type: MessageType.REGISTER,
+      role,
+      ...deviceId ? { deviceId } : {},
+      ...options.metadata ? { metadata: options.metadata } : {}
+    });
+  };
+  const handleServerMessage = (parsed) => {
+    if (isPingMessage(parsed)) {
+      send({
+        type: MessageType.PONG,
+        pingId: parsed.pingId
+      });
+      return;
+    }
+    if (isDeviceStatusMessage(parsed)) {
+      deviceStatus = parsed.payload;
+      options.onDeviceStatus?.(parsed.payload);
+      return;
+    }
+    if (isSnapshotUploadRequestedMessage(parsed)) {
+      options.onSnapshotUploadRequested?.(parsed);
+      return;
+    }
+    if (isExportSnapshotErrorMessage(parsed)) {
+      options.onExportSnapshotError?.(parsed);
+      return;
+    }
+    if (isRefreshStatusMessage(parsed)) {
+      options.onRefreshStatus?.(parsed);
+      return;
+    }
+    if (isSnapshotReadyMessage(parsed)) {
+      options.onSnapshotReady?.(parsed);
+      return;
+    }
+    if (isRefreshErrorMessage(parsed)) {
+      options.onRefreshError?.(parsed);
+      return;
+    }
+    if (isBeginTransactionMessage(parsed)) {
+      options.onBeginTransaction?.(parsed);
+      return;
+    }
+    if (isCommitTransactionMessage(parsed)) {
+      options.onCommitTransaction?.(parsed);
+      return;
+    }
+    if (isRollbackTransactionMessage(parsed)) {
+      options.onRollbackTransaction?.(parsed);
+      return;
+    }
+    if (isExecuteWriteMessage(parsed)) {
+      options.onExecuteWrite?.(parsed);
+      return;
+    }
+    if (isTransactionStatusMessage(parsed)) {
+      options.onTransactionStatus?.(parsed);
+      if (role !== DevToolsRole.BROWSER) {
+        return;
+      }
+      const pending = pendingTransaction.get(parsed.transactionId);
+      if (parsed.state === "open" && pending?.action === "begin") {
+        setTransactionState("open");
+        activeTransactionId = parsed.transactionId;
+        activeDeviceId = parsed.deviceId;
+        pending.resolve();
+        pendingTransaction.delete(parsed.transactionId);
+        return;
+      }
+      if (parsed.state === "idle" && pending && (pending.action === "commit" || pending.action === "rollback")) {
+        resetTransaction();
+        pending.resolve();
+        pendingTransaction.delete(parsed.transactionId);
+        return;
+      }
+      if (parsed.state === "failed") {
+        rejectPendingTransaction(
+          parsed.transactionId,
+          new Error(parsed.message ?? "Transaction failed")
+        );
+        resetTransaction();
+      }
+      return;
+    }
+    if (isWriteResultMessage(parsed)) {
+      options.onWriteResult?.(parsed);
+      const pending = pendingWrites.get(parsed.writeId);
+      if (pending) {
+        pending.resolve({ rowsAffected: parsed.rowsAffected });
+        pendingWrites.delete(parsed.writeId);
+      }
+      return;
+    }
+    if (isWriteErrorMessage(parsed)) {
+      options.onWriteError?.(parsed);
+      const error = new Error(parsed.message);
+      if (parsed.writeId) {
+        const pendingWrite = pendingWrites.get(parsed.writeId);
+        if (pendingWrite) {
+          pendingWrite.reject(error);
+          pendingWrites.delete(parsed.writeId);
+        }
+      } else {
+        rejectPendingTransaction(parsed.transactionId, error);
+        resetTransaction();
+      }
+    }
+  };
+  const openSocket = () => {
+    if (socket && (socket.readyState === WebSocketImpl.OPEN || socket.readyState === WebSocketImpl.CONNECTING)) {
+      return;
+    }
+    setConnectionState(intentionalDisconnect ? "disconnected" : connectionState === "disconnected" ? "connecting" : "reconnecting");
+    socket = new WebSocketImpl(wsUrl);
+    socket.addEventListener("open", () => {
+      reconnectScheduler.reset();
+      lastConnectionError = null;
+      setConnectionState("connected");
+      options.onConnect?.();
+      sendRegister();
+    });
+    socket.addEventListener("message", (event) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(String(event.data));
+      } catch {
+        return;
+      }
+      handleServerMessage(parsed);
+    });
+    socket.addEventListener("close", () => {
+      socket = null;
+      options.onDisconnect?.();
+      rejectAllPending(new Error("Disconnected from DevTools hub"));
+      if (intentionalDisconnect) {
+        setConnectionState("disconnected");
+        return;
+      }
+      setConnectionState("reconnecting");
+      reconnectScheduler.schedule();
+    });
+    socket.addEventListener("error", () => {
+      const error = new Error(`WebSocket connection failed: ${wsUrl}`);
+      lastConnectionError = error.message;
+      options.onError?.(error);
+    });
+  };
+  const connect = () => {
+    intentionalDisconnect = false;
+    openSocket();
+  };
+  const disconnect = () => {
+    intentionalDisconnect = true;
+    reconnectScheduler.cancel();
+    socket?.close();
+    socket = null;
+    rejectAllPending(new Error("Disconnected"));
+    setConnectionState("disconnected");
+  };
+  const setServerUrl = (url) => {
+    wsUrl = url;
+    const wasConnected = connectionState === "connected" || connectionState === "connecting" || connectionState === "reconnecting";
+    disconnect();
+    intentionalDisconnect = false;
+    if (wasConnected) {
+      connect();
+    }
+  };
+  const requestRefresh = (targetDeviceId) => {
+    send({
+      type: MessageType.REFRESH_REQUEST,
+      deviceId: targetDeviceId,
+      refreshType: "snapshot"
+    });
+  };
+  const requestExportSnapshot = () => {
+    send({
+      type: MessageType.EXPORT_SNAPSHOT_REQUEST,
+      refreshType: "snapshot"
+    });
+  };
+  const sendTransactionAck = (message) => {
+    send({
+      type: MessageType.TRANSACTION_ACK,
+      ...message
+    });
+  };
+  const sendWriteAck = (message) => {
+    send({
+      type: MessageType.WRITE_ACK,
+      ...message
+    });
+  };
+  const waitForTransaction = (transactionId, action) => {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingTransaction.delete(transactionId);
+        reject(new Error(`Transaction ${action} timed out`));
+      }, WRITE_TIMEOUT_MS);
+      pendingTransaction.set(transactionId, {
+        action,
+        resolve: () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    });
+  };
+  const beginTransaction = async (targetDeviceId) => {
+    if (role !== DevToolsRole.BROWSER) {
+      throw new Error("beginTransaction is only available for browser clients");
+    }
+    if (transactionState !== "idle") {
+      throw new Error("A transaction is already active");
+    }
+    const transactionId = generateTransactionId();
+    setTransactionState("opening");
+    activeTransactionId = transactionId;
+    activeDeviceId = targetDeviceId;
+    const promise = waitForTransaction(transactionId, "begin");
+    send({
+      type: MessageType.BEGIN_TRANSACTION_REQUEST,
+      transactionId,
+      deviceId: targetDeviceId
+    });
+    await promise;
+  };
+  const commitTransaction = async () => {
+    if (role !== DevToolsRole.BROWSER) {
+      throw new Error("commitTransaction is only available for browser clients");
+    }
+    if (!activeTransactionId || !activeDeviceId || transactionState !== "open") {
+      throw new Error("No open transaction");
+    }
+    const transactionId = activeTransactionId;
+    const deviceIdForCommit = activeDeviceId;
+    setTransactionState("committing");
+    const promise = waitForTransaction(transactionId, "commit");
+    send({
+      type: MessageType.COMMIT_TRANSACTION_REQUEST,
+      transactionId,
+      deviceId: deviceIdForCommit
+    });
+    await promise;
+  };
+  const rollbackTransaction = async () => {
+    if (role !== DevToolsRole.BROWSER) {
+      throw new Error("rollbackTransaction is only available for browser clients");
+    }
+    if (!activeTransactionId || !activeDeviceId) {
+      throw new Error("No active transaction");
+    }
+    const transactionId = activeTransactionId;
+    const deviceIdForRollback = activeDeviceId;
+    setTransactionState("rolling_back");
+    const promise = waitForTransaction(transactionId, "rollback");
+    send({
+      type: MessageType.ROLLBACK_TRANSACTION_REQUEST,
+      transactionId,
+      deviceId: deviceIdForRollback
+    });
+    await promise;
+  };
+  const executeWrite = async (operation) => {
+    if (role !== DevToolsRole.BROWSER) {
+      throw new Error("executeWrite is only available for browser clients");
+    }
+    if (!activeTransactionId || !activeDeviceId || transactionState !== "open") {
+      throw new Error("No open transaction");
+    }
+    const writeId = generateWriteId();
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingWrites.delete(writeId);
+        reject(new Error("Write operation timed out"));
+      }, WRITE_TIMEOUT_MS);
+      pendingWrites.set(writeId, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    });
+    send({
+      type: MessageType.WRITE_REQUEST,
+      writeId,
+      transactionId: activeTransactionId,
+      deviceId: activeDeviceId,
+      operation
+    });
+    return promise;
+  };
+  return {
+    connect,
+    disconnect,
+    getConnectionState: () => connectionState,
+    getLastConnectionError: () => lastConnectionError,
+    getDeviceStatus: () => deviceStatus,
+    getDeviceId: () => deviceId,
+    getServerUrl: () => wsUrl,
+    setServerUrl,
+    send,
+    requestRefresh,
+    requestExportSnapshot,
+    sendTransactionAck,
+    sendWriteAck,
+    beginTransaction,
+    commitTransaction,
+    rollbackTransaction,
+    executeWrite,
+    getTransactionState: () => transactionState,
+    getActiveTransactionId: () => activeTransactionId
+  };
+}
+
+// src/client/fetchSnapshot.ts
+async function fetchSnapshot(downloadUrl) {
+  let response;
+  try {
+    response = await fetch(downloadUrl);
+  } catch (error) {
+    const networkMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Network error fetching snapshot from ${downloadUrl}. ${networkMessage} If the web UI runs on a different port than the hub, ensure CORS is enabled on the hub HTTP API.`
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch snapshot from ${downloadUrl}: ${response.status} ${response.statusText}`
+    );
+  }
+  return response.arrayBuffer();
+}
+
+// src/client/resolveDeviceDatabaseUrl.ts
+function resolveApiBase(serverUrl, options) {
+  if (options?.useSameOriginApi && typeof window !== "undefined") {
+    return window.location.origin;
+  }
+  if (serverUrl.startsWith("ws://") || serverUrl.startsWith("wss://")) {
+    return wsUrlToHttpUrl(serverUrl);
+  }
+  return serverUrl.replace(/\/$/, "");
+}
+function resolveDeviceExportDatabaseUrl(serverUrl, deviceId, options) {
+  const base = resolveApiBase(serverUrl, options);
+  return `${base}${PROJECT_DEVICE_EXPORTS_API_PATH}/${encodeURIComponent(deviceId)}/database`;
+}
+function resolveDeviceExportDatabaseMetaUrl(serverUrl, deviceId, options) {
+  const base = resolveApiBase(serverUrl, options);
+  return `${base}${PROJECT_DEVICE_EXPORTS_API_PATH}/${encodeURIComponent(deviceId)}/database/meta`;
+}
+function resolveDeviceExportsUrl(serverUrl, options) {
+  const base = resolveApiBase(serverUrl, options);
+  return `${base}${PROJECT_DEVICE_EXPORTS_API_PATH}`;
+}
+
+// src/client/deviceDatabase.ts
+async function fetchJson(url, errorLabel) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    const networkMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Network error fetching ${errorLabel} from ${url}. ${networkMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${errorLabel} from ${url}: ${response.status} ${response.statusText}`);
+  }
+  return await response.json();
+}
+async function fetchDeviceExportMeta(serverUrl, deviceId, options) {
+  const url = resolveDeviceExportDatabaseMetaUrl(serverUrl, deviceId, options);
+  return fetchJson(url, "device export metadata");
+}
+async function fetchDeviceExportDatabase(serverUrl, deviceId, options) {
+  const url = resolveDeviceExportDatabaseUrl(serverUrl, deviceId, options);
+  return fetchSnapshot(url);
+}
+async function fetchDeviceExports(serverUrl, options) {
+  const url = resolveDeviceExportsUrl(serverUrl, options);
+  const payload = await fetchJson(url, "device exports");
+  return payload.devices ?? [];
+}
+
+// src/client/resolveProjectDatabaseUrl.ts
+function resolveApiBase2(serverUrl, options) {
+  if (options?.useSameOriginApi && typeof window !== "undefined") {
+    return window.location.origin;
+  }
+  if (serverUrl.startsWith("ws://") || serverUrl.startsWith("wss://")) {
+    return wsUrlToHttpUrl(serverUrl);
+  }
+  return serverUrl.replace(/\/$/, "");
+}
+function resolveProjectDatabaseUrl(serverUrl, options) {
+  return `${resolveApiBase2(serverUrl, options)}${PROJECT_DATABASE_API_PATH}`;
+}
+function resolveProjectDatabaseMetaUrl(serverUrl, options) {
+  return `${resolveApiBase2(serverUrl, options)}${PROJECT_DATABASE_META_API_PATH}`;
+}
+function resolveProjectDatabasesUrl(serverUrl, options) {
+  return `${resolveApiBase2(serverUrl, options)}${PROJECT_DATABASES_API_PATH}`;
+}
+
+// src/client/projectDatabase.ts
+async function fetchProjectDatabaseMeta(serverUrl, options) {
+  const url = resolveProjectDatabaseMetaUrl(serverUrl, options);
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    const networkMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Network error fetching project database metadata from ${url}. ${networkMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch project database metadata from ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  return await response.json();
+}
+async function fetchProjectDatabase(serverUrl, options) {
+  const url = resolveProjectDatabaseUrl(serverUrl, options);
+  return fetchSnapshot(url);
+}
+async function fetchProjectDatabases(serverUrl, options) {
+  const url = resolveProjectDatabasesUrl(serverUrl, options);
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    const networkMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Network error fetching project databases from ${url}. ${networkMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch project databases from ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  const payload = await response.json();
+  return payload.databases ?? [];
+}
+
+// src/client/resolveSnapshotDownloadUrl.ts
+function resolveSnapshotDownloadUrl(hubWsUrl, deviceId, options = {}) {
+  const path = `${DEVICE_SNAPSHOT_API_PATH}/${encodeURIComponent(deviceId)}/snapshot`;
+  if (options.useSameOriginApi) {
+    return path;
+  }
+  return buildDeviceSnapshotUrl(wsUrlToHttpUrl(hubWsUrl), deviceId);
+}
+
+// src/client/formatSyncError.ts
+function formatSyncErrorMessage(code, message) {
+  return formatRefreshErrorMessage(code, message);
+}
+function formatRefreshErrorMessage(code, message) {
+  switch (code) {
+    case "DEVICE_OFFLINE":
+      return "Selected device disconnected. Reconnect the mobile app and try again.";
+    case "REFRESH_IN_PROGRESS":
+      return "A refresh is already in progress for this device.";
+    case "EXPORT_FAILED":
+      return `Device failed to export or upload snapshot: ${message}`;
+    case "UPLOAD_FAILED":
+      return `Snapshot upload failed on the hub: ${message}`;
+    case "TIMEOUT":
+      return "Timed out waiting for the device to upload a snapshot.";
+    case "SNAPSHOT_NOT_FOUND":
+      return "Snapshot expired or was not found. Click Refresh again.";
+    case "INVALID_REQUEST":
+      return `Invalid refresh request: ${message}`;
+    default:
+      return message;
+  }
+}
+
+// src/utils/deviceLabel.ts
+function shortenDeviceId(deviceId, visibleChars = 4) {
+  if (deviceId.length <= visibleChars * 2 + 1) {
+    return deviceId;
+  }
+  return `${deviceId.slice(0, visibleChars)}\u2026${deviceId.slice(-visibleChars)}`;
+}
+function resolveDeviceDisplayName(deviceId, deviceStatus, fallback) {
+  const mobile = deviceStatus?.mobiles.find((device) => device.deviceId === deviceId);
+  if (mobile?.metadata?.appName) {
+    return mobile.metadata.appName;
+  }
+  if (fallback?.databaseName) {
+    return fallback.databaseName;
+  }
+  if (fallback?.label) {
+    return fallback.label;
+  }
+  return "Device export";
+}
+function resolveDeviceLabel(deviceId, deviceStatus, fallback) {
+  return {
+    deviceId,
+    deviceName: resolveDeviceDisplayName(deviceId, deviceStatus, fallback)
+  };
+}
+function formatSnapshotReceivedMessage(deviceLabel, databaseName) {
+  return `${deviceLabel.deviceName} (${shortenDeviceId(deviceLabel.deviceId)}) \xB7 ${databaseName}`;
+}
+function buildSnapshotLoadedToast(initiator, deviceId, databaseName, deviceStatus, fallback) {
+  const deviceLabel = resolveDeviceLabel(deviceId, deviceStatus, fallback);
+  return {
+    title: initiator === "mobile" ? "New database received" : "Database refreshed",
+    message: formatSnapshotReceivedMessage(deviceLabel, databaseName)
+  };
+}
+
+// src/utils/resolvePreferredDeviceId.ts
+function findMobileByBundleId(mobiles, bundleId) {
+  if (!bundleId) {
+    return void 0;
+  }
+  return mobiles.find((mobile) => mobile.metadata?.bundleId === bundleId);
+}
+function resolvePreferredDeviceId(input) {
+  const connectedIds = new Set(input.mobiles.map((device) => device.deviceId));
+  const exportById = new Map(input.exports.map((entry) => [entry.deviceId, entry]));
+  if (input.selectedDeviceId) {
+    if (connectedIds.has(input.selectedDeviceId)) {
+      return input.selectedDeviceId;
+    }
+    const selectedExport = exportById.get(input.selectedDeviceId);
+    if (selectedExport) {
+      const bundleMatch = findMobileByBundleId(input.mobiles, selectedExport.bundleId);
+      if (bundleMatch) {
+        return bundleMatch.deviceId;
+      }
+      if (input.mobiles.length === 1) {
+        return input.mobiles[0].deviceId;
+      }
+      return input.selectedDeviceId;
+    }
+  }
+  return input.mobiles[0]?.deviceId ?? input.exports[0]?.deviceId ?? null;
+}
+function resolveLiveSwitchTarget(input) {
+  if (!input.selectedDeviceId || input.mobiles.length === 0) {
+    return null;
+  }
+  if (input.mobiles.some((mobile) => mobile.deviceId === input.selectedDeviceId)) {
+    return null;
+  }
+  const selectedExport = input.exports.find((entry) => entry.deviceId === input.selectedDeviceId);
+  const bundleMatch = findMobileByBundleId(input.mobiles, selectedExport?.bundleId);
+  if (bundleMatch) {
+    return bundleMatch.deviceId;
+  }
+  return input.mobiles[0]?.deviceId ?? null;
+}
+
+// src/types/snapshot.ts
+var SNAPSHOT_KIND_HEADER = "x-database-kind";
+var SNAPSHOT_MIME_HEADER = "x-snapshot-mime-type";
+var SNAPSHOT_NAME_HEADER = "x-database-name";
+
+// src/client/snapshotUpload.ts
+function createSnapshotUploadBody(bytes) {
+  return bytes;
+}
+function resolveSnapshotUploadUrl(uploadUrl, hubWsUrl) {
+  const hubHttpBase = wsUrlToHttpUrl(hubWsUrl);
+  const target = new URL(uploadUrl);
+  const hub = new URL(hubHttpBase.endsWith("/") ? hubHttpBase : `${hubHttpBase}/`);
+  target.protocol = hub.protocol;
+  target.hostname = hub.hostname;
+  target.port = hub.port;
+  return target.toString();
+}
+async function uploadSnapshot(uploadUrl, bytes, options) {
+  const headers = {
+    "Content-Type": "application/octet-stream",
+    [options.kindHeader]: options.kind,
+    [options.mimeHeader]: options.mimeType
+  };
+  if (options.databaseName && options.nameHeader) {
+    headers[options.nameHeader] = options.databaseName;
+  }
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers,
+    body: createSnapshotUploadBody(bytes)
+  });
+  if (!response.ok) {
+    throw new Error(`Upload failed with status ${response.status}`);
+  }
+}
+
+// src/client/handleDeviceSnapshot.ts
+async function handleDeviceSnapshotUpload(database, message, options = {}) {
+  if (options.deviceId && message.deviceId !== options.deviceId) {
+    return;
+  }
+  if (!database) {
+    throw new Error("No database adapter configured");
+  }
+  if (!options.hubServerUrl) {
+    throw new Error("hubServerUrl is required to upload a device snapshot");
+  }
+  const snapshot = await database.exportSnapshot();
+  const hubHttp = wsUrlToHttpUrl(options.hubServerUrl);
+  const uploadUrl = buildDeviceSnapshotUrl(hubHttp, message.deviceId);
+  await uploadSnapshot(uploadUrl, snapshot.bytes, {
+    kind: snapshot.kind,
+    mimeType: snapshot.mimeType,
+    kindHeader: SNAPSHOT_KIND_HEADER,
+    mimeHeader: SNAPSHOT_MIME_HEADER,
+    databaseName: database.name,
+    nameHeader: SNAPSHOT_NAME_HEADER
+  });
+}
+
+exports.buildSnapshotLoadedToast = buildSnapshotLoadedToast;
+exports.createDevToolsClient = createDevToolsClient;
+exports.createSnapshotUploadBody = createSnapshotUploadBody;
+exports.fetchDeviceExportDatabase = fetchDeviceExportDatabase;
+exports.fetchDeviceExportMeta = fetchDeviceExportMeta;
+exports.fetchDeviceExports = fetchDeviceExports;
+exports.fetchProjectDatabase = fetchProjectDatabase;
+exports.fetchProjectDatabaseMeta = fetchProjectDatabaseMeta;
+exports.fetchProjectDatabases = fetchProjectDatabases;
+exports.fetchSnapshot = fetchSnapshot;
+exports.formatRefreshErrorMessage = formatRefreshErrorMessage;
+exports.formatSnapshotReceivedMessage = formatSnapshotReceivedMessage;
+exports.formatSyncErrorMessage = formatSyncErrorMessage;
+exports.handleDeviceSnapshotUpload = handleDeviceSnapshotUpload;
+exports.resolveDeviceDisplayName = resolveDeviceDisplayName;
+exports.resolveDeviceExportDatabaseMetaUrl = resolveDeviceExportDatabaseMetaUrl;
+exports.resolveDeviceExportDatabaseUrl = resolveDeviceExportDatabaseUrl;
+exports.resolveDeviceExportsUrl = resolveDeviceExportsUrl;
+exports.resolveDeviceLabel = resolveDeviceLabel;
+exports.resolveLiveSwitchTarget = resolveLiveSwitchTarget;
+exports.resolvePreferredDeviceId = resolvePreferredDeviceId;
+exports.resolveProjectDatabaseMetaUrl = resolveProjectDatabaseMetaUrl;
+exports.resolveProjectDatabaseUrl = resolveProjectDatabaseUrl;
+exports.resolveProjectDatabasesUrl = resolveProjectDatabasesUrl;
+exports.resolveSnapshotDownloadUrl = resolveSnapshotDownloadUrl;
+exports.resolveSnapshotUploadUrl = resolveSnapshotUploadUrl;
+exports.shortenDeviceId = shortenDeviceId;
+exports.uploadSnapshot = uploadSnapshot;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map