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,19 @@ 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}) {
+    // dateJoined is in UTC, in the following format: 2024-02-24T11:18+00:00.
+    final dateJoined = DateTime.parse(user.dateJoined);
+    return byDate.difference(dateJoined).inDays >= realmWaitingPeriodThreshold;
+  }
+
   ////////////////////////////////
   // Streams, topics, and stuff about them.
 

test/model/store_test.dart

@@ -4,6 +4,7 @@ import 'dart:io';
 import 'package:checks/checks.dart';
 import 'package:fake_async/fake_async.dart';
 import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
 import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/core.dart';
@@ -247,6 +248,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