ForEach.Infrastructure.External.Octopus
0.1.0
dotnet add package ForEach.Infrastructure.External.Octopus --version 0.1.0
NuGet\Install-Package ForEach.Infrastructure.External.Octopus -Version 0.1.0
<PackageReference Include="ForEach.Infrastructure.External.Octopus" Version="0.1.0" />
<PackageVersion Include="ForEach.Infrastructure.External.Octopus" Version="0.1.0" />
<PackageReference Include="ForEach.Infrastructure.External.Octopus" />
paket add ForEach.Infrastructure.External.Octopus --version 0.1.0
#r "nuget: ForEach.Infrastructure.External.Octopus, 0.1.0"
#:package ForEach.Infrastructure.External.Octopus@0.1.0
#addin nuget:?package=ForEach.Infrastructure.External.Octopus&version=0.1.0
#tool nuget:?package=ForEach.Infrastructure.External.Octopus&version=0.1.0
ForEach.Infrastructure.External.Octopus
Typed clients for the four web services of Octopus (the Belgian accounting package by Inaras, not Octopus Deploy): the Rest, Management, file sync and file import APIs. The Refit interfaces are generated from the OpenAPI documents Octopus publishes; the package adds the token flow, the authentication handler, error parsing and DI registration. It is a plain client: it knows nothing about the application that uses it (no site or dossier mapping, no accounting logic).
// The token provider needs a TimeProvider (TimeProvider.System in production).
services.AddSingleton(TimeProvider.System);
services.AddOctopusClients(
options =>
{
options.IsEnabled = true;
options.SoftwareHouseUuid = "<issued by Octopus>";
options.User = "<web-service user>";
options.Password = "<secret>";
},
configureBuilder: (builder, clientName, isTokenClient) =>
builder.AddStandardResilienceHandler()); // optional: resilience per HttpClient
// ...
var bookyears = await restApi.GetBookyears(dossierId, cancellationToken);
Bind the options from configuration with options => configuration.GetSection("Octopus").Bind(options).
| Member | What it does |
|---|---|
AddOctopusClients |
Registers the validated OctopusOptions, the singleton IOctopusTokenProvider, and one Refit client per API (IOctopusRestApi, IOctopusManagementApi, IOctopusFileSyncApi, IOctopusFileImportApi), each behind OctopusAuthenticationHandler. configureBuilder is called once for the token client and once per API client so the host can add resilience. |
OctopusOptions |
Section Octopus: IsEnabled (default false), the four base URLs (default: the Inaras production hosts), SoftwareHouseUuid, User, Password, Locale, TokenLifetime, TokenExpiryBuffer. Validated on start: credentials are required when enabled and the URLs must be absolute http(s). |
IOctopusTokenProvider |
One authentication token per API and one dossier token per (API, dossier), cached and refreshed before expiry. |
OctopusAuthenticationHandler |
Attaches the right credential to every call by route (dossierToken for /dossiers/{id}/..., bearer token for the Management API, ...), re-acquires and resends once on a 401. A forward-only stream body is never resent. |
OctopusApiError |
Describe, Parse, IsNotFound, IsUnauthorized, IsForbidden, IsDisabled: turns Refit's ApiException into the reason Octopus gave, in either documented error-body shape. |
OctopusIntegrationDisabledException |
Thrown (wrapped by Refit) before any traffic while IsEnabled is false. |
Credentials are global to the client (one Software House ID and one web-service user); the dossier is a parameter of each call, so a host that serves several dossiers keeps that mapping itself.
Octopus enforces daily call caps per operation (for example 150 dossier tokens a day, 48 */modified
reads, 400 relation or booking writes); tokens are therefore acquired lazily and cached. Retry only
idempotent calls (GET, PUT, DELETE): a POST inserts a booking or, on the Management API, can cost money.
The three application/octet-stream uploads (UploadInvoiceAttachment, ImportSoda,
LoadDocumentByMailAddress) are hand-written with [Body] Stream (*.Streams.cs); Refitter emits
them as StreamPart, which Refit accepts only under [Multipart].
Regenerating the clients
src/ForEach.Infrastructure.External.Octopus/Codegen/ holds the OpenAPI documents (specs/, as
published, unmodified), one Refitter settings file per API (*.refitter) and the script:
pwsh packages/Octopus/src/ForEach.Infrastructure.External.Octopus/Codegen/Generate-OctopusClients.ps1 [-Download]
Refitter is pinned in packages/Octopus/.config/dotnet-tools.json (2.0.0, the version the committed
code was generated with; running the script with it reproduces Generated/ byte for byte). -Download
first refreshes the specs from https://service.inaras.be/<api>/v1/openapi.json; review that diff
before regenerating. The auth headers (Token, dossierToken, softwareHouseUuid) are left out of the
generated signatures (ignoredOperationHeaders) because the handler attaches them, so a spec that
adds a header parameter or a route also needs Auth/OctopusRequestAuthorization.cs updated.
Relation to ForEach.Connectors.Octopus
The old, unrelated ForEach.Connectors.Octopus (7.0.9) is superseded by this package. It is not
a predecessor of this code base and nothing here depends on it; new code should use
ForEach.Infrastructure.External.Octopus.
Targets net8.0 and net10.0. Dependencies: Refit, Refit.HttpClientFactory and
Microsoft.Extensions.Http.
Source and release notes: https://github.com/foreach-rs/nuget-releases/tree/main/packages/Octopus
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Http (>= 10.0.9)
- Refit (>= 13.1.0)
- Refit.HttpClientFactory (>= 13.1.0)
-
net8.0
- Microsoft.Extensions.Http (>= 10.0.9)
- Refit (>= 13.1.0)
- Refit.HttpClientFactory (>= 13.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0 | 55 | 11/19/2026 |