@v3finance/core-sdk 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -3,11 +3,442 @@
 All notable changes to this package are documented in this file. The format is based on
 [Keep a Changelog](https://keepachangelog.com), and this project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.2.1 — 2026-11-12
+
+### Added
+
+Spec snapshot refreshed from the live API (commit `07ac55d`). No operation was added or removed.
+
+- `addresses.create()` with a `groupId` answers 201 with `warnings` when the address was created
+  but could not be put into the folder — the folder was deleted, the right to it was lost after
+  the check, or the write failed. The codes are in the new `FolderSkipWarning`:
+  `FOLDER_NOT_FOUND`, `FOLDER_FORBIDDEN`, `FOLDER_WRITE_FAILED`.
+- `approvals.vote()` — `applyWarnings` on `RequestVoteResult`, the same warning for a vote that
+  applied an approved `create_address`. The API now keeps the folder chosen when the request was
+  filed (it used to drop it, and the address was created outside the folder without a word) and
+  checks the right to it when the request is applied. The request's history gets a
+  `folder_skipped` event; `ApprovalRequestEvent.type` is a `string`, so that is not a type change.
+- `docs/errors.md`: the codes above, which are warnings and not errors, and the codes of the
+  web-login refusals in front of the auth library — `ADMIN_CANNOT_APPROVE_WEB_LOGIN`,
+  `WEB_SESSION_CANNOT_APPROVE`, `WEB_SESSION_CANNOT_MANAGE_SESSIONS` — plus the library's
+  `FAILED_TO_GET_SESSION`, which the API refers to. The note that the API does no rate limiting of
+  its own is corrected: requesting a web-login code is limited, with a 429 `RATE_LIMITED`.
+
+### Fixed
+
+- **The client did not work in a browser at all.** Every request failed with a `network` error
+  before it was sent. The transport stored `fetch` in a private field and called it as a method,
+  which passes the client as the receiver; a browser's `fetch` rejects any receiver but the window
+  (`TypeError: Illegal invocation`). Node and React Native do not check, so nothing caught it until
+  the first web page used the package. `fetch` is now called with no receiver, and when no custom
+  one is given the global is looked up per call — so instrumentation or a mock server that
+  replaces `globalThis.fetch` after the client is built is honoured too. No workaround is needed
+  any more; if you passed `fetch: (input, init) => fetch(input, init)` to get around this, it can
+  go.
+- `addresses.update()` answered without `owner`, `access` and `sharing`, although its type is the
+  listing row and declares the first two as required. That was the API's handler, and it is fixed
+  there: the answer is now the same row `addresses.list()` returns, so it can replace the address
+  in a list. `sharing` is accordingly required on `Address` (`AddressListItem`) and on
+  `AddressDetail`. Reading code is unaffected; a fixture or mock that builds one of these without
+  `sharing` stops compiling.
+- `transfers.send()` — the documentation said `outcome: 'replayed'` means "already sent". It does
+  not: it means a transfer with this `idempotencyKey` already existed, and `data` is that transfer
+  as it stands now — confirmed, waiting for signatures, still executing or failed. Read
+  `data.transaction.status`. Corrected in the TSDoc of `transfers.send` and `Gated`, in the README,
+  `docs/concepts.md` and `docs/errors.md`. No code changed.
+
+## 0.2.0 — 2026-11-11
+
+The API corrected its own document between 0.1.0 and this release:
+[v3-finance/policy-engine#13](https://github.com/v3-finance/policy-engine/pull/13) brought the
+response schemas in line with what the handlers send and tied the two together with tests on the
+API's side. Every answer this package had been describing by hand, because the document was wrong
+about it, is generated again — and a number of generated shapes moved as a result. Those moves are
+listed under **Breaking** below; read that part before upgrading.
+
+### Added
+
+- `docs/errors.md` — every error code the API can return, grouped by domain, with what causes it
+  and what a client should do about it, plus the codes that are easy to mishandle and the ones
+  declared in the server's types but never actually returned.
+- `registries.evaluate(input, { explain: true })` — the per-policy trace of a decision: for every
+  enabled policy the person has for the action, whether it applied and, if not, which selector it
+  failed on. The API already read `?explain=true` but did not declare it, and a typed client
+  should not invent parameters; it is declared now. All four decisions carry `trace[]` then, a
+  bare `deny` included. Without the flag the field is absent, which is why `EvaluationResult`
+  keeps it optional.
+- One schema per report type — `TransactionActivityReport`, `CounterpartyActivityReport`,
+  `CounterpartyGroupActivityReport`, `AssetMovementReport`, `AddressActivityReport`,
+  `AccountStatementReport`, `OperationsExceptionsReport`, `ApprovalActivityReport`,
+  `BalancePositionReport`, next to the existing `CategoryAnalytics` — and `AnyReport`, the union of
+  the ten. With them come the row types they are built from (`ByCounterpartyAddressRow`,
+  `ByGroupCounterpartyRow`, `ByCounterpartyBriefRow`, `StatementTokenRow`, `ReportAccountBalance`).
+- Named request bodies for the reporting resource: `CreateReportTemplateBody`,
+  `PatchReportTemplateBody`, `CreateReportSnapshotBody`, `CreateReportExportBody` and
+  `ReportDrilldownBody`.
+- Three snapshot schemas instead of one: `ReportSnapshot` (what creating one answers, figures under
+  `result`), `ReportSnapshotDetail` (one snapshot, figures under `resultJson`) and
+  `ReportSnapshotListItem`, plus `ReportSnapshotList` for the listing.
+- Ledger and balances: `LedgerPosting`, `LedgerEntryToken`, `LedgerEntriesPage`,
+  `BalancesAsOfTotal`, `BalancesAsOfAccount`, and `BalancesAsOfWithAccounts` — what
+  `balances.asOf()` answers when no summary was asked for.
+- Sharing: `ParticipantVia` (where a person's access comes from, as a union discriminated by
+  `kind`), `ShareBatchItem` (`ShareBatchGrantedItem | ShareBatchRejectedItem`, discriminated by
+  `ok`), `ShareBatchAllRejected` (the body of the all-refused 400) and `ShareGrantCreated`.
+- Fields the API has been sending and now declares, so they are reachable through the types:
+  `usdValue`, `decisionPolicyVersionId`, `decisionCounterpartyGroupsJson`, `counterpartyId` and
+  `idempotencyKey` on `TransactionDetail`; `currentVersionId` on `Policy`, `PolicyDetail`,
+  `PolicyWithRules` and the rows of `VaultPoliciesPage`; `policyVersionId` on `PolicyTrace`;
+  `policyId` on `PolicyApprover`; `revokedAt` and `revokedById` on `AddressAccessGrant` and
+  `VisibilityGrant` (which also gains `updatedAt`); `groupId` on the rows of `VaultPoliciesPage`;
+  and `_count` on `AddressGroup` and `AddressGroupDetail` — an ORM counter that equals
+  `memberCount`, declared only because it arrives; read `memberCount`.
+  One of these changed behaviour as well as type: `POST /policies` used to answer
+  `currentVersionId: null` although the first version had already been taken, and now answers its
+  id.
+
+### Changed
+
+- Spec snapshot refreshed from the live API twice since 0.1.0.
+
+  The first refresh (API commit `ebd03eb`) moved no type. The envelope no longer drops the
+  machine-readable keys a handler sets beside `error`: it carries them inside `details`, so
+  `error.details.field` names the category field that failed validation (it is an explicit `null`
+  when the error is not about one field) and `error.details.stepIndex` the composite step that was
+  denied, counted from 0. Against the 0.1.0 snapshot that was 306 changed descriptions in
+  `openapi/spec.json` and 6 changed examples — the invitation token example stopped looking like a
+  live secret — and two lines in `src/generated/`.
+
+  The second (API commit `165504b`, v3-finance/policy-engine#13) is the one this release is about.
+  The document now names 262 schemas, up from 228: 34 added, none removed, and 30 of the existing
+  ones changed shape. 72 operations under `/vaults/{code}` now declare a 403 or a 404 they did not
+  before; that changes no type — it documents refusals those endpoints already gave, the
+  vault-membership gate first among them.
+- `docs/errors.md` told callers those two keys were stripped and had to be parsed out of `message`.
+  That was accurate when it was written and is not any more. Corrected with it:
+  - an unmatched path and an unhandled exception now answer with the envelope as JSON, so a
+    non-JSON error body usually means the edge or a proxy answered rather than the API. Not always,
+    and the document now says so: a malformed or empty body sent under a JSON content type is
+    refused by the framework's validator with a 400 `text/plain`, which is raised as an exception
+    carrying its own finished response and so never passes through the envelope layer. No resource
+    method of this package can produce one;
+  - a validation failure does not reach a client as the flat `{error: "…"}` string the document
+    showed. The handler builds that shape, the envelope layer repackages it, and what arrives is
+    the ordinary envelope with a status-derived `BAD_REQUEST`;
+  - there is nothing diagnostic left in `message` to forward on a signing-service failure or a
+    failed report — but only the report one is a constant (`Report generation failed`). The
+    signing-service message is a template carrying the upstream status (`Wallet Service returned
+    400`), on address creation as well as on transfers; what is withheld is the service's own
+    response body, which goes to the worker log.
+- `reports.run(type, …)` answers with the schema of THAT report. `ReportResult` used to map nine of
+  the ten types to one loose `ActivityReport` in which every block was optional, so
+  `run('balance_position', …)` offered a `summary` that report never has and no `totalsByAsset`,
+  which is all it has. Each type now maps to its own schema; `runUnified(type, …)` narrows the same
+  way, and `runTemplate()` answers `AnyReport`, because a template's type is not known to the
+  compiler.
+- Every request body of the reporting resource is typed. `createTemplate`, `updateTemplate`,
+  `createSnapshot` and `createExport` took `unknown` because the document declared those bodies
+  inline and there was nothing to import; it names them now. `queryOperations` takes
+  `DrilldownQuery`, which is `ReportDrilldownBody` with its two free-form bags (`filters`,
+  `drilldown`) replaced by the keys the endpoint actually reads — the generated type alone would
+  let a misspelled filter compile and make a figure disagree with its own breakdown — and answers
+  `DrilldownResponse`.
+- `me.updateProfile()` is typed `UserProfile`, as it was, and the type is now TRUE. The PATCH
+  handler used to return the database row without `needsEmail`, so the answer read `undefined`
+  where a `boolean` was promised — on the flag that gates the "add your real email" prompt. The
+  API sends it on both paths now.
+- Names this package exports that the document also has — `LedgerPosting`, `ReportSnapshotDetail`,
+  `ReportSnapshotListItem` — are strict aliases of the generated schemas, as are `LedgerEntryItem`
+  (of `LedgerEntry`) and `PolicyRow` (of `PolicyTableItem`). Only `ReportSnapshotListItem` existed
+  in 0.1.0, as a hand-written `Pick` of the same eleven fields.
+- `ReportType` is taken from the document's own enum rather than spelled out. Same ten values.
+- `AssignCategoryBody.values` is optional, as it is to the API, which defaults it to `{}`. A
+  category with required fields still needs them filled.
+- `sharing.share()` and `folders.grant()` are typed with `ShareGrantCreated`. It is the same union
+  as before, `AddressAccessGrant | ShareBatchResult`, under the name the document gives it.
+- `balances.entries({ addressId })` narrows for a non-administrator too. The API used to ignore
+  the filter for members and answer with entries across all of their addresses; it now applies it
+  within the member's own addresses, and somebody else's address answers an empty page rather than
+  a 403. Nothing changed on this side — the same call returns less.
+- `balances.entries({ entryType })` is typed with `LedgerEntryType`: the six kinds the journal
+  reports — `genesis` among them, the opening correction written when the ledger was first
+  backfilled — or the stored spelling of the three that are renamed on the way out. That is the
+  FILTER; an entry itself still carries a `string`, as the document declares.
+
+#### Breaking
+
+Type-level only: no method was renamed or removed, no exported name was dropped, and an existing
+call sends the same request. What changed is what the compiler believes about answers, so an
+upgrade can surface compile errors in code that reads them — in nearly every case at a spot that
+was already wrong at runtime: a field that read `undefined`, a string treated as a number.
+
+**A field changed type**
+
+- `Comparison.incomingUsdChangePercent`, `outgoingUsdChangePercent`,
+  `grossTurnoverUsdChangePercent`, `operationsCountChangePercent` and
+  `averageOperationUsdChangePercent` — `number | null` → `string | null`.
+- `Observation.changePercent` — `number | null` → `string | null`.
+
+  These six are decimal STRINGS on the wire (`"12.5"`, `"-40"`) and always were; the document said
+  `number`. Arithmetic or `toFixed()` on them compiled and operated on a string. Put them through
+  `parseDecimal`, or `Number()` if a float is acceptable for display.
+- `ReportMeta.dataCutoff` — `string | null` → `{ timestamp: string, blockNumber: number | null }`.
+- `ReportMeta.schemaVersion` — `string | number | null` → `string`.
+- `CategoryAnalytics.report` — no longer `ReportMeta` but the five fields that report really
+  carries (`type`, `generatedAt`, `from`, `to`, `timezone`).
+- `ActivityReport` — an interface whose twelve blocks were all optional → a deprecated UNION of
+  the nine per-type schemas. Reading `report.summary` off it no longer compiles, because not every
+  member has one. Use the schema of the report you asked for, or `AnyReport`. Narrow a union by a
+  block only that report has (`'totalsByAsset' in report`): `report.type` will not do it, since
+  the document types that field as the same ten-value enum on every member.
+- `reports.runTemplate()` — `ActivityReport` → `AnyReport`, which adds `CategoryAnalytics`.
+- `reports.run()` and `reports.runUnified()` — `ActivityReport` → the schema of the report asked
+  for. Reading a block that report does not have stops compiling: `.approvals` on anything but
+  `approval_activity`, `.summary` on `account_statement`. Those reads returned `undefined` before.
+
+**A parameter stopped accepting any string**
+
+- `ReportFilters`: `dateBasis`, `groupBy`, `comparison`, `counterpartyClassification`,
+  `folderClassification`, `breakdownBy` and `agg` are the enums the document declares. `groupBy:
+  'quarter'` used to compile and answer 400.
+- `reports.run('address_activity', …)` requires exactly one of `addressId` and `folderId`. Neither,
+  or both, was a 400 — delivered as `REPORT_INVALID_PERIOD`, which points at the dates.
+- `balances.entries({ entryType })` — `string` → the union of entry types.
+- `reports.snapshot()` — `ReportSnapshot` → `ReportSnapshotDetail`. There is no `result` on it: the
+  figures are under `resultJson`, where the detail endpoint has always put them. `result` exists
+  only on what `createSnapshot()` answers.
+- `BalancesAsOf.totals` and `.accounts` — arrays of untyped records → `BalancesAsOfTotal[]` and
+  `BalancesAsOfAccount[]`. `accounts` is also OPTIONAL in the schema now (absent under
+  `summary: true`); the three overloads of `balances.asOf()` still tell the two cases apart, so
+  `(await balances.asOf(at)).accounts` needs no check.
+- `LedgerEntry.postings[]` — the fields the document used to promise beyond the two ids (`amount`,
+  `amountDecimal`, `direction`, `token`, `account`) are gone, replaced by what arrives:
+  `LedgerPosting`, with the figure in `amountRawSigned`/`amountDecimalSigned`.
+  `LedgerEntry.token` is `LedgerEntryToken | null` instead of an untyped record, and
+  `operationType` is `'transfer' | 'deposit' | null`.
+- `Participant.via` — an array of untyped records → `ParticipantVia[]`.
+- `CategoryAccessScope` — `unknown` → `'owner_only' | 'vault_members'`, which is what
+  `viewScope`, `assignScope` and `editScope` take on `categories.create()`/`update()` and what a
+  category carries. The API still ACCEPTS `restricted` on input as an alias of `owner_only`, stores
+  it as `owner_only` and never answers with it; the type leaves it out on purpose, so a caller
+  that sends it stops compiling. Send `owner_only`.
+
+**A field was removed from a type — it never arrived**
+
+- `ReportTemplate.createdById` → the field is `ownerId`. `description` is declared, and
+  `parametersJson` is never `null`.
+- `ByAddressOwnerRow.ownerId` and `.owner` → the field is `userId`, and the row also carries
+  `addressesCount`, `incomingByAsset` and `outgoingByAsset`.
+- `AssetAmount.contractAddress`. It is on `ByAssetRow`, not on an amount.
+- `PolicyTableItem.conditionJson` and `.approvalJson` — neither policy listing selects them
+  (`admin.policies.list`, `admin.policyGroups.policies`), so a row cannot tell you whether a policy
+  is conditional. Load the policy itself for that.
+- `_count.limits` on the rows of `VaultPoliciesPage`.
+
+**A field became required or lost `null`**
+
+Harmless when reading, a compile error when BUILDING one of these — a fixture or a mock: the six
+status counters, `activeDays`, `firstOperationAt` and `lastOperationAt` on `ReportSummary`; every
+field of `ReportMeta` (all are required now, `from`, `to`, `timezone` and `generatedById` are never
+`null`, and `type`, `dateBasis`, `baseCurrency` and `classificationMode` are enums); `tokenId`,
+`assetCode` and `network` on `AssetAmount` and `ByAssetRow`; `severity` (`'info' | 'warning'`) and
+`drilldownFilters` on `Observation`; most of `ReportSnapshot`, `result` included; `vaultId`,
+`requestedAt`, `storageKey`, `errorCode` and `errorMessage` on `ReportExport`; `updatedAt` on
+`ReportTemplate`; `metric.agg` on `CategoryAnalytics`; `LedgerEntry.reference`; and the fields
+listed under Added. `ShareBatchResult.results[]` is a discriminated union now, so an item must be
+consistent with its `ok`.
+
+**A request body that was `unknown` is checked**
+
+`createTemplate`, `updateTemplate`, `createSnapshot` and `createExport`, as above; and
+`queryOperations`, whose body went from `unknown` to `DrilldownQuery` and whose answer from
+`unknown` to `DrilldownResponse`. A body the API would have refused with a 400 no longer compiles.
+
+`parameters` on the first three is typed as a free-form record, and it is NOT a query string — the
+API hands it to the report builder as it is, parsing nothing and defaulting nothing. So the
+obvious move, spreading the filters of a live report into it, is safe only with two conditions:
+
+- **`categoryField` is ignored there.** A live report parses `'ticker:EUR'` into a filter; a
+  template or snapshot does not, and answers 200 with figures for EVERY value — a frozen report
+  that silently is not the one on screen. Send the parsed form instead:
+  `categoryFieldValues: { ticker: ['EUR'] }`. This is a defect of the API, reported there; the
+  package documents it rather than hides it.
+- **`timezone` has no default there.** The live endpoints fall back to `UTC`; pass it explicitly.
+
+Multi-value filters must be arrays (a comma-separated string is not split), and because the type
+is an index signature a value typed as the `ReportFilters` interface needs a spread
+(`parameters: { ...filters }`).
+
+**Unchanged in type, corrected in meaning**
+
+- `AssetAmount.amount` is still a `string`, and its description no longer says "raw smallest
+  units". It is a DECIMAL string in units of the asset (`"1.5"`), signed only in the `netFlow*`
+  blocks. Code that passed it to `amount()` was already failing at runtime on the first fractional
+  value; use `parseDecimal`. The same holds for the `byAsset` rows and the balances of
+  `asset_movement`, `account_statement` and `balance_position`. The one raw figure in a report is
+  `balanceRaw` in the opening and closing balances of `address_activity`.
+- `BalancesAsOfTotal.available` and `.reserved` are DECIMAL too — duplicates of
+  `availableDecimal`/`reservedDecimal` — while the fields of the same names on `balances.list()`
+  are raw. Raw figures of a replay exist only per account, in `accounts[].balance`.
+- The percentage fields that are new to the document with the per-type schemas —
+  `turnoverShareUsd`, `shareOfGroupTurnoverUsd`, `shareOfUserActivityUsd`, the `…RatePercent`
+  fields of `approval_activity`, the two shares in `balance_position.concentration` — are decimal
+  strings as well.
+
+### Fixed
+
+Nineteen of the fixes below NARROW a type that used to be `string`, `unknown` or a loose
+`Record`. Code that passed a value the API rejects now fails to compile instead of failing at
+runtime with a 400 — which is the point, but it means an upgrade can surface new compile errors.
+None of them renames or removes an exported name.
+
+**Calls that could not be made at all**
+
+- `reports.run('balance_position', …)` accepted no parameters. Its entry declared
+  `Record<string, never>`, and that index signature applies to the fields of `ReportFilters` too
+  once the two are intersected, collapsing every one of them to `never`. The only argument that
+  compiled was `{}` — so the report could not be asked for a date, which is the whole point of a
+  position report. All six parameters the handler reads now compile.
+- The `idempotency-key` header is no longer sent. The server has never read it, which by itself
+  bought nothing; in a browser it cost the entire request, because the API's CORS preflight allows
+  exactly `Content-Type` and `Authorization`, so a money call carrying the header was never sent
+  and surfaced as a network error no retry explained. The `idempotencyKey` option stays, accepted
+  and deprecated: the body field is what protects a transfer.
+- `units.format()` threw `RangeError` for any token with 0 or 1 decimals (`minimumFractionDigits`
+  defaulted to 2 above a `maximumFractionDigits` of `decimals`). The decimals ceiling was also 36
+  while the API and the package's own generated type allow 38, so `registries.createToken` could
+  register a token that `amount()` then refused.
+
+**Answers that were read from the wrong place**
+
+- `balances.entries()` typed postings from the document, which declared `amount`,
+  `amountDecimal`, `direction`, `token` and `account`. The handler sends none of them — the money
+  field is `amountRawSigned` — so `BigInt(posting.amount)` threw on the only endpoint that exposes
+  the ledger. The document has been corrected, and the type is the generated `LedgerPosting`.
+- `reports.snapshot()` promised `result`; the detail handler returns the stored row, so the field
+  is `resultJson`. The numbers were unreachable through the type and `result` read `undefined`
+  every time. The document now has a schema for each answer: `snapshot()` is typed with
+  `ReportSnapshotDetail`, and `createSnapshot()` keeps `ReportSnapshot` with `result` — that
+  handler does map it.
+- `balances.asOf()` exposed 2 of its 8 parameters. Opening the rest meant opening `summary`, and
+  with `summary` the handler omits `accounts` altogether. Three overloads tell the cases apart —
+  `BalancesAsOfWithAccounts` without a summary, `BalancesAsOfSummary` with one, the union when the
+  flag is decided at runtime — so the type never promises an array that will not be there. The
+  document agrees now: `accounts` is optional on `BalancesAsOf`.
+
+**Values the API rejects no longer compile**
+
+- `approvals.list({status})` took any string, but approval statuses are UPPERCASE while transfer
+  statuses are lowercase and both appear on one screen; `'pending'` compiled and got a 400.
+- `history.list({status})` took any string, and the package's own exported `TransactionStatus`
+  includes `submitted`, which that filter does not accept — the SDK was suggesting a value that
+  returns 400.
+- `balances.list({purpose})` knew 2 of the 4 ledger purposes.
+- `OperationType`, `OperationKind` and `PendingApproval` were hand-written aliases widened to
+  `string`, and an explicit re-export shadows the generated schema of the same name — so
+  `OperationType` reached consumers as `string` rather than `'deposit' | 'transfer'`, and a typo
+  in an operation type was caught only by the API. All three are strict aliases now, and
+  `test/nameShadowing.test.ts` fails if one widens again.
+- Request bodies that were `unknown` on `categories.addField`/`updateField`/`addApprover`/
+  `addGrant`, `admin.invitations.acceptDebug`, `vaults.buildDerivationPath`/`parseDerivationPath`
+  now carry their schemas. Response types were filled in only where the handler was read and
+  matched.
+
+**Transport**
+
+- `timeoutMs` and `signal` stopped applying once the response headers arrived: the timer was
+  cleared around `fetch`, and the body streamed after. A server that answered and then stalled
+  mid-body left a request hanging with nothing to end it. Both now stay armed until the body is in
+  hand, and a body read that fails is no longer swallowed into `data: undefined` typed as the
+  shape the caller asked for.
+- A non-JSON error body put the proxy's whole HTML page into `message` (measured at 2.3 KB), and
+  `request()` and `fetchRaw()` disagreed about the same 502. They now answer alike, HTML is
+  suppressed and a short text body is kept.
+- `Gated.status` reported 201 when the server had answered 200.
+- A sub-second timeout rendered as "within 0s".
+
+**Documentation that no longer matched the API**: the shape of a validation error, the claim that
+a non-JSON error body can no longer come from the API, `CATEGORY_NOT_FOUND`'s actual paths,
+`REPORT_VAULT_NOT_FOUND` (unreachable — all seven in-handler vault 404s in the reports router are
+dead code), `details.param` on `REPORT_INVALID_PARAMS`, `SUBJECT_REQUIRED` across its three
+different answers, four of nine observation codes, the missing `OPERATION_RELATION_INVALID`, the
+transport codes (`NETWORK_ERROR`, `TIMEOUT`, `ABORTED`, `PARSE_ERROR`) that were named nowhere,
+the count of endpoints left out, the `replayed` branch that only `transfers.send` can reach, and
+the keyset-pagination claim (11 list endpoints are cursored, 18 return `items` alone, 8 a bare
+array).
+
+- `admin.users.setRole` took any string for the platform role. The spec declares
+  `enum: ["admin", "user"]`, so this is a narrowing the contract already backed — and worth the
+  compile error on a privilege path, where `string` meant finding out from a 400 after sending a
+  role change. The response keeps `role: string`: the spec declares it bare, and narrowing an
+  answer we do not control would be a guess. The type is exported as `PlatformRole`.
+
+- `approvals.vote` returned `unknown`. It is typed from `RequestVoteResult`, which the spec
+  declares as a component but never `$ref`s — the operation inlines its 200 instead. The two were
+  compared property by property and are the same schema, down to identical `required` sets; the
+  only difference is an `additionalProperties: false` that does not reach the TypeScript shape.
+  Worth checking rather than assuming, because a component nothing references usually means the
+  opposite — an orphan left behind, which is what the `Address` schema turned out to be.
+- `deleteSnapshot` and `deleteTemplate` returned `unknown` for a body the spec pins as
+  `{deleted: true}`.
+
+**Guards added**, because none of the above was caught by a green CI: `generate:check` compares
+only the generated files against the snapshot, and the surface test only checks that paths are
+reachable. New metatests cover name shadowing, query parameters missing from a method's type,
+request bodies left as `unknown`, and the completeness of `docs/errors.md`.
+
+Two more came with the corrected document. `test/reportResults.test.ts` holds every method of the
+reporting resource to the schema the API declares for the operation it calls — the check that
+would have caught nine report types sharing one catch-all. And the body test now has a second
+list beside the untyped one: bodies typed by hand OVER a named schema, each held to that schema's
+fields. It has one entry, `queryOperations`; the list of untyped bodies is empty.
+
+`test/transport.test.ts` pins the transport fixes by BEHAVIOUR, which none of the metatests can
+reach: they are all about *when* something happens — when the timer is cleared, when the body is
+read, which status is reported — and no type describes that. Its stub aborts its body stream when
+the signal fires, the way a real `fetch` does, and that detail is the whole test: a stub that
+ignores the signal passes even against the broken client, because nothing can interrupt a body
+nobody wired up. Each case was checked by reverting the fix — restoring the old timer placement
+turns four of them red with "test timed out", which is the production symptom exactly.
+
+**Seven places where the API's document disagreed with its own handlers** turned up while this
+release was being prepared. hono-openapi does not validate answers against the document, so
+nothing here could fix them — only describe the answer by hand and say why.
+v3-finance/policy-engine#13 fixed all seven at the source, and the hand-written descriptions have
+been dropped in favour of the generated types:
+
+| What was wrong | What it meant in 0.1.0 | Now |
+|---|---|---|
+| Ledger postings declared five fields that never arrive and none of the six that do | `posting.amount` was `undefined`; `BigInt(posting.amount)` threw | generated `LedgerPosting`, figure in `amountRawSigned` |
+| One schema for a snapshot, though creating one answers `result` and reading one `resultJson` | `snapshot(id).result` read `undefined`; the figures were unreachable through the type | three schemas; `snapshot()` answers `ReportSnapshotDetail` |
+| `accounts` required on `BalancesAsOf`, though absent under `summary=true` | nothing yet — `asOf()` did not offer `summary` | optional in the schema; the overloads of `asOf()` say which call gets it |
+| `AssetAmount.amount` described as raw smallest units | `amount(x.amount, decimals)` threw on the first fractional value | described as the decimal string it is |
+| The all-refused batch grant answers 400 with `{results}`, declared as an error envelope | the per-subject reasons were in `error.details`, which nothing described | declared as a second form of that 400, `ShareBatchAllRejected`. The SDK still throws on it, body in `details` |
+| `usdValue`, `decisionPolicyVersionId`, `currentVersionId` sent but not declared | unreachable through the types | declared; see Added |
+| `PATCH /me/profile` declared `needsEmail` and did not send it | `updateProfile()` answered `needsEmail: undefined` | the HANDLER was fixed, not the document: the flag is sent |
+
+What remains hand-written is hand-written because the document has nothing to offer, not because
+it is wrong: query parameters (the generator emits schemas only, never `parameters`), the few
+answers the API still declares inline without a name (`AmlScore`, the status-history row), and the
+unions it carries only as a bare `string` — `TransactionStatus`, `ApprovalRequestStatus`,
+`LedgerEntryType`. One answer stays untyped for the first of those reasons: the group access
+summary of `admin.policyGroups.access`.
+
+- `codeFromStatus` now uses the API's own name for every status the API names: 401 is
+  `UNAUTHENTICATED` (was `UNAUTHORIZED`), 422 is `UNPROCESSABLE_ENTITY` (was `UNPROCESSABLE`), 503
+  is `SERVICE_UNAVAILABLE` (was `UNAVAILABLE`), and 413/501 are now named at all. Previously a
+  non-JSON response gave a code the server never uses for that condition, so a client branching on
+  the server's name missed it. 502 and 504 keep the SDK's own names, because the API has no
+  envelope for them — they arrive from the edge.
+  The test covering this mapping asserted only the statuses that already agreed; it now covers all
+  of them.
+
 ## 0.1.0 — 2026-11-10
 
-First release. The whole API is covered — 171 operations grouped into resources, with the
-administrative surface marked — and a test asserts that every endpoint is reachable, so one added
-to the API shows up as a failure rather than as a gap nobody noticed.
+First release. Every endpoint a client calls is covered — 157 of the API's 171 operations, grouped
+into resources, with the administrative surface marked; the fourteen exceptions are listed under
+Known limitations. A test asserts that each of the rest is reachable, so one added to the API shows
+up as a failure rather than as a gap nobody noticed.
 
 ### Added
 
@@ -17,8 +448,8 @@ to the API shows up as a failure rather than as a gap nobody noticed.
 - Injected authentication: `getAuthHeaders`, `onTokenRotated`, `onUnauthorized`. Works with a
   browser cookie, a native cookie jar or a bearer token; the package stores no credentials.
 - `CoreError` with a `code` that is always present and a `kind` separating HTTP, network, timeout,
-  aborted and parse failures. Three real response shapes are parsed, including the validation
-  failure that arrives as a plain string.
+  aborted and parse failures. Three real response shapes are parsed, including a flat
+  `{error: "…"}` string — which is what a non-JSON error body is read as.
 - Money as smallest-unit strings with BigInt arithmetic (`amount`, `parseDecimal`, `format`, `add`,
   `sub`, `compare`). There is no `toNumber`, on purpose: it would be a convenient door into the
   precision loss the module exists to prevent.
@@ -40,5 +471,8 @@ to the API shows up as a failure rather than as a gap nobody noticed.
 - The `assets` filter on reports is accepted by the API and silently ignored by it, so it is marked
   deprecated here. Use `tokenIds`.
 - `runTemplate` cannot override a template's stored filters: the endpoint accepts no body.
-- `/welcome` and `/webhooks/wallet` are not exposed — a browser landing page and the wallet
-  service's inbound channel respectively.
+- 14 of the 171 operations are not exposed. `/welcome` and `/webhooks/wallet` are a browser landing
+  page and the wallet service's inbound channel; the other 12 are the `/address-groups/*` paths,
+  which are the older prefix of the same endpoints the folders resource serves under
+  `/address-folders` — one entity, two prefixes, and exposing both would only raise the question of
+  which to call.