stream-chat 9.44.1 → 9.45.0

package/src/messageComposer/middleware/textComposer/types.ts

@@ -16,9 +16,73 @@ export type BaseSuggestion = {
 export type CommandSuggestionDisabledReason = 'editing' | 'quoted_message';
 
 export type CommandSuggestion = BaseSuggestion & CommandResponse;
-export type UserSuggestion = BaseSuggestion & UserResponse & TokenizationPayload;
+export type UserSuggestion = BaseSuggestion &
+  UserResponse &
+  TokenizationPayload & {
+    mentionType: 'user';
+  };
+export type ChannelMentionSuggestion = BaseSuggestion &
+  TokenizationPayload & {
+    mentionType: 'channel';
+    name: 'channel';
+  };
+export type HereMentionSuggestion = BaseSuggestion &
+  TokenizationPayload & {
+    mentionType: 'here';
+    name: 'here';
+  };
+export type RoleMentionSuggestion = BaseSuggestion &
+  TokenizationPayload & {
+    mentionType: 'role';
+    name: string;
+  };
+export type UserGroupMentionSuggestion = BaseSuggestion &
+  TokenizationPayload & {
+    description?: string;
+    memberCount?: number;
+    mentionType: 'user_group';
+    name: string;
+  };
+export type MentionSuggestion =
+  | UserSuggestion
+  | ChannelMentionSuggestion
+  | HereMentionSuggestion
+  | RoleMentionSuggestion
+  | UserGroupMentionSuggestion;
+
 export type CustomValidSuggestion = BaseSuggestion & CustomTextComposerSuggestion;
-export type Suggestion = CommandSuggestion | UserSuggestion | CustomValidSuggestion;
+export type Suggestion = CommandSuggestion | MentionSuggestion | CustomValidSuggestion;
+
+export type UserMentionEntity = UserResponse & {
+  mentionType: 'user';
+};
+export type ChannelMentionEntity = {
+  id: 'channel';
+  mentionType: 'channel';
+  name: 'channel';
+};
+export type HereMentionEntity = {
+  id: 'here';
+  mentionType: 'here';
+  name: 'here';
+};
+export type RoleMentionEntity = {
+  id: string;
+  mentionType: 'role';
+  name?: string;
+};
+export type UserGroupMentionEntity = {
+  id: string;
+  mentionType: 'user_group';
+  name?: string;
+};
+
+export type MentionEntity =
+  | UserMentionEntity
+  | ChannelMentionEntity
+  | HereMentionEntity
+  | RoleMentionEntity
+  | UserGroupMentionEntity;
 
 export type TextComposerStateSnapshot = TextComposerState;
 
@@ -55,7 +119,11 @@ export type Suggestions<T extends Suggestion = Suggestion> = {
 export type TextSelection = { end: number; start: number };
 
 export type TextComposerState<T extends Suggestion = Suggestion> = {
+  /**
+   * @deprecated Use `mentions` instead.
+   */
   mentionedUsers: UserResponse[];
+  mentions?: MentionEntity[];
   selection: TextSelection;
   text: string;
   command?: CommandResponse | null;

package/src/messageComposer/textComposer.ts

@@ -5,11 +5,18 @@ import type { TextComposerMiddlewareExecutorState } from './middleware';
 import type { TextComposerSuggestion } from './middleware/textComposer/types';
 import type { TextSelection } from './middleware/textComposer/types';
 import type {
+  MentionEntity,
   TextComposerCommandActivationEffect,
   TextComposerState,
   TextComposerStateSnapshot,
+  UserMentionEntity,
 } from './middleware/textComposer/types';
 import type { Suggestions } from './middleware/textComposer/types';
+import {
+  isUserMentionEntity,
+  mentionEntityToUserResponse,
+  userResponseToMentionEntity,
+} from './middleware/textComposer/mentionUtils';
 import type { MessageComposer } from './messageComposer';
 import type { CommandResponse, DraftMessage, LocalMessage, UserResponse } from '../types';
 
@@ -34,6 +41,71 @@ export const textIsEmpty = (text: string) => {
   );
 };
 
+const getInitialMentions = (message?: DraftMessage | LocalMessage): MentionEntity[] => {
+  if (!message) return [];
+
+  const mentions: MentionEntity[] = (message.mentioned_users ?? []).map(
+    (item: string | UserResponse) =>
+      typeof item === 'string'
+        ? ({ id: item, mentionType: 'user' } as UserMentionEntity)
+        : { ...item, mentionType: 'user' },
+  );
+
+  if (message.mentioned_channel) {
+    mentions.push({
+      id: 'channel',
+      mentionType: 'channel',
+      name: 'channel',
+    });
+  }
+
+  if (message.mentioned_here) {
+    mentions.push({
+      id: 'here',
+      mentionType: 'here',
+      name: 'here',
+    });
+  }
+
+  if (message.mentioned_roles?.length) {
+    mentions.push(
+      ...message.mentioned_roles.map((role) => ({
+        id: role,
+        mentionType: 'role' as const,
+        name: role,
+      })),
+    );
+  }
+
+  if (message.mentioned_groups?.length) {
+    mentions.push(
+      ...message.mentioned_groups.map((group) => ({
+        id: group.id,
+        mentionType: 'user_group' as const,
+        name: group.name,
+      })),
+    );
+  } else if (message.mentioned_group_ids?.length) {
+    // Composer rehydration can still receive draft/local request-shaped data, where
+    // group mentions are represented only by ids even though response/render paths use
+    // `mentioned_groups` for presentation metadata.
+    mentions.push(
+      ...message.mentioned_group_ids.map((groupId) => ({
+        id: groupId,
+        mentionType: 'user_group' as const,
+      })),
+    );
+  }
+
+  return mentions;
+};
+
+const isSameMentionEntity = (first: MentionEntity, second: MentionEntity) =>
+  first.id === second.id && first.mentionType === second.mentionType;
+
+const getMentionsFromState = (state: TextComposerState) =>
+  state.mentions ?? state.mentionedUsers.map(userResponseToMentionEntity);
+
 const initState = ({
   composer,
   message,
@@ -46,15 +118,20 @@ const initState = ({
     return {
       command: null,
       mentionedUsers: [],
+      mentions: [],
       text,
       selection: { start: text.length, end: text.length },
     };
   }
   const text = message.text ?? '';
-  return {
-    mentionedUsers: (message.mentioned_users ?? []).map((item: string | UserResponse) =>
+  const mentions = getInitialMentions(message);
+  const mentionedUsers = (message.mentioned_users ?? []).map(
+    (item: string | UserResponse) =>
       typeof item === 'string' ? ({ id: item } as UserResponse) : item,
-    ),
+  );
+  return {
+    mentionedUsers,
+    mentions,
     text,
     selection: { start: text.length, end: text.length },
   };
@@ -134,6 +211,10 @@ export class TextComposer {
     return this.state.getLatestValue().mentionedUsers;
   }
 
+  get mentions() {
+    return getMentionsFromState(this.state.getLatestValue());
+  }
+
   get selection() {
     return this.state.getLatestValue().selection;
   }
@@ -161,7 +242,22 @@ export class TextComposer {
   };
 
   setMentionedUsers(users: UserResponse[]) {
-    this.state.partialNext({ mentionedUsers: users });
+    const nonUserMentions = this.mentions.filter(
+      (entity) => !isUserMentionEntity(entity),
+    );
+    this.state.partialNext({
+      mentionedUsers: users,
+      mentions: [...nonUserMentions, ...users.map(userResponseToMentionEntity)],
+    });
+  }
+
+  setMentions(entities: MentionEntity[]) {
+    this.state.partialNext({
+      mentionedUsers: entities
+        .filter(isUserMentionEntity)
+        .map(mentionEntityToUserResponse),
+      mentions: entities,
+    });
   }
 
   clearCommand() {
@@ -174,27 +270,75 @@ export class TextComposer {
     });
   }
 
+  /**
+   * @deprecated Use `upsertMentionEntity({ ...user, mentionType: 'user' })` instead.
+   */
   upsertMentionedUser = (user: UserResponse) => {
     const mentionedUsers = [...this.mentionedUsers];
-    const existingUserIndex = mentionedUsers.findIndex((u) => u.id === user.id);
+    const existingUserIndex = mentionedUsers.findIndex((entity) => entity.id === user.id);
     if (existingUserIndex >= 0) {
       mentionedUsers.splice(existingUserIndex, 1, user);
-      this.state.partialNext({ mentionedUsers });
+      this.setMentionedUsers(mentionedUsers);
     } else {
       mentionedUsers.push(user);
-      this.state.partialNext({ mentionedUsers });
+      this.setMentionedUsers(mentionedUsers);
     }
   };
 
+  /**
+   * @deprecated Use `getMentionEntity('user', userId)` instead.
+   */
   getMentionedUser = (userId: string) =>
-    this.state.getLatestValue().mentionedUsers.find((u: UserResponse) => u.id === userId);
+    this.mentionedUsers.find((user) => user.id === userId);
 
+  /**
+   * @deprecated Use `removeMentionEntity('user', userId)` instead.
+   */
   removeMentionedUser = (userId: string) => {
-    const existingUserIndex = this.mentionedUsers.findIndex((u) => u.id === userId);
+    const existingUserIndex = this.mentionedUsers.findIndex(
+      (entity) => entity.id === userId,
+    );
     if (existingUserIndex === -1) return;
     const mentionedUsers = [...this.mentionedUsers];
     mentionedUsers.splice(existingUserIndex, 1);
-    this.state.partialNext({ mentionedUsers });
+    this.setMentionedUsers(mentionedUsers);
+  };
+
+  upsertMentionEntity = (entity: MentionEntity) => {
+    const mentions = [...this.mentions];
+    const existingEntityIndex = mentions.findIndex((currentEntity) =>
+      isSameMentionEntity(currentEntity, entity),
+    );
+
+    if (existingEntityIndex >= 0) {
+      mentions.splice(existingEntityIndex, 1, entity);
+    } else {
+      mentions.push(entity);
+    }
+
+    this.setMentions(mentions);
+  };
+
+  getMentionEntity = (
+    mentionType: MentionEntity['mentionType'],
+    id: MentionEntity['id'],
+  ) =>
+    this.mentions.find(
+      (entity) => entity.mentionType === mentionType && entity.id === id,
+    );
+
+  removeMentionEntity = (
+    mentionType: MentionEntity['mentionType'],
+    id: MentionEntity['id'],
+  ) => {
+    const existingEntityIndex = this.mentions.findIndex(
+      (entity) => entity.mentionType === mentionType && entity.id === id,
+    );
+    if (existingEntityIndex === -1) return;
+
+    const mentions = [...this.mentions];
+    mentions.splice(existingEntityIndex, 1);
+    this.setMentions(mentions);
   };
 
   setCommand = (command: CommandResponse | null) => {

package/src/pagination/UserGroupPaginator.ts

@@ -0,0 +1,93 @@
+import { BasePaginator } from './BasePaginator';
+import type {
+  PaginationQueryParams,
+  PaginationQueryReturnValue,
+  PaginatorOptions,
+  PaginatorState,
+} from './BasePaginator';
+import type { QueryUserGroupsOptions, UserGroupResponse } from '../types';
+import type { StreamChat } from '../client';
+
+type UserGroupListCursor = {
+  created_at_gt: string;
+  id_gt: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const decodeCursor = <TCursor extends object>(cursor: string | null | undefined) => {
+  if (!cursor) return undefined;
+
+  try {
+    const parsed = JSON.parse(cursor);
+    return isRecord(parsed) ? (parsed as TCursor) : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Paginates user-group listing through `/usergroups`.
+ *
+ * This entity only supports forward cursor pagination via `created_at_gt` and `id_gt`.
+ * Previous-page pagination is not available because the API does not expose a backward cursor.
+ */
+export class UserGroupPaginator extends BasePaginator<UserGroupResponse> {
+  private client: StreamChat;
+  protected _teamId: string | undefined;
+
+  constructor(client: StreamChat, options?: PaginatorOptions) {
+    super(options);
+    this.client = client;
+  }
+
+  get initialState(): PaginatorState<UserGroupResponse> {
+    return {
+      ...super.initialState,
+      hasPrev: false,
+    };
+  }
+
+  get teamId() {
+    return this._teamId;
+  }
+
+  set teamId(teamId: string | undefined) {
+    if (teamId === this._teamId) return;
+    this._teamId = teamId;
+    this.resetState();
+  }
+
+  private buildNextCursor = (items: UserGroupResponse[]) => {
+    if (items.length < this.pageSize) return undefined;
+    const lastItem = items[items.length - 1];
+    if (!lastItem) return undefined;
+
+    return JSON.stringify({
+      created_at_gt: lastItem.created_at,
+      id_gt: lastItem.id,
+    } satisfies UserGroupListCursor);
+  };
+
+  query = async ({
+    direction,
+  }: PaginationQueryParams): Promise<PaginationQueryReturnValue<UserGroupResponse>> => {
+    if (direction === 'prev') {
+      return { items: [] };
+    }
+
+    const cursor = decodeCursor<UserGroupListCursor>(this.cursor?.next);
+    const options: QueryUserGroupsOptions = {
+      limit: this.pageSize,
+      ...(this.teamId ? { team_id: this.teamId } : {}),
+      ...(cursor?.id_gt ? { id_gt: cursor.id_gt } : {}),
+      ...(cursor?.created_at_gt ? { created_at_gt: cursor.created_at_gt } : {}),
+    };
+
+    const { user_groups: items } = await this.client.queryUserGroups(options);
+    return { items, next: this.buildNextCursor(items) };
+  };
+
+  filterQueryResults = (items: UserGroupResponse[]) => items;
+}

package/src/pagination/index.ts

@@ -1,3 +1,4 @@
 export * from './BasePaginator';
 export * from './FilterBuilder';
 export * from './ReminderPaginator';
+export * from './UserGroupPaginator';

package/src/permissions.ts

@@ -56,6 +56,7 @@ export const DenyAll = new Permission(
   Deny,
 );
 
+// Fixme: rename to RoleName with next major release
 export type Role =
   | 'admin'
   | 'user'

package/src/types.ts

@@ -133,6 +133,7 @@ export type AppSettingsAPIResponse = APIResponse & {
     async_url_enrich_enabled?: boolean;
     auto_translation_enabled?: boolean;
     before_message_send_hook_url?: string;
+    before_message_send_hook_attempt_timeout_ms?: number;
     campaign_enabled?: boolean;
     cdn_expiration_seconds?: number;
     custom_action_handler_url?: string;
@@ -754,6 +755,8 @@ export type MessageResponseBase = MessageBase & {
   mentioned_users?: UserResponse[];
   mentioned_channel?: boolean;
   mentioned_here?: boolean;
+  mentioned_group_ids?: string[];
+  mentioned_groups?: UserGroupResponse[];
   mentioned_roles?: string[];
   message_text_updated_at?: string;
   moderation?: ModerationResponse; // present only with Moderation v2
@@ -905,6 +908,35 @@ export type SearchAPIResponse = APIResponse & {
   results_warning?: SearchWarning | null;
 };
 
+export type RoleResponse = {
+  name: Role;
+  custom: boolean;
+  scopes: string[];
+  created_at: string;
+  updated_at: string;
+};
+
+export type CreateRoleAPIResponse = APIResponse & {
+  role: RoleResponse;
+};
+
+export type ListRolesAPIResponse = APIResponse & {
+  roles: RoleResponse[];
+};
+
+export type SearchRolesAPIResponse = APIResponse & {
+  roles: RoleResponse[];
+};
+
+export type SearchRolesOptions = {
+  query: string;
+  include_global_roles?: boolean;
+  limit?: number;
+  name_gt?: string;
+  // If not provided, the default is search performed both in user-assignable + channel-assignable roles
+  role_type?: 'user' | 'channel';
+};
+
 export type SearchWarning = {
   channel_search_cids: string[];
   channel_search_count: number;
@@ -1111,6 +1143,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 = {
@@ -2394,6 +2435,7 @@ export type AppSettings = {
   async_url_enrich_enabled?: boolean;
   auto_translation_enabled?: boolean;
   before_message_send_hook_url?: string;
+  before_message_send_hook_attempt_timeout_ms?: number;
   cdn_expiration_seconds?: number;
   custom_action_handler_url?: string;
   disable_auth_checks?: boolean;
@@ -2892,6 +2934,9 @@ export type Message = Partial<
     mentioned_users: string[];
     shared_location?: StaticLocationPayload | LiveLocationPayload;
     mentioned_channel?: boolean;
+    mentioned_here?: boolean;
+    mentioned_group_ids?: string[];
+    mentioned_roles?: string[];
   }
 >;
 
@@ -3162,8 +3207,15 @@ export type TypingStartEvent = Event;
 
 export type ReservedUpdatedMessageFields = keyof typeof RESERVED_UPDATED_MESSAGE_FIELDS;
 
-export type UpdatedMessage = Omit<MessageResponse, ReservedUpdatedMessageFields> & {
+export type UpdatedMessage = Omit<
+  MessageResponse,
+  ReservedUpdatedMessageFields | 'mentioned_groups'
+> & {
   mentioned_users?: string[];
+  mentioned_channel?: boolean;
+  mentioned_here?: boolean;
+  mentioned_group_ids?: string[];
+  mentioned_roles?: string[];
   type?: MessageLabel;
 };
 
@@ -4459,7 +4511,10 @@ export type QueryDraftsResponse = APIResponse & {
   drafts: DraftResponse[];
 } & Omit<Pager, 'limit'>;
 
-export type DraftMessagePayload = PartializeKeys<DraftMessage, 'id'> & {
+export type DraftMessagePayload = PartializeKeys<
+  Omit<DraftMessage, 'mentioned_groups'>,
+  'id'
+> & {
   user_id?: string;
 };
 
@@ -4470,6 +4525,11 @@ export type DraftMessage = {
   custom?: {};
   html?: string;
   mentioned_users?: string[];
+  mentioned_channel?: boolean;
+  mentioned_here?: boolean;
+  mentioned_group_ids?: string[];
+  mentioned_groups?: UserGroupResponse[];
+  mentioned_roles?: string[];
   mml?: string;
   parent_id?: string;
   poll_id?: string;
@@ -4687,6 +4747,105 @@ export type QueryRemindersResponse = {
   next?: string;
 };
 
+export type UserGroupMemberResponse = {
+  group_id: string;
+  user_id: string;
+  is_admin: boolean;
+  created_at: string;
+};
+
+export type UserGroupResponse = {
+  id: string;
+  name: string;
+  created_at: string;
+  updated_at: string;
+  description?: string;
+  team_id?: string;
+  members?: UserGroupMemberResponse[];
+  created_by?: string;
+};
+
+export type CreateUserGroupOptions = {
+  /** Human-readable user group name */
+  name: string;
+  /** Optional user group description shown to members */
+  description?: string;
+  /** Optional custom user group ID. If omitted, the backend generates one */
+  id?: string;
+  /** Optional list of user IDs to add as members when the group is created */
+  member_ids?: string[];
+  /** Optional team ID that scopes the user group to a specific team */
+  team_id?: string;
+};
+
+export type CreateUserGroupResponse = APIResponse & {
+  user_group: UserGroupResponse;
+};
+
+export type GetUserGroupOptions = {
+  team_id?: string;
+};
+
+export type GetUserGroupResponse = APIResponse & {
+  user_group: UserGroupResponse;
+};
+
+export type QueryUserGroupsOptions = {
+  limit?: number;
+  id_gt?: string;
+  created_at_gt?: string;
+  team_id?: string;
+};
+
+export type QueryUserGroupsResponse = APIResponse & {
+  user_groups: UserGroupResponse[];
+};
+
+export type SearchUserGroupsOptions = {
+  query: string;
+  limit?: number;
+  id_gt?: string;
+  name_gt?: string;
+  team_id?: string;
+};
+
+export type SearchUserGroupsResponse = APIResponse & {
+  user_groups: UserGroupResponse[];
+};
+
+export type UpdateUserGroupOptions = {
+  description?: string;
+  name?: string;
+  team_id?: string;
+};
+
+export type UpdateUserGroupResponse = APIResponse & {
+  user_group: UserGroupResponse;
+};
+
+export type DeleteUserGroupOptions = {
+  team_id?: string;
+};
+
+export type AddUserGroupMembersOptions = {
+  member_ids: string[];
+  as_admin?: boolean;
+  team_id?: string;
+};
+
+export type AddUserGroupMembersResponse = APIResponse & {
+  user_group: UserGroupResponse;
+};
+
+export type RemoveUserGroupMembersOptions = {
+  member_ids: string[];
+  team_id?: string;
+};
+
+export type RemoveUserGroupMembersResponse = APIResponse & {
+  user_group: UserGroupResponse;
+};
+
 export type HookType = 'webhook' | 'sqs' | 'sns' | 'pending_message';
 
 export type EventHook = {

package/src/utils.ts

@@ -381,6 +381,7 @@ export const localMessageToNewMessagePayload = (localMessage: LocalMessage): Mes
     command,
     html,
     i18n,
+    mentioned_groups,
     quoted_message,
     mentioned_users,
     // Message content related fields