Hapnd.Sdk 0.2.0

Hapnd SDK for .NET

The official .NET SDK for Hapnd - the event sourcing platform built for engineers.

Installation

dotnet add package Hapnd.Sdk

Quick Start

using Hapnd.Sdk;

// Create a client
var hapnd = new HapndClient("sk_live_your_api_key");

// Append an event
var result = await hapnd.Aggregate("order_123")
    .Append(new OrderPlaced { CustomerId = "cust_456" });

Console.WriteLine($"Event {result.EventId} at version {result.Version}");

// Get aggregate state (if sync projection is bound)
if (result.HasState)
{
    var state = result.State<OrderState>();
    Console.WriteLine($"Order total: {state.Total}");
}

Features

• Fluent API - Chain operations naturally
• Convention-based aggregate types - order_123 → aggregate type order
• Optimistic concurrency - Prevent lost updates with version checks
• Built-in resilience - Automatic retries and circuit breaker
• ASP.NET Core integration - First-class dependency injection support

Usage

Appending Events

// Simple append
await hapnd.Aggregate("order_123")
    .Append(new ItemAdded { Item = "Widget", Price = 25.00m });

// With optimistic concurrency
await hapnd.Aggregate("order_123")
    .ExpectVersion(5)
    .Append(new ItemAdded { Item = "Gadget", Price = 15.00m });

// With metadata for tracing
await hapnd.Aggregate("order_123")
    .WithCorrelation("req_abc123")
    .WithCausation("evt_xyz789")
    .WithMetadata(new { UserId = "user_456" })
    .Append(new OrderShipped());

// Multiple events atomically
await hapnd.Aggregate("order_123")
    .AppendMany([
        new ItemAdded { Item = "Widget", Price = 25.00m },
        new ItemAdded { Item = "Gadget", Price = 15.00m }
    ]);

Querying State

var aggregate = await hapnd.Aggregate("order_123")
    .GetState<OrderState>();

if (aggregate is not null)
{
    Console.WriteLine($"Version: {aggregate.Version}");
    Console.WriteLine($"Total: {aggregate.State.Total}");
    Console.WriteLine($"Items: {aggregate.State.ItemCount}");
}

Custom Aggregate Types

By default, aggregate type is inferred from the ID prefix:

For non-standard IDs, specify explicitly:

await hapnd.Aggregate("ORD-2024-00123")
    .WithAggregateType("order")
    .Append(new OrderPlaced());

Custom Event Type Names

By default, the class name is used as the event type. Override with an attribute:

[EventType("order_placed")]
public class OrderPlaced
{
    public string CustomerId { get; init; }
}

ASP.NET Core Integration

// In Program.cs or Startup.cs
services.AddHapnd("sk_live_your_api_key");

// Or with configuration
services.AddHapnd(options =>
{
    options.ApiKey = configuration["Hapnd:ApiKey"];
    options.Timeout = TimeSpan.FromSeconds(60);
});

Then inject IHapndClient:

public class OrderService
{
    private readonly IHapndClient _hapnd;

    public OrderService(IHapndClient hapnd)
    {
        _hapnd = hapnd;
    }

    public async Task PlaceOrder(string customerId)
    {
        var result = await _hapnd.Aggregate($"order_{Guid.NewGuid()}")
            .Append(new OrderPlaced { CustomerId = customerId });
    }
}

Resilience

The SDK includes automatic retry and circuit breaker policies.

Default Behavior

• Retries: 3 attempts with exponential backoff
• Circuit Breaker: Opens after 50% failure rate (minimum 10 requests)

Configuration

services.AddHapnd(options =>
{
    options.ApiKey = "sk_live_your_api_key";
    options.Resilience = new HapndResilienceOptions
    {
        MaxRetryAttempts = 5,
        RetryDelay = TimeSpan.FromMilliseconds(200),
        EnableCircuitBreaker = true,
        CircuitBreakerDuration = TimeSpan.FromSeconds(60)
    };
});

Disable Resilience

options.Resilience = null;

Error Handling

using Hapnd.Sdk;
using Polly.CircuitBreaker;

try
{
    await hapnd.Aggregate("order_123")
        .ExpectVersion(5)
        .Append(new ItemAdded { Item = "Widget" });
}
catch (HapndConcurrencyException ex)
{
    // Version mismatch - reload and retry
    Console.WriteLine($"Expected version {ex.ExpectedVersion}, actual {ex.ActualVersion}");
}
catch (HapndApiException ex)
{
    // Server returned an error
    Console.WriteLine($"API error {ex.StatusCode}: {ex.Message}");
}
catch (HapndNetworkException ex)
{
    // Network failure or timeout
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (BrokenCircuitException)
{
    // Circuit breaker is open - back off
    Console.WriteLine("Service unavailable, try again later");
}

Exception Hierarchy

Requirements

• .NET 9.0 or later

License

Apache 2.0 - see LICENSE for details.