DirectivSys.Sdk 1.0.1

DirectivSys.Sdk

Official .NET SDK for DirectivSys Analytics Platform. Enables seamless integration with DirectivSys to receive AI-powered business intelligence directives and submit analytics payloads.

Features

✨ Zero Boilerplate - Automatic webhook endpoint creation
🔒 Secure by Default - Built-in authentication and validation
📦 Strongly Typed - Complete DTOs for all analytics types
🚀 Easy Submission - Fluent API for submitting analytics payloads
⚡ Async/Await - Modern async patterns throughout

Installation

dotnet add package DirectivSys.Sdk

Or via Package Manager Console:

Install-Package DirectivSys.Sdk

Quick Start

1. Configure Services (Program.cs or Startup.cs)

using DirectivSys.Sdk.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add DirectivSys SDK
builder.Services.AddDirectivSys(options =>
{
    options.ApiKey = "your-directivsys-secret-key";
    options.BaseUrl = "https://api.directivsys.com";
    options.ClientId = Guid.Parse("your-client-id");
});

var app = builder.Build();

// Map the webhook endpoint
app.MapDirectivWebhook();

// Set up your callback to handle incoming directives
var directivSys = app.GetDirectivSys();
directivSys.OnDirectiveReceived = HandleDirective;

app.Run();

void HandleDirective(GlobalRecord record)
{
    Console.WriteLine($"Received {record.Directives.Count} directives for {record.AnalyticsType}");
    
    foreach (var directive in record.Directives.OrderBy(d => d.Priority))
    {
        Console.WriteLine($"[Priority {directive.Priority}] {directive.Action}");
        Console.WriteLine($"  Rationale: {directive.Rationale}");
        
        // Execute your business logic based on the directive
        switch (directive.Action)
        {
            case "reorderSupplier":
                var sku = directive.Parameters["sku"].ToString();
                var quantity = Convert.ToInt32(directive.Parameters["quantity"]);
                // Your reorder logic here
                break;
                
            case "launchPromotion":
                var targets = directive.Targets;
                // Your promotion logic here
                break;
        }
    }
}

2. Submit Analytics Data

using DirectivSys.Sdk.Models.Payloads;
using DirectivSys.Sdk.Services;

public class InventoryService
{
    private readonly DirectivSysClient _client;

    public InventoryService(DirectivSysClient client)
    {
        _client = client;
    }

    public async Task AnalyzeInventoryAsync()
    {
        var payload = new InventoryHealthPayload
        {
            Sku = "SKU123",
            StockLevel = 20,
            ReorderPoint = 50,
            SafetyStock = 30,
            ForecastedDemandNext30Days = 200,
            AverageLeadTimeDays = 5,
            Instructions = new List<string>
            {
                "Trigger reorder when stock level falls below reorder point.",
                "Increase safety stock by 10% if average lead time exceeds 7 days."
            }
        };

        var response = await _client.SubmitInventoryHealthAsync(payload);
        Console.WriteLine($"Payload submitted: {response.PayloadId}");
    }
}

Supported Analytics Types

The SDK includes strongly-typed payload classes for all DirectivSys analytics types:

Supply Chain Analytics

• InventoryHealth - Stock level monitoring and reorder recommendations
• SupplierReliability - Supplier performance evaluation
• DemandForecast - Future demand prediction
• CostOptimization - Order quantity and cost optimization

E-Commerce Analytics

• CustomerSegmentation - Customer grouping by behavior and value
• CartAbandonment - Abandoned cart detection and recovery
• SalesFunnelConversion - Conversion rate tracking and optimization
• ProductPerformance - Bestseller and slow-mover identification
• CustomerLifetimeValue - Long-term customer value estimation
• MarketingROI - Campaign effectiveness measurement

API Reference

Configuration

DirectivSysOptions

public class DirectivSysOptions
{
    public string ApiKey { get; set; }        // Required: Your DirectivSys secret key
    public string BaseUrl { get; set; }       // Default: "https://api.directivsys.com"
    public Guid? ClientId { get; set; }       // Required for API submissions
    public int TimeoutSeconds { get; set; }   // Default: 30
}

Core Models

