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 CLI, and no binary at all, in this package.** A command-line client
  over this library is a reasonable thing to want — it is the obvious way to
  ask "what does this endpoint actually return", which matters here because
  the e-invoicing and integration methods are typed as
  `serde_json::Value` and were verified against mocks rather than a live
  service. It belongs in a sibling crate (`invoiceninja-sdk-cli`) in a
  workspace, not in this one, for three reasons:

  - *Dependencies.* Every entry in `Cargo.toml` is there because the library
    needs it, and three of the five are already in the tree via `reqwest`.
    An argument parser would be the first dependency that is not
    load-bearing for the library, along with the project's first optional
    dependency and first `[features]` section.
  - *MSRV.* Not a break today — `clap` 4.6.7 declares 1.85, under this
    crate's 1.88 (checked 2026-10-25). The cost is the coupling: a second
    floor that moves on someone else's release schedule, in a project where
    three places must agree on the number and a documented procedure exists
    for rechecking it. A separate crate keeps it out of the library's graph.
  - *Versioning.* Pre-1.0 this crate tells callers to pin an exact version
    and expect breaking changes in minor releases. A CLI's flags are a
    compatibility surface too, and one version number would force the two to
    move in lockstep. `cargo install invoiceninja-sdk` silently needing
    `--features cli` is a smaller version of the same problem.

  For ad-hoc probing, `examples/` already covers it and costs nothing:
  `capture_shapes`, `seed_sample_data` and `smoke_test` are CLI-shaped
  programs configured from environment variables, with the
  `IN_SMOKE_WRITE_HOST` guard to copy for anything that writes.

  Same shape of decision as the `updated_at` sync engine in the open
  questions: a different product from this crate, recorded so the option is
  not forgotten.
- **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.

**Gitea is the source of truth; GitHub is a one-way mirror.** The canonical
repository is `gitea.awkawb.cloud/awkawb/invoiceninja-sdk`. A Gitea push mirror
copies every commit to <https://github.com/awkawb1/invoiceninja-sdk>, which
is what `Cargo.toml` points at. Nothing should be written to the GitHub
copy: the next sync overwrites it, so a merged pull request there would
simply disappear. Contributions go through Gitea.

