feat(llc, core, persistence): channel pinning and archiving (#2204)

Co-authored-by: Sahil Kumar <sahil@getstream.io>
Co-authored-by: Sahil Kumar <xdsahil@gmail.com>

Author: renefloor

packages/stream_chat/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ✅ Added
 
+- Added support for Channel pinning and archiving.
 - Added support for 'DraftMessage' feature, which allows users to save draft messages in channels.
   Several methods have been added to the `Client` and `Channel` class to manage draft messages:
     - `channel.createDraft`: Saves a draft message for a specific channel.

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

@@ -236,6 +236,32 @@ class Channel {
     return state!.channelStateStream.map((cs) => cs.channel?.hidden == true);
   }
 
+  /// Channel pinned status.
+  /// Status is specific to the current user.
+  bool get isPinned {
+    _checkInitialized();
+    return membership?.pinnedAt != null;
+  }
+
+  /// Channel pinned status as a stream.
+  /// Status is specific to the current user.
+  Stream<bool> get isPinnedStream {
+    return membershipStream.map((m) => m?.pinnedAt != null);
+  }
+
+  /// Channel archived status.
+  /// Status is specific to the current user.
+  bool get isArchived {
+    _checkInitialized();
+    return membership?.archivedAt != null;
+  }
+
+  /// Channel archived status as a stream.
+  /// Status is specific to the current user.
+  Stream<bool> get isArchivedStream {
+    return membershipStream.map((m) => m?.archivedAt != null);
+  }
+
   /// The last date at which the channel got truncated.
   DateTime? get truncatedAt {
     _checkInitialized();
@@ -1935,6 +1961,54 @@ class Channel {
     return _client.showChannel(id!, type);
   }
 
+  /// Pins the channel for the current user.
+  Future<Member> pin() async {
+    _checkInitialized();
+
+    final response = await _client.pinChannel(
+      channelId: id!,
+      channelType: type,
+    );
+
+    return response.channelMember;
+  }
+
+  /// Unpins the channel.
+  Future<Member?> unpin() async {
+    _checkInitialized();
+
+    final response = await _client.unpinChannel(
+      channelId: id!,
+      channelType: type,
+    );
+
+    return response.channelMember;
+  }
+
+  /// Archives the channel.
+  Future<Member?> archive() async {
+    _checkInitialized();
+
+    final response = await _client.archiveChannel(
+      channelId: id!,
+      channelType: type,
+    );
+
+    return response.channelMember;
+  }
+
+  /// Unarchives the channel for the current user.
+  Future<Member?> unarchive() async {
+    _checkInitialized();
+
+    final response = await _client.unarchiveChannel(
+      channelId: id!,
+      channelType: type,
+    );
+
+    return response.channelMember;
+  }
+
   /// Stream of [Event] coming from websocket connection specific for the
   /// channel. Pass an eventType as parameter in order to filter just a type
   /// of event.

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

@@ -1877,6 +1877,83 @@ class StreamChatClient {
         unset: unset,
       );
 
+  /// Pins the channel for the current user.
+  Future<PartialUpdateMemberResponse> pinChannel({
+    required String channelId,
+    required String channelType,
+  }) {
+    return partialMemberUpdate(
+      channelId: channelId,
+      channelType: channelType,
+      set: const MemberUpdatePayload(pinned: true).toJson(),
+    );
+  }
+
+  /// Unpins the channel for the current user.
+  Future<PartialUpdateMemberResponse> unpinChannel({
+    required String channelId,
+    required String channelType,
+  }) {
+    return partialMemberUpdate(
+      channelId: channelId,
+      channelType: channelType,
+      unset: [MemberUpdateType.pinned.name],
+    );
+  }
+
+  /// Archives the channel for the current user.
+  Future<PartialUpdateMemberResponse> archiveChannel({
+    required String channelId,
+    required String channelType,
+  }) {
+    final currentUser = state.currentUser;
+    if (currentUser == null) {
+      throw const StreamChatError(
+        'User is not set on client, '
+        'use `connectUser` or `connectAnonymousUser` instead',
+      );
+    }
+
+    return partialMemberUpdate(
+      channelId: channelId,
+      channelType: channelType,
+      set: const MemberUpdatePayload(archived: true).toJson(),
+    );
+  }
+
+  /// Unarchives the channel for the current user.
+  Future<PartialUpdateMemberResponse> unarchiveChannel({
+    required String channelId,
+    required String channelType,
+  }) {
+    return partialMemberUpdate(
+      channelId: channelId,
+      channelType: channelType,
+      unset: [MemberUpdateType.archived.name],
+    );
+  }
+
+  /// Partially updates the member of the given channel.
+  ///
+  /// Use [set] to define values to be set.
+  /// Use [unset] to define values to be unset.
+  /// When [userId] is not provided, the current user will be used.
+  Future<PartialUpdateMemberResponse> partialMemberUpdate({
+    required String channelId,
+    required String channelType,
+    Map<String, Object?>? set,
+    List<String>? unset,
+  }) {
+    assert(set != null || unset != null, 'Set or unset must be provided.');
+
+    return _chatApi.channel.updateMemberPartial(
+      channelId: channelId,
+      channelType: channelType,
+      set: set,
+      unset: unset,
+    );
+  }
+
   /// Closes the [_ws] connection and resets the [state]
   /// If [flushChatPersistence] is true the client deletes all offline
   /// user's data.

packages/stream_chat/lib/src/core/api/channel_api.dart

@@ -375,4 +375,24 @@ class ChannelApi {
     );
     return EmptyResponse.fromJson(response.data);
   }
+
+  /// Updates some of the member data
+  Future<PartialUpdateMemberResponse> updateMemberPartial({
+    required String channelId,
+    required String channelType,
+    Map<String, Object?>? set,
+    List<String>? unset,
+  }) async {
+    final response = await _client.patch(
+      // Note: user_id is not required for client side Apis as it can be fetched
+      // directly from the user token but, for the api path is built with it
+      // so we need to pass it as a placeholder.
+      '${_getChannelUrl(channelId, channelType)}/member/{user_id}',
+      data: {
+        if (set != null) 'set': set,
+        if (unset != null) 'unset': unset,
+      },
+    );
+    return PartialUpdateMemberResponse.fromJson(response.data);
+  }
 }

