@talkjs/core 1.0.1 → 1.1.1

package/dist/talkSession.d.ts

@@ -114,11 +114,11 @@ export declare interface AudioFileMetadata {
  *
  * This means that the following AutoLink is valid:
  *
- * ```
+ * ```json
  * {
  *     type: "autoLink",
  *     text: "talkjs.com"
- *     url: "https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#AutoLinkNode"
+ *     url: "https://talkjs.com/docs/Reference/JavaScript_Data_API/Message_Content/#AutoLinkNode"
  * }
  * ```
  *
@@ -218,8 +218,8 @@ export declare interface ConversationActiveState {
  * References the conversation with a given conversation ID, from the perspective of the current user.
  *
  * @remarks
- * Used in all Realtime API operations affecting that conversation, such as fetching or updating conversation attributes.
- * Created via {@link Session.conversation}.
+ * Used in all Data API operations affecting that conversation, such as fetching or updating conversation attributes.
+ * Created via {@link Session.conversation|Session.conversation()}.
  *
  * @public
  */
@@ -234,13 +234,41 @@ export declare interface ConversationRef {
     /**
      * Get a reference to a participant in this conversation
      *
-     * @param user - the user's ID or a reference to the user
+     * @remarks
+     * Note that `Participant` is not the same as `User`.
+     * A `Participant` represents a user's settings related to a specific conversation.
+     *
+     * Calling {@link ConversationRef.createIfNotExists|ConversationRef.createIfNotExists} or {@link ConversationRef.set|ConversationRef.set} will automatically add the current user as a participant.
+     *
+     * @example To add "Alice" to the conversation "Cats"
+     * ```ts
+     * session.conversation("Cats").participant("Alice").createIfNotExists();
+     * ```
+     *
+     * The user "Alice" must exist before you do this.
+     *
+     * @example To remove "Alice" from the conversation "Cats"
+     * ```ts
+     * session.conversation("Cats").participant("Alice").delete();
+     * ```
+     *
+     * The user "Alice" will still exist after you do this. This deletes the participant, not the user.
+     *
+     * @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
+     * @public
      */
     participant(user: string | UserRef): ParticipantRef;
     /**
      * Get a reference to a message in this conversation
      *
-     * @param user - the message ID
+     * @remarks
+     * 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
+     * @public
      */
     message(id: string): MessageRef;
     /**
@@ -260,7 +288,7 @@ export declare interface ConversationRef {
      * You are added as a participant if you are not already a participant in the conversation.
      *
      * @returns A promise that resolves when the operation completes.
-     * When client-side conversation syncing is disabled, you may only set your `notify` property, when you are already a participant.
+     * When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the `notify` property.
      * Everything else requires client-side conversation syncing to be enabled, and will cause the promise to reject.
      */
     set(params: SetConversationParams): Promise<void>;
@@ -289,6 +317,54 @@ export declare interface ConversationRef {
     /**
      * Sends a message in the conversation
      *
+     * @example Send a simple message with markup (bold in this example)
+     * ```ts
+     * conversationRef.send("*Hello*");
+     * ```
+     *
+     * @example Reply to a message and set custom message data
+     * ```ts
+     * conversationRef.send({
+     *   text: "Agreed",
+     *   referencedMessageId: "...",
+     *   custom: { priority: "HIGH" }
+     * });
+     * ```
+     *
+     * @example Send pre-formatted text with {@link TextBlock}
+     * ```ts
+     * conversationRef.send({
+     *   content: [{
+     *     type: "text",
+     *     children: [{
+     *       type: "bold",
+     *       children: ["Hello"]
+     *     }]
+     *   }]
+     * });
+     * ```
+     *
+     * @example Send a file with {@link SendFileBlock}
+     * ```ts
+     * // `file` is a File object from `<input type="file">`
+     * const fileToken = await session.uploadImage(
+     *   file, { filename: file.name, width: 640, height: 480 }
+     * );
+     *
+     * conversationRef.send({
+     *   content: [{ type: "file", fileToken }]
+     * });
+     * ```
+     *
+     * @example Send a location with {@link LocationBlock}
+     * ```ts
+     * // You can get the user's location with the browser's geolocation API
+     * const [latitude, longitude] = [42.43, -83.99];
+     * conversationRef.send({
+     *   content: [{ type: "location", latitude, longitude }]
+     * });
+     * ```
+     *
      * @returns A promise that resolves with a reference to the newly created message. The promise will reject if you do not have permission to send the message.
      */
     send(params: string | SendTextMessageParams | SendMessageParams): Promise<MessageRef>;
@@ -310,11 +386,64 @@ export declare interface ConversationRef {
      *
      * @remarks
      * Whenever `Subscription.state.type` is "active" and something about the conversation changes, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
-     * This includes changes to nested data. As an extreme example, `onSnapshot` would be called if `snapshot.lastMessage.referencedMessage.sender.name` changes.
+     * This includes changes to nested data. As an extreme example, `onSnapshot` would be called when `snapshot.lastMessage.referencedMessage.sender.name` changes.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
      */
     subscribe(onSnapshot?: (snapshot: ConversationSnapshot | null) => void): ConversationSubscription;
+    /**
+     * Subscribes to the typing status of the conversation.
+     *
+     * @remarks
+     * Whenever `Subscription.state.type` is "active" and the typing status changes, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
+     * This includes changes to nested data, such as when a user who is typing changes their name.
+     *
+     * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     *
+     * Note that if there are "many" people typing and another person starts to type, `onSnapshot` will not be called.
+     * This is because your existing {@link ManyTypingSnapshot} is still valid and did not change when the new person started to type.
+     */
+    subscribeTyping(onSnapshot?: (snapshot: TypingSnapshot | null) => void): TypingSubscription;
+    /**
+     * Marks the current user as typing in this conversation for 10 seconds.
+     *
+     * @remarks
+     * This means that other users will see a typing indicator in the UI, from the current user.
+     *
+     * The user will automatically stop typing after 10 seconds. You cannot manually mark a user as "not typing".
+     * Users are also considered "not typing" when they send a message, even if that message was sent from a different tab or using the REST API.
+     *
+     * To keep the typing indicator visible for longer, call this function again to reset the 10s timer.
+     *
+     * @example Example implementation
+     * ```ts
+     * let lastMarkedAsTyping = 0;
+     *
+     * inputElement.addEventListener("change", event => {
+     *   const text = event.target.value;
+     *
+     *   // Deleting your draft never counts as typing
+     *   if (text.length === 0) {
+     *     return;
+     *   }
+     *
+     *   const now = Date.now();
+     *
+     *   // Don't mark as typing more than once every 5s
+     *   if (now - lastMarkedAsTyping > 5000) {
+     *     lastMarkedAsTyping = now;
+     *     convRef.markAsTyping();
+     *   }
+     * });
+     *
+     * // When you send a message, you are no longer considered typing
+     * // So we need to send markAsTyping as soon as you type something
+     * function onSendMessage() {
+     *   lastMarkedAsTyping = 0;
+     * }
+     * ```
+     */
+    markAsTyping(): Promise<void>;
 }
 
 /**
@@ -333,11 +462,11 @@ export declare interface ConversationSnapshot {
      */
     id: string;
     /**
-     * Contains the conversation subject if it was set using {@link ConversationBuilder.subject}.
+     * Contains the conversation subject, or `null` if the conversation does not have a subject specified.
      */
     subject: string | null;
     /**
-     * Contains the URL of a photo was set using {@link ConversationBuilder.subject}.
+     * Contains the URL of a photo to represent the topic of the conversation or `null` if the conversation does not have a photo specified.
      */
     photoUrl: string | null;
     /**
@@ -365,9 +494,25 @@ export declare interface ConversationSnapshot {
      */
     unreadMessageCount: number;
     /**
-     * Timestamp of when the current user read a message
+     * The most recent date that the current user read the conversation.
+     *
+     * @remarks
+     * This value is updated whenever you read a message in a chat UI, open an email notification, or mark the conversation as read using an API like {@link ConversationRef.markAsRead}.
+     *
+     * Any messages sent after this timestamp are unread messages.
      */
     readUntil: number;
+    /**
+     * Everyone in the conversation has read any messages sent on or before this date.
+     *
+     * @remarks
+     * This is the minimum of all the participants' `readUntil` values.
+     * Any messages sent on or before this timestamp should show a "read" indicator in the UI.
+     *
+     * This value will rarely change in very large conversations.
+     * If just one person stops checking their messages, `everyoneReadUntil` will never update.
+     */
+    everyoneReadUntil: number;
     /**
      * Whether the conversation should be considered unread.
      *
@@ -643,6 +788,27 @@ export declare interface ErrorState {
     error: Error;
 }
 
+/**
+ * The {@link TypingSnapshot} variant used when only a few people are typing.
+ */
+export declare interface FewTypingSnapshot {
+    /**
+     * Check this to differentiate between FewTypingSnapshot (`false`) and ManyTypingSnapshot (`true`).
+     *
+     * @remarks
+     * When `false`, you can see the list of users who are typing in the `users` property.
+     */
+    many: false;
+    /**
+     * The users who are currently typing in this conversation.
+     *
+     * @remarks
+     * The list is in chronological order, starting with the users who have been typing the longest.
+     * The current user is never contained in the list, only other users.
+     */
+    users: UserSnapshot[];
+}
+
 /**
  * A file attachment received in a message's content.
  *
@@ -671,35 +837,34 @@ export declare type FileBlock = VideoBlock | ImageBlock | AudioBlock | VoiceBloc
  *
  * @remarks
  * You cannot create a FileToken yourself. Get a file token by uploading your file to TalkJS with {@link Session.uploadFile}, or one of the subtype-specific variants like {@link Session.uploadImage}.
+ * Alternatively, take a file token from an existing {@link FileBlock} to re-send an attachment you received, without having to download and re-upload the file.
+ * You can also upload files using the {@link https://talkjs.com/docs/Reference/REST_API/Messages/#1-upload-a-file| REST API}.
+ * This system ensures that all files must be uploaded to TalkJS before being sent to users, limiting the risk of malware.
  *
- * For example:
+ * Passed in {@link SendFileBlock} when you send a message containing a file attachment.
  *
- * ```
+ * We may change the FileToken format in the future.
+ * Do not store old file tokens for future use, as these may stop working.
+ *
+ * @example Using a file input
+ * ```ts
  * // From `<input type="file">`
  * const file: File = fileInputElement.files[0];
  * const myFileToken = await session.uploadFile(file, { filename: file.name });
- * ```
- *
- * Alternatively, take a file token from an existing {@link FileBlock} to re-send an attachment you received, without having to download and re-upload the file.
  *
- * You can also upload files using the {@link https://talkjs.com/docs/Reference/REST_API/Messages/#1-upload-a-file| REST API}.
- *
- * Passed in {@link SendFileBlock} when you send a message containing a file attachment:
- *
- * ```
- * const block: SendFileBlock = {
+ * const block = {
  *   type: 'file',
  *   fileToken: myFileToken,
  * };
- *
- * const convRef = session.conversation('example_conversation_id');
- * convRef.send({ content: [block] });
+ * session.conversation('example_conversation_id').send({ content: [block] });
  * ```
  *
- * We may change the FileToken format in the future.
- * Do not store old file tokens for future use, as these may stop working.
- *
- * This system ensures that all files must be uploaded to TalkJS before being sent to users, limiting the risk of malware.
+ * @example Re-sending a file from a previous message
+ * ```ts
+ * session.conversation('example_conversation_id').send({
+ *   content: previousMessageSnapshot.content
+ * });
+ * ```
  *
  * @public
  */
@@ -715,7 +880,7 @@ export declare type FileToken = string & {
  *
  * Instead, treat GenericFileBlock as the default. For example:
  *
- * ```
+ * ```ts
  * if (block.subtype === "video") {
  *     handleVideoBlock(block);
  * } else if (block.subtype === "image") {
@@ -763,7 +928,7 @@ export declare interface GenericFileMetadata {
 }
 
 /**
- * Returns a TalkSession option for the specified App ID and User ID.
+ * Returns a TalkSession for the specified App ID and User ID.
  *
  * @remarks
  * Backed by a registry, so calling this function twice with the same app and user returns the same session object both times.
@@ -879,6 +1044,20 @@ export declare interface LocationBlock {
     longitude: number;
 }
 
+/**
+ * The {@link TypingSnapshot} variant used when many people are typing.
+ */
+export declare interface ManyTypingSnapshot {
+    /**
+     * Check this to differentiate between FewTypingSnapshot (`false`) and ManyTypingSnapshot (`true`).
+     *
+     * @remarks
+     * When `true`, you do not receive a list of users who are typing.
+     * You should show a message like "several people are typing" instead.
+     */
+    many: true;
+}
+
 /**
  * A node in a {@link TextBlock} that renders its children with a specific style.
  *
@@ -931,7 +1110,7 @@ export declare interface MessageActiveState {
     latestSnapshot: MessageSnapshot[] | null;
     /**
      * True if `latestSnapshot` contains all messages in the conversation.
-     * Use `MessageSubscription.loadMore` to load more.
+     * Use {@link MessageSubscription.loadMore} to load more.
      */
     loadedAll: boolean;
 }
@@ -940,8 +1119,8 @@ export declare interface MessageActiveState {
  * References the message with a given message ID.
  *
  * @remarks
- * Used in all Realtime API operations affecting that message, such as fetching or editing the message attributes, or deleting the message.
- * Created via {@link ConversationRef.message}.
+ * Used in all Data API operations affecting that message, such as fetching or editing the message attributes, or deleting the message.
+ * Created via {@link ConversationRef.message} and {@link ConversationRef.send}.
  *
  * @public
  */
@@ -964,7 +1143,7 @@ export declare interface MessageRef {
      * Fetches a snapshot of the message.
      *
      * @remarks
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#cached-fetch | Cached Fetch}
+     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#cached-fetch | Cached Fetch}
      *
      * @returns A snapshot of the message's attributes, or null if the message doesn't exist, the conversation doesn't exist, or you're not a participant in the conversation.
      */
@@ -1068,7 +1247,7 @@ export declare interface MessageSnapshot {
  * 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.
  *
- * You can expand this window by calling `loadMore`, which extends the window further into the past.
+ * You can expand this window by calling {@link MessageSubscription.loadMore}, which extends the window further into the past.
  *
  * @public
  */
@@ -1115,7 +1294,7 @@ export declare interface MessageSubscription {
      * @param count - The number of additional messages to load. Must be between 1 and 100
      * @returns A promise that resolves once the additional messages have loaded
      */
-    loadMore: (count?: number) => Promise<void>;
+    loadMore(count?: number): Promise<void>;
     /**
      * Unsubscribe from this resource and stop receiving updates.
      *
@@ -1129,7 +1308,7 @@ export declare interface MessageSubscription {
  * References a given user's participation in a conversation.
  *
  * @remarks
- * Used in all Realtime API operations affecting that participant, such as joining/leaving a conversation, or setting their access.
+ * Used in all Data API operations affecting that participant, such as joining/leaving a conversation, or setting their access.
  * Created via {@link ConversationRef.participant}.
  *
  * @public
@@ -1162,10 +1341,10 @@ export declare interface ParticipantRef {
      * Sets properties of this participant. If the user is not already a participant in the conversation, they will be added.
      *
      * @remarks
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#automatic-batching | Automatic Batching}
+     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#automatic-batching | Automatic Batching}
      *
      * @returns A promise that resolves when the operation completes.
-     * When client-side conversation syncing is disabled, you may only set your `notify` property, when you are already a participant.
+     * When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the `notify` property.
      * Everything else requires client-side conversation syncing to be enabled, and will cause the promise to reject.
      */
     set(params: SetParticipantParams): Promise<void>;
@@ -1173,10 +1352,10 @@ export declare interface ParticipantRef {
      * Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the promise will reject.
      *
      * @remarks
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#automatic-batching | Automatic Batching}
+     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#automatic-batching | Automatic Batching}
      *
      * @returns A promise that resolves when the operation completes.
-     * When client-side conversation syncing is disabled, you may only set your `notify` property, when you are already a participant.
+     * When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the `notify` property.
      * Everything else requires client-side conversation syncing to be enabled, and will cause the promise to reject.
      */
     edit(params: SetParticipantParams): Promise<void>;
@@ -1186,7 +1365,7 @@ export declare interface ParticipantRef {
      * @remarks
      * If the participant already exists, this operation is still considered successful and the promise will still resolve.
      *
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#automatic-batching | Automatic Batching}
+     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#automatic-batching | Automatic Batching}
      *
      * @returns A promise that resolves when the operation completes. The promise will reject if client-side conversation syncing is disabled and the user is not already a participant.
      */
@@ -1297,9 +1476,9 @@ export declare interface ReferencedMessageSnapshot {
     /**
      * Where this message originated from:
      *
-     * - "web" = Message sent via the UI or via `ConversationBuilder.sendMessage`
+     * - "web" = Message sent via the UI or via {@link ConversationBuilder.sendMessage}
      *
-     * - "rest" = Message sent via the REST API's "send message" endpoint
+     * - "rest" = Message sent via the REST API's "send message" endpoint or {@link ConversationRef.send}
      *
      * - "import" = Message sent via the REST API's "import messages" endpoint
      *
@@ -1330,7 +1509,7 @@ export declare function registerPolyfills({ WebSocket }: {
  * `SendContentBlock` is a subset of `ContentBlock`.
  * This means that you can re-send the `content` from an existing message without any issues:
  *
- * ```
+ * ```ts
  * const existingMessage: MessageSnapshot = ...;
  *
  * const convRef = session.conversation('example_conversation_id');
@@ -1352,7 +1531,7 @@ export declare type SendContentBlock = TextBlock | SendFileBlock | LocationBlock
  * The `SendFileBlock` interface is a subset of the `FileBlock` interface.
  * If you have an existing `FileBlock` received in a message, you can re-use that block to re-send the same attachment:
  *
- * ```
+ * ```ts
  * const existingFileBlock = ...;
  * const imageToShare = existingFileBlock.content[0] as ImageBlock
  *
@@ -1397,6 +1576,8 @@ export declare interface SendMessageParams {
      *
      * @remarks
      * By default users do not have permission to send {@link LinkNode}, {@link ActionLinkNode}, or {@link ActionButtonNode}, as they can be used to trick the recipient.
+     *
+     * Currently, each message can only contain a single {@link SendContentBlock}.
      */
     content: [SendContentBlock];
 }
@@ -1579,6 +1760,10 @@ export declare interface TalkSession {
      * @remarks
      * This is immutable. If you want to connect as a different user,
      * call `getTalkSession` again to get a new session.
+     *
+     * Equivalent to calling `Session.user` with the current user's ID.
+     *
+     * @see {@link Session.user} which lets you get a reference to any user.
      */
     readonly currentUser: UserRef;
     /**
@@ -1597,6 +1782,27 @@ export declare interface TalkSession {
     /**
      * Get a reference to a user
      *
+     * @remarks
+     * This is the entry-point for all operations that affect a user globally, such as editing their name.
+     * For operations related to a user's participation in a conversation, do: `session.conversation(<convId>).participant(<userId>)`
+     *
+     * @see {@link Session.currentUser} which is a short-hand for `session.user(session.me.id)`.
+     *
+     * @example Initialising a user
+     * ```
+     * const userRef = session.user("test");
+     * userRef.createIfNotExists({ name: "Alice" });
+     * ```
+     *
+     * @example Subscribing to changes
+     * ```
+     * const userRef = session.user("test");
+     * const sub = userRef.subscribe(snapshot => console.log(snapshot));
+     * await sub.connected;
+     *
+     * // Changing the user's name emits a snapshot and triggers the `console.log`
+     * await userRef.set({ name: "Bob" });
+     *
      * @param id - The ID of the user that you want to reference
      * @returns A {@linkcode UserRef} for the user with that ID
      * @public
@@ -1605,6 +1811,30 @@ export declare interface TalkSession {
     /**
      * Get a reference to a conversation
      *
+     * @remarks
+     * This is the entry-point for all conversation-related operations.
+     * This includes operations affecting conversation attributes, but also anything related to messages and participants.
+     *
+     * @example Ensure that the conversation exists and you are a participant
+     * ```
+     * session.conversation("test").createIfNotExists();
+     * ```
+     *
+     * @example Set the conversation's subject
+     * ```
+     * session.conversation("test").set({ subject: "Power tools" });
+     * ```
+     *
+     * @example Stop receiving notifications for this conversation
+     * ```
+     * session.conversation("test").set({ notify: false });
+     * ```
+     *
+     * @example Send a message
+     * ```
+     * session.conversation("test").send("Hello");
+     * ```
+     *
      * @param id - The ID of the conversation that you want to reference
      * @returns A {@linkcode ConversationRef} for the conversation with that ID
      * @public
@@ -1692,7 +1922,7 @@ export declare interface TalkSessionOptions {
  *
  * Then this would become a Text Block with the structure:
  *
- * ```
+ * ```json
  * {
  *   type: "text",
  *   children: [
@@ -1730,7 +1960,7 @@ export declare interface TextBlock {
  * The simplest `TextNode` is a plain text string.
  * Using "hello" as an example message, the `TextBlock` would be:
  *
- * ```typescript
+ * ```ts
  * {
  *   type: 'text';
  *   children: ['hello'];
@@ -1739,7 +1969,7 @@ export declare interface TextBlock {
  *
  * Other than plain text, there are many different kinds of node which render some text in a specific way or with certain formatting.
  *
- * ```
+ * ```ts
  * type TextNode =
  *     | string
  *     | MarkupNode
@@ -1761,6 +1991,106 @@ export declare interface TextBlock {
  */
 export declare type TextNode = string | MarkupNode | BulletListNode | BulletPointNode | CodeSpanNode | LinkNode | AutoLinkNode | ActionLinkNode | ActionButtonNode | CustomEmojiNode | MentionNode;
 
+/**
+ * The state of a typing subscription when it is actively listening for changes
+ *
+ * @public
+ */
+export declare interface TypingActiveState {
+    type: "active";
+    /**
+     * The most recently received typing indicator snapshot, or `null` if you are not a participant in the conversation (including when the conversation does not exist).
+     */
+    latestSnapshot: TypingSnapshot | null;
+}
+
+/**
+ * A snapshot of the typing indicators in a conversation at a given moment in time.
+ * Will be either {@link FewTypingSnapshot} when only a few people are typing, or {@link ManyTypingSnapshot} when many people are typing.
+ *
+ * @remarks
+ * Currently {@link FewTypingSnapshot} is used when there are 5 or less people typing in the conversation, and {@link ManyTypingSnapshot} is used when more than 5 people are typing.
+ * This limit may change in the future, which will not be considered a breaking change.
+ *
+ * @example Converting a TypingSnapshot to text
+ * ```ts
+ * function formatTyping(snapshot: TypingSnapshot): string {
+ *   if (snapshot.many) {
+ *     return "Several people are typing";
+ *   }
+ *
+ *   const names = snapshot.users.map(user => user.name);
+ *
+ *   if (names.length === 0) {
+ *     return "";
+ *   }
+ *
+ *   if (names.length === 1) {
+ *     return names[0] + " is typing";
+ *   }
+ *
+ *   if (names.length === 2) {
+ *     return names.join(" and ") + " are typing";
+ *   }
+ *
+ *   // Prefix last name with "and "
+ *   names.push("and " + names.pop());
+ *   return names.join(", ") + " are typing";
+ * }
+ * ```
+ */
+export declare type TypingSnapshot = FewTypingSnapshot | ManyTypingSnapshot;
+
+/**
+ * A subscription to the typing status in a specific conversation
+ *
+ * @remarks
+ * 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.
+ *
+ * @public
+ */
+export declare interface TypingSubscription {
+    /**
+     * 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: TypingSnapshot | null`. It is the current state of the typing indicators, or null if you're not a participant in the conversation
+     *
+     * When `type` is "error", includes the `error: Error` field. It is a JS `Error` object explaining what caused the subscription to be terminated.
+     */
+    state: PendingState | TypingActiveState | 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<TypingActiveState>;
+    /**
+     * 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>;
+    /**
+     * 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 after you have manually unsubscribed
  *
@@ -1787,7 +2117,7 @@ export declare interface UserActiveState {
  * References the user with a given user ID.
  *
  * @remarks
- * Used in all Realtime API operations affecting that user, such as creating the user, fetching or updating user data, or adding a user to a conversation.
+ * Used in all Data API operations affecting that user, such as creating the user, fetching or updating user data, or adding a user to a conversation.
  * Created via {@link Session.user}.
  *
  * @public
@@ -1808,7 +2138,7 @@ export declare interface UserRef {
      * Fetching a user snapshot doesn't require any permissions. You can read the public information of any user.
      * Private information, such as email addresses and phone numbers, aren't included in the response.
      *
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#automatic-batching | Automatic Batching} and {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#cached-fetch | Cached Fetch}
+     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#automatic-batching | Automatic Batching} and {@link https://talkjs.com/docs/Reference/JavaScript_Data_API/Performance/#cached-fetch | Cached Fetch}
      *
      * @returns A snapshot of the user's public attributes, or null if the user doesn't exist.
      */
@@ -1837,8 +2167,6 @@ export declare interface UserRef {
      * @remarks
      * Whenever `Subscription.state.type` is "active" and the user is created or their attributes change, `onSnapshot` will fire and `Subscription.state.latestSnapshot` will be updated.
      *
-     * Supports {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#subscription-sharing | Subscription Sharing} and {@link https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Realtime_API/#debounced-unsubscribe | Debounced Unsubscribe}
-     *
      * @returns A subscription to the user
      */
     subscribe(onSnapshot?: (event: UserSnapshot | null) => void): UserSubscription;