model: Add hasPassedWaitingPeriod helper method to PerAccountStore

Also add `UserRole.isAtLeast` method.

Author: sm-sayedi

lib/api/model/model.dart

@@ -303,6 +303,11 @@ enum UserRole{
   final int? apiValue;
 
   int? toJson() => apiValue;
+
+  bool isAtLeast(UserRole threshold) {
+    // Roles with more privilege have lower [apiValue].
+    return apiValue! <= threshold.apiValue!;
+  }
 }
 
 /// As in `streams` in the initial snapshot.

lib/model/store.dart

@@ -434,6 +434,28 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
 
   final TypingStatus typingStatus;
 
+  /// Whether [user] has passed the realm's waiting period to be a full member.
+  ///
+  /// See:
+  ///   https://zulip.com/api/roles-and-permissions#determining-if-a-user-is-a-full-member
+  ///
+  /// To determine if a user is a full member, callers must also check that the
+  /// user's role is at least [UserRole.member].
+  bool hasPassedWaitingPeriod(User user, {required DateTime byDate}) {
+    // [User.dateJoined] is in UTC. For logged-in users, the format is:
+    // YYYY-MM-DDTHH:mm+00:00, which includes the timezone offset for UTC.
+    // For logged-out spectators, the format is: YYYY-MM-DD, which doesn't
+    // include the timezone offset. In the later case, [DateTime.parse] will
+    // interpret it as the client's local timezone, which could lead to
+    // incorrect results; but that's acceptable for now because the app
+    // doesn't support viewing as a spectator.
+    //
+    // See the related discussion:
+    //   https://chat.zulip.org/#narrow/channel/412-api-documentation/topic/provide.20an.20explicit.20format.20for.20.60realm_user.2Edate_joined.60/near/1980194
+    final dateJoined = DateTime.parse(user.dateJoined);
+    return byDate.difference(dateJoined).inDays >= realmWaitingPeriodThreshold;
+  }
+
   ////////////////////////////////
   // Streams, topics, and stuff about them.
 

test/model/store_test.dart

@@ -247,6 +247,28 @@ void main() {
     });
   });
 
+  group('PerAccountStore.hasPassedWaitingPeriod', () {
+    final store = eg.store(initialSnapshot:
+      eg.initialSnapshot(realmWaitingPeriodThreshold: 2));
+
+    final testCases = [
+      ('2024-11-25T10:00+00:00', DateTime.utc(2024, 11, 25 + 0, 10, 00), false),
+      ('2024-11-25T10:00+00:00', DateTime.utc(2024, 11, 25 + 1, 10, 00), false),
+      ('2024-11-25T10:00+00:00', DateTime.utc(2024, 11, 25 + 2, 09, 59), false),
+      ('2024-11-25T10:00+00:00', DateTime.utc(2024, 11, 25 + 2, 10, 00), true),
+      ('2024-11-25T10:00+00:00', DateTime.utc(2024, 11, 25 + 1000, 07, 00), true),
+    ];
+
+    for (final (String dateJoined, DateTime currentDate, bool hasPassedWaitingPeriod) in testCases) {
+      test('user joined at $dateJoined ${hasPassedWaitingPeriod ? 'has' : "hasn't"} '
+          'passed waiting period by $currentDate', () {
+        final user = eg.user(dateJoined: dateJoined);
+        check(store.hasPassedWaitingPeriod(user, byDate: currentDate))
+          .equals(hasPassedWaitingPeriod);
+      });
+    }
+  });
+
   group('PerAccountStore.handleEvent', () {
     // Mostly this method just dispatches to ChannelStore and MessageStore etc.,
     // and so most of the tests live in the test files for those