GlobalRecord

The main container for analytics results received via webhook:

public class GlobalRecord
{
    public Guid RecordId { get; set; }
    public Guid ClientId { get; set; }
    public string AnalyticsType { get; set; }
    public List<Directive> Directives { get; set; }
    public List<Metric> Metrics { get; set; }
    public List<Observation> Observations { get; set; }
    public Provenance Provenance { get; set; }
    public DateTime CreatedAt { get; set; }
}

Directive

Actionable recommendations from the AI agent:

public class Directive
{
    public Guid DirectiveId { get; set; }
    public int Priority { get; set; }                    // 1 = highest priority
    public string Action { get; set; }                   // e.g., "reorderSupplier"
    public Dictionary<string, object> Parameters { get; set; }
    public List<string> Targets { get; set; }
    public string Rationale { get; set; }
    public string Status { get; set; }
}

Metric

Calculated business metrics:

public class Metric
{
    public string Name { get; set; }
    public double Value { get; set; }
    public string Unit { get; set; }
    public string Status { get; set; }      // "healthy", "warning", "critical"
    public string Explanation { get; set; }
}

Observation

Human-readable explanations and context:

public class Observation
{
    public string Text { get; set; }
    public string Severity { get; set; }    // "info", "warning", "critical"
    public string Scope { get; set; }       // "global", "product", "supplier"
}

DirectivSysClient Methods

Submit Analytics Payloads

// Specific analytics types
Task<SubmitPayloadResponse> SubmitInventoryHealthAsync(InventoryHealthPayload payload, CancellationToken cancellationToken = default)
Task<SubmitPayloadResponse> SubmitCustomerSegmentationAsync(CustomerSegmentationPayload payload, CancellationToken cancellationToken = default)
Task<SubmitPayloadResponse> SubmitCartAbandonmentAsync(CartAbandonmentPayload payload, CancellationToken cancellationToken = default)
Task<SubmitPayloadResponse> SubmitProductPerformanceAsync(ProductPerformancePayload payload, CancellationToken cancellationToken = default)

// Generic submission for any analytics type
Task<SubmitPayloadResponse> SubmitAnalyticsAsync<T>(string analyticsType, T payload, CancellationToken cancellationToken = default) 
    where T : AnalyticsPayloadBase

Retrieve Results (Polling)

Task<List<GlobalRecord>> GetResultsAsync(
    string? analyticsType = null,
    int limit = 10,
    DateTime? since = null,
    CancellationToken cancellationToken = default)

Advanced Usage

Custom Analytics Types

For analytics types not included in the SDK, use the generic submission method:

public class CustomAnalyticsPayload : AnalyticsPayloadBase
{
    public string CustomField1 { get; set; }
    public int CustomField2 { get; set; }
}

var payload = new CustomAnalyticsPayload
{
    CustomField1 = "value",
    CustomField2 = 42,
    Instructions = new List<string> { "Your natural-language instruction here" }
};

await client.SubmitAnalyticsAsync("CustomAnalyticsType", payload);

Accessing Services Directly

// In a controller or service
public class MyController : ControllerBase
{
    private readonly DirectivSysClient _client;
    private readonly IDirectivSysService _service;

    public MyController(DirectivSysClient client, IDirectivSysService service)
    {
        _client = client;
        _service = service;
        
        // Set callback dynamically
        _service.OnDirectiveReceived = HandleDirective;
    }
}

Error Handling

try
{
    var response = await client.SubmitInventoryHealthAsync(payload);
}
catch (DirectivSysException ex)
{
    // Handle DirectivSys-specific errors
    Console.WriteLine($"DirectivSys error: {ex.Message}");
}
catch (HttpRequestException ex)
{
    // Handle network errors
    Console.WriteLine($"Network error: {ex.Message}");
}

Configuration Best Practices

Using Configuration Files

appsettings.json:

{
  "DirectivSys": {
    "ApiKey": "your-secret-key",
    "BaseUrl": "https://api.directivsys.com",
    "ClientId": "your-client-id-guid",
    "TimeoutSeconds": 30
  }
}

Program.cs:

