@talkjs/core 1.1.1 → 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.
  *
@@ -381,6 +467,19 @@ export declare interface ConversationRef {
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
      */
     subscribeMessages(onSnapshot?: (snapshot: MessageSnapshot[] | null, loadedAll: boolean) => void): MessageSubscription;
+    /**
+     * Subscribes to the participants in the conversation.
+     *
+     * @remarks
+     * 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.
+     *
+     * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     */
+    subscribeParticipants(onSnapshot?: (snapshot: ParticipantSnapshot[] | null, loadedAll: boolean) => void): ParticipantSubscription;
     /**
      * Subscribes to the conversation.
      *
@@ -1245,7 +1344,7 @@ export declare interface MessageSnapshot {
  * Get a MessageSubscription by calling {@link ConversationRef.subscribeMessages}
  *
  * The subscription is 'windowed'. It includes all messages since a certain point in time.
- * By default, you subscribe to the 30 most recent messages, and any new messages are sent after you subscribe.
+ * By default, you subscribe to the 30 most recent messages, and any new messages that are sent after you subscribe.
  *
  * You can expand this window by calling {@link MessageSubscription.loadMore}, which extends the window further into the past.
  *
@@ -1291,7 +1390,7 @@ export declare interface MessageSubscription {
      * @remarks
      * Calling `loadMore` multiple times in parallel will still only load one page of messages.
      *
-     * @param count - The number of additional messages to load. Must be between 1 and 100
+     * @param count - The number of additional messages to load. Must be between 1 and 100. Default 30.
      * @returns A promise that resolves once the additional messages have loaded
      */
     loadMore(count?: number): Promise<void>;
@@ -1304,6 +1403,24 @@ export declare interface MessageSubscription {
     unsubscribe(): void;
 }
 
+/**
+ * The state of a participants subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface ParticipantActiveState {
+    type: "active";
+    /**
+     * The most recently received snapshot for the participants, or `null` if you are not a participant in that conversation.
+     */
+    latestSnapshot: ParticipantSnapshot[] | null;
+    /**
+     * True if `latestSnapshot` contains all participants in the conversation.
+     * Use {@link ParticipantSubscription.loadMore} to load more.
+     */
+    loadedAll: boolean;
+}
+
 /**
  * References a given user's participation in a conversation.
  *
@@ -1413,6 +1530,72 @@ export declare interface ParticipantSnapshot {
     joinedAt: number;
 }
 
+/**
+ * A subscription to the participants in a specific conversation.
+ *
+ * @remarks
+ * Get a ParticipantSubscription by calling {@link ConversationRef.subscribeParticipants}
+ *
+ * The subscription is 'windowed'. It includes everyone who joined since a certain point in time.
+ * By default, you subscribe to the 10 most recent participants, and any participants who joined after you subscribe.
+ *
+ * You can expand this window by calling {@link ParticipantSubscription.loadMore}, which extends the window further into the past.
+ *
+ * @public
+ */
+export declare interface ParticipantSubscription {
+    /**
+     * 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: ParticipantSnapshot[] | null` the current state of the participants in the window, or null if you're not a participant in the conversation
+     *
+     * - `loadedAll: boolean` true when `latestSnapshot` contains all the participants in the conversation
+     *
+     * When `type` is "error", includes the `error` field. It is a JS `Error` object explaining what caused the subscription to be terminated.
+     */
+    state: PendingState | ParticipantActiveState | 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<ParticipantActiveState>;
+    /**
+     * 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 participants
+     *
+     * @remarks
+     * Calling `loadMore` multiple times in parallel will still only load one page of participants.
+     *
+     * @param count - The number of additional participants to load. Must be between 1 and 50. Default 10.
+     * @returns A promise that resolves once the additional participants 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;
+}
+
 /**
  * The state of a subscription before it has connected to the server
  *
@@ -1840,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.
      *