Axowl.Sdk.Eventing.Client 0.1.1

Axowl.Sdk.Eventing.Client

Bi-directional event SDK for Axowl audit chain:

• Publish customer-defined events (custom.wallet.topup etc) — Axowl seals + archives them in the same chain as managed events (user.login, korean_identity.verified, etc).
• Poll events back — cursor-based, unary RPC (CF Free friendly, no streaming).

Install

dotnet add package Axowl.Sdk.Eventing.Client

Publish (customer → Axowl)

using Axowl.Sdk.Eventing.Abstractions.Contracts;
using Axowl.Sdk.Eventing.Client;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAxowlEventing(opts =>
{
    opts.ApiKey    = builder.Configuration["Axowl:ApiKey"]!;
    opts.Transport = TransportMode.GrpcWithFallback;
});

var app = builder.Build();

app.MapPost("/wallet/topup", async (IAxowlEventClient axowl, TopUpRequest req) =>
{
    // 1) business logic (DB write, etc)
    // ...

    // 2) seal event in Axowl chain
    var sealed = await axowl.PublishAsync(
        eventType:         "custom.wallet.topup",
        businessDataJson:  JsonSerializer.Serialize(new { req.UserId, req.Amount }),
        triggeredBy:       req.UserId.ToString(),
        targetUserId:      req.UserId.ToString());

    return Results.Ok(new {
        log_id          = sealed.LogId,
        integrity_hash  = sealed.IntegrityHash,
        signature       = sealed.Signature,
        sealed_at       = sealed.SealedAt
    });
});

EventType MUST start with custom. — managed namespace (user.*, korean_identity.*, etc.) reserved for Axowl internal handlers.

Poll (Axowl → customer fan-out)

Register handler classes; SDK runs a BackgroundService that calls them.

public class WalletTopUpHandler : IAxowlEventHandler
{
    public IReadOnlyList<string> EventTypePatterns => new[] { "custom.wallet.*" };

    public async Task HandleAsync(AxowlEvent evt, CancellationToken ct)
    {
        // react: send email, update cache, etc.
        // idempotent — same LogId may arrive twice in edge cases (network retry).
    }
}

// Program.cs
services.AddSingleton<IAxowlEventHandler, WalletTopUpHandler>();
services.AddAxowlEventing(opts =>
{
    opts.ApiKey       = "ah_live_...";
    opts.EventTypes   = new[] { "custom.*" };          // poll filter
    opts.PollInterval = TimeSpan.FromSeconds(5);
}, enablePollingService: true);

Programmatic Poll (no fan-out)

var batch = await axowl.PollAsync(
    cursor:     savedCursor,
    eventTypes: new[] { "custom.voucher.*" },
    categories: new[] { "CUSTOM" },
    limit:      100);

foreach (var evt in batch.Events) { /* handle */ }
SaveCursor(batch.NextCursor);

Architecture

EventCategory column distinguishes (CUSTOM vs USER/AUTH/...). Filter via Poll parameters.

Wildcard match (handler + filter)

Configuration reference

public sealed class AxowlEventingClientOptions
{
    public string ServerAddress     { get; set; } = "https://testgrpc.axowl.com";
    public string RestServerAddress { get; set; } = "https://testapi.axowl.com";
    public string ApiKey            { get; set; } = "";
    public TransportMode Transport  { get; set; } = TransportMode.Grpc;

    public TimeSpan PollInterval    { get; set; } = TimeSpan.FromSeconds(5);
    public int      Limit           { get; set; } = 100;
    public IReadOnlyList<string> EventTypes { get; set; } = Array.Empty<string>();
    public IReadOnlyList<string> Categories { get; set; } = Array.Empty<string>();
    public DateTime? SinceUtc       { get; set; }
}

Related

• Axowl.Sdk.Integrity.Client — hash chain primitives
• Axowl.Sdk.Identity.Client — JWT + permission check