@lark-sh/client 0.1.11 → 0.1.13

package/dist/index.d.mts

@@ -209,9 +209,10 @@ declare class DatabaseReference {
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
     /**
      * 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.
      */
-    setPriority(priority: number | string): Promise<void>;
+    setPriority(priority: number | string | null): Promise<void>;
     /**
      * Atomically modify the data at this location using optimistic concurrency.
      *
@@ -238,10 +239,14 @@ declare 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'): Promise<DataSnapshot>;
+    once(eventType?: EventType): Promise<DataSnapshot>;
     /**
      * Subscribe to events at this location.
      * Returns an unsubscribe function.
@@ -344,6 +349,11 @@ declare class DatabaseReference {
      * Format: https://db.lark.sh/project/database/path/to/data
      */
     toString(): string;
+    /**
+     * Returns the URL for JSON serialization.
+     * This allows refs to be serialized with JSON.stringify().
+     */
+    toJSON(): string;
 }
 /**
  * A reference that is also a Promise - returned by push().
@@ -462,6 +472,7 @@ declare class DataSnapshot {
     val<T = any>(): T;
     /**
      * Check if data exists at this location (is not null/undefined).
+     * Returns false for priority-only nodes (only .priority, no actual value).
      */
     exists(): boolean;
     /**
@@ -609,7 +620,16 @@ interface TransactionConditionOp {
 type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteOp | TransactionConditionOp;
 /** Object syntax for transactions: path -> value (null = delete) */
 type TransactionObject = Record<string, unknown>;
-type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Connection state machine:
+ * - 'disconnected': Not connected
+ * - 'connecting': Initial connection in progress
+ * - 'connected': WebSocket open
+ * - 'joined': Join complete (database identified)
+ * - 'authenticated': Auth complete (ready to operate)
+ * - 'reconnecting': Attempting to reconnect after disconnect
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'joined' | 'authenticated' | 'reconnecting';
 /**
  * Server values that are resolved by the server when a write is committed.
  * Use these with set(), update(), or push() to have the server fill in values.
@@ -695,6 +715,8 @@ declare class LarkDatabase {
     private _coordinatorUrl;
     private _volatilePaths;
     private _transportType;
+    private _currentToken;
+    private _isAnonymous;
     private _connectionId;
     private _connectOptions;
     private _intentionalDisconnect;
@@ -708,11 +730,15 @@ declare class LarkDatabase {
     private disconnectCallbacks;
     private errorCallbacks;
     private reconnectingCallbacks;
+    private authStateChangedCallbacks;
     private infoSubscriptions;
+    private authenticationPromise;
+    private authenticationResolve;
     private _serverTimeOffset;
     constructor();
     /**
-     * Whether the database is currently connected.
+     * Whether the database is fully connected and authenticated.
+     * Returns true when ready to perform database operations.
      */
     get connected(): boolean;
     /**
@@ -769,6 +795,10 @@ declare class LarkDatabase {
     connect(databaseId: string, options?: ConnectOptions): Promise<void>;
     /**
      * 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)
      */
     private performConnect;
     /**
@@ -901,9 +931,50 @@ declare class LarkDatabase {
      * Returns an unsubscribe function.
      */
     onReconnecting(callback: () => void): () => void;
+    /**
+     * Register a callback for auth state changes.
+     * Fires when user signs in, signs out, or auth changes.
+     * Returns an unsubscribe function.
+     */
+    onAuthStateChanged(callback: (auth: AuthInfo | null) => void): () => void;
+    /**
+     * 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)
+     */
+    signIn(token: string): Promise<void>;
+    /**
+     * 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.
+     */
+    signOut(): Promise<void>;
     private handleMessage;
     private handleClose;
     private handleError;
+    /**
+     * Check if authenticated synchronously.
+     * Returns true if authenticated, false if connecting (should wait), throws if disconnected.
+     */
+    private isAuthenticatedOrThrow;
+    /**
+     * 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.
+     */
+    private waitForAuthenticated;
     private send;
     /**
      * @internal Send a set operation.
@@ -962,6 +1033,14 @@ declare class LarkDatabase {
      * @internal Send an onDisconnect operation.
      */
     _sendOnDisconnect(path: string, action: string, value?: unknown): Promise<void>;
+    /**
+     * @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: string): {
+        value: unknown;
+        found: boolean;
+    };
     /**
      * @internal Send a subscribe message to server.
      * Includes tag for non-default queries to enable proper event routing.

package/dist/index.d.ts

@@ -209,9 +209,10 @@ declare class DatabaseReference {
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
     /**
      * 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.
      */
