@talkjs/core 1.2.0 → 1.4.0

package/dist/talkSession.d.ts

@@ -214,6 +214,92 @@ export declare interface ConversationActiveState {
     latestSnapshot: ConversationSnapshot | null;
 }
 
+/**
+ * The state of a conversation list subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface ConversationListActiveState {
+    type: "active";
+    /**
+     * The most recently received snapshot for the conversations
+     */
+    latestSnapshot: ConversationSnapshot[];
+    /**
+     * True if `latestSnapshot` contains all conversations you are in.
+     * Use {@link ConversationListSubscription.loadMore} to load more.
+     */
+    loadedAll: boolean;
+}
+
+/**
+ * A subscription to your most recently active conversations.
+ *
+ * @remarks
+ * Get a ConversationListSubscription by calling {@link Session.subscribeConversations}.
+ *
+ * The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations.
+ * Conversations are ordered by last activity. The last activity of a conversation is either `joinedAt` or `lastMessage.createdAt`, whichever is higher.
+ *
+ * The window will automatically expand to include any conversations you join, and any old conversations that receive new messages after subscribing.
+ *
+ * You can expand this window by calling {@link ConversationListSubscription.loadMore}, which extends the window further into the past.
+ *
+ * @public
+ */
+export declare interface ConversationListSubscription {
+    /**
+     * 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` and `loadedAll`.
+     *
+     * - `latestSnapshot: ConversationSnapshot[]` the current state of the conversations in the window
+     *
+     * - `loadedAll: boolean` true when `latestSnapshot` contains all the conversations you are in
+     *
+     * When `type` is "error", includes the `error` field. It is a JS `Error` object explaining what caused the subscription to be terminated.
+     */
+    state: PendingState | ConversationListActiveState | 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<ConversationListActiveState>;
+    /**
+     * 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>;
+    /**
+     * Expand the window to include older conversations
+     *
+     * @remarks
+     * Calling `loadMore` multiple times in parallel will still only load one page of conversations.
+     *
+     * @param count - The number of additional conversations to load. Must be between 1 and 30. Default 20.
+     * @returns A promise that resolves once the additional conversations have loaded
+     */
+    loadMore(count?: number): Promise<void>;
+    /**
+     * 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 conversation with a given conversation ID, from the perspective of the current user.
  *
@@ -375,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)
      */
@@ -388,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)
      */
@@ -398,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)
@@ -408,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;
     /**
@@ -1937,6 +2025,24 @@ export declare interface TalkSession {
      * @public
      */
     conversation(id: string): ConversationRef;
+    /**
+     * Subscribes to your most recently active conversations.
+     *
+     * @remarks
+     * The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations.
+     * Conversations are ordered by last activity. The last activity of a conversation is either `joinedAt` or `lastMessage.createdAt`, whichever is higher.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    subscribeConversations(onSnapshot?: (snapshot: ConversationSnapshot[], loadedAll: boolean) => void): ConversationListSubscription;
     /**
      * Upload a generic file without any additional metadata.
      *
@@ -2210,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.
  *
@@ -2262,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;
 }
 
 /**