diff --git a/Directory.Build.targets b/Directory.Build.targets index 331cc769..38d1648d 100644 --- a/Directory.Build.targets +++ b/Directory.Build.targets @@ -3,6 +3,10 @@ + + + <_Parameter1>DynamicProxyGenAssembly2 + diff --git a/src/PinguApps.Appwrite.Client/Clients/AccountClient.cs b/src/PinguApps.Appwrite.Client/Clients/AccountClient.cs index 732400a5..3e72d624 100644 --- a/src/PinguApps.Appwrite.Client/Clients/AccountClient.cs +++ b/src/PinguApps.Appwrite.Client/Clients/AccountClient.cs @@ -8,6 +8,7 @@ using PinguApps.Appwrite.Shared.Responses; namespace PinguApps.Appwrite.Client; + public class AccountClient : IAccountClient, ISessionAware { private readonly IAccountApi _accountApi; @@ -31,6 +32,7 @@ public AccountClient(IAccountApi accountApi) return _sessionAware.Session; } + /// public async Task> Get() { try @@ -46,6 +48,7 @@ public async Task> Get() } } + /// public async Task> Create(CreateAccountRequest request) { try diff --git a/src/PinguApps.Appwrite.Client/Clients/AppwriteClient.cs b/src/PinguApps.Appwrite.Client/Clients/AppwriteClient.cs index 2d1bb3c4..53f727c3 100644 --- a/src/PinguApps.Appwrite.Client/Clients/AppwriteClient.cs +++ b/src/PinguApps.Appwrite.Client/Clients/AppwriteClient.cs @@ -1,8 +1,9 @@ using PinguApps.Appwrite.Client.Clients; namespace PinguApps.Appwrite.Client; -public class AppwriteClient : IAppwriteClient +public class AppwriteClient : IAppwriteClient, ISessionAware { + /// public IAccountClient Account { get; } public AppwriteClient(IAccountClient accountClient) @@ -13,6 +14,7 @@ public AppwriteClient(IAccountClient accountClient) string? ISessionAware.Session { get; set; } ISessionAware? _sessionAware; + /// public string? Session => GetSession(); private string? GetSession() { @@ -24,6 +26,7 @@ public AppwriteClient(IAccountClient accountClient) return _sessionAware.Session; } + /// public void SetSession(string? session) { (this as ISessionAware).UpdateSession(session); diff --git a/src/PinguApps.Appwrite.Client/Clients/IAccountClient.cs b/src/PinguApps.Appwrite.Client/Clients/IAccountClient.cs index 7b1b32a1..0f9624cf 100644 --- a/src/PinguApps.Appwrite.Client/Clients/IAccountClient.cs +++ b/src/PinguApps.Appwrite.Client/Clients/IAccountClient.cs @@ -4,8 +4,27 @@ using PinguApps.Appwrite.Shared.Responses; namespace PinguApps.Appwrite.Client; + +/// +/// The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity. +/// Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings. +/// This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme. +/// Appwrite Docs +/// public interface IAccountClient { + /// + /// Use this endpoint to allow a new user to register a new account in your project. After the user registration completes successfully, you can use the /account/verfication route to start verifying the user email address. To allow the new user to login to their new account, you need to create a new account session. + /// Appwrite Docs + /// + /// The request content + /// The created user Task> Create(CreateAccountRequest request); + + /// + /// Get the currently logged in user. + /// Appwrite Docs + /// + /// The user Task> Get(); } diff --git a/src/PinguApps.Appwrite.Client/Clients/IAppwriteClient.cs b/src/PinguApps.Appwrite.Client/Clients/IAppwriteClient.cs index ccea18ce..139d953b 100644 --- a/src/PinguApps.Appwrite.Client/Clients/IAppwriteClient.cs +++ b/src/PinguApps.Appwrite.Client/Clients/IAppwriteClient.cs @@ -1,10 +1,26 @@ -using PinguApps.Appwrite.Client.Clients; +namespace PinguApps.Appwrite.Client; -namespace PinguApps.Appwrite.Client; - -public interface IAppwriteClient : ISessionAware +/// +/// The root of the Client SDK. Access all API sections from here +/// +public interface IAppwriteClient { + /// + /// The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity. + /// Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings. + /// This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme. + /// Appwrite Docs + /// IAccountClient Account { get; } + /// + /// Set the session of the logged in user + /// + /// The session token void SetSession(string? session); + + /// + /// The sessio of the currently logged in user + /// + string? Session { get; } } diff --git a/src/PinguApps.Appwrite.Client/Clients/ISessionAware.cs b/src/PinguApps.Appwrite.Client/Clients/ISessionAware.cs index bed10cf6..60672b1d 100644 --- a/src/PinguApps.Appwrite.Client/Clients/ISessionAware.cs +++ b/src/PinguApps.Appwrite.Client/Clients/ISessionAware.cs @@ -1,6 +1,8 @@ namespace PinguApps.Appwrite.Client.Clients; -public interface ISessionAware + +internal interface ISessionAware { public string? Session { get; protected set; } + public void UpdateSession(string? session) => Session = session; } diff --git a/src/PinguApps.Appwrite.Client/ServiceCollectionExtensions.cs b/src/PinguApps.Appwrite.Client/ServiceCollectionExtensions.cs index 2f1a8a25..339b00bd 100644 --- a/src/PinguApps.Appwrite.Client/ServiceCollectionExtensions.cs +++ b/src/PinguApps.Appwrite.Client/ServiceCollectionExtensions.cs @@ -5,8 +5,20 @@ using Refit; namespace PinguApps.Appwrite.Client; + +/// +/// Provides extenions to IServiceCollection, to enable adding the SDK to your DI container +/// public static class ServiceCollectionExtensions { + /// + /// Adds all necessary components for the Client SDK to work as a singleton. Best used on client-side + /// + /// The service collection to add to + /// Your Appwrite Project ID + /// Your Appwrite Endpoint. Defaults to the cloud endpoint. + /// Custom refit settings to customise the SDK. + /// The service collection, enabling chaining public static IServiceCollection AddAppwriteClient(this IServiceCollection services, string projectId, string endpoint = "https://cloud.appwrite.io/v1", RefitSettings? refitSettings = null) { services.AddSingleton(sp => new HeaderHandler(projectId)); @@ -21,6 +33,14 @@ public static IServiceCollection AddAppwriteClient(this IServiceCollection servi return services; } + /// + /// Adds all necessary components for the Client SDK in a transient state. Best used on server-side to perform client SDK abilities on behalf of users + /// + /// The service collection to add to + /// Your Appwrite Project ID + /// Your Appwrite Endpoint. Defaults to the could endpoint. + /// Custom refit settings to customise the SDK. + /// The service collection, enabling chaining public static IServiceCollection AddAppwriteClientForServer(this IServiceCollection services, string projectId, string endpoint = "https://cloud.appwrite.io/v1", RefitSettings? refitSettings = null) { services.AddSingleton(sp => new HeaderHandler(projectId)); diff --git a/src/PinguApps.Appwrite.Common/AppwriteError.cs b/src/PinguApps.Appwrite.Common/AppwriteError.cs index 7fba2bff..8c57337f 100644 --- a/src/PinguApps.Appwrite.Common/AppwriteError.cs +++ b/src/PinguApps.Appwrite.Common/AppwriteError.cs @@ -1,6 +1,14 @@ using System.Text.Json.Serialization; namespace PinguApps.Appwrite.Shared; + +/// +/// An error thrown from Appwrite +/// +/// The message returned from Appwrite +/// Http Status Code of the response +/// The type of error thrown +/// The version of Appwrite throwing the error public record AppwriteError( [property: JsonPropertyName("message")] string Message, [property: JsonPropertyName("code")] int Code, diff --git a/src/PinguApps.Appwrite.Common/AppwriteResult.cs b/src/PinguApps.Appwrite.Common/AppwriteResult.cs index 76502edc..d0a04fc5 100644 --- a/src/PinguApps.Appwrite.Common/AppwriteResult.cs +++ b/src/PinguApps.Appwrite.Common/AppwriteResult.cs @@ -1,6 +1,11 @@ using OneOf; namespace PinguApps.Appwrite.Shared; + +/// +/// The result of all API calls +/// +/// the type of response expected on success public class AppwriteResult { public AppwriteResult(OneOf result) @@ -8,9 +13,28 @@ public AppwriteResult(OneOf result) Result = result; } + /// + /// The result of making the API call. Can be , or depending on what happened + /// public OneOf Result { get; } + + /// + /// Indicates the API call was successful + /// public bool Success => Result.IsT0; + + /// + /// Indicates there is an error + /// public bool IsError => Result.IsT1 || Result.IsT2; + + /// + /// Indicates that there was an error thrown within Appwrite + /// public bool IsAppwriteError => Result.IsT1; + + /// + /// Indicates that there was an error thrown within the SDK + /// public bool IsInternalError => Result.IsT2; } diff --git a/src/PinguApps.Appwrite.Common/Enums/TargetProviderType.cs b/src/PinguApps.Appwrite.Common/Enums/TargetProviderType.cs index f39c7d25..c187dbc1 100644 --- a/src/PinguApps.Appwrite.Common/Enums/TargetProviderType.cs +++ b/src/PinguApps.Appwrite.Common/Enums/TargetProviderType.cs @@ -1,12 +1,25 @@ using System.Runtime.Serialization; namespace PinguApps.Appwrite.Shared.Enums; + +/// +/// The type of target +/// public enum TargetProviderType { + /// + /// Email + /// [EnumMember(Value = "email")] Email, + /// + /// Sms + /// [EnumMember(Value = "sms")] Sms, + /// + /// Push + /// [EnumMember(Value = "push")] Push } diff --git a/src/PinguApps.Appwrite.Common/InternalError.cs b/src/PinguApps.Appwrite.Common/InternalError.cs index 89023dc8..14517c4d 100644 --- a/src/PinguApps.Appwrite.Common/InternalError.cs +++ b/src/PinguApps.Appwrite.Common/InternalError.cs @@ -1,4 +1,9 @@ namespace PinguApps.Appwrite.Shared; + +/// +/// An internal error, indicating a fault within the SDK rather than Appwrite +/// +/// The message of any thrown exception public record InternalError( string Message ); diff --git a/src/PinguApps.Appwrite.Common/Requests/CreateAccountRequest.cs b/src/PinguApps.Appwrite.Common/Requests/CreateAccountRequest.cs index 79de3011..45ed939e 100644 --- a/src/PinguApps.Appwrite.Common/Requests/CreateAccountRequest.cs +++ b/src/PinguApps.Appwrite.Common/Requests/CreateAccountRequest.cs @@ -2,17 +2,33 @@ using PinguApps.Appwrite.Shared.Utils; namespace PinguApps.Appwrite.Shared.Requests; + +/// +/// The request for creating an account +/// public class CreateAccountRequest { + /// + /// User ID. Choose a custom ID or generate a random ID with . Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars + /// [JsonPropertyName("userId")] public string UserId { get; set; } = IdUtils.GenerateUniqueId(); + /// + /// User email + /// [JsonPropertyName("email")] public string Email { get; set; } = string.Empty; + /// + /// New user password. Must be between 8 and 256 chars + /// [JsonPropertyName("password")] public string Password { get; set; } = string.Empty; + /// + /// User name. Max length: 128 chars + /// [JsonPropertyName("name")] public string? Name { get; set; } } diff --git a/src/PinguApps.Appwrite.Common/Responses/HashOptions.cs b/src/PinguApps.Appwrite.Common/Responses/HashOptions.cs index 9b68903f..dec12232 100644 --- a/src/PinguApps.Appwrite.Common/Responses/HashOptions.cs +++ b/src/PinguApps.Appwrite.Common/Responses/HashOptions.cs @@ -1,6 +1,14 @@ using System.Text.Json.Serialization; namespace PinguApps.Appwrite.Shared.Responses; + +/// +/// Password hashing algorithm information +/// +/// The hashing algorithm +/// The memory cost of the hash +/// The time cost of the hash +/// The threads used public record HashOptions( [property: JsonPropertyName("type")] string Type, [property: JsonPropertyName("memoryCost")] long MemoryCost, diff --git a/src/PinguApps.Appwrite.Common/Responses/Target.cs b/src/PinguApps.Appwrite.Common/Responses/Target.cs index 0e6c64cb..05200ac5 100644 --- a/src/PinguApps.Appwrite.Common/Responses/Target.cs +++ b/src/PinguApps.Appwrite.Common/Responses/Target.cs @@ -3,6 +3,17 @@ using PinguApps.Appwrite.Shared.Enums; namespace PinguApps.Appwrite.Shared.Responses; +/// +/// A user-owned message receiver. A single user may have multiple e.g. emails, phones, and a browser. Each target is registered with a single provider. +/// +/// Target ID +/// Target creation time in ISO 8601 format +/// Target update date in ISO 8601 format +/// Target Name +/// User ID +/// Provider ID +/// The target provider type. Can be one of the following: `email`, `sms` or `push` +/// The target identifier public record Target( [property: JsonPropertyName("$id")] string Id, [property: JsonPropertyName("$createdAt")] DateTime CreatedAt, diff --git a/src/PinguApps.Appwrite.Common/Responses/User.cs b/src/PinguApps.Appwrite.Common/Responses/User.cs index 1d1affee..34a3d019 100644 --- a/src/PinguApps.Appwrite.Common/Responses/User.cs +++ b/src/PinguApps.Appwrite.Common/Responses/User.cs @@ -3,6 +3,30 @@ using System.Text.Json.Serialization; namespace PinguApps.Appwrite.Shared.Responses; + +/// +/// An Appwrite User object +/// +/// User ID +/// User creation date in ISO 8601 format +/// User update date in ISO 8601 format +/// User name +/// Hashed user password +/// Password hashing algorithm +/// Password hashing algorithm configuration. Can be one of: +/// AlgoArgon2 model, AlgoScrypt model, AlgoScryptModified model, AlgoBcrypt model, AlgoPHPass model, AlgoSHA model, AlgoMD5 model +/// User registration date in ISO 8601 format +/// User status. Pass `true` for enabled and `false` for disabled +/// Labels for the user +/// Password update time in ISO 8601 format +/// User email address +/// User phone number in E.164 format +/// Email verification status +/// Phone verification status +/// Multi factor authentication status +/// User preferences as a key-value object +/// A user-owned message receiver. A single user may have multiple e.g. emails, phones, and a browser. Each target is registered with a single provider. Can be one of: +/// Most recent access date in ISO 8601 format. This attribute is only updated again after 24 hours public record User( [property: JsonPropertyName("$id")] string Id, [property: JsonPropertyName("$createdAt")] DateTime CreatedAt, diff --git a/src/PinguApps.Appwrite.Common/Utils/IdUtils.cs b/src/PinguApps.Appwrite.Common/Utils/IdUtils.cs index b698e1c8..25c9fe6f 100644 --- a/src/PinguApps.Appwrite.Common/Utils/IdUtils.cs +++ b/src/PinguApps.Appwrite.Common/Utils/IdUtils.cs @@ -2,10 +2,18 @@ using System.Linq; namespace PinguApps.Appwrite.Shared.Utils; + +/// +/// Utilities for Appwrite Id properties +/// public static class IdUtils { - private static readonly Random _random = new Random(); + private static readonly Random _random = new(); + /// + /// Generates a Hex Timestamp, used in Id's + /// + /// a string of the hex timestamp for UTC now public static string GetHexTimestamp() { var dt = DateTimeOffset.UtcNow; @@ -15,6 +23,11 @@ public static string GetHexTimestamp() return sec.ToString("x") + msec.ToString("x").PadLeft(5, '0'); } + /// + /// Generates a unique Id under the same rules that Appwrite uses to generate unique Ids + /// + /// The padding to use - defaults to 7 + /// A unique Id, in line with Appwrite Id generation rules public static string GenerateUniqueId(int padding = 7) { var baseId = GetHexTimestamp(); diff --git a/src/PinguApps.Appwrite.Server/Servers/IAccountServer.cs b/src/PinguApps.Appwrite.Server/Servers/IAccountServer.cs index 1e2b6607..a9b63d56 100644 --- a/src/PinguApps.Appwrite.Server/Servers/IAccountServer.cs +++ b/src/PinguApps.Appwrite.Server/Servers/IAccountServer.cs @@ -4,7 +4,20 @@ using PinguApps.Appwrite.Shared.Responses; namespace PinguApps.Appwrite.Server.Servers; + +/// +/// The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity. +/// Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings. +/// This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme. +/// Appwrite Docs +/// public interface IAccountServer { + /// + /// Use this endpoint to allow a new user to register a new account in your project. After the user registration completes successfully, you can use the /account/verfication route to start verifying the user email address. To allow the new user to login to their new account, you need to create a new account session. + /// Appwrite Docs + /// + /// The request content + /// The created user Task> Create(CreateAccountRequest request); } diff --git a/src/PinguApps.Appwrite.Server/Servers/IAppwriteServer.cs b/src/PinguApps.Appwrite.Server/Servers/IAppwriteServer.cs index 3fdd19e6..db525f1c 100644 --- a/src/PinguApps.Appwrite.Server/Servers/IAppwriteServer.cs +++ b/src/PinguApps.Appwrite.Server/Servers/IAppwriteServer.cs @@ -1,6 +1,15 @@ namespace PinguApps.Appwrite.Server.Servers; +/// +/// The root of the Client SDK. Access all API sections from here +/// public interface IAppwriteServer { + /// + /// The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity. + /// Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings. + /// This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme. + /// Appwrite Docs + /// IAccountServer Account { get; } -} \ No newline at end of file +} diff --git a/src/PinguApps.Appwrite.Server/ServiceCollectionExtensions.cs b/src/PinguApps.Appwrite.Server/ServiceCollectionExtensions.cs index 92e17d7c..a5bad40c 100644 --- a/src/PinguApps.Appwrite.Server/ServiceCollectionExtensions.cs +++ b/src/PinguApps.Appwrite.Server/ServiceCollectionExtensions.cs @@ -6,8 +6,21 @@ using Refit; namespace PinguApps.Appwrite.Server; + +/// +/// Provides extenions to IServiceCollection, to enable adding the SDK to your DI container +/// public static class ServiceCollectionExtensions { + /// + /// Adds all necessary components for the Server SDK + /// + /// The service collection to add to + /// Your Appwrite Project ID + /// Your Appwrite Api Key + /// Your Appwrite Endpoint. Defaults to the cloud endpoint. + /// Custom refit settings to customise the SDK. + /// The service collection, enabling chaining public static IServiceCollection AddAppwriteServer(this IServiceCollection services, string projectId, string apiKey, string endpoint = "https://cloud.appwrite.io/v1", RefitSettings? refitSettings = null) { services.AddSingleton(sp => new HeaderHandler(projectId, apiKey));