-    setPriority(priority: number | string): Promise<void>;
+    setPriority(priority: number | string | null): Promise<void>;
     /**
      * Atomically modify the data at this location using optimistic concurrency.
      *
@@ -238,10 +239,14 @@ declare 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'): Promise<DataSnapshot>;
+    once(eventType?: EventType): Promise<DataSnapshot>;
     /**
      * Subscribe to events at this location.
      * Returns an unsubscribe function.
@@ -344,6 +349,11 @@ declare class DatabaseReference {
      * Format: https://db.lark.sh/project/database/path/to/data
      */
     toString(): string;
+    /**
+     * Returns the URL for JSON serialization.
+     * This allows refs to be serialized with JSON.stringify().
+     */
+    toJSON(): string;
 }
 /**
  * A reference that is also a Promise - returned by push().
@@ -462,6 +472,7 @@ declare class DataSnapshot {
     val<T = any>(): T;
     /**
      * Check if data exists at this location (is not null/undefined).
+     * Returns false for priority-only nodes (only .priority, no actual value).
      */
     exists(): boolean;
     /**
@@ -609,7 +620,16 @@ interface TransactionConditionOp {
 type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteOp | TransactionConditionOp;
 /** Object syntax for transactions: path -> value (null = delete) */
 type TransactionObject = Record<string, unknown>;
-type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Connection state machine:
+ * - 'disconnected': Not connected
+ * - 'connecting': Initial connection in progress
+ * - 'connected': WebSocket open
+ * - 'joined': Join complete (database identified)
+ * - 'authenticated': Auth complete (ready to operate)
+ * - 'reconnecting': Attempting to reconnect after disconnect
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'joined' | 'authenticated' | 'reconnecting';
 /**
  * Server values that are resolved by the server when a write is committed.
  * Use these with set(), update(), or push() to have the server fill in values.
@@ -695,6 +715,8 @@ declare class LarkDatabase {
     private _coordinatorUrl;
     private _volatilePaths;
     private _transportType;
+    private _currentToken;
+    private _isAnonymous;
     private _connectionId;
     private _connectOptions;
     private _intentionalDisconnect;
@@ -708,11 +730,15 @@ declare class LarkDatabase {
     private disconnectCallbacks;
     private errorCallbacks;
     private reconnectingCallbacks;
+    private authStateChangedCallbacks;
     private infoSubscriptions;
+    private authenticationPromise;
+    private authenticationResolve;
     private _serverTimeOffset;
     constructor();
     /**
-     * Whether the database is currently connected.
+     * Whether the database is fully connected and authenticated.
+     * Returns true when ready to perform database operations.
      */
     get connected(): boolean;
     /**
@@ -769,6 +795,10 @@ declare class LarkDatabase {
     connect(databaseId: string, options?: ConnectOptions): Promise<void>;
     /**
      * 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)
      */
     private performConnect;
     /**
@@ -901,9 +931,50 @@ declare class LarkDatabase {
      * Returns an unsubscribe function.
      */
     onReconnecting(callback: () => void): () => void;
+    /**
+     * Register a callback for auth state changes.
+     * Fires when user signs in, signs out, or auth changes.
+     * Returns an unsubscribe function.
+     */
+    onAuthStateChanged(callback: (auth: AuthInfo | null) => void): () => void;
+    /**
+     * 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)
+     */
+    signIn(token: string): Promise<void>;
+    /**
+     * 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.
+     */
+    signOut(): Promise<void>;
     private handleMessage;
     private handleClose;
     private handleError;
+    /**
+     * Check if authenticated synchronously.
+     * Returns true if authenticated, false if connecting (should wait), throws if disconnected.
+     */
+    private isAuthenticatedOrThrow;
+    /**
+     * 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.
+     */
+    private waitForAuthenticated;
     private send;
     /**
      * @internal Send a set operation.
@@ -962,6 +1033,14 @@ declare class LarkDatabase {
      * @internal Send an onDisconnect operation.
      */
     _sendOnDisconnect(path: string, action: string, value?: unknown): Promise<void>;
+    /**
+     * @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: string): {
+        value: unknown;
+        found: boolean;
+    };
     /**
      * @internal Send a subscribe message to server.
      * Includes tag for non-default queries to enable proper event routing.