@v3finance/core-sdk 0.1.0 → 0.2.0

package/docs/errors.md

@@ -0,0 +1,471 @@
+# Errors
+
+Every failure thrown by this SDK is a `CoreError`.
+
+```ts
+import { CoreError, isCoreError, hasCode } from '@v3finance/core-sdk'
+
+try {
+  await client.vault('acme').transfers.send({ ... })
+} catch (e) {
+  if (!isCoreError(e)) throw e
+  if (hasCode(e, 'INSUFFICIENT_BALANCE')) return showTopUp()
+  showMessage(e.message)
+}
+```
+
+**`code` is always a non-empty string.** It comes from one of three places: the server sent it, it was derived from the HTTP status, or — when no answer arrived to derive anything from — it is one of the four the SDK names itself, in the table below. Branch on `code`; display `message`. Never branch on `message` — its wording changes without notice, and parts of it are in Russian.
+
+Those four are listed nowhere else in this document because the API does not use them for anything, so one `switch` over `code` can cover both halves without a collision.
+
+**`kind` says where the failure came from, and each kind calls for a different reaction:**
+
+| `kind` | `code` | `status` | Meaning | Reaction |
+|---|---|---|---|---|
+| `http` | from the body, otherwise from the status | the status | The server answered `>= 400`. `code` and `status` are meaningful. | Branch on `code` (tables below). |
+| `network` | `NETWORK_ERROR` | `null` | The request never completed: no connection, DNS, socket closed. | Retry. On money paths read [Timeouts on money paths](#timeouts-on-money-paths) first — the request may still have arrived. |
+| `timeout` | `TIMEOUT` | `null` | No answer within the timeout (60s by default). | Same as `network`, and on money paths the same caveat applies with more force. |
+| `aborted` | `ABORTED` | `null` | The caller aborted it via `signal`. | Not a failure. Do not surface it. On money paths treat it like `timeout`: the request may already have left. |
+| `parse` | `PARSE_ERROR` | `null` | A response arrived on a 2xx status but was not readable as JSON. | A contract mismatch or a proxy in the way. Report it; retrying rarely helps. |
+
+**`details`** is what the handler attached, plus the two root keys the envelope moves inside it (see below) — so it can be populated even where the handler attached nothing. Its shape depends on `code` — the tables name it where it is useful. It is `undefined` far more often than not.
+
+**`endpoint`** is `"METHOD /path"`, for logs only. Never put it in a user-facing message.
+
+## Two error envelopes
+
+Most of the API answers with `{"error":{"code","message","details?"}}`. Reporting endpoints (`/reports/*`, `/report-snapshots/*`, `/report-exports/*`, `/report-templates/*`) have their own, older envelope with `REPORT_*` codes and a `details` object that is usually `{}`. The two shapes differ on the wire; `CoreError` reads both, so you never see the difference. Two further shapes exist and are also handled: a flat `{code,message}` from the auth namespace, and a non-JSON body.
+
+A non-JSON error body almost always means the edge or a proxy answered rather than the API: both of the API's own catch-alls are JSON now — an unmatched path answers `{"error":{"code":"NOT_FOUND","message":"Not found"}}` and an unhandled exception `{"error":{"code":"INTERNAL_ERROR","message":"Internal error"}}`. There is one exception, and it is the API: a body that is malformed or empty while the request carries `Content-Type: application/json` is rejected by the framework's validator with a **400 `text/plain`** `Malformed JSON in request body`. That refusal is raised as an exception carrying its own finished response, so the envelope layer — which only ever rewrites JSON bodies — never sees it. It reaches you as `code: "BAD_REQUEST"` with that sentence as `message`.
+
+No resource method of this package can produce it: they build their bodies themselves and serialise with `JSON.stringify`. The only route to it from here is the low-level `request()` with a `body` that `JSON.stringify` turns into nothing — a function, a symbol — because an empty body still goes out under a JSON content type. Worth knowing so it is not mistaken for an infrastructure fault; not worth writing a branch for.
+
+What you do have to know is that the envelope layer rebuilds the body, so only `code`, `message` and `details` ever reach you under their own names. Two machine-readable keys that handlers set beside `error` are not lost, though — the layer carries them **inside `details`**:
+
+- `field` → `details.field` — the offending field key on a `CATEGORY_FIELD_*` error, and `null` when the handler decided the error is not about one particular field. The key is still inside `message` as well, but read `details` and stop parsing text.
+- `stepIndex` → `details.stepIndex` — which step of a composite chain was denied, counted from 0. `message` keeps its `"Step 2 (counterparty_create): …"` prefix for display, but take the number from `details`.
+
+The forwarded set is closed, and that is the part worth remembering: every other root key a handler sets is still dropped, which is what stops a future `{error: e.message, ...e}` from handing a client a database-driver text or an internal URL. A new key does not appear by itself — it has to be added to the API's list first.
+
+## Validation errors have no code of their own
+
+Request-schema failures (a missing field, a bad enum, a malformed cursor) come back in the ordinary envelope, with no code of their own:
+
+```json
+{ "error": { "code": "BAD_REQUEST", "message": "amount: Required; asset: Invalid enum value" } }
+```
+
+The validation hook inside the API does build a flat `{"error": "amount: Required; …"}`, and older notes (this file among them) described that as the wire format. It is not: the envelope layer repackages every body whose `error` is a string, so the flat form never leaves the API. Do not write a reader for it.
+
+`code` is derived from the status — the hook sets none — which is why it is `BAD_REQUEST` and not something domain-specific. `message` is a readable `path: problem` list joined by `; ` and is the only information available; `details` is absent. Show the message, or map it to your own form state by parsing the paths.
+
+This is why `BAD_REQUEST` is not a domain error. It means "the body or query did not match the schema", and it covers, among others: an unknown report type (`type=transaction-activity` instead of `transaction_activity` — the names are snake_case everywhere), an `idempotencyKey` shorter than 8 characters, and an out-of-range `limit`.
+
+## Status-derived codes
+
+When a body carried no code of its own — a proxy's HTML 502, a platform 429, an
+empty body — the SDK derives one from the status, using the API's own name for
+that status so that one condition has one name whichever side produced it.
+
+| Status | Code |
+|---|---|
+| 400 | `BAD_REQUEST` |
+| 401 | `UNAUTHENTICATED` |
+| 403 | `FORBIDDEN` |
+| 404 | `NOT_FOUND` |
+| 409 | `CONFLICT` |
+| 413 | `PAYLOAD_TOO_LARGE` |
+| 422 | `UNPROCESSABLE_ENTITY` |
+| 429 | `RATE_LIMITED` |
+| 501 | `NOT_IMPLEMENTED` |
+| 503 | `SERVICE_UNAVAILABLE` |
+| 502 | `BAD_GATEWAY` — the SDK's own name |
+| 504 | `GATEWAY_TIMEOUT` — the SDK's own name |
+| other `>= 500` | `INTERNAL_ERROR` |
+| other `4xx` | `REQUEST_FAILED` |
+
+502 and 504 are the exception, and they are the two statuses to **branch on by
+`status` rather than by `code`**: the API has no envelope for them — its own
+derivation would call both `INTERNAL_ERROR` — they arrive from the edge as HTML,
+and the SDK is the only side naming them.
+
+One asymmetry left on the server side, worth knowing only so you read it
+correctly: the API's envelope would derive `UNAUTHORIZED` for a 401 whose body
+somehow carried no code. No path produces that today — every real 401 comes from
+the authentication middleware with `UNAUTHENTICATED`.
+
+## Money and transfers
+
+`POST /transfers`, and the vote / cancel / reconcile endpoints behind it.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `INSUFFICIENT_BALANCE` | 400 | The atomic reserve failed: the address does not have that much of that token available. A concurrent transfer may have taken it. | Show the shortfall. Refresh balances before offering a retry — the amount that fits may have changed. Do not retry blind. |
+| `INVALID_AMOUNT` | 400 | Amount is not a positive decimal string, or has more decimals than the token allows. | Fix client-side. A user-facing validation message, not a retry. |
+| `TOKEN_NOT_FOUND` | 400 | The asset is not in the registry, or is disabled (kill-switched during an incident). | Refresh the token registry. If it is still missing, the asset is unavailable — say so; do not retry. |
+| `TOKEN_NETWORK_MISMATCH` | 400 | The token lives on a different network than the sending address. | A client bug or a stale form. Re-resolve the token for the address's network. |
+| `ADDRESS_NOT_FOUND` | 404 | No such address id. | Refresh the address list; the address was deleted or the id is stale. |
+| `ADDRESS_NOT_IN_VAULT` | 400 | The address exists but belongs to another vault. | A client bug: the vault scope and the address id disagree. |
+| `ADDRESS_TRANSFER_FORBIDDEN` | 403 | You are neither the owner nor an admin, and you hold no grant with transfer rights on this address. Checked before the policy engine. | Show the address as view-only. The remedy is a `contributor` grant from the owner — direct the user there, not to a retry. |
+| `POLICY_DENIED` | 403 | The policy engine said `block`, or no policy permits the action (default-deny). `details` carries the full decision, including `trace`. | Terminal for this request. Show `message` — it already names the rule that fired. Changing the amount or the destination may make the same request pass; retrying it unchanged will not. |
+| `APPROVAL_UNSATISFIABLE` | 409 | Signatures are required but cannot be gathered: fewer eligible approvers than the threshold. `details` has `{threshold, eligibleApprovers}`. | **Do not retry.** Nobody can approve this. Tell the user to contact an administrator — the policy or the approver group has to change. See [Easily confused](#easily-confused). |
+| `APPROVAL_FAILED` | 409 | The approval request could not be created for some other reason. The reserve has already been returned, so no funds are stuck. | Retry once with a **new** idempotency key. If it repeats, it is a server-side fault — escalate. |
+| `VAULT_HAS_NO_WALLET_SERVICE` | 500 | The vault has no `walletServiceUrl` configured. | Configuration fault, not a user error. Transfers from this vault cannot work at all. Contact an administrator. |
+| `GAS_STATION_FAILED` | 502 | Energy/bandwidth provisioning failed. The transfer is marked `failed` and the reserve is already returned. | Retry with a **new** idempotency key (the old one is bound to the failed row). If it persists, an upstream service is down. |
+| `WALLET_SERVICE_ERROR` | 502, or 400 when the signing service itself answered 4xx | The signing service was unreachable, errored, or returned no transaction id. The transfer is `failed` and the reserve is returned. | Same as above: retry with a new key. On the 400 variant the signing service rejected the request and a retry will fail identically — but `message` now gives only its status (`Wallet Service returned 400`): the service's own body is not echoed to clients, it goes to the worker log. Show that the signing service refused and report the transfer id; do not try to explain the refusal from `message`. |
+| `TRANSFER_NOT_EXECUTABLE` | 404 / 409 / 500 | The transfer is missing, or is not in the status execution requires. | Re-read the transfer and drive the UI from its real status. Do not retry. |
+
+### Voting on a transfer
+
+`POST /transfers/{id}/approvals` and `POST /transfers/{id}/cancel`.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `TRANSFER_NOT_FOUND` | 404 | No such transfer, or an `awaiting_approval` transfer has no approval request — which is a data inconsistency, not a normal state. | Refresh the list. If a transfer you can see keeps producing this, report it. |
+| `NOT_AWAITING_APPROVAL` | 409 | Voting is over: someone else's vote already resolved it, or it was cancelled. | Not an error worth an alert. Refresh the transfer and show its real status. |
+| `NOT_AN_APPROVER` | 403 | You are not in the approver snapshot taken when the request was created. Editing the policy or the group afterwards does not add you. | Hide the approve/reject controls for this item. Terminal. |
+| `ALREADY_VOTED` | 409 | You already voted. One vote per person. | Refresh; show your recorded vote. |
+| `NOT_INITIATOR` | 403 | Only the initiator or an admin can cancel. | Hide the cancel control. |
+
+### Reconciling a stuck transfer
+
+`POST /transfers/{id}/reconcile`, admin only. For a transfer left in `pending` because the worker died mid-execution — cancel does not reach those, it requires `awaiting_approval`.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `TRANSFER_STILL_EXECUTING` | 409 | The transfer entered `pending` less than 10 minutes ago. | **This is "wait", not "no".** Execution may still be in flight; intervening now risks a second broadcast. Back off and offer the action again after the window. See [Easily confused](#easily-confused). |
+| `TRANSFER_NOT_STUCK` | 409 | The transfer is not in `pending` at all, or was closed by another path while you were reconciling. | Re-read it. It resolved itself; nothing to do. |
+| `RESERVE_ALREADY_CONSUMED` | 409 | You asked to return the reserve, but a `confirm` posting has already spent it — the transaction went to the network. | **Never retry as a release.** The money left. Finish the transfer by supplying its `txHash` instead. |
+
+### Not error codes, though they look like them
+
+Two sets of uppercase strings travel inside **successful** bodies and will mislead anyone grepping for codes:
+
+- **`applyError` on a 200 vote response** — `STALE`, `APPLY_FAILED`, `APPLY_FAILED_ROLLED_BACK`, `APPLY_FAILED_PARTIAL`, `TRANSFER_EXECUTION_FAILED`. The vote itself succeeded and the request reached its final status; what failed was applying the approved change. No exception is thrown, so you must read this field. `TRANSFER_EXECUTION_FAILED` in particular means the approval went through and the transfer then failed — the reserve has been returned.
+- **Policy `reason` strings** inside `POLICY_DENIED`'s `details`, and `observations[].code` in report bodies. The first are author-defined — an administrator writes `DAILY_LIMIT_EXCEEDED` or `AMOUNT_EXCEEDED` into a policy by hand, so the set is open and unstable. The second are report findings, not failures. Do not branch on either as if it were an error code.
+
+  The observation set, unlike the policy reasons, is closed, and it is all nine of these — each with a `severity` of `info` or `warning`, which is the field to drive presentation from:
+
+  | Code | Severity | Raised when |
+  |---|---|---|
+  | `COUNTERPARTY_TURNOVER_INCREASED` | info | USD turnover is up 30% or more on the previous period |
+  | `COUNTERPARTY_TURNOVER_DECREASED` | info | USD turnover is down 30% or more |
+  | `AVERAGE_PAYMENT_INCREASED` | info | The average operation is up 50% or more |
+  | `SINGLE_OPERATION_CONCENTRATION` | warning | One operation is 50% or more of the period's USD turnover |
+  | `SINGLE_ADDRESS_CONCENTRATION` | info | One address is 70% or more of it |
+  | `UNMATCHED_OPERATIONS_PRESENT` | warning | Operations in the period have no counterparty |
+  | `UNCATEGORIZED_OPERATIONS_PRESENT` | info | Operations in the period carry no category |
+  | `OPERATIONS_WITHOUT_USD_RATE` | warning | Operations had no rate, so they are missing from the USD totals |
+  | `PENDING_OPERATIONS_AGED` | warning | Something has been `pending` or `awaiting_approval` for over 6 hours |
+
+  The thresholds are server-side configuration, so treat the numbers above as today's values rather than part of the contract. Each observation also carries `drilldownFilters`, naming what the finding was computed over — but only some of those keys are ones the drill-down endpoint actually reads (`statuses` is; the singular `addressId` and `operationKey` are not), so forwarding the object wholesale widens the resulting list instead of narrowing it, and does so without an error.
+
+## Addresses
+
+`POST /addresses` and the address listing.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `CONCURRENCY_CONFLICT` | 409 | A unique derivation index could not be allocated after 3 attempts — too many simultaneous creations. | **Retry.** This is the one conflict here where a plain retry is the correct answer. |
+| `NETWORK_NOT_IN_VAULT` | 400 | The network is not connected to this vault. | Offer only the vault's own networks. Terminal otherwise. |
+| `INVALID_SEGMENT` | 400 | A derivation-path segment is missing, unknown, or disabled. | A client bug or a stale form: re-read the vault's route configuration and rebuild the form. |
+| `GROUP_CREATE_FORBIDDEN` | 403 | You passed a `groupId` for a folder you may not create addresses in. | Create the address outside the folder, or ask the folder's creator. |
+| `FORBIDDEN_SCOPE` | 403 | You passed `?userId=` for somebody other than yourself, and you are not an admin. | A client bug. Drop the parameter. |
+| `MONITORING_FAILED` | 502 | The address was created and then rolled back because it could not be registered for chain monitoring. | Nothing was kept. Retry; if it persists, an upstream service is down. |
+| `WALLET_SERVICE_ERROR` | 502 | The signing service did not return an address. | Retry. Nothing was created. |
+| `VAULT_NOT_FOUND` | 404 | The vault code does not resolve. | A client bug or a deleted vault. |
+| `VAULT_HAS_NO_WALLET_SERVICE` | 500 | No `walletServiceUrl` on the vault. | Configuration fault. Contact an administrator. |
+| `NO_DYNAMIC_ROUTE` | 500 | The vault's derivation scheme has no incrementing segment. | Configuration fault — address creation is impossible in this vault until an admin fixes it. |
+| `TOKEN_NOT_REGISTERED` | 500 | An asset segment points at a token missing from the registry. | Configuration fault. Contact an administrator. |
+| `POLICY_DENIED` | 403 | `block`, or no policy permits `create_address`. `details` holds the decision. | Terminal. Show `message`. |
+
+Address creation that requires signatures is **not** an error: the server answers **202** with `{status:"awaiting_approval", approvalRequestId, approvalThreshold}`. Nothing is thrown. (`POLICY_REQUIRES_APPROVAL` exists in the server's type but is never sent — see [Declared but never returned](#declared-but-never-returned).)
+
+## Grants and sharing
+
+Address shares, folder shares, member-visibility grants. All grant `POST`s are idempotent: repeating a pair changes the rights, and a revoked grant is reactivated. There is no `GRANT_EXISTS` anywhere.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `SUBJECT_REQUIRED` | 400 | A **member-visibility** grant with `subjectType:"user"` and no `subjectUserId`, or `"group"` and no `subjectGroupId`. Only that endpoint reports the omission under this code — see below. | A client bug. |
+| `TARGET_REQUIRED` | 400 | A visibility grant with `scope:"group"` and no `targetGroupId`. | A client bug. |
+| `SELF_SHARE` | 400 | You tried to share something with yourself. | Filter yourself out of the recipient picker. |
+| `OWNER_SUBJECT` | 400 | The recipient already owns the object; a grant would add nothing. | Filter the owner out of the picker. |
+| `NOT_MEMBER` | 404 | The user is not a member of this vault. | They must be invited to the vault first. Terminal for a grant. |
+| `NOT_VISIBLE` | 403 | The user **is** a member, but is not visible to you, so you cannot name them as a recipient. | Different remedy from `NOT_MEMBER`: ask an admin for a visibility grant. See [Easily confused](#easily-confused). |
+| `GROUP_NOT_FOUND` | 404 | The subject group is not a policy group of this vault. | Refresh the group list. |
+| `NOT_OWNER` | 403 | Only the address owner (or an admin) may share it or manage its grants. | Hide the share controls. Terminal. |
+| `NOT_MANAGER` | **403 or 404** | 403: you are not the folder's creator. 404: the folder does not exist. The code is the same for both. | Use `status` to tell them apart. 404 → refresh the folder list; 403 → hide the control. |
+| `NOT_FOLDER_MANAGER` | 403 | Only the folder's creator changes its contents. | Terminal. Ask the creator. |
+| `NOT_ADDRESS_OWNER` | 403 | You manage the folder, but the address you are adding is not yours — putting it in a shared folder would widen access to it behind its owner's back. | Terminal, and deliberately so. Only the address's own owner can add it. |
+| `ALREADY_MEMBER` | 409 | The address is already in the folder. | Benign. Treat as success and refresh. |
+| `GROUP_NAME_CONFLICT` | 409 | You already have a folder with that name (names are unique per owner, not per vault). | Ask for a different name. |
+| `ACCESS_VIA_GROUP` | 409 | You tried to remove your own access, but it comes from a user group, not a personal grant. `details` has `{groupId, groupName}`. | Explain it with the group name from `details`: the user must leave the group, or an admin must revoke the group's grant. |
+| `NOT_YOURS` | 403 | You tried to remove someone else's grant via the "remove me" endpoint. | A client bug. Revoking another person's access is the object owner's prerogative. |
+| `FORBIDDEN` | 403 | Generic refusal when removing an address from a folder. | Terminal. |
+
+### One omitted subject id, three different answers
+
+Naming a `subjectType` and forgetting the matching id is the same client bug everywhere, and each of the three grant endpoints reports it differently. Nothing in the shapes hints at this, so it is worth having in one place:
+
+| Endpoint | `subjectType:"user"`, no `subjectUserId` | `subjectType:"group"`, no `subjectGroupId` |
+|---|---|---|
+| `POST …/visibility-grants` | `SUBJECT_REQUIRED`, **400** | `SUBJECT_REQUIRED`, **400** |
+| `POST …/addresses/{id}/shares` (single subject) | `SUBJECT_REQUIRED`, **403** | `GROUP_NOT_FOUND`, **403** |
+| `POST …/address-folders/{id}/grants` (single subject) | `BAD_REQUEST`, 400 | `BAD_REQUEST`, 400 |
+
+Why they differ, since it explains which to expect elsewhere:
+
+- the folder endpoint's body schema requires the pairing, so the request is a schema failure and never reaches a handler — hence a validation `BAD_REQUEST` and no domain code;
+- the address-share schema does not, so the request reaches the shared subject validator. For `"group"` that validator looks the group up by an empty id and misses, which is why the mistake surfaces as `GROUP_NOT_FOUND` rather than as a missing subject;
+- the **status** on that endpoint is hard-coded to 403 for every per-subject refusal (see below), so neither of its codes arrives with the status its meaning suggests.
+
+In the `subjects[]` batch form of either endpoint the pairing *is* enforced by the schema, so there a missing id is always a 400 `BAD_REQUEST` for the whole request — one bad entry does reject the rest, which is the single exception to the independence the batch form otherwise guarantees.
+
+### Batch sharing needs item-by-item handling
+
+Sharing one address accepts a `subjects[]` array, and each recipient is processed **independently** — one rejection must not cancel the rest.
+
+- If **at least one** grant was created or changed, the status is **201** and the body is `{results:[…]}`. **No exception is thrown.** Walk `results` and read `ok`, `outcome` (`created` / `updated` / `reactivated`) and `error` per item.
+- If **every** item failed, the status is **400** with the same `{results:[…]}` body. There is no `error` key, so the envelope never touches it: you get `code: "BAD_REQUEST"` and the whole body in `details`. Read `details.results` for the real per-subject codes.
+
+  The API's document describes this as the second of two forms that 400 takes — the ordinary envelope for a body that failed validation, and `ShareBatchAllRejected` for a batch in which every recipient was refused — so there is a type for the cast:
+
+  ```ts
+  import { isCoreError, type ShareBatchAllRejected } from '@v3finance/core-sdk'
+
+  try {
+    await client.vault('acme').sharing.share(addressId, { subjects, role: 'viewer' })
+  } catch (e) {
+    if (!isCoreError(e) || e.status !== 400) throw e
+    const refused = (e.details as ShareBatchAllRejected | undefined)?.results
+    if (!refused) throw e // the other 400: the body did not match the schema
+    for (const item of refused) report(item.subjectUserId ?? item.subjectGroupId, item.error.code)
+  }
+  ```
+
+  `details` is `unknown`, so this is an assertion, not a check: the `results` test on the next line is what tells the two 400s apart. A validation failure carries no `details` at all.
+- Inside a `results` item, `error.message` **equals** `error.code`. Never show it to a person; map the code to your own wording.
+
+In the single-subject form the per-subject code is returned as a normal error — but when sharing **one address**, the status is hard-coded to **403** regardless of the code, so a `NOT_MEMBER` arrives as 403 there and as 404 from the folder endpoint. Branch on `code`, not `status`.
+
+## Approvals and voting
+
+`/approval-requests` — the generic engine behind transfers, counterparty changes, address creation and category edits.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `NOT_FOUND` | 404 | No such request in this vault. | Refresh the list. |
+| `NOT_PENDING` | 409 | The request is already `APPROVED` / `REJECTED` / `CANCELLED`. Voting is over. | Refresh and show the final status. Expected under concurrency; not worth an alert. |
+| `NOT_APPROVER` | 403 | You are not in the approver snapshot. The snapshot is frozen at creation — later policy or group edits do not add you. | Hide the controls for this request. Terminal. |
+| `ALREADY_VOTED` | 409 | One vote per person, already cast. | Refresh; show your vote. |
+| `NOT_INITIATOR` | 403 | Only the initiator or an admin can cancel. | Hide the cancel control. |
+| `UNSATISFIABLE` | 409 | The request cannot be created: a step has fewer eligible approvers than its threshold, or every step is auto-approved so no request is needed. | **Do not retry.** An administrator has to fix the policy. Same situation as `APPROVAL_UNSATISFIABLE` on a transfer. |
+| `DB_REQUIRED` | 500 | A money-path request was handled without the database binding. Deliberately fail-closed, so no reserve is left locked. | Infrastructure fault. Nothing the user can do; escalate. |
+| `POLICY_DENIED` | 403 | No policy permits one of the steps. `message` is prefixed `Step N (action): …`. | Terminal. The step index is in `details.stepIndex`; the prefix in `message` is for display, not for parsing. |
+| `POLICY_BLOCKED` | 403 | A `block` policy matched one of the steps. | Terminal. Show `message` — it names the policy and the reason. |
+| `CHAIN_FAILED_ROLLED_BACK` | 400 | A composite chain that needed no signatures failed partway and **was** rolled back. | Nothing was kept. Fix the cause from `message` and resubmit. |
+| `CHAIN_FAILED_PARTIAL` | 400 | Same, but the rollback did **not** fully succeed. | **Do not resubmit.** Some steps are applied. Re-read the affected objects and reconcile, or escalate. |
+
+## Annotation categories
+
+Category schema management (admin) and value assignment (anyone with the right).
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `CATEGORY_NOT_FOUND` | 404 | No such category in this vault — but only from the paths that **write values**: assigning, editing an assignment, and the apply of an approved `category_assign` / `category_edit`. The value writer is the one place that raises it. | Refresh the category list. |
+| `CATEGORY_ARCHIVED` | 400 | The category is archived and takes no new assignments. | Remove it from the picker. |
+| `CATEGORY_APPLIES_TO` | 400 | The category applies to transfers only, or deposits only, and you used it on the other kind. | Filter the picker by operation type. |
+| `CATEGORY_ALREADY_ASSIGNED` | 409 | This category is already on this operation. | Switch to `PATCH` to edit the existing assignment. |
+| `CATEGORY_FORBIDDEN` | 403 | You lack `view` / `assign` / `edit` on this category — or lack the matching access on the operation's address. | Show the fields as read-only, or hide them. Terminal; the remedy is a category grant or address access. |
+| `ASSIGNMENT_STALE` | 409 | Optimistic lock: the assignment changed since you loaded it. | **Re-read, merge, resubmit.** The canonical refresh-and-retry case. Do not resend the same `expectVersion`. |
+| `CATEGORY_KEY_CONFLICT` | 409 | A category with that key already exists. Keys are immutable once created. | Ask for a different key. |
+| `CATEGORY_FIELD_CONFLICT` | 409 | A field with that key already exists on the category. | Ask for a different key. |
+| `CATEGORY_FIELD_DUPLICATE` | 400 | The request body repeats a field key. | A client bug. |
+| `CATEGORY_FIELD_UNKNOWN` | 400 | You wrote a value for a field the category does not have. | Re-read the category schema; your copy is stale. |
+| `CATEGORY_FIELD_ARCHIVED` | 400 | You wrote to an archived field. | Drop it from the form. |
+| `CATEGORY_FIELD_REQUIRED` | 400 | A required field has no value. | Normal form validation. The field key is in `details.field` (and in `message`). |
+| `CATEGORY_FIELD_TYPE` | 400 | A value does not match the field's type, or a field config is invalid (`scale` outside 0–18, `scale` on a non-numeric field, `options` on a non-select field). | Fix client-side. The field key is in `details.field`, and in `message` too — bind the form error from `details`. |
+| `CATEGORY_FIELD_OPTION` | 400 | A select value is not among the options, or the options list is empty or has duplicates. | Re-read the schema and rebuild the options. |
+| `CATEGORY_FIELD_LINK` | 400 | A `currencyFieldKey` is wrong: on a non-currency field, pointing at itself, at a missing field, or at a field that is not `select`/`text`. | An admin-side configuration fix. |
+| `CATEGORY_APPROVAL_CONFIG` | 400 | `approvalScope` is not `none` but no `approvalThreshold` was given. | A client bug: the two fields must be set together. |
+| `CATEGORY_GRANT_SUBJECT` | 400 / 404 | The grant subject is missing (400) or is not a member / group of this vault (404). | Use `status` to distinguish. 404 → refresh the directory. |
+| `CATEGORY_APPROVER_SUBJECT` | 404 | The named approver user or group does not exist. | Refresh the directory; the id is stale. |
+
+The **schema** endpoints under `/operation-categories` — reading a category, patching it, adding or archiving a field, managing grants and approvers — do not use `CATEGORY_NOT_FOUND` for a category that does not resolve. They answer a plain 404, so you get the status-derived `NOT_FOUND`, and the same goes for a missing field. Reaching for `CATEGORY_NOT_FOUND` to drive "this category is gone, reload the schema" therefore only works on the value paths; branch on `status === 404` if you need it on both.
+
+Editing a value in a category that requires approval is **not** an error: you get **202** with the created request. The approval condition lives on the category itself, not in the policy engine.
+
+Category keys and field keys and types are **immutable** after creation, and anything with history can only be archived. There is no error code for attempting otherwise — the API simply has no endpoint for it.
+
+## Counterparties
+
+Note the statuses: conflicts in this domain answer **400**, not 409.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `NAME_TAKEN` | 400 | A counterparty with that name already exists in the vault. | Ask for a different name. |
+| `ADDRESS_TAKEN` | 400 | One of the addresses already belongs to another counterparty here. `message` names it when it can be resolved. | Show which address collides; the user must remove it from the other counterparty first. |
+| `NETWORK_NOT_REGISTERED` | 400 | An address names a network missing from the registry. `message` lists them. | Terminal for a non-admin: an administrator must register the network. |
+| `VALIDATION` | 400 | A required field (`name`, `address`, `code`) is empty after trimming. | Normal form validation. |
+| `CODE_TAKEN` | 400 | A counterparty **group** with that code already exists in the vault. | Ask for a different code. |
+| `ALREADY_MEMBER` | 400 | The counterparty is already in the group. | Benign. Treat as success and refresh. |
+| `NOT_FOUND` | 404 | The counterparty or group does not exist in this vault. | Refresh. (Arrives as a status-derived `NOT_FOUND` — see [Declared but never returned](#declared-but-never-returned).) |
+
+Changing a group's membership is scoped to its own vault, and that is checked at the write, including when it arrives via an approved request. A cross-vault attempt fails as a plain 404, not with a distinct code.
+
+Group membership also gates destination whitelists: archiving a counterparty group revokes the whitelist it backs, because membership resolves over non-archived groups only. There is no error for this — transfers simply start being denied with `POLICY_DENIED`.
+
+## Operation metadata and relations
+
+One domain code lives here — the metadata, link and status-history endpoints have none of their own and refuse with plain statuses.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `OPERATION_RELATION_INVALID` | 422 | The relation itself does not make sense: it points an operation at itself, or it carries a `relatedAmountRaw` without the `tokenId` that amount is denominated in, or that `tokenId` is not in the registry. | Fix client-side; `message` says which of the three. A partial amount is meaningless without its token, so send the pair or neither. |
+
+What is **not** an invalid relation, though it is easy to read as one: if you may not touch either operation, the answer is a plain 404 (`NOT_FOUND`) naming neither side — deliberately, so the existence of an operation you cannot see is not disclosed. Writing a relation needs the `transfer` right on both, not `view`, because access to an operation and the right to annotate it are separate rights. So a viewer gets that 404 for an operation they can read perfectly well, and the fix is a `contributor` grant, not a different payload.
+
+## Reports
+
+Reporting endpoints use their own envelope with `REPORT_*` codes. `details` is present but frequently `{}`.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `REPORT_INVALID_PERIOD` | 400 | `from >= to`, an unparseable date, an invalid IANA timezone, a bad `at`, or `from`/`to` missing for a type that needs them. | Fix the parameters. `message` says which. |
+| `REPORT_PERIOD_TOO_LARGE` | 400 | The period exceeds 1100 days — or, on a snapshot, the result exceeded ~900 KB. | Narrow the period or the filters, then retry. Same code, two causes; `message` distinguishes them. |
+| `REPORT_INVALID_GROUPING` | 400 | `groupBy=day` over a period longer than 400 days. | Switch to `week` or `month` and retry. |
+| `REPORT_INVALID_PARAMS` | 400 | A parameter the chosen report type requires is missing. `details.param` names it — but only where exactly one parameter is at fault (`counterpartyId`, `counterpartyGroupId`, `tokenId`, `categoryKey`). `address_activity` wants `addressId` **or** `folderId`, and that branch sends `details: {}`, leaving `message` as the only source. | Read `details.param` when it is there and fall back to `message`; do not build the form error from `details.param` alone. |
+| `REPORT_UNSUPPORTED_FORMAT` | 400 | Either an unknown report type, or an export format that does not exist yet (`xlsx`, `pdf`). | For the format case, fall back to `json` or `csv` — it will not start working on retry. |
+| `REPORT_FORBIDDEN_SCOPE` | 403 | You asked for another user's scope, for a snapshot that is not yours, or tried to create a shared template without being an admin. | Drop the parameter, or contact an admin. Terminal. |
+| `REPORT_ADDRESS_NOT_FOUND`, `REPORT_FOLDER_NOT_FOUND`, `REPORT_TOKEN_NOT_FOUND`, `REPORT_COUNTERPARTY_NOT_FOUND`, `REPORT_COUNTERPARTY_GROUP_NOT_FOUND` | 404 | The filter target does not exist, or is outside your scope — the two are not distinguished, on purpose. | Refresh the relevant list. Do not conclude the object was deleted. |
+| `REPORT_SNAPSHOT_NOT_FOUND` | 404 | No such snapshot, or it is not yours. | Refresh the list. |
+| `REPORT_SNAPSHOT_NOT_READY` | 409 | The snapshot exists but its status is not `completed`. | Poll; then export. A wait, not a failure. |
+| `REPORT_EXPORT_NOT_FOUND` | 404 | No such export, it is not yours, or its content is gone. | Request the export again. |
+| `REPORT_DATA_INCONSISTENT` | 500 | **The catch-all** for any unexpected failure during report generation — despite the name, it does not specifically mean the data is inconsistent. | Treat as a server fault: retry once, then report it with the endpoint, the parameters and the time. `message` is the constant `Report generation failed` — the driver text behind it stays in the worker log by design, so there is nothing diagnostic to forward. |
+
+The export **download** endpoint streams a file rather than JSON. Errors from it still arrive as a normal envelope; successes do not, so read them with the raw-response path, not as JSON.
+
+## Profile, seats and invitations
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `USERNAME_TAKEN` | 409 | Usernames are unique globally. | Ask for another. |
+| `INVALID_EMAIL` | 400 | The address is malformed, or is itself a seat placeholder address. | Normal form validation. |
+| `EMAIL_TAKEN` | 409 | Another account already uses that address. | Ask for another, or point the user at signing in with it. |
+| `NOT_A_SEAT` | 409 | The account already has a real email. This endpoint binds a first address to a seat account; it is **not** a change-email endpoint, because changing an address without a confirmation loop is account takeover. | Terminal. Changing an existing address needs a separate, confirmed flow. |
+| `INVITATION_NOT_FOUND` | 404 | No pending invitation for that email. | The user needs a new invitation from an admin. |
+| `USER_ALREADY_LINKED` | 400 | The account is already attached to an invitation. | Benign under retries. Treat as already-done. |
+
+The public invitation lookup (`GET /invitations/by-token/{token}`) signals a dead link with **410** and no domain code — you get `REQUEST_FAILED`. Both "revoked" and "already accepted" come back that way, distinguishable only by `message`. Branch on `status === 410` and tell the user the link is no longer usable.
+
+## AML
+
+`GET /aml/score`, and risk as a policy condition.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `AML_ADDRESS_UNRECOGNISED` | 400 | The address format matches no supported network (TRON `T`+33, Ethereum `0x`+40). `details.address` echoes it. | Normal validation. Do not call the endpoint for addresses you cannot classify. |
+| `AML_UNAVAILABLE` | 502 | The provider timed out, returned an error, or no API key is configured. `details.providerStatus` carries the upstream status. | **Show "could not check", never a clean result.** The status is always 502 regardless of what the provider returned — read `details.providerStatus` if you need the real one. Retrying immediately rarely helps; a successful answer is cached for 24 h. |
+
+Two rules the API enforces and your interface has to mirror:
+
+- **`amlLevel: null` means "not checked", not "no risk".** A green badge on an unchecked address misleads someone about money. Render the unknown state distinctly.
+- **The level stored on an operation is a snapshot** taken when the operation was created, not live. A request waiting for signatures never re-checks. If you need the current value, call `/aml/score` separately and label it as current.
+
+A risk threshold in a policy is expressed as a **level**, not a numeric score, and unknown counts as a match by default — a provider outage must not silently remove a control.
+
+## Authentication and access
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `UNAUTHENTICATED` | 401 | No session, or the token expired. | Sign out and route to login. The client's `onUnauthorized` hook fires first for every 401. |
+| `FORBIDDEN` | 403 | Admin-only endpoint, or you are not a member of this vault. | Terminal. Hide the surface rather than letting the user hit it. |
+| `BAD_REQUEST` | 400 | Either a schema validation failure (see above), or a vault code missing from the path. | Read `message`. |
+
+`/api/auth/*` is the auth library's own namespace. It answers with a flat `{code, message}` that the API's envelope does not rewrite; `CoreError` reads it, so `code` is populated, but the values come from that library and are not part of this API's contract. Do not branch on a fixed list there — branch on `status`, and show `message`.
+
+Rate limiting is not implemented in the API itself. A 429 therefore comes from the platform in front of it, usually without a JSON body, which means `code: "RATE_LIMITED"` and no `details`. Back off and retry.
+
+## Easily confused
+
+**`APPROVAL_UNSATISFIABLE` / `UNSATISFIABLE` is not a transient conflict.** It is a 409, and 409s are usually worth a retry. This one never is: it means the policy demands more signatures than there are people able to give them, so every retry fails identically. The only resolution is an administrator changing the policy or the approver group. Say that, and do not offer a retry button. On a transfer, the reserve has already been returned when you see this, so no funds are stuck.
+
+**`TRANSFER_STILL_EXECUTING` means "wait", not "no".** The transfer went into `pending` less than 10 minutes ago and execution may still be in flight. The server refuses on purpose: intervening could cause a **second broadcast**, which is far more expensive than waiting. Do not surface it as a failure, do not loop on it — back off past the window and offer the action again.
+
+**`RESERVE_ALREADY_CONSUMED` means the money left.** It appears when a release is attempted over a transfer whose reserve was already spent by a `confirm` posting. Idempotency does not protect you here: confirm and release are different keys that draw on the same balance, so a release layered on a completed confirm would create money out of nothing. The correct next step is always to finish the transfer by its `txHash`, never to retry the release.
+
+**`CONCURRENCY_CONFLICT` on address creation is the opposite of the above: retry it.** It means the server could not allocate a unique derivation index because other creations were racing it. Nothing was created, nothing is half-done, and the next attempt will usually succeed. Make this the one 409 in the SDK you retry automatically.
+
+**`NOT_VISIBLE` is not `NOT_MEMBER`.** `NOT_MEMBER` (404) means the person is not in the vault — they need an invitation. `NOT_VISIBLE` (403) means they **are** in the vault but you cannot see them, so you cannot name them as a grant recipient. The remedy is a visibility grant from an administrator. Visibility is default-deny — you see only yourself until granted — so `NOT_VISIBLE` is the common failure when sharing is first rolled out, and reporting it as "no such user" sends people hunting for a problem that does not exist.
+
+**`NOT_MANAGER` carries two different situations under one code**, 403 (not the folder's creator) and 404 (no such folder). Switch on `status`.
+
+**Validation errors carry no code.** A 400 with `code: "BAD_REQUEST"` is almost always a schema failure, and `message` is the only detail you get. Do not write a `case 'BAD_REQUEST'` branch expecting a domain meaning.
+
+**`message` is sometimes just the code.** Inside a batch `results` item, `error.message` is set to `error.code`. `CoreError` already guards against this for top-level errors — it substitutes a neutral message when the server's `message` equals its `code` — but inside a `results` array you are reading raw JSON. Map codes to your own wording there.
+
+**A 401 does not always carry the same code.** This API's own middleware sends `UNAUTHENTICATED`, and so does the SDK when a 401 arrives without a code of its own — but `/api/auth/*` is served by the authentication library and sends whatever it sends. **Branch on `status === 401`**, which is also what the `onUnauthorized` hook does for you.
+
+**`details` is not always there, and its shape varies by code.** It is typed `unknown`. Narrow it before reading. Reporting endpoints send `{}` more often than anything.
+
+## Timeouts on money paths
+
+The default timeout is 60 seconds, because `POST /transfers` executes inline: it provisions gas, waits for propagation, then broadcasts. A timeout there does **not** mean nothing happened — it means you do not know what happened.
+
+**Retry a timed-out transfer only with the same `idempotencyKey`.** A new key is a new transfer, and you will send the money twice.
+
+**The key is read from the request BODY, not from a header.** `transfers.send` puts it in the body, which is what protects it. The low-level `request()` helper still accepts an `idempotencyKey` option for source compatibility, but the transport now sends it **nowhere** and the option is deprecated: calling a money endpoint through the low-level client with the key only in the options buys you nothing, and a retry after a timeout sends the money twice.
+
+It used to leave as an `idempotency-key` header, which was worse than useless. The API's CORS preflight allows exactly `Content-Type` and `Authorization`, so in a browser the extra header failed the preflight and the request was never sent — a money call that could not reach the server, surfacing as a network error that no retry explains. In Node it was merely ignored.
+
+```ts
+const key = crypto.randomUUID()           // one key per intended transfer
+
+async function send() {
+  return client.vault('acme').transfers.send({
+    fromAddressId, toAddress, amount, asset,
+    idempotencyKey: key,                   // in the body
+  })
+}
+
+let result
+try {
+  result = await send()
+} catch (e) {
+  if (isCoreError(e) && (e.kind === 'timeout' || e.kind === 'network' || e.kind === 'aborted')) {
+    result = await send()                  // SAME key — a replay, not a second transfer
+  } else throw e
+}
+
+if (result.outcome === 'replayed') showAlreadySent(result.data)
+else if (result.outcome === 'pending') showAwaitingApproval(result.data)
+else showSent(result.data)
+```
+
+Rules that follow from how the server handles the key:
+
+- **The key is reserved before any external call.** A replay is therefore recognised even if the first attempt died mid-broadcast. The server answers **200** and does not broadcast again; the SDK labels that `outcome: 'replayed'`.
+- **Tell "replayed" apart from "sent".** A replay means the earlier attempt did reach the server and only the answer was lost. Say "already sent", not "sent" a second time.
+- **A new key after a `failed` or `rejected` transfer.** The old key is bound to that row, and reusing it returns the dead transfer instead of sending a new one.
+- **No key sent, and a timeout?** Do **not** retry. Fetch the transfer list or the operation history first and establish whether the transfer exists. Make the SDK's own callers always pass a key so this situation cannot arise.
+- **`network` and `aborted` carry the same uncertainty as `timeout`** on money paths. The request may have been received and executed; only the response was lost. Treat all three identically: same key, or verify first.
+- **A thrown `GAS_STATION_FAILED` or `WALLET_SERVICE_ERROR` is different.** Those are definite: the transfer is `failed` and the reserve has been returned. Retry those with a **new** key.
+- **Nothing a client does can leave funds locked.** Every failure path either returns the reserve or leaves a `pending` transfer that an admin can reconcile. Timeouts are a reporting problem, not a custody one — but a double send is permanent, so the key matters more than the retry.
+
+## Declared but never returned
+
+These codes exist on the server and never reach a client. Most are simply never constructed; two are constructed but cannot get out — one sits behind a middleware that answers first, the other has its code stripped on the way. Either way, do not write handling for them. If one ever does appear, the server changed.
+
+| Code | Where it is declared | What happens instead |
+|---|---|---|
+| `POLICY_REQUIRES_APPROVAL` | Address creation errors | A **202** with `{status:"awaiting_approval", approvalRequestId, approvalThreshold}`. Not an error at all. |
+| `STALE` | Approval-request errors | Only ever arrives as `applyError.code` inside a **200** vote response. Never thrown. |
+| `NOT_FOUND` (counterparty) | Counterparty errors | The handlers return a plain 404, so you still receive `code: "NOT_FOUND"` — derived from the status rather than sent. Behaviour is identical; the declaration is dead. |
+| `ASSIGNMENT_NOT_FOUND` | Category assignment errors | A plain 404 with the status-derived `NOT_FOUND`. |
+| `REPORT_VAULT_NOT_FOUND` | Report errors, and one report handler does build it | Every report endpoint sits behind the vault-membership middleware, which resolves the vault first and answers its own 404 — so the handler's check cannot be the one that fires. You get the status-derived `NOT_FOUND`, with the middleware's `Vault "x" not found` as the message. |
+| `STEP_REF_UNRESOLVED` | Approval-request error codes | It is raised, but only inside the composite-chain runner, when a `$step:N` reference names a step that has no result yet. The runner's `catch` keeps the sentence and drops the code, so what leaves is `CHAIN_FAILED_ROLLED_BACK` or `CHAIN_FAILED_PARTIAL` with that sentence inside `message`. Handle those; `hasCode(e, 'STEP_REF_UNRESOLVED')` is never true. |
+
+Two further codes are reachable only through server misconfiguration and are worth knowing so you classify them correctly rather than showing them to a user: `DB_REQUIRED` (500, a money path reached without its database binding — fail-closed, nothing is left locked) and `VAULT_HAS_NO_WALLET_SERVICE` / `NO_DYNAMIC_ROUTE` / `TOKEN_NOT_REGISTERED` (500, vault configuration gaps that make transfers or address creation impossible until an administrator fixes them).
+
+**Conditions I could not pin down:** `TRANSFER_NOT_EXECUTABLE` is thrown from several places with three different statuses (404 when the transfer is missing, 409 when it is not `pending`, 500 when its execution context fails to load), so apart from "re-read the transfer and trust its status" there is no single client action that fits all of them. `APPROVAL_FAILED` is the fallback for any approval-request creation failure that is not `UNSATISFIABLE`; which failures reach it is not evident from the code, so "retry once with a new key, then escalate" is the honest guidance rather than a specific cause.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@v3finance/core-sdk",
-  "version": "0.1.0",
-  "description": "The official TypeScript SDK for the V3 Finance Core API — custodial addresses, transfers, policies and approvals",
+  "version": "0.2.0",
+  "description": "The official TypeScript SDK for the V3 Finance Core API — custodial addresses, transfers under policy control, approvals, shared access, labelling and reports",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "src",
+    "docs",
     "CHANGELOG.md"
   ],
   "main": "./dist/cjs/index.js",
@@ -48,13 +49,13 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "spec:update": "node scripts/fetch-spec.ts",
-    "generate": "node scripts/generate.ts",
-    "generate:check": "node scripts/generate.ts --check",
+    "spec:update": "node --experimental-strip-types scripts/fetch-spec.ts",
+    "generate": "node --experimental-strip-types scripts/generate.ts",
+    "generate:check": "node --experimental-strip-types scripts/generate.ts --check",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.build.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "build": "node scripts/build.ts",
+    "build": "node --experimental-strip-types scripts/build.ts",
     "preversion": "node scripts/sync-version.mjs",
     "version": "node scripts/sync-version.mjs && git add src/version.ts",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"