Refactor envelope and receiver methods for clarity

- Changed return type of `CreateEnvelopeAsync` to ensure a non-null `Envelope` is always returned.
- Updated `AddEnvelopeReceiverAsync` to allow nullable `salutation` parameter.
- Renamed cancellation token parameter in `CreateEnvelopeReceiverCommandHandler` for consistency.
- Enhanced error handling in `CreateEnvelopeAsync` to throw exceptions on failure with improved messages.
- Adjusted `CreateParameters` method to accept nullable `salutation`.

EnvelopeGenerator.Application/Contracts/SQLExecutor/IEnvelopeExecutor.cs

@@ -17,5 +17,5 @@ public interface IEnvelopeExecutor : ISQLExecutor
     /// <param name="tfaEnabled"></param>
     /// <param name="cancellation"></param>
     /// <returns></returns>
-    Task<Envelope?> CreateEnvelopeAsync(int userId, string title = "", string message = "", bool tfaEnabled = false, CancellationToken cancellation = default);
+    Task<Envelope> CreateEnvelopeAsync(int userId, string title = "", string message = "", bool tfaEnabled = false, CancellationToken cancellation = default);
 }

EnvelopeGenerator.Application/Contracts/SQLExecutor/IEnvelopeReceiverExecutor.cs

@@ -16,5 +16,5 @@ public interface IEnvelopeReceiverExecutor
     /// <param name="phone"></param>
     /// <param name="cancellation"></param>
     /// <returns></returns>
-    Task<EnvelopeReceiver?> AddEnvelopeReceiverAsync(string envelope_uuid, string emailAddress, string salutation, string? phone = null, CancellationToken cancellation = default);
+    Task<EnvelopeReceiver?> AddEnvelopeReceiverAsync(string envelope_uuid, string emailAddress, string? salutation = null, string? phone = null, CancellationToken cancellation = default);
 }

EnvelopeGenerator.Application/EnvelopeReceivers/Commands/Create/CreateEnvelopeReceiverCommandHandler.cs

@@ -1,4 +1,5 @@
 using EnvelopeGenerator.Application.Contracts.SQLExecutor;
+using EnvelopeGenerator.Domain.Entities;
 using MediatR;
 
 namespace EnvelopeGenerator.Application.EnvelopeReceivers.Commands.Create;
@@ -31,10 +32,25 @@ public class CreateEnvelopeReceiverCommandHandler : IRequestHandler<CreateEnvelo
     /// and storing the envelope and document details.
     /// </summary>
     /// <param name="request">The command containing all necessary information to create an envelope.</param>
-    /// <param name="cancellationToken">Token to observe while waiting for the task to complete.</param>
+    /// <param name="cancel">Token to observe while waiting for the task to complete.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
-    public Task Handle(CreateEnvelopeReceiverCommand request, CancellationToken cancellationToken)
+    public async Task Handle(CreateEnvelopeReceiverCommand request, CancellationToken cancel)
     {
-        throw new NotImplementedException();
+        int userId = request.UserId ?? throw new InvalidOperationException("UserId cannot be null when creating an envelope.");
+
+        var envelope = await _envelopeExecutor.CreateEnvelopeAsync(userId, request.Title, request.Message, request.TFAEnabled, cancel);
+
+        List<EnvelopeReceiver> sentRecipients = new();
+        List<ReceiverGetOrCreateCommand> unsentRecipients = new();
+
+        foreach (var receiver in request.Receivers)
+        {
+            var envelopeReceiver = await _erExecutor.AddEnvelopeReceiverAsync(envelope.Uuid, receiver.EmailAddress, receiver.Salution, receiver.PhoneNumber, cancel);
+
+            if (envelopeReceiver is null)
+                unsentRecipients.Add(receiver);
+            else
+                sentRecipients.Add(envelopeReceiver);
+        }
     }
 }

EnvelopeGenerator.Application/SQL/EnvelopeReceiverAddReadSQL.cs

@@ -40,7 +40,7 @@ public class EnvelopeReceiverAddReadSQL : ISQL<Envelope>
 	/// <param name="salutation"></param>
 	/// <param name="phone"></param>
 	/// <returns></returns>
-    public static DynamicParameters CreateParameters(string envelope_uuid, string emailAddress, string salutation, string? phone = null)
+    public static DynamicParameters CreateParameters(string envelope_uuid, string emailAddress, string? salutation = null, string? phone = null)
     {
         var parameters = new DynamicParameters();
         parameters.Add("@ENV_UID", envelope_uuid);

EnvelopeGenerator.Infrastructure/Executor/EnvelopeExecutor.cs

@@ -20,18 +20,19 @@ public class EnvelopeExecutor : SQLExecutor, IEnvelopeExecutor
         _envelopeRepository = envelopeRepository;
     }
 
-    public async Task<Envelope?> CreateEnvelopeAsync(int userId, string title = "", string message = "", bool tfaEnabled = false, CancellationToken cancellation = default)
+    public async Task<Envelope> CreateEnvelopeAsync(int userId, string title = "", string message = "", bool tfaEnabled = false, CancellationToken cancellation = default)
     {
         using var connection = new SqlConnection(Params.ConnectionString);
         var sql = Provider.GetRequiredService<EnvelopeCreateReadSQL>();
         await connection.OpenAsync(cancellation);
         var parameters = EnvelopeCreateReadSQL.CreateParmas(userId, title, message, tfaEnabled);
         var envelopes = await connection.QueryAsync<Envelope>(sql.Raw, parameters);
-        var envelope = envelopes.FirstOrDefault();
+        var envelope = envelopes.FirstOrDefault()
+            ?? throw new InvalidOperationException($"Envelope creation failed. Parameters:" +
+            $"userId={userId}, title='{title}', message='{message}', tfaEnabled={tfaEnabled}."); ;
              
-        if (envelope is null)
+        return await _envelopeRepository.ReadByUuidAsync(envelope.Uuid, withAll: true) 
-            return null;
+            ?? throw new InvalidOperationException($"Envelope creation succeeded but retrieval failed. Parameters:" +
-
+            $"userId={userId}, title='{title}', message='{message}', tfaEnabled={tfaEnabled}.");
-        return await _envelopeRepository.ReadByUuidAsync(envelope.Uuid, withAll: true);
     }
 }

EnvelopeGenerator.Infrastructure/Executor/EnvelopeReceiverExecutor.cs

@@ -19,7 +19,7 @@ public class EnvelopeReceiverExecutor: SQLExecutor, IEnvelopeReceiverExecutor
         _erRepository = erRepository;
     }
 
-    public async Task<EnvelopeReceiver?> AddEnvelopeReceiverAsync(string envelope_uuid, string emailAddress, string salutation, string? phone = null, CancellationToken cancellation = default)
+    public async Task<EnvelopeReceiver?> AddEnvelopeReceiverAsync(string envelope_uuid, string emailAddress, string? salutation, string? phone = null, CancellationToken cancellation = default)
     {
         using var connection = new SqlConnection(Params.ConnectionString);
         var sql = Provider.GetRequiredService<EnvelopeReceiverAddReadSQL>();