stream-chat 9.44.1 → 9.44.2

package/dist/types/channel_manager.d.ts

@@ -1,4 +1,4 @@
-import type { StreamChat } from './client';
+import type { QueryChannelsResponseWithChannels, StreamChat } from './client';
 import type { ChannelFilters, ChannelOptions, ChannelSort, ChannelStateOptions, Event } from './types';
 import type { ValueOrPatch } from './store';
 import { StateStore } from './store';
@@ -10,6 +10,8 @@ export type ChannelManagerPagination = {
     isLoading: boolean;
     isLoadingNext: boolean;
     options: ChannelOptions;
+    responseFilters?: ChannelFilters;
+    responseSort?: ChannelSort;
     sort: ChannelSort;
 };
 export type ChannelManagerState = {
@@ -64,7 +66,8 @@ export type ChannelManagerOptions = {
      */
     lockChannelOrder?: boolean;
 };
-export type QueryChannelsRequestType = (...params: Parameters<StreamChat['queryChannels']>) => Promise<Channel[]>;
+export type QueryChannelsRequestOutput = Channel[] | QueryChannelsResponseWithChannels;
+export type QueryChannelsRequestType = (filters: ChannelFilters, sort?: ChannelSort, options?: ChannelOptions, stateOptions?: ChannelStateOptions) => Promise<QueryChannelsRequestOutput>;
 export declare const DEFAULT_CHANNEL_MANAGER_OPTIONS: {
     abortInFlightQuery: boolean;
     allowNotLoadedChannelPromotionForEvent: {

package/dist/types/client.d.ts

@@ -8,7 +8,7 @@ import { WSConnectionFallback } from './connection_fallback';
 import { Campaign } from './campaign';
 import { ChannelBatchUpdater } from './channel_batch_updater';
 import { Segment } from './segment';
-import type { ActiveLiveLocationsAPIResponse, APIErrorResponse, APIResponse, AppSettings, AppSettingsAPIResponse, BannedUsersFilters, BannedUsersPaginationOptions, BannedUsersResponse, BannedUsersSort, BanUserOptions, BaseDeviceFields, BlockList, BlockListResponse, BlockUserAPIResponse, CampaignData, CampaignFilters, CampaignQueryOptions, CampaignResponse, CampaignSort, CastVoteAPIResponse, ChannelAPIResponse, ChannelData, ChannelFilters, ChannelMute, ChannelOptions, ChannelResponse, ChannelSort, ChannelStateOptions, CheckPushResponse, CheckSNSResponse, CheckSQSResponse, Configs, ConnectAPIResponse, CreateChannelOptions, CreateChannelResponse, CreateCommandOptions, CreateCommandResponse, CreateImportOptions, CreateImportResponse, CreateImportURLResponse, CreatePollAPIResponse, CreatePollData, CreatePollOptionAPIResponse, CreatePredefinedFilterOptions, CreateReminderOptions, CustomPermissionOptions, DeactivateUsersOptions, DeleteCommandResponse, DeleteMessageOptions, DeleteUserOptions, Device, DeviceIdentifier, DraftFilters, DraftSort, EndpointName, Event, EventAPIResponse, EventHandler, ExportChannelOptions, ExportChannelRequest, ExportChannelResponse, ExportChannelStatusResponse, ExportUsersRequest, ExportUsersResponse, FlagMessageResponse, FlagReportsFilters, FlagReportsPaginationOptions, FlagReportsResponse, FlagsFilters, FlagsPaginationOptions, FlagsResponse, FlagUserResponse, FutureChannelBansResponse, GetBlockedUsersAPIResponse, GetCampaignOptions, GetChannelTypeResponse, GetCommandResponse, GetHookEventsResponse, GetImportResponse, GetMessageOptions, GetPollAPIResponse, GetRateLimitsResponse, GetRetentionPolicyResponse, GetRetentionPolicyRunsOptions, GetRetentionPolicyRunsResponse, GetThreadAPIResponse, GetThreadOptions, GetUnreadCountAPIResponse, GetUnreadCountBatchAPIResponse, ListChannelResponse, ListCommandsResponse, ListImportsPaginationOptions, ListImportsResponse, ListPredefinedFiltersOptions, ListPredefinedFiltersResponse, LocalMessage, Logger, MarkChannelsReadOptions, MarkDeliveredOptions, MessageFilters, MessageFlagsFilters, MessageFlagsPaginationOptions, MessageFlagsResponse, MessageResponse, Mute, MuteUserOptions, MuteUserResponse, OGAttachment, OwnUserResponse, Pager, PartialMessageUpdate, PartialPollUpdate, PartialThreadUpdate, PartialUserUpdate, PermissionAPIResponse, PermissionsAPIResponse, PollAnswersAPIResponse, PollData, PollOptionData, PollSort, PollVote, PollVoteData, PollVotesAPIResponse, PredefinedFilterResponse, Product, PushPreference, PushProvider, PushProviderConfig, PushProviderID, PushProviderListResponse, PushProviderUpsertResponse, QueryDraftsResponse, QueryFutureChannelBansOptions, QueryMessageHistoryFilters, QueryMessageHistoryOptions, QueryMessageHistoryResponse, QueryMessageHistorySort, QueryPollsFilters, QueryPollsOptions, QueryPollsResponse, QueryReactionsAPIResponse, QueryReactionsOptions, QueryRemindersOptions, QueryRemindersResponse, QuerySegmentsOptions, QuerySegmentTargetsFilter, QueryTeamUsageStatsOptions, QueryTeamUsageStatsResponse, QueryThreadsOptions, QueryVotesFilters, QueryVotesOptions, ReactionFilters, ReactionResponse, ReactionSort, ReactivateUserOptions, ReactivateUsersOptions, ReminderAPIResponse, ReviewFlagReportOptions, ReviewFlagReportResponse, SdkIdentifier, SearchAPIResponse, SearchOptions, SegmentData, SegmentResponse, SegmentTargetsResponse, SegmentType, SendFileAPIResponse, SetRetentionPolicyResponse, SharedLocationResponse, SortParam, StreamChatOptions, SyncOptions, SyncResponse, TaskResponse, TaskStatus, TestPushDataInput, TestSNSDataInput, TestSQSDataInput, TokenOrProvider, TranslateResponse, UnBanUserOptions, UpdateChannelsBatchOptions, UpdateChannelTypeRequest, UpdateChannelTypeResponse, UpdateCommandOptions, UpdateCommandResponse, UpdateLocationPayload, UpdateMessageAPIResponse, UpdateMessageOptions, UpdatePollAPIResponse, UpdatePredefinedFilterOptions, UpdateReminderOptions, UpdateSegmentData, UpdateUsersAPIResponse, UpsertPushPreferencesResponse, UserCustomEvent, UserFilters, UserOptions, UserResponse, UserSort, VoteSort } from './types';
+import type { ActiveLiveLocationsAPIResponse, APIErrorResponse, APIResponse, AppSettings, AppSettingsAPIResponse, BannedUsersFilters, BannedUsersPaginationOptions, BannedUsersResponse, BannedUsersSort, BanUserOptions, BaseDeviceFields, BlockList, BlockListResponse, BlockUserAPIResponse, CampaignData, CampaignFilters, CampaignQueryOptions, CampaignResponse, CampaignSort, CastVoteAPIResponse, ChannelAPIResponse, ChannelData, ChannelFilters, ChannelMute, ChannelOptions, ChannelResponse, ChannelSort, ChannelStateOptions, CheckPushResponse, CheckSNSResponse, CheckSQSResponse, Configs, ConnectAPIResponse, CreateChannelOptions, CreateChannelResponse, CreateCommandOptions, CreateCommandResponse, CreateImportOptions, CreateImportResponse, CreateImportURLResponse, CreatePollAPIResponse, CreatePollData, CreatePollOptionAPIResponse, CreatePredefinedFilterOptions, CreateReminderOptions, CustomPermissionOptions, DeactivateUsersOptions, DeleteCommandResponse, DeleteMessageOptions, DeleteUserOptions, Device, DeviceIdentifier, DraftFilters, DraftSort, EndpointName, Event, EventAPIResponse, EventHandler, ExportChannelOptions, ExportChannelRequest, ExportChannelResponse, ExportChannelStatusResponse, ExportUsersRequest, ExportUsersResponse, FlagMessageResponse, FlagReportsFilters, FlagReportsPaginationOptions, FlagReportsResponse, FlagsFilters, FlagsPaginationOptions, FlagsResponse, FlagUserResponse, FutureChannelBansResponse, GetBlockedUsersAPIResponse, GetCampaignOptions, GetChannelTypeResponse, GetCommandResponse, GetHookEventsResponse, GetImportResponse, GetMessageOptions, GetPollAPIResponse, GetRateLimitsResponse, GetRetentionPolicyResponse, GetRetentionPolicyRunsOptions, GetRetentionPolicyRunsResponse, GetThreadAPIResponse, GetThreadOptions, GetUnreadCountAPIResponse, GetUnreadCountBatchAPIResponse, ListChannelResponse, ListCommandsResponse, ListImportsPaginationOptions, ListImportsResponse, ListPredefinedFiltersOptions, ListPredefinedFiltersResponse, LocalMessage, Logger, MarkChannelsReadOptions, MarkDeliveredOptions, MessageFilters, MessageFlagsFilters, MessageFlagsPaginationOptions, MessageFlagsResponse, MessageResponse, Mute, MuteUserOptions, MuteUserResponse, OGAttachment, OwnUserResponse, Pager, PartialMessageUpdate, PartialPollUpdate, PartialThreadUpdate, PartialUserUpdate, PermissionAPIResponse, PermissionsAPIResponse, PollAnswersAPIResponse, PollData, PollOptionData, PollSort, PollVote, PollVoteData, PollVotesAPIResponse, PredefinedFilterResponse, Product, PushPreference, PushProvider, PushProviderConfig, PushProviderID, PushProviderListResponse, PushProviderUpsertResponse, QueryChannelsAPIResponse, QueryDraftsResponse, QueryFutureChannelBansOptions, QueryMessageHistoryFilters, QueryMessageHistoryOptions, QueryMessageHistoryResponse, QueryMessageHistorySort, QueryPollsFilters, QueryPollsOptions, QueryPollsResponse, QueryReactionsAPIResponse, QueryReactionsOptions, QueryRemindersOptions, QueryRemindersResponse, QuerySegmentsOptions, QuerySegmentTargetsFilter, QueryTeamUsageStatsOptions, QueryTeamUsageStatsResponse, QueryThreadsOptions, QueryVotesFilters, QueryVotesOptions, ReactionFilters, ReactionResponse, ReactionSort, ReactivateUserOptions, ReactivateUsersOptions, ReminderAPIResponse, ReviewFlagReportOptions, ReviewFlagReportResponse, SdkIdentifier, SearchAPIResponse, SearchOptions, SegmentData, SegmentResponse, SegmentTargetsResponse, SegmentType, SendFileAPIResponse, SetRetentionPolicyResponse, SharedLocationResponse, SortParam, StreamChatOptions, SyncOptions, SyncResponse, TaskResponse, TaskStatus, TestPushDataInput, TestSNSDataInput, TestSQSDataInput, TokenOrProvider, TranslateResponse, UnBanUserOptions, UpdateChannelsBatchOptions, UpdateChannelTypeRequest, UpdateChannelTypeResponse, UpdateCommandOptions, UpdateCommandResponse, UpdateLocationPayload, UpdateMessageAPIResponse, UpdateMessageOptions, UpdatePollAPIResponse, UpdatePredefinedFilterOptions, UpdateReminderOptions, UpdateSegmentData, UpdateUsersAPIResponse, UpsertPushPreferencesResponse, UserCustomEvent, UserFilters, UserOptions, UserResponse, UserSort, VoteSort } from './types';
 import { ErrorFromResponse } from './types';
 import { InsightMetrics } from './insights';
 import { Thread } from './thread';
@@ -24,6 +24,9 @@ import { StateStore } from './store';
 import type { MessageComposer } from './messageComposer';
 import type { AbstractOfflineDB } from './offline-support';
 type MessageComposerTearDownFunction = () => void;
+export type QueryChannelsResponseWithChannels = Omit<QueryChannelsAPIResponse, 'channels'> & {
+    channels: Channel[];
+};
 type MessageComposerSetupFunction = ({ composer, }: {
     composer: MessageComposer;
 }) => void | MessageComposerTearDownFunction;
@@ -513,7 +516,29 @@ export declare class StreamChat {
      */
     queryMessageFlags(filterConditions?: MessageFlagsFilters, options?: MessageFlagsPaginationOptions): Promise<MessageFlagsResponse>;
     /**
-     * queryChannelsRequest - Queries channels and returns the raw response
+     * queryChannelsRequestWithResponse - Queries channels and returns the full API response
+     * including top-level metadata such as `predefined_filter`.
+     *
+     * This exists as a compatibility bridge, as changing `queryChannelsRequest()` to return
+     * `QueryChannelsAPIResponse` would be a breaking change because it currently returns
+     * only the channel list. In the next major release, the request/response APIs should
+     * be consolidated so callers can access the full response through the primary API.
+     *
+     * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
+     * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
+     * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{last_updated: -1}, {created_at: 1}]
+     * @param {ChannelOptions} [options] Options object. Can include predefined_filter, filter_values, and sort_values for using predefined filters.
+     *
+     * @return {Promise<QueryChannelsAPIResponse>} full search channels response
+     */
+    queryChannelsRequestWithResponse(filterConditions: ChannelFilters, sort?: ChannelSort, options?: ChannelOptions): Promise<QueryChannelsAPIResponse>;
+    /**
+     * queryChannelsRequest - Queries channels and returns the raw channel response list.
+     *
+     * This preserves the historical return shape for backwards compatibility. Use
+     * `queryChannelsRequestWithResponse()` when response level metadata such as
+     * `predefined_filter` is needed. In the next major release these APIs should be
+     * consolidated into a single full-response API.
      *
      * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
      * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
@@ -533,10 +558,14 @@ export declare class StreamChat {
      * @param {ChannelStateOptions} [stateOptions] State options object. These options will only be used for state management and won't be sent in the request.
      * - stateOptions.skipInitialization - Skips the initialization of the state for the channels matching the ids in the list.
      * - stateOptions.skipHydration - Skips returning the channels as instances of the Channel class and rather returns the raw query response.
+     * - stateOptions.withResponse - Returns the full query response with hydrated channels. This is a compatibility bridge for internal callers that need response-level metadata while the default return value remains `Channel[]`.
      *
      * @return {Promise<Array<Channel>>} search channels response
      */
-    queryChannels(filterConditions: ChannelFilters, sort?: ChannelSort, options?: ChannelOptions, stateOptions?: ChannelStateOptions): Promise<Channel[]>;
+    queryChannels(filterConditions: ChannelFilters, sort: ChannelSort, options: ChannelOptions, stateOptions: ChannelStateOptions & {
+        withResponse: true;
+    }): Promise<QueryChannelsResponseWithChannels>;
+    queryChannels(filterConditions?: ChannelFilters, sort?: ChannelSort, options?: ChannelOptions, stateOptions?: ChannelStateOptions): Promise<Channel[]>;
     /**
      * queryReactions - Query reactions
      *

package/dist/types/types.d.ts

@@ -949,6 +949,15 @@ export type ChannelStateOptions = {
     offlineMode?: boolean;
     skipInitialization?: string[];
     skipHydration?: boolean;
+    /**
+     * Returns the full query response with hydrated channels from `queryChannels()`.
+     *
+     * This is a compatibility bridge for internal callers that need response level
+     * metadata such as `predefined_filter`. The default `queryChannels()` return value
+     * remains `Channel[]` to avoid a breaking change. This should be folded into a
+     * single full response API in the next major release.
+     */
+    withResponse?: boolean;
 };
 export type CreateChannelOptions = {
     automod?: ChannelConfigAutomod;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stream-chat",
-  "version": "9.44.1",
+  "version": "9.44.2",
   "description": "JS SDK for the Stream Chat API",
   "homepage": "https://getstream.io/chat/",
   "author": {

package/src/channel_manager.ts

@@ -1,10 +1,11 @@
-import type { StreamChat } from './client';
+import type { QueryChannelsResponseWithChannels, StreamChat } from './client';
 import type {
   ChannelFilters,
   ChannelOptions,
   ChannelSort,
   ChannelStateOptions,
   Event,
+  QueryChannelsAPIResponse,
 } from './types';
 import type { ValueOrPatch } from './store';
 import { isPatch, StateStore } from './store';
@@ -34,6 +35,8 @@ export type ChannelManagerPagination = {
   isLoading: boolean;
   isLoadingNext: boolean;
   options: ChannelOptions;
+  responseFilters?: ChannelFilters;
+  responseSort?: ChannelSort;
   sort: ChannelSort;
 };
 
@@ -133,9 +136,14 @@ export type ChannelManagerOptions = {
   lockChannelOrder?: boolean;
 };
 
+export type QueryChannelsRequestOutput = Channel[] | QueryChannelsResponseWithChannels;
+
 export type QueryChannelsRequestType = (
-  ...params: Parameters<StreamChat['queryChannels']>
-) => Promise<Channel[]>;
+  filters: ChannelFilters,
+  sort?: ChannelSort,
+  options?: ChannelOptions,
+  stateOptions?: ChannelStateOptions,
+) => Promise<QueryChannelsRequestOutput>;
 
 export const DEFAULT_CHANNEL_MANAGER_OPTIONS = {
   abortInFlightQuery: false,
@@ -152,6 +160,54 @@ export const DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS = {
   offset: 0,
 };
 
+const mapPredefinedFilterSortToChannelSort = (
+  sort: NonNullable<QueryChannelsAPIResponse['predefined_filter']>['sort'],
+): ChannelSort =>
+  (sort ?? []).map(({ direction = 1, field }) => ({
+    [field]: direction,
+  })) as ChannelSort;
+
+const getResponsePaginationParams = ({
+  queryChannelsResponse,
+  sort,
+}: {
+  queryChannelsResponse?: Pick<QueryChannelsAPIResponse, 'predefined_filter'>;
+  sort: ChannelSort;
+}): Pick<ChannelManagerPagination, 'responseFilters' | 'responseSort'> => {
+  const predefinedFilter = queryChannelsResponse?.predefined_filter;
+
+  if (!predefinedFilter) {
+    return {};
+  }
+
+  return {
+    responseFilters: predefinedFilter.filter as ChannelFilters,
+    responseSort:
+      predefinedFilter.sort !== undefined
+        ? mapPredefinedFilterSortToChannelSort(predefinedFilter.sort)
+        : sort,
+  };
+};
+
+const getResponseFiltersAndSort = (
+  pagination: ChannelManagerPagination,
+): Pick<ChannelManagerPagination, 'filters' | 'sort'> => ({
+  filters: pagination.responseFilters ?? pagination.filters,
+  sort: pagination.responseSort ?? pagination.sort,
+});
+
+const omitResponsePaginationParams = (pagination: ChannelManagerPagination) => {
+  const paginationWithoutResponseParams = { ...pagination };
+  delete paginationWithoutResponseParams.responseFilters;
+  delete paginationWithoutResponseParams.responseSort;
+
+  return paginationWithoutResponseParams;
+};
+
+const isQueryChannelsResponseWithChannels = (
+  response: QueryChannelsRequestOutput,
+): response is QueryChannelsResponseWithChannels => !Array.isArray(response);
+
 /**
  * A class that manages a list of channels and changes it based on configuration and WS events. The
  * list of channels is reactive as well as the pagination and it can be subscribed to for state updates.
@@ -279,23 +335,39 @@ export class ChannelManager extends WithSubscriptions {
       ...options,
     };
     try {
-      const channels = await this.queryChannelsRequest(
+      const queryChannelsResponse = await this.queryChannelsRequest(
         filters,
         sort,
         options,
-        stateOptions,
+        { ...stateOptions, withResponse: true },
       );
+      const channels = isQueryChannelsResponseWithChannels(queryChannelsResponse)
+        ? queryChannelsResponse.channels
+        : queryChannelsResponse;
       const newOffset = offset + (channels?.length ?? 0);
       const newOptions = { ...options, offset: newOffset };
       const { pagination } = this.state.getLatestValue();
+      const responsePaginationParams = getResponsePaginationParams({
+        queryChannelsResponse: isQueryChannelsResponseWithChannels(queryChannelsResponse)
+          ? queryChannelsResponse
+          : undefined,
+        sort,
+      });
+      const paginationWithoutResponseParams = omitResponsePaginationParams(pagination);
 
       this.state.partialNext({
         channels,
         pagination: {
-          ...pagination,
+          // Drop response derived filter/sort from the previous query before applying
+          // the current response. Non predefined queries do not return this metadata,
+          // so keeping the old values would make later WS mutations use stale
+          // predefined filter semantics. Also the predefined_filter might change, producing
+          // a different combination as well so we always need to first clean up.
+          ...paginationWithoutResponseParams,
           hasNext: (channels?.length ?? 0) >= (limit ?? 1),
           isLoading: false,
           options: newOptions,
+          ...responsePaginationParams,
         },
         initialized: true,
         error: undefined,
@@ -368,7 +440,7 @@ export class ChannelManager extends WithSubscriptions {
       this.state.next((currentState) => ({
         ...currentState,
         pagination: {
-          ...currentState.pagination,
+          ...omitResponsePaginationParams(currentState.pagination),
           isLoading: true,
           isLoadingNext: false,
           filters,
@@ -434,12 +506,15 @@ export class ChannelManager extends WithSubscriptions {
       this.state.partialNext({
         pagination: { ...pagination, isLoading: false, isLoadingNext: true },
       });
-      const nextChannels = await this.queryChannelsRequest(
+      const queryChannelsResponse = await this.queryChannelsRequest(
         filters,
         sort,
         options,
         this.stateOptions,
       );
+      const nextChannels = isQueryChannelsResponseWithChannels(queryChannelsResponse)
+        ? queryChannelsResponse.channels
+        : queryChannelsResponse;
       const { channels } = this.state.getLatestValue();
       const newOffset = offset + (nextChannels?.length ?? 0);
       const newOptions = { ...options, offset: newOffset };
@@ -498,7 +573,7 @@ export class ChannelManager extends WithSubscriptions {
       return;
     }
 
-    const { sort } = pagination ?? {};
+    const { sort } = getResponseFiltersAndSort(pagination);
 
     this.setChannels(
       promoteChannel({
@@ -535,7 +610,7 @@ export class ChannelManager extends WithSubscriptions {
     if (!channels) {
       return;
     }
-    const { filters, sort } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const channelType = event.channel_type;
     const channelId = event.channel_id;
@@ -594,7 +669,7 @@ export class ChannelManager extends WithSubscriptions {
     });
 
     const { channels, pagination } = this.state.getLatestValue();
-    const { filters, sort } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
     const isTargetChannelArchived = isChannelArchived(channel);
@@ -631,7 +706,7 @@ export class ChannelManager extends WithSubscriptions {
     });
 
     const { channels, pagination } = this.state.getLatestValue();
-    const { sort, filters } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
     const isTargetChannelArchived = isChannelArchived(channel);
@@ -658,7 +733,7 @@ export class ChannelManager extends WithSubscriptions {
 
   private memberUpdatedHandler = (event: Event) => {
     const { pagination, channels } = this.state.getLatestValue();
-    const { filters, sort } = pagination;
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
     if (
       !event.member?.user ||
       event.member.user.id !== this.client.userID ||

package/src/client.ts

@@ -281,6 +281,13 @@ function isString(x: unknown): x is string {
 
 type MessageComposerTearDownFunction = () => void;
 
+export type QueryChannelsResponseWithChannels = Omit<
+  QueryChannelsAPIResponse,
+  'channels'
+> & {
+  channels: Channel[];
+};
+
 type MessageComposerSetupFunction = ({
   composer,
 }: {
@@ -1888,20 +1895,26 @@ export class StreamChat {
   }
 
   /**
-   * queryChannelsRequest - Queries channels and returns the raw response
+   * queryChannelsRequestWithResponse - Queries channels and returns the full API response
+   * including top-level metadata such as `predefined_filter`.
+   *
+   * This exists as a compatibility bridge, as changing `queryChannelsRequest()` to return
+   * `QueryChannelsAPIResponse` would be a breaking change because it currently returns
+   * only the channel list. In the next major release, the request/response APIs should
+   * be consolidated so callers can access the full response through the primary API.
    *
    * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
    * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
    * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{last_updated: -1}, {created_at: 1}]
    * @param {ChannelOptions} [options] Options object. Can include predefined_filter, filter_values, and sort_values for using predefined filters.
    *
-   * @return {Promise<Array<ChannelAPIResponse>>} search channels response
+   * @return {Promise<QueryChannelsAPIResponse>} full search channels response
    */
-  async queryChannelsRequest(
+  async queryChannelsRequestWithResponse(
     filterConditions: ChannelFilters,
     sort: ChannelSort = [],
     options: ChannelOptions = {},
-  ) {
+  ): Promise<QueryChannelsAPIResponse> {
     const defaultOptions: ChannelOptions = {
       state: true,
       watch: true,
@@ -1934,9 +1947,33 @@ export class StreamChat {
           ...restOptions,
         };
 
-    const data = await this.post<QueryChannelsAPIResponse>(
-      this.baseURL + '/channels',
-      payload,
+    return await this.post<QueryChannelsAPIResponse>(this.baseURL + '/channels', payload);
+  }
+
+  /**
+   * queryChannelsRequest - Queries channels and returns the raw channel response list.
+   *
+   * This preserves the historical return shape for backwards compatibility. Use
+   * `queryChannelsRequestWithResponse()` when response level metadata such as
+   * `predefined_filter` is needed. In the next major release these APIs should be
+   * consolidated into a single full-response API.
+   *
+   * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
+   * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
+   * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{last_updated: -1}, {created_at: 1}]
+   * @param {ChannelOptions} [options] Options object. Can include predefined_filter, filter_values, and sort_values for using predefined filters.
+   *
+   * @return {Promise<Array<ChannelAPIResponse>>} search channels response
+   */
+  async queryChannelsRequest(
+    filterConditions: ChannelFilters,
+    sort: ChannelSort = [],
+    options: ChannelOptions = {},
+  ) {
+    const data = await this.queryChannelsRequestWithResponse(
+      filterConditions,
+      sort,
+      options,
     );
 
     // FIXME: In the next major release, return the full QueryChannelsAPIResponse
@@ -1955,16 +1992,34 @@ export class StreamChat {
    * @param {ChannelStateOptions} [stateOptions] State options object. These options will only be used for state management and won't be sent in the request.
    * - stateOptions.skipInitialization - Skips the initialization of the state for the channels matching the ids in the list.
    * - stateOptions.skipHydration - Skips returning the channels as instances of the Channel class and rather returns the raw query response.
+   * - stateOptions.withResponse - Returns the full query response with hydrated channels. This is a compatibility bridge for internal callers that need response-level metadata while the default return value remains `Channel[]`.
    *
    * @return {Promise<Array<Channel>>} search channels response
    */
+  async queryChannels(
+    filterConditions: ChannelFilters,
+    sort: ChannelSort,
+    options: ChannelOptions,
+    stateOptions: ChannelStateOptions & { withResponse: true },
+  ): Promise<QueryChannelsResponseWithChannels>;
+  async queryChannels(
+    filterConditions?: ChannelFilters,
+    sort?: ChannelSort,
+    options?: ChannelOptions,
+    stateOptions?: ChannelStateOptions,
+  ): Promise<Channel[]>;
   async queryChannels(
     filterConditions: ChannelFilters,
     sort: ChannelSort = [],
     options: ChannelOptions = {},
     stateOptions: ChannelStateOptions = {},
-  ) {
-    const channels = await this.queryChannelsRequest(filterConditions, sort, options);
+  ): Promise<Channel[] | QueryChannelsResponseWithChannels> {
+    const queryChannelsResponse = await this.queryChannelsRequestWithResponse(
+      filterConditions,
+      sort,
+      options,
+    );
+    const channels = queryChannelsResponse.channels;
 
     this.dispatchEvent({
       type: 'channels.queried',
@@ -1980,7 +2035,16 @@ export class StreamChat {
       });
     }
 
-    return this.hydrateActiveChannels(channels, stateOptions, options);
+    const hydratedChannels = this.hydrateActiveChannels(channels, stateOptions, options);
+
+    if (stateOptions.withResponse) {
+      return {
+        ...queryChannelsResponse,
+        channels: hydratedChannels,
+      };
+    }
+
+    return hydratedChannels;
   }
 
   /**

package/src/types.ts

@@ -1111,6 +1111,15 @@ export type ChannelStateOptions = {
   offlineMode?: boolean;
   skipInitialization?: string[];
   skipHydration?: boolean;
+  /**
+   * Returns the full query response with hydrated channels from `queryChannels()`.
+   *
+   * This is a compatibility bridge for internal callers that need response level
+   * metadata such as `predefined_filter`. The default `queryChannels()` return value
+   * remains `Channel[]` to avoid a breaking change. This should be folded into a
+   * single full response API in the next major release.
+   */
+  withResponse?: boolean;
 };
 
 export type CreateChannelOptions = {