Authlink.Portal.Client.Http 2.0.0

📦 Package Overview

Authlink.Portal.Client.Http provides a ready-to-use, production-grade implementation of the IPortalClient abstraction defined in Authlink.Portal.Client.Core.

🚀 Install

dotnet add package Authlink.Portal.Client.Http

Or via Package Manager:

PM> Install-Package Authlink.Portal.Client.Http

🆕 What's New in v2.0

Breaking Changes

All methods now return ErrorOr<TResponse> instead of throwing exceptions. This provides:

• ✅ Type-safe error handling
• ✅ Comprehensive error information (status codes, response bodies, exception details)
• ✅ Better control flow without try-catch blocks
• ✅ Rich metadata for debugging and logging

🛠️ Usage Examples

Setup

builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
});

Basic Usage with Error Handling

public class MyService
{
    private readonly IPortalClient _client;

    public MyService(IPortalClient client)
    {
        _client = client;
    }

    public async Task GetUsersAsync()
    {
        var request = new UsersRequest
        {
            PageNumber = 1,
            PageSize = 10
        };

        var result = await _client.UsersAsync(request);

        if (result.IsError)
        {
            // Handle error
            var error = result.FirstError;
            Console.WriteLine($"Error: {error.Code} - {error.Description}");

            // Access metadata
            if (error.Metadata.TryGetValue("StatusCode", out var statusCode))
            {
                Console.WriteLine($"HTTP Status: {statusCode}");
            }

            if (error.Metadata.TryGetValue("ResponseBody", out var body))
            {
                Console.WriteLine($"Response: {body}");
            }

            return;
        }

        // Success - use the value
        var response = result.Value;
        Console.WriteLine($"Found {response.TotalCount} users");
        foreach (var user in response.Users)
        {
            Console.WriteLine($"- {user.FirstName} {user.LastName}");
        }
    }
}

Pattern Matching

var result = await _client.UserAsync(new UserRequest { UserId = userId });

return result.Match(
    user => Ok(user),
    errors => errors[0].Type switch
    {
        ErrorType.NotFound => NotFound(),
        ErrorType.Unauthorized => Unauthorized(),
        ErrorType.Forbidden => Forbid(),
        _ => Problem(errors[0].Description)
    }
);

Switching on Error Type

var result = await _client.CreateUserAsync(request);

if (result.IsError)
{
    var error = result.FirstError;

    return error.Type switch
    {
        ErrorType.Validation => BadRequest(error.Description),
        ErrorType.Conflict => Conflict(error.Description),
        ErrorType.Unauthorized => Unauthorized(),
        ErrorType.Forbidden => Forbid(),
        _ => StatusCode(500, error.Description)
    };
}

return Ok(result.Value);

🔧 Error Types

The client returns specific error types for common scenarios:

📊 Error Metadata

All errors include metadata for detailed diagnostics:

if (result.IsError)
{
    var error = result.FirstError;

    // Available metadata keys:
    // - StatusCode: HTTP status code (int)
    // - StatusCodeName: Status code name (string)
    // - ResponseBody: Raw response content (string)
    // - RequestPath: The path that failed (string)
    // - ExceptionType: Exception type name (string)
    // - ExceptionMessage: Exception message (string)
    // - TypeName: Type that failed to deserialize (string)
}

🔄 Migration from v1.x

Before (v1.x)

try
{
    var response = await _client.UsersAsync(request);
    return Ok(response);
}
catch (HttpRequestException ex)
{
    return StatusCode(500, "Request failed");
}

After (v2.0)

var result = await _client.UsersAsync(request);

if (result.IsError)
{
    var error = result.FirstError;
    // Rich error information available
    return Problem(error.Description);
}

return Ok(result.Value);

📚 Documentation

https://docs.authlink.co.za

📄 License

MIT