@talkjs/core 1.7.0 → 1.8.0

package/dist/talkSession.d.ts

@@ -1698,6 +1698,17 @@ export declare interface ParticipantRef {
      * @returns A promise that resolves when the operation completes. This promise will reject if client-side conversation syncing is disabled.
      */
     delete(): Promise<void>;
+    /**
+     * Subscribe to this participant's state.
+     *
+     * @remarks
+     * While the subscription is active, `onSnapshot` will be called when the participant joins or leaves the conversation, or their attributes change, including attributes on their user.
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
+     *
+     * @returns A subscription to the participant
+     */
+    subscribe(onSnapshot?: (snapshot: ParticipantSnapshot | null) => void): SingleParticipantSubscription;
 }
 
 /**
@@ -2279,6 +2290,64 @@ export declare interface SetUserParams {
     pushTokens?: Record<string, true | null> | null;
 }
 
+/**
+ * The state of a participant subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface SingleParticipantActiveState {
+    readonly type: "active";
+    /**
+     * The most recently received snapshot for the participant, or `null` if they are not a participant in that conversation.
+     */
+    readonly latestSnapshot: ParticipantSnapshot | null;
+}
+
+/**
+ * A subscription to a specific participant.
+ *
+ * @remarks
+ * Get a SingleParticipantSubscription by calling {@link ParticipantRef.subscribe}
+ *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
+ * @public
+ */
+export declare interface SingleParticipantSubscription {
+    /**
+     * 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: ParticipantSnapshot | null`, the current state of the participant.
+     * `latestSnapshot` is `null` when the user is not a participant or the conversation 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 | SingleParticipantActiveState | UnsubscribedState | ErrorState;
+    /**
+     * Resolves when the subscription starts receiving updates from the server.
+     */
+    readonly connected: Promise<SingleParticipantActiveState>;
+    /**
+     * 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.
+     */
+    readonly 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;
+}
+
 export declare type Subscription = {
     unsubscribe: () => void;
 };
@@ -2439,6 +2508,8 @@ export declare interface TalkSession {
      * Creates a search for messages in all the current user's conversations.
      *
      * @remarks
+     * The search feature is available on the Growth plan or higher. On the Basic plan, this method will return an error.
+     *
      * Search is a two-step process. After calling `searchMessages`, call {@link MessageSearch.setQuery} to specify a search query and begin the search.
      *
      * As search can be quite slow, there are two different ways of using search:
@@ -2480,6 +2551,8 @@ export declare interface TalkSession {
      * Creates a search for all the current user's conversations.
      *
      * @remarks
+     * The search feature is available on the Growth plan or higher. On the Basic plan, this method will return an error.
+     *
      * Search is a two-step process. After calling `searchConversations`, call {@link ConversationSearch.setQuery} to specify a search query and begin the search.
      *
      * As search can be quite slow, there are two different ways of using search: