Add XML Documentation to IPasswordlessClient

Directory.Build.props

@@ -10,7 +10,7 @@
   <PropertyGroup>
     <PasswordlessMajorVersion>1</PasswordlessMajorVersion>
     <PasswordlessMinorVersion>0</PasswordlessMinorVersion>
-    <PasswordlessPatchVersion>0</PasswordlessPatchVersion>
+    <PasswordlessPatchVersion>1</PasswordlessPatchVersion>
     <PasswordlessMajorMinorVersion>$(PasswordlessMajorVersion).$(PasswordlessMinorVersion)</PasswordlessMajorMinorVersion>
     <VersionPrefix>$(PasswordlessMajorMinorVersion).$(PasswordlessPatchVersion)</VersionPrefix>
   </PropertyGroup>

src/Sdk/Helpers/Base64UrlConverter.cs

@@ -0,0 +1,21 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Passwordless.Net;
+
+public sealed class Base64UrlConverter : JsonConverter<byte[]>
+{
+    public override byte[] Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (!reader.HasValueSequence)
+        {
+            return Base64Url.DecodeUtf8(reader.ValueSpan);
+        }
+        return Base64Url.Decode(reader.GetString().AsSpan());
+    }
+
+    public override void Write(Utf8JsonWriter writer, byte[] value, JsonSerializerOptions options)
+    {
+        writer.WriteStringValue(Base64Url.Encode(value));
+    }
+}

src/Sdk/IPasswordlessClient.cs

@@ -2,14 +2,81 @@
 
 namespace Passwordless.Net;
 
+/// <summary>
+/// Provides APIs that help you interact with Passwordless.dev.
+/// </summary>
 public interface IPasswordlessClient
 {
+    /// <summary>
+    /// Creates a <see cref="RegisterTokenResponse" /> which will be used by your frontend to negotiate
+    /// the creation of a WebAuth credential.
+    /// </summary>
+    /// <param name="registerOptions">The <see cref="RegisterOptions"/> that will be used to configure your token.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation containing the <see cref="RegisterTokenResponse" />.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
     Task<RegisterTokenResponse> CreateRegisterTokenAsync(RegisterOptions registerOptions, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Attempts to delete a credential via the supplied id.
+    /// </summary>
+    /// <param name="id">The id of a credential representing as a Base64 URL encoded <see cref="string" />.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
     Task DeleteCredentialAsync(string id, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Attempts to delete a credential via the supplied id.
+    /// </summary>
+    /// <param name="id">The id of a credential representing as a Base64 URL encoded <see cref="byte[]" />.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
     Task DeleteCredentialAsync(byte[] id, CancellationToken cancellationToken = default);
-    Task<List<AliasPointer>> ListAliasesAsync(string userId, CancellationToken cancellationToken = default);
-    Task<List<Credential>> ListCredentialsAsync(string userId, CancellationToken cancellationToken = default);
-    Task<List<PasswordlessUserSummary>?> ListUsersAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// List all the <see cref="AliasPointer" /> for a given user.
+    /// </summary>
+    /// <param name="userId">The userId of the user for which the aliases will be returned.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{AliasPointer}" />.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
+    Task<IReadOnlyList<AliasPointer>> ListAliasesAsync(string userId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// List all the <see cref="Credential" /> for a given user.
+    /// </summary>
+    /// <param name="userId">The userId of the user for which the credentials will be returned.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{Credential}" />.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
+    Task<IReadOnlyList<Credential>> ListCredentialsAsync(string userId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// List all the <see cref="PasswordlessUserSummary" /> for the account associated with your ApiSecret.
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{PasswordlessUserSummary}" />.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
+    Task<IReadOnlyList<PasswordlessUserSummary>?> ListUsersAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Verifies that the given token is valid and returns information packed into it. The token should have been generated
+    /// via calling a <c>signInWith*</c> method from your frontend code.
+    /// </summary>
+    /// <param name="verifyToken">The token to verify.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation containing the <see cref="VerifiedUser" />.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
     Task<VerifiedUser?> VerifyTokenAsync(string verifyToken, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes a user.
+    /// </summary>
+    /// <param name="userId">The id of the user that should be deleted.</param>
+    /// <param name="cancellationToken"></param>
+    /// <returns>A task object representing the asynchronous operation.</returns>
+    /// <exception cref="PasswordlessApiException">An exception containing details abaout the reason for failure.</exception>
     Task DeleteUserAsync(string userId, CancellationToken cancellationToken = default);
 }

src/Sdk/Models/ListResponse.cs

@@ -0,0 +1,11 @@
+namespace Passwordless.Net.Models;
+
+internal class ListResponse<T>
+{
+    public ListResponse(IReadOnlyList<T> values)
+    {
+        Values = values;
+    }
+
+    public IReadOnlyList<T> Values { get; }
+}

src/Sdk/PasswordlessClient.cs

@@ -2,8 +2,6 @@
 using System.Net.Http;
 using System.Net.Http.Json;
 using System.Text;
-using System.Text.Json;
-using System.Text.Json.Serialization;
 using Passwordless.Net.Models;
 
 namespace Passwordless.Net;
@@ -41,13 +39,15 @@ public PasswordlessClient(HttpClient client)
         _client = client;
     }
 
+    /// <inheritdoc/>
     public async Task<RegisterTokenResponse> CreateRegisterTokenAsync(RegisterOptions registerOptions, CancellationToken cancellationToken = default)
     {
         var res = await _client.PostAsJsonAsync("register/token", registerOptions, cancellationToken);
         res.EnsureSuccessStatusCode();
         return (await res.Content.ReadFromJsonAsync<RegisterTokenResponse>(options: null, cancellationToken))!;
     }
 
+    /// <inheritdoc/>
     public async Task<VerifiedUser?> VerifyTokenAsync(string verifyToken, CancellationToken cancellationToken = default)
     {
         var request = new HttpRequestMessage(HttpMethod.Post, "signin/verify")
@@ -71,35 +71,40 @@ public async Task<RegisterTokenResponse> CreateRegisterTokenAsync(RegisterOption
         return null;
     }
 
+    /// <inheritdoc/>
     public async Task DeleteUserAsync(string userId, CancellationToken cancellationToken = default)
     {
         await _client.PostAsJsonAsync("users/delete", new { UserId = userId }, cancellationToken);
     }
 
-    public async Task<List<PasswordlessUserSummary>?> ListUsersAsync(CancellationToken cancellationToken = default)
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<PasswordlessUserSummary>?> ListUsersAsync(CancellationToken cancellationToken = default)
     {
         var response = await _client.GetFromJsonAsync<ListResponse<PasswordlessUserSummary>>("users/list", cancellationToken);
         return response!.Values;
     }
 
-    public async Task<List<AliasPointer>> ListAliasesAsync(string userId, CancellationToken cancellationToken = default)
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<AliasPointer>> ListAliasesAsync(string userId, CancellationToken cancellationToken = default)
     {
         var response = await _client.GetFromJsonAsync<ListResponse<AliasPointer>>($"alias/list?userid={userId}", cancellationToken);
         return response!.Values;
     }
 
-
-    public async Task<List<Credential>> ListCredentialsAsync(string userId, CancellationToken cancellationToken = default)
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<Credential>> ListCredentialsAsync(string userId, CancellationToken cancellationToken = default)
     {
         var response = await _client.GetFromJsonAsync<ListResponse<Credential>>($"credentials/list?userid={userId}", cancellationToken);
         return response!.Values;
     }
 
+    /// <inheritdoc/>
     public async Task DeleteCredentialAsync(string id, CancellationToken cancellationToken = default)
     {
         await _client.PostAsJsonAsync("credentials/delete", new { CredentialId = id }, cancellationToken);
     }
 
+    /// <inheritdoc/>
     public async Task DeleteCredentialAsync(byte[] id, CancellationToken cancellationToken = default)
     {
         await DeleteCredentialAsync(Base64Url.Encode(id), cancellationToken);
@@ -151,26 +156,4 @@ protected virtual void Dispose(bool disposing)
             _client.Dispose();
         }
     }
-
-    public class ListResponse<T>
-    {
-        public List<T> Values { get; set; } = null!;
-    }
-
-    public sealed class Base64UrlConverter : JsonConverter<byte[]>
-    {
-        public override byte[] Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
-        {
-            if (!reader.HasValueSequence)
-            {
-                return Base64Url.DecodeUtf8(reader.ValueSpan);
-            }
-            return Base64Url.Decode(reader.GetString().AsSpan());
-        }
-
-        public override void Write(Utf8JsonWriter writer, byte[] value, JsonSerializerOptions options)
-        {
-            writer.WriteStringValue(Base64Url.Encode(value));
-        }
-    }
 }