Add user invite events to support user invite authorisation (#624)

* Update user invit models for authorisation.

* Adding authorisation staus model.

* Added user invite event types.

* Added user invite details endpoint client.

* Do user invite authorisation check first (added DB script to set all existing invites as authorised).

Author: sipsorcery

src/NoFrixion.MoneyMoov/ApiClients/UserInviteClient.cs

@@ -26,6 +26,8 @@ public interface IUserInviteClient
 
     Task<RestApiResponse<UserInvite>> GetUserInviteAsync(string accessToken, Guid userInviteID);
 
+    Task<RestApiResponse<UserInvite>> GetUserInviteDetailsAsync(string accessToken, Guid userInviteID);
+
     Task<RestApiResponse<UserInvite>> SendInviteAsync(string userAccessToken, Guid merchantID,
         string inviteeEmailAddress,
         string inviteRegistrationUrl,
@@ -39,6 +41,8 @@ Task<RestApiResponse<UserInvite>> SendInviteAsync(string userAccessToken, Guid m
     Task<RestApiResponse> ResendUserInviteAsync(string accessToken, Guid userInviteID);
 
     Task<RestApiResponse> DeleteUserInviteAsync(string accessToken, Guid inviteID);
+
+    Task<RestApiResponse> AuthoriseUserInviteAsync(string strongUserAccessToken, Guid inviteID);
 }
 
 public class UserInviteClient : IUserInviteClient
@@ -102,6 +106,25 @@ public Task<RestApiResponse<UserInvite>> GetUserInviteAsync(string accessToken,
         };
     }
 
+    /// <summary>
+    /// Calls the MoneyMoov Merchant get user invite details endpoint to get a single user invite by ID.
+    /// </summary>
+    /// <param name="accessToken">A User scoped JWT access token.</param>
+    /// <param name="userInviteID">The ID of the user invite to retrieve.</param>
+    /// <returns>If successful, a user invite object.</returns>
+    public Task<RestApiResponse<UserInvite>> GetUserInviteDetailsAsync(string accessToken, Guid userInviteID)
+    {
+        var url = MoneyMoovUrlBuilder.UserInvitesApi.UserInviteDetailsUrl(_apiClient.GetBaseUri().ToString(), userInviteID);
+
+        var prob = _apiClient.CheckAccessToken(accessToken, nameof(GetUserInviteDetailsAsync));
+
+        return prob switch
+        {
+            var p when p.IsEmpty => _apiClient.GetAsync<UserInvite>(url, accessToken),
+            _ => Task.FromResult(new RestApiResponse<UserInvite>(HttpStatusCode.PreconditionFailed, new Uri(url), prob))
+        };
+    }
+
     /// <summary>
     /// Calls the MoneyMoov account endpoint to create and send an email invite to register
     /// and join a merchant account.
@@ -192,4 +215,25 @@ public Task<RestApiResponse> DeleteUserInviteAsync(string accessToken, Guid invi
             _ => Task.FromResult(new RestApiResponse(HttpStatusCode.PreconditionFailed, new Uri(url), prob))
         };
     }
+
+    /// <summary>
+    /// Calls the MoneyMoov user invites endpoint to authorise a user invite.
+    /// </summary>
+    /// <param name="strongUserAccessToken">The strong user access token acquired to authorise the user invite. Strong
+    /// tokens can only be acquired from a strong customer authentication flow, are short lived (typically 5 minute expiry)
+    /// and are specific to the user invite.</param>
+    /// <param name="inviteID">The ID of the user invite to authorise.</param>
+    /// <returns>An API response indicating the result of the authorise attempt.</returns>
+    public Task<RestApiResponse> AuthoriseUserInviteAsync(string strongUserAccessToken, Guid inviteID)
+    {
+        var url = MoneyMoovUrlBuilder.UserInvitesApi.AuthoriseUserInviteUrl(_apiClient.GetBaseUri().ToString(), inviteID);
+
+        var prob = _apiClient.CheckAccessToken(strongUserAccessToken, nameof(AuthoriseUserInviteAsync));
+
+        return prob switch
+        {
+            var p when p.IsEmpty => _apiClient.PostAsync(url, strongUserAccessToken),
+            _ => Task.FromResult(new RestApiResponse(HttpStatusCode.PreconditionFailed, new Uri(url), prob))
+        };
+    }
 }

src/NoFrixion.MoneyMoov/Enums/UserInviteEventTypeEnum.cs

@@ -0,0 +1,30 @@
+//-----------------------------------------------------------------------------
+// Filename: UserInviteEventTypeEnum.cs
+// 
+// Description: Enum for the different types of user invite events that can
+// occur.
+// 
+// Author(s):
+// Aaron Clauson ([email protected])
+// 
+// History:
+// 06 Aug 2025  Aaron Clauson   Created, Carnesore Point, Wexford, Ireland.
+// 
+// License:
+// MIT.
+//-----------------------------------------------------------------------------
+
+namespace NoFrixion.MoneyMoov.Enums;
+
+public enum UserInviteEventTypeEnum
+{
+    /// <summary>
+    /// Something went wrong and the event type is unknown.
+    /// </summary>
+    Unknown = 0,
+    
+    /// <summary>
+    /// A user invite was authorised by an approver.
+    /// </summary>
+    Authorise = 1
+}

