invoiceninja-sdk/GOALS.md

Goals

What this crate is trying to be, what it is deliberately not, and what is still open. The point of writing this down is that several decisions here look like oversights until you know the reasoning — this is where the reasoning lives.

What this is for

A complete, honest async Rust client for the Invoice Ninja v5 API.

Complete in that every endpoint the API exposes should eventually be reachable through it. Honest in that it should not quietly lose data, quietly truncate results, or quietly succeed when it did not.

Goals

1. Never lose data in a round trip

A get followed by an update must not drop fields the crate does not know about. Every model carries #[serde(flatten)] extra, and the modelled fields are a curated subset rather than an attempt at the whole schema.

This is why custom_value1..4, custom_surcharge1..4, and fields with ambiguous upstream types are intentionally unmodelled — extra carries them losslessly, whereas a wrong concrete type is a hard decode error that breaks the entire response.

2. Tolerate upstream inconsistency, fail on real problems

Invoice Ninja returns null for many nominally-string fields, and the same field name can differ in type across resources (frequency_id is a number on recurring invoices and a string on subscriptions; /statics returns payment_types.id as a string and every other table's as a number).

Decoding should absorb that — hence null_to_default and id_as_string — without becoming so permissive that genuine errors pass silently.

3. Prefer a loud failure to a quiet wrong answer

The bug worth remembering: list_all_* used to stop when a page came back shorter than requested, which the server's per_page cap made wrong, so it returned a partial list indistinguishable from a complete one. Silent truncation is the worst failure mode this crate can have.

Concretely: pagination terminates on the paginator's own total_pages, a runaway walk raises Error::PaginationLimit rather than returning what it has, and an id that cannot safely be a path segment is rejected instead of being mangled into a request against a different endpoint.

4. Be safe by default where the API handles money

POST is never replayed on a 5xx or a timeout, because the server may have applied it before the response was lost and a retry would create a second invoice, payment, or email. A 429 is retried for any method, because the server states it refused the request without processing it.

When a safety default and a convenience conflict here, safety wins, and the reasoning goes in a comment so it is not later optimised away.

5. Make failures diagnosable

An error should say enough to act on. Decode failures carry an excerpt of the body that actually arrived, because "expected value at line 1 column 1" does not reveal that a proxy returned an HTML error page. API errors keep the whole per-field errors map, not just the first message.

6. Verify against the source, not against assumptions

Field names and types come from Invoice Ninja's openapi/api-docs.yaml; the set of endpoints comes from routes/api.php and the controllers, because the published spec is incomplete for routes. Claims in COVERAGE.md are checked against the upstream repository rather than inferred.

7. Stay testable without credentials

The whole suite runs offline: model decoding against fixtures, request plumbing against a wiremock server on loopback. Nobody should need an Invoice Ninja account to contribute.

Non-goals

• Not a port of the official PHP SDK. It is a useful cross-check, but thinner, and two of its behaviours are bugs not to copy. See the comparison in COVERAGE.md. The divergences — JSON instead of form_params, keeping the whole validation errors map, exposing bulk download only on PDF-rendering entities — are deliberate.
• No sync/blocking API. Async only.
• No ORM, session, or caching layer. The crate wraps endpoints. It does not model relationships between entities or cache responses, beyond advising that /statics is worth caching.
• No modelling of every field. See goal 1; breadth of endpoints is a goal, breadth of typed fields is not.
• No retrying of non-idempotent requests. See goal 4.
• No API stability before 1.0. See below.

Publication and compatibility

Published on crates.io so it is installable, with no stability promise before 1.0. Pin an exact version; expect breaking changes in minor releases. CHANGELOG.md records them, and breaking changes should be legible there rather than discovered at compile time.

Error is #[non_exhaustive] so that adding variants is not itself a breaking change.

MSRV is 1.88, set by the dependency graph rather than by this crate's code. It may rise when dependencies require it; that is a changelog entry, not a blocker. It should never rise because a convenience API was used without checking — see the note in CLAUDE.md.

Roadmap: closing the coverage gaps

All 34 Route::resource groups are wrapped. Full coverage is the target, so COVERAGE.md's gap list is a to-do list, not a permanent boundary. Roughly in order of value over effort:

1. Multipart uploads — 16 PUT /{resource}/{id}/upload routes plus edocument/upload. Blocked only on enabling reqwest's multipart feature. This is also what makes create_document possible, so it unblocks the one obviously missing piece of an otherwise complete resource.
2. Per-resource extras — mechanical, and they reuse existing patterns: webhooks/{id}/retry, tasks/sort, designs/set/default, client_gateway_tokens/{id}/setAsDefault, subscriptions/steps, the client extras (updateTaxData, show_settings, check_vat, …), the bank-integration and company-gateway extras.
3. Password-protected actions — with_api_password already makes these reachable; only the methods are missing. Client purge and merge, vendor merge, company purge, user invite and purge.
4. Preview, activities, and email history — distinct response shapes, so each needs its own hand-written method and probably its own model.
5. Public invitation-key downloads — eight routes that take no auth token, so they do not fit the authenticated request path and need a different entry point.
6. Import/export and the integrations — Stripe, QuickBooks, einvoice (17 routes), Yodlee, Nordigen, calendar. The largest block and the least SDK-shaped; worth doing last and possibly in pieces.

Keep COVERAGE.md current as these land — it names exact counts, so it goes stale quietly.

Open questions

These are genuinely undecided. Deciding one is a change to this file.

• Auth routes (/login, /logout, /refresh, passkeys) are in the gap list, but they are a different authentication model from the API token this client is built around. Including them may mean a second client type rather than more methods on this one. Not obviously in scope.
• chart is still generic over T: DeserializeOwned, because the eleven chart endpoints share no response shape. Per-chart structs would be eleven small models of unstable payloads; unclear whether that earns its keep.
• Large responses are buffered entirely into memory. PDF downloads and CSV report exports go through Vec<u8>. Streaming would be better for big exports but changes those signatures.
• Error::PaginationLimit has no test, because reaching it needs 10,001 mock round trips. Making MAX_PAGES injectable purely for a test may be worse than the gap.
• When to go 1.0, and what the API needs to settle first.