tetherdb 0.1.0

package/dist/client/index.cjs

@@ -0,0 +1,1742 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  AuthStatus: () => AuthStatus,
+  DataMode: () => DataMode,
+  OperationType: () => OperationType,
+  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  SyncStatus: () => SyncStatus,
+  Table: () => Table,
+  TetherClient: () => TetherClient,
+  TetherClientError: () => TetherClientError,
+  TetherClientErrorCode: () => TetherClientErrorCode
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/shared/types.ts
+var OperationType = /* @__PURE__ */ ((OperationType2) => {
+  OperationType2["Put"] = "put";
+  OperationType2["Delete"] = "delete";
+  return OperationType2;
+})(OperationType || {});
+var PROTOCOL_VERSION = 1;
+
+// src/client/errors.ts
+var TetherClientErrorCode = /* @__PURE__ */ ((TetherClientErrorCode2) => {
+  TetherClientErrorCode2[TetherClientErrorCode2["MissingConfiguration"] = 0] = "MissingConfiguration";
+  TetherClientErrorCode2[TetherClientErrorCode2["InvalidInput"] = 1] = "InvalidInput";
+  TetherClientErrorCode2[TetherClientErrorCode2["FetchUnavailable"] = 2] = "FetchUnavailable";
+  TetherClientErrorCode2[TetherClientErrorCode2["NetworkError"] = 3] = "NetworkError";
+  TetherClientErrorCode2[TetherClientErrorCode2["MissingCredentials"] = 4] = "MissingCredentials";
+  TetherClientErrorCode2[TetherClientErrorCode2["RegistrationFailed"] = 5] = "RegistrationFailed";
+  TetherClientErrorCode2[TetherClientErrorCode2["AuthenticationFailed"] = 6] = "AuthenticationFailed";
+  TetherClientErrorCode2[TetherClientErrorCode2["StorageError"] = 7] = "StorageError";
+  TetherClientErrorCode2[TetherClientErrorCode2["SyncError"] = 8] = "SyncError";
+  return TetherClientErrorCode2;
+})(TetherClientErrorCode || {});
+var TetherClientError = class extends Error {
+  /** Error category code identifying the broad error type. */
+  code;
+  /**
+   * Initializes a new `TetherClientError`.
+   *
+   * @param code - The error category code.
+   * @param message - User-safe error description message.
+   */
+  constructor(code, message) {
+    super(message ?? getDefaultClientErrorMessage(code));
+    this.name = "TetherClientError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function getDefaultClientErrorMessage(code) {
+  switch (code) {
+    case 0 /* MissingConfiguration */:
+      return "Missing required configuration option";
+    case 1 /* InvalidInput */:
+      return "Invalid input parameter provided";
+    case 2 /* FetchUnavailable */:
+      return "No fetch implementation available";
+    case 3 /* NetworkError */:
+      return "Network communication error";
+    case 4 /* MissingCredentials */:
+      return "Missing authentication credentials";
+    case 5 /* RegistrationFailed */:
+      return "Registration failed";
+    case 6 /* AuthenticationFailed */:
+      return "Authentication failed";
+    case 7 /* StorageError */:
+      return "Local storage operation failed";
+    case 8 /* SyncError */:
+      return "Synchronization error";
+  }
+}
+
+// src/client/shared/event.ts
+var EventRegistry = class {
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Registers a callback listener to be notified when events are published.
+   *
+   * @param listener - Callback function receiving event payloads.
+   * @returns An unregister function that removes the listener.
+   */
+  register(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Dispatches an event payload to all registered listeners in registration order.
+   * Catches and logs listener exceptions to prevent aborting dispatch to remaining listeners.
+   *
+   * @param args - The event data payload (optional if payload type is void).
+   */
+  publish(...args) {
+    const event = args[0];
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error("Unhandled error:", err);
+      }
+    }
+  }
+};
+
+// src/client/auth.ts
+var DataMode = /* @__PURE__ */ ((DataMode2) => {
+  DataMode2[DataMode2["Remote"] = 0] = "Remote";
+  DataMode2[DataMode2["Local"] = 1] = "Local";
+  DataMode2[DataMode2["Merge"] = 2] = "Merge";
+  DataMode2[DataMode2["Clear"] = 3] = "Clear";
+  return DataMode2;
+})(DataMode || {});
+var AuthStatus = /* @__PURE__ */ ((AuthStatus2) => {
+  AuthStatus2[AuthStatus2["SignedOut"] = 0] = "SignedOut";
+  AuthStatus2[AuthStatus2["SigningIn"] = 1] = "SigningIn";
+  AuthStatus2[AuthStatus2["SignedIn"] = 2] = "SignedIn";
+  AuthStatus2[AuthStatus2["Error"] = 3] = "Error";
+  return AuthStatus2;
+})(AuthStatus || {});
+var Auth = class {
+  /** Base URL for remote authentication REST API endpoints. */
+  baseUrl;
+  /** Reactive event registry triggered whenever the authentication status changes. */
+  onStatusChange = new EventRegistry();
+  storage;
+  fetchFn;
+  currentAuthStatus = 0 /* SignedOut */;
+  currentUsername;
+  currentUserId;
+  currentToken;
+  autoRestorePromise;
+  constructor(dependencies) {
+    this.baseUrl = dependencies.baseUrl;
+    this.storage = dependencies.storage;
+    const rawFetch = dependencies.fetchFn ?? (typeof globalThis !== "undefined" && globalThis.fetch ? globalThis.fetch : typeof fetch !== "undefined" ? fetch : void 0);
+    if (!rawFetch) {
+      throw new TetherClientError(
+        2 /* FetchUnavailable */,
+        "No fetch implementation available"
+      );
+    }
+    this.fetchFn = rawFetch.bind(globalThis);
+    this.autoRestorePromise = this.restoreSession();
+  }
+  /**
+   * Current authentication lifecycle status.
+   */
+  get status() {
+    return this.currentAuthStatus;
+  }
+  /**
+   * The authenticated user's username, or `undefined` if signed out.
+   */
+  get username() {
+    return this.currentUsername;
+  }
+  /**
+   * The authenticated user's ID, or `undefined` if signed out.
+   */
+  get userId() {
+    return this.currentUserId;
+  }
+  /**
+   * The active authentication session token, or `undefined` if signed out.
+   */
+  get token() {
+    return this.currentToken;
+  }
+  /**
+   * Restores any remembered session from IndexedDB metadata on startup.
+   */
+  async restoreSession() {
+    try {
+      const session = await this.storage.getMeta("auth");
+      if (session?.token && session.username) {
+        this.currentUserId = session.userId;
+        this.currentUsername = session.username;
+        this.currentToken = session.token;
+        this.setStatus(2 /* SignedIn */);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Registers a new user account, applies local data mode, and notifies listeners.
+   */
+  async register(options) {
+    if (!options?.username || !options?.password) {
+      throw new TetherClientError(
+        4 /* MissingCredentials */,
+        "Registration requires username and password"
+      );
+    }
+    const previousStatus = this.currentAuthStatus;
+    this.setStatus(1 /* SigningIn */);
+    try {
+      const defaultDataMode = previousStatus === 2 /* SignedIn */ ? 3 /* Clear */ : 1 /* Local */;
+      const dataMode = options.dataMode ?? defaultDataMode;
+      const data = await this.sendAuthRequest(
+        "/auth/register",
+        { username: options.username, password: options.password },
+        5 /* RegistrationFailed */,
+        "Registration failed"
+      );
+      this.currentUserId = data.userId;
+      this.currentUsername = data.username;
+      this.currentToken = data.token;
+      await this.applyDataMode(dataMode);
+      await this.updateStoredAuth(options.remember ?? false, data);
+      this.setStatus(2 /* SignedIn */);
+      return true;
+    } catch {
+      this.setStatus(3 /* Error */);
+      return false;
+    }
+  }
+  /**
+   * Logs into an account (or reconnects with remembered credentials), applies data mode, and notifies listeners.
+   */
+  async login(options = {}) {
+    await this.autoRestorePromise;
+    this.setStatus(1 /* SigningIn */);
+    try {
+      let token = this.currentToken;
+      let username = this.currentUsername;
+      let userId = this.currentUserId;
+      if (options.username && options.password) {
+        const data = await this.sendAuthRequest(
+          "/auth/login",
+          { username: options.username, password: options.password },
+          6 /* AuthenticationFailed */,
+          "Authentication failed"
+        );
+        token = data.token;
+        username = data.username;
+        userId = data.userId;
+        await this.updateStoredAuth(options.remember ?? false, data);
+      } else if (!token) {
+        const stored = await this.storage.getMeta("auth");
+        if (stored?.token) {
+          token = stored.token;
+          username = stored.username;
+          userId = stored.userId;
+        }
+      }
+      if (!token) {
+        throw new TetherClientError(
+          4 /* MissingCredentials */,
+          "No login credentials or saved session available"
+        );
+      }
+      this.currentToken = token;
+      this.currentUsername = username;
+      this.currentUserId = userId;
+      await this.applyDataMode(options.dataMode ?? 0 /* Remote */);
+      this.setStatus(2 /* SignedIn */);
+      return true;
+    } catch {
+      this.setStatus(3 /* Error */);
+      return false;
+    }
+  }
+  /**
+   * Logs out of the current session, removes stored credentials, and applies data mode.
+   */
+  async logout(options = {}) {
+    this.currentUserId = void 0;
+    this.currentUsername = void 0;
+    this.currentToken = void 0;
+    await this.storage.deleteMeta("auth");
+    await this.applyDataMode(options.dataMode ?? 3 /* Clear */);
+    this.setStatus(0 /* SignedOut */);
+    return true;
+  }
+  /**
+   * Updates the in-memory and persisted session token when refreshed by the server.
+   *
+   * @param token - The new refreshed session token.
+   */
+  async handleTokenRefresh(token) {
+    this.currentToken = token;
+    const session = await this.storage.getMeta("auth");
+    if (session) {
+      await this.storage.setMeta("auth", {
+        ...session,
+        token
+      });
+    }
+  }
+  /**
+   * Cleans up local session and transitions to SignedOut when authentication fails or expires.
+   *
+   * @param _message - Optional error message from the server.
+   */
+  async handleAuthError(_message) {
+    this.currentUserId = void 0;
+    this.currentUsername = void 0;
+    this.currentToken = void 0;
+    await this.storage.deleteMeta("auth");
+    this.setStatus(0 /* SignedOut */);
+  }
+  // -- Private Helpers ------------------------------------------------------
+  async sendAuthRequest(path, credentials, errorCode, defaultErrorMessage) {
+    const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credentials)
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new TetherClientError(errorCode, data.error ?? defaultErrorMessage);
+    }
+    return data;
+  }
+  async applyDataMode(dataMode) {
+    if (dataMode === 3 /* Clear */ || dataMode === 0 /* Remote */) {
+      await this.storage.clearTables(true);
+      await this.storage.setMeta("lastSyncSeq", 0);
+    }
+  }
+  async updateStoredAuth(remember, auth) {
+    if (remember) {
+      await this.storage.setMeta("auth", {
+        token: auth.token,
+        userId: auth.userId,
+        username: auth.username
+      });
+    } else {
+      await this.storage.deleteMeta("auth");
+    }
+  }
+  setStatus(status) {
+    if (this.currentAuthStatus === status) return;
+    this.currentAuthStatus = status;
+    this.onStatusChange.publish(status);
+  }
+};
+
+// src/shared/path.ts
+function normalizeBasePath(path) {
+  if (path === "" || path === "/") return "";
+  if (path.endsWith("/")) path = path.slice(0, path.length - 1);
+  if (!path.startsWith("/")) path = `/${path}`;
+  return path === "/" ? "" : path;
+}
+
+// src/shared/clock.ts
+function shouldOverwrite(incoming, existing) {
+  if (!existing) return true;
+  if (incoming.timestamp > existing.timestamp) {
+    return true;
+  }
+  if (incoming.timestamp < existing.timestamp) {
+    return false;
+  }
+  const incomingClient = incoming.clientId ?? "";
+  const existingClient = existing.clientId ?? "";
+  return incomingClient >= existingClient;
+}
+
+// src/client/shared/id.ts
+function randomUUID() {
+  if (typeof crypto !== "undefined") {
+    if (typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    if (typeof crypto.getRandomValues === "function") {
+      return "10000000-1000-4000-8000-100000000000".replace(
+        /[018]/g,
+        (char) => {
+          const num = Number(char);
+          const randomByte = crypto.getRandomValues(new Uint8Array(1))[0];
+          return (num ^ randomByte & 15 >> num / 4).toString(16);
+        }
+      );
+    }
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const randomByte = Math.random() * 16 | 0;
+    return (char === "x" ? randomByte : randomByte & 3 | 8).toString(16);
+  });
+}
+
+// src/client/table.ts
+var Table = class {
+  /** Reactive event registry triggered when records in this table are created, updated, or deleted. */
+  onChange = new EventRegistry();
+  tableName;
+  storage;
+  /**
+   * Creates a new Table instance.
+   *
+   * @param tableName - Name of the table.
+   * @param storage - Local storage coordinator.
+   */
+  constructor(tableName, storage) {
+    this.tableName = tableName;
+    this.storage = storage;
+  }
+  /**
+   * The name of the table.
+   */
+  get name() {
+    return this.tableName;
+  }
+  /**
+   * The client identifier for local mutations.
+   */
+  get clientId() {
+    return this.storage.clientId;
+  }
+  /**
+   * Retrieves a single record by its identifier.
+   *
+   * @param id - The unique record identifier.
+   * @returns A promise resolving to the record data, or `undefined` if not found.
+   */
+  async get(id) {
+    const record = await this.storage.getRecord(this.tableName, id);
+    return record?.data;
+  }
+  /**
+   * Retrieves records stored in this table, optionally filtered by a list of IDs.
+   *
+   * @param ids - Optional list of record identifiers to fetch. If omitted, retrieves all records.
+   * @returns A promise resolving to an array of record data objects.
+   */
+  async getAll(ids) {
+    if (ids !== void 0) {
+      if (ids.length === 0) return [];
+      const map = await this.storage.getRecords(this.tableName, ids);
+      const results = [];
+      for (const id of ids) {
+        const rec = map.get(id);
+        if (rec) {
+          results.push(rec.data);
+        }
+      }
+      return results;
+    }
+    const records = await this.storage.getAllRecords(this.tableName);
+    return records.map((r) => r.data);
+  }
+  /**
+   * Deletes all records in this table and queues tombstones for synchronization.
+   *
+   * @returns A promise resolving to the number of deleted records.
+   */
+  async clear() {
+    const records = await this.storage.getAllRecords(this.tableName);
+    const ids = records.map((r) => r.id);
+    return this.deleteAll(ids);
+  }
+  /**
+   * Retrieves a single stored record including metadata (version, timestamp).
+   *
+   * @param id - The unique record identifier.
+   * @returns A promise resolving to the stored record with metadata, or `undefined` if not found.
+   */
+  async getWithMetadata(id) {
+    return this.storage.getRecord(this.tableName, id);
+  }
+  /**
+   * Retrieves all records with storage metadata (version, timestamp).
+   *
+   * @returns A promise resolving to an array of stored records with metadata.
+   */
+  async getAllWithMetadata() {
+    return this.storage.getAllRecords(this.tableName);
+  }
+  /**
+   * Stores or updates a record locally and triggers synchronization.
+   *
+   * @param id - The unique record identifier.
+   * @param data - The data payload to save.
+   * @returns A promise resolving to the saved data.
+   */
+  async put(id, data) {
+    await this.putAll([{ id, data }]);
+    return data;
+  }
+  /**
+   * Atomically stores or updates multiple records locally in a single batch,
+   * queues outbox mutations, notifies subscribers with an event list, and triggers synchronization.
+   *
+   * @param entries - Array of record entries to save.
+   * @returns A promise resolving to the array of saved data objects.
+   */
+  async putAll(entries) {
+    if (entries.length === 0) return [];
+    const ids = entries.map((e) => e.id);
+    const existingMap = await this.storage.getRecords(this.tableName, ids);
+    const now = Date.now();
+    const mutations = [];
+    const events = [];
+    const savedData = [];
+    for (const entry of entries) {
+      const { mutation, event } = this.createMutationItem(
+        entry.id,
+        "put" /* Put */,
+        existingMap.get(entry.id),
+        now,
+        entry.data
+      );
+      mutations.push(mutation);
+      events.push(event);
+      savedData.push(entry.data);
+    }
+    await this.storage.applyLocalChanges(this.tableName, mutations);
+    this.onChange.publish(events);
+    return savedData;
+  }
+  /**
+   * Deletes a record locally by creating a tombstone and triggers synchronization.
+   *
+   * @param id - The unique record identifier to delete.
+   * @returns A promise resolving to `true` if the record existed and was deleted; otherwise `false`.
+   */
+  async delete(id) {
+    const deletedCount = await this.deleteAll([id]);
+    return deletedCount > 0;
+  }
+  /**
+   * Atomically deletes multiple records locally in a single batch,
+   * creates tombstones, notifies subscribers with an event list, and triggers synchronization.
+   *
+   * @param ids - Array of record identifiers to delete.
+   * @returns A promise resolving to the count of records that existed and were deleted.
+   */
+  async deleteAll(ids) {
+    if (ids.length === 0) return 0;
+    const existingMap = await this.storage.getRecords(this.tableName, ids);
+    const now = Date.now();
+    const mutations = [];
+    const events = [];
+    for (const id of ids) {
+      const existing = existingMap.get(id);
+      if (!existing || existing.deleted) continue;
+      const { mutation, event } = this.createMutationItem(
+        id,
+        "delete" /* Delete */,
+        existing,
+        now
+      );
+      mutations.push(mutation);
+      events.push(event);
+    }
+    if (mutations.length > 0) {
+      await this.storage.applyLocalChanges(this.tableName, mutations);
+      this.onChange.publish(events);
+    }
+    return mutations.length;
+  }
+  /**
+   * Subscribes to the complete list of records in this table.
+   * Immediately invokes the listener with the current records, and re-invokes it
+   * whenever any local or remote mutations occur on this table.
+   *
+   * @param listener - Callback receiving the latest array of records.
+   * @returns An unsubscribe function.
+   */
+  subscribeAll(listener) {
+    let isActive = true;
+    let currentVersion = 0;
+    const fetchAndNotify = () => {
+      const version = ++currentVersion;
+      this.getAll().then((items) => {
+        if (isActive && version === currentVersion) {
+          listener(items);
+        }
+      }).catch(() => {
+      });
+    };
+    fetchAndNotify();
+    const unsubscribe = this.onChange.register(() => {
+      fetchAndNotify();
+    });
+    return () => {
+      isActive = false;
+      unsubscribe();
+    };
+  }
+  /**
+   * Notifies registered subscribers of remote change events.
+   *
+   * @param events - The list of remote change events.
+   */
+  notifyRemoteChanges(events) {
+    if (events.length === 0) return;
+    this.onChange.publish(events);
+  }
+  // -- Private Helpers ------------------------------------------------------
+  createMutationItem(id, op, existing, now, data) {
+    const version = (existing?.version ?? 0) + 1;
+    const timestamp = Math.max(now, (existing?.timestamp ?? 0) + 1);
+    const change = {
+      table: this.tableName,
+      id,
+      op,
+      data,
+      timestamp,
+      clientId: this.clientId,
+      version
+    };
+    return {
+      mutation: { id, op, data, change },
+      event: { op, id, data, isRemote: false }
+    };
+  }
+};
+
+// src/client/storage.ts
+var Storage = class {
+  /** Name of the local IndexedDB database. */
+  name;
+  /** Unique client instance identifier used for monotonic logical clock tie-breaking. */
+  clientId;
+  /** Reactive event registry triggered when mutations are committed to the local database. */
+  onLocalChange = new EventRegistry();
+  databasePromise = null;
+  schemaMutex = Promise.resolve();
+  tables = /* @__PURE__ */ new Map();
+  /**
+   * Creates a new Storage instance.
+   *
+   * @param name - Name of the IndexedDB database.
+   */
+  constructor(name) {
+    this.name = name;
+    this.clientId = randomUUID();
+  }
+  /**
+   * Obtains a typed table reference for reading, mutating, and subscribing to records.
+   * Tables are created dynamically on-demand if not already declared.
+   *
+   * @typeParam T - Data payload model type for records in this table.
+   * @param name - The table name.
+   * @returns A typed `Table<T>` instance.
+   */
+  table(name) {
+    let table = this.tables.get(name);
+    if (!table) {
+      table = new Table(name, this);
+      this.tables.set(name, table);
+    }
+    return table;
+  }
+  /**
+   * Opens or returns the active IndexedDB connection, executing schema upgrades when needed.
+   *
+   * @returns A promise resolving to the open IDBDatabase instance.
+   */
+  async getDatabase() {
+    if (this.databasePromise) return this.databasePromise;
+    this.databasePromise = this.openDatabase().catch((err) => {
+      this.databasePromise = null;
+      throw err;
+    });
+    return this.databasePromise;
+  }
+  /**
+   * Dynamically ensures that multiple application tables exist in IndexedDB.
+   *
+   * @param tableNames - Array of table names to ensure.
+   */
+  async ensureTables(tableNames) {
+    this.schemaMutex = this.schemaMutex.then(async () => {
+      const database = await this.getDatabase();
+      const missing = tableNames.filter(
+        (s) => !database.objectStoreNames.contains(s)
+      );
+      if (missing.length === 0) return;
+      const nextVersion = database.version + 1;
+      this.databasePromise = this.upgradeDatabase(
+        database,
+        nextVersion,
+        missing
+      ).catch((err) => {
+        this.databasePromise = null;
+        throw err;
+      });
+      await this.databasePromise;
+    });
+    return this.schemaMutex;
+  }
+  /**
+   * Ensures a single application table exists in IndexedDB.
+   *
+   * @param tableName - Name of the table to ensure.
+   */
+  async ensureTable(tableName) {
+    await this.ensureTables([tableName]);
+  }
+  /**
+   * Retrieves a metadata value from the internal metadata store.
+   *
+   * @typeParam T - Expected value type.
+   * @param key - The metadata key identifier.
+   * @returns The stored metadata value, or `undefined` if not set.
+   */
+  async getMeta(key) {
+    return this.withDatabase(async (database) => {
+      const entry = await promisifyRequest(
+        database.transaction(META_STORE, "readonly").objectStore(META_STORE).get(key)
+      );
+      return entry?.value;
+    });
+  }
+  /**
+   * Sets a metadata value in the internal metadata store.
+   *
+   * @param key - The metadata key identifier.
+   * @param value - The value to store.
+   */
+  async setMeta(key, value) {
+    return this.withDatabase(async (database) => {
+      await promisifyRequest(
+        database.transaction(META_STORE, "readwrite").objectStore(META_STORE).put({ key, value })
+      );
+    });
+  }
+  /**
+   * Deletes a metadata entry from the internal metadata store.
+   *
+   * @param key - The metadata key identifier.
+   */
+  async deleteMeta(key) {
+    return this.withDatabase(async (database) => {
+      await promisifyRequest(
+        database.transaction(META_STORE, "readwrite").objectStore(META_STORE).delete(key)
+      );
+    });
+  }
+  /**
+   * Retrieves a single stored record by table and identifier.
+   *
+   * @typeParam T - Expected payload type.
+   * @param tableName - Table name.
+   * @param id - Record identifier.
+   * @returns Stored record or `undefined` if not found.
+   */
+  async getRecord(tableName, id) {
+    await this.ensureTable(tableName);
+    return this.withDatabase(async (database) => {
+      return promisifyRequest(
+        database.transaction(tableName, "readonly").objectStore(tableName).get(id)
+      );
+    });
+  }
+  /**
+   * Retrieves multiple stored records by their identifiers in a single readonly transaction.
+   *
+   * @typeParam T - Expected payload type.
+   * @param tableName - Table name.
+   * @param ids - Array of record identifiers.
+   * @returns Map of found stored records keyed by id.
+   */
+  async getRecords(tableName, ids) {
+    if (ids.length === 0) return /* @__PURE__ */ new Map();
+    await this.ensureTable(tableName);
+    return this.withDatabase(async (database) => {
+      const tx = database.transaction(tableName, "readonly");
+      const store = tx.objectStore(tableName);
+      const results = /* @__PURE__ */ new Map();
+      for (const id of ids) {
+        const request = store.get(id);
+        request.onsuccess = () => {
+          if (request.result) {
+            results.set(id, request.result);
+          }
+        };
+      }
+      await promisifyTransaction(tx);
+      return results;
+    });
+  }
+  /**
+   * Retrieves stored records from a specified table.
+   *
+   * @typeParam T - Data payload type.
+   * @param tableName - Table name.
+   * @returns Array of stored records with metadata.
+   */
+  async getAllRecords(tableName) {
+    await this.ensureTable(tableName);
+    return this.withDatabase(async (database) => {
+      const records = await promisifyRequest(
+        database.transaction(tableName, "readonly").objectStore(tableName).getAll()
+      );
+      return records ?? [];
+    });
+  }
+  /**
+   * Atomically persists a batch of local mutations alongside outbox changelog entries
+   * within a single IndexedDB transaction.
+   *
+   * @typeParam T - Data payload type.
+   * @param tableName - Target table name.
+   * @param mutations - List of mutations to apply and queue into outbox.
+   * @returns Array of newly stored records with updated metadata.
+   */
+  async applyLocalChanges(tableName, mutations) {
+    if (mutations.length === 0) return [];
+    await this.ensureTable(tableName);
+    return this.withDatabase(async (database) => {
+      const tx = database.transaction([tableName, OUTBOX_STORE], "readwrite");
+      const dataStore = tx.objectStore(tableName);
+      const outboxStore = tx.objectStore(OUTBOX_STORE);
+      const records = [];
+      const now = Date.now();
+      for (const item of mutations) {
+        const isDelete = item.op === "delete" /* Delete */;
+        const record = {
+          id: item.id,
+          data: item.data ?? null,
+          timestamp: item.change.timestamp,
+          version: item.change.version ?? 1,
+          clientId: item.change.clientId,
+          deleted: isDelete
+        };
+        if (isDelete) {
+          dataStore.delete(item.id);
+        } else {
+          dataStore.put(record);
+        }
+        outboxStore.add({
+          change: item.change,
+          createdAt: now
+        });
+        records.push(record);
+      }
+      await promisifyTransaction(tx);
+      this.onLocalChange.publish();
+      return records;
+    });
+  }
+  /**
+   * Retrieves all currently queued outbox entries awaiting sync.
+   *
+   * @param limit - Optional maximum number of entries to retrieve.
+   * @returns Array of pending outbox queue items.
+   */
+  async getPendingOutbox(limit) {
+    return this.withDatabase(async (database) => {
+      const store = database.transaction(OUTBOX_STORE, "readonly").objectStore(OUTBOX_STORE);
+      const req = limit ? store.getAll(null, limit) : store.getAll();
+      const results = await promisifyRequest(req);
+      return results ?? [];
+    });
+  }
+  /**
+   * Clears acknowledged changes from the outbox by their local database IDs.
+   *
+   * @param localIds - Array of auto-incremented local outbox IDs to remove.
+   */
+  async removeOutboxEntries(localIds) {
+    if (localIds.length === 0) return;
+    return this.withDatabase(async (database) => {
+      const tx = database.transaction(OUTBOX_STORE, "readwrite");
+      const store = tx.objectStore(OUTBOX_STORE);
+      for (const id of localIds) {
+        store.delete(id);
+      }
+      await promisifyTransaction(tx);
+    });
+  }
+  /**
+   * Applies an entire snapshot batch across tables atomically in a single transaction.
+   *
+   * @param snapshot - Array of record items to persist.
+   * @param seq - Global sequence number corresponding to this snapshot.
+   */
+  async applySnapshotBatch(snapshot, seq) {
+    await this.applyBatchRecords(snapshot, seq);
+  }
+  /**
+   * Applies a batch of incoming remote delta mutations atomically across tables
+   * in a single IndexedDB transaction without generating local outbox echo entries.
+   *
+   * @param changes - Array of change records received from the server.
+   * @param seq - New sequence number to record upon transaction commit.
+   */
+  async applyRemoteChangesBatch(changes, seq) {
+    if (changes.length === 0) {
+      await this.setMeta("lastSyncSeq", seq);
+      return;
+    }
+    const records = changes.map((change) => ({
+      table: change.table,
+      id: change.id,
+      data: change.data,
+      timestamp: change.timestamp,
+      version: change.version ?? 1,
+      deleted: change.op === "delete" /* Delete */,
+      clientId: change.clientId
+    }));
+    await this.applyBatchRecords(records, seq);
+  }
+  /**
+   * Clears only user table stores, leaving internal metadata and outbox intact if desired.
+   *
+   * @param clearOutbox - Whether to clear the pending outbox queue as well (defaults to `true`).
+   */
+  async clearTables(clearOutbox = true) {
+    return this.withDatabase(async (db) => {
+      const storeNames = Array.from(db.objectStoreNames).filter((name) => {
+        if (name === META_STORE) return false;
+        if (name === OUTBOX_STORE && !clearOutbox) return false;
+        return true;
+      });
+      await this.clearStores(db, storeNames);
+    });
+  }
+  /**
+   * Clears all local table stores, outbox changelog entries, and metadata.
+   */
+  async clearAllData() {
+    return this.withDatabase(async (db) => {
+      await this.clearStores(db, Array.from(db.objectStoreNames));
+    });
+  }
+  /**
+   * Closes the active IndexedDB connection.
+   */
+  async close() {
+    if (this.databasePromise) {
+      const db = await this.databasePromise;
+      db.close();
+      this.databasePromise = null;
+    }
+  }
+  // -- Private Helpers ------------------------------------------------------
+  async withDatabase(fn) {
+    return this.schemaMutex.then(async () => {
+      const db = await this.getDatabase();
+      return fn(db);
+    });
+  }
+  async applyBatchRecords(records, seq) {
+    if (records.length === 0) {
+      await this.setMeta("lastSyncSeq", seq);
+      return;
+    }
+    const tableNames = Array.from(
+      new Set(records.map((item) => item.table))
+    ).filter(Boolean);
+    await this.ensureTables(tableNames);
+    await this.withDatabase(async (database) => {
+      const tx = database.transaction([...tableNames, META_STORE], "readwrite");
+      const tableStores = /* @__PURE__ */ new Map();
+      for (const name of tableNames) {
+        tableStores.set(name, tx.objectStore(name));
+      }
+      for (const item of records) {
+        const store = tableStores.get(item.table);
+        if (!store) continue;
+        const getReq = store.get(item.id);
+        getReq.onsuccess = () => {
+          const existing = getReq.result;
+          if (!existing || shouldOverwrite(item, existing)) {
+            if (item.deleted) {
+              store.delete(item.id);
+            } else {
+              const record = {
+                id: item.id,
+                data: item.data,
+                timestamp: item.timestamp,
+                version: item.version ?? 1,
+                clientId: item.clientId
+              };
+              store.put(record);
+            }
+          }
+        };
+      }
+      const metaStore = tx.objectStore(META_STORE);
+      metaStore.put({ key: "lastSyncSeq", value: seq });
+      metaStore.put({ key: "lastSyncTimestamp", value: Date.now() });
+      await promisifyTransaction(tx);
+    });
+  }
+  async clearStores(database, storeNames) {
+    if (storeNames.length === 0) return;
+    const tx = database.transaction(storeNames, "readwrite");
+    for (const name of storeNames) {
+      tx.objectStore(name).clear();
+    }
+    await promisifyTransaction(tx);
+  }
+  async openDatabase() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.name);
+      request.onupgradeneeded = () => {
+        this.createInternalStores(request.result);
+      };
+      request.onsuccess = () => {
+        const database = request.result;
+        if (!database.objectStoreNames.contains(OUTBOX_STORE) || !database.objectStoreNames.contains(META_STORE)) {
+          const nextVersion = database.version + 1;
+          this.databasePromise = this.upgradeDatabase(
+            database,
+            nextVersion,
+            []
+          );
+          this.databasePromise.then(resolve).catch(reject);
+        } else {
+          resolve(database);
+        }
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async upgradeDatabase(currentDb, nextVersion, newTables) {
+    currentDb.close();
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.name, nextVersion);
+      request.onupgradeneeded = () => {
+        const database = request.result;
+        this.createInternalStores(database);
+        for (const tableName of newTables) {
+          if (!database.objectStoreNames.contains(tableName)) {
+            database.createObjectStore(tableName, { keyPath: "id" });
+          }
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+  createInternalStores(db) {
+    if (!db.objectStoreNames.contains(OUTBOX_STORE)) {
+      db.createObjectStore(OUTBOX_STORE, {
+        keyPath: "localId",
+        autoIncrement: true
+      });
+    }
+    if (!db.objectStoreNames.contains(META_STORE)) {
+      db.createObjectStore(META_STORE, { keyPath: "key" });
+    }
+  }
+};
+var OUTBOX_STORE = "__tether_outbox";
+var META_STORE = "__tether_meta";
+function promisifyRequest(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function promisifyTransaction(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+  });
+}
+
+// src/client/sync.ts
+var SyncStatus = /* @__PURE__ */ ((SyncStatus2) => {
+  SyncStatus2[SyncStatus2["Disconnected"] = 0] = "Disconnected";
+  SyncStatus2[SyncStatus2["Connecting"] = 1] = "Connecting";
+  SyncStatus2[SyncStatus2["Connected"] = 2] = "Connected";
+  SyncStatus2[SyncStatus2["Error"] = 3] = "Error";
+  return SyncStatus2;
+})(SyncStatus || {});
+var Sync = class {
+  /** Remote WebSocket endpoint URL. */
+  url;
+  /** Application namespace identifier for partitioning synchronization channels. */
+  appId;
+  /** Client identifier used for conflict resolution tie-breaking. */
+  clientId;
+  /** Reactive event registry triggered whenever synchronization status transitions. */
+  onStatusChange = new EventRegistry();
+  /** Reactive event registry triggered whenever background sync or network errors occur. */
+  onError = new EventRegistry();
+  token;
+  storage;
+  options;
+  webSocket = null;
+  currentStatus = 0 /* Disconnected */;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  pingTimer = null;
+  pushTimer = null;
+  isPushing = false;
+  isDestroyed = false;
+  pendingBatches = /* @__PURE__ */ new Map();
+  // batchId -> localIds
+  messageQueue = Promise.resolve();
+  /**
+   * Creates a new Sync instance.
+   *
+   * @param storage - Local storage coordinator.
+   * @param options - Configuration options for sync and connection.
+   */
+  constructor(storage, options) {
+    if (!options.appId) {
+      throw new TetherClientError(
+        0 /* MissingConfiguration */,
+        "Missing required appId in SyncOptions"
+      );
+    }
+    if (!options.clientId) {
+      throw new TetherClientError(
+        0 /* MissingConfiguration */,
+        "Missing required clientId in SyncOptions"
+      );
+    }
+    this.url = options.url;
+    this.token = options.token;
+    this.storage = storage;
+    this.appId = options.appId;
+    this.clientId = options.clientId;
+    this.options = {
+      reconnectIntervalMs: 1e3,
+      maxReconnectIntervalMs: 3e4,
+      pingIntervalMs: 3e4,
+      ...options
+    };
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      window.addEventListener("online", this.handleOnline);
+      window.addEventListener("offline", this.handleOffline);
+    }
+    if (this.token && this.url) {
+      this.connect();
+    }
+  }
+  /**
+   * Current operational status of the sync coordinator.
+   */
+  get status() {
+    return this.currentStatus;
+  }
+  /**
+   * Initiates a WebSocket connection to the sync endpoint and sends authentication.
+   *
+   * @param token - Optional session token to connect with.
+   * @param url - Optional WebSocket URL override.
+   */
+  connect(token, url) {
+    if (token) this.token = token;
+    if (url) this.url = url;
+    if (!this.url) {
+      return;
+    }
+    if (this.webSocket) {
+      this.disconnect();
+    }
+    this.setStatus(1 /* Connecting */);
+    const wsUrl = this.url;
+    const WebSocketImpl = this.options.webSocketClass ?? (typeof WebSocket !== "undefined" ? WebSocket : null);
+    if (!WebSocketImpl) {
+      this.setStatus(3 /* Error */);
+      this.onError.publish(
+        new TetherClientError(
+          0 /* MissingConfiguration */,
+          "No WebSocket implementation available in this environment"
+        )
+      );
+      return;
+    }
+    try {
+      this.webSocket = new WebSocketImpl(wsUrl);
+    } catch (err) {
+      this.setStatus(3 /* Error */);
+      this.onError.publish(
+        new TetherClientError(
+          3 /* NetworkError */,
+          err instanceof Error ? err.message : "Failed to construct WebSocket connection"
+        )
+      );
+      this.scheduleReconnect();
+      return;
+    }
+    this.webSocket.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.startPing();
+      this.sendAuth();
+    };
+    this.webSocket.onmessage = (event) => {
+      try {
+        const raw = typeof event.data === "string" ? event.data : event.data.toString("utf8");
+        const msg = JSON.parse(raw);
+        this.messageQueue = this.messageQueue.then(() => this.handleServerMessage(msg)).catch((err) => {
+          this.onError.publish(
+            new TetherClientError(
+              8 /* SyncError */,
+              err instanceof Error ? err.message : "Failed to process incoming WebSocket message"
+            )
+          );
+        });
+      } catch (err) {
+        this.onError.publish(
+          new TetherClientError(
+            8 /* SyncError */,
+            err instanceof Error ? err.message : "Failed to parse incoming WebSocket message"
+          )
+        );
+      }
+    };
+    this.webSocket.onerror = () => {
+      this.onError.publish(
+        new TetherClientError(
+          3 /* NetworkError */,
+          "WebSocket connection encountered an error"
+        )
+      );
+    };
+    this.webSocket.onclose = (event) => {
+      this.stopPing();
+      this.pendingBatches.clear();
+      this.messageQueue = Promise.resolve();
+      this.webSocket = null;
+      if (!this.isDestroyed) {
+        this.setStatus(0 /* Disconnected */);
+        if (event.code !== 1e3 && event.code !== 1005) {
+          this.scheduleReconnect();
+        }
+      }
+    };
+  }
+  /**
+   * Disconnects the active WebSocket connection.
+   */
+  disconnect() {
+    this.stopPing();
+    this.pendingBatches.clear();
+    this.messageQueue = Promise.resolve();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.webSocket) {
+      const ws = this.webSocket;
+      this.webSocket = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onerror = () => {
+      };
+      ws.onclose = null;
+      try {
+        const wsWithTerminate = ws;
+        if (typeof wsWithTerminate.terminate === "function") {
+          wsWithTerminate.terminate();
+        } else {
+          ws.close();
+        }
+      } catch {
+      }
+    }
+    this.setStatus(0 /* Disconnected */);
+  }
+  /**
+   * Permanently tears down the sync coordinator and cancels reconnection timers.
+   */
+  destroy() {
+    this.isDestroyed = true;
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      window.removeEventListener("online", this.handleOnline);
+      window.removeEventListener("offline", this.handleOffline);
+    }
+    this.disconnect();
+  }
+  /**
+   * Schedules a debounced push of pending outbox mutations.
+   *
+   * @param delayMs - Optional override for debounce delay in milliseconds.
+   */
+  schedulePush(delayMs) {
+    const delay = delayMs ?? this.options.pushDebounceMs ?? 10;
+    if (this.pushTimer) clearTimeout(this.pushTimer);
+    this.pushTimer = setTimeout(() => {
+      this.pushTimer = null;
+      this.pushOutbox();
+    }, delay);
+  }
+  /**
+   * Immediately extracts queued outbox changes and transmits them to the server.
+   */
+  async pushOutbox() {
+    if (this.isPushing || this.pendingBatches.size > 0 || this.currentStatus !== 2 /* Connected */ || !this.webSocket || this.webSocket.readyState !== (this.webSocket.OPEN ?? 1)) {
+      return;
+    }
+    this.isPushing = true;
+    try {
+      const pending = await this.storage.getPendingOutbox(500);
+      if (pending.length === 0) return;
+      const batchId = `batch_${Math.random().toString(36).substring(2, 10)}`;
+      const localIds = [];
+      const changes = [];
+      for (const entry of pending) {
+        if (entry.localId !== void 0) {
+          localIds.push(entry.localId);
+        }
+        changes.push(entry.change);
+      }
+      this.pendingBatches.set(batchId, localIds);
+      this.send({
+        type: "change_batch" /* ChangeBatch */,
+        clientId: this.clientId,
+        batchId,
+        changes
+      });
+    } catch (err) {
+      this.onError.publish(
+        new TetherClientError(
+          8 /* SyncError */,
+          err instanceof Error ? err.message : "Failed to push outbox batch to server"
+        )
+      );
+    } finally {
+      this.isPushing = false;
+    }
+  }
+  // -- Private Helpers ------------------------------------------------------
+  setStatus(newStatus) {
+    if (this.currentStatus === newStatus) return;
+    this.currentStatus = newStatus;
+    this.onStatusChange.publish(newStatus);
+  }
+  startPing() {
+    this.stopPing();
+    const interval = this.options.pingIntervalMs ?? 3e4;
+    if (interval <= 0) return;
+    this.pingTimer = setInterval(() => {
+      this.send({ type: "ping" /* Ping */ });
+    }, interval);
+  }
+  stopPing() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+  isOnline() {
+    if (typeof navigator !== "undefined" && typeof navigator.onLine === "boolean") {
+      return navigator.onLine;
+    }
+    return true;
+  }
+  handleOnline = () => {
+    if (this.isDestroyed || !this.token || !this.url) return;
+    this.reconnectAttempts = 0;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.connect();
+  };
+  handleOffline = () => {
+    if (this.isDestroyed) return;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.webSocket) {
+      this.disconnect();
+    }
+  };
+  scheduleReconnect() {
+    if (this.reconnectTimer || this.isDestroyed || !this.isOnline()) return;
+    const base = this.options.reconnectIntervalMs ?? 1e3;
+    const max = this.options.maxReconnectIntervalMs ?? 3e4;
+    const delay = Math.min(base * 2 ** this.reconnectAttempts, max);
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+  send(msg) {
+    if (this.webSocket && this.webSocket.readyState === (this.webSocket.OPEN ?? 1)) {
+      this.webSocket.send(JSON.stringify(msg));
+    }
+  }
+  async sendAuth() {
+    const lastSyncSeq = await this.storage.getMeta("lastSyncSeq") ?? 0;
+    this.send({
+      type: "auth" /* Auth */,
+      protocolVersion: PROTOCOL_VERSION,
+      token: this.token ?? "",
+      appId: this.options.appId,
+      clientId: this.clientId,
+      lastSyncSeq
+    });
+  }
+  async handleServerMessage(msg) {
+    switch (msg.type) {
+      case "auth_success" /* AuthSuccess */: {
+        this.reconnectAttempts = 0;
+        this.setStatus(2 /* Connected */);
+        if (msg.token) {
+          this.token = msg.token;
+          this.options.onTokenRefresh?.(msg.token);
+        }
+        this.startPing();
+        await this.pushOutbox();
+        break;
+      }
+      case "auth_error" /* AuthError */: {
+        this.setStatus(3 /* Error */);
+        this.disconnect();
+        this.options.onAuthError?.(msg.message);
+        this.onError.publish(
+          new TetherClientError(
+            6 /* AuthenticationFailed */,
+            msg.message
+          )
+        );
+        break;
+      }
+      case "sync_snapshot" /* SyncSnapshot */: {
+        await this.handleSnapshot(msg.snapshot, msg.seq);
+        await this.pushOutbox();
+        break;
+      }
+      case "sync_diff" /* SyncDiff */: {
+        await this.handleDiff(msg.changes, msg.toSeq);
+        await this.pushOutbox();
+        break;
+      }
+      case "broadcast_changes" /* BroadcastChanges */: {
+        await this.handleDiff(msg.changes, msg.seq);
+        break;
+      }
+      case "change_ack" /* ChangeAck */: {
+        const localIds = this.pendingBatches.get(msg.batchId);
+        if (localIds) {
+          this.pendingBatches.delete(msg.batchId);
+          await this.storage.removeOutboxEntries(localIds);
+        }
+        if (msg.appliedSeq !== void 0) {
+          await this.storage.setMeta("lastSyncSeq", msg.appliedSeq);
+        }
+        await this.pushOutbox();
+        break;
+      }
+      case "pong" /* Pong */:
+        break;
+      case "error" /* Error */:
+        this.onError.publish(
+          new TetherClientError(8 /* SyncError */, msg.message)
+        );
+        break;
+    }
+  }
+  async handleSnapshot(records, seq) {
+    await this.storage.applySnapshotBatch(records, seq);
+    this.notifyTableRemoteEvents(
+      records.map((item) => ({
+        table: item.table,
+        id: item.id,
+        isDelete: item.deleted ?? false,
+        data: item.data
+      }))
+    );
+  }
+  async handleDiff(changes, seq) {
+    await this.storage.applyRemoteChangesBatch(changes, seq);
+    this.notifyTableRemoteEvents(
+      changes.map((change) => ({
+        table: change.table,
+        id: change.id,
+        isDelete: change.op === "delete" /* Delete */,
+        data: change.data
+      }))
+    );
+  }
+  notifyTableRemoteEvents(items) {
+    const tableEvents = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      let events = tableEvents.get(item.table);
+      if (!events) {
+        events = [];
+        tableEvents.set(item.table, events);
+      }
+      events.push({
+        op: item.isDelete ? "delete" /* Delete */ : "put" /* Put */,
+        id: item.id,
+        data: item.isDelete ? void 0 : item.data,
+        isRemote: true
+      });
+    }
+    for (const [tableName, events] of tableEvents.entries()) {
+      const table = this.storage.table(tableName);
+      table.notifyRemoteChanges(events);
+    }
+  }
+};
+
+// src/client/client.ts
+var TetherClient = class {
+  /** Reactive event registry triggered whenever the authentication status changes. */
+  onAuthStatusChange = new EventRegistry();
+  /** Reactive event registry triggered whenever the synchronization status changes. */
+  onSyncStatusChange = new EventRegistry();
+  /** Reactive event registry triggered whenever background sync or network errors occur. */
+  onError = new EventRegistry();
+  storage;
+  auth;
+  sync;
+  /**
+   * Initializes a new TetherClient instance and wires reactive auth & sync coordination.
+   *
+   * @param name - Name of the local IndexedDB database.
+   * @param options - Configuration options for the server connection and sync behavior.
+   */
+  constructor(name, options = {}) {
+    this.storage = this.createStorage(name);
+    this.auth = this.createAuth(options, this.storage);
+    this.sync = this.createSync(name, options, this.storage);
+    this.storage.onLocalChange.register(() => {
+      this.sync.schedulePush();
+    });
+    this.auth.onStatusChange.register((status) => {
+      this.onAuthStatusChange.publish(status);
+      if (status === 2 /* SignedIn */ && this.auth.token) {
+        this.sync.connect(this.auth.token);
+      } else {
+        this.sync.disconnect();
+      }
+    });
+    this.sync.onStatusChange.register((status) => {
+      this.onSyncStatusChange.publish(status);
+    });
+    this.sync.onError.register((err) => {
+      this.onError.publish(err);
+    });
+  }
+  // -- Database / Storage ------------------------------------------------------
+  /**
+   * Obtains a typed table reference for reading, mutating, and subscribing to records.
+   * Tables are created dynamically on-demand if not already declared.
+   *
+   * @typeParam T - Data payload model type for records in this table.
+   * @param name - The table name.
+   * @returns A typed `Table<T>` instance.
+   */
+  table(name) {
+    return this.storage.table(name);
+  }
+  /**
+   * Clears all local application tables, outbox entries, and sync metadata.
+   */
+  async clear() {
+    await this.storage.clearAllData();
+  }
+  /**
+   * Closes active synchronization connections and closes the IndexedDB database handle.
+   */
+  async close() {
+    this.sync.destroy();
+    await this.storage.close();
+  }
+  // -- Authentication ------------------------------------------------------
+  /**
+   * Current authentication lifecycle status.
+   */
+  get authStatus() {
+    return this.auth.status;
+  }
+  /**
+   * The authenticated user's username, or `undefined` if signed out.
+   */
+  get username() {
+    return this.auth.username;
+  }
+  /**
+   * Registers a new user account, applies local data mode, and connects synchronization.
+   *
+   * @param options - Registration credentials and data reconciliation settings.
+   * @returns `true` if registration succeeded; `false` otherwise.
+   */
+  async register(options) {
+    return this.auth.register(options);
+  }
+  /**
+   * Logs into an account (or reconnects using remembered credentials), applies data mode, and connects synchronization.
+   *
+   * @param options - Optional login credentials and data reconciliation mode.
+   * @returns `true` if authentication succeeded; `false` otherwise.
+   */
+  async login(options = {}) {
+    return this.auth.login(options);
+  }
+  /**
+   * Logs out of the current session, disconnects sync, and optionally clears local tables.
+   *
+   * @param options - Options controlling whether local data should be wiped.
+   * @returns `true` on successful logout.
+   */
+  async logout(options = {}) {
+    return this.auth.logout(options);
+  }
+  // -- Synchronization ------------------------------------------------------
+  /**
+   * Retrieves the current synchronization status (e.g. Connected, Connecting, Disconnected, Error).
+   */
+  get syncStatus() {
+    return this.sync.status;
+  }
+  // -- Private Helpers ------------------------------------------------------
+  createStorage(name) {
+    return new Storage(name);
+  }
+  createAuth(options, storage) {
+    return new Auth({
+      baseUrl: this.resolveBaseUrl(options),
+      storage,
+      fetchFn: options.fetch
+    });
+  }
+  createSync(name, options, storage) {
+    return new Sync(storage, {
+      url: this.resolveWebSocketUrl(options),
+      appId: options.appId ?? name,
+      clientId: storage.clientId,
+      webSocketClass: options.webSocketClass,
+      pushDebounceMs: options.pushDebounceMs,
+      reconnectIntervalMs: options.reconnectIntervalMs,
+      maxReconnectIntervalMs: options.maxReconnectIntervalMs,
+      pingIntervalMs: options.pingIntervalMs,
+      onTokenRefresh: (token) => {
+        this.auth.handleTokenRefresh(token);
+      },
+      onAuthError: (message) => {
+        this.auth.handleAuthError(message);
+      }
+    });
+  }
+  parseUrl(urlStr) {
+    if (!urlStr) return {};
+    try {
+      const isWs = /^wss?:/i.test(urlStr);
+      const isSecure = /^https:|^wss:/i.test(urlStr);
+      const httpNormalized = urlStr.replace(/^ws(s)?:/i, "http$1:");
+      const parsed = new URL(httpNormalized);
+      const host = parsed.hostname || void 0;
+      const port = parsed.port ? Number.parseInt(parsed.port, 10) : void 0;
+      const pathname = parsed.pathname;
+      let basePath;
+      let webSocketPath;
+      if (isWs) {
+        if (pathname === "/sync" || pathname === "/sync/") {
+          basePath = "";
+          webSocketPath = "/sync";
+        } else if (pathname.endsWith("/sync") || pathname.endsWith("/sync/")) {
+          basePath = pathname.replace(/\/sync\/?$/, "");
+          webSocketPath = pathname.replace(/\/$/, "");
+        } else if (pathname && pathname !== "/") {
+          basePath = pathname.replace(/\/$/, "");
+          webSocketPath = `${basePath}/sync`;
+        }
+      } else {
+        if (pathname && pathname !== "/") {
+          basePath = pathname.replace(/\/$/, "");
+        } else {
+          basePath = "";
+        }
+      }
+      return {
+        host,
+        port,
+        secure: isSecure,
+        basePath,
+        webSocketPath
+      };
+    } catch {
+      return {};
+    }
+  }
+  resolveHostHeader(options) {
+    const urlConfig = this.parseUrl(options.url);
+    const isBrowser = typeof window !== "undefined" && Boolean(window.location);
+    const host = options.host ?? urlConfig.host ?? (isBrowser && window.location.hostname !== "" ? window.location.hostname : void 0);
+    const port = options.port ?? urlConfig.port ?? (isBrowser && window.location.port ? Number.parseInt(window.location.port, 10) : void 0);
+    const secure = options.secure ?? urlConfig.secure ?? (isBrowser ? window.location.protocol === "https:" : false);
+    if (!host) {
+      return { host: void 0, secure };
+    }
+    const hostHeader = port !== void 0 && !host.includes(":") ? `${host}:${port}` : host;
+    return { host: hostHeader, secure };
+  }
+  resolveBaseUrl(options) {
+    const urlConfig = this.parseUrl(options.url);
+    const basePath = normalizeBasePath(
+      options.basePath ?? urlConfig.basePath ?? ""
+    );
+    const { host, secure } = this.resolveHostHeader(options);
+    if (!host) return basePath;
+    const proto = secure ? "https" : "http";
+    return `${proto}://${host}${basePath}`;
+  }
+  resolveWebSocketUrl(options) {
+    const urlConfig = this.parseUrl(options.url);
+    const { host, secure } = this.resolveHostHeader(options);
+    if (!host) return void 0;
+    const basePath = normalizeBasePath(
+      options.basePath ?? urlConfig.basePath ?? ""
+    );
+    const webSocketPath = options.webSocketPath ?? urlConfig.webSocketPath ?? `${basePath}/sync`;
+    const proto = secure ? "wss" : "ws";
+    return `${proto}://${host}${webSocketPath}`;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthStatus,
+  DataMode,
+  OperationType,
+  PROTOCOL_VERSION,
+  SyncStatus,
+  Table,
+  TetherClient,
+  TetherClientError,
+  TetherClientErrorCode
+});
+//# sourceMappingURL=index.cjs.map