@talkjs/core 1.3.0 → 1.4.0

package/dist/talkSession.d.ts

@@ -461,8 +461,10 @@ export declare interface ConversationRef {
      * Initially, you will be subscribed to the 30 most recent messages and any new messages.
      * Call `loadMore` to load additional older messages.
      *
-     * Whenever `Subscription.state.type` is "active" and a message is sent, edited, deleted, or you load more messages, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
-     * `loadedAll` is true when the snapshot contains all the messages in the conversation.
+     * While the subscription is active, `onSnapshot` will be called whenever the message snapshots change.
+     * This includes when a message is sent, edited, deleted, and when you load more messages.
+     * It also includes when nested data changes, such as when `snapshot[0].referencedMessage.sender.name` changes.
+     * `loadedAll` is true when `snapshot` contains all the messages in the conversation, and false if you could load more.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
      */
@@ -474,8 +476,10 @@ export declare interface ConversationRef {
      * Initially, you will be subscribed to the 10 participants who joined most recently, and any new participants.
      * Call `loadMore` to load additional older participants.
      *
-     * Whenever `Subscription.state.type` is "active" and a participant is created, edited, deleted, or you load more participants, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
-     * `loadedAll` is true when the snapshot contains all the participants in the conversation.
+     * While the subscription is active, `onSnapshot` will be called whenever the participant snapshots change.
+     * This includes when someone joins or leaves, when their participant attributes are edited, and when you load more participants.
+     * It also includes when nested data changes, such as when `snapshot[0].user.name` changes.
+     * `loadedAll` is true when `snapshot` contains all the participants in the conversation, and false if you could load more.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
      */
@@ -484,7 +488,7 @@ export declare interface ConversationRef {
      * Subscribes to the conversation.
      *
      * @remarks
-     * Whenever `Subscription.state.type` is "active" and something about the conversation changes, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
+     * While the subscription is active, `onSnapshot` will be called when you join or leave the conversation, or when the snapshot changes.
      * This includes changes to nested data. As an extreme example, `onSnapshot` would be called when `snapshot.lastMessage.referencedMessage.sender.name` changes.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
@@ -494,13 +498,11 @@ export declare interface ConversationRef {
      * Subscribes to the typing status of the conversation.
      *
      * @remarks
-     * Whenever `Subscription.state.type` is "active" and the typing status changes, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
-     * This includes changes to nested data, such as when a user who is typing changes their name.
+     * While the subscription is active, `onSnapshot` will be called when you join or leave the conversation, or when the snapshot changes.
+     * This includes changes to the nested `UserSnapshot`s. If one of the people who is typing, changes their name, `onSnapshot` will be called.
+     * You will not be notified when there are already "many" people typing, and another person starts typing, because the snapshot does not change.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
-     *
-     * Note that if there are "many" people typing and another person starts to type, `onSnapshot` will not be called.
-     * This is because your existing {@link ManyTypingSnapshot} is still valid and did not change when the new person started to type.
      */
     subscribeTyping(onSnapshot?: (snapshot: TypingSnapshot | null) => void): TypingSubscription;
     /**
@@ -2033,8 +2035,10 @@ export declare interface TalkSession {
      * If an older conversation receives a new message, or you are added to a conversation, it will appear at the start of the list.
      * Call `loadMore` to load additional older conversations.
      *
-     * Whenever `Subscription.state.type` is "active" and something changes in your conversations, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
-     * `loadedAll` is true when the snapshot contains all your conversations.
+     * While the subscription is active, `onSnapshot` will be called whenever the conversation snapshots change.
+     * This includes when you join or leave a conversation, when the conversation attributes change, and when you load more conversations.
+     * It also includes when nested data changes, such as when `snapshot[0].lastMessage.referencedMessage.sender.name` changes.
+     * `loadedAll` is true when `snapshot` contains all your conversations, and false if you could load more.
      *
      * If the current user does not exist yet, the snapshot will be an empty list.
      */
@@ -2312,6 +2316,97 @@ export declare interface UserActiveState {
     latestSnapshot: UserSnapshot | null;
 }
 
+/**
+ * The state of a user online subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface UserOnlineActiveState {
+    type: "active";
+    /**
+     * The most recently received snapshot
+     */
+    latestSnapshot: UserOnlineSnapshot | null;
+}
+
+/**
+ * A snapshot of a user's online status at a given moment in time.
+ *
+ * @remarks
+ * Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when `oldSnapshot !== newSnapshot`.
+ *
+ * @public
+ */
+export declare interface UserOnlineSnapshot {
+    /**
+     * The user this snapshot relates to
+     */
+    user: UserSnapshot;
+    /**
+     * Whether the user is connected right now
+     *
+     * @remarks
+     * Users are considered connected whenever they have an active websocket connection to the TalkJS servers.
+     * In practice, this means:
+     *
+     * People using the {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/ | JS Data API} are considered connected if they are subscribed to something, or if they sent a request in the last few seconds.
+     * Creating a `TalkSession` is not enough to appear connected.
+     *
+     * People using {@link https://talkjs.com/docs/Reference/Components/ | Components}, are considered connected if they have a UI open.
+     *
+     * People using the {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/ | JavaScript SDK}, {@link https://talkjs.com/docs/Reference/React_SDK/Installation/ | React SDK}, {@link https://talkjs.com/docs/Reference/React_Native_SDK/Installation/ | React Native SDK}, or {@link https://talkjs.com/docs/Reference/Flutter_SDK/Installation/ | Flutter SDK} are considered connected whenever they have an active `Session` object.
+     */
+    isConnected: boolean;
+}
+
+/**
+ * A subscription to the online status of a user
+ *
+ * @remarks
+ * Get a UserOnlineSubscription by calling {@link UserRef.subscribeOnline}.
+ *
+ * @public
+ */
+export declare interface UserOnlineSubscription {
+    /**
+     * The current state of the subscription
+     *
+     * @remarks
+     * An object with the following fields:
+     *
+     * `type` is one of "pending", "active", "unsubscribed", or "error".
+     *
+     * When `type` is "active", includes `latestSnapshot: UserOnlineSnapshot | null`
+     * `null` means the user does not exist.
+     *
+     * When `type` is "error", includes the `error` field. It is a JS `Error` object explaining what caused the subscription to be terminated.
+     */
+    state: PendingState | UserOnlineActiveState | UnsubscribedState | ErrorState;
+    /**
+     * Resolves when the subscription starts receiving updates from the server.
+     *
+     * @remarks
+     * Wait for this promise if you want to perform some action as soon as the subscription is active.
+     *
+     * The promise rejects if the subscription is terminated before it connects.
+     */
+    connected: Promise<UserOnlineActiveState>;
+    /**
+     * Resolves when the subscription permanently stops receiving updates from the server.
+     *
+     * @remarks
+     * This is either because you unsubscribed or because the subscription encountered an unrecoverable error.
+     */
+    terminated: Promise<UnsubscribedState | ErrorState>;
+    /**
+     * Unsubscribe from this resource and stop receiving updates.
+     *
+     * @remarks
+     * If the subscription is already in the "unsubscribed" or "error" state, this is a no-op.
+     */
+    unsubscribe(): void;
+}
+
 /**
  * References the user with a given user ID.
  *
@@ -2364,11 +2459,20 @@ export declare interface UserRef {
      * Subscribe to this user's state.
      *
      * @remarks
-     * Whenever `Subscription.state.type` is "active" and the user is created or their attributes change, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
+     * While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes.
      *
      * @returns A subscription to the user
      */
     subscribe(onSnapshot?: (event: UserSnapshot | null) => void): UserSubscription;
+    /**
+     * Subscribe to this user and their online status.
+     *
+     * @remarks
+     * While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes (including changes to the nested UserSnapshot).
+     *
+     * @returns A subscription to the user's online status
+     */
+    subscribeOnline(onSnapshot?: (event: UserOnlineSnapshot | null) => void): UserOnlineSubscription;
 }
 
 /**