Changelog¶
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.
This package's version follows the pain001
suite; the first release will be 0.0.88, in lockstep with it.
[0.0.88] - 2026-11-14¶
Changed¶
- CI tests against pain001 0.0.88, the release this SDK ships with
(
ci/server-requirements.in). -
The CI and CodeQL workflows run in concurrency groups: a new push to a pull request cancels the superseded run.
-
dotnet packalso writes a symbols package (.snupkg) and runs .NET package validation, which uses ApiCompat.scripts/api-compat.sh(the CI Linux build job) adds the last publishedPain001.Sdkas the baseline, so a breaking API change fails; until the first release is published it says there is no baseline and checks the package alone. -
The package version is 0.0.88, the suite version this first release ships with (
Pain001.Sdk.csproj,CITATION.cff, theSECURITY.mdtable, the README install snippet and the bug report form). -
The vendored conformance kit is kit 2, byte-identical to core's (pinned by
conformance/SHA256SUMS): new casesgenerate-refused-rows,generate-refused-scheme,validate-bad-leiandvalidate-chaps-purpose-required, and their fixtures. The CI conformance job runs it against the latest released core,pain001 serve0.0.87, re-locked with hashes inci/server-requirements.txt. -
The README shows a demo,
.github/demo.gif, rendered bymake demofrom.github/demo.tape: the Basic example against a realpain001 serveon loopback.examples/Basicnow also prints the server's health and the validation row counts before it generates. -
Tests run on xunit.runner.visualstudio 4.0.1 (was 3.1.5) and Microsoft.NET.Test.Sdk 18.12.0 (was 18.11.0); lock file updated.
- The CI vulnerable-package job restores with
--locked-mode, as every other restore in CI already does throughRestoreLockedMode.
Added¶
-
The user manual: MkDocs Material from
docs/, built in strict mode by the docs workflow and deployed to GitHub Pages frommain, with the API reference rendered from the XML documentation comments (scripts/api-docs.sh,scripts/api_docs.py). New pages: getting started, examples, architecture, five ADRs, the ecosystem comparison, benchmarks, packaging, policies and the roadmap; the rootDEVELOPMENT.md,CONTRIBUTING.md,GOVERNANCE.md,SECURITY.md,SUPPORT.mdand this changelog are included into it.DEVELOPMENT.mdmaps every CI gate to its local command and lists the settings a release needs. The README follows the portfolio template in full. -
make regression(scripts/regression.sh): installs the pinned server into a temporary virtual environment unlessPAIN001_SERVERis set, starts it and a second one with an API key on free loopback ports, runsmake check, the conformance kit, every example and the benchmark smoke run, and stops both servers on exit, failure included. -
.devcontainer/(the .NET 10 dev container image pinned by digest, with Python and Node) that restores and builds on creation, and a.pre-commit-config.yamlmirroring the cheap CI gates. -
A release workflow (
.github/workflows/release.yml): on a signed tagv<version>it checks the tag againstKEYS.ascand every version reference, builds and tests, packs, writes a CycloneDX SBOM andSHA256SUMS, attests build provenance, creates the GitHub release titledpain001-sdk-dotnet <version>with notes in the suite's shape (scripts/release-notes.sh, highlights from.github/release-highlights.md), checks it, and publishes to NuGet by trusted publishing. Run by hand it is a dry run that skips the last three steps; every step is safe to re-run. -
REUSE compliance:
LICENSES/holds the Apache-2.0 and MIT texts (as inLICENSE-APACHEandLICENSE-MIT), andREUSE.tomlcovers the files that cannot carry a header. The docs-lint workflow (andmake docs-lint) runsreuse lintand codespell beside markdownlint, from hash-pinnedci/lint-requirements.txt. -
BenchmarkDotNet benchmarks (
benchmarks/Pain001.Sdk.Benchmarks, BenchmarkDotNet 0.15.8): the client-side cost of every typed method andRequestAsyncwith the kit's fixtures and recorded server answers, no network; and one loopback round trip per method topain001 servewhenPAIN001_BASE_URLis set.make benchruns them;make bench-smoke(one iteration each) runs in the CI conformance job. Lock file added. -
The complexity ceilings of the portfolio standard, enforced on every method by the build and CI: cyclomatic complexity 10 (CA1502, as before), cognitive complexity 15, 60 lines per method and 500 per file (SonarAnalyzer.CSharp 10.35.0.4138, a build-time analyser with only S3776, S138 and S104 switched on; thresholds in
SonarLint.xml), and Halstead difficulty 30 (scripts/halstead.py,make halstead, the CI Complexity job). No method is over a ceiling. Lock files updated. -
One runnable example per public method in
examples/:Health,Validate,Generate,Check,Faces,ProjectFace,RawRequest,ErrorHandling(refusal, API error and no-document, in catch order),Timeouts(timeout, cancellation andRetryPolicy) andApiKey, besideBasic. Each checks its own result.scripts/run-examples.sh(make examples) runs them all; the CI conformance job runs it againstpain001 serve, plusApiKeyagainst a second server started withPAIN001_API_KEY. -
A coverage gate:
make coverage(part ofmake check) and the CI unit-test job run the tests under coverlet (coverlet.msbuild10.1.0, test-only) and fail below 100 % line and branch coverage of the library. Lock file updated. -
RetryPolicy, an opt-in retry policy set onPain001ClientOptions.Retry(default none, so behaviour is unchanged). It resendsGETcalls only (HealthAsync,FacesAsync,RequestAsyncwithGET) on HTTP 429 or 503 and on connection errors, up toMaxAttempts(3), with exponential backoff and jitter fromInitialDelay(200 ms) capped atMaxDelay(5 s). ARetry-Afterheader replaces the backoff, and one asking for more thanMaxDelayends the retries. APOSTis never retried.Pain001ClientOptions.TimeProvidersets the clock it waits on. -
Pain001GenerationRefusedException, aPain001ApiExceptionsubclass thatGenerateAsyncraises when the server refuses the data (HTTP 422 withsuccess: false, pain001 0.0.87 and later). ItsResponseholds the decoded body, with the blockingValidationErrorsandSchemeViolations; its message gives the status and the count of each, never the findings. A 422 for a malformed request stays a plainPain001ApiException. This matches the Go SDK'sRefusalErrorand the Java SDK'sGenerationRefusedException.Pain001ApiExceptionis no longer sealed, so acatch (Pain001ApiException)still catches a refusal. -
Target
net10.0only. .NET 8 and .NET 9 reached end of support on 10 November 2026; .NET 10 is the supported LTS release (to November 2028). Pain001Client, a typed async client for the pain001 REST API:HealthAsync,ValidateAsync,GenerateAsync,CheckAsync,FacesAsync,ProjectFaceAsyncand the low-levelRequestAsync, withCancellationTokenon every call, an optional bearer API key and a per-request timeout. No third-party runtime dependency.Pain001ApiException, carrying the HTTP status and the server'sdetail; its message never includes the detail, which can echo payment data.- Response records with snake_case JSON mapping (row errors as
pain001's
RowError{field, message, value}; HTTP 422 items as FastAPI'sValidationError), andMessageTypesconstants for the 13 message types the server lists. - The conformance kit, vendored from core and pinned by
conformance/SHA256SUMS, with a runner that ports core's reference runner, typed tests for every method, and unit tests against an in-memory handler. - CI: format, build and unit tests on Linux, Windows and macOS, a
vulnerable-package audit, and a conformance job against a
hash-pinned
pain001 serve. - An example console project,
examples/Basic, that generates a pain.001.001.09 file from the kit's credit-transfer fixture. - Community baseline: README, SECURITY, CONTRIBUTING, CODE_OF_CONDUCT, AGENTS, CITATION, DCO, issue forms, a pull request template, and DCO and markdownlint workflows.
- FsCheck property tests over what the server sends back
(
ResponsePropertyTests): any status, bytes and media type through every typed method andRequestAsync, error details that must stay out of the exception message, and well-formed answers that must decode to what was sent. 500 cases per property, in the existing unit test job. Test-only packages FsCheck and FsCheck.Xunit 3.6.0; lock file updated.
Fixed¶
-
GenerateAsyncno longer returns a result without a document. A 2xx answer whosesuccessis not true, or whosexmlis missing or empty, now raisesPain001NoDocumentException(with the status and the decodedResponse), as Go returnsErrNoDocument, C++ throwsNoDocumentand Rust returnsError::Decode. A returnedUiGenerateResponsetherefore always carries the XML. -
A response body that is not valid UTF-8 is kept as text, each invalid byte replaced by U+FFFD, as the documentation already promised for a body that is not JSON. Before,
Pain001ApiException.DetailandPain001RawResponse.Bodyheld an element that threwInvalidOperationExceptionwhen read, so an error handler callingDetail.GetString()on a Latin-1 proxy page threw again.