@talkjs/core 1.6.3 → 1.8.0

package/dist/talkSession.d.ts

@@ -587,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.
  *
@@ -1341,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.
  *
@@ -1577,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;
 }
 
 /**
@@ -1884,6 +2016,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.
  *
@@ -2141,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;
 };
@@ -2297,6 +2504,92 @@ 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
+     * 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:
+     *
+     * 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
+     * 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:
+     *
+     * 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.
      *