@talkjs/core 1.2.0 → 1.3.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.
  *
@@ -1937,6 +2023,22 @@ 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.
+     *
+     * 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.
+     *
+     * 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.
      *