Served.SDK 1.4.0

Served.SDK

The official .NET SDK for the Served API by UnifiedHQ. This library provides a strongly-typed, modern fluent client for interacting with the Served platform, covering Project Management, Task Tracking, Time Registration, Finance, DevOps, and more.

Links

Features

• Module-Based API: Organized access through domain modules (e.g., client.ProjectManagement.Projects).
• Generic & Abstract: Built on reusable base classes for consistent CRUD operations.
• Strongly Typed: Full type safety for all Served entities (Projects, Tasks, Invoices, etc.).
• Modern Async: Built from the ground up with async/await.
• Bulk Operations: Support for batch create, update, and delete operations.
• Error Handling: Custom ServedApiException provides detailed error context.
• Backwards Compatible: Legacy client access patterns still supported.
• Tracing & Observability: Built-in OpenTelemetry support with Forge platform integration.
• Fork & Extend: Open source - fork and run your own pipelines.

Installation

dotnet add package Served.SDK

Quick Start

using Served.SDK.Client;

// Initialize with UnifiedHQ infrastructure (default)
var client = new ServedClientBuilder()
    .WithToken("YOUR_API_TOKEN")
    .WithTenant("YOUR_TENANT_SLUG")
    .WithTracing(options => options.EnableForge = true)  // Enable Forge analytics
    .Build();

// Get projects
var projects = await client.ProjectManagement.Projects.GetAllAsync();

// Create a task
var task = await client.ProjectManagement.Tasks.CreateAsync(new CreateTaskRequest
{
    Name = "My Task",
    ProjectId = projects.First().Id
});

// Log time
await client.Registration.TimeRegistrations.CreateAsync(new CreateTimeRegistrationRequest
{
    TaskId = task.Id,
    Minutes = 60,
    Description = "Working on task"
});

Configuration

Environment Variables

Initialization Options

// Simple initialization (uses UnifiedHQ infrastructure)
var client = new ServedClient(
    baseUrl: ServedClient.DefaultApiUrl,  // https://apis.unifiedhq.ai
    token: "YOUR_API_TOKEN",
    tenant: "YOUR_TENANT_SLUG"
);

// Builder pattern with full control
var client = new ServedClientBuilder()
    .WithBaseUrl("https://apis.unifiedhq.ai")
    .WithToken(token)
    .WithTenant("my-workspace")
    .WithTracing(options =>
    {
        options.ServiceName = "my-application";
        options.EnableForge = true;
        options.SamplingRate = 0.1;
    })
    .Build();

// Dependency injection for ASP.NET Core
services.AddHttpClient<IServedClient, ServedClient>(client =>
{
    client.BaseAddress = new Uri("https://apis.unifiedhq.ai");
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "TOKEN");
});

API Modules

Tracing & Analytics

The SDK includes built-in tracing with OpenTelemetry support and Forge platform integration.

Enable Tracing

var client = new ServedClient("https://apis.unifiedhq.ai", token)
    .EnableTracing();

// Or with builder for full control
var client = new ServedClientBuilder()
    .WithToken(token)
    .WithTracing(options =>
    {
        options.ServiceName = "my-application";
        options.EnableForge = true;
        options.SamplingRate = 0.1;
    })
    .Build();

View Analytics

Once tracing is enabled, view your analytics at:

• Forge Dashboard: forge.unifiedhq.ai/analytics
• Your Workspace: unifiedhq.ai/app/analytics

Custom Events

client.Tracer?.RecordEvent(new TelemetryEvent
{
    Type = TelemetryEventType.Custom,
    Name = "invoice.generated",
    Attributes = new Dictionary<string, object>
    {
        ["invoice.id"] = invoiceId,
        ["invoice.amount"] = amount
    }
});

Fork & Extend

This SDK is open source. Fork it to:

1. Run Your Own Pipelines: Fork the repo and run CI/CD in your environment
2. Extend Functionality: Add custom modules for your use case
3. Contribute Back: Submit PRs to improve the SDK

# Clone your fork
git clone https://github.com/YOUR_USERNAME/served-sdk.git

# Build locally
dotnet build

# Run tests
dotnet test

# Create your own NuGet package
dotnet pack -c Release

Error Handling

try
{
    await client.ProjectManagement.Projects.GetAsync(99999);
}
catch (ServedApiException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    Console.WriteLine("Project not found.");
}
catch (ServedApiException ex)
{
    Console.WriteLine($"API Error: {ex.StatusCode} - {ex.Content}");
}

Support

• Documentation: unifiedhq.ai/docs
• Issues: GitHub Issues
• Discord: UnifiedHQ Community

License

MIT License - see LICENSE for details.

Built with love by UnifiedHQ