refactor(llc, ui): introduce 'ChannelCapability' and deprecate 'PermissionType' (#2155)

* refactor(llc, ui): introduce 'ChannelCapability' and deprecate 'PermissionType'

* chore: update CHANGELOG.md

* test: add channel capability extension tests

* Apply suggestions from code review

* chore: minor changes

Author: xsahil03x

packages/stream_chat/CHANGELOG.md

@@ -1,3 +1,19 @@
+## Upcoming
+
+✅ Added
+
+- Added new helper extensions on `Channel` to provide a convenient way to check if the current user
+  has specific capabilities in a channel.
+
+  ```dart
+  final canSendMessage = channel.canSendMessage;
+  final canSendReaction = channel.canSendReaction;
+  ```
+
+🔄 Changed
+
+- Deprecated `PermissionType` in favor of `ChannelCapability`.
+
 ## 9.6.0
 
 🐞 Fixed

packages/stream_chat/lib/src/client/channel.dart

@@ -270,7 +270,7 @@ class Channel {
     final userLastMessageAt = currentUserLastMessageAt;
     if (userLastMessageAt == null) return 0;
 
-    if (ownCapabilities.contains(PermissionType.skipSlowMode)) return 0;
+    if (canSkipSlowMode) return 0;
 
     final currentTime = DateTime.timestamp();
     final elapsedTime = currentTime.difference(userLastMessageAt).inSeconds;
@@ -413,11 +413,11 @@ class Channel {
   }
 
   /// List of user permissions on this channel
-  List<String> get ownCapabilities =>
+  List<ChannelCapability> get ownCapabilities =>
       state?._channelState.channel?.ownCapabilities ?? [];
 
   /// List of user permissions on this channel
-  Stream<List<String>> get ownCapabilitiesStream {
+  Stream<List<ChannelCapability>> get ownCapabilitiesStream {
     _checkInitialized();
     return state!.channelStateStream
         .map((cs) => cs.channel?.ownCapabilities ?? [])
@@ -2899,9 +2899,7 @@ class ChannelClientState {
     if (_channel.isMuted) return false;
 
     // Don't count if the channel doesn't allow read events.
-    if (!_channel.ownCapabilities.contains(PermissionType.readEvents)) {
-      return false;
-    }
+    if (!_channel.canReceiveReadEvents) return false;
 
     // Don't count thread replies which are not shown in the channel as unread.
     if (message.parentId != null && message.showInChannel == false) {
@@ -3215,3 +3213,187 @@ extension on Iterable<Message> {
     return messageMap.values;
   }
 }
+
+/// Extension methods for checking channel capabilities on a Channel instance.
+///
+/// These methods provide a convenient way to check if the current user has
+/// specific capabilities in a channel.
+extension ChannelCapabilityCheck on Channel {
+  /// True, if the current user can send a message to this channel.
+  bool get canSendMessage {
+    return ownCapabilities.contains(ChannelCapability.sendMessage);
+  }
+
+  /// True, if the current user can send a reply to this channel.
+  bool get canSendReply {
+    return ownCapabilities.contains(ChannelCapability.sendReply);
+  }
+
+  /// True, if the current user can send a message with restricted visibility.
+  bool get canSendRestrictedVisibilityMessage {
+    return ownCapabilities.contains(
+      ChannelCapability.sendRestrictedVisibilityMessage,
+    );
+  }
+
+  /// True, if the current user can send reactions.
+  bool get canSendReaction {
+    return ownCapabilities.contains(ChannelCapability.sendReaction);
+  }
+
+  /// True, if the current user can attach links to messages.
+  bool get canSendLinks {
+    return ownCapabilities.contains(ChannelCapability.sendLinks);
+  }
+
+  /// True, if the current user can attach files to messages.
+  bool get canCreateAttachment {
+    return ownCapabilities.contains(ChannelCapability.createAttachment);
+  }
+
+  /// True, if the current user can freeze or unfreeze channel.
+  bool get canFreezeChannel {
+    return ownCapabilities.contains(ChannelCapability.freezeChannel);
+  }
+
+  /// True, if the current user can enable or disable slow mode.
+  bool get canSetChannelCooldown {
+    return ownCapabilities.contains(ChannelCapability.setChannelCooldown);
+  }
+
+  /// True, if the current user can leave channel (remove own membership).
+  bool get canLeaveChannel {
+    return ownCapabilities.contains(ChannelCapability.leaveChannel);
+  }
+
+  /// True, if the current user can join channel (add own membership).
+  bool get canJoinChannel {
+    return ownCapabilities.contains(ChannelCapability.joinChannel);
+  }
+
+  /// True, if the current user can pin a message.
+  bool get canPinMessage {
+    return ownCapabilities.contains(ChannelCapability.pinMessage);
+  }
+
+  /// True, if the current user can delete any message from the channel.
+  bool get canDeleteAnyMessage {
+    return ownCapabilities.contains(ChannelCapability.deleteAnyMessage);
+  }
+
+  /// True, if the current user can delete own messages from the channel.
+  bool get canDeleteOwnMessage {
+    return ownCapabilities.contains(ChannelCapability.deleteOwnMessage);
+  }
+
+  /// True, if the current user can update any message in the channel.
+  bool get canUpdateAnyMessage {
+    return ownCapabilities.contains(ChannelCapability.updateAnyMessage);
+  }
+
+  /// True, if the current user can update own messages in the channel.
+  bool get canUpdateOwnMessage {
+    return ownCapabilities.contains(ChannelCapability.updateOwnMessage);
+  }
+
+  /// True, if the current user can use message search.
+  bool get canSearchMessages {
+    return ownCapabilities.contains(ChannelCapability.searchMessages);
+  }
+
+  /// True, if the current user can send typing events.
+  bool get canSendTypingEvents {
+    return ownCapabilities.contains(ChannelCapability.sendTypingEvents);
+  }
+
+  /// True, if the current user can upload message attachments.
+  bool get canUploadFile {
+    return ownCapabilities.contains(ChannelCapability.uploadFile);
+  }
+
+  /// True, if the current user can delete channel.
+  bool get canDeleteChannel {
+    return ownCapabilities.contains(ChannelCapability.deleteChannel);
+  }
+
+  /// True, if the current user can update channel data.
+  bool get canUpdateChannel {
+    return ownCapabilities.contains(ChannelCapability.updateChannel);
+  }
+
+  /// True, if the current user can update channel members.
+  bool get canUpdateChannelMembers {
+    return ownCapabilities.contains(ChannelCapability.updateChannelMembers);
+  }
+
+  /// True, if the current user can update thread data.
+  bool get canUpdateThread {
+    return ownCapabilities.contains(ChannelCapability.updateThread);
+  }
+
+  /// True, if the current user can quote a message.
+  bool get canQuoteMessage {
+    return ownCapabilities.contains(ChannelCapability.quoteMessage);
+  }
+
+  /// True, if the current user can ban channel members.
+  bool get canBanChannelMembers {
+    return ownCapabilities.contains(ChannelCapability.banChannelMembers);
+  }
+
+  /// True, if the current user can flag a message.
+  bool get canFlagMessage {
+    return ownCapabilities.contains(ChannelCapability.flagMessage);
+  }
+
+  /// True, if the current user can mute a channel.
+  bool get canMuteChannel {
+    return ownCapabilities.contains(ChannelCapability.muteChannel);
+  }
+
+  /// True, if the current user can send custom events.
+  bool get canSendCustomEvents {
+    return ownCapabilities.contains(ChannelCapability.sendCustomEvents);
+  }
+
+  /// True, if the current user has read events capability.
+  bool get canReceiveReadEvents {
+    return ownCapabilities.contains(ChannelCapability.readEvents);
+  }
+
+  /// True, if the current user has connect events capability.
+  bool get canReceiveConnectEvents {
+    return ownCapabilities.contains(ChannelCapability.connectEvents);
+  }
+
+  /// True, if the current user can send and receive typing events.
+  bool get canUseTypingEvents {
+    return ownCapabilities.contains(ChannelCapability.typingEvents);
+  }
+
+  /// True, if channel slow mode is active.
+  bool get isInSlowMode {
+    return ownCapabilities.contains(ChannelCapability.slowMode);
+  }
+
+  /// True, if the current user is allowed to post messages as usual even if the
+  /// channel is in slow mode.
+  bool get canSkipSlowMode {
+    return ownCapabilities.contains(ChannelCapability.skipSlowMode);
+  }
+
+  /// True, if the current user can create a poll.
+  bool get canSendPoll {
+    return ownCapabilities.contains(ChannelCapability.sendPoll);
+  }
+
+  /// True, if the current user can vote in a poll.
+  bool get canCastPollVote {
+    return ownCapabilities.contains(ChannelCapability.castPollVote);
+  }
+
+  /// True, if the current user can query poll votes.
+  bool get canQueryPollVotes {
+    return ownCapabilities.contains(ChannelCapability.queryPollVotes);
+  }
+}

packages/stream_chat/lib/src/core/models/channel_model.dart

@@ -14,7 +14,7 @@ class ChannelModel {
     String? id,
     String? type,
     String? cid,
-    this.ownCapabilities,
+    List<String>? ownCapabilities,
     ChannelConfig? config,
     this.createdBy,
     this.frozen = false,
@@ -40,6 +40,7 @@ class ChannelModel {
         config = config ?? ChannelConfig(),
         createdAt = createdAt ?? DateTime.now(),
         updatedAt = updatedAt ?? DateTime.now(),
+        ownCapabilities = ownCapabilities?.map(ChannelCapability.new).toList(),
 
         // For backwards compatibility, set 'disabled', 'hidden'
         // and 'truncated_at' in [extraData].
@@ -67,9 +68,9 @@ class ChannelModel {
   @JsonKey(includeToJson: false)
   final String cid;
 
-  /// List of user permissions on this channel
+  /// List of various capabilities that a user can have in a channel.
   @JsonKey(includeToJson: false)
-  final List<String>? ownCapabilities;
+  final List<ChannelCapability>? ownCapabilities;
 
   /// The channel configuration data
   @JsonKey(includeToJson: false)
@@ -238,3 +239,118 @@ class ChannelModel {
     );
   }
 }
+
+/// {@template channelCapability}
+/// Represents various capabilities that a user can have in a channel.
+/// {@endtemplate}
+extension type const ChannelCapability(String capability) implements String {
+  /// Ability to send a message.
+  static const sendMessage = ChannelCapability('send-message');
+
+  /// Ability to reply to a message.
+  static const sendReply = ChannelCapability('send-reply');
+
+  /// Ability to send a message with restricted visibility.
+  static const sendRestrictedVisibilityMessage = ChannelCapability(
+    'send-restricted-visibility-message',
+  );
+
+  /// Ability to send reactions.
+  static const sendReaction = ChannelCapability('send-reaction');
+
+  /// Ability to attach links to messages.
+  static const sendLinks = ChannelCapability('send-links');
+
+  /// Ability to attach files to messages.
+  static const createAttachment = ChannelCapability('create-attachment');
+
+  /// Ability to freeze or unfreeze channel.
+  static const freezeChannel = ChannelCapability('freeze-channel');
+
+  /// Ability to enable or disable slow mode.
+  static const setChannelCooldown = ChannelCapability('set-channel-cooldown');
+
+  /// Ability to leave channel (remove own membership).
+  static const leaveChannel = ChannelCapability('leave-channel');
+
+  /// Ability to join channel (add own membership).
+  static const joinChannel = ChannelCapability('join-channel');
+
+  /// Ability to pin a message.
+  static const pinMessage = ChannelCapability('pin-message');
+
+  /// Ability to delete any message from the channel.
+  static const deleteAnyMessage = ChannelCapability('delete-any-message');
+
+  /// Ability to delete own messages from the channel.
+  static const deleteOwnMessage = ChannelCapability('delete-own-message');
+
+  /// Ability to update any message in the channel.
+  static const updateAnyMessage = ChannelCapability('update-any-message');
+
+  /// Ability to update own messages in the channel.
+  static const updateOwnMessage = ChannelCapability('update-own-message');
+
+  /// Ability to use message search.
+  static const searchMessages = ChannelCapability('search-messages');
+
+  /// Ability to send typing events.
+  static const sendTypingEvents = ChannelCapability('send-typing-events');
+
+  /// Ability to upload message attachments.
+  static const uploadFile = ChannelCapability('upload-file');
+
+  /// Ability to delete channel.
+  static const deleteChannel = ChannelCapability('delete-channel');
+
+  /// Ability to update channel data.
+  static const updateChannel = ChannelCapability('update-channel');
+
+  /// Ability to update channel members.
+  static const updateChannelMembers = ChannelCapability(
+    'update-channel-members',
+  );
+
+  /// Ability to update thread data.
+  static const updateThread = ChannelCapability('update-thread');
+
+  /// Ability to quote a message.
+  static const quoteMessage = ChannelCapability('quote-message');
+
+  /// Ability to ban channel members.
+  static const banChannelMembers = ChannelCapability('ban-channel-members');
+
+  /// Ability to flag a message.
+  static const flagMessage = ChannelCapability('flag-message');
+
+  /// Ability to mute a channel.
+  static const muteChannel = ChannelCapability('mute-channel');
+
+  /// Ability to send custom events.
+  static const sendCustomEvents = ChannelCapability('send-custom-events');
+
+  /// Ability to receive read events.
+  static const readEvents = ChannelCapability('read-events');
+
+  /// Ability to receive connect events.
+  static const connectEvents = ChannelCapability('connect-events');
+
+  /// Ability to send and receive typing events.
+  static const typingEvents = ChannelCapability('typing-events');
+
+  /// Indicates that channel slow mode is active.
+  static const slowMode = ChannelCapability('slow-mode');
+
+  /// Indicates that the user is allowed to post messages as usual even if the
+  /// channel is in slow mode.
+  static const skipSlowMode = ChannelCapability('skip-slow-mode');
+
+  /// Ability to update a poll.
+  static const sendPoll = ChannelCapability('send-poll');
+
+  /// Ability to update a poll.
+  static const castPollVote = ChannelCapability('cast-poll-vote');
+
+  /// Ability to query poll votes.
+  static const queryPollVotes = ChannelCapability('query-poll-votes');
+}

packages/stream_chat/lib/src/permission_type.dart

@@ -1,4 +1,5 @@
 /// Describes capabilities of a user vis-a-vis a channel
+@Deprecated("Use 'ChannelCapability' instead")
 class PermissionType {
   /// Capability required to send a message in the channel
   /// Channel is not frozen (or user has UseFrozenChannel permission)