invoiceninja-sdk/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An async Rust client for the Invoice Ninja v5 API.

GOALS.md states what the project is for, what it deliberately is not, and what is still undecided. Read it before making a design call — several choices in here look like oversights until you know the reasoning (the curated model subset, the untyped chart, not retrying POST, the divergences from the official PHP SDK). If a change would contradict a stated goal or settle an open question, update GOALS.md in the same change.

Development environment

This project uses Nix for toolchain management (Rust via rust-overlay):

nix develop

Rust version

Two versions are pinned, and three places must agree when either moves:

	Version	Declared in
Dev toolchain	1.99.1	devVersion in flake.nix, test job in ci.yml
MSRV	1.88	msrvVersion in flake.nix, rust-version in Cargo.toml, msrv job in ci.yml

CI has a third job, stable, which tracks latest stable and runs weekly (Mondays, via schedule) as well as on push and PR. It exists so a new Rust release that breaks the build or fires a new clippy lint shows up before the pin moves. Check it when bumping devVersion — if it is red, the bump needs work first. Nothing needs to stay in sync with it.

It is advisory, but it reports red. There is deliberately no continue-on-error, because a green check with an annotation is a signal nobody reads. That means it must stay out of the required status checks in branch protection — that repo setting, not anything in ci.yml, is what keeps it from blocking merges. Expect it red occasionally through no fault of the change under test; that is the tradeoff for it being visible.

The pinned test and msrv jobs skip scheduled runs (if: github.event_name != 'schedule'), since a pinned toolchain against a locked dependency graph cannot change on a timer.

The MSRV is set by the dependency graph, not by this crate's code: reqwest pulls in url → idna → idna_adapter → icu_*, and the icu crates require 1.88. Recheck the floor after a dependency bump with:

cargo metadata --format-version 1 \
  | jq -r '.packages[] | select(.rust_version) | "\(.rust_version)\t\(.name)"' \
  | sort -V | tail -5

Verify a candidate MSRV actually builds before declaring it — the number above was confirmed by running the suite, not inferred:

CARGO_TARGET_DIR=/tmp/msrv-target nix develop .#msrv --command cargo test

Don't reach for a newer std API without checking it against the MSRV; a convenience like Option::is_none_or (1.82) is rarely worth raising the floor for.

Common commands

cargo build
cargo test
cargo test <test_name>       # run a single test
cargo check
cargo clippy
cargo fmt

# Run the example (requires IN_API_TOKEN, optionally IN_BASE_URL)
IN_API_TOKEN=... cargo run --example list_clients

Tests live in tests/ (integration-style, no network access required); src/ has no #[test] modules. Four files:

• model_roundtrip.rs — the serde layer, from hand-written payloads.
• client_requests.rs — the request plumbing (pagination, path escaping, headers, timeouts, retry, error mapping, one test per endpoint extra) against a wiremock server on loopback.
• decode_tolerance.rs — for every model, serialises Default, then nulls and removes each field in turn and requires the result to still decode. A new model belongs in its list; a new non-Option field without null_to_default fails it.
• real_shapes.rs — decodes tests/fixtures/*.json, which are the shapes (keys and JSON types, no values) of responses captured from a real server, and checks a decode + re-serialise loses no key. It also refuses fixtures that hold any real value, and fixtures with no test.

No credentials or internet needed for any of them.

Why the fixtures matter: twice, mocks written from the upstream source passed while a real server disagreed (system-log timestamps; the /subscriptions/steps shape), and frequency_id and several empty-string fields were wrong the same way. When the smoke test finds a divergence, refresh the fixtures so it stays caught:

# 1. Fill a DISPOSABLE instance with one row of each kind (writes!).
IN_SMOKE_WRITE_HOST=localhost IN_BASE_URL=... IN_API_TOKEN=... \
  cargo run --example seed_sample_data
# 2. Capture shapes (GET only). Review `git diff tests/fixtures` before committing.
IN_BASE_URL=... IN_API_TOKEN=... cargo run --example capture_shapes

A resource with no rows is skipped, so the fixture set only covers what the instance held. Bank integrations, company gateways, client gateway tokens, subscriptions, task schedulers, and recurring quotes are not captured: they need external accounts, or (recurring quotes on 5.13.50) the server's own insert fails.

Fields omitted when empty. The server runs ConvertEmptyStringsToNull, so an unset String serialised as "" becomes NULL, which a non-null column or an integer rule then rejects. Location.country_id, PurchaseOrder.status_id and Webhook.format therefore carry skip_serializing_if = "String::is_empty". If a create from a Default model 500s or 422s on an empty field, do the same — and add the path to OMITTED_WHEN_EMPTY in tests/real_shapes.rs and examples/smoke_test.rs, which is deliberately a list of decisions rather than a blanket exemption.

Testing against a real server

Everything above is checked against mock servers written from the upstream source, so it cannot catch a place where the real server disagrees with that reading. examples/smoke_test.rs can:

# Read-only (GET requests only). IN_BASE_URL has no default, on purpose.
IN_BASE_URL=http://localhost:8080/api/v1 IN_API_TOKEN=... \
  cargo run --example smoke_test

# Adds a write tier: create a throwaway client, upload files to it, delete it.
IN_SMOKE_WRITE_HOST=localhost IN_BASE_URL=... IN_API_TOKEN=... \
  cargo run --example smoke_test

Never point the write tier at a production server. The guard is that IN_SMOKE_WRITE_HOST must equal the host in IN_BASE_URL, so a write only reaches a server that was named explicitly. Even after its delete the write tier leaves a gap in the client number sequence and a soft-deleted row (a real purge needs the account password), and it may fire webhooks. Use a disposable instance — a local VM or container — for it.

Beyond "does it decode", the read tier fetches the same rows raw and fails if a typed row lost a key (keys kept: <resource>, names only, never values), and the write tier creates a purchase order, location, webhook and recurring invoice from bare Default models, since those are what broke. The read tier also downloads an invoice by invitation key, which is there to re-check the claim that those routes are token-authenticated; the matching download_e_* is left out, since it renders from e-invoice settings a test instance need not have. With IN_API_PASSWORD set as well, a password tier merges two throwaway clients and purges the survivor (a real, permanent delete); it was run against a disposable 5.13.50 instance on 2026-10-24 and all four checks pass. .github/workflows/smoke.yml runs it on demand (workflow_dispatch only, needing IN_BASE_URL and IN_API_TOKEN secrets); the write tier runs only if the write_host input names the instance's host.

It prints PASS/FAIL per check and never the contents of a record. The upload wire format (POST plus _method=PUT) was read from the framework source, then confirmed by running the write tier against a disposable Invoice Ninja 5.13.50 instance (2026-10-24): single and multi-file uploads both attached.

Changelog

CHANGELOG.md follows Keep a Changelog and semantic versioning. Update it in the same change that alters behaviour — add an entry under ## [Unreleased], in the right section (Added, Changed, Deprecated, Removed, Fixed, Security), creating the section if it is not there yet. Entries describe the effect on a user of the crate, not the implementation: say what broke or changed for a caller and why, not which function was edited. Purely internal work (refactors, test-only changes, doc tweaks) does not need an entry.

Architecture

• src/client.rs — InvoiceNinjaClient holds a reqwest::Client (with the X-Api-Token auth header baked in) and a base_url. Low-level helpers (get_list, get_one, post_one, put_one, delete_one, post_list) handle request dispatch and decode ListResponse<T> / ItemResponse<T> envelopes, mapping non-2xx responses through api_error into Error::Api.
• Not every endpoint answers with a JSON envelope, so there are three other helper families: get_raw/post_raw return the body as bytes (PDF streams and CSV report exports), get_unwrapped/post_unwrapped decode a bare JSON body with no data wrapper (/statics, /charts/*, /search), and get_discard just checks the status (/ping).
• Per-resource methods (list_clients, get_invoice, create_product, etc.) are generated by the resource_methods! macro at the bottom of client.rs, which expands to list/list_all/get/create/update/delete/bulk for a given REST path and model type. To add a new resource: add a model under src/models/, re-export it from src/models/mod.rs, and add one resource_methods! invocation in client.rs. Note the macro takes seven method names before the path and model — adding a resource means passing all seven.
• resource_methods! delegates the six CRUD methods to crud_methods! and adds bulk on top. Use crud_methods! directly for resources with no /bulk route — currently client_gateway_tokens, companies, and system_logs. Check routes/api.php before assuming a resource has one; a generated bulk_* against a missing route just 405s.
• Requests go through two chokepoints: req(method, path) builds them and is the single place the optional X-API-PASSWORD header and the per-request timeout are attached, and execute(builder) dispatches them and is the single place retrying happens. A new helper must use both — calling self.http directly would skip the header, the timeout, and the retry policy. Only req and execute should touch self.http.
• The request timeout is per attempt, not per call. RetryPolicy:: max_elapsed is what bounds a call overall; without it, four attempts at the 60s default would take four minutes. Keep both in mind when changing either.
• Both credentials are stored as HeaderValues with set_sensitive(true). reqwest's Client Debug prints its default headers, so that flag is the only thing keeping the API token out of any {:?} log. Don't build either header without it; a test pins this.
• src/retry.rs — RetryPolicy plus the rules for what may be replayed. The method matters, not just the status. A 429 means the server refused the request without processing it, so any method is safe to retry; a 5xx or timeout gives no such guarantee, so only idempotent methods are. Don't extend retrying to POST on 5xx — this is a billing API, and a replayed create would duplicate an invoice or payment.
• Interpolate ids into paths with seg(id)?, never raw. It escapes the value into a single path segment and rejects ids that are empty or dot-only. Both halves matter: escaping stops a / or ? in an id from retargeting the request, but escaping alone is not enough, because the WHATWG rules the url crate follows decode %2E back to . before resolving dot segments — so an escaped .. still collapses the path. The exceptions are report and chart, which take a multi-segment tail by design (chart("project_burnup/<id>", …)) and must stay unescaped.
• entity_action_methods! generates three methods — {x}_action and download_{x} for the GET /{resource}/{id}/{action} route, plus download_{plural} for the bulk merged-PDF action. Only invoices, quotes, credits, and purchase orders have the action route — don't add it elsewhere without checking routes/api.php. In particular the official PHP SDK puts bulk download on every resource, which is wrong; only PDF-rendering entities support it.
• invitation_download_methods! generates download_{x}_by_invitation_key and download_e_{x}_by_invitation_key for the same four resources. Two traps, both pinned by tests: the entity segment is singular (invoice/{key}/download, the only route family in the API that is), and the routes are authenticated despite being the link a client follows — they sit in routes/api.php's api/v1 group under token_auth. The genuinely token-less invitation downloads are the separate client-portal routes in routes/client.php, which are not under /api/v1 and are not wrapped. COVERAGE.md used to list the /api/v1 eight as unwrapped for that reason, having conflated the two families; don't reintroduce the claim.
• upload_methods! generates upload_{x} for the 16 resources with a /{id}/upload route; documents can only be created this way, because DocumentController::store is an empty stub upstream (hence no create_document). Three things are easy to get wrong, all verified against the upstream source: the request is a POST with _method=PUT (PHP does not parse multipart on a real PUT, and the spec's _method=POST would 405); is_public goes out as 1/0 (Laravel's strict boolean rule rejects the string "true"); and uploads are never retried, because reqwest's multipart body is not cloneable and execute gives an un-cloneable request exactly one attempt — a test pins this, since nothing in the types would notice if it changed. Don't "fix" any of the three.
• Non-CRUD endpoints (documents, reports, charts, search, statics, emails, refunds, ping/health) are hand-written in the last impl block rather than macro-generated, because their request and response shapes are all different.
• list_* returns one page; list_all_* goes through get_all_pages, which terminates on meta.pagination.total_pages and only falls back to the short-page heuristic when the server sends no metadata. The heuristic is not sound on its own: BaseController caps per_page at min(abs(per_page), 5000), so a page can be shorter than requested while records remain — which is why per_page is clamped to 5000 before the walk starts. per_page(0) falls back to the default size (it would make the short-page check got < 0, which never terminates), the page counter advances locally rather than trusting the echoed current_page, an empty page always ends the walk, and a MAX_PAGES backstop raises Error::PaginationLimit rather than quietly returning a truncated list.
• src/models/ — one file per resource, plus common.rs for shared envelope/pagination types (ListParams, ListResponse, ItemResponse, Meta, Pagination).
• Several endpoints share a schema, so some models are type aliases rather than separate structs: Invoice Ninja keeps quotes and credits in the invoices table (an entity_type field distinguishes them), so Quote and Credit alias Invoice (src/models/invoice.rs); likewise RecurringQuote aliases RecurringInvoice (src/models/recurring_invoice.rs), whose fields are a strict superset. Each alias still gets its own path via the macro.
• Every model struct has a #[serde(flatten)] pub extra: Map<String, Value> field. This preserves any API fields not explicitly modeled, so a get followed by an update round-trips without silently dropping data. Keep this pattern when adding fields or new models.
• Every non-Option field carries #[serde(default, deserialize_with = "super::common::null_to_default")], not a bare #[serde(default)]. default alone only covers a missing key; a key present with an explicit null fails with invalid type: null, expected a string. Invoice Ninja returns null for many nominally-string fields, so a bare default would break decoding of the whole response. Option<T> fields keep the plain #[serde(default)] — they already map null to None, and that distinction matters (an unset archived_at should stay None, not become Some(0)).
• Models deliberately cover a curated subset of each schema and let extra carry the rest — custom_value1..4 and custom_surcharge1..4 are intentionally unmodeled. Fields whose JSON type is ambiguous or inconsistent in the upstream spec (e.g. Subscription.currency_id, webhook_configuration, due_date_days) are also left to extra, since a wrong concrete type is a hard deserialize error whereas extra is lossless.
• Field names and types come from Invoice Ninja's own OpenAPI spec (openapi/api-docs.yaml on the v5-stable branch of the invoiceninja repo). Check it before adding or retyping a field; the same name can differ in type across resources (frequency_id is a number on recurring invoices and expenses but a string on subscriptions).
• The published spec is incomplete for routes: it documents /{id} and action paths only for clients, locations, and tags, and omits them for invoices and everything else. routes/api.php in the same repo is the authoritative route list, and the controllers are authoritative for what a given action returns. Use the spec for schemas, the routes and controllers for endpoints.
• src/error.rs — Error enum (thiserror) covering transport, JSON decode, API error responses (with per-field validation errors map), and client construction errors. ApiErrorBody mirrors Invoice Ninja's error JSON shape.
• A missing record is a 400, not a 404. Handler.php maps Laravel's ModelNotFoundException to a 400 carrying No query results for model [App\Models\X]., and keeps 404 for a route that does not exist or a method it does not support. So don't write a not-found check against 404 — the smoke test's post-purge assertion did, and passed only because it had never been run. Match the status together with the message.

Coverage

All 34 of the API's Route::resource groups are wrapped, plus users (which isn't one). 338 methods: 30 resources with CRUD + bulk, 3 with CRUD only, 4 with entity actions, 4 with invitation-key downloads, 16 with document uploads, and 74 hand-written.

Plus the non-CRUD surface: documents, entity actions and PDF downloads for the four action-capable resources, their invitation-key PDF and e-document downloads, report, chart, search, statics, send_email, refund_payment, ping, and health_check.

COVERAGE.md is the detailed inventory — every wrapped endpoint, every gap, and the reason for each gap. The main remaining gaps are the integration and auth routes, import/export, the client-portal routes (which are not under /api/v1, so they don't fit the client's base_url), and a few company and user extras.

Keep COVERAGE.md current when adding or removing an endpoint: it names exact counts and route groups, so it goes stale quietly. The three coverage summaries — here, README.md, and COVERAGE.md — should agree; COVERAGE.md is the one with the specifics, the other two summarize and link to it.

Relationship to the official PHP SDK

invoiceninja/sdk-php is the first-party wrapper and a useful cross-check, but it is thinner than this crate — each endpoint class is just a URI over a shared BaseEntity. See the comparison table in COVERAGE.md for what each side covers.

Two divergences are deliberate and shouldn't be "fixed" to match it:

• We send JSON; it sends form_params. Form encoding bracket-encodes nested structures, which is bad for payloads like an invoice's line_items. The API accepts both.
• We keep the whole errors map on Error::Api; it surfaces only the first validation message.

And two of its behaviours are bugs not to copy: it sends stream: false in download payloads (no controller reads a stream input), and it exposes download on every resource even though only PDF-rendering entities support that action.