builder.Services.AddDirectivSys(options =>
{
    builder.Configuration.GetSection("DirectivSys").Bind(options);
});

Using Environment Variables

builder.Services.AddDirectivSys(options =>
{
    options.ApiKey = Environment.GetEnvironmentVariable("DIRECTIVSYS_API_KEY") 
        ?? throw new InvalidOperationException("DIRECTIVSYS_API_KEY not set");
    options.ClientId = Guid.Parse(Environment.GetEnvironmentVariable("DIRECTIVSYS_CLIENT_ID")!);
});

Webhook Security

The webhook endpoint (/directiv/webhook) validates incoming requests using the API key provided in the Authorization header. DirectivSys includes this header automatically when sending webhook notifications.

The validation ensures:

• Request includes Authorization: Bearer {your-api-key} header
• The provided key matches your configured API key
• Payload can be deserialized to GlobalRecord

Example: Complete Integration

using DirectivSys.Sdk.Extensions;
using DirectivSys.Sdk.Models;
using DirectivSys.Sdk.Models.Payloads;
using DirectivSys.Sdk.Services;

var builder = WebApplication.CreateBuilder(args);

// Configure DirectivSys
builder.Services.AddDirectivSys(options =>
{
    options.ApiKey = builder.Configuration["DirectivSys:ApiKey"]!;
    options.ClientId = Guid.Parse(builder.Configuration["DirectivSys:ClientId"]!);
});

// Add your services
builder.Services.AddControllers();
builder.Services.AddHostedService<InventoryAnalysisWorker>();

var app = builder.Build();

app.UseRouting();
app.MapControllers();
app.MapDirectivWebhook();

// Configure directive callback
var directivSys = app.GetDirectivSys();
directivSys.OnDirectiveReceived = record =>
{
    var logger = app.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Received analytics: {Type} with {Count} directives",
        record.AnalyticsType, record.Directives.Count);

    foreach (var directive in record.Directives)
    {
        // Process each directive
        ProcessDirective(directive, app.Services);
    }
};

app.Run();

void ProcessDirective(Directive directive, IServiceProvider services)
{
    var scope = services.CreateScope();
    
    switch (directive.Action)
    {
        case "reorderSupplier":
            var inventoryService = scope.ServiceProvider.GetRequiredService<IInventoryService>();
            inventoryService.Reorder(directive.Parameters["sku"].ToString()!);
            break;
            
        case "launchPromotion":
            var marketingService = scope.ServiceProvider.GetRequiredService<IMarketingService>();
            marketingService.LaunchCampaign(directive.Targets);
            break;
    }
}

// Background worker to periodically submit analytics
public class InventoryAnalysisWorker : BackgroundService
{
    private readonly DirectivSysClient _client;
    private readonly ILogger<InventoryAnalysisWorker> _logger;

    public InventoryAnalysisWorker(DirectivSysClient client, ILogger<InventoryAnalysisWorker> logger)
    {
        _client = client;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                // Aggregate your data
                var inventoryData = await GetCurrentInventoryAsync();
                
                // Submit to DirectivSys
                await _client.SubmitInventoryHealthAsync(inventoryData, stoppingToken);
                
                _logger.LogInformation("Inventory analysis submitted successfully");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to submit inventory analysis");
            }

            // Run daily
            await Task.Delay(TimeSpan.FromHours(24), stoppingToken);
        }
    }

    private async Task<InventoryHealthPayload> GetCurrentInventoryAsync()
    {
        // Your logic to aggregate inventory data
        return new InventoryHealthPayload
        {
            Sku = "SKU123",
            StockLevel = 45,
            ReorderPoint = 50,
            SafetyStock = 30,
            ForecastedDemandNext30Days = 200,
            Instructions = new List<string>
            {
                "Reorder if stock falls below reorder point",
                "Flag critical if stock below safety level"
            }
        };
    }
}

Requirements

• .NET 6.0 or higher
• ASP.NET Core application (for webhook endpoint)

Support

For issues, questions, or feature requests, please visit:

• GitHub Issues: https://github.com/directivsys/directivsys-sdk-dotnet/issues
• Documentation: https://docs.directivsys.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ by DirectivSys Inc