@lark-sh/client 0.1.0

package/dist/index.js

@@ -0,0 +1,1391 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DataSnapshot: () => DataSnapshot,
+  DatabaseReference: () => DatabaseReference,
+  LarkDatabase: () => LarkDatabase,
+  LarkError: () => LarkError,
+  OnDisconnect: () => OnDisconnect,
+  generatePushId: () => generatePushId
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/protocol/constants.ts
+var OnDisconnectAction = {
+  SET: "s",
+  UPDATE: "u",
+  DELETE: "d",
+  CANCEL: "c"
+};
+var eventTypeFromShort = {
+  v: "value",
+  ca: "child_added",
+  cc: "child_changed",
+  cr: "child_removed"
+};
+var eventTypeToShort = {
+  value: "v",
+  child_added: "ca",
+  child_changed: "cc",
+  child_removed: "cr"
+};
+var DEFAULT_COORDINATOR_URL = "https://db.lark.dev";
+
+// src/connection/Coordinator.ts
+var Coordinator = class {
+  constructor(baseUrl = DEFAULT_COORDINATOR_URL) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  /**
+   * Request connection details from the coordinator.
+   *
+   * @param database - Database ID in format "project/database"
+   * @param options - Either a user token or anonymous flag
+   * @returns Connection details including host, port, and connection token
+   */
+  async connect(database, options = {}) {
+    const body = { database };
+    if (options.token) {
+      body.token = options.token;
+    } else if (options.anonymous) {
+      body.anonymous = true;
+    } else {
+      body.anonymous = true;
+    }
+    const response = await fetch(`${this.baseUrl}/connect`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      let errorMessage = `Coordinator request failed: ${response.status}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    const data = await response.json();
+    return data;
+  }
+};
+
+// src/LarkError.ts
+var LarkError = class _LarkError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.code = code;
+    this.name = "LarkError";
+    const ErrorWithCapture = Error;
+    if (ErrorWithCapture.captureStackTrace) {
+      ErrorWithCapture.captureStackTrace(this, _LarkError);
+    }
+  }
+};
+
+// src/protocol/messages.ts
+function isAckMessage(msg) {
+  return "a" in msg && !("uid" in msg);
+}
+function isJoinAckMessage(msg) {
+  return "a" in msg && "uid" in msg;
+}
+function isNackMessage(msg) {
+  return "n" in msg;
+}
+function isEventMessage(msg) {
+  return "ev" in msg;
+}
+function isOnceResponseMessage(msg) {
+  return "oc" in msg;
+}
+function isPushAckMessage(msg) {
+  return "pa" in msg;
+}
+
+// src/connection/MessageQueue.ts
+var MessageQueue = class {
+  constructor(defaultTimeout = 3e4) {
+    this.nextId = 1;
+    this.pending = /* @__PURE__ */ new Map();
+    this.defaultTimeout = defaultTimeout;
+  }
+  /**
+   * Generate a new unique request ID.
+   */
+  nextRequestId() {
+    return String(this.nextId++);
+  }
+  /**
+   * Register a pending request that expects a response.
+   * Returns a promise that resolves when ack is received, or rejects on nack/timeout.
+   */
+  registerRequest(requestId, timeout) {
+    return new Promise((resolve, reject) => {
+      const timeoutMs = timeout ?? this.defaultTimeout;
+      const timeoutHandle = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new LarkError("timeout", `Request ${requestId} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(requestId, {
+        resolve,
+        reject,
+        timeout: timeoutHandle
+      });
+    });
+  }
+  /**
+   * Handle an incoming server message. If it's a response to a pending request,
+   * resolve or reject the corresponding promise.
+   *
+   * @returns true if the message was handled (was a response), false otherwise
+   */
+  handleMessage(message) {
+    if (isJoinAckMessage(message)) {
+      const pending = this.pending.get(message.a);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.a);
+        pending.resolve({
+          uid: message.uid,
+          provider: message.provider,
+          token: message.token
+        });
+        return true;
+      }
+    }
+    if (isAckMessage(message)) {
+      const pending = this.pending.get(message.a);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.a);
+        pending.resolve(void 0);
+        return true;
+      }
+    }
+    if (isNackMessage(message)) {
+      const pending = this.pending.get(message.n);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.n);
+        pending.reject(new LarkError(message.e, message.m));
+        return true;
+      }
+    }
+    if (isOnceResponseMessage(message)) {
+      const pending = this.pending.get(message.oc);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.oc);
+        pending.resolve(message.ov);
+        return true;
+      }
+    }
+    if (isPushAckMessage(message)) {
+      const pending = this.pending.get(message.pa);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.pa);
+        pending.resolve(message.pk);
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Reject all pending requests (e.g., on disconnect).
+   */
+  rejectAll(error) {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+  /**
+   * Get the number of pending requests.
+   */
+  get pendingCount() {
+    return this.pending.size;
+  }
+};
+
+// src/connection/SubscriptionManager.ts
+var SubscriptionManager = class {
+  constructor() {
+    // path -> eventType -> array of subscriptions
+    this.subscriptions = /* @__PURE__ */ new Map();
+    // Callback to send subscribe message to server
+    this.sendSubscribe = null;
+    // Callback to send unsubscribe message to server
+    this.sendUnsubscribe = null;
+    // Callback to create DataSnapshot from event data
+    this.createSnapshot = null;
+  }
+  /**
+   * Initialize the manager with server communication callbacks.
+   */
+  initialize(options) {
+    this.sendSubscribe = options.sendSubscribe;
+    this.sendUnsubscribe = options.sendUnsubscribe;
+    this.createSnapshot = options.createSnapshot;
+  }
+  /**
+   * Subscribe to events at a path.
+   * Returns an unsubscribe function.
+   */
+  subscribe(path, eventType, callback) {
+    const normalizedPath = path;
+    const isFirstForPath = !this.subscriptions.has(normalizedPath);
+    const existingEventTypes = this.getEventTypesForPath(normalizedPath);
+    const isFirstForEventType = !existingEventTypes.includes(eventType);
+    if (!this.subscriptions.has(normalizedPath)) {
+      this.subscriptions.set(normalizedPath, /* @__PURE__ */ new Map());
+    }
+    const pathSubs = this.subscriptions.get(normalizedPath);
+    if (!pathSubs.has(eventType)) {
+      pathSubs.set(eventType, []);
+    }
+    const eventSubs = pathSubs.get(eventType);
+    const unsubscribe = () => {
+      this.unsubscribeCallback(normalizedPath, eventType, callback);
+    };
+    eventSubs.push({ callback, unsubscribe });
+    if (isFirstForPath || isFirstForEventType) {
+      const allEventTypes = this.getEventTypesForPath(normalizedPath);
+      const shortEventTypes = allEventTypes.map((et) => eventTypeToShort[et]);
+      this.sendSubscribe?.(normalizedPath, shortEventTypes).catch((err) => {
+        console.error("Failed to subscribe:", err);
+      });
+    }
+    return unsubscribe;
+  }
+  /**
+   * Remove a specific callback from a subscription.
+   */
+  unsubscribeCallback(path, eventType, callback) {
+    const pathSubs = this.subscriptions.get(path);
+    if (!pathSubs) return;
+    const eventSubs = pathSubs.get(eventType);
+    if (!eventSubs) return;
+    const index = eventSubs.findIndex((entry) => entry.callback === callback);
+    if (index !== -1) {
+      eventSubs.splice(index, 1);
+    }
+    if (eventSubs.length === 0) {
+      pathSubs.delete(eventType);
+    }
+    if (pathSubs.size === 0) {
+      this.subscriptions.delete(path);
+      this.sendUnsubscribe?.(path).catch((err) => {
+        console.error("Failed to unsubscribe:", err);
+      });
+    }
+  }
+  /**
+   * Remove all subscriptions of a specific event type at a path.
+   */
+  unsubscribeEventType(path, eventType) {
+    const normalizedPath = path;
+    const pathSubs = this.subscriptions.get(normalizedPath);
+    if (!pathSubs) return;
+    pathSubs.delete(eventType);
+    if (pathSubs.size === 0) {
+      this.subscriptions.delete(normalizedPath);
+      this.sendUnsubscribe?.(normalizedPath).catch((err) => {
+        console.error("Failed to unsubscribe:", err);
+      });
+    } else {
+      const remainingEventTypes = this.getEventTypesForPath(normalizedPath);
+      const shortEventTypes = remainingEventTypes.map((et) => eventTypeToShort[et]);
+      this.sendSubscribe?.(normalizedPath, shortEventTypes).catch((err) => {
+        console.error("Failed to update subscription:", err);
+      });
+    }
+  }
+  /**
+   * Remove ALL subscriptions at a path.
+   */
+  unsubscribeAll(path) {
+    const normalizedPath = path;
+    if (!this.subscriptions.has(normalizedPath)) return;
+    this.subscriptions.delete(normalizedPath);
+    this.sendUnsubscribe?.(normalizedPath).catch((err) => {
+      console.error("Failed to unsubscribe:", err);
+    });
+  }
+  /**
+   * Handle an incoming event message from the server.
+   */
+  handleEvent(message) {
+    const eventType = eventTypeFromShort[message.ev];
+    if (!eventType) {
+      console.warn("Unknown event type:", message.ev);
+      return;
+    }
+    const path = message.p;
+    const pathSubs = this.subscriptions.get(path);
+    if (!pathSubs) return;
+    const eventSubs = pathSubs.get(eventType);
+    if (!eventSubs || eventSubs.length === 0) return;
+    let snapshotPath;
+    let snapshotValue;
+    if (eventType === "value") {
+      snapshotPath = path;
+      snapshotValue = message.v;
+    } else {
+      snapshotPath = path === "/" ? `/${message.k}` : `${path}/${message.k}`;
+      snapshotValue = message.v;
+    }
+    const snapshot = this.createSnapshot?.(snapshotPath, snapshotValue, message.x ?? false);
+    if (!snapshot) return;
+    for (const entry of eventSubs) {
+      try {
+        entry.callback(snapshot, void 0);
+      } catch (err) {
+        console.error("Error in subscription callback:", err);
+      }
+    }
+  }
+  /**
+   * Get all event types currently subscribed at a path.
+   */
+  getEventTypesForPath(path) {
+    const pathSubs = this.subscriptions.get(path);
+    if (!pathSubs) return [];
+    return Array.from(pathSubs.keys());
+  }
+  /**
+   * Clear all subscriptions (e.g., on disconnect).
+   */
+  clear() {
+    this.subscriptions.clear();
+  }
+  /**
+   * Check if there are any subscriptions at a path.
+   */
+  hasSubscriptions(path) {
+    return this.subscriptions.has(path);
+  }
+};
+
+// src/connection/WebSocketClient.ts
+var import_ws = __toESM(require("ws"));
+var WebSocketImpl = typeof WebSocket !== "undefined" ? WebSocket : import_ws.default;
+var WebSocketClient = class {
+  constructor(options) {
+    this.ws = null;
+    this._state = "disconnected";
+    this.options = options;
+  }
+  get state() {
+    return this._state;
+  }
+  get connected() {
+    return this._state === "connected";
+  }
+  /**
+   * Connect to a WebSocket server.
+   */
+  connect(url) {
+    return new Promise((resolve, reject) => {
+      if (this._state !== "disconnected") {
+        reject(new Error("Already connected or connecting"));
+        return;
+      }
+      this._state = "connecting";
+      try {
+        this.ws = new WebSocketImpl(url);
+      } catch (err) {
+        this._state = "disconnected";
+        reject(err);
+        return;
+      }
+      const onOpen = () => {
+        cleanup();
+        this._state = "connected";
+        this.setupEventHandlers();
+        resolve();
+        this.options.onOpen();
+      };
+      const onError = (event) => {
+        cleanup();
+        this._state = "disconnected";
+        this.ws = null;
+        reject(new Error("WebSocket connection failed"));
+        this.options.onError(event);
+      };
+      const onClose = (event) => {
+        cleanup();
+        this._state = "disconnected";
+        this.ws = null;
+        reject(new Error(`WebSocket closed: ${event.code} ${event.reason}`));
+      };
+      const cleanup = () => {
+        this.ws?.removeEventListener("open", onOpen);
+        this.ws?.removeEventListener("error", onError);
+        this.ws?.removeEventListener("close", onClose);
+      };
+      this.ws.addEventListener("open", onOpen);
+      this.ws.addEventListener("error", onError);
+      this.ws.addEventListener("close", onClose);
+    });
+  }
+  /**
+   * Set up persistent event handlers after connection is established.
+   */
+  setupEventHandlers() {
+    if (!this.ws) return;
+    this.ws.addEventListener("message", (event) => {
+      this.options.onMessage(event.data);
+    });
+    this.ws.addEventListener("close", (event) => {
+      this._state = "disconnected";
+      this.ws = null;
+      this.options.onClose(event.code, event.reason);
+    });
+    this.ws.addEventListener("error", (event) => {
+      this.options.onError(event);
+    });
+  }
+  /**
+   * Send a message over the WebSocket.
+   */
+  send(data) {
+    if (!this.ws || this._state !== "connected") {
+      throw new Error("WebSocket not connected");
+    }
+    this.ws.send(data);
+  }
+  /**
+   * Close the WebSocket connection.
+   */
+  close(code = 1e3, reason = "Client disconnect") {
+    if (this.ws) {
+      this.ws.close(code, reason);
+      this.ws = null;
+    }
+    this._state = "disconnected";
+  }
+};
+
+// src/OnDisconnect.ts
+var OnDisconnect = class {
+  constructor(db, path) {
+    this._db = db;
+    this._path = path;
+  }
+  /**
+   * Set a value when disconnected.
+   */
+  async set(value) {
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.SET, value);
+  }
+  /**
+   * Update values when disconnected.
+   */
+  async update(values) {
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.UPDATE, values);
+  }
+  /**
+   * Remove data when disconnected.
+   */
+  async remove() {
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.DELETE);
+  }
+  /**
+   * Cancel any pending onDisconnect handlers at this location.
+   */
+  async cancel() {
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.CANCEL);
+  }
+  /**
+   * Set a value with priority when disconnected.
+   */
+  async setWithPriority(value, priority) {
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.SET, value, priority);
+  }
+};
+
+// src/utils/path.ts
+function normalizePath(path) {
+  if (!path || path === "/") return "/";
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  if (segments.length === 0) return "/";
+  return "/" + segments.join("/");
+}
+function joinPath(...segments) {
+  const allParts = [];
+  for (const segment of segments) {
+    if (!segment || segment === "/") continue;
+    const parts = segment.split("/").filter((p) => p.length > 0);
+    allParts.push(...parts);
+  }
+  if (allParts.length === 0) return "/";
+  return "/" + allParts.join("/");
+}
+function getParentPath(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return "/";
+  const lastSlash = normalized.lastIndexOf("/");
+  if (lastSlash <= 0) return "/";
+  return normalized.substring(0, lastSlash);
+}
+function getKey(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return null;
+  const lastSlash = normalized.lastIndexOf("/");
+  return normalized.substring(lastSlash + 1);
+}
+function getValueAtPath(obj, path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return obj;
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+// src/utils/pushid.ts
+var PUSH_CHARS = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
+var lastPushTime = 0;
+var lastRandChars = [];
+function generatePushId() {
+  let now = Date.now();
+  const duplicateTime = now === lastPushTime;
+  lastPushTime = now;
+  const timeChars = new Array(8);
+  for (let i = 7; i >= 0; i--) {
+    timeChars[i] = PUSH_CHARS.charAt(now % 64);
+    now = Math.floor(now / 64);
+  }
+  let id = timeChars.join("");
+  if (!duplicateTime) {
+    lastRandChars = [];
+    for (let i = 0; i < 12; i++) {
+      lastRandChars.push(Math.floor(Math.random() * 64));
+    }
+  } else {
+    let i = 11;
+    while (i >= 0 && lastRandChars[i] === 63) {
+      lastRandChars[i] = 0;
+      i--;
+    }
+    if (i >= 0) {
+      lastRandChars[i]++;
+    }
+  }
+  for (let i = 0; i < 12; i++) {
+    id += PUSH_CHARS.charAt(lastRandChars[i]);
+  }
+  return id;
+}
+
+// src/DatabaseReference.ts
+var DatabaseReference = class _DatabaseReference {
+  constructor(db, path, query = {}) {
+    this._db = db;
+    this._path = normalizePath(path);
+    this._query = query;
+  }
+  /**
+   * The path of this reference.
+   */
+  get path() {
+    return this._path;
+  }
+  /**
+   * The last segment of the path (the "key"), or null for root.
+   */
+  get key() {
+    return getKey(this._path);
+  }
+  /**
+   * Get a reference to the parent node, or null if this is root.
+   */
+  get parent() {
+    if (this._path === "/") return null;
+    const parentPath = getParentPath(this._path);
+    return new _DatabaseReference(this._db, parentPath);
+  }
+  /**
+   * Get a reference to the root of the database.
+   */
+  get root() {
+    return new _DatabaseReference(this._db, "");
+  }
+  // ============================================
+  // Navigation
+  // ============================================
+  /**
+   * Get a reference to a child path.
+   */
+  child(path) {
+    const childPath = joinPath(this._path, path);
+    return new _DatabaseReference(this._db, childPath);
+  }
+  // ============================================
+  // Write Operations
+  // ============================================
+  /**
+   * Set the data at this location, overwriting any existing data.
+   */
+  async set(value) {
+    await this._db._sendSet(this._path, value);
+  }
+  /**
+   * Update specific children at this location without overwriting other children.
+   */
+  async update(values) {
+    await this._db._sendUpdate(this._path, values);
+  }
+  /**
+   * Remove the data at this location.
+   */
+  async remove() {
+    await this._db._sendDelete(this._path);
+  }
+  /**
+   * Generate a new child location with a unique key and optionally set its value.
+   *
+   * If value is provided, sets the value and returns a Promise that resolves
+   * to the new reference.
+   *
+   * If no value is provided, returns a reference immediately with a client-generated
+   * push key (you can then call set() on it).
+   */
+  push(value) {
+    if (value === void 0) {
+      const key = generatePushId();
+      return this.child(key);
+    }
+    return this._db._sendPush(this._path, value).then((key) => {
+      return this.child(key);
+    });
+  }
+  /**
+   * Set the data with a priority value for ordering.
+   */
+  async setWithPriority(value, priority) {
+    await this._db._sendSet(this._path, value, priority);
+  }
+  /**
+   * Set the priority of the data at this location.
+   */
+  async setPriority(priority) {
+    console.warn("setPriority: fetching current value to preserve it");
+    const snapshot = await this.once();
+    await this.setWithPriority(snapshot.val(), priority);
+  }
+  // ============================================
+  // Read Operations
+  // ============================================
+  /**
+   * Read the data at this location once.
+   */
+  async once(eventType = "value") {
+    if (eventType !== "value") {
+      throw new Error('once() only supports "value" event type');
+    }
+    return this._db._sendOnce(this._path, this._buildQueryParams());
+  }
+  // ============================================
+  // Subscriptions
+  // ============================================
+  /**
+   * Subscribe to events at this location.
+   * Returns an unsubscribe function.
+   */
+  on(eventType, callback) {
+    return this._db._subscribe(this._path, eventType, callback);
+  }
+  /**
+   * Unsubscribe from events.
+   * If eventType is specified, removes all listeners of that type.
+   * If no eventType, removes ALL listeners at this path.
+   */
+  off(eventType) {
+    if (eventType) {
+      this._db._unsubscribeEventType(this._path, eventType);
+    } else {
+      this._db._unsubscribeAll(this._path);
+    }
+  }
+  // ============================================
+  // OnDisconnect
+  // ============================================
+  /**
+   * Get an OnDisconnect handler for this location.
+   */
+  onDisconnect() {
+    return new OnDisconnect(this._db, this._path);
+  }
+  // ============================================
+  // Query Modifiers
+  // ============================================
+  /**
+   * Order results by key.
+   */
+  orderByKey() {
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      orderBy: "key"
+    });
+  }
+  /**
+   * Order results by priority.
+   */
+  orderByPriority() {
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      orderBy: "priority"
+    });
+  }
+  /**
+   * Order results by a child key.
+   * NOTE: Phase 2 - not yet implemented on server.
+   */
+  orderByChild(path) {
+    console.warn("orderByChild() is not yet implemented");
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      orderBy: "child",
+      orderByChildPath: path
+    });
+  }
+  /**
+   * Order results by value.
+   * NOTE: Phase 2 - not yet implemented on server.
+   */
+  orderByValue() {
+    console.warn("orderByValue() is not yet implemented");
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      orderBy: "value"
+    });
+  }
+  /**
+   * Limit to the first N results.
+   */
+  limitToFirst(limit) {
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      limitToFirst: limit
+    });
+  }
+  /**
+   * Limit to the last N results.
+   */
+  limitToLast(limit) {
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      limitToLast: limit
+    });
+  }
+  /**
+   * Start at a specific value/key.
+   * NOTE: Phase 2 - not yet implemented on server.
+   */
+  startAt(value, key) {
+    console.warn("startAt() is not yet implemented");
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      startAt: { value, key }
+    });
+  }
+  /**
+   * End at a specific value/key.
+   * NOTE: Phase 2 - not yet implemented on server.
+   */
+  endAt(value, key) {
+    console.warn("endAt() is not yet implemented");
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      endAt: { value, key }
+    });
+  }
+  /**
+   * Filter to items equal to a specific value.
+   * NOTE: Phase 2 - not yet implemented on server.
+   */
+  equalTo(value, key) {
+    console.warn("equalTo() is not yet implemented");
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      equalTo: { value, key }
+    });
+  }
+  // ============================================
+  // Internal Helpers
+  // ============================================
+  /**
+   * Build query parameters for wire protocol.
+   */
+  _buildQueryParams() {
+    const params = {};
+    let hasParams = false;
+    if (this._query.orderBy === "key") {
+      params.ob = "k";
+      hasParams = true;
+    } else if (this._query.orderBy === "priority") {
+      params.ob = "p";
+      hasParams = true;
+    }
+    if (this._query.limitToFirst !== void 0) {
+      params.lf = this._query.limitToFirst;
+      hasParams = true;
+    }
+    if (this._query.limitToLast !== void 0) {
+      params.ll = this._query.limitToLast;
+      hasParams = true;
+    }
+    return hasParams ? params : void 0;
+  }
+  /**
+   * Returns the absolute URL for this database location.
+   * Format: https://db.lark.sh/project/database/path/to/data
+   */
+  toString() {
+    const baseUrl = this._db._getBaseUrl();
+    if (this._path === "/") {
+      return baseUrl;
+    }
+    return `${baseUrl}${this._path}`;
+  }
+};
+
+// src/DataSnapshot.ts
+var DataSnapshot = class _DataSnapshot {
+  constructor(data, path, db, options = {}) {
+    this._data = data;
+    this._path = normalizePath(path);
+    this._db = db;
+    this._volatile = options.volatile ?? false;
+    this._priority = options.priority ?? null;
+  }
+  /**
+   * Get a DatabaseReference for the location of this snapshot.
+   */
+  get ref() {
+    return this._db.ref(this._path);
+  }
+  /**
+   * Get the last segment of the path (the "key"), or null for root.
+   */
+  get key() {
+    return getKey(this._path);
+  }
+  /**
+   * Get the raw data value.
+   */
+  val() {
+    return this._data;
+  }
+  /**
+   * Check if data exists at this location (is not null/undefined).
+   */
+  exists() {
+    return this._data !== null && this._data !== void 0;
+  }
+  /**
+   * Get a child snapshot at the specified path.
+   */
+  child(path) {
+    const childPath = joinPath(this._path, path);
+    const childData = getValueAtPath(this._data, path);
+    return new _DataSnapshot(childData, childPath, this._db, {
+      volatile: this._volatile
+    });
+  }
+  /**
+   * Check if this snapshot has any children.
+   */
+  hasChildren() {
+    if (typeof this._data !== "object" || this._data === null) {
+      return false;
+    }
+    return Object.keys(this._data).length > 0;
+  }
+  /**
+   * Check if this snapshot has a specific child.
+   */
+  hasChild(path) {
+    const childData = getValueAtPath(this._data, path);
+    return childData !== void 0 && childData !== null;
+  }
+  /**
+   * Get the number of children.
+   */
+  numChildren() {
+    if (typeof this._data !== "object" || this._data === null) {
+      return 0;
+    }
+    return Object.keys(this._data).length;
+  }
+  /**
+   * Iterate over children. Return true from callback to stop iteration.
+   */
+  forEach(callback) {
+    if (typeof this._data !== "object" || this._data === null) {
+      return;
+    }
+    const keys = Object.keys(this._data);
+    for (const key of keys) {
+      const childSnap = this.child(key);
+      if (callback(childSnap) === true) {
+        break;
+      }
+    }
+  }
+  /**
+   * Get the priority of the data at this location.
+   */
+  getPriority() {
+    return this._priority;
+  }
+  /**
+   * Check if this snapshot was from a volatile (high-frequency) update.
+   * This is a Lark extension not present in Firebase.
+   */
+  isVolatile() {
+    return this._volatile;
+  }
+  /**
+   * Export the snapshot data as JSON (alias for val()).
+   */
+  toJSON() {
+    return this._data;
+  }
+};
+
+// src/utils/jwt.ts
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid JWT format");
+  }
+  const payload = parts[1];
+  const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  let decoded;
+  if (typeof atob === "function") {
+    decoded = atob(padded);
+  } else {
+    decoded = Buffer.from(padded, "base64").toString("utf-8");
+  }
+  return JSON.parse(decoded);
+}
+
+// src/LarkDatabase.ts
+var LarkDatabase = class {
+  constructor() {
+    this._state = "disconnected";
+    this._auth = null;
+    this._databaseId = null;
+    this._coordinatorUrl = null;
+    this.ws = null;
+    // Event callbacks
+    this.connectCallbacks = /* @__PURE__ */ new Set();
+    this.disconnectCallbacks = /* @__PURE__ */ new Set();
+    this.errorCallbacks = /* @__PURE__ */ new Set();
+    this.messageQueue = new MessageQueue();
+    this.subscriptionManager = new SubscriptionManager();
+  }
+  // ============================================
+  // Connection State
+  // ============================================
+  /**
+   * Whether the database is currently connected.
+   */
+  get connected() {
+    return this._state === "connected";
+  }
+  /**
+   * Current auth info, or null if not connected.
+   */
+  get auth() {
+    return this._auth;
+  }
+  /**
+   * @internal Get the base URL for reference toString().
+   */
+  _getBaseUrl() {
+    if (this._coordinatorUrl && this._databaseId) {
+      return `${this._coordinatorUrl}/${this._databaseId}`;
+    }
+    return "lark://";
+  }
+  // ============================================
+  // Connection Management
+  // ============================================
+  /**
+   * Connect to a database.
+   *
+   * @param databaseId - Database ID in format "project/database"
+   * @param options - Connection options (token, anonymous, coordinator URL)
+   */
+  async connect(databaseId, options = {}) {
+    if (this._state !== "disconnected") {
+      throw new Error("Already connected or connecting");
+    }
+    this._state = "connecting";
+    this._databaseId = databaseId;
+    this._coordinatorUrl = options.coordinator || DEFAULT_COORDINATOR_URL;
+    try {
+      const coordinatorUrl = this._coordinatorUrl;
+      const coordinator = new Coordinator(coordinatorUrl);
+      const connectResponse = await coordinator.connect(databaseId, {
+        token: options.token,
+        anonymous: options.anonymous
+      });
+      const wsUrl = connectResponse.ws_url;
+      this.ws = new WebSocketClient({
+        onMessage: this.handleMessage.bind(this),
+        onOpen: () => {
+        },
+        // Handled in connect flow
+        onClose: this.handleClose.bind(this),
+        onError: this.handleError.bind(this)
+      });
+      await this.ws.connect(wsUrl);
+      const requestId = this.messageQueue.nextRequestId();
+      const joinMessage = {
+        o: "j",
+        t: connectResponse.token,
+        r: requestId
+      };
+      this.send(joinMessage);
+      await this.messageQueue.registerRequest(requestId);
+      const jwtPayload = decodeJwtPayload(connectResponse.token);
+      this._auth = {
+        uid: jwtPayload.sub,
+        provider: jwtPayload.provider,
+        token: jwtPayload.claims || {}
+      };
+      this._state = "connected";
+      this.subscriptionManager.initialize({
+        sendSubscribe: this.sendSubscribeMessage.bind(this),
+        sendUnsubscribe: this.sendUnsubscribeMessage.bind(this),
+        createSnapshot: this.createSnapshot.bind(this)
+      });
+      this.connectCallbacks.forEach((cb) => cb());
+    } catch (error) {
+      this._state = "disconnected";
+      this._auth = null;
+      this._databaseId = null;
+      this.ws?.close();
+      this.ws = null;
+      throw error;
+    }
+  }
+  /**
+   * Disconnect from the database.
+   * This triggers onDisconnect hooks on the server.
+   */
+  async disconnect() {
+    if (this._state === "disconnected") {
+      return;
+    }
+    if (this._state === "connected" && this.ws) {
+      try {
+        const requestId = this.messageQueue.nextRequestId();
+        this.send({ o: "l", r: requestId });
+        await Promise.race([
+          this.messageQueue.registerRequest(requestId),
+          new Promise((resolve) => setTimeout(resolve, 1e3))
+        ]);
+      } catch {
+      }
+    }
+    this.cleanup();
+  }
+  /**
+   * Clean up connection state.
+   */
+  cleanup() {
+    this.ws?.close();
+    this.ws = null;
+    this._state = "disconnected";
+    this._auth = null;
+    this._databaseId = null;
+    this._coordinatorUrl = null;
+    this.subscriptionManager.clear();
+    this.messageQueue.rejectAll(new Error("Connection closed"));
+  }
+  // ============================================
+  // Reference Access
+  // ============================================
+  /**
+   * Get a reference to a path in the database.
+   */
+  ref(path = "") {
+    return new DatabaseReference(this, path);
+  }
+  // ============================================
+  // Connection Events
+  // ============================================
+  /**
+   * Register a callback for when connection is established.
+   * Returns an unsubscribe function.
+   */
+  onConnect(callback) {
+    this.connectCallbacks.add(callback);
+    return () => this.connectCallbacks.delete(callback);
+  }
+  /**
+   * Register a callback for when connection is lost.
+   * Returns an unsubscribe function.
+   */
+  onDisconnect(callback) {
+    this.disconnectCallbacks.add(callback);
+    return () => this.disconnectCallbacks.delete(callback);
+  }
+  /**
+   * Register a callback for connection errors.
+   * Returns an unsubscribe function.
+   */
+  onError(callback) {
+    this.errorCallbacks.add(callback);
+    return () => this.errorCallbacks.delete(callback);
+  }
+  // ============================================
+  // Internal: Message Handling
+  // ============================================
+  handleMessage(data) {
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      console.error("Failed to parse message:", data);
+      return;
+    }
+    if (this.messageQueue.handleMessage(message)) {
+      return;
+    }
+    if (isEventMessage(message)) {
+      this.subscriptionManager.handleEvent(message);
+    }
+  }
+  handleClose(code, reason) {
+    const wasConnected = this._state === "connected";
+    this.cleanup();
+    if (wasConnected) {
+      this.disconnectCallbacks.forEach((cb) => cb());
+    }
+  }
+  handleError(event) {
+    const error = new Error("WebSocket error");
+    this.errorCallbacks.forEach((cb) => cb(error));
+  }
+  // ============================================
+  // Internal: Sending Messages
+  // ============================================
+  send(message) {
+    if (!this.ws || !this.ws.connected) {
+      throw new LarkError("not_connected", "Not connected to database");
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+  /**
+   * @internal Send a set operation.
+   */
+  async _sendSet(path, value, priority) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "s",
+      p: normalizePath(path) || "/",
+      v: value,
+      r: requestId
+    };
+    if (priority !== void 0) {
+      message.y = priority;
+    }
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Send an update operation.
+   */
+  async _sendUpdate(path, values) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "u",
+      p: normalizePath(path) || "/",
+      v: values,
+      r: requestId
+    };
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Send a delete operation.
+   */
+  async _sendDelete(path) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "d",
+      p: normalizePath(path) || "/",
+      r: requestId
+    };
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Send a push operation. Returns the generated key.
+   */
+  async _sendPush(path, value) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "p",
+      p: normalizePath(path) || "/",
+      v: value,
+      r: requestId
+    };
+    this.send(message);
+    const key = await this.messageQueue.registerRequest(requestId);
+    return key;
+  }
+  /**
+   * @internal Send a once (read) operation.
+   */
+  async _sendOnce(path, query) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "o",
+      p: normalizePath(path) || "/",
+      r: requestId
+    };
+    if (query) {
+      message.q = query;
+    }
+    this.send(message);
+    const value = await this.messageQueue.registerRequest(requestId);
+    return new DataSnapshot(value, path, this);
+  }
+  /**
+   * @internal Send an onDisconnect operation.
+   */
+  async _sendOnDisconnect(path, action, value, priority) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "od",
+      p: normalizePath(path) || "/",
+      a: action,
+      r: requestId
+    };
+    if (value !== void 0) {
+      message.v = value;
+    }
+    if (priority !== void 0) {
+      message.y = priority;
+    }
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Send a subscribe message to server.
+   */
+  async sendSubscribeMessage(path, eventTypes) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "sb",
+      p: normalizePath(path) || "/",
+      e: eventTypes,
+      r: requestId
+    };
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Send an unsubscribe message to server.
+   */
+  async sendUnsubscribeMessage(path) {
+    const requestId = this.messageQueue.nextRequestId();
+    const message = {
+      o: "us",
+      p: normalizePath(path) || "/",
+      r: requestId
+    };
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  /**
+   * @internal Create a DataSnapshot from event data.
+   */
+  createSnapshot(path, value, volatile) {
+    return new DataSnapshot(value, path, this, { volatile });
+  }
+  // ============================================
+  // Internal: Subscription Management
+  // ============================================
+  /**
+   * @internal Subscribe to events at a path.
+   */
+  _subscribe(path, eventType, callback) {
+    return this.subscriptionManager.subscribe(path, eventType, callback);
+  }
+  /**
+   * @internal Unsubscribe from a specific event type at a path.
+   */
+  _unsubscribeEventType(path, eventType) {
+    this.subscriptionManager.unsubscribeEventType(path, eventType);
+  }
+  /**
+   * @internal Unsubscribe from all events at a path.
+   */
+  _unsubscribeAll(path) {
+    this.subscriptionManager.unsubscribeAll(path);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataSnapshot,
+  DatabaseReference,
+  LarkDatabase,
+  LarkError,
+  OnDisconnect,
+  generatePushId
+});
+//# sourceMappingURL=index.js.map