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 identity map, lazy relationship loading, or transparent entity caching. Three separate refusals with one theme — the client stays stateless and the models stay plain data:

  • Lazy loading. An Invoice that could fetch its own client would have to hold a client handle, so it would stop being a Deserialize struct. That breaks Default-constructibility, which every create_* relies on, and it breaks the extra round-trip model.
  • Dirty tracking. The same problem from the other side: you cannot meaningfully diff a flattened Map of fields the crate does not model, and carrying those fields is the whole point of extra (goal 1).
  • Entity caching. The shared response path in BaseController sends no ETag, If-None-Match, or Cache-Control, so a cached entity cannot be cheaply revalidated — every hit is a gamble. Serving a stale invoice balance is a correctness hazard, not a missed optimisation.

  An identity map would also mean shared mutable state; InvoiceNinjaClient is currently cheap to Clone across tasks, and a lock would change that. Server-side eager loading via include already covers the common case in one round trip.

  Note this does not rule out typed include helpers or an opt-in cache for the static lookup tables — see the open questions.

• 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.

• Typed include helpers. Eager loading is a stringly parameter today (.include("client,payments")), so a typo is a silent no-op rather than a compile error. An enum-backed builder per resource would fix that, and it conflicts with nothing above — it is just not done. The cost is knowing which relationships each resource actually accepts, which the spec does not reliably document.

• An opt-in cache for /statics. The payload is large and near-constant and the docs already say to cache it, but the crate offers no hook. A small trait the caller implements would stay clear of the entity-caching hazard above, since the lookup tables are not money. Whether that beats "cache it yourself" is genuinely unclear.

  Related, and deliberately parked: the API accepts an updated_at query parameter meaning "everything changed since T", which is the shape a local mirror would need. That is a sync engine rather than a cache, and a different product from this crate — recorded so the option is not forgotten rather than because it is planned.

• When to go 1.0, and what the API needs to settle first.