src/NoFrixion.MoneyMoov/Models/Authorisation/AuthorisationStatus.cs

@@ -0,0 +1,60 @@
+//-----------------------------------------------------------------------------
+// Filename: AuthorisationStatus.cs
+//
+// Description: Represents the authorisation status for a parent model,
+// e.g. payout, beneficiary etc. Once the parent model is authorised this state
+// can largely be ignored until the next time the parent model is updated.
+//
+// Author(s):
+// Aaron Clauson ([email protected])
+// 
+// History:
+// 02 Aug 2025  Aaron Clauson   Created, Carnesore Point, Wexford, Ireland.
+//
+// License: 
+// MIT.
+//-----------------------------------------------------------------------------
+
+using NoFrixion.MoneyMoov.Enums;
+using NoFrixion.MoneyMoov.Models.Approve;
+
+namespace NoFrixion.MoneyMoov.Models;
+
+public class AuthorisationStatus
+{
+    /// <summary>
+    /// A list of users who have successfully authorised the latest version of the parent model.
+    /// </summary>
+    public List<Authorisation>? Authorisations { get; set; }
+
+    /// <summary>
+    /// True if the parent model can be authorised by the user who loaded it.
+    /// </summary>
+    public bool CanAuthorise { get; set; }
+
+    /// <summary>
+    /// True if the parent model can be updated by the user who loaded it.
+    /// </summary>
+    public bool CanUpdate { get; set; }
+
+    /// <summary>
+    /// True if the parent model was loaded for a user and that user has already authorised the latest version.
+    /// </summary>
+    public bool HasCurrentUserAuthorised { get; set; }
+
+    /// <summary>
+    /// The number of authorisers required for the parent model. Is determined by business settings
+    /// on the source account and/or merchant.
+    /// </summary>
+    public int AuthorisersRequiredCount { get; set; }
+
+    /// <summary>
+    /// The number of distinct authorisers that have authorised the parent model.
+    /// </summary>
+    public int AuthorisersCompletedCount { get; set; }
+
+    /// <summary>
+    /// A list of authentication types allowed to authorise the parent model.
+    /// </summary>
+    public List<AuthenticationTypesEnum>? AuthenticationMethods { get; set; }
+}

src/NoFrixion.MoneyMoov/Models/UserInvite/UserInvite.cs

@@ -55,21 +55,26 @@ public class UserInvite
     /// </summary>
     public bool IsAuthorised { get; set; }
 
+    /// <summary>
+    /// The authorisation status for the user invite. It is used for invites
+    /// that require authorisation before they can be activated.
+    /// </summary>
+    public AuthorisationStatus? AuthorisationStatus { get; set; }
+
     public UserInviteStatusEnum Status
     {
         get
         {
-            if(!IsAuthorised)
+            if (UserID != null)
             {
-                return UserInviteStatusEnum.AuthorisationRequired;
+                return UserInviteStatusEnum.Accepted;
             }
 
-            if (UserID != null)
+            if (!IsAuthorised)
             {
-                return UserInviteStatusEnum.Accepted;
+                return UserInviteStatusEnum.AuthorisationRequired;
             }
-            
-            if ((DateTimeOffset.Now - LastInvited) > new TimeSpan(USER_INVITE_EXPIRATION_HOURS, 0, 0))
+            else if ((DateTimeOffset.Now - LastInvited) > new TimeSpan(USER_INVITE_EXPIRATION_HOURS, 0, 0))
             {
                 return UserInviteStatusEnum.Expired;
             }
@@ -85,6 +90,8 @@ public UserInviteStatusEnum Status
     /// used to ensure a user invite's details are not modified between the time the
     /// authorisation is given and the time the user invite is enabled.
     /// </summary>
+    /// <remarks>There is currently no need for a nonce as user invites cannot have their critical details updated 
+    /// once created.</remarks>
     /// <returns>A hash of the user invite's critical fields.</returns>
     public string GetApprovalHash()
     {

src/NoFrixion.MoneyMoov/MoneyMoovUrlBuilder.cs

@@ -315,6 +315,12 @@ public static string UserInvitesUrl(string moneyMoovBaseUrl)
 
         public static string UserInviteUrl(string moneyMoovBaseUrl, Guid userInviteID)
             => $"{moneyMoovBaseUrl}/{MoneyMoovResources.userinvites}/{userInviteID}";
+
+        public static string AuthoriseUserInviteUrl(string moneyMoovBaseUrl, Guid userInviteID)
+            => $"{moneyMoovBaseUrl}/{MoneyMoovResources.userinvites}/authorise/{userInviteID}";
+
+        public static string UserInviteDetailsUrl(string moneyMoovBaseUrl, Guid userInviteID)
+            => $"{moneyMoovBaseUrl}/{MoneyMoovResources.userinvites}/{userInviteID}/details";
     }
 
     /// <summary>