External Integrations

Requirement Application MUST own a public external-service interface named for its business action.

Rationale A business port states the behavior that a use case needs without naming its provider.

Example IPaymentAuthorizer describes the business action without exposing a payment-provider client.

Requirement Infrastructure MUST own provider clients, SDKs, authentication, and transport models.

Rationale Provider-specific names and contracts remain outside Application's business boundary.

Example IStripeClient is provider infrastructure rather than an Application port.

Requirement An external client MUST bind its base address, credentials, timeout, and policy through validated options.

Rationale Validated options make provider configuration explicit at startup.

Requirement An HTTP integration MUST use HttpClientFactory and applicable service discovery.

Rationale Managed client construction centralizes handler lifetime and service resolution.

Requirement An HTTP integration MUST NOT construct a new HTTP client for each request.

Rationale Per-request clients lose central handler configuration and can exhaust network resources.

Requirement An external client MUST retry transient failures with bounded attempts and jitter.

Rationale Bounded jittered retries reduce synchronized retry load on an unavailable provider.

Requirement An external client MUST NOT retry a non-idempotent provider call without provider idempotency and documented replay behavior.

Rationale Repeated provider calls can duplicate irreversible external effects.

Requirement An integration MUST map provider errors to project-owned outcomes and stable diagnostics.

Rationale Project-owned outcomes remain stable when provider responses or SDK types change.

The project's own error catalog holds the stable codes. litespec/backend/api#return-stable-problem-details returns a code from that catalog. An integration that invents one code per provider creates one code space per provider. A client that branches on failure learns every code space. A provider's own error taxonomy is the input to the mapping, not its output.

Example A declined card and a declined direct debit both map to the project's payment-refused code. The provider's own code travels in diagnostics.

Requirement An API MUST NOT expose provider bodies, credentials, headers, exception types, or internal account identifiers.

Rationale Provider internals can disclose secrets, implementation details, or another account's data.

Requirement An inbound provider handler MUST verify signature, timestamp tolerance, replay protection, content type, size, schema, and event identity before processing.

Rationale Each check protects a different part of the trust boundary for a provider message.

Order matters here. Verify the signature first, over the raw body, before parsing the body or running any other check. An unauthenticated caller can reach a parser that runs first. A deserialized body is no longer the bytes that the signature covered. Stripe's signature guidance states the same requirement.

Example A failed signature returns 401 with no body. A message that names the failed check tells an unauthenticated caller how to pass it.

Requirement An inbound provider handler MUST store or process duplicate events idempotently.

Rationale Provider delivery can repeat one event after a timeout or acknowledgement failure.

Requirement A CSV or spreadsheet import MUST reject or neutralize a value that begins with a formula-leading character.

Rationale The formula-leading characters are the equals sign, the plus sign, the minus sign, the at sign, the tab, and the carriage return. Escaping when you export protects the reader of that export. It does not protect the reader of the next export. A different report can re-export an unchanged imported value without escaping it. CSV injection travels through the store, so the boundary that admits the value is where it stops.

Example An import that rejects the value reports the row and the field. An import that neutralizes it records what it changed. A silently altered value is a data defect the owner cannot see.

Requirement An integration test MUST use WireMock.Net or a protocol-specific local endpoint.

Rationale A controllable endpoint exercises the network contract without a live provider account.

Requirement An integration test MUST cover timeout, connection failure, transient response, permanent response, malformed payload, rate limit, duplicate delivery, and unexpected response shape.

Rationale Each failure mode can affect retry, mapping, or idempotency behavior.

An unexpected response shape is the mode a provider produces without failing. A well-formed response can carry a field that moved, a type that changed, or a value no one planned for. The response parses. The behavior is still wrong. Every other listed mode reports that response as an error. A provider that versions its API changes shape on a schedule. A pinned version still changes on the day the provider raises it.