@talkjs/core 1.8.2 → 1.9.0

package/dist/talkSession.d.ts

@@ -1358,29 +1358,38 @@ export declare interface MessageRef {
      * Get a reference to a specific emoji reaction on this message
      *
      * @remarks
-     * If you call `.reaction` with an invalid emoji, it will still succeed and you will still get a `ReactionRef`.
+     * If you call `.reactions` with an invalid emoji, it will still succeed and you will still get a `ReactionRef`.
      * However, the TalkJS server will reject any calls that use an invalid emoji.
      *
-     * Calling this method multiple times with the same emoji reuses the same {@link ReactionRef} object.
-     *
-     * In the future, this will also be used to fetch a full list of people who used that specific reaction on the message.
+     * Calling this method multiple times with the same emoji reuses the same {@link ReactionsRef} object.
      *
      * @example Reacting to the message with a Unicode emoji
      * ```ts
-     * MessageRef.reaction("🚀").add()
+     * MessageRef.reactions("🚀").add()
      * ```
      *
      * @example Removing your custom emoji reaction from the message
      * ```ts
-     * MessageRef.reaction(":cat-roomba:").remove()
+     * MessageRef.reactions(":cat-roomba:").remove()
+     * ```
+     *
+     * @example Subscribing to the list of users who reacted with a specific emoji
+     * ```ts
+     * MessageRef.reactions("🚀").subscribe(snapshots => console.log(snapshots))
      * ```
      *
      * @param emoji - The emoji for the reaction you want to reference. a single Unicode emoji like "🚀" or a custom emoji like ":cat_roomba:". Custom emoji can be up to 50 characters long.
-     * @returns A {@link ReactionRef} for the reaction with that emoji on this message
+     * @returns A {@link ReactionsRef} for the reactions with that emoji on this message
      * @throws If the emoji is not a string or is an empty string
      * @public
      */
-    reaction(emoji: string): ReactionRef;
+    reactions(emoji: string): ReactionsRef;
+    /**
+     * Get a reference to a specific emoji reaction on this message
+     *
+     * @deprecated This has been renamed to {@link MessageRef.reactions}. For back-compat, this method will continue to be available as an alias.
+     */
+    reaction(emoji: string): ReactionsRef;
     /**
      * Fetches a snapshot of the message.
      *
@@ -1515,17 +1524,21 @@ export declare interface MessageSnapshot {
      */
     readonly referencedMessage: ReferencedMessageSnapshot | null;
     /**
-     * Where this message originated from:
+     * Specifies how this message was created.
+     *
+     * - "rest" = Message sent normally, via one of the UI components, the Data API, or the REST API
      *
-     * - "web" = Message sent via the UI or via {@link ConversationBuilder.sendMessage}
+     * - "import" = Message sent via the admin REST API's "import messages" endpoint
      *
-     * - "rest" = Message sent via the REST API's "send message" endpoint or {@link ConversationRef.send}
+     * - "email" = Message sent as a reply to an email notification
      *
-     * - "import" = Message sent via the REST API's "import messages" endpoint
+     * - "web" = Message sent using a classic SDK
      *
-     * - "email" = Message sent by replying to an email notification
+     * To track more detailed information about where a message comes from, such as browser vs mobile app, use message custom data.
+     *
+     * The "rest" and "web" values are confusingly named. This is for historical reasons and to maintain backwards compatibility.
      */
-    readonly origin: "web" | "rest" | "import" | "email";
+    readonly origin: "rest" | "import" | "email" | "web";
     /**
      * The contents of the message, as a plain text string without any formatting or attachments.
      * Useful for showing in a conversation list or in notifications.
@@ -1536,12 +1549,13 @@ export declare interface MessageSnapshot {
      */
     readonly content: ContentBlock[];
     /**
-     * All the emoji reactions that have been added to this message.
+     * A summary of the emoji reactions that have been added to this message.
      *
      * @remarks
-     * There can be up to 50 different reactions on each message.
+     * Each message can have up to 50 unique emoji used for reactions.
+     * They are sorted in the order they were first added to the message, starting with the oldest.
      */
-    readonly reactions: ReactionSnapshot[];
+    readonly reactions: ReactionsSummarySnapshot[];
 }
 
 /**
@@ -1597,9 +1611,9 @@ export declare interface MessageSubscription {
      * Expand the window to include older messages
      *
      * @remarks
-     * The `count` parameter is relative to the current number of loaded participants.
+     * The `count` parameter is relative to the current number of loaded messages.
      * If you call `loadMore(5)` and then call `loadMore(10)` immediately afterwards (without awaiting the promise),
-     * then only 10 additional participants will be loaded, not 15.
+     * then only 10 additional messages will be loaded, not 15.
      *
      * Avoid calling `.loadMore` in a loop until you have loaded all messages.
      * If you do need to call loadMore in a loop, make sure you set an upper bound (e.g. 1000) on the number of messages, where the loop will exit.
@@ -1801,9 +1815,9 @@ export declare interface ParticipantSubscription {
      * Expand the window to include older participants
      *
      * @remarks
-     * The `count` parameter is relative to the current number of loaded messages.
+     * The `count` parameter is relative to the current number of loaded participants.
      * If you call `loadMore(5)` and then call `loadMore(10)` immediately afterwards (without awaiting the promise),
-     * then only 10 additional messages will be loaded, not 15.
+     * then only 10 additional participants will be loaded, not 15.
      *
      * Avoid calling `.loadMore` in a loop until you have loaded all participants.
      * If you do need to call loadMore in a loop, make sure you set a small upper bound (e.g. 100) on the number of participants, where the loop will exit.
@@ -1831,17 +1845,54 @@ export declare interface PendingState {
 }
 
 /**
- * References a specific emoji reaction on a message.
+ * References all the reactions on a message using a specific emoji.
+ *
+ * @deprecated This has been renamed to {@link ReactionsRef}. For back-compat, this will continue to be available as an alias.
+ *
+ * @public
+ */
+export declare type ReactionRef = ReactionsRef;
+
+/**
+ * The state of a user reaction list subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface ReactionsActiveState {
+    readonly type: "active";
+    /**
+     * The most recently received snapshot for the participants, or `null` if you are not a participant in that conversation.
+     */
+    readonly latestSnapshot: SingleReactionSnapshot[] | null;
+    /**
+     * True if `latestSnapshot` contains all users who used this reaction.
+     * Use {@link ReactionsSubscription.loadMore} to load more.
+     */
+    readonly loadedAll: boolean;
+}
+
+/**
+ * A summary of the reactions to a message using a specific emoji.
+ *
+ * @deprecated This has been renamed to {@link ReactionsSummarySnapshot}. For back-compat, this will continue to be available as an alias.
+ *
+ * @public
+ */
+export declare type ReactionSnapshot = ReactionsSummarySnapshot;
+
+/**
+ * References all the reactions on a message using a specific emoji.
  *
  * @remarks
- * Used in all Data API operations affecting that emoji reaction, such as adding or removing the reaction.
- * Created via {@link MessageRef.reaction}.
+ * Used in all Data API operations affecting reactions with this emoji.
+ * This includes mutating *your* reaction with `.add` and `.remove`, as well as fetching information about the aggregate state using `getFirstReactions` and `.subscribe`.
+ * Created via {@link MessageRef.reactions}.
  *
  * @public
  */
