MvService.Cbm.ExternalClient 1.0.0

MvService.Cbm.ExternalClient

.NET client library for the Contract Billing Management (CBM) External API v1.

Covers:

• Contracts (read + line-item write)
• On-demand billing items (generic + typed time/material/usage ingress)
• Asset bulk-import
• ERP order event ingestion
• Customer management (create, read, update, lookup by external ref)
• Subscription lifecycle (trial, plan change, cancellation, status)

Installation

<PackageReference Include="MvService.Cbm.ExternalClient" Version="1.*" />

Add the GitHub Packages source to your nuget.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="github-mv-service"
         value="https://nuget.pkg.github.com/MV-Service/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <github-mv-service>
      <add key="Username" value="%GITHUB_USERNAME%" />
      <add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
    </github-mv-service>
  </packageSourceCredentials>
</configuration>

GITHUB_TOKEN needs read:packages scope (classic PAT or fine-grained with read access to the MV-Service org packages).

Quickstart

X-Api-Key authentication (default)

builder.Services
    .AddCbmExternalClient(o =>
    {
        o.BaseUrl = "https://cbm.example.com";
        o.ApiKey  = "your-api-key";
    })
    .AddStandardResilienceHandler(); // optional — requires Microsoft.Extensions.Http.Resilience

OAuth 2.0 client_credentials flow

builder.Services
    .AddCbmExternalClient(o =>
    {
        o.BaseUrl      = "https://cbm.example.com";
        o.UseOAuthFlow = true;
        o.ClientId     = "your-marketplace-app-id";
        o.ClientSecret = "your-client-secret";
        o.Scope        = "contracts:read billing:write assets:write";
    });

Tokens are cached and refreshed automatically (30-second buffer before expiry).

Basic usage

public class MyService(ICbmExternalClient cbm)
{
    public async Task RunAsync(CancellationToken ct)
    {
        // List active contracts
        var page = await cbm.ListContractsAsync(
            status: CbmContractStatus.Active, ct: ct);

        foreach (var contract in page.Items)
            Console.WriteLine($"{contract.ContractNumber} — {contract.CustomerName}");

        // Submit a time entry
        var entry = await cbm.SubmitTimeEntryAsync(new CbmTimeEntryRequest
        {
            CustomerExternalRef = "CUST-001",
            Hours               = 2.5m,
            OccurredAt          = DateTime.UtcNow,
            Description         = "Maintenance work",
        }, ct);

        Console.WriteLine($"Recorded: {entry.Id}");

        // Bulk-import assets
        var result = await cbm.ImportAssetsAsync(new CbmBulkImportRequest
        {
            ThirdPartyAppId = Guid.Parse("..."),
            Assets =
            [
                new CbmBulkImportAssetItem
                {
                    ExternalAssetId    = "SRV-001",
                    Name               = "Web Server 01",
                    AssetType          = "Server",
                    ExternalReferenceUrl = "https://idoit.example.com/cmdb/1234",
                },
            ],
        }, ct);

        Console.WriteLine($"Imported: {result.Created} created, {result.Updated} updated");
    }
}

API Reference

Webhook Event Types

Use the CbmWebhookEventTypes constants class when registering webhook subscriptions:

await cbm.RegisterWebhookAsync(new CbmCreateWebhookRequest
{
    Url = "https://my-app.example.com/webhooks/cbm",
    EventTypes =
    [
        CbmWebhookEventTypes.CustomerCreated,
        CbmWebhookEventTypes.SubscriptionTrialStarted,
        CbmWebhookEventTypes.SubscriptionUpgraded,
        CbmWebhookEventTypes.SubscriptionCancelled,
    ],
});

Available event types:

Error handling

All HTTP errors surface as typed exceptions:

All exceptions expose StatusCode and ResponseBody for diagnostics.

Resilience

AddCbmExternalClient returns an IHttpClientBuilder. Chain .AddStandardResilienceHandler() (from Microsoft.Extensions.Http.Resilience) or any Polly pipeline you need:

builder.Services
    .AddCbmExternalClient(o => { ... })
    .AddResilienceHandler("cbm", pipeline =>
    {
        pipeline.AddRetry(new HttpRetryStrategyOptions { MaxRetryAttempts = 3 });
        pipeline.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions());
    });

License

UNLICENSED — internal MV-Service component.