packages/stream_chat/lib/src/core/api/requests.dart

@@ -205,3 +205,31 @@ class ThreadOptions extends Equatable {
   @override
   List<Object?> get props => [watch, replyLimit, participantLimit, memberLimit];
 }
+
+/// Payload for updating a member.
+@JsonSerializable(createFactory: false, includeIfNull: false)
+class MemberUpdatePayload {
+  /// Creates a new MemberUpdatePayload instance.
+  const MemberUpdatePayload({
+    this.archived,
+    this.pinned,
+  });
+
+  /// Set to true to archive the channel for a user.
+  final bool? archived;
+
+  /// Set to true to pin the channel for a user.
+  final bool? pinned;
+
+  /// Serialize model to json
+  Map<String, dynamic> toJson() => _$MemberUpdatePayloadToJson(this);
+}
+
+/// Type of member update to unset.
+enum MemberUpdateType {
+  /// Unset the archived flag.
+  archived,
+
+  /// Unset the pinned flag.
+  pinned,
+}

packages/stream_chat/lib/src/core/api/requests.g.dart

@@ -100,6 +100,18 @@ class QueryMembersResponse extends _BaseResponse {
       _$QueryMembersResponseFromJson(json);
 }
 
+/// Model response for update member API calls, such as
+/// [StreamChatClient.updateMemberPartial]
+@JsonSerializable(createToJson: false)
+class PartialUpdateMemberResponse extends _BaseResponse {
+  /// The updated member state
+  late Member channelMember;
+
+  /// Create a new instance from a json
+  static PartialUpdateMemberResponse fromJson(Map<String, dynamic> json) =>
+      _$PartialUpdateMemberResponseFromJson(json);
+}
+
 /// Model response for [StreamChatClient.queryUsers] api call
 @JsonSerializable(createToJson: false)
 class QueryUsersResponse extends _BaseResponse {

packages/stream_chat/lib/src/core/api/responses.dart

@@ -97,6 +97,7 @@ class ChannelState implements ComparableFieldProvider {
       ChannelSortKey.updatedAt => channel?.updatedAt,
       ChannelSortKey.lastMessageAt => channel?.lastMessageAt,
       ChannelSortKey.memberCount => channel?.memberCount,
+      ChannelSortKey.pinnedAt => membership?.pinnedAt,
       // TODO: Support providing default value for hasUnread, unreadCount
       ChannelSortKey.hasUnread => null,
       ChannelSortKey.unreadCount => null,
@@ -134,4 +135,7 @@ extension type const ChannelSortKey(String key) implements String {
 
   /// Sort channels by the count of unread messages.
   static const unreadCount = ChannelSortKey('unread_count');
+
+  /// Sort channels by the date they were pinned.
+  static const pinnedAt = ChannelSortKey('pinned_at');
 }

packages/stream_chat/lib/src/core/api/responses.g.dart

@@ -24,6 +24,8 @@ class Member extends Equatable implements ComparableFieldProvider {
     this.banned = false,
     this.banExpires,
     this.shadowBanned = false,
+    this.pinnedAt,
+    this.archivedAt,
     this.extraData = const {},
   })  : userId = userId ?? user?.id,
         createdAt = createdAt ?? DateTime.now(),
@@ -50,6 +52,8 @@ class Member extends Equatable implements ComparableFieldProvider {
     'shadow_banned',
     'created_at',
     'updated_at',
+    'pinned_at',
+    'archived_at'
   ];
 
   /// The interested user
@@ -82,6 +86,12 @@ class Member extends Equatable implements ComparableFieldProvider {
   /// True if the member is shadow banned from the channel
   final bool shadowBanned;
 
+  /// The date at which the channel was pinned by the member
+  final DateTime? pinnedAt;
+
+  /// The date at which the channel was archived by the member
+  final DateTime? archivedAt;
+
   /// The date of creation
   final DateTime createdAt;
 
@@ -103,6 +113,8 @@ class Member extends Equatable implements ComparableFieldProvider {
     bool? isModerator,
     DateTime? createdAt,
     DateTime? updatedAt,
+    DateTime? pinnedAt,
+    DateTime? archivedAt,
     bool? banned,
     DateTime? banExpires,
     bool? shadowBanned,
@@ -119,6 +131,8 @@ class Member extends Equatable implements ComparableFieldProvider {
         channelRole: channelRole ?? this.channelRole,
         userId: userId ?? this.userId,
         isModerator: isModerator ?? this.isModerator,
+        pinnedAt: pinnedAt ?? this.pinnedAt,
+        archivedAt: archivedAt ?? this.archivedAt,
         createdAt: createdAt ?? this.createdAt,
         updatedAt: updatedAt ?? this.updatedAt,
         extraData: extraData ?? this.extraData,
@@ -141,6 +155,8 @@ class Member extends Equatable implements ComparableFieldProvider {
         banned,
         banExpires,
         shadowBanned,
+        pinnedAt,
+        archivedAt,
         createdAt,
         updatedAt,
         extraData,

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

@@ -1,3 +1,4 @@
+import 'package:collection/collection.dart';
 import 'package:stream_chat/src/core/api/requests.dart';
 import 'package:stream_chat/src/core/api/sort_order.dart';
 import 'package:stream_chat/src/core/models/attachment_file.dart';
@@ -90,8 +91,15 @@ abstract class ChatPersistenceClient {
       getMessagesByCid(cid, messagePagination: messagePagination),
       getPinnedMessagesByCid(cid, messagePagination: pinnedMessagePagination),
     ]);
+
+    final members = data[0] as List<Member>?;
+    final membership = userId == null
+        ? null
+        : members?.firstWhereOrNull((it) => it.userId == userId);
+
     return ChannelState(
-      members: data[0] as List<Member>?,
+      members: members,
+      membership: membership,
       read: data[1] as List<Read>?,
       channel: data[2] as ChannelModel?,
       messages: data[3] as List<Message>?,