-export declare interface ReactionRef {
+export declare interface ReactionsRef {
     /**
-     * Which emoji the reaction is using.
+     * Which emoji the reactions use.
      *
      * @remarks
      * Either a single Unicode emoji, or the name of a custom emoji with a colon at the start and end.
@@ -1861,36 +1912,127 @@ export declare interface ReactionRef {
      * The ID of the message that this is a reaction to.
      *
      * @remarks
-     * Immutable: if you want to react to a different message, get a new ReactionRef instead.
+     * Immutable: if you want reactions for a different message, get a new ReactionRef instead.
      */
     readonly messageId: string;
     /**
      * The ID of the conversation the message belongs to.
      *
      * @remarks
-     * Immutable: if you want to reference a message from a different conversation, get a new MessageRef from that conversation and call `.reaction` on that MessageRef.
+     * Immutable: if you want reactions for a message in a different conversation, get a new MessageRef from that conversation and call `.reactions` on that MessageRef.
      */
     readonly conversationId: string;
     /**
-     * Adds this emoji reaction onto the message, from the current user.
+     * React with this emoji reaction, as the current user.
      *
-     * @returns A promise that resolves when the operation completes. The promise will reject if the request is invalid, the message doesn't exist, there are already 50 different reactions on this message, or if you do not have permission to use emoji reactions on that message.
+     * @returns A promise that resolves when the operation completes. The promise will reject if the request is invalid, the message doesn't exist, there are already 50 different reactions on this message, or if you do not have permission to use emoji reactions on that message. The promise will resolve with no effect if you have already reacted with this emoji.
      */
     add(): Promise<void>;
     /**
-     * Removes this emoji reaction from the message, from the current user.
+     * Un-react with this emoji reaction, as the current user.
      *
-     * @returns A promise that resolves when the operation completes. The promise will reject if the request is invalid, the message doesn't exist, or you do not have permission to use emoji reactions on that message.
+     * @returns A promise that resolves when the operation completes. The promise will reject if the request is invalid, the message doesn't exist, or you do not have permission to use emoji reactions on that message. The promise will resolve with no effect if you have not reacted with this emoji.
      */
     remove(): Promise<void>;
+    /**
+     * Lists the first 10 users who added this reaction to the message.
+     *
+     * @remarks
+     * If more than 10 users added this reaction to the message, only the first 10 users will be returned.
+     *
+     * To load more than 10 users, and to get real-time updates when users add or remove reactions, use {@link subscribe} instead.
+     *
+     * @returns The first 10 users, or `null` if the message doesn't exist or is inaccessible to you.
+     */
+    getFirstReactions(): Promise<SingleReactionSnapshot[] | null>;
+    /**
+     * Subscribe to the list of users who have added this reaction to the message
+     */
+    subscribe(onSnapshot?: (snapshot: SingleReactionSnapshot[] | null, loadedAll: boolean) => void): ReactionsSubscription;
+}
+
+/**
+ * A subscription to the users who have reacted with a specific emoji on a specific message.
+ *
+ * @remarks
+ * Get a ReactionsSubscription by calling {@link ReactionsRef.subscribe}
+ *
+ * The subscription is 'windowed'. It includes all reactions up to a certain point in time.
+ * By default, you subscribe to the 10 oldest reactions.
+ *
+ * You can expand this window to load newer reactions by calling {@link ReactionsSubscription.loadMore}, which extends the window further into the future.
+ *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
+ * @public
+ */
+export declare interface ReactionsSubscription {
+    /**
+     * 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: SingleReactionSnapshot[] | null` the current state of who used this reaction, or null if the message does not exist, or if you're not a participant in the conversation
+     *
+     * - `loadedAll: boolean` true when `latestSnapshot` contains all the users who added this reaction to the message
+     *
+     * When `type` is "error", includes the `error` field. It is a JS `Error` object explaining what caused the subscription to be terminated.
+     */
+    state: PendingState | ReactionsActiveState | 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.
+     */
+    readonly connected: Promise<ReactionsActiveState>;
+    /**
+     * 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>;
+    /**
+     * Expand the window to include people who added the reaction later
+     *
+     * @remarks
+     * The `count` parameter is relative to the current number of loaded users.
+     * If you call `loadMore(5)` and then call `loadMore(10)` immediately afterwards (without awaiting the promise),
+     * then only 10 additional users will be loaded, not 15.
+     *
+     * Avoid calling `.loadMore` in a loop until you have loaded all users.
+     * If you do need to call loadMore in a loop, make sure you set an upper bound (e.g. 1000) on the number of users, where the loop will exit.
+     *
+     * @param count - The number of additional users to load. Must be between 1 and 100. Default 30.
+     * @returns A promise that resolves once the additional users 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;
 }
 
 /**
- * A summary of a single emoji reaction on a message.
+ * A summary of the reactions to a message using a specific emoji.
+ *
+ * @remarks
+ * To see who reacted with a given emoji, or to add a reaction yourself, get a {@link ReactionsRef} using {@link MessageRef.reactions}.
  *
  * @public
  */
-export declare interface ReactionSnapshot {
+export declare interface ReactionsSummarySnapshot {
     /**
      * Which emoji the users reacted with.
      *
@@ -1913,7 +2055,7 @@ export declare interface ReactionSnapshot {
      * const sent = "👍"
      *
      * // React with thumbs up,
-     * await message.reaction(emoji).add()
+     * await message.reactions(emoji).add()
      *
      * // Fetch the reaction
      * const snapshot = await message.get();
@@ -1992,17 +2134,21 @@ export declare interface ReferencedMessageSnapshot {
      */
     readonly referencedMessageId: string | null;
     /**
-     * Where this message originated from:
+     * Specifies how this message was created.
      *
-     * - "web" = Message sent via the UI or via {@link ConversationBuilder.sendMessage}
+     * - "rest" = Message sent normally, via one of the UI components, the Data API, or the REST API
      *
-     * - "rest" = Message sent via the REST API's "send message" endpoint or {@link ConversationRef.send}
+     * - "import" = Message sent via the admin REST API's "import messages" endpoint
      *
-     * - "import" = Message sent via the REST API's "import messages" endpoint
+     * - "email" = Message sent as a reply to an email notification
      *
-     * - "email" = Message sent by replying to an email notification
+     * - "web" = Message sent using a classic SDK
+     *
+     * To track more detailed information about where a message comes from, such as browser vs mobile app, use message custom data.
+     *
+     * The "rest" and "web" values are confusingly named. This is for historical reasons and to maintain backwards compatibility.
      */
-    readonly origin: "web" | "rest" | "import" | "email";
+    readonly origin: "rest" | "import" | "email" | "web";
     /**
      * The contents of the message, as a plain text string without any formatting or attachments.
      * Useful for showing in a conversation list or in notifications.
@@ -2015,7 +2161,7 @@ export declare interface ReferencedMessageSnapshot {
     /**
      * All the emoji reactions that have been added to this message.
      */
-    readonly reactions: ReactionSnapshot[];
+    readonly reactions: ReactionsSummarySnapshot[];
 }
 
 export declare function registerPolyfills({ WebSocket }: {
@@ -2354,6 +2500,25 @@ export declare interface SingleParticipantSubscription {
     unsubscribe(): void;
 }
 
+/**
+ * A snapshot of a user's reaction to a message.
+ *
+ * @remarks
+ * Returned from {@link ReactionsRef.getFirstReactions} and {@link ReactionsRef.subscribe}
+ *
+ * @public
+ */
+export declare interface SingleReactionSnapshot {
+    /**
+     * Which user added the reaction
+     */
+    readonly user: UserSnapshot;
+    /**
+     * The timestamp of when the user added this reaction to the message
+     */
+    readonly createdAt: number;
+}
+
 export declare type Subscription = {
     unsubscribe: () => void;
 };
@@ -2706,7 +2871,7 @@ export declare interface TalkSessionOptions {
  * }
  * ```
  *
- * Rather than relying the automatic message parsing, you can also specify the `TextBlock` directly using {@link ConversationRef.send} with {@link SendMessageParams}.
+ * Rather than relying on the automatic message parsing, you can also specify the `TextBlock` directly using {@link ConversationRef.send} with {@link SendMessageParams}.
  *
  * @public
  */
@@ -3083,8 +3248,16 @@ export declare interface UserSnapshot {
      * The default message a person sees when starting a chat with this user
      *
      * @remarks
-     * Welcome messages are rendered in the UI as messages, but they are not real messages.
-     * This means they do not appear when you list messages using the REST API or JS Data API, and you cannot reply or react to them.
+     * Welcome messages are rendered in the UI as messages, but they are not real
+     * messages. This means they do not appear when you list messages using the
+     * REST API or JS Data API, and you cannot reply or react to them.
+     *
+     * Note: User welcome messages are only supported by the Classic SDKs, and in
+     * the Components-based SDKs, this field is ignored. To show welcome messages
+     * in the Components-based SDK, see
+     * {@link https://talkjs.com/docs/Guides/React/Welcome_Messages/ | Welcome Messages}.
+     *
+     * @deprecated
      */
     readonly welcomeMessage: string | null;
 }
@@ -3211,7 +3384,7 @@ export declare interface VideoFileMetadata {
  * Includes metadata about the duration of the recording in seconds, where available.
  *
  * Voice recordings done in the TalkJS UI will always include the duration.
- * Voice recording that you upload with the REST API or {@link Session.uploadVoice} will include this metadata if you specified it when uploading.
+ * Voice recordings that you upload with the REST API or {@link Session.uploadVoice} will include this metadata if you specified it when uploading.
  *
  * Voice recordings will never be taken from a reply to an email notification.
  * Any attached audio file will become an {@link AudioBlock} instead of a voice block.