@liveblocks/core 1.2.0-internal6 → 1.2.0

package/dist/index.d.mts

@@ -1,3 +1,10 @@
+/**
+ * Throws an error if multiple copies of a Liveblocks package are being loaded
+ * at runtime. This likely indicates a packaging issue with the project.
+ */
+declare function detectDupes(pkgName: string, pkgVersion: string | false, // false if not built yet
+pkgFormat: string | false): void;
+
 /**
  * Represents an indefinitely deep arbitrary JSON data structure. There are
  * four types that make up the Json family:
@@ -550,6 +557,19 @@ declare type Resolve<T> = T extends (...args: unknown[]) => unknown ? T : {
     [K in keyof T]: T[K];
 };
 
+declare type CustomAuthenticationResult = {
+    token: string;
+    error?: never;
+} | {
+    token?: never;
+    error: "forbidden";
+    reason: string;
+} | {
+    token?: never;
+    error: string;
+    reason: string;
+};
+
 /**
  * This type is used by clients to define the metadata for a user.
  */
@@ -625,14 +645,36 @@ interface IWebSocketInstance {
 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
 }
 
@@ -657,7 +699,7 @@ declare type Status = "initial" | "connecting" | "connected" | "reconnecting" |
  */
 declare type LostConnectionEvent = "lost" | "restored" | "failed";
 /**
- * Arbitrary record that will be used as the authentication "token". It's the
+ * 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
@@ -666,7 +708,7 @@ declare type LostConnectionEvent = "lost" | "restored" | "failed";
 declare type BaseAuthResult = NonNullable<Json>;
 declare type Delegates<T extends BaseAuthResult> = {
     authenticate: () => Promise<T>;
-    createSocket: (token: T) => IWebSocketInstance;
+    createSocket: (authValue: T) => IWebSocketInstance;
 };
 
 declare type IdTuple<T> = [id: string, value: T];
@@ -794,7 +836,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[];
 };
@@ -849,7 +891,7 @@ declare type RoomStateServerMsg<TUserMeta extends BaseUserMeta> = {
      */
     readonly scopes: string[];
     readonly users: {
-        readonly [actor: number]: TUserMeta & {
+        readonly [otherActor: number]: TUserMeta & {
             scopes: string[];
         };
     };
@@ -919,9 +961,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;
 };
 
 /**
@@ -1194,11 +1243,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.
@@ -1314,6 +1358,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>;
@@ -1321,7 +1366,8 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
             connectionId: number;
             event: TRoomEvent;
         }>;
-        readonly me: Observable<TPresence>;
+        readonly self: Observable<User<TPresence, TUserMeta>>;
+        readonly myPresence: Observable<TPresence>;
         readonly others: Observable<{
             others: Others<TPresence, TUserMeta>;
             event: OthersEvent<TPresence, TUserMeta>;
@@ -1421,9 +1467,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.
@@ -1876,19 +1920,6 @@ declare namespace protocol {
   };
 }
 
-/**
- * PRIVATE / INTERNAL APIS
- * -----------------------
- *
- * This module is intended for internal use only, PLEASE DO NOT RELY ON ANY OF
- * THE EXPORTS IN HERE. These are implementation details that can change at any
- * time and without announcement. This module purely exists to share code
- * between the several Liveblocks packages.
- *
- * But since you're so deep inside Liveblocks code... we're hiring!
- * https://join.team/liveblocks ;)
- */
-
 /**
  * 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
@@ -1901,4 +1932,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, 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, errorIf, freeze, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };
+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 };

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Throws an error if multiple copies of a Liveblocks package are being loaded
+ * at runtime. This likely indicates a packaging issue with the project.
+ */
+declare function detectDupes(pkgName: string, pkgVersion: string | false, // false if not built yet
+pkgFormat: string | false): void;
+
 /**
  * Represents an indefinitely deep arbitrary JSON data structure. There are
  * four types that make up the Json family:
@@ -550,6 +557,19 @@ declare type Resolve<T> = T extends (...args: unknown[]) => unknown ? T : {
     [K in keyof T]: T[K];
 };
 
+declare type CustomAuthenticationResult = {
+    token: string;
+    error?: never;
+} | {
+    token?: never;
+    error: "forbidden";
+    reason: string;
+} | {
+    token?: never;
+    error: string;
+    reason: string;
+};
+
 /**
  * This type is used by clients to define the metadata for a user.
  */
@@ -625,14 +645,36 @@ interface IWebSocketInstance {
 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
 }
 
@@ -657,7 +699,7 @@ declare type Status = "initial" | "connecting" | "connected" | "reconnecting" |
  */
 declare type LostConnectionEvent = "lost" | "restored" | "failed";
 /**
- * Arbitrary record that will be used as the authentication "token". It's the
+ * 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
@@ -666,7 +708,7 @@ declare type LostConnectionEvent = "lost" | "restored" | "failed";
 declare type BaseAuthResult = NonNullable<Json>;
 declare type Delegates<T extends BaseAuthResult> = {
     authenticate: () => Promise<T>;
-    createSocket: (token: T) => IWebSocketInstance;
+    createSocket: (authValue: T) => IWebSocketInstance;
 };
 
 declare type IdTuple<T> = [id: string, value: T];
@@ -794,7 +836,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[];
 };
@@ -849,7 +891,7 @@ declare type RoomStateServerMsg<TUserMeta extends BaseUserMeta> = {
      */
     readonly scopes: string[];
     readonly users: {
-        readonly [actor: number]: TUserMeta & {
+        readonly [otherActor: number]: TUserMeta & {
             scopes: string[];
         };
     };
@@ -919,9 +961,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;
 };
 
 /**
@@ -1194,11 +1243,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.
@@ -1314,6 +1358,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>;
@@ -1321,7 +1366,8 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
             connectionId: number;
             event: TRoomEvent;
         }>;
-        readonly me: Observable<TPresence>;
+        readonly self: Observable<User<TPresence, TUserMeta>>;
+        readonly myPresence: Observable<TPresence>;
         readonly others: Observable<{
             others: Others<TPresence, TUserMeta>;
             event: OthersEvent<TPresence, TUserMeta>;
@@ -1421,9 +1467,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.
@@ -1876,19 +1920,6 @@ declare namespace protocol {
   };
 }
 
-/**
- * PRIVATE / INTERNAL APIS
- * -----------------------
- *
- * This module is intended for internal use only, PLEASE DO NOT RELY ON ANY OF
- * THE EXPORTS IN HERE. These are implementation details that can change at any
- * time and without announcement. This module purely exists to share code
- * between the several Liveblocks packages.
- *
- * But since you're so deep inside Liveblocks code... we're hiring!
- * https://join.team/liveblocks ;)
- */
-
 /**
  * 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
@@ -1901,4 +1932,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, 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, errorIf, freeze, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };
+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 };