feat: [CHA-794] Add sort and filter param to queryThreads (#1511)

## CLA

- [x] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required).
- [x] Code changes are tested

## Description of the changes, What, Why and How?

Ticket: https://linear.app/stream/issue/CHA-794

Currently the QueryThreads endpoint is fairly limited, we should
overhaul the endpoint and support filter and sort parameter just like we
do with the other endpoints.

Example usage of the new params.

```
const { threads: page1, next: next1 } = await client.queryThreads({
  sort: [
    { created_at: -1 },
    { reply_count: 1 },
    { participant_count: -1 },
  ],
  filter: {
    created_by_user_id: { $eq: 'user1' },
    updated_at: { $gte: '2024-01-01T00:00:00Z' },
});

// request the next page
const { threads: page2, next: next2 } = await client.queryThreads({
  sort: [
    { created_at: -1 },
    { reply_count: 1 },
    { participant_count: -1 },
  ],
  filter: {
    created_by_user_id: { $eq: 'user1' },
    updated_at: { $gte: '2024-01-01T00:00:00Z' },
  }
  next: next1,
});
```

## Changelog
- Add sort and filter parameters to `queryThreads`

Author: adityaalifn

src/client.ts

@@ -2828,6 +2828,8 @@ export class StreamChat<StreamChatGenerics extends ExtendableGenerics = DefaultG
    * @param {boolean} options.watch Subscribes the user to the channels of the threads.
    * @param {number}  options.participant_limit Limits the number of participants returned per threads.
    * @param {number}  options.reply_limit Limits the number of replies returned per threads.
+   * @param {ThreadFilters} options.filter MongoDB style filters for threads
+   * @param {ThreadSort} options.sort MongoDB style sort for threads
    *
    * @returns {{ threads: Thread<StreamChatGenerics>[], next: string }} Returns the list of threads and the next cursor.
    */
@@ -2840,9 +2842,26 @@ export class StreamChat<StreamChatGenerics extends ExtendableGenerics = DefaultG
       ...options,
     };
 
+    const requestBody: Record<string, unknown> = {
+      ...optionsWithDefaults,
+    };
+
+    if (optionsWithDefaults.filter && Object.keys(optionsWithDefaults.filter).length > 0) {
+      requestBody.filter = optionsWithDefaults.filter;
+    }
+
+    if (
+      optionsWithDefaults.sort &&
+      (Array.isArray(optionsWithDefaults.sort)
+        ? optionsWithDefaults.sort.length > 0
+        : Object.keys(optionsWithDefaults.sort).length > 0)
+    ) {
+      requestBody.sort = normalizeQuerySort(optionsWithDefaults.sort);
+    }
+
     const response = await this.post<QueryThreadsAPIResponse<StreamChatGenerics>>(
       `${this.baseURL}/threads`,
-      optionsWithDefaults,
+      requestBody,
     );
 
     return {

src/types.ts

@@ -571,11 +571,13 @@ export type PartialThreadUpdate = {
 };
 
 export type QueryThreadsOptions = {
+  filter?: ThreadFilters;
   limit?: number;
   member_limit?: number;
   next?: string;
   participant_limit?: number;
   reply_limit?: number;
+  sort?: ThreadSort;
   watch?: boolean;
 };
 
@@ -3900,3 +3902,41 @@ export type DraftMessage<StreamChatGenerics extends ExtendableGenerics = Default
   silent?: boolean;
   type?: MessageLabel;
 };
