@liveblocks/core 1.2.1 → 1.2.2-comments1

package/dist/index.d.mts

@@ -570,6 +570,11 @@ declare type CustomAuthenticationResult = {
     reason: string;
 };
 
+declare type BaseUserInfo = {
+    [key: string]: Json | undefined;
+    name?: string;
+    avatar?: string;
+};
 /**
  * This type is used by clients to define the metadata for a user.
  */
@@ -582,9 +587,162 @@ declare type BaseUserMeta = {
     /**
      * Additional user information that has been set in the authentication endpoint.
      */
-    info?: Json;
+    info?: BaseUserInfo;
+};
+
+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?: BaseUserInfo;
+    [other: string]: Json | undefined;
+} & JwtMeta;
+/**
+ * New authorization Access Token.
+ */
+declare type AccessToken = {
+    k: TokenKind.ACCESS_TOKEN;
+    pid: string;
+    uid: string;
+    perms: LiveblocksPermissions;
+    ui?: BaseUserInfo;
+} & JwtMeta;
+/**
+ * New authorization ID Token.
+ */
+declare type IDToken = {
+    k: TokenKind.ID_TOKEN;
+    pid: string;
+    uid: string;
+    gids?: string[];
+    ui?: BaseUserInfo;
+} & JwtMeta;
+declare type AuthToken = AccessToken | IDToken | LegacySecretToken;
+declare type ParsedAuthToken = {
+    readonly raw: string;
+    readonly parsed: AuthToken;
+};
+
+declare type AuthValue = {
+    type: "secret";
+    token: ParsedAuthToken;
+} | {
+    type: "public";
+    publicApiKey: string;
+};
+
+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";
+    id: string;
+};
+declare type CommentBodyText = {
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    code?: boolean;
+    text: string;
+};
+declare type CommentBody = {
+    version: 1;
+    content: CommentBodyBlockElement[];
+};
+
+/**
+ * Represents a comment.
+ */
+declare type CommentData = {
+    type: "comment";
+    id: string;
+    threadId: string;
+    roomId: string;
+    userId: string;
+    createdAt: string;
+    editedAt?: string;
+} & ({
+    body: CommentBody;
+    mentionedIds: string[];
+    deletedAt?: never;
+} | {
+    body?: never;
+    mentionedIds: [];
+    deletedAt: string;
+});
+
+/**
+ * Represents a thread of comments.
+ */
+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(): Promise<ThreadData<ThreadMetadata>[]>;
+    createThread(options: {
+        threadId: string;
+        commentId: string;
+        metadata: ThreadMetadata | undefined;
+        body: CommentBody;
+    }): Promise<ThreadData<ThreadMetadata>>;
+    editThreadMetadata(options: {
+        metadata: Partial<ThreadMetadata>;
+        threadId: string;
+    }): Promise<ThreadData<ThreadMetadata>>;
+    createComment(options: {
+        threadId: string;
+        commentId: string;
+        body: CommentBody;
+    }): Promise<CommentData>;
+    editComment(options: {
+        threadId: string;
+        commentId: string;
+        body: CommentBody;
+    }): Promise<CommentData>;
+    deleteComment(options: {
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+};
+declare function createCommentsApi<ThreadMetadata extends BaseMetadata>(roomId: string, getAuthValue: () => Promise<AuthValue>, { serverEndpoint }: Options): CommentsApi<ThreadMetadata>;
+
 declare type Callback<T> = (event: T) => void;
 declare type UnsubscribeCallback = () => void;
 declare type Observable<T> = {
@@ -606,6 +764,59 @@ declare type Observable<T> = {
      */
     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;
@@ -760,12 +971,41 @@ declare enum ServerMsgCode {
     INITIAL_STORAGE_STATE = 200,
     UPDATE_STORAGE = 201,
     REJECT_STORAGE_OP = 299,
-    UPDATE_YDOC = 300
+    UPDATE_YDOC = 300,
+    THREAD_CREATED = 400,
+    THREAD_METADATA_UPDATED = 401,
+    COMMENT_CREATED = 402,
+    COMMENT_EDITED = 403,
+    COMMENT_DELETED = 404
 }
 /**
  * Messages that can be sent from the server to the client.
  */
-declare type ServerMsg<TPresence extends JsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = UpdatePresenceServerMsg<TPresence> | UserJoinServerMsg<TUserMeta> | UserLeftServerMsg | BroadcastedEventServerMsg<TRoomEvent> | RoomStateServerMsg<TUserMeta> | InitialDocumentStateServerMsg | UpdateStorageServerMsg | RejectedStorageOpServerMsg | YDocUpdate;
+declare type ServerMsg<TPresence extends JsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = UpdatePresenceServerMsg<TPresence> | UserJoinServerMsg<TUserMeta> | UserLeftServerMsg | BroadcastedEventServerMsg<TRoomEvent> | RoomStateServerMsg<TUserMeta> | InitialDocumentStateServerMsg | UpdateStorageServerMsg | RejectedStorageOpServerMsg | YDocUpdate | CommentsEventServerMsg;
+declare type CommentsEventServerMsg = ThreadCreatedEvent | ThreadMetadataUpdatedEvent | CommentCreatedEvent | CommentEditedEvent | CommentDeletedEvent;
+declare type ThreadCreatedEvent = {
+    type: ServerMsgCode.THREAD_CREATED;
+    threadId: string;
+};
+declare type ThreadMetadataUpdatedEvent = {
+    type: ServerMsgCode.THREAD_METADATA_UPDATED;
+    threadId: string;
+};
+declare type CommentCreatedEvent = {
+    type: ServerMsgCode.COMMENT_CREATED;
+    threadId: string;
+    commentId: string;
+};
+declare type CommentEditedEvent = {
+    type: ServerMsgCode.COMMENT_EDITED;
+    threadId: string;
+    commentId: string;
+};
+declare type CommentDeletedEvent = {
+    type: ServerMsgCode.COMMENT_DELETED;
+    threadId: string;
+    commentId: string;
+};
 /**
  * Sent by the WebSocket server and broadcasted to all clients to announce that
  * a User updated their presence. For example, when a user moves their cursor.
@@ -856,6 +1096,7 @@ declare type YDocUpdate = {
     readonly type: ServerMsgCode.UPDATE_YDOC;
     readonly update: string;
     readonly isSync: boolean;
+    readonly stateVector: string | null;
 };
 /**
  * Sent by the WebSocket server and broadcasted to all clients to announce that
@@ -971,6 +1212,10 @@ declare type User<TPresence extends JsonObject, TUserMeta extends BaseUserMeta>
      * can only read but not mutate it.
      */
     readonly canWrite: boolean;
+    /**
+     * True if the user can comment on a thread
+     */
+    readonly canComment: boolean;
 };
 
 /**
@@ -1238,7 +1483,7 @@ declare type SubscribeFn<TPresence extends JsonObject, _TStorage extends LsonObj
      */
     (type: "storage-status", listener: Callback<StorageStatus>): () => void;
 };
-declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = {
+declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = CommentsApi<any> & {
     /**
      * The id of the room.
      */
@@ -1383,6 +1628,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
         readonly storageDidLoad: Observable<void>;
         readonly storageStatus: Observable<StorageStatus>;
         readonly ydoc: Observable<YDocUpdate>;
+        readonly comments: Observable<CommentsEventServerMsg>;
     };
     /**
      * Batches modifications made during the given function.
@@ -1568,6 +1814,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.
@@ -1594,12 +1927,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_error: typeof error;
+declare const fancyConsole_errorWithTitle: typeof errorWithTitle;
+declare const fancyConsole_warn: typeof warn;
+declare const fancyConsole_warnWithTitle: typeof warnWithTitle;
+declare namespace fancyConsole {
+  export {
+    fancyConsole_error as error,
+    fancyConsole_errorWithTitle as errorWithTitle,
+    fancyConsole_warn as warn,
+    fancyConsole_warnWithTitle as warnWithTitle,
+  };
+}
+
 /**
  * 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;
@@ -1799,15 +2159,15 @@ declare type TreeNode = LsonTreeNode | UserTreeNode;
 type DevToolsTreeNode_JsonTreeNode = JsonTreeNode;
 type DevToolsTreeNode_LiveTreeNode<TName extends `Live${string}` = `Live${string}`> = LiveTreeNode<TName>;
 type DevToolsTreeNode_LsonTreeNode = LsonTreeNode;
-type DevToolsTreeNode_UserTreeNode = UserTreeNode;
 type DevToolsTreeNode_TreeNode = TreeNode;
+type DevToolsTreeNode_UserTreeNode = UserTreeNode;
 declare namespace DevToolsTreeNode {
   export {
     DevToolsTreeNode_JsonTreeNode as JsonTreeNode,
     DevToolsTreeNode_LiveTreeNode as LiveTreeNode,
     DevToolsTreeNode_LsonTreeNode as LsonTreeNode,
-    DevToolsTreeNode_UserTreeNode as UserTreeNode,
     DevToolsTreeNode_TreeNode as TreeNode,
+    DevToolsTreeNode_UserTreeNode as UserTreeNode,
   };
 }
 
@@ -1907,16 +2267,16 @@ declare type FullClientToPanelMessage = ClientToPanelMessage & {
     source: "liveblocks-devtools-client";
 };
 
-type protocol_PanelToClientMessage = PanelToClientMessage;
 type protocol_ClientToPanelMessage = ClientToPanelMessage;
-type protocol_FullPanelToClientMessage = FullPanelToClientMessage;
 type protocol_FullClientToPanelMessage = FullClientToPanelMessage;
+type protocol_FullPanelToClientMessage = FullPanelToClientMessage;
+type protocol_PanelToClientMessage = PanelToClientMessage;
 declare namespace protocol {
   export {
-    protocol_PanelToClientMessage as PanelToClientMessage,
     protocol_ClientToPanelMessage as ClientToPanelMessage,
-    protocol_FullPanelToClientMessage as FullPanelToClientMessage,
     protocol_FullClientToPanelMessage as FullClientToPanelMessage,
+    protocol_FullPanelToClientMessage as FullPanelToClientMessage,
+    protocol_PanelToClientMessage as PanelToClientMessage,
   };
 }
 
@@ -1932,4 +2292,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, 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, 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, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };