Xyo.Sdk 2.1.0

XYO Financial SDK for .NET

The official .NET SDK for XYO Financial.
Seamlessly enrich raw financial transactions into clean merchant profiles, intelligent business categorizations, high-res logos, and geolocated address metadata using AI-powered enrichment pipelines.

✨ Key Features

• ⚡ High-Throughput Async/Await: Pure non-blocking Task-based asynchronous architecture with CancellationToken support on all operations.
• 💉 First-Class Dependency Injection: Seamless ASP.NET Core and Generic Host integration via services.AddXyoClient() with SocketsHttpHandler socket pooling.
• 🌊 Memory-Safe Batch Streaming: $O(1)$ memory streaming .tar.gz decompression yielding records on-the-fly without buffering multi-gigabyte archives.
• 🛡️ Enterprise Security Hardening: Zero-Trust domain validation (CWE-183), SSRF defense, Zip Slip mitigation (CWE-22), and decompression bomb limits (CWE-400).
• 📋 RFC 7807 Problem Details: Rich, typed exception hierarchy mapping API validation errors and HTTP status codes to actionable diagnostics.
• 🔄 Dynamic Token Rotation: Seamless support for cloud secret stores (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) via asynchronous key suppliers.

⚙️ Requirements & Compatibility

📦 Installation

Install the package from NuGet:

.NET CLI

dotnet add package Xyo.Sdk

Package Manager Console

Install-Package Xyo.Sdk

PackageReference

<PackageReference Include="Xyo.Sdk" Version="2.1.0" />

🚀 Quickstart Guide

1. Direct Client Instantiation

using Xyo.Sdk.Client;

// Initialize client with API key
using var client = new XyoClient("xyo_live_your_api_key_here");

// Synchronously enrich a single transaction description
var response = await client.EnrichTransactionAsync("SQ *COSTA COFFEE GREENWICH", "GB");

Console.WriteLine($"Merchant:    {response.Merchant}");
Console.WriteLine($"Description: {response.Description}");
Console.WriteLine($"Categories:  {string.Join(", ", response.Categories)}");
Console.WriteLine($"Logo URL:    {response.Logo}");

📚 Core Operations & Code Examples

1. Real-Time Single Transaction Enrichment

using Xyo.Generated.Model;
using Xyo.Sdk.Client;

var request = new EnrichmentRequest(
    content: "TFL TRAVEL CHARGE TFL.GOV.UK",
    countryCode: "GB"
);

var response = await client.EnrichTransactionAsync(request);

Console.WriteLine($"Merchant: {response.Merchant}");
Console.WriteLine($"Address:  {response.Address}");

2. High-Throughput Bulk Batch Submission

Submit batches of transactions for asynchronous parallel processing:

var batch = new List<EnrichmentRequest>
{
    new("UBER *TRIP 12345", "GB"),
    new("STARBUCKS STORE #10423", "US"),
    new("AMZN Mktp US*1A2B3C", "US")
};

// Submit batch (optionally attaching tenant user identifier for audit logs)
var batchResponse = await client.EnrichTransactionsAsync(batch, apiUser: "tenant_bank_01");

Console.WriteLine($"Job ID:       {batchResponse.Id}");
Console.WriteLine($"Download URL: {batchResponse.Link}");

// Poll job status
var statusResponse = await client.GetEnrichmentStatusAsync(batchResponse.Id);
Console.WriteLine($"Job Status: {statusResponse.Status}");

3. Memory-Safe Streaming Batch Download ($O(1)$ Memory)

Stream records on-the-fly directly from the compressed .tar.gz archive:

// Stream records one-by-one with sub-megabyte memory overhead
await foreach (var record in client.StreamEnrichmentCollectionAsync(batchResponse.Link))
{
    Console.WriteLine($"[Enriched] {record.Merchant} -> {string.Join("/", record.Categories)}");
}

Or deserialize the entire archive into a read-only list:

IReadOnlyList<EnrichmentResponse> results = await client.DownloadEnrichmentCollectionAsync(batchResponse.Link);
Console.WriteLine($"Downloaded {results.Count} enriched records.");

4. Dynamic Token Rotation (Key Vault / Secrets Manager)

Configure an asynchronous key supplier for zero-downtime secret rotation:

var config = new XyoClientConfig()
    .WithTokenSupplier(async (cancellationToken) =>
    {
        // Retrieve fresh token from Azure Key Vault, AWS Secrets Manager, etc.
        return await secretVault.GetSecretAsync("XYO_API_KEY", cancellationToken);
    });

using var dynamicClient = new XyoClient(config);

🚀 Framework & Architecture Integration

The XYO Financial .NET SDK is engineered for institutional-grade reliability, high-concurrency microservices, and cloud-native deployments across .NET 8, .NET 9, and upcoming .NET 10 LTS runtimes.

1. ASP.NET Core 8 / 9 Integration with Polly Resilience

Register IXyoClient in Program.cs using the official dependency injection extension methods with Microsoft Polly transient error retry policies and circuit breakers:

// ASP.NET Core: Program.cs
using System;
using System.Collections.Generic;
using System.Threading;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Polly;
using Xyo.Generated.Model;
using Xyo.Sdk.Client;
using Xyo.Sdk.Exceptions;
using Xyo.Sdk.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register XYO Client with configuration options and Polly retry policies
builder.Services.AddXyoClient(options => 
{
    options.ApiKey = builder.Configuration["Xyo:ApiKey"]!;
    options.BaseUrl = builder.Configuration["Xyo:BaseUrl"] ?? "https://api.xyo.financial";
    options.Timeout = TimeSpan.FromSeconds(2);
    options.CorrelationId = "banking-api-gateway";
})
.AddTransientHttpErrorPolicy(policy => 
    policy.WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromMilliseconds(200 * retryAttempt)));