`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

**This roadmap is now closed** — every item below is done, and every route an
API-token client can reach is wrapped. It is kept rather than deleted because
several entries record what an item's original reasoning got wrong, which is
worth more than the fact that it shipped. What is still unwrapped is in
`COVERAGE.md`'s gap list, with a reason per entry, and none of it is a
sequenced to-do any more.

The items ran roughly in order of value over effort:

**Done:** multipart document uploads, for the 16 resources that have the
route (`upload_client`, `upload_invoice`, …). This earlier claimed it would
also make `create_document` possible, which was wrong: upstream
`DocumentController::store` is an empty stub, and an upload is the *only*
way a document is created. There is no `create_document` and there will not
be one. `edocument/upload` was left out because it imports an expense from
an e-document rather than attaching a file, so it belongs with item 6.

**Done:** the per-resource extras — webhook retry, task sort, default
design, default gateway token, subscription steps, and the client,
bank-integration, and company-gateway routes (19 methods). The numbering
below keeps its original item numbers. Running the smoke test against a real
server overturned one reading of the source here: `/subscriptions/steps`
answers with an object keyed by class name, not the array the controller
suggests. That is the case for keeping the real-server tier.

**Done:** the password-protected actions — client purge and merge, vendor
merge, company purge, user invite and purge, and the blank-user template (8
methods). The smoke test's password tier (`IN_API_PASSWORD`) has since been
run against a disposable 5.13.50 instance, on 2026-10-24, with all four
checks passing — but only after its own post-purge assertion was fixed, which
had checked for a 404 and passed solely because it had never been run. The
claim here that `with_api_password` already made them reachable was not quite
true: a password with a control character was refused locally.

**Done:** activities, email history and previews (14 methods, two new
models). The email history stays raw JSON, since no instance here had sent
mail to take a shape from; promoting it to a model needs a sample. Several
previews are unverified against a real server (see `COVERAGE.md`).

**Done:** the invitation-key downloads — the PDF and the XML e-document for
invoices, quotes, credits and purchase orders, keyed by a contact's
invitation key (8 methods). This item used to read "eight routes that take no
auth token, so they do not fit the authenticated request path and need a
different entry point." That was wrong on every count, and wrong in the way
goal 6 exists to catch: the premise came from reading the route *names*
rather than the route file. All eight sit inside `routes/api.php`'s `api/v1`
group under its `token_auth` middleware — the controllers' own OpenAPI blocks
declare `X-API-TOKEN` — so they needed no new entry point and were two dozen
lines of macro. What the item had actually described is the client-portal
family in `routes/client.php`, which is genuinely token-less, is not under
`/api/v1`, and stays unwrapped for that reason.

**Done:** import/export and the integrations — `/import`, `/preimport`,
`/import_json`, `/export`, `edocument/upload`, einvoice (17 routes),
QuickBooks, Stripe, calendar, Yodlee and Nordigen (38 methods). This was the
last item, so **the roadmap is closed**: every route in `routes/api.php` that
an API-token client can reach is now wrapped. It did land in pieces, as the
item predicted — import/export first, then the integrations.

**Done:** the auth routes, once split apart — the single "auth routes"
label had quietly merged four unrelated things. `logout` and the passkey
list/delete routes sit behind the same `token_auth` middleware as every
other wrapped endpoint, so they needed no new client type, just methods
(and a documented warning that `logout` rotates every token on the whole
company, not just the caller's). `login` *does* need a different entry
point — there is no token yet to build an `InvoiceNinjaClient` with — but
that turned out to be a standalone associated function, not a second
client type: `InvoiceNinjaClient::login` trades an email and password for
a `LoginResponse` carrying a token, which then goes to `new` or `hosted`
as normal. Passkey *registration* and passkey *login* stay unwrapped
because they're WebAuthn ceremonies a browser has to drive; `/refresh` and
`/refresh_react` turned out to be the bulk `updated_at` sync dump already
parked below, not an auth concept, so they stay out for that reason
instead; and `/connected_account` (Gmail OAuth linking) was filed under
the wrong heading — it belongs with the Integrations done item above. See
`COVERAGE.md`'s "Logout, passkeys, and login" section for the detail.

As the item also predicted, it is the least SDK-shaped part of the API, and
the typing reflects that: most of these return `serde_json::Value`, because
their replies are pass-throughs from Storecove, Stripe, Yodlee or GoCardless,
or arrays assembled for Invoice Ninja's React client. That is a deliberate
application of the rule in goal 2 — a wrong concrete type is a hard decode
error, where `Value` is lossless — and not a shortcut to revisit without a
reason. `COVERAGE.md` records it as the crate's largest untyped surface.

Two things in this block are *not* wrapped, and cannot be. The OAuth legs of
the QuickBooks and calendar flows take no API token and answer with browser
redirects, so connecting an account stays a browser flow; the methods here
operate a connection that already exists. And `POST /quickbooks/settings` is
a registered route with no controller method behind it, so it 500s — there is
nothing to wrap until upstream adds the handler.

What remains unwrapped is now only what each entry in `COVERAGE.md`'s gap
list explains: the passkey and SSO ceremonies and `/login/precheck`
(each needs something — a browser, a redirect — this client doesn't have),
`/refresh`/`/refresh_react` (the sync-engine shape parked below), the
client-portal family, the provider webhooks, and a few company and user
extras. Keep that file current — it names exact counts, so it goes stale
quietly.

**Decided: `chart` stays generic.** The premise in the old open question —
"eleven chart endpoints share no response shape" — undersold the problem.
Reading `ChartController`/`ChartService` directly: the eleven routes are
nine distinct bodies (`totals`/`totalsV2` and `chart_summary`/
`chart_summaryV2` are pairs of the same implementation), and six of those
nine *do* share an outer idiom — an object keyed by a company's own
currency ids, plus a sentinel `999` key for the cross-currency aggregate.
But the leaf rows inside that shape are raw `DB::select` results with no
model behind them, and they don't agree with each other: within `totals()`
alone, the `invoices` leaf carries `invoiced_amount`, `revenue` carries
`paid_to_date`, `outstanding` carries `amount` *and* `outstanding_count`,
and `chart_summary`'s four leaves differ again. That is goal 2's
"ambiguous upstream type" problem — compounded by `SUM()` often coming
back from the DB driver as a numeric string — repeated dozens of times
over. The remaining three bodies (`cashflow_forecast`,
`client_payment_analytics`, `project_analytics`/`project_burnup`) delegate
to standalone service classes with no shape in common with each other or
with the currency-keyed family, and `calculated_fields` returns whichever
scalar or array type its ~20-way `field` match picks, so there is no fixed
shape to type at all. Modeling the shared outer envelope would still leave
dozens of hand-maintained, DB-column-shaped leaf structs for marginal
benefit over a caller defining their own `T` for the one endpoint they
use — which `chart::<T>` already lets them do.

## Open questions

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

- **Large bodies are buffered entirely into memory.** PDF downloads and CSV
  report exports come back as `Vec<u8>`, and an uploaded `FileUpload` holds
  its whole contents until the request finishes. Streaming would be better
  for big files in both directions but changes those signatures — and for
  uploads it would also change the retry story, which currently depends on
  the multipart body being un-cloneable.
- **`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.