+
+export type ThreadSort = ThreadSortBase | Array<ThreadSortBase>;
+
+export type ThreadSortBase = {
+  active_participant_count?: AscDesc;
+  created_at?: AscDesc;
+  last_message_at?: AscDesc;
+  parent_message_id?: AscDesc;
+  participant_count?: AscDesc;
+  reply_count?: AscDesc;
+  updated_at?: AscDesc;
+};
+
+export type ThreadFilters = QueryFilters<
+  {
+    channel_cid?: RequireOnlyOne<Pick<QueryFilter<string>, '$eq' | '$in'>> | PrimitiveFilter<string>;
+  } & {
+    parent_message_id?:
+      | RequireOnlyOne<Pick<QueryFilter<ThreadResponse['parent_message_id']>, '$eq' | '$in'>>
+      | PrimitiveFilter<ThreadResponse['parent_message_id']>;
+  } & {
+    created_by_user_id?:
+      | RequireOnlyOne<Pick<QueryFilter<ThreadResponse['created_by_user_id']>, '$eq' | '$in'>>
+      | PrimitiveFilter<ThreadResponse['created_by_user_id']>;
+  } & {
+    created_at?:
+      | RequireOnlyOne<Pick<QueryFilter<ThreadResponse['created_at']>, '$eq' | '$gt' | '$lt' | '$gte' | '$lte'>>
+      | PrimitiveFilter<ThreadResponse['created_at']>;
+  } & {
+    updated_at?:
+      | RequireOnlyOne<Pick<QueryFilter<ThreadResponse['updated_at']>, '$eq' | '$gt' | '$lt' | '$gte' | '$lte'>>
+      | PrimitiveFilter<ThreadResponse['updated_at']>;
+  } & {
+    last_message_at?:
+      | RequireOnlyOne<Pick<QueryFilter<ThreadResponse['last_message_at']>, '$eq' | '$gt' | '$lt' | '$gte' | '$lte'>>
+      | PrimitiveFilter<ThreadResponse['last_message_at']>;
+  }
+>;

test/unit/threads.test.ts

@@ -16,6 +16,9 @@ import {
   ThreadManager,
   ThreadResponse,
   THREAD_MANAGER_INITIAL_STATE,
+  ThreadFilters,
+  ThreadSort,
+  QueryThreadsOptions,
 } from '../../src';
 import { THREAD_RESPONSE_RESERVED_KEYS } from '../../src/thread';
 
@@ -1269,7 +1272,7 @@ describe('Threads 2.0', () => {
             unseenThreadIds: [],
           });
           await threadManager.reload();
-          expect(stubbedQueryThreads.calledWithMatch({ limit: 25 })).to.be.true;
+          expect(stubbedQueryThreads.firstCall.calledWithMatch({ limit: 25 })).to.be.true;
         });
 
         it('skips reload if there were no updates since the latest reload', async () => {
@@ -1488,6 +1491,89 @@ describe('Threads 2.0', () => {
           expect(pagination.nextCursor).to.equal('cursor2');
         });
       });
+
+      describe('queryThreads', () => {
+        it('forms correct request with default parameters', async () => {
+          await threadManager.queryThreads();
+
+          expect(
+            stubbedQueryThreads.calledWithMatch({
+              limit: 25,
+              participant_limit: 10,
+              reply_limit: 10,
+              watch: true,
+            }),
+          ).to.be.true;
+        });
+
+        it('applies filter parameters correctly', async () => {
+          const filter: ThreadFilters = {
+            created_at: { $gt: '2024-01-01T00:00:00Z' },
+          };
+
+          await threadManager.queryThreads({ filter });
+
+          expect(
+            stubbedQueryThreads.calledWithMatch({
+              limit: 25,
+              participant_limit: 10,
+              reply_limit: 10,
+              watch: true,
+              filter,
+            }),
+          ).to.be.true;
+        });
+
+        it('applies sort parameters correctly', async () => {
+          const sort: ThreadSort = [{ created_at: -1 }, { last_message_at: 1 }];
+
+          await threadManager.queryThreads({ sort });
+
+          expect(
+            stubbedQueryThreads.calledWithMatch({
+              limit: 25,
+              participant_limit: 10,
+              reply_limit: 10,
+              watch: true,
+              sort,
+            }),
+          ).to.be.true;
+        });
+
+        it('applies both filter and sort parameters correctly', async () => {
+          const filter: ThreadFilters = {
+            created_by_user_id: { $eq: 'user1' },
+            updated_at: { $gte: '2024-01-01T00:00:00Z' },
+          };
+          const sort: ThreadSort = [{ last_message_at: -1 }];
+
+          await threadManager.queryThreads({ filter, sort });
+
+          expect(
+            stubbedQueryThreads.calledWithMatch({
+              limit: 25,
+              participant_limit: 10,
+              reply_limit: 10,
+              watch: true,
+              filter,
+              sort,
+            }),
+          ).to.be.true;
+        });
+
+        it('handles empty filter and sort parameters', async () => {
+          await threadManager.queryThreads({});
+
+          expect(
+            stubbedQueryThreads.calledWithMatch({
+              limit: 25,
+              participant_limit: 10,
+              reply_limit: 10,
+              watch: true,
+            }),
+          ).to.be.true;
+        });
+      });
     });
   });
 });