@talkjs/core 1.4.1 → 1.5.0

package/dist/talkSession.d.ts

@@ -342,6 +342,7 @@ export declare interface ConversationRef {
      *
      * @param user - Specifies which participant in the conversation you want to reference. Either the user's ID, or a reference to that user.
      * @returns A {@linkcode ParticipantRef} for that user's participation in this conversation
+     * @throws If the user is not a UserRef or a non-empty string
      * @public
      */
     participant(user: string | UserRef): ParticipantRef;
@@ -352,8 +353,9 @@ export declare interface ConversationRef {
      * Use this if you need to fetch, delete, or edit a specific message in this conversation, and you know its message ID.
      * To fetch the most recent messages in this conversation, use {@link ConversationRef.subscribeMessages} instead.
      *
-     * @param id - The ID of the user that you want to reference
-     * @returns A {@linkcode UserRef} for the user with that ID
+     * @param id - The ID of the message that you want to reference
+     * @returns A {@linkcode MessageRef} for the message with that ID in this conversation
+     * @throws If the id is not a string or is an empty string
      * @public
      */
     message(id: string): MessageRef;
@@ -701,8 +703,7 @@ export declare interface CreateConversationParams {
      */
     welcomeMessages?: string[];
     /**
-     * Custom metadata you have set on the conversation.
-     * This value acts as a patch. Remove specific properties by setting them to `null`.
+     * Custom metadata to set on the conversation.
      * Default = no custom metadata
      */
     custom?: Record<string, string>;
@@ -812,7 +813,7 @@ export declare interface CreateUserParams {
 export declare interface CustomEmojiNode {
     type: "customEmoji";
     /**
-     * The name of the custom emoji to show.
+     * The name (including colons at the start and end) of the custom emoji to show.
      */
     text: string;
 }
@@ -831,7 +832,7 @@ export declare interface CustomEmojiNode {
  */
 export declare interface EditMessageParams {
     /**
-     * Custom metadata you have set on the message.
+     * Custom metadata to set on the message.
      * This value acts as a patch. Remove specific properties by setting them to `null`.
      * Default = no custom metadata
      */
@@ -860,7 +861,7 @@ export declare interface EditMessageParams {
  */
 export declare interface EditTextMessageParams {
     /**
-     * Custom metadata you have set on the message.
+     * Custom metadata to set on the message.
      * This value acts as a patch. Remove specific properties by setting them to `null`.
      * Default = no custom metadata
      */
@@ -1002,7 +1003,7 @@ export declare interface GenericFileBlock {
     /**
      * Never set for generic file blocks.
      */
-    subtype?: undefined;
+    subtype?: never;
     /**
      * An encoded identifier for this file. Use in {@link SendFileBlock} to send this file in another message.
      */
@@ -1206,7 +1207,7 @@ export declare interface MentionNode {
 export declare interface MessageActiveState {
     type: "active";
     /**
-     * The most recently received snapshot for the user, or `null` if the user does not exist yet.
+     * The most recently received snapshot for the messages, or `null` if you're not a participant in the conversation.
      */
     latestSnapshot: MessageSnapshot[] | null;
     /**
@@ -1240,6 +1241,31 @@ export declare interface MessageRef {
      * Immutable: if you want to reference a message from a different conversation, get a new MessageRef from that conversation.
      */
     readonly conversationId: string;
+    /**
+     * 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`.
+     * However, the TalkJS server will reject any calls that use an invalid emoji.
+     *
+     * In the future, this will also be used to fetch a full list of people who used that specific reaction on the message.
+     *
+     * @example Reacting to the message with a Unicode emoji
+     * ```ts
+     * MessageRef.reaction("🚀").add()
+     * ```
+     *
+     * @example Removing your custom emoji reaction from the message
+     * ```ts
+     * MessageRef.reaction(":cat-roomba:").remove()
+     * ```
+     *
+     * @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 {@linkcode ReactionRef} for the reaction with that emoji on this message
+     * @throws If the emoji is not a string or is an empty string
+     * @public
+     */
+    reaction(emoji: string): ReactionRef;
     /**
      * Fetches a snapshot of the message.
      *
@@ -1256,7 +1282,7 @@ export declare interface MessageRef {
      */
     edit(params: string | EditTextMessageParams | EditMessageParams): Promise<void>;
     /**
-     * Deletes this message, or does nothing if they are already not a participant.
+     * Deletes this message, or does nothing if the message does not exist.
      *
      * @remarks
      * Deleting a nonexistent message is treated as success, and the promise will resolve.
@@ -1337,6 +1363,13 @@ export declare interface MessageSnapshot {
      * The main body of the message, as a list of blocks that are rendered top-to-bottom.
      */
     content: ContentBlock[];
+    /**
+     * All the emoji reactions that have been added to this message.
+     *
+     * @remarks
+     * There can be up to 50 different reactions on each message.
+     */
+    reactions: ReactionSnapshot[];
 }
 
 /**
@@ -1607,6 +1640,116 @@ export declare interface PendingState {
     type: "pending";
 }
 
+/**
+ * References a specific emoji reaction on a message.
+ *
+ * @remarks
+ * Used in all Data API operations affecting that emoji reaction, such as adding or removing the reaction.
+ * Created via {@link MessageRef.reaction}.
+ *
+ * @public
+ */
+export declare interface ReactionRef {
+    /**
+     * Which emoji the reaction is using.
+     *
+     * @remarks
+     * Either a single Unicode emoji, or the name of a custom emoji with a colon at the start and end.
+     * This is not validated until you send a request to the server.
+     * Since custom emoji are configured in the frontend, there are no checks to make sure a custom emoji actually exists.
+     *
+     * Immutable: if you want to use a different emoji, get a new ReactionRef instead.
+     *
+     * @example Unicode emoji
+     * "👍"
+     *
+     * @example Custom emoji
+     * ":cat-roomba:"
+     */
+    readonly emoji: string;
+    /**
+     * 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.
+     */
+    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.
+     */
+    readonly conversationId: string;
+    /**
+     * Adds this emoji reaction onto the message, from 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.
+     */
+    add(): Promise<void>;
+    /**
+     * Removes this emoji reaction from the message, from 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.
+     */
+    remove(): Promise<void>;
+}
+
+/**
+ * A summary of a single emoji reaction on a message.
+ *
+ * @public
+ */
+export declare interface ReactionSnapshot {
+    /**
+     * Which emoji the users reacted with.
+     *
+     * @remarks
+     * Either a single Unicode emoji, or the name of a custom emoji with a colon at the start and end.
+     * Since custom emoji are defined in the frontend, they are not validated by the TalkJS server.
+     * The UI should ignore reactions that use unrecognised custom emoji.
+     *
+     * NOTE: In unicode, it is possible to have multiple emoji that look identical but are represented differently.
+     * For example, `"👍" !== "👍️"` because the second emoji includes a {@link https://en.wikipedia.org/wiki/Variation_Selectors_(Unicode_block) | variation selector 16 codepoint}.
+     * This codepoint forces the character to appear as an emoji.
+     *
+     * TalkJS normalises all emoji reactions to be "fully qualified" {@link https://unicode.org/Public/emoji/16.0/emoji-test.txt | according to this list}.
+     * This prevents a message having multiple separate 👍 reactions.
+     *
+     * Be careful when processing the `emoji` property, as this normalisation might break equality checks:
+     *
+     * ```ts
+     * // Emoji has unnecessary variation selector 16
+     * const sent = "👍"
+     *
+     * // React with thumbs up,
+     * await message.reaction(emoji).add()
+     *
+     * // Fetch the reaction
+     * const snapshot = await message.get();
+     * const received = snapshot.reactions[0].emoji;
+     *
+     * // Fails because TalkJS removed the variation selector
+     * assert sent === received;
+     * ```
+     *
+     * @example Unicode emoji
+     * "👍"
+     *
+     * @example Custom emoji
+     * ":cat-roomba:"
+     */
+    emoji: string;
+    /**
+     * The number of times this emoji has been added to the message.
+     */
+    count: number;
+    /**
+     * Whether the current user has reacted to the message with this emoji.
+     */
+    currentUserReacted: boolean;
+}
+
 /**
  * A snapshot of a message's attributes at a given moment in time, used in {@link MessageSnapshot.referencedMessage}.
  *
@@ -1679,6 +1822,10 @@ export declare interface ReferencedMessageSnapshot {
      * The main body of the message, as a list of blocks that are rendered top-to-bottom.
      */
     content: ContentBlock[];
+    /**
+     * All the emoji reactions that have been added to this message.
+     */
+    reactions: ReactionSnapshot[];
 }
 
 export declare function registerPolyfills({ WebSocket }: {
@@ -1747,7 +1894,7 @@ export declare interface SendFileBlock {
  */
 export declare interface SendMessageParams {
     /**
-     * Custom metadata you have set on the user.
+     * Custom metadata to set on the message.
      * Default = no custom metadata
      */
     custom?: Record<string, string>;
@@ -1779,7 +1926,7 @@ export declare interface SendMessageParams {
  */
 export declare interface SendTextMessageParams {
     /**
-     * Custom metadata you have set on the user.
+     * Custom metadata to set on the message.
      * Default = no custom metadata
      */
     custom?: Record<string, string>;
@@ -1858,7 +2005,7 @@ export declare interface SetParticipantParams {
     access?: "ReadWrite" | "Read" | null;
     /**
      * When the participant should be notified about new messages in this conversation.
-     * Default = `ReadWrite` access.
+     * Default = true.
      *
      * @remarks
      * `false` means no notifications, `true` means notifications for all messages, and `"MentionsOnly"` means that the user will only be notified when they are mentioned with an `@`.
@@ -1990,6 +2137,7 @@ export declare interface TalkSession {
      *
      * @param id - The ID of the user that you want to reference
      * @returns A {@linkcode UserRef} for the user with that ID
+     * @throws If the id is not a string or is an empty string
      * @public
      */
     user(id: string): UserRef;
@@ -2022,6 +2170,7 @@ export declare interface TalkSession {
      *
      * @param id - The ID of the conversation that you want to reference
      * @returns A {@linkcode ConversationRef} for the conversation with that ID
+     * @throws If the id is not a string or is an empty string
      * @public
      */
     conversation(id: string): ConversationRef;
@@ -2251,7 +2400,7 @@ export declare type TypingSnapshot = FewTypingSnapshot | ManyTypingSnapshot;
  * Get a TypingSubscription by calling {@link ConversationRef.subscribeTyping}.
  *
  * When there are "many" people typing (meaning you received {@link ManyTypingSnapshot}), the next update you receive will be {@link FewTypingSnapshot} once enough people stop typing.
- * Until then, your {@link ManyTypingSnapshot} is still valid and doesn not need to changed, so `onSnapshot` will not be called.
+ * Until then, your {@link ManyTypingSnapshot} is still valid and does not need to changed, so `onSnapshot` will not be called.
  *
  * @public
  */