var app = builder.Build();

// High-performance Minimal API endpoint
app.MapPost("/api/v1/enrich", async (EnrichmentDto dto, IXyoClient xyoClient, CancellationToken ct) =>
{
    try
    {
        var response = await xyoClient.EnrichTransactionAsync(dto.Description, dto.CountryCode, ct);
        return Results.Ok(response);
    }
    catch (XyoProblemDetailsException ex)
    {
        return Results.Problem(
            title: ex.Title,
            detail: ex.Detail,
            statusCode: ex.Status,
            type: ex.Type,
            extensions: new Dictionary<string, object?> { ["errors"] = ex.Errors }
        );
    }
});

app.Run();

public record EnrichmentDto(string Description, string CountryCode);

2. High-Performance Architectural Highlights

Pooled SocketsHttpHandler Socket Lifetime Management

When registering via AddXyoClient, the SDK configures a pooled SocketsHttpHandler instance with PooledConnectionLifetime = TimeSpan.FromMinutes(15) and SetHandlerLifetime(Timeout.InfiniteTimeSpan). This follows modern .NET networking best practices, preventing socket exhaustion (TIME_WAIT proliferation) during burst traffic while ensuring DNS record updates are respected without recycling handler instances.

Zero Large Object Heap (LOH) Allocations

Traditional batch processing reads entire multi-gigabyte compressed .tar.gz archives into memory buffers, causing objects $\ge 85,000$ bytes to be allocated directly onto the Large Object Heap (LOH). The XYO SDK utilizes a streaming push/pull decompression architecture that reads records chunk-by-chunk directly into pooled memory buffers, maintaining strict $O(1)$ memory consumption regardless of whether the archive contains 100 or 10,000,000 transactions.

Native AOT (Ahead-Of-Time) Compilation

The SDK is fully compatible with .NET Native AOT publishing (PublishAot=true). By avoiding dynamic runtime code emission and untyped reflection, binaries compile directly into native machine code for maximum security and execution speed:

dotnet publish -c Release -r linux-x64 --self-contained

3. Enterprise Background Worker Service (BackgroundService)

For continuous batch processing and automated reconciliation pipelines, inject IXyoClient inside an IHostedService / BackgroundService:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Xyo.Sdk.Client;

public sealed class TransactionBatchWorker : BackgroundService
{
    private readonly IXyoClient _xyoClient;
    private readonly ILogger<TransactionBatchWorker> _logger;

    public TransactionBatchWorker(IXyoClient xyoClient, ILogger<TransactionBatchWorker> logger)
    {
        _xyoClient = xyoClient;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                // Ingest archive stream on-the-fly with O(1) memory overhead
                string downloadUrl = "https://download.xyo.financial/batches/reconciliation_2026_08.tar.gz";
                
                await foreach (var record in _xyoClient.StreamEnrichmentCollectionAsync(downloadUrl, stoppingToken))
                {
                    _logger.LogInformation("Processed transaction {Merchant} ({Category})", 
                        record.Merchant, string.Join(", ", record.Categories));
                }
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                _logger.LogError(ex, "Transient batch ingestion failure occurred. Retrying...");
            }

            await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
        }
    }
}

🛡 Exception Handling & RFC 7807 Problem Details

The SDK throws strongly-typed exceptions conforming to the RFC 7807 Problem Details specification:

using Xyo.Sdk.Exceptions;

try
{
    var result = await client.EnrichTransactionAsync("COSTA", "INVALID_CODE");
}
catch (XyoProblemDetailsException ex)
{
    // RFC 7807 Structured Problem Details
    Console.WriteLine($"HTTP Status: {ex.Status}");
    Console.WriteLine($"Title:       {ex.Title}");
    Console.WriteLine($"Detail:      {ex.Detail}");
    Console.WriteLine($"Type:        {ex.Type}");

    if (ex.Errors != null)
    {
        foreach (var (field, errors) in ex.Errors)
        {
            Console.WriteLine($"  Field '{field}': {string.Join(", ", errors)}");
        }
    }
}
catch (XyoServerException ex) when (ex.IsRetryable())
{
    // Transient 5xx server errors safe for exponential backoff
    Console.WriteLine($"Transient server error: {ex.StatusCode}. Retrying...");
}
catch (XyoNetworkException ex)
{
    // Transport errors (DNS, timeout, connection resets)
    Console.WriteLine($"Network failure: {ex.Message}");
}

🔒 Security & Defensive Architecture

• Zero-Trust Domain Egress Allowlist: Validates all archive download URLs against pinned official domains (api.xyo.financial, download.xyo.financial, AWS S3 storage hosts) and strictly rejects cleartext HTTP.
• Credential Leakage Prevention: Strips Bearer authorization headers when following download links to third-party or S3 storage buckets.
• Decompression Bomb Defense (CWE-400): Streaming Tar and GZip decoders enforce hard limits on total archive byte ingestion, per-entry sizes, and entry counts.
• Zip Slip Defense (CWE-22): Rejects directory traversal sequences and rooted paths in archive entry names.
• CRLF Injection Prevention (CWE-113): Validates custom headers and user IDs against carriage return and newline characters.

📄 License

Distributed under the Apache License, Version 2.0. See LICENSE for details.

🤝 Support & Security

• Documentation & Portal: xyo.financial
• Security Policy & Vulnerability Reporting: SECURITY.md / security@syniol.com
• Contribution Guidelines: CONTRIBUTING.md