PropertyDashboard.Client.Sdk 1.1.6

PropertyDashboard Client SDK

A modern, strongly-typed .NET client SDK for the PropertyDashboard API with built-in authentication support, NodaTime integration, and System.Text.Json serialization.

Features

• Strongly Typed - Full C# type safety with auto-generated models from OpenAPI specification
• Auth0 Integration - Built-in authentication with automatic token management
• NodaTime Support - Proper date/time handling with NodaTime types
• Modern JSON - Uses System.Text.Json for optimal performance
• Dependency Injection - First-class support for .NET DI container
• Async/Await - Fully asynchronous API with cancellation token support
• Auto-generated - Always up-to-date with the latest API changes

Installation

From NuGet.org (Recommended)

dotnet add package PropertyDashboard.Client.Sdk

From GitHub Packages

# Add GitHub Packages source (one-time setup)
dotnet nuget add source \
  --username YOUR_GITHUB_USERNAME \
  --password YOUR_GITHUB_TOKEN \
  --store-password-in-clear-text \
  --name github \
  "https://nuget.pkg.github.com/szymonhel/index.json"

# Install the package
dotnet add package PropertyDashboard.Client.Sdk --source github

Quick Start

1. Register the Client

Choose the authentication method that fits your use case:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using PropertyDashboard.Client.Sdk;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        // Option A: No authentication (development only)
        services.AddPropertyDashboardClient("http://localhost:5000");

        // Option B: Static bearer token
        services.AddPropertyDashboardClient(
            "https://api.propertydashboard.com",
            "your-bearer-token"
        );

        // Option C: Auth0 with automatic token management (recommended)
        services.AddPropertyDashboardClientWithAuth0(
            baseUrl: "https://api.propertydashboard.com",
            tokenEndpoint: "https://your-tenant.auth0.com/oauth/token",
            clientId: "your-client-id",
            clientSecret: "your-client-secret",
            audience: "https://api.propertydashboard.com",
            tenantId: "your-tenant-id"
        );
    })
    .Build();

2. Use the Client

using PropertyDashboard.Client.Sdk;

public class PropertyService
{
    private readonly PropertyDashboardClient _client;

    public PropertyService(PropertyDashboardClient client)
    {
        _client = client;
    }

    public async Task<ICollection<RoomTypeDto>> GetRoomTypesAsync()
    {
        var result = await _client.Get_all_room_typesAsync();
        return result.RoomTypes ?? new List<RoomTypeDto>();
    }

    public async Task<ReservationBillingResult> GetReservationBillingAsync(Guid reservationId)
    {
        return await _client.Get_reservation_billingAsync(reservationId);
    }
}

Authentication Options

Option 1: No Authentication

Perfect for local development or public APIs:

services.AddPropertyDashboardClient("http://localhost:5000");

Option 2: Static Bearer Token

When you already have an access token:

services.AddPropertyDashboardClient(
    "https://api.propertydashboard.com",
    "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
);

Option 3: Auth0 Integration (Recommended)

Automatic token acquisition and renewal:

services.AddPropertyDashboardClientWithAuth0(
    baseUrl: "https://api.propertydashboard.com",
    tokenEndpoint: "https://your-tenant.auth0.com/oauth/token",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    audience: "https://api.propertydashboard.com",
    tenantId: "your-tenant-id"
);

Benefits:

• Automatic token acquisition
• Token caching and renewal
• Secure credential management
• Multi-tenant support

API Examples

Reservations & Billing

// Get reservation billing
var billing = await client.Get_reservation_billingAsync(reservationId);
Console.WriteLine($"Total: {billing.TotalAmount}");

// Add payment transaction
await client.Post_transactionAsync(reservationId, new AddReservationPaymentDto
{
    Amount = 100.00m,
    PaymentMethod = PaymentMethod.CreditCard
});

// Generate invoice
var invoiceUri = await client.Generate_invoiceAsync(reservationId);
Console.WriteLine($"Invoice: {invoiceUri}");

// Close billing
await client.Close_billingAsync(reservationId);

Products & Categories

// Get all product categories
var categories = await client.Get_list_of_product_categoriesAsync();

// Create new product category
var categoryId = await client.ProductCategoriesAsync(new UpsertProductCategoryCommand
{
    Name = "Room Service",
    Description = "In-room dining and services"
});

// Get all products
var products = await client.Get_list_of_productsAsync();

// Create new product
var productId = await client.ProductsAsync(new UpsertProductCommand
{
    Name = "Breakfast",
    Price = 15.00m,
    CategoryId = categoryId
});

Company Profiles

