@talkjs/core 1.6.2 → 1.7.0

package/dist/talkSession.d.ts

@@ -337,6 +337,8 @@ export declare interface ConversationRef {
      * Note that `Participant` is not the same as `User`.
      * A `Participant` represents a user's settings related to a specific conversation.
      *
+     * Calling this method multiple times with the same ID reuses the same {@link ParticipantRef} object.
+     *
      * 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"
@@ -364,6 +366,9 @@ export declare interface ConversationRef {
      *
      * @remarks
      * Use this if you need to fetch, delete, or edit a specific message in this conversation, and you know its message ID.
+     *
+     * Calling this method multiple times with the same ID reuses the same {@link MessageRef} object.
+     *
      * To fetch the most recent messages in this conversation, use {@link ConversationRef.subscribeMessages} instead.
      * To send a message, use {@link ConversationRef.send}.
      *
@@ -582,6 +587,67 @@ export declare interface ConversationRef {
     markAsTyping(): Promise<void>;
 }
 
+/**
+ * Search object returned by `TalkSession.searchConversations` functions.
+ * Used to search for conversations the user is in.
+ * @public
+ */
+export declare interface ConversationSearch {
+    /**
+     * Sets the query string for this search and starts searching for conversations whose `subject` or `custom.search` match the query.
+     *
+     * @remarks
+     * This resets the search to its initial state, clearing all previous results.
+     * Initially loads 3 results. Call {@link MessageSearch.loadMore} to load additional results.
+     *
+     * The query matches a conversation when, for each word in the query, that word appears in the conversation's subject or in `conversation.custom.search`.
+     * This means one of the words in the string starts with the word from the query.
+     * This is case-insensitive and punctuation at the start / end of words is ignored (in both the string and the query).
+     *
+     * A conversation titled `I like to look at rainbows`, will appear in searches for `rainbows`, `rain`, `look at`, `(look, i *LIKE* rain)`, and `look look look!`.
+     * It will not appear in searches for `bows`, `rain-bows`, `look-at`, or `I like to look at rainbows too`.
+     *
+     * It is not possible to match both a conversation's subject and its `custom.search` field at the same time.
+     * A conversation called `Kittens` with `custom.search: "where to buy food"` will not appear in a search for `kitten food`.
+     * However, this only applies per-conversation. If there is one conversation with subject `Kittens` and a second conversation with `custom.search: "Kittens"`, then a search for `kittens` will return both conversations.
+     *
+     * @returns A promise that resolves with the complete first page of results. The promise rejects if the search encounters an error.
+     */
+    setQuery(query: string): Promise<ConversationSearchState>;
+    /**
+     * Continues searching for more conversations.
+     *
+     * @remarks
+     * You can only call `loadMore` when the search has a query set, and is idle.
+     * Calling `loadMore` before calling `setQuery`, while the `setQuery` promise is still pending, or while another `loadMore` promise is pending, has no effect.
+     *
+     * @param limit - The number of results to load. `limit` should be between 1 and 50. Default 10.
+     * @returns A promise that resolves once finished loading, containing all the results from this page and all previous pages. The promise rejects if the search encounters an error.
+     */
+    loadMore(limit?: number): Promise<ConversationSearchState>;
+}
+
+/**
+ * The state of a conversation search in the current step.
+ *
+ * @public
+ */
+export declare interface ConversationSearchState {
+    /**
+     * The conversations that were found in the search.
+     */
+    results: ConversationSnapshot[];
+    /**
+     * Whether all results have been loaded.
+     *
+     * @remarks
+     * Note: When true, this means that the search has reached the oldest matching conversation and no more conversations can be loaded.
+     * However, it does not mean that `results` contains every matching conversation.
+     * Any conversations that received messages since you called `setQuery`, may be missing from `results`.
+     */
+    loadedAll: boolean;
+}
+
 /**
  * A snapshot of a conversation's attributes at a given moment in time.
  *
@@ -1293,6 +1359,8 @@ export declare interface MessageRef {
      * 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.
      *
+     * 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.
      *
      * @example Reacting to the message with a Unicode emoji
@@ -1334,6 +1402,66 @@ export declare interface MessageRef {
     delete(): Promise<void>;
 }
 
+/**
+ * Search object returned by `TalkSession.searchMessages`.
+ * Used to search for messages in the current user's conversations.
+ *
+ * @public
+ */
+export declare interface MessageSearch {
+    /**
+     * Sets the query string for this search and starts searching for messages matching the query.
+     *
+     * @remarks
+     * This resets the search to its initial state, clearing all previous results.
+     * Initially loads 3 results. Call {@link MessageSearch.loadMore} to load additional results.
+     *
+     * The query matches a message when, for each word in the query, that word appears in the message text.
+     * This means one of the words in the string starts with the word from the query.
+     * This is case-insensitive and punctuation at the start / end of words is ignored (in both the string and the query).
+     *
+     * Non-text messages (such as uploaded images) are never returned by search.
+     *
+     * A message saying `I like to look at rainbows`, will appear in searches for `rainbows`, `rain`, `look at`, `(look, i *LIKE* rain)`, and `look look look!`.
+     * It will not appear in searches for `bows`, `rain-bows`, `look-at`, or `I like to look at rainbows too`.
+     *
+     * @returns A promise that resolves with the complete first page of results. The promise rejects if the search encounters an error.
+     */
+    setQuery(query: string): Promise<MessageSearchState>;
+    /**
+     * Continues searching for more messages.
+     *
+     * @remarks
+     * You can only call `loadMore` when the search has a query set, and is idle.
+     * Calling `loadMore` before calling `setQuery`, while the `setQuery` promise is still pending, or while another `loadMore` promise is pending, has no effect.
+     *
+     * @param limit - The number of results to load. `limit` should be between 1 and 50. Default 10.
+     * @returns A promise that resolves once finished loading, containing all the results from this page and all previous pages. The promise rejects if the search encounters an error.
+     */
+    loadMore(limit?: number): Promise<MessageSearchState>;
+}
+
+/**
+ * The state of a message search in the current step.
+ *
+ * @public
+ */
+export declare interface MessageSearchState {
+    /**
+     * Contains all messages found by the search. Each message is paired up with the conversation it is from.
+     */
+    results: SearchMessageSnapshot[];
+    /**
+     * Whether all results have been loaded.
+     *
+     * @remarks
+     * Note: When true, this means that the search has reached the oldest matching message and no more messages can be loaded.
+     * However, it does not mean that `results` contains every matching message.
+     * Any messages sent after you called `setQuery` will be missing from `results`.
+     */
+    loadedAll: boolean;
+}
+
 /**
  * A snapshot of a message's attributes at a given moment in time.
  *
@@ -1877,6 +2005,23 @@ export declare function registerPolyfills({ WebSocket }: {
     WebSocket: object;
 }): void;
 
+/**
+ * A snapshot of search results in a given moment in time.
+ * contains a message and the conversation it from.
+ *
+ * @public
+ */
+export declare interface SearchMessageSnapshot {
+    /**
+     * The conversation that the message was found in.
+     */
+    conversation: ConversationSnapshot;
+    /**
+     * The message that was found in the search.
+     */
+    message: MessageSnapshot;
+}
+
 /**
  * The version of {@link ContentBlock} that is used when sending or editing messages.
  *
@@ -2200,9 +2345,12 @@ export declare interface TalkSession {
      *
      * @remarks
      * This is the entry-point for all operations that affect a user globally, such as editing their name.
+     *
+     * Calling this method multiple times with the same ID reuses the same {@link UserRef} object.
+     *
      * 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)`.
+     * @see {@link Session.currentUser} which is a short-hand for `session.user(meId)`.
      *
      * @example Initialising a user
      * ```
@@ -2232,6 +2380,8 @@ export declare interface TalkSession {
      * This is the entry-point for all conversation-related operations.
      * This includes operations affecting conversation attributes, but also anything related to messages and participants.
      *
+     * Calling this method multiple times with the same ID reuses the same {@link ConversationRef} object.
+     *
      * @example Ensure that the conversation exists and you are a participant
      * ```
      * session.conversation("test").createIfNotExists();
@@ -2285,6 +2435,88 @@ export declare interface TalkSession {
      * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribeConversations(onSnapshot?: (snapshot: ConversationSnapshot[], loadedAll: boolean) => void): ConversationListSubscription;
+    /**
+     * Creates a search for messages in all the current user's conversations.
+     *
+     * @remarks
+     * 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:
+     *
+     * Option 1: Processing each search result as soon as it is received:
+     *
+     * ```ts
+     * const search = session.searchMessages((results, status) => {
+     *   console.log("Found a new message. All messages found so far:", results);
+     * });
+     * search.setQuery("Hello");
+     * ```
+     *
+     * Option 2: Wait until the full page is received (up to 60s delay) before processing:
+     *
+     * ```ts
+     * const search = session.searchMessages();
+     * const { results, loadedAll } = await search.setQuery("Hello");
+     * console.log("Search completed, first page of messages:", results);
+     * ```
+     *
+     * @param onResults - Callback to run whenever we receive new results or the status changes. Status `searching` means we are actively searching for more messages. `canLoadMore` means that the search is idle, but you can load older results with {@link MessageSearch.loadMore}. `loadedAll` means that there are no more messages to load.
+     * @returns A search object. Call {@link MessageSearch.setQuery} to specify the string to search for, and begin receiving results.
+     *
+     * @example Basic UI integration (search-on-keypress)
+     * ```ts
+     * const search = session.searchMessages((results, status) => {
+     *   render(results, status);
+     * });
+     *
+     * const searchInput = document.querySelector("#searchInput");
+     * searchInput.addEventListener("change", () => {
+     *   search.setQuery(searchInput.value);
+     * });
+     * ```
+     */
+    searchMessages(onResults?: (results: SearchMessageSnapshot[], status: "searching" | "canLoadMore" | "loadedAll") => void): MessageSearch;
+    /**
+     * Creates a search for all the current user's conversations.
+     *
+     * @remarks
+     * 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:
+     *
+     * Option 1: Processing each search result as soon as it is received:
+     *
+     * ```ts
+     * const search = session.searchConversations((results, status) => {
+     *   console.log("Found a new conversation. All conversations found so far:", results);
+     * });
+     * search.setQuery("Hello");
+     * ```
+     *
+     * Option 2: Wait until the full page is received (up to 60s delay) before processing:
+     *
+     * ```ts
+     * const search = session.searchConversations();
+     * const { results, loadedAll } = await search.setQuery("Hello");
+     * console.log("Search completed, first page of conversations:", results);
+     * ```
+     *
+     * @param onResults - Callback to run whenever we receive new results or the status changes. Status `searching` means we are actively searching for more conversations. `canLoadMore` means that the search is idle, but you can load older results with {@link ConversationSearch.loadMore}. `loadedAll` means that there are no more conversations to load.
+     * @returns A {@link ConversationSearch}. Call {@link ConversationSearch.setQuery} to specify the string to search for, and begin receiving results.
+     *
+     * @example Basic UI integration (search-on-keypress)
+     * ```ts
+     * const search = session.searchConversations((results, status) => {
+     *   render(results, status);
+     * });
+     *
+     * const searchInput = document.querySelector("#searchInput");
+     * searchInput.addEventListener("change", () => {
+     *   search.setQuery(searchInput.value);
+     * });
+     * ```
+     */
+    searchConversations(onResults?: (results: ConversationSnapshot[], status: "searching" | "canLoadMore" | "loadedAll") => void): ConversationSearch;
     /**
      * Upload a generic file without any additional metadata.
      *