Developer reference
Client data fetching
Use API helpers, fresh generations and deliberate invalidation to show coherent financial answers.
Components use helpers under src/lib/api to call Helm’s API. The shared cache deduplicates reads and tracks generations; successful mutations invalidate affected data.
Read-state contract
| State | Presentation |
|---|---|
| Loading | Explain that the answer is being fetched. |
| Empty | Show that a successful owned result contains no records. |
| Unavailable | Show that the answer could not be established, with a retry path. |
| Ready | Render the server’s result and its evidence context. |
A failed balance read must not become an empty list or zero. A partial page is not complete history.
After a mutation
- Await a valid command result, not just a click or request dispatch.
- Invalidate the relevant entity and financial reads.
- Read under the same still-current owned identity.
- Display completion only when the relevant fresh result is established.
For an account with a separately stated balance, creation and balance confirmation can have different outcomes. Preserve recovery on the same account.
Stale response handling
Capture the identity and generation associated with the request. Reject a late result after sign-out, account change or generation retirement. Clear private caches and owned browser drafts through the existing privacy lifecycle.
Retry deliberately
Read retries and financial retries have different consequences. Use bounded reads; preserve the original idempotency contract for an uncertain command. Do not add hidden mutation retry loops in a component.
See hooks for selecting existing query contracts.