@v3finance/core-sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,434 @@
+# Changelog
+
+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.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. 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
+
+- `CoreClient` with vault scoping: `core.vault(code).addresses.list()`. A scope is an expression,
+  not state, so two vaults can be used side by side and switching the active one cannot leave a
+  stale scope pointing at the wrong place.
+- 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 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.
+- `Gated` results for the fifteen operations that can finish in more than one way, telling applied,
+  pending and replayed apart by HTTP status — the response bodies are identical, so a client
+  reading only the body reports "done" where the truth is "awaiting signatures".
+- Keyset pagination helpers `paginate` and `collectAll`.
+- Resources: addresses, transfers, history, balances, approvals, counterparties and their groups,
+  shared access, folders, members, operation labelling, operation metadata and relations, reports
+  with templates, snapshots and exports, registries, policy preflight, AML, sign-in, and the
+  administrative surface.
+- Per-report-type parameters, so the compiler requires `from`/`to` and the target each report needs
+  rather than letting the call fail at runtime.
+- `OPERATIONS`, a generated catalogue of all 171 API operations with the access level each requires.
+- Cache keys for TanStack Query at `@v3finance/core-sdk/query-keys`.
+
+### Known limitations
+
+- 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.
+- 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 V3 Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.