// Create company profile
var result = await client.Create_company_profileAsync(new CreateCompanyCommand
{
    Name = "Acme Corporation",
    TaxIdentifier = "123456789",
    Email = "billing@acme.com"
});

// Query companies
var companies = await client.Query_companiesAsync(
    name: "Acme",
    taxIdentifier: null
);

Add-ons

// Book add-on for reservation
await client.Book_add_onAsync(reservationId, new BookAddOnDto
{
    ProductId = productId,
    Quantity = 2,
    Date = LocalDate.FromDateTime(DateTime.Today)
});

NodaTime Integration

This SDK uses NodaTime for better date/time handling:

using NodaTime;

// LocalDate for dates without time
var checkInDate = new LocalDate(2025, 10, 23);

// Instant for timestamps
var createdAt = SystemClock.Instance.GetCurrentInstant();

// LocalDateTime for date + time without timezone
var appointmentTime = new LocalDateTime(2025, 10, 23, 14, 30);

// Duration for time spans
var stayDuration = Duration.FromDays(3);

Why NodaTime?

• No timezone ambiguity issues
• Explicit about what kind of date/time you're working with
• Better API design than DateTime
• Proper serialization support

Error Handling

The SDK throws strongly-typed exceptions for different error scenarios:

try
{
    var result = await client.Get_reservation_billingAsync(reservationId);
}
catch (ApiException apiEx) when (apiEx.StatusCode == 404)
{
    Console.WriteLine("Reservation not found");
}
catch (ApiException apiEx) when (apiEx.StatusCode == 401)
{
    Console.WriteLine("Authentication failed - check your credentials");
}
catch (ApiException apiEx)
{
    Console.WriteLine($"API Error: {apiEx.StatusCode} - {apiEx.Message}");
    Console.WriteLine($"Response: {apiEx.Response}");
}
catch (HttpRequestException httpEx)
{
    Console.WriteLine($"Network error: {httpEx.Message}");
    Console.WriteLine("Ensure the API is running and accessible");
}

Cancellation Support

All API methods support cancellation tokens:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

try
{
    var result = await client.Get_all_room_typesAsync(cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Request was cancelled or timed out");
}

Autofac Integration

The SDK also supports Autofac DI container:

using Autofac;
using PropertyDashboard.Client.Sdk;

var builder = new ContainerBuilder();

// Register the client module
builder.RegisterModule(new PropertyDashboardClientModule
{
    BaseUrl = "https://api.propertydashboard.com",
    TokenEndpoint = "https://your-tenant.auth0.com/oauth/token",
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",
    Audience = "https://api.propertydashboard.com",
    TenantId = "your-tenant-id"
});

var container = builder.Build();
var client = container.Resolve<PropertyDashboardClient>();

Configuration

Customize HttpClient

services.AddPropertyDashboardClient("https://api.propertydashboard.com")
    .ConfigureHttpClient(http =>
    {
        http.Timeout = TimeSpan.FromSeconds(60);
        http.DefaultRequestHeaders.Add("X-Custom-Header", "value");
    });

Configure JSON Serialization

The SDK uses System.Text.Json with NodaTime support. To customize serialization:

// Create a partial class to extend the generated client
namespace PropertyDashboard.Client.Sdk
{
    public partial class PropertyDashboardClient
    {
        static partial void UpdateJsonSerializerSettings(JsonSerializerOptions settings)
        {
            settings.PropertyNameCaseInsensitive = true;
            settings.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
            // Add more customizations as needed
        }
    }
}

Requirements

• .NET 9.0 or later
• NodaTime 3.2.2 or later
• System.Text.Json 9.0 or later

Development

Regenerating the Client

The client is auto-generated from the OpenAPI specification. To regenerate:

# Ensure the PropertyDashboard API is running on http://localhost:5000
cd scripts
./regenerate-client.sh

This script:

1. Downloads the latest OpenAPI spec from the running API
2. Generates the C# client using NSwag
3. Builds and validates the SDK

Prerequisites for Regeneration

# Restore .NET tools (includes NSwag)
dotnet tool restore

# Run the PropertyDashboard API
cd backend/PropertyDashboard/PropertyDashboard.WebApp
dotnet run

Version History

See Releases for detailed changelog.

Contributing

This is an auto-generated SDK. To contribute:

1. Submit changes to the PropertyDashboard API
2. Update the OpenAPI specification
3. Regenerate the client using the script above

License

MIT

Support

• Documentation: PropertyDashboard Docs
• Issues: GitHub Issues
• API Status: Ensure the PropertyDashboard API is running and accessible

Related Projects

• PropertyDashboard API - The main PropertyDashboard backend
• NodaTime - Better date and time API for .NET
• NSwag - OpenAPI toolchain for .NET