@lark-sh/client 0.1.11 → 0.1.12

package/dist/index.js

@@ -58,7 +58,8 @@ var ErrorCode = {
   INVALID_OPERATION: "invalid_operation",
   INTERNAL_ERROR: "internal_error",
   CONDITION_FAILED: "condition_failed",
-  INVALID_QUERY: "invalid_query"
+  INVALID_QUERY: "invalid_query",
+  AUTH_REQUIRED: "auth_required"
 };
 var DEFAULT_COORDINATOR_URL = "https://db.lark.sh";
 
@@ -464,6 +465,9 @@ function isAckMessage(msg) {
 function isJoinCompleteMessage(msg) {
   return "jc" in msg;
 }
+function isAuthCompleteMessage(msg) {
+  return "ac" in msg;
+}
 function isNackMessage(msg) {
   return "n" in msg;
 }
@@ -529,6 +533,18 @@ var MessageQueue = class {
         return true;
       }
     }
+    if (isAuthCompleteMessage(message)) {
+      const pending = this.pending.get(message.ac);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.ac);
+        const response = {
+          uid: message.au || null
+        };
+        pending.resolve(response);
+        return true;
+      }
+    }
     if (isAckMessage(message)) {
       const pending = this.pending.get(message.a);
       if (pending) {
@@ -552,7 +568,7 @@ var MessageQueue = class {
       if (pending) {
         clearTimeout(pending.timeout);
         this.pending.delete(message.oc);
-        pending.resolve(message.ov);
+        pending.resolve(message.ov ?? null);
         return true;
       }
     }
@@ -850,7 +866,7 @@ function getNestedValue(obj, path) {
 }
 function getSortValue(value, queryParams) {
   if (!queryParams) {
-    return null;
+    return getNestedValue(value, ".priority");
   }
   if (queryParams.orderBy === "priority") {
     return getNestedValue(value, ".priority");
@@ -865,13 +881,14 @@ function getSortValue(value, queryParams) {
     return null;
   }
   const hasRangeFilter = queryParams.startAt !== void 0 || queryParams.startAfter !== void 0 || queryParams.endAt !== void 0 || queryParams.endBefore !== void 0 || queryParams.equalTo !== void 0;
-  if (hasRangeFilter) {
+  const hasLimit = queryParams.limitToFirst !== void 0 || queryParams.limitToLast !== void 0;
+  if (hasRangeFilter || hasLimit) {
     return getNestedValue(value, ".priority");
   }
   return null;
 }
 function compareEntries(a, b, queryParams) {
-  if (!queryParams || queryParams.orderBy === "key" || !queryParams.orderBy && !queryParams.orderByChild) {
+  if (queryParams?.orderBy === "key") {
     return compareKeys(a.key, b.key);
   }
   const cmp = compareValues(a.sortValue, b.sortValue);
@@ -1329,7 +1346,7 @@ var View = class {
         return { value: displayCache, found: true };
       }
       if (this._hasReceivedInitialSnapshot || this._pendingWriteData.length > 0) {
-        return { value: displayCache, found: true };
+        return { value: displayCache ?? null, found: true };
       }
       return { value: void 0, found: false };
     }
@@ -1337,7 +1354,7 @@ var View = class {
       const relativePath = this.path === "/" ? normalized : normalized.slice(this.path.length);
       if (this._hasReceivedInitialSnapshot || this._pendingWriteData.length > 0) {
         const extractedValue = getValueAtPath(displayCache, relativePath);
-        return { value: extractedValue, found: true };
+        return { value: extractedValue ?? null, found: true };
       }
     }
     return { value: void 0, found: false };
@@ -1430,6 +1447,17 @@ var View = class {
     if (!this.queryParams) return false;
     return !!(this.queryParams.limitToFirst || this.queryParams.limitToLast);
   }
+  /**
+   * Check if this View loads all data (no limits, no range filters).
+   * A View that loads all data can serve as a "complete" cache for child paths.
+   * This matches Firebase's loadsAllData() semantics.
+   */
+  loadsAllData() {
+    if (!this.queryParams) return true;
+    const hasLimit = !!(this.queryParams.limitToFirst || this.queryParams.limitToLast);
+    const hasRangeFilter = this.queryParams.startAt !== void 0 || this.queryParams.endAt !== void 0 || this.queryParams.equalTo !== void 0 || this.queryParams.startAfter !== void 0 || this.queryParams.endBefore !== void 0;
+    return !hasLimit && !hasRangeFilter;
+  }
   // ============================================
   // Pending Writes (for local-first)
   // ============================================
@@ -1602,10 +1630,13 @@ var SubscriptionManager = class {
       this.unsubscribeCallback(normalizedPath, eventType, callback, queryId);
     };
     if (isNewView || isNewEventType || queryParamsChanged) {
-      const allEventTypes = view.getEventTypes();
-      this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0, tag).catch((err) => {
-        console.error("Failed to subscribe:", err);
-      });
+      const hasAncestorComplete = this.hasAncestorCompleteView(normalizedPath);
+      if (!hasAncestorComplete) {
+        const allEventTypes = view.getEventTypes();
+        this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0, tag).catch((err) => {
+          console.error("Failed to subscribe:", err);
+        });
+      }
     }
     if (!isNewView && view.hasReceivedInitialSnapshot) {
       this.fireInitialEventsToCallback(view, eventType, callback);
@@ -1833,18 +1864,23 @@ var SubscriptionManager = class {
     }
   }
   /**
-   * Detect and fire child_moved events for children that changed position.
+   * Detect and fire child_moved events for children that changed position OR sort value.
+   *
+   * Firebase fires child_moved for ANY priority/sort value change, regardless of whether
+   * the position actually changes. This is Case 2003 behavior.
    *
-   * IMPORTANT: child_moved should only fire for children whose VALUE changed
-   * and caused a position change. Children that are merely "displaced" by
-   * another child moving should NOT fire child_moved.
+   * IMPORTANT: child_moved should only fire for children whose VALUE or PRIORITY changed.
+   * Children that are merely "displaced" by another child moving should NOT fire child_moved.
    *
    * @param affectedChildren - Only check these children for moves. If not provided,
    *                           checks all children (for full snapshots where we compare values).
+   * @param previousDisplayCache - Previous display cache for comparing sort values
+   * @param currentDisplayCache - Current display cache for comparing sort values
    */
-  detectAndFireMoves(view, previousOrder, currentOrder, previousPositions, currentPositions, previousChildSet, currentChildSet, childMovedSubs, isVolatile, serverTimestamp, affectedChildren) {
+  detectAndFireMoves(view, previousOrder, currentOrder, previousPositions, currentPositions, previousChildSet, currentChildSet, childMovedSubs, isVolatile, serverTimestamp, affectedChildren, previousDisplayCache, currentDisplayCache) {
     if (childMovedSubs.length === 0) return;
     const childrenToCheck = affectedChildren ?? new Set(currentOrder);
+    const queryParams = view.queryParams;
     for (const key of childrenToCheck) {
       if (!previousChildSet.has(key) || !currentChildSet.has(key)) {
         continue;
@@ -1856,7 +1892,24 @@ var SubscriptionManager = class {
       }
       const oldPrevKey = oldPos > 0 ? previousOrder[oldPos - 1] : null;
       const newPrevKey = newPos > 0 ? currentOrder[newPos - 1] : null;
-      if (oldPrevKey !== newPrevKey) {
+      let positionChanged = oldPrevKey !== newPrevKey;
+      let sortValueChanged = false;
+      let isPriorityOrdering = false;
+      if (previousDisplayCache && currentDisplayCache) {
+        const prevValue = previousDisplayCache[key];
+        const currValue = currentDisplayCache[key];
+        const prevSortValue = getSortValue(prevValue, queryParams);
+        const currSortValue = getSortValue(currValue, queryParams);
+        sortValueChanged = JSON.stringify(prevSortValue) !== JSON.stringify(currSortValue);
+        isPriorityOrdering = !queryParams?.orderBy || queryParams.orderBy === "priority";
+      }
+      let shouldFire;
+      if (affectedChildren) {
+        shouldFire = positionChanged || isPriorityOrdering && sortValueChanged;
+      } else {
+        shouldFire = isPriorityOrdering && sortValueChanged;
+      }
+      if (shouldFire) {
         this.fireChildMoved(view, key, childMovedSubs, newPrevKey, isVolatile, serverTimestamp);
       }
     }
@@ -1900,10 +1953,10 @@ var SubscriptionManager = class {
   /**
    * Fire child_removed callbacks for a child key.
    */
-  fireChildRemoved(view, childKey, subs, isVolatile, serverTimestamp) {
+  fireChildRemoved(view, childKey, subs, isVolatile, serverTimestamp, previousValue) {
     if (subs.length === 0) return;
     const childPath = joinPath(view.path, childKey);
-    const snapshot = this.createSnapshot?.(childPath, null, isVolatile, serverTimestamp);
+    const snapshot = this.createSnapshot?.(childPath, previousValue ?? null, isVolatile, serverTimestamp);
     if (snapshot) {
       for (const entry of subs) {
         try {
@@ -1932,6 +1985,30 @@ var SubscriptionManager = class {
       }
     }
   }
+  /**
+   * Handle subscription revocation due to auth change.
+   * The server has already removed the subscription, so we just clean up locally.
+   * This is different from unsubscribeAll which sends an unsubscribe message.
+   */
+  handleSubscriptionRevoked(path) {
+    const normalizedPath = path;
+    const queryIds = this.pathToQueryIds.get(normalizedPath);
+    if (!queryIds || queryIds.size === 0) return;
+    for (const queryId of queryIds) {
+      const viewKey = this.makeViewKey(normalizedPath, queryId);
+      const view = this.views.get(viewKey);
+      if (view) {
+        const tag = this.viewKeyToTag.get(viewKey);
+        if (tag !== void 0) {
+          this.tagToViewKey.delete(tag);
+          this.viewKeyToTag.delete(viewKey);
+        }
+        view.clear();
+        this.views.delete(viewKey);
+      }
+    }
+    this.pathToQueryIds.delete(normalizedPath);
+  }
   /**
    * Clear all subscriptions (e.g., on disconnect).
    */
@@ -1953,35 +2030,71 @@ var SubscriptionManager = class {
     return queryIds !== void 0 && queryIds.size > 0;
   }
   /**
-   * Check if a path is "covered" by an active subscription.
+   * Check if a path is "covered" by an active subscription that has received data.
    *
    * A path is covered if:
-   * - There's an active 'value' subscription at that exact path, OR
-   * - There's an active 'value' subscription at an ancestor path
+   * - There's an active subscription at that exact path that has data, OR
+   * - There's an active subscription at an ancestor path that has data
+   *
+   * Note: Any subscription type (value, child_added, child_moved, etc.) receives
+   * the initial snapshot from the server and thus has cached data.
    */
   isPathCovered(path) {
     const normalized = normalizePath(path);
-    if (this.hasValueSubscription(normalized)) {
+    if (this.hasActiveSubscriptionWithData(normalized)) {
       return true;
     }
     const segments = normalized.split("/").filter((s) => s.length > 0);
     for (let i = segments.length - 1; i >= 0; i--) {
       const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
-      if (this.hasValueSubscription(ancestorPath)) {
+      if (this.hasActiveSubscriptionWithData(ancestorPath)) {
         return true;
       }
     }
-    if (normalized !== "/" && this.hasValueSubscription("/")) {
+    if (normalized !== "/" && this.hasActiveSubscriptionWithData("/")) {
       return true;
     }
     return false;
   }
   /**
-   * Check if there's a 'value' subscription at a path (any query identifier).
+   * Check if there's an active subscription at a path that has data.
+   * A View has data if it has received the initial snapshot OR has pending writes.
+   * Any subscription type (value, child_added, child_moved, etc.) counts.
    */
-  hasValueSubscription(path) {
+  hasActiveSubscriptionWithData(path) {
     const views = this.getViewsAtPath(path);
-    return views.some((view) => view.hasCallbacksForType("value"));
+    return views.some((view) => view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites()));
+  }
+  /**
+   * Check if any ancestor path has a "complete" View (one that loadsAllData).
+   * A complete View has no limits and no range filters, so it contains all data
+   * for its subtree. Child subscriptions can use the ancestor's data instead
+   * of creating their own server subscription.
+   *
+   * This matches Firebase's behavior where child listeners don't need their own
+   * server subscription if an ancestor has an unlimited listener.
+   */
+  hasAncestorCompleteView(path) {
+    const normalized = normalizePath(path);
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
+      const views = this.getViewsAtPath(ancestorPath);
+      for (const view of views) {
+        if (view.hasCallbacks() && view.loadsAllData() && view.hasReceivedInitialSnapshot) {
+          return true;
+        }
+      }
+    }
+    if (normalized !== "/") {
+      const rootViews = this.getViewsAtPath("/");
+      for (const view of rootViews) {
+        if (view.hasCallbacks() && view.loadsAllData() && view.hasReceivedInitialSnapshot) {
+          return true;
+        }
+      }
+    }
+    return false;
   }
   /**
    * Get a cached value if the path is covered by an active subscription.
@@ -2004,7 +2117,7 @@ var SubscriptionManager = class {
       const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
       const ancestorViews = this.getViewsAtPath(ancestorPath);
       for (const view of ancestorViews) {
-        if (view.hasCallbacksForType("value")) {
+        if (view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites())) {
           const result = view.getCacheValue(normalized);
           if (result.found) {
             return result;
@@ -2015,7 +2128,7 @@ var SubscriptionManager = class {
     if (normalized !== "/") {
       const rootViews = this.getViewsAtPath("/");
       for (const view of rootViews) {
-        if (view.hasCallbacksForType("value")) {
+        if (view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites())) {
           const result = view.getCacheValue(normalized);
           if (result.found) {
             return result;
@@ -2124,8 +2237,11 @@ var SubscriptionManager = class {
     const previousChildSet = new Set(previousOrder);
     const isFirstSnapshot = !view.hasReceivedInitialSnapshot && !view.hasPendingWrites();
     let previousCacheJson = null;
+    let previousDisplayCache = null;
     if (!isVolatile) {
-      previousCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
+      const cache = view.getDisplayCache();
+      previousDisplayCache = cache && typeof cache === "object" && !Array.isArray(cache) ? cache : null;
+      previousCacheJson = this.serializeCacheForComparison(cache);
     }
     const affectedChildren = /* @__PURE__ */ new Set();
     let isFullSnapshot = false;
@@ -2183,7 +2299,8 @@ var SubscriptionManager = class {
       }
       for (const key of previousOrder) {
         if (!currentChildSet.has(key)) {
-          this.fireChildRemoved(view, key, childRemovedSubs, isVolatile, serverTimestamp);
+          const prevValue = previousDisplayCache?.[key];
+          this.fireChildRemoved(view, key, childRemovedSubs, isVolatile, serverTimestamp, prevValue);
         }
       }
     } else {
@@ -2194,7 +2311,8 @@ var SubscriptionManager = class {
           const prevKey = view.getPreviousChildKey(childKey);
           this.fireChildAdded(view, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
         } else if (wasPresent && !isPresent) {
-          this.fireChildRemoved(view, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+          const prevValue = previousDisplayCache?.[childKey];
+          this.fireChildRemoved(view, childKey, childRemovedSubs, isVolatile, serverTimestamp, prevValue);
         } else if (wasPresent && isPresent) {
           const prevKey = view.getPreviousChildKey(childKey);
           this.fireChildChanged(view, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
@@ -2205,6 +2323,8 @@ var SubscriptionManager = class {
     previousOrder.forEach((key, idx) => previousPositions.set(key, idx));
     const currentPositions = /* @__PURE__ */ new Map();
     currentOrder.forEach((key, idx) => currentPositions.set(key, idx));
+    const currentCache = view.getDisplayCache();
+    const currentDisplayCache = currentCache && typeof currentCache === "object" && !Array.isArray(currentCache) ? currentCache : null;
     this.detectAndFireMoves(
       view,
       previousOrder,
@@ -2216,7 +2336,9 @@ var SubscriptionManager = class {
       childMovedSubs,
       isVolatile,
       serverTimestamp,
-      isFullSnapshot ? void 0 : affectedChildren
+      isFullSnapshot ? void 0 : affectedChildren,
+      previousDisplayCache,
+      currentDisplayCache
     );
   }
   // ============================================
@@ -2235,8 +2357,12 @@ var SubscriptionManager = class {
         views.push(view);
       } else if (normalized.startsWith(viewPath + "/")) {
         views.push(view);
+      } else if (viewPath.startsWith(normalized + "/")) {
+        views.push(view);
       } else if (viewPath === "/") {
         views.push(view);
+      } else if (normalized === "/") {
+        views.push(view);
       }
     }
     return views;
@@ -2300,7 +2426,48 @@ var SubscriptionManager = class {
           }
         }
       }
-      this.fireChildEvents(view, previousOrder, previousChildSet, currentOrder, currentChildSet, "/", false, void 0, previousDisplayCache);
+      this.fireChildEventsForAck(view, previousOrder, previousChildSet, currentOrder, currentChildSet, previousDisplayCache);
+    }
+  }
+  /**
+   * Fire child events for ACK handling, skipping child_moved.
+   * This is a variant of fireChildEvents that doesn't fire moves because:
+   * 1. Moves were already fired optimistically
+   * 2. If server modifies data, PUT event will fire correct moves
+   * 3. ACK can arrive before PUT, causing incorrect intermediate state
+   */
+  fireChildEventsForAck(view, previousOrder, previousChildSet, currentOrder, currentChildSet, previousDisplayCache) {
+    const childAddedSubs = view.getCallbacks("child_added");
+    const childChangedSubs = view.getCallbacks("child_changed");
+    const childRemovedSubs = view.getCallbacks("child_removed");
+    if (childAddedSubs.length === 0 && childChangedSubs.length === 0 && childRemovedSubs.length === 0) {
+      return;
+    }
+    const displayCache = view.getDisplayCache();
+    for (const key of currentOrder) {
+      if (!previousChildSet.has(key)) {
+        if (childAddedSubs.length > 0 && displayCache) {
+          const prevKey = view.getPreviousChildKey(key);
+          this.fireChildAdded(view, key, childAddedSubs, prevKey, false, void 0);
+        }
+      } else if (previousDisplayCache && childChangedSubs.length > 0 && displayCache) {
+        const prevValue = previousDisplayCache[key];
+        const currentValue = displayCache[key];
+        const prevJson = this.serializeCacheForComparison(prevValue);
+        const currJson = this.serializeCacheForComparison(currentValue);
+        if (prevJson !== currJson) {
+          const prevKey = view.getPreviousChildKey(key);
+          this.fireChildChanged(view, key, childChangedSubs, prevKey, false, void 0);
+        }
+      }
+    }
+    for (const key of previousOrder) {
+      if (!currentChildSet.has(key)) {
+        if (childRemovedSubs.length > 0) {
+          const prevValue = previousDisplayCache?.[key];
+          this.fireChildRemoved(view, key, childRemovedSubs, false, void 0, prevValue);
+        }
+      }
     }
   }
   /**
@@ -2369,18 +2536,28 @@ var SubscriptionManager = class {
     const updatedViews = [];
     for (const view of affectedViews) {
       let relativePath;
+      let effectiveValue = value;
       if (normalized === view.path) {
         relativePath = "/";
       } else if (view.path === "/") {
         relativePath = normalized;
-      } else {
+      } else if (normalized.startsWith(view.path + "/")) {
         relativePath = normalized.slice(view.path.length);
+      } else if (view.path.startsWith(normalized + "/")) {
+        const pathDiff = view.path.slice(normalized.length);
+        effectiveValue = getValueAtPath(value, pathDiff);
+        if (operation === "update" && effectiveValue === void 0) {
+          continue;
+        }
+        relativePath = "/";
+      } else {
+        continue;
       }
       const previousDisplayCache = view.getDisplayCache();
       const previousOrder = view.orderedChildren;
       const previousChildSet = new Set(previousOrder);
       const previousCacheJson = this.serializeCacheForComparison(previousDisplayCache);
-      view.addPendingWriteData(requestId, relativePath, value, operation);
+      view.addPendingWriteData(requestId, relativePath, effectiveValue, operation);
       const currentOrder = view.orderedChildren;
       const currentChildSet = new Set(currentOrder);
       const currentCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
@@ -2477,7 +2654,8 @@ var SubscriptionManager = class {
       for (const key of previousOrder) {
         if (!currentChildSet.has(key)) {
           if (childRemovedSubs.length > 0) {
-            const snapshot = this.createSnapshot?.(joinPath(view.path, key), null, isVolatile, serverTimestamp);
+            const prevValue = previousDisplayCache?.[key];
+            const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue ?? null, isVolatile, serverTimestamp);
             if (snapshot) {
               for (const entry of childRemovedSubs) {
                 try {
@@ -2491,6 +2669,23 @@ var SubscriptionManager = class {
         }
       }
     } else {
+      if (childRemovedSubs.length > 0) {
+        for (const key of previousOrder) {
+          if (affectedChildren.has(key)) continue;
+          if (currentChildSet.has(key)) continue;
+          const prevValue = previousDisplayCache ? previousDisplayCache[key] : null;
+          const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue, isVolatile, serverTimestamp);
+          if (snapshot) {
+            for (const entry of childRemovedSubs) {
+              try {
+                entry.callback(snapshot, void 0);
+              } catch (err) {
+                console.error("Error in child_removed callback:", err);
+              }
+            }
+          }
+        }
+      }
       for (const key of affectedChildren) {
         const wasPresent = previousChildSet.has(key);
         const isPresent = currentChildSet.has(key);
@@ -2516,7 +2711,8 @@ var SubscriptionManager = class {
           }
         } else if (wasPresent && !isPresent) {
           if (childRemovedSubs.length > 0) {
-            const snapshot = this.createSnapshot?.(joinPath(view.path, key), null, isVolatile, serverTimestamp);
+            const prevValue = previousDisplayCache ? previousDisplayCache[key] : null;
+            const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue, isVolatile, serverTimestamp);
             if (snapshot) {
               for (const entry of childRemovedSubs) {
                 try {
@@ -2549,18 +2745,24 @@ var SubscriptionManager = class {
           }
         }
       }
-      if (childRemovedSubs.length > 0) {
-        for (const key of previousOrder) {
+      if (childAddedSubs.length > 0 && displayCache) {
+        for (const key of currentOrder) {
+          if (previousChildSet.has(key)) continue;
           if (affectedChildren.has(key)) continue;
-          if (currentChildSet.has(key)) continue;
-          const prevValue = previousDisplayCache ? previousDisplayCache[key] : null;
-          const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue, isVolatile, serverTimestamp);
+          const childValue = displayCache[key];
+          const snapshot = this.createSnapshot?.(
+            joinPath(view.path, key),
+            childValue,
+            isVolatile,
+            serverTimestamp
+          );
           if (snapshot) {
-            for (const entry of childRemovedSubs) {
+            const prevKey = view.getPreviousChildKey(key);
+            for (const entry of childAddedSubs) {
               try {
-                entry.callback(snapshot, void 0);
+                entry.callback(snapshot, prevKey);
               } catch (err) {
-                console.error("Error in child_removed callback:", err);
+                console.error("Error in child_added callback:", err);
               }
             }
           }
@@ -2583,7 +2785,9 @@ var SubscriptionManager = class {
         childMovedSubs,
         isVolatile,
         serverTimestamp,
-        isFullSnapshot ? void 0 : affectedChildren
+        isFullSnapshot ? void 0 : affectedChildren,
+        previousDisplayCache,
+        displayCache
       );
     }
   }
@@ -2806,26 +3010,26 @@ var DatabaseReference = class _DatabaseReference {
       queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX] = this._query.orderByChildPath;
     }
     if (this._query.startAt !== void 0) {
-      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAt.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAt.value ?? null;
       if (this._query.startAt.key !== void 0) {
         queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_NAME] = this._query.startAt.key;
       }
       queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_IS_INCLUSIVE] = true;
     } else if (this._query.startAfter !== void 0) {
-      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAfter.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAfter.value ?? null;
       if (this._query.startAfter.key !== void 0) {
         queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_NAME] = this._query.startAfter.key;
       }
       queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_IS_INCLUSIVE] = false;
     }
     if (this._query.endAt !== void 0) {
-      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endAt.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endAt.value ?? null;
       if (this._query.endAt.key !== void 0) {
         queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_NAME] = this._query.endAt.key;
       }
       queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_IS_INCLUSIVE] = true;
     } else if (this._query.endBefore !== void 0) {
-      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endBefore.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endBefore.value ?? null;
       if (this._query.endBefore.key !== void 0) {
         queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_NAME] = this._query.endBefore.key;
       }
@@ -2984,17 +3188,39 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Set the priority of the data at this location.
-   * Fetches current value and sets it with the new priority.
+   * Uses cached value for optimistic behavior (local effects are immediate).
+   * The optimistic update happens synchronously, Promise resolves after server ack.
    */
-  async setPriority(priority) {
+  setPriority(priority) {
     validateNotInfoPath(this._path, "setPriority");
-    const snapshot = await this.once();
-    const currentVal = snapshot.val();
-    if (currentVal === null || currentVal === void 0) {
-      await this._db._sendSet(this._path, { ".priority": priority });
-      return;
+    const { value: cachedValue, found } = this._db._getCachedValue(this._path);
+    if (!found) {
+      return this.once().then((snapshot) => {
+        const actualValue2 = snapshot.val();
+        if (actualValue2 === null || actualValue2 === void 0) {
+          return this._db._sendSet(this._path, { ".priority": priority });
+        }
+        return this.setWithPriority(actualValue2, priority);
+      });
     }
-    await this.setWithPriority(currentVal, priority);
+    let actualValue;
+    if (cachedValue === null || cachedValue === void 0) {
+      actualValue = null;
+    } else if (typeof cachedValue === "object" && !Array.isArray(cachedValue)) {
+      const obj = cachedValue;
+      if (".value" in obj && Object.keys(obj).every((k) => k === ".value" || k === ".priority")) {
+        actualValue = obj[".value"];
+      } else {
+        const { ".priority": _oldPriority, ...rest } = obj;
+        actualValue = Object.keys(rest).length > 0 ? rest : null;
+      }
+    } else {
+      actualValue = cachedValue;
+    }
+    if (actualValue === null || actualValue === void 0) {
+      return this._db._sendSet(this._path, { ".priority": priority });
+    }
+    return this.setWithPriority(actualValue, priority);
   }
   /**
    * Atomically modify the data at this location using optimistic concurrency.
@@ -3065,14 +3291,23 @@ var DatabaseReference = class _DatabaseReference {
   /**
    * Read the data at this location once.
    *
-   * @param eventType - The event type (only 'value' is supported)
+   * For 'value' events, this fetches data directly from the server.
+   * For child events ('child_added', 'child_changed', 'child_removed', 'child_moved'),
+   * this subscribes, waits for the first event, then unsubscribes.
+   *
+   * @param eventType - The event type
    * @returns Promise that resolves to the DataSnapshot
    */
   once(eventType = "value") {
-    if (eventType !== "value") {
-      throw new Error('once() only supports "value" event type');
+    if (eventType === "value") {
+      return this._db._sendOnce(this._path, this._buildQueryParams());
     }
-    return this._db._sendOnce(this._path, this._buildQueryParams());
+    return new Promise((resolve) => {
+      const unsubscribe = this.on(eventType, (snapshot) => {
+        unsubscribe();
+        resolve(snapshot);
+      });
+    });
   }
   // ============================================
   // Subscriptions
@@ -3141,6 +3376,12 @@ var DatabaseReference = class _DatabaseReference {
    */
   orderByChild(path) {
     this._validateNoOrderBy("orderByChild");
+    if (path.startsWith("$") || path.includes("/$")) {
+      throw new LarkError(
+        ErrorCode.INVALID_PATH,
+        `orderByChild: Invalid path '${path}'. Paths cannot contain '$' prefix (reserved for internal use)`
+      );
+    }
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "child",
@@ -3514,35 +3755,35 @@ var DatabaseReference = class _DatabaseReference {
       hasParams = true;
     }
     if (this._query.startAt !== void 0) {
-      params.startAt = this._query.startAt.value;
+      params.startAt = this._query.startAt.value ?? null;
       if (this._query.startAt.key !== void 0) {
         params.startAtKey = this._query.startAt.key;
       }
       hasParams = true;
     }
     if (this._query.startAfter !== void 0) {
-      params.startAfter = this._query.startAfter.value;
+      params.startAfter = this._query.startAfter.value ?? null;
       if (this._query.startAfter.key !== void 0) {
         params.startAfterKey = this._query.startAfter.key;
       }
       hasParams = true;
     }
     if (this._query.endAt !== void 0) {
-      params.endAt = this._query.endAt.value;
+      params.endAt = this._query.endAt.value ?? null;
       if (this._query.endAt.key !== void 0) {
         params.endAtKey = this._query.endAt.key;
       }
       hasParams = true;
     }
     if (this._query.endBefore !== void 0) {
-      params.endBefore = this._query.endBefore.value;
+      params.endBefore = this._query.endBefore.value ?? null;
       if (this._query.endBefore.key !== void 0) {
         params.endBeforeKey = this._query.endBefore.key;
       }
       hasParams = true;
     }
     if (this._query.equalTo !== void 0) {
-      params.equalTo = this._query.equalTo.value;
+      params.equalTo = this._query.equalTo.value ?? null;
       if (this._query.equalTo.key !== void 0) {
         params.equalToKey = this._query.equalTo.key;
       }
@@ -3561,6 +3802,13 @@ var DatabaseReference = class _DatabaseReference {
     }
     return `${baseUrl}${this._path}`;
   }
+  /**
+   * Returns the URL for JSON serialization.
+   * This allows refs to be serialized with JSON.stringify().
+   */
+  toJSON() {
+    return this.toString();
+  }
 };
 var ThenableReference = class extends DatabaseReference {
   constructor(db, path, promise) {
@@ -3581,11 +3829,17 @@ function isWrappedPrimitive(data) {
     return false;
   }
   const keys = Object.keys(data);
-  return keys.length === 2 && ".value" in data && ".priority" in data;
+  if (keys.length === 2 && ".value" in data && ".priority" in data) {
+    return true;
+  }
+  if (keys.length === 1 && ".value" in data) {
+    return true;
+  }
+  return false;
 }
 function stripPriorityMetadata(data) {
   if (data === null || data === void 0) {
-    return data;
+    return null;
   }
   if (typeof data !== "object") {
     return data;
@@ -3648,9 +3902,19 @@ var DataSnapshot = class _DataSnapshot {
   }
   /**
    * Check if data exists at this location (is not null/undefined).
+   * Returns false for priority-only nodes (only .priority, no actual value).
    */
   exists() {
-    return this._data !== null && this._data !== void 0;
+    if (this._data === null || this._data === void 0) {
+      return false;
+    }
+    if (typeof this._data === "object" && !Array.isArray(this._data)) {
+      const keys = Object.keys(this._data);
+      if (keys.length === 1 && keys[0] === ".priority") {
+        return false;
+      }
+    }
+    return true;
   }
   /**
    * Get a child snapshot at the specified path.
@@ -3797,24 +4061,6 @@ var DataSnapshot = class _DataSnapshot {
   }
 };
 
-// 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/utils/volatile.ts
 function isVolatilePath(path, patterns) {
   if (!patterns || patterns.length === 0) {
@@ -3937,6 +4183,11 @@ var LarkDatabase = class {
     this._coordinatorUrl = null;
     this._volatilePaths = [];
     this._transportType = null;
+    // Auth state
+    this._currentToken = null;
+    // Token for auth (empty string = anonymous)
+    this._isAnonymous = false;
+    // True if connected anonymously
     // Reconnection state
     this._connectionId = null;
     this._connectOptions = null;
@@ -3949,8 +4200,12 @@ var LarkDatabase = class {
     this.disconnectCallbacks = /* @__PURE__ */ new Set();
     this.errorCallbacks = /* @__PURE__ */ new Set();
     this.reconnectingCallbacks = /* @__PURE__ */ new Set();
+    this.authStateChangedCallbacks = /* @__PURE__ */ new Set();
     // .info path subscriptions (handled locally, not sent to server)
     this.infoSubscriptions = [];
+    // Authentication promise - resolves when auth completes, allows operations to queue
+    this.authenticationPromise = null;
+    this.authenticationResolve = null;
     this._serverTimeOffset = 0;
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
@@ -3960,10 +4215,11 @@ var LarkDatabase = class {
   // Connection State
   // ============================================
   /**
-   * Whether the database is currently connected.
+   * Whether the database is fully connected and authenticated.
+   * Returns true when ready to perform database operations.
    */
   get connected() {
-    return this._state === "connected";
+    return this._state === "authenticated";
   }
   /**
    * Whether the database is currently attempting to reconnect.
@@ -4048,16 +4304,27 @@ var LarkDatabase = class {
     }
     this._connectOptions = options;
     this._intentionalDisconnect = false;
+    this.authenticationPromise = new Promise((resolve) => {
+      this.authenticationResolve = resolve;
+    });
     await this.performConnect(databaseId, options);
   }
   /**
    * Internal connect implementation used by both initial connect and reconnect.
+   * Implements the Join → Auth flow:
+   * 1. Connect WebSocket
+   * 2. Send join (identifies database)
+   * 3. Send auth (authenticates user - required even for anonymous)
    */
   async performConnect(databaseId, options, isReconnect = false) {
     const previousState = this._state;
     this._state = isReconnect ? "reconnecting" : "connecting";
     this._databaseId = databaseId;
     this._coordinatorUrl = options.coordinator || DEFAULT_COORDINATOR_URL;
+    if (!isReconnect) {
+      this._currentToken = options.token || "";
+      this._isAnonymous = !options.token && options.anonymous !== false;
+    }
     try {
       const coordinatorUrl = this._coordinatorUrl;
       const coordinator = new Coordinator(coordinatorUrl);
@@ -4083,30 +4350,44 @@ var LarkDatabase = class {
       );
       this.transport = transportResult.transport;
       this._transportType = transportResult.type;
-      const requestId = this.messageQueue.nextRequestId();
+      this._state = "connected";
+      const joinRequestId = this.messageQueue.nextRequestId();
       const joinMessage = {
         o: "j",
-        t: connectResponse.token,
-        r: requestId
+        d: databaseId,
+        r: joinRequestId
       };
       if (this._connectionId) {
         joinMessage.pcid = this._connectionId;
       }
       this.send(joinMessage);
-      const joinResponse = await this.messageQueue.registerRequest(requestId);
+      const joinResponse = await this.messageQueue.registerRequest(joinRequestId);
       this._volatilePaths = joinResponse.volatilePaths;
       this._connectionId = joinResponse.connectionId;
       if (joinResponse.serverTime != null) {
         this._serverTimeOffset = joinResponse.serverTime - Date.now();
       }
-      const jwtPayload = decodeJwtPayload(connectResponse.token);
+      this._state = "joined";
+      const authRequestId = this.messageQueue.nextRequestId();
+      const authMessage = {
+        o: "au",
+        t: this._currentToken ?? "",
+        r: authRequestId
+      };
+      this.send(authMessage);
+      const authResponse = await this.messageQueue.registerRequest(authRequestId);
       this._auth = {
-        uid: jwtPayload.sub,
-        provider: jwtPayload.provider,
-        token: jwtPayload.claims || {}
+        uid: authResponse.uid || "",
+        provider: this._isAnonymous ? "anonymous" : "custom",
+        token: {}
+        // Token claims would need to be decoded from the token if needed
       };
-      this._state = "connected";
+      this._state = "authenticated";
       this._reconnectAttempt = 0;
+      if (this.authenticationResolve) {
+        this.authenticationResolve();
+        this.authenticationResolve = null;
+      }
       this.fireConnectionStateChange();
       if (!isReconnect) {
         this.subscriptionManager.initialize({
@@ -4119,6 +4400,7 @@ var LarkDatabase = class {
         await this.restoreAfterReconnect();
       }
       this.connectCallbacks.forEach((cb) => cb());
+      this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
     } catch (error) {
       if (isReconnect) {
         this._state = "reconnecting";
@@ -4131,6 +4413,8 @@ var LarkDatabase = class {
       this._connectOptions = null;
       this._connectionId = null;
       this._transportType = null;
+      this._currentToken = null;
+      this._isAnonymous = false;
       this.transport?.close();
       this.transport = null;
       throw error;
@@ -4144,13 +4428,14 @@ var LarkDatabase = class {
     if (this._state === "disconnected") {
       return;
     }
-    const wasConnected = this._state === "connected";
+    const wasAuthenticated = this._state === "authenticated";
+    const wasPartiallyConnected = this._state === "connected" || this._state === "joined";
     this._intentionalDisconnect = true;
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
     }
-    if (wasConnected && this.transport) {
+    if ((wasAuthenticated || wasPartiallyConnected) && this.transport) {
       try {
         const requestId = this.messageQueue.nextRequestId();
         this.send({ o: "l", r: requestId });
@@ -4162,7 +4447,7 @@ var LarkDatabase = class {
       }
     }
     this.cleanupFull();
-    if (wasConnected) {
+    if (wasAuthenticated || wasPartiallyConnected) {
       this.disconnectCallbacks.forEach((cb) => cb());
     }
   }
@@ -4171,7 +4456,7 @@ var LarkDatabase = class {
    * Disconnects from the server but preserves subscriptions for later reconnection via goOnline().
    */
   goOffline() {
-    if (this._state === "connected" || this._state === "reconnecting") {
+    if (this._state === "authenticated" || this._state === "joined" || this._state === "connected" || this._state === "reconnecting") {
       this._intentionalDisconnect = true;
       if (this._reconnectTimer) {
         clearTimeout(this._reconnectTimer);
@@ -4202,7 +4487,7 @@ var LarkDatabase = class {
    * Used for intentional disconnect.
    */
   cleanupFull() {
-    const wasConnected = this._state === "connected";
+    const wasAuthenticated = this._state === "authenticated";
     this.transport?.close();
     this.transport = null;
     this._state = "disconnected";
@@ -4213,11 +4498,15 @@ var LarkDatabase = class {
     this._connectionId = null;
     this._connectOptions = null;
     this._transportType = null;
+    this._currentToken = null;
+    this._isAnonymous = false;
     this._reconnectAttempt = 0;
+    this.authenticationPromise = null;
+    this.authenticationResolve = null;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
     this.pendingWrites.clear();
-    if (wasConnected) {
+    if (wasAuthenticated) {
       this.fireConnectionStateChange();
     }
     this.infoSubscriptions = [];
@@ -4250,7 +4539,7 @@ var LarkDatabase = class {
   getInfoValue(path) {
     const normalizedPath = normalizePath(path) || "/";
     if (normalizedPath === "/.info/connected") {
-      return this._state === "connected";
+      return this._state === "authenticated";
     }
     if (normalizedPath === "/.info/serverTimeOffset") {
       return this._serverTimeOffset;
@@ -4317,6 +4606,9 @@ var LarkDatabase = class {
     if (this._intentionalDisconnect || !this._databaseId || !this._connectOptions) {
       return;
     }
+    this.authenticationPromise = new Promise((resolve) => {
+      this.authenticationResolve = resolve;
+    });
     try {
       await this.performConnect(this._databaseId, this._connectOptions, true);
     } catch {
@@ -4475,6 +4767,9 @@ var LarkDatabase = class {
    * @internal Send a transaction to the server.
    */
   async _sendTransaction(ops) {
+    if (!this.isAuthenticatedOrThrow()) {
+      if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    }
     const requestId = this.messageQueue.nextRequestId();
     this.pendingWrites.trackWrite(requestId, "transaction", "/", ops);
     const message = {
@@ -4521,6 +4816,76 @@ var LarkDatabase = class {
     this.reconnectingCallbacks.add(callback);
     return () => this.reconnectingCallbacks.delete(callback);
   }
+  /**
+   * Register a callback for auth state changes.
+   * Fires when user signs in, signs out, or auth changes.
+   * Returns an unsubscribe function.
+   */
+  onAuthStateChanged(callback) {
+    this.authStateChangedCallbacks.add(callback);
+    return () => this.authStateChangedCallbacks.delete(callback);
+  }
+  // ============================================
+  // Authentication Management
+  // ============================================
+  /**
+   * Sign in with a new auth token while connected.
+   * Changes the authenticated user without disconnecting.
+   *
+   * Note: Some subscriptions may be revoked if the new user doesn't have
+   * permission. Listen for 'permission_denied' errors on your subscriptions.
+   *
+   * @param token - The auth token for the new user
+   * @throws Error if not connected (must call connect() first)
+   */
+  async signIn(token) {
+    if (this._state !== "authenticated" && this._state !== "joined") {
+      throw new LarkError("not_connected", "Must be connected first - call connect()");
+    }
+    const authRequestId = this.messageQueue.nextRequestId();
+    const authMessage = {
+      o: "au",
+      t: token,
+      r: authRequestId
+    };
+    this.send(authMessage);
+    const authResponse = await this.messageQueue.registerRequest(authRequestId);
+    this._currentToken = token;
+    this._isAnonymous = false;
+    this._auth = {
+      uid: authResponse.uid || "",
+      provider: "custom",
+      token: {}
+    };
+    this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
+  }
+  /**
+   * Sign out the current user.
+   * Reverts to anonymous authentication.
+   *
+   * Note: Some subscriptions may be revoked if anonymous users don't have
+   * permission. Listen for 'permission_denied' errors on your subscriptions.
+   */
+  async signOut() {
+    if (this._state !== "authenticated") {
+      return;
+    }
+    const unauthRequestId = this.messageQueue.nextRequestId();
+    const unauthMessage = {
+      o: "ua",
+      r: unauthRequestId
+    };
+    this.send(unauthMessage);
+    const authResponse = await this.messageQueue.registerRequest(unauthRequestId);
+    this._currentToken = "";
+    this._isAnonymous = true;
+    this._auth = {
+      uid: authResponse.uid || "",
+      provider: "anonymous",
+      token: {}
+    };
+    this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
+  }
   // ============================================
   // Internal: Message Handling
   // ============================================
@@ -4532,6 +4897,9 @@ var LarkDatabase = class {
       console.error("Failed to parse message:", data);
       return;
     }
+    if (process.env.LARK_DEBUG) {
+      console.log("[LARK] <<< SERVER:", JSON.stringify(message, null, 2));
+    }
     if (isPingMessage(message)) {
       this.transport?.send(JSON.stringify({ o: "po" }));
       return;
@@ -4541,6 +4909,12 @@ var LarkDatabase = class {
       this.subscriptionManager.clearPendingWrite(message.a);
     } else if (isNackMessage(message)) {
       this.pendingWrites.onNack(message.n);
+      if (message.e === "permission_denied" && message.sp) {
+        const path = message.sp;
+        console.warn(`Subscription revoked at ${path}: permission_denied`);
+        this.subscriptionManager.handleSubscriptionRevoked(path);
+        return;
+      }
       if (message.e !== "condition_failed") {
         console.error(`Write failed (${message.e}): ${message.m || message.e}`);
       }
@@ -4557,27 +4931,28 @@ var LarkDatabase = class {
     if (this._state === "disconnected") {
       return;
     }
-    const wasConnected = this._state === "connected";
+    const wasAuthenticated = this._state === "authenticated";
     const wasReconnecting = this._state === "reconnecting";
+    const wasPartiallyConnected = this._state === "connected" || this._state === "joined";
     if (this._intentionalDisconnect) {
       this.cleanupFull();
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
       return;
     }
     const canReconnect = this._databaseId && this._connectOptions;
-    if ((wasConnected || wasReconnecting) && canReconnect) {
+    if ((wasAuthenticated || wasPartiallyConnected || wasReconnecting) && canReconnect) {
       this._state = "reconnecting";
       this.cleanupForReconnect();
       this.reconnectingCallbacks.forEach((cb) => cb());
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
       this.scheduleReconnect();
     } else {
       this.cleanupFull();
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
     }
@@ -4588,10 +4963,48 @@ var LarkDatabase = class {
   // ============================================
   // Internal: Sending Messages
   // ============================================
+  /**
+   * Check if authenticated synchronously.
+   * Returns true if authenticated, false if connecting (should wait), throws if disconnected.
+   */
+  isAuthenticatedOrThrow() {
+    if (this._state === "authenticated") {
+      return true;
+    }
+    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
+      return false;
+    }
+    throw new LarkError("not_connected", "Not connected - call connect() first");
+  }
+  /**
+   * Wait for authentication to complete before performing an operation.
+   * If already authenticated, returns immediately (synchronously).
+   * If connecting/reconnecting, waits for auth to complete.
+   * If disconnected and no connect in progress, throws.
+   *
+   * IMPORTANT: This returns a Promise only if waiting is needed.
+   * Callers should use: `if (!this.isAuthenticatedOrThrow()) if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();`
+   * to preserve synchronous execution when already authenticated.
+   */
+  async waitForAuthenticated() {
+    if (this._state === "authenticated") {
+      return;
+    }
+    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
+      if (this.authenticationPromise) {
+        await this.authenticationPromise;
+        return;
+      }
+    }
+    throw new LarkError("not_connected", "Not connected - call connect() first");
+  }
   send(message) {
     if (!this.transport || !this.transport.connected) {
       throw new LarkError("not_connected", "Not connected to database");
     }
+    if (process.env.LARK_DEBUG) {
+      console.log("[LARK] >>> CLIENT:", JSON.stringify(message, null, 2));
+    }
     this.transport.send(JSON.stringify(message));
   }
   /**
@@ -4599,6 +5012,7 @@ var LarkDatabase = class {
    * Note: Priority is now part of the value (as .priority), not a separate field.
    */
   async _sendSet(path, value) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const normalizedPath = normalizePath(path) || "/";
     validateWriteData(value, normalizedPath);
     const requestId = this.messageQueue.nextRequestId();
@@ -4623,6 +5037,7 @@ var LarkDatabase = class {
    * @internal Send an update operation.
    */
   async _sendUpdate(path, values) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const normalizedPath = normalizePath(path) || "/";
     for (const [key, value] of Object.entries(values)) {
       const fullPath = key.startsWith("/") ? key : `${normalizedPath}/${key}`;
@@ -4654,6 +5069,7 @@ var LarkDatabase = class {
    * @internal Send a delete operation.
    */
   async _sendDelete(path) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const normalizedPath = normalizePath(path) || "/";
     const requestId = this.messageQueue.nextRequestId();
     const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
@@ -4689,7 +5105,7 @@ var LarkDatabase = class {
   _sendVolatileSet(path, value) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -4705,7 +5121,7 @@ var LarkDatabase = class {
   _sendVolatileUpdate(path, values) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -4721,7 +5137,7 @@ var LarkDatabase = class {
   _sendVolatileDelete(path) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, "", "delete");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -4760,6 +5176,7 @@ var LarkDatabase = class {
         return new DataSnapshot(cached.value, path, this);
       }
     }
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "o",
@@ -4776,6 +5193,7 @@ var LarkDatabase = class {
    * @internal Send an onDisconnect operation.
    */
   async _sendOnDisconnect(path, action, value) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "od",
@@ -4789,11 +5207,20 @@ var LarkDatabase = class {
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
+  /**
+   * @internal Get a cached value from the subscription manager.
+   * Used for optimistic writes where we need the current value without a network fetch.
+   */
+  _getCachedValue(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    return this.subscriptionManager.getCachedValue(normalizedPath);
+  }
   /**
    * @internal Send a subscribe message to server.
    * Includes tag for non-default queries to enable proper event routing.
    */
   async sendSubscribeMessage(path, eventTypes, queryParams, tag) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "sb",
@@ -4811,6 +5238,7 @@ var LarkDatabase = class {
    * Includes query params and tag so server can identify which specific subscription to remove.
    */
   async sendUnsubscribeMessage(path, queryParams, tag) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "us",