@liveblocks/core 1.1.7 → 1.2.0-comments

package/dist/index.d.ts

@@ -5,6 +5,19 @@
 declare function detectDupes(pkgName: string, pkgVersion: string | false, // false if not built yet
 pkgFormat: string | false): void;
 
+declare type CustomAuthenticationResult = {
+    token: string;
+    error?: never;
+} | {
+    token?: never;
+    error: "forbidden";
+    reason: string;
+} | {
+    token?: never;
+    error: string;
+    reason: string;
+};
+
 /**
  * Represents an indefinitely deep arbitrary JSON data structure. There are
  * four types that make up the Json family:
@@ -25,6 +38,239 @@ declare function isJsonScalar(data: Json): data is JsonScalar;
 declare function isJsonArray(data: Json): data is JsonArray;
 declare function isJsonObject(data: Json): data is JsonObject;
 
+declare enum Permission {
+    Read = "room:read",
+    Write = "room:write",
+    PresenceWrite = "room:presence:write",
+    CommentsWrite = "comments:write",
+    CommentsRead = "comments:read"
+}
+declare type LiveblocksPermissions = Record<string, Permission[]>;
+declare enum TokenKind {
+    SECRET_LEGACY = "sec-legacy",
+    ACCESS_TOKEN = "acc",
+    ID_TOKEN = "id"
+}
+declare type JwtMeta = {
+    iat: number;
+    exp: number;
+};
+/**
+ * Legacy Secret Token.
+ */
+declare type LegacySecretToken = {
+    k: TokenKind.SECRET_LEGACY;
+    roomId: string;
+    scopes: string[];
+    id?: string;
+    info?: Json;
+    [other: string]: Json | undefined;
+} & JwtMeta;
+/**
+ * New authorization Access Token.
+ */
+declare type AccessToken = {
+    k: TokenKind.ACCESS_TOKEN;
+    pid: string;
+    uid: string;
+    perms: LiveblocksPermissions;
+    ui?: Json;
+} & JwtMeta;
+/**
+ * New authorization ID Token.
+ */
+declare type IDToken = {
+    k: TokenKind.ID_TOKEN;
+    pid: string;
+    uid: string;
+    gids?: string[];
+    ui?: Json;
+} & JwtMeta;
+declare type AuthToken = AccessToken | IDToken | LegacySecretToken;
+declare type ParsedAuthToken = {
+    readonly raw: string;
+    readonly parsed: AuthToken;
+};
+
+declare type Callback<T> = (event: T) => void;
+declare type UnsubscribeCallback = () => void;
+declare type Observable<T> = {
+    /**
+     * Register a callback function to be called whenever the event source emits
+     * an event.
+     */
+    subscribe(callback: Callback<T>): UnsubscribeCallback;
+    /**
+     * Register a one-time callback function to be called whenever the event
+     * source emits an event. After the event fires, the callback is
+     * auto-unsubscribed.
+     */
+    subscribeOnce(callback: Callback<T>): UnsubscribeCallback;
+    /**
+     * Returns a promise that will resolve when an event is emitted by this
+     * event source. Optionally, specify a predicate that has to match. The first
+     * event matching that predicate will then resolve the promise.
+     */
+    waitUntil(predicate?: (event: T) => boolean): Promise<T>;
+};
+declare type EventSource<T> = Observable<T> & {
+    /**
+     * Notify all subscribers about the event.
+     */
+    notify(event: T): void;
+    /**
+     * Clear all registered event listeners. None of the registered functions
+     * will ever get called again. Be careful when using this API, because the
+     * subscribers may not have any idea they won't be notified anymore.
+     */
+    clear(): void;
+    /**
+     * Returns the number of active subscribers.
+     */
+    count(): number;
+    /**
+     * Pauses event delivery until unpaused. Any .notify() calls made while
+     * paused will get buffered into memory and emitted later.
+     */
+    pause(): void;
+    /**
+     * Emits all in-memory buffered events, and unpauses. Any .notify() calls
+     * made after this will be synchronously delivered again.
+     */
+    unpause(): void;
+    /**
+     * Observable instance, which can be used to subscribe to this event source
+     * in a readonly fashion. Safe to publicly expose.
+     */
+    observable: Observable<T>;
+};
+/**
+ * makeEventSource allows you to generate a subscribe/notify pair of functions
+ * to make subscribing easy and to get notified about events.
+ *
+ * The events are anonymous, so you can use it to define events, like so:
+ *
+ *   const event1 = makeEventSource();
+ *   const event2 = makeEventSource();
+ *
+ *   event1.subscribe(foo);
+ *   event1.subscribe(bar);
+ *   event2.subscribe(qux);
+ *
+ *   // Unsubscription is pretty standard
+ *   const unsub = event2.subscribe(foo);
+ *   unsub();
+ *
+ *   event1.notify();  // Now foo and bar will get called
+ *   event2.notify();  // Now qux will get called (but foo will not, since it's unsubscribed)
+ *
+ */
+declare function makeEventSource<T>(): EventSource<T>;
+
+interface IWebSocketEvent {
+    type: string;
+}
+interface IWebSocketCloseEvent extends IWebSocketEvent {
+    readonly code: number;
+    readonly wasClean: boolean;
+    readonly reason: string;
+}
+interface IWebSocketMessageEvent extends IWebSocketEvent {
+    readonly data: string | Buffer | ArrayBuffer | readonly Buffer[];
+}
+interface IWebSocketInstance {
+    readonly CONNECTING: number;
+    readonly OPEN: number;
+    readonly CLOSING: number;
+    readonly CLOSED: number;
+    readonly readyState: number;
+    addEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
+    addEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
+    addEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
+    removeEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
+    removeEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
+    removeEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
+    close(): void;
+    send(data: string): void;
+}
+/**
+ * Either the browser-based WebSocket API or Node.js' WebSocket API (from the
+ * 'ws' package).
+ *
+ * This type defines the minimal WebSocket API that Liveblocks needs from
+ * a WebSocket implementation, and is a minimal subset of the browser-based
+ * WebSocket APIs and Node.js' WebSocket API so that both implementations are
+ * assignable to this type.
+ */
+interface IWebSocket {
+    new (address: string): IWebSocketInstance;
+}
+/**
+ * The following ranges will be respected by the client:
+ *
+ *   40xx: client will disconnect
+ *   41xx: client will reauthorize
+ *   42xx: client will retry without reauthorizing (currently not used)
+ *
+ */
+declare enum WebsocketCloseCodes {
+    /** Unexpected error happened with the network/infra level. In spirit akin to HTTP 503 */
+    CLOSE_ABNORMAL = 1006,
+    /** Unexpected error happened. In spirit akin to HTTP 500 */
+    UNEXPECTED_CONDITION = 1011,
+    /** Please back off for now, but try again in a few moments */
+    TRY_AGAIN_LATER = 1013,
+    /** Message wasn't understood, disconnect */
+    INVALID_MESSAGE_FORMAT = 4000,
+    /** Server refused to allow connection. Re-authorizing won't help. Disconnect. In spirit akin to HTTP 403 */
+    NOT_ALLOWED = 4001,
+    /** Unused */
+    MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
+    /** Unused */
+    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
+    /** Unused */
+    MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
+    /** Room is full, disconnect */
+    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
+    /** The auth token is expired, reauthorize to get a fresh one. In spirit akin to HTTP 401 */
+    TOKEN_EXPIRED = 4109,
+    /** Disconnect immediately */
+    CLOSE_WITHOUT_RETRY = 4999
+}
+
+/**
+ * Old connection statuses, here for backward-compatibility reasons only.
+ */
+declare type LegacyConnectionStatus = "closed" | "authenticating" | "connecting" | "open" | "unavailable" | "failed";
+/**
+ * Returns a human-readable status indicating the current connection status of
+ * a Room, as returned by `room.getStatus()`. Can be used to implement
+ * a connection status badge.
+ */
+declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
+/**
+ * Used to report about app-level reconnection issues.
+ *
+ * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
+ * the application will only get an event if the reconnection attempts by the
+ * client are taking (much) longer than usual. Definitely a situation you want
+ * to inform your users about, for example, by throwing a toast message on
+ * screen, or show a "trying to reconnect" banner.
+ */
+declare type LostConnectionEvent = "lost" | "restored" | "failed";
+/**
+ * Arbitrary record that will be used as the authentication "authValue". It's the
+ * value that is returned by calling the authentication delegate, and will get
+ * passed to the connection factory delegate. This value will be remembered by
+ * the connection manager, but its value will not be interpreted, so it can be
+ * any value (except null).
+ */
+declare type BaseAuthResult = NonNullable<Json>;
+declare type Delegates<T extends BaseAuthResult> = {
+    authenticate: () => Promise<T>;
+    createSocket: (authValue: T) => IWebSocketInstance;
+};
+
 declare enum OpCode {
     INIT = 0,
     SET_PARENT_KEY = 1,
@@ -193,55 +439,6 @@ declare type PlainLsonList = {
 };
 declare type PlainLson = PlainLsonObject | PlainLsonMap | PlainLsonList | Json;
 
-declare type LiveObjectUpdateDelta<O extends {
-    [key: string]: unknown;
-}> = {
-    [K in keyof O]?: UpdateDelta | undefined;
-};
-/**
- * A LiveObject notification that is sent in-client to any subscribers whenever
- * one or more of the entries inside the LiveObject instance have changed.
- */
-declare type LiveObjectUpdates<TData extends LsonObject> = {
-    type: "LiveObject";
-    node: LiveObject<TData>;
-    updates: LiveObjectUpdateDelta<TData>;
-};
-/**
- * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
- * Keys should be a string, and values should be serializable to JSON.
- * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
- */
-declare class LiveObject<O extends LsonObject> extends AbstractCrdt {
-    constructor(obj?: O);
-    /**
-     * Transform the LiveObject into a javascript object
-     */
-    toObject(): O;
-    /**
-     * Adds or updates a property with a specified key and a value.
-     * @param key The key of the property to add
-     * @param value The value of the property to add
-     */
-    set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
-    /**
-     * Returns a specified property from the LiveObject.
-     * @param key The key of the property to get
-     */
-    get<TKey extends keyof O>(key: TKey): O[TKey];
-    /**
-     * Deletes a key from the LiveObject
-     * @param key The key of the property to delete
-     */
-    delete(key: keyof O): void;
-    /**
-     * Adds or updates multiple properties at once with an object.
-     * @param patch The object used to overrides properties
-     */
-    update(patch: Partial<O>): void;
-    toImmutable(): ToImmutable<O>;
-}
-
 /**
  * Helper type to convert any valid Lson type to the equivalent Json type.
  *
@@ -531,6 +728,55 @@ declare type ToJson<T extends Lson | LsonObject> = T extends Json ? T : T extend
     [K in KS]: ToJson<V>;
 } : never;
 
+declare type LiveObjectUpdateDelta<O extends {
+    [key: string]: unknown;
+}> = {
+    [K in keyof O]?: UpdateDelta | undefined;
+};
+/**
+ * A LiveObject notification that is sent in-client to any subscribers whenever
+ * one or more of the entries inside the LiveObject instance have changed.
+ */
+declare type LiveObjectUpdates<TData extends LsonObject> = {
+    type: "LiveObject";
+    node: LiveObject<TData>;
+    updates: LiveObjectUpdateDelta<TData>;
+};
+/**
+ * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
+ * Keys should be a string, and values should be serializable to JSON.
+ * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
+ */
+declare class LiveObject<O extends LsonObject> extends AbstractCrdt {
+    constructor(obj?: O);
+    /**
+     * Transform the LiveObject into a javascript object
+     */
+    toObject(): O;
+    /**
+     * Adds or updates a property with a specified key and a value.
+     * @param key The key of the property to add
+     * @param value The value of the property to add
+     */
+    set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
+    /**
+     * Returns a specified property from the LiveObject.
+     * @param key The key of the property to get
+     */
+    get<TKey extends keyof O>(key: TKey): O[TKey];
+    /**
+     * Deletes a key from the LiveObject
+     * @param key The key of the property to delete
+     */
+    delete(key: keyof O): void;
+    /**
+     * Adds or updates multiple properties at once with an object.
+     * @param patch The object used to overrides properties
+     */
+    update(patch: Partial<O>): void;
+    toImmutable(): ToImmutable<O>;
+}
+
 /**
  * This helper type is effectively a no-op, but will force TypeScript to
  * "evaluate" any named helper types in its definition. This can sometimes make
@@ -572,110 +818,6 @@ declare type BaseUserMeta = {
     info?: Json;
 };
 
-declare type Callback<T> = (event: T) => void;
-declare type UnsubscribeCallback = () => void;
-declare type Observable<T> = {
-    /**
-     * Register a callback function to be called whenever the event source emits
-     * an event.
-     */
-    subscribe(callback: Callback<T>): UnsubscribeCallback;
-    /**
-     * Register a one-time callback function to be called whenever the event
-     * source emits an event. After the event fires, the callback is
-     * auto-unsubscribed.
-     */
-    subscribeOnce(callback: Callback<T>): UnsubscribeCallback;
-    /**
-     * Returns a promise that will resolve when an event is emitted by this
-     * event source. Optionally, specify a predicate that has to match. The first
-     * event matching that predicate will then resolve the promise.
-     */
-    waitUntil(predicate?: (event: T) => boolean): Promise<T>;
-};
-
-interface IWebSocketEvent {
-    type: string;
-}
-interface IWebSocketCloseEvent extends IWebSocketEvent {
-    readonly code: number;
-    readonly wasClean: boolean;
-    readonly reason: string;
-}
-interface IWebSocketMessageEvent extends IWebSocketEvent {
-    readonly data: string | Buffer | ArrayBuffer | readonly Buffer[];
-}
-interface IWebSocketInstance {
-    readonly CONNECTING: number;
-    readonly OPEN: number;
-    readonly CLOSING: number;
-    readonly CLOSED: number;
-    readonly readyState: number;
-    addEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
-    addEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
-    addEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
-    removeEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
-    removeEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
-    removeEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
-    close(): void;
-    send(data: string): void;
-}
-/**
- * Either the browser-based WebSocket API or Node.js' WebSocket API (from the
- * 'ws' package).
- *
- * This type defines the minimal WebSocket API that Liveblocks needs from
- * a WebSocket implementation, and is a minimal subset of the browser-based
- * WebSocket APIs and Node.js' WebSocket API so that both implementations are
- * assignable to this type.
- */
-interface IWebSocket {
-    new (address: string): IWebSocketInstance;
-}
-declare enum WebsocketCloseCodes {
-    CLOSE_ABNORMAL = 1006,
-    INVALID_MESSAGE_FORMAT = 4000,
-    NOT_ALLOWED = 4001,
-    MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
-    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
-    MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
-    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
-    CLOSE_WITHOUT_RETRY = 4999
-}
-
-/**
- * Old connection statuses, here for backward-compatibility reasons only.
- */
-declare type LegacyConnectionStatus = "closed" | "authenticating" | "connecting" | "open" | "unavailable" | "failed";
-/**
- * Returns a human-readable status indicating the current connection status of
- * a Room, as returned by `room.getStatus()`. Can be used to implement
- * a connection status badge.
- */
-declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
-/**
- * Used to report about app-level reconnection issues.
- *
- * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
- * the application will only get an event if the reconnection attempts by the
- * client are taking (much) longer than usual. Definitely a situation you want
- * to inform your users about, for example, by throwing a toast message on
- * screen, or show a "trying to reconnect" banner.
- */
-declare type LostConnectionEvent = "lost" | "restored" | "failed";
-/**
- * Arbitrary record that will be used as the authentication "token". It's the
- * value that is returned by calling the authentication delegate, and will get
- * passed to the connection factory delegate. This value will be remembered by
- * the connection manager, but its value will not be interpreted, so it can be
- * any value (except null).
- */
-declare type BaseAuthResult = NonNullable<Json>;
-declare type Delegates<T extends BaseAuthResult> = {
-    authenticate: () => Promise<T>;
-    createSocket: (token: T) => IWebSocketInstance;
-};
-
 declare type IdTuple<T> = [id: string, value: T];
 declare enum CrdtType {
     OBJECT = 0,
@@ -801,7 +943,7 @@ declare type UserJoinServerMsg<TUserMeta extends BaseUserMeta> = {
      */
     readonly info: TUserMeta["info"];
     /**
-     * Permissions that the user has in the Room.
+     * Informs the client what (public) permissions this (other) User has.
      */
     readonly scopes: string[];
 };
@@ -845,8 +987,18 @@ declare type BroadcastedEventServerMsg<TRoomEvent extends Json> = {
  */
 declare type RoomStateServerMsg<TUserMeta extends BaseUserMeta> = {
     readonly type: ServerMsgCode.ROOM_STATE;
+    /**
+     * Informs the client what their actor ID is going to be.
+     * @since v1.2 (WS API v7)
+     */
+    readonly actor: number;
+    /**
+     * Informs the client what permissions the current User (self) has.
+     * @since v1.2 (WS API v7)
+     */
+    readonly scopes: string[];
     readonly users: {
-        readonly [actor: number]: TUserMeta & {
+        readonly [otherActor: number]: TUserMeta & {
             scopes: string[];
         };
     };
@@ -916,9 +1068,16 @@ declare type User<TPresence extends JsonObject, TUserMeta extends BaseUserMeta>
      */
     readonly presence: TPresence;
     /**
-     * False if the user can modify the room storage, true otherwise.
+     * @deprecated Use `!user.canWrite` instead.
+     * False if the user can mutate the Room’s Storage and/or YDoc, true if they
+     * can only read but not mutate it.
      */
     readonly isReadOnly: boolean;
+    /**
+     * True if the user can mutate the Room’s Storage and/or YDoc, false if they
+     * can only read but not mutate it.
+     */
+    readonly canWrite: boolean;
 };
 
 /**
@@ -1191,11 +1350,6 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      * The id of the room.
      */
     readonly id: string;
-    /**
-     * A client is considered "self aware" if it knows its own
-     * metadata and connection ID (from the auth server).
-     */
-    isSelfAware(): boolean;
     /**
      * @deprecated This API will be removed in a future version of Liveblocks.
      * Prefer using `.getStatus()` instead.
@@ -1311,6 +1465,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      */
     getStorageSnapshot(): LiveObject<TStorage> | null;
     readonly events: {
+        /** @deprecated Prefer `status` instead. */
         readonly connection: Observable<LegacyConnectionStatus>;
         readonly status: Observable<Status>;
         readonly lostConnection: Observable<LostConnectionEvent>;
@@ -1389,6 +1544,51 @@ declare type RoomInitializers<TPresence extends JsonObject, TStorage extends Lso
     shouldInitiallyConnect?: boolean;
 }>;
 
+declare type AuthValue = {
+    type: "secret";
+    token: ParsedAuthToken;
+} | {
+    type: "public";
+    publicApiKey: string;
+};
+declare type RequestedScope = "room:read" | "comments:read";
+declare type AuthManager = {
+    getAuthValue(requestedScope: RequestedScope, roomId: string): Promise<AuthValue>;
+};
+
+declare type BaseThreadRealtimeEvent = {
+    roomId: string;
+    threadId: string;
+};
+declare type BaseCommentRealtimeEvent = BaseThreadRealtimeEvent & {
+    commentId: string;
+};
+declare type ThreadCreatedRealtimeEvent = BaseThreadRealtimeEvent & {
+    type: "threadCreated";
+};
+declare type ThreadUpdatedRealtimeEvent = BaseThreadRealtimeEvent & {
+    type: "threadUpdated";
+};
+declare type ThreadDeletedRealtimeEvent = BaseThreadRealtimeEvent & {
+    type: "threadDeleted";
+};
+declare type CommentCreatedRealtimeEvent = BaseCommentRealtimeEvent & {
+    type: "commentCreated";
+};
+declare type CommentUpdatedRealtimeEvent = BaseCommentRealtimeEvent & {
+    type: "commentEdited";
+};
+declare type CommentDeletedRealtimeEvent = BaseCommentRealtimeEvent & {
+    type: "commentDeleted";
+};
+declare type RealtimeEvent = ThreadCreatedRealtimeEvent | ThreadUpdatedRealtimeEvent | ThreadDeletedRealtimeEvent | CommentCreatedRealtimeEvent | CommentUpdatedRealtimeEvent | CommentDeletedRealtimeEvent;
+
+declare type RealtimeClient = {
+    subscribeToEvents: (roomId: string, callback: Callback<RealtimeEvent>) => UnsubscribeCallback;
+    error: Observable<Error>;
+    connection: Observable<Status>;
+};
+
 declare type EnterOptions<TPresence extends JsonObject, TStorage extends LsonObject> = Resolve<RoomInitializers<TPresence, TStorage> & {
     /**
      * Only necessary when you’re using Liveblocks with React v17 or lower.
@@ -1401,6 +1601,10 @@ declare type EnterOptions<TPresence extends JsonObject, TStorage extends LsonObj
     unstable_batchedUpdates?: (cb: () => void) => void;
 }>;
 declare type Client = {
+    __internal: {
+        getAuthValue: AuthManager["getAuthValue"];
+        realtimeClient: RealtimeClient;
+    };
     /**
      * Gets a room. Returns null if {@link Client.enter} has not been called previously.
      *
@@ -1419,9 +1623,7 @@ declare type Client = {
      */
     leave(roomId: string): void;
 };
-declare type AuthEndpoint = string | ((room: string) => Promise<{
-    token: string;
-}>);
+declare type AuthEndpoint = string | ((room: string) => Promise<CustomAuthenticationResult>);
 /**
  * The authentication endpoint that is called to ensure that the current user has access to a room.
  * Can be an url or a callback if you need to add additional headers.
@@ -1522,6 +1724,93 @@ declare function assert(condition: boolean, errmsg: string): asserts condition;
  */
 declare function nn<T>(value: T, errmsg?: string): NonNullable<T>;
 
+declare type AsyncFunction<T, A extends any[] = any[]> = (...args: A) => Promise<T>;
+declare type AsyncCacheOptions<T, E> = {
+    isStateEqual?: (a: AsyncState<T, E>, b: AsyncState<T, E>) => boolean;
+};
+declare type AsyncStateInitial = {
+    readonly isLoading: false;
+    readonly data?: never;
+    readonly error?: never;
+};
+declare type AsyncStateLoading<T> = {
+    readonly isLoading: true;
+    readonly data?: T;
+    readonly error?: never;
+};
+declare type AsyncStateSuccess<T> = {
+    readonly isLoading: false;
+    readonly data: T;
+    readonly error?: never;
+};
+declare type AsyncStateError<T, E> = {
+    readonly isLoading: false;
+    readonly data?: T;
+    readonly error: E;
+};
+declare type AsyncState<T, E> = AsyncStateInitial | AsyncStateLoading<T> | AsyncStateSuccess<T> | AsyncStateError<T, E>;
+declare type AsyncStateResolved<T, E> = AsyncStateSuccess<T> | AsyncStateError<T, E>;
+declare type AsyncCacheItem<T, E> = Observable<AsyncState<T, E>> & {
+    setAsyncFunction(asyncFunction: AsyncFunction<T, [string]>): void;
+    get(): Promise<AsyncStateResolved<T, E>>;
+    getState(): AsyncState<T, E>;
+    revalidate(): Promise<AsyncStateResolved<T, E>>;
+};
+declare type AsyncCache<T, E> = {
+    /**
+     * @private
+     *
+     * Creates a key in the cache.
+     *
+     * @param key The key to create.
+     * @param asyncFunction Override the cache's function for this key.
+     */
+    create(key: string, asyncFunction?: AsyncFunction<T, [string]>): AsyncCacheItem<T, E>;
+    /**
+     * Returns a promise which resolves with the state of the key.
+     *
+     * @param key The key to get.
+     */
+    get(key: string): Promise<AsyncStateResolved<T, E>>;
+    /**
+     * Returns the current state of the key synchronously.
+     *
+     * @param key The key to get the state of.
+     */
+    getState(key: string): AsyncState<T, E> | undefined;
+    /**
+     * Revalidates the key.
+     *
+     * @param key The key to revalidate.
+     */
+    revalidate(key: string): Promise<AsyncStateResolved<T, E>>;
+    /**
+     * Subscribes to the key's changes.
+     *
+     * @param key The key to subscribe to.
+     * @param callback The function invoked on every change.
+     */
+    subscribe(key: string, callback: Callback<AsyncState<T, E>>): UnsubscribeCallback;
+    /**
+     * Subscribes to the key's changes once.
+     *
+     * @param key The key to subscribe to.
+     * @param callback The function invoked on every change.
+     */
+    subscribeOnce(key: string, callback: Callback<AsyncState<T, E>>): UnsubscribeCallback;
+    /**
+     * Returns whether a key already exists in the cache.
+     *
+     * @param key The key to look for.
+     */
+    has(key: string): boolean;
+    /**
+     * Clears all keys.
+     */
+    clear(): void;
+};
+declare function createAsyncCache<T, E>(asyncFunction: AsyncFunction<T, [string]>, options?: AsyncCacheOptions<T, E>): AsyncCache<T, E>;
+
 /**
  * Displays a deprecation warning in the dev console. Only in dev mode, and
  * only once per message/key. In production, this is a no-op.
@@ -1548,12 +1837,39 @@ declare function throwUsageError(message: string): void;
  */
 declare function errorIf(condition: unknown, message: string): void;
 
+declare const warn: (message: string, ...args: readonly unknown[]) => void;
+declare const error: (message: string, ...args: readonly unknown[]) => void;
+declare const warnWithTitle: (title: string, message: string, ...args: readonly unknown[]) => void;
+declare const errorWithTitle: (title: string, message: string, ...args: readonly unknown[]) => void;
+
+declare const fancyConsole_warn: typeof warn;
+declare const fancyConsole_error: typeof error;
+declare const fancyConsole_warnWithTitle: typeof warnWithTitle;
+declare const fancyConsole_errorWithTitle: typeof errorWithTitle;
+declare namespace fancyConsole {
+  export {
+    fancyConsole_warn as warn,
+    fancyConsole_error as error,
+    fancyConsole_warnWithTitle as warnWithTitle,
+    fancyConsole_errorWithTitle as errorWithTitle,
+  };
+}
+
 /**
  * Freezes the given argument, but only in development builds. In production
  * builds, this is a no-op for performance reasons.
  */
 declare const freeze: typeof Object.freeze;
 
+declare type Poller = {
+    start(interval: number): void;
+    restart(interval: number): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+};
+declare function makePoller(callback: () => void): Poller;
+
 declare const brand: unique symbol;
 declare type Brand<T, TBrand extends string> = T & {
     [brand]: TBrand;
@@ -1653,19 +1969,6 @@ declare function asPos(str: string): Pos;
  */
 declare function shallow(a: unknown, b: unknown): boolean;
 
-declare type CustomAuthenticationResult = {
-    token: string;
-    error?: never;
-} | {
-    token?: never;
-    error: "forbidden";
-    reason: string;
-} | {
-    token?: never;
-    error: string;
-    reason: string;
-};
-
 declare enum ClientMsgCode {
     UPDATE_PRESENCE = 100,
     BROADCAST_EVENT = 103,
@@ -1887,6 +2190,103 @@ declare namespace protocol {
   };
 }
 
+declare type BaseMetadata = Record<string, string | boolean | number>;
+
+declare type CommentBodyBlockElement = CommentBodyParagraph;
+declare type CommentBodyInlineElement = CommentBodyText | CommentBodyMention;
+declare type CommentBodyElement = CommentBodyBlockElement | CommentBodyInlineElement;
+declare type CommentBodyParagraph = {
+    type: "paragraph";
+    children: CommentBodyInlineElement[];
+};
+declare type CommentBodyMention = {
+    type: "mention";
+    userId: string;
+};
+declare type CommentBodyText = {
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    code?: boolean;
+    text: string;
+};
+declare type CommentBody = {
+    version: 1;
+    content: CommentBodyBlockElement[];
+};
+
+declare type CommentData = {
+    type: "comment";
+    id: string;
+    threadId: string;
+    roomId: string;
+    userId: string;
+    createdAt: string;
+    editedAt?: string;
+} & ({
+    body: CommentBody;
+    deletedAt?: never;
+} | {
+    body?: never;
+    deletedAt: string;
+});
+
+declare type ThreadData<ThreadMetadata extends BaseMetadata = never> = {
+    type: "thread";
+    id: string;
+    roomId: string;
+    createdAt: string;
+    updatedAt?: string;
+    comments: CommentData[];
+    metadata: [ThreadMetadata] extends [never] ? Record<string, never> : ThreadMetadata;
+};
+
+declare type Options = {
+    serverEndpoint: string;
+};
+declare type CommentsApi<ThreadMetadata extends BaseMetadata> = {
+    getThreads(options: {
+        roomId: string;
+    }): Promise<ThreadData<ThreadMetadata>[]>;
+    createThread(options: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        metadata: ThreadMetadata | undefined;
+        body: CommentBody;
+    }): Promise<ThreadData<ThreadMetadata>>;
+    editThreadMetadata(options: {
+        roomId: string;
+        metadata: Partial<ThreadMetadata>;
+        threadId: string;
+    }): Promise<ThreadData<ThreadMetadata>>;
+    createComment(options: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        body: CommentBody;
+    }): Promise<CommentData>;
+    editComment(options: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        body: CommentBody;
+    }): Promise<CommentData>;
+    deleteComment(options: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+};
+declare function createCommentsApi<ThreadMetadata extends BaseMetadata>(client: Client, { serverEndpoint }: Options): CommentsApi<ThreadMetadata>;
+
+declare type BaseUserInfo = {
+    name?: string;
+    avatar?: string;
+};
+
+declare function isCommentBodyMention(element: CommentBodyElement): element is CommentBodyMention;
+
 /**
  * Helper type to help users adopt to Lson types from interface definitions.
  * You should only use this to wrap interfaces you don't control. For more
@@ -1899,4 +2299,4 @@ declare type EnsureJson<T> = [
     [K in keyof T]: EnsureJson<T[K]>;
 };
 
-export { AckOp, BaseAuthResult, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, CustomAuthenticationResult, Delegates, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, FetchStorageClientMsg, FetchYDocClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LegacyConnectionStatus, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, LostConnectionEvent, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RejectedStorageOpServerMsg, Resolve, Room, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, Status, StorageStatus, StorageUpdate, ToImmutable, ToJson, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, UpdateYDocClientMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, createClient, deprecate, deprecateIf, detectDupes, errorIf, freeze, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };
+export { AckOp, AsyncCache, AsyncState, AsyncStateError, AsyncStateInitial, AsyncStateLoading, AsyncStateResolved, AsyncStateSuccess, BaseAuthResult, BaseMetadata, BaseUserInfo, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, CommentBody, CommentBodyElement, CommentBodyMention, CommentBodyParagraph, CommentData, CommentsApi, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, CustomAuthenticationResult, Delegates, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, EventSource, FetchStorageClientMsg, FetchYDocClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LegacyConnectionStatus, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, LostConnectionEvent, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RealtimeClient, RejectedStorageOpServerMsg, Resolve, Room, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, Status, StorageStatus, StorageUpdate, ThreadData, ToImmutable, ToJson, UnsubscribeCallback, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, UpdateYDocClientMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, fancyConsole as console, createAsyncCache, createClient, createCommentsApi, deprecate, deprecateIf, detectDupes, errorIf, freeze, isChildCrdt, isCommentBodyMention, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };