@v3finance/core-sdk 0.1.0 → 0.2.0

package/README.md

@@ -5,25 +5,43 @@
 [![types](https://img.shields.io/npm/types/@v3finance/core-sdk.svg)](https://www.npmjs.com/package/@v3finance/core-sdk)
 [![license](https://img.shields.io/npm/l/@v3finance/core-sdk.svg)](./LICENSE)
 
-The official TypeScript SDK for the V3 Finance Core API.
-Custodial addresses, transfers under policy control, approvals and shared access.
-
-- **Vault scoping** that carries no state: `core.vault(code)` is an expression, so two vaults work side by side.
-- **Policy-aware results**: a transfer either executes, waits for signatures or replays — told apart by status, not guesswork.
-- **Money that cannot silently lose precision**: smallest-unit strings and BigInt arithmetic, with no `toNumber`.
-- **Pluggable authentication**: browser cookie, native cookie jar or bearer token — you supply headers, the SDK hands events back.
-- **Complete**: every endpoint of the API, grouped into resources, with the administrative surface marked.
-- **Fully typed**, zero dependencies, ESM and CommonJS. Runs on Node.js, Bun, Deno, Cloudflare Workers and React Native.
-
-The whole API is covered: addresses and transfers, approvals, counterparties, shared access and
-folders, operation labelling, reports, and the administrative surface. A test asserts that every
-endpoint is reachable through some resource, so an endpoint added to the API shows up as a failure
-rather than as a gap nobody noticed.
-
-Two endpoints are deliberately absent: `/welcome` is a browser landing page the API redirects to,
-and `/webhooks/wallet` is the inbound channel for the wallet service.
-
-## Install
+The official TypeScript SDK for the V3 Finance Core API — custodial addresses, transfers under
+policy control, approvals, shared access, operation labelling and reports.
+
+- **Complete.** Every endpoint a client calls — 157 of the API's 171 operations, grouped into
+  resources, with the administrative surface marked. The fourteen left out are named under
+  [Resources](#resources). A test asserts that each of the rest is reachable, so an endpoint added
+  to the API shows up as a build failure rather than as a gap nobody noticed.
+- **Honest about approvals.** An operation can be applied, queued for signatures or replayed, and
+  the response bodies are identical — the SDK tells them apart, so your interface does not report
+  "sent" when the funds are merely reserved.
+- **Money that cannot silently lose precision.** Smallest-unit strings and BigInt arithmetic, with
+  no `toNumber`.
+- **Pluggable authentication.** Browser cookie, native cookie jar or bearer token; the package
+  stores no credentials.
+- **Fully typed, zero dependencies**, ESM and CommonJS. Runs on Node.js, Bun, Deno, Cloudflare
+  Workers and React Native.
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Three things to know first](#three-things-to-know-first)
+- [Resources](#resources)
+- [Amounts](#amounts)
+- [Error handling](#error-handling)
+- [Pagination](#pagination)
+- [Administrative operations](#administrative-operations)
+- [TanStack Query](#tanstack-query)
+- [TypeScript](#typescript)
+- [Requirements](#requirements)
+- [Staying in sync with the API](#staying-in-sync-with-the-api)
+- [Further reading](#further-reading)
+- [Versioning](#versioning)
+- [License](#license)
+
+## Installation
 
 ```bash
 npm install @v3finance/core-sdk
@@ -43,23 +61,52 @@ const core = new CoreClient({
 const page = await core.vault('my-vault').addresses.list({ limit: 20 })
 ```
 
-## Three things to know before the first call
+## Configuration
+
+```ts
+new CoreClient({
+  baseUrl,          // defaults to the production API
+  getAuthHeaders,   // called before every request
+  credentials,      // 'include' in a browser served from another origin
+  onTokenRotated,   // required in bearer mode — see below
+  onUnauthorized,   // the session is gone: sign out, route to login
+  fetch,            // your own, for tests or older runtimes
+  timeoutMs,        // default 60s; money paths call out to other services
+  headers,          // added to every request
+})
+```
+
+Sign-in is a magic link sent by email, and signing up is possible only on an administrator's
+invitation. The session then travels in one of three ways:
+
+| Runtime | How |
+| --- | --- |
+| Browser | `credentials: 'include'`, cookie set by the server |
+| React Native | your own cookie jar, returned from `getAuthHeaders` |
+| Anywhere | `Authorization: Bearer <session-token>` |
+
+In bearer mode **`onTokenRotated` is required**: the server extends a session through the
+`set-auth-token` header, and a client that does not store the new token is signed out at the next
+rotation.
+
+## Three things to know first
 
 ### 1. `vault(code)` is an expression, not state
 
 ```ts
 core.vault('alpha').addresses.list()
-core.vault('beta').addresses.list()
+core.vault('beta').transfers.send(…)
 ```
 
-There is deliberately no "current vault". The code is visible on every call site, an administrator can
-work with several vaults at once, and switching the active vault at runtime cannot leave a stale scope
-pointing at the wrong one. Build a scope where you use it; do not store it.
+There is deliberately no "current vault". The code is visible at every call site, an administrator
+can work with several vaults at once, and switching the active vault at runtime cannot leave a
+stale scope pointing at the wrong one. Build a scope where you use it; do not store it.
 
 ### 2. An operation may not execute — it may go for approval
 
-Transfers and address creation run through the policy engine. The result is `Gated`, and the three
-branches **must** be distinguished: the response body is identical, only the status differs.
+Transfers, address creation and several other operations pass through the policy engine. The
+result is `Gated`, and the three branches **must** be distinguished: the response body is the same
+in all of them, only the status differs.
 
 ```ts
 const result = await core.vault(code).transfers.send({
@@ -71,41 +118,88 @@ const result = await core.vault(code).transfers.send({
 })
 
 switch (result.outcome) {
-  case 'applied':
-    return toast('Transfer sent')
-  case 'pending':
-    return toast('Awaiting signatures — the funds are reserved')
-  case 'replayed':
-    return toast('This transfer was already sent')
+  case 'applied':  return toast('Transfer sent')
+  case 'pending':  return toast('Awaiting signatures — the funds are reserved')
+  case 'replayed': return toast('This transfer was already sent')
 }
 ```
 
 Reporting "sent" on `pending` tells a person their money has gone when it is frozen.
 
-**Always pass `idempotencyKey`** and keep it until you have an answer: after a timeout it is the only
-way to retry without sending money twice.
+**Always pass `idempotencyKey`** on a transfer and keep it until you have an answer: after a
+timeout it is the only way to retry without sending money twice. The key is read from the request
+**body** — the `idempotency-key` header is not sent at all. It used to be, and in a browser it broke the
+request outright: the API's CORS preflight allows only `Content-Type` and `Authorization`.
 
 ### 3. Amounts are strings, never numbers
 
-Balances arrive in smallest units. `float64` loses precision above 2⁵³, and production balances go higher.
-
 ```ts
 import { amount, parseDecimal, format, add } from '@v3finance/core-sdk'
 
 const balance = amount(address.balance ?? '0', 6, 'usdt')
-format(balance, { withAsset: true }) // "1,500.00 USDT"
+format(balance, { withAsset: true })     // "1,500.00 USDT"
 add(balance, parseDecimal('2.5', 6))
 ```
 
-There is no `toNumber`, on purpose — it would be a convenient door into the bug this layer prevents.
+There is no `toNumber`, on purpose — it would be a convenient door into the precision loss this
+layer exists to prevent. `float64` breaks above 2⁵³ and real balances go higher.
 
 **`balance: null` is not zero.** It means the address has no ledger account yet: nothing has ever
-arrived. "No account" and "empty account" deserve different wording in an interface.
+arrived. "No account" and "empty account" deserve different wording.
+
+## Resources
+
+Scoped to a vault — `core.vault(code).…`:
+
+| Resource | What it covers |
+| --- | --- |
+| `addresses` | list, detail, create (gated), edit metadata |
+| `transfers` | send (gated), detail, vote, cancel, reconcile (admin) |
+| `history` | the unified feed of operations; direction is a filter, not an endpoint |
+| `balances` | balances, a point in time, the raw ledger |
+| `approvals` | requests, detail, vote, cancel, composite chains |
+| `counterparties`, `counterpartyGroups` | the directory and its groups — every mutation is gated |
+| `sharing` | sharing an address, participants, shared by me and with me |
+| `folders` | address folders, their grants and participants |
+| `members` | the directory, resolve by username, user groups |
+| `categories` | the labelling schema and the values on operations |
+| `operations` | metadata, links, status history, deposits, approval relations |
+| `reports` | reports, templates, snapshots, exports |
+
+At the root — `core.…`:
+
+| Resource | What it covers |
+| --- | --- |
+| `me` | profile, email binding, push tokens, allowed segments |
+| `vaults` | list, detail, create, derivation-path build and parse |
+| `registries` | networks, tokens, rates, policy preflight, AML |
+| `auth` | request a magic link |
+| `admin` | policies, policy groups, users, invitations, visibility grants, seats |
+| `health()` | liveness, no authentication |
 
-## Errors
+Fourteen of the API's 171 operations are deliberately absent. Two are not a client's business:
+`/welcome` is a browser landing page the API redirects to, and `/webhooks/wallet` is the inbound
+channel for the wallet service. The other twelve are the `/address-groups/*` paths — the older
+prefix of the endpoints `folders` already serves under `/address-folders`. One entity, two
+prefixes; see [docs/concepts.md](./docs/concepts.md#5-shared-access-roles-out-flags-in).
 
-Every failure is a `CoreError` and always carries a `code` — sent by the server or derived from the
-HTTP status. Branch on `code`, display `message`.
+## Amounts
+
+```ts
+amount(raw, decimals, asset?)      // from smallest units
+parseDecimal('1.5', 6)             // from human input; extra digits are refused, not rounded
+toDecimalString(a)                 // '1.5'
+format(a, { withAsset: true })     // '1.50 USDT', grouped by locale
+add(a, b) · sub(a, b) · compare(a, b) · isZero(a) · isNegative(a)
+```
+
+Adding different assets throws, as does adding different precision: the result would be a
+meaningless number rather than a missing one.
+
+## Error handling
+
+Every failure is a `CoreError` and always carries a `code` — sent by the server, or derived from
+the HTTP status. Branch on `code`, display `message`.
 
 ```ts
 import { hasCode, isCoreError } from '@v3finance/core-sdk'
@@ -121,27 +215,16 @@ try {
 ```
 
 `kind` separates `http` (the server answered), `network` (the request never left), `timeout`,
-`aborted` and `parse`.
+`aborted` and `parse`. The full code reference is in [docs/errors.md](./docs/errors.md).
 
-## Authentication
-
-The SDK does not store credentials: you provide headers, it reports two events back.
-
-| Runtime | How |
-| --- | --- |
-| Browser | `credentials: 'include'`, the cookie is set by the server |
-| React Native | your own cookie jar, returned from `getAuthHeaders` |
-| Anywhere | `Authorization: Bearer <session-token>` |
-
-In bearer mode **`onTokenRotated` is required**: the server extends a session through the
-`set-auth-token` header, and a client that does not store the new token is signed out at the next
-rotation.
-
-Sign-in is a magic link sent by email. Signing up is possible only on an administrator's invitation.
+Batch endpoints — sharing an address with several subjects — need one extra habit: **read
+`results[]` whenever the call succeeds**. Each subject is handled independently and a partial
+failure still answers 201; 400 comes only when every subject was rejected.
 
 ## Pagination
 
-Lists return `{ items, nextCursor }`. The cursor is opaque — do not parse it.
+Lists return `{ items, nextCursor }`. The cursor is opaque — do not parse it, and treat
+`nextCursor === null` as the only end-of-list signal.
 
 ```ts
 import { paginate } from '@v3finance/core-sdk'
@@ -151,7 +234,10 @@ for await (const address of paginate((p) => core.vault(code).addresses.list(p)))
 }
 ```
 
-## Admin operations
+Not every list is paginated: report templates and snapshots return what they have, and snapshots
+cut off at a limit rather than continuing with a cursor.
+
+## Administrative operations
 
 The package covers the whole API, administrative endpoints included. Access level is available
 programmatically:
@@ -159,31 +245,88 @@ programmatically:
 ```ts
 import { OPERATIONS, isAdminOperation } from '@v3finance/core-sdk'
 
-isAdminOperation('POST /api/v1/policies') // true
+isAdminOperation('POST /api/v1/policies')   // true
+```
+
+A method existing here grants nothing: the server decides from your session, and a
+non-administrator receives 403.
+
+## TanStack Query
+
+Cache keys live in a separate entry point, so the package itself stays dependency-free and the
+keys match between applications — otherwise invalidation in one does not match the other, and the
+mismatch surfaces as "the data did not refresh".
+
+```ts
+import { queryKeys } from '@v3finance/core-sdk/query-keys'
+
+useQuery({
+  queryKey: queryKeys.addresses(code, filters),
+  queryFn: () => core.vault(code).addresses.list(filters),
+})
+```
+
+## TypeScript
+
+Every **named** model of the API is exported — all 262 schemas of its OpenAPI document, generated
+rather than retyped, so a shape the resources do not surface yet is still reachable by name. Where
+the package presents a name of its own (`Address`, `Transaction`, `PersonCard`) it is an alias of
+the generated schema, not a parallel definition. The deliberate exceptions narrow a generated
+`string` to the literal union it really is — `TransactionStatus` — and say so where they are
+declared.
+
+What has no name is what the document declares inline, which is most success bodies: those shapes
+are written out by the resource method that returns them. If you need one as a standalone type,
+take it from the method — `Awaited<ReturnType<…>>` — rather than redeclaring it.
+
+Where a report requires a parameter, the compiler requires it too, and the answer is typed as
+THAT report — the ten have little in common beyond the `report` header:
+
+```ts
+const movement = await core.vault(code).reports.run('asset_movement', { from, to, tokenId })
+movement.openingBalance.total   // AssetMovementReport — tokenId was required
+
+const position = await core.vault(code).reports.run('balance_position', {})
+position.totalsByAsset          // BalancePositionReport — needs no period, has no `summary`
 ```
 
-A method existing in the package grants nothing: the server decides, based on your session.
+Where the type is known only at runtime — the answer of `runTemplate()` — you get `AnyReport`, the
+union of the ten. Amounts in reports are decimal strings (`"1.5"`), not smallest units, with the
+one exception named on `reports.run`: read them with `parseDecimal`, not `amount`.
+
+## Requirements
+
+Node.js 20 or newer, or any runtime with `fetch`. Developing the package itself needs Node 24,
+because its build scripts are TypeScript executed directly.
 
 ## Staying in sync with the API
 
-The repository holds a snapshot of the OpenAPI document (`openapi/spec.json`). Every model is
-generated from it into `src/generated/types.ts` — one exported type per schema, descriptions
-included — by a small purpose-built generator rather than `openapi-typescript`, which is built on
-the TypeScript 5 compiler API that TypeScript 7 no longer ships.
+The repository holds a snapshot of the OpenAPI document. Every model is generated from it into
+`src/generated/types.ts` by a small purpose-built generator — `openapi-typescript` is built on the
+TypeScript 5 compiler API, which TypeScript 7 no longer ships.
 
 ```bash
 npm run spec:update   # refresh the snapshot from the live API
 npm run generate      # regenerate types and the operation catalogue
 ```
 
-CI fails when the generated files drift from the snapshot, and when the API gains an operation that
-has not been classified by access level.
-
-A test keeps the generated files in step with the snapshot, so a drift shows up in a pull request
+A test keeps the generated files in step with the snapshot, so drift shows up in a pull request
 rather than in a consumer at runtime.
 
-Development requires Node.js 24 (the build scripts are TypeScript run directly). The published
-package supports Node.js 20 and above.
+## Further reading
+
+- [docs/concepts.md](./docs/concepts.md) — the domain behind the API: the two tiers of
+  authorisation, how approvals work, why money is a string, how sharing is modelled. Worth reading
+  before building anything non-trivial.
+- [docs/errors.md](./docs/errors.md) — every error code, what causes it and what to do about it.
+- [AGENTS.md](./AGENTS.md) — for changing this package: what is generated, what is written by
+  hand, and the rules that are not style.
+- [CHANGELOG.md](./CHANGELOG.md) — including the known limitations of the current release.
+
+## Versioning
+
+[Semantic versioning](https://semver.org). The package is below 1.0 while the shape settles;
+breaking changes are listed in the changelog.
 
 ## License
 

package/dist/cjs/client.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient, type ClientOptions } from './core/http.js';
-import type { CreateVaultBody, Health, VaultDetail } from './generated/types.js';
+import type { BuildPathBody, BuildPathResponse, CreateVaultBody, Health, ParsePathBody, ParsedPathResponse, UserProfile, VaultDetail, VaultListItem } from './generated/types.js';
 import { AddressesResource } from './resources/addresses.js';
 import { ApprovalsResource } from './resources/approvals.js';
 import { BalancesResource } from './resources/balances.js';
@@ -66,21 +66,30 @@ export interface VaultScope {
     readonly reports: ReportsResource;
     readonly operations: OperationsResource;
 }
-export interface VaultSummary {
-    id: string;
-    code: string;
-    name: string;
-    [extra: string]: unknown;
-}
-export interface Profile {
-    id: string;
-    name: string | null;
-    username: string | null;
-    email: string | null;
-    /** The account came from an invitation link and has no real email yet. */
-    needsEmail: boolean;
-    [extra: string]: unknown;
-}
+/**
+ * A vault as `vaults.list()` returns it.
+ *
+ * Listing and detail are DIFFERENT shapes, so this name can only stand for
+ * one of them. A list item carries `counts` (groups, invitations, policies,
+ * members) and a stripped-down `networks` (id, code, name, coinType); the
+ * detail response carries full `Network` records and the whole `routes` tree,
+ * and no counts at all. `vaults.get()` is therefore typed `VaultDetail`, not
+ * this.
+ *
+ * @deprecated Use `VaultListItem` directly. The name survives only because
+ * dropping an exported one breaks consumers: it used to be a hand-written
+ * interface that declared `id`, `code` and `name` and swept everything else
+ * into an index signature, which described neither shape — `counts` and
+ * `routes` alike arrived as `unknown`.
+ */
+export type VaultSummary = VaultListItem;
+/**
+ * The caller's own profile — what `me.profile()` and `me.updateProfile()`
+ * both answer with.
+ *
+ * @deprecated Use `UserProfile` directly; the name is kept for consumers.
+ */
+export type Profile = UserProfile;
 export declare class CoreClient {
     /** Low-level access for endpoints the resources do not cover yet. */
     readonly http: HttpClient;
@@ -88,9 +97,22 @@ export declare class CoreClient {
     /** Scope of one vault. Build it at the call site; do not store it. */
     vault(code: string): VaultScope;
     readonly vaults: {
-        /** Administrators only: a plain member sees their own vault through `me.vault()`. */
-        list: () => Promise<VaultSummary[]>;
-        get: (code: string) => Promise<VaultSummary>;
+        /**
+         * Administrators only: a plain member sees their own vault through
+         * `me.vault()`. Not paginated and not filterable — the whole list comes
+         * back, newest first.
+         */
+        list: () => Promise<VaultListItem[]>;
+        /**
+         * Full configuration of one vault: every connected network and the whole
+         * `routes` tree, disabled variants included.
+         *
+         * Open to any MEMBER of the vault, unlike `list()`, which is
+         * administrator-only (an administrator passes the membership check too).
+         * The richer payload is also why the return type differs from a list
+         * item: see `VaultSummary`.
+         */
+        get: (code: string) => Promise<VaultDetail>;
         /** Administrators only. */
         create: (input: CreateVaultBody) => Promise<VaultDetail>;
         /**
@@ -99,11 +121,34 @@ export declare class CoreClient {
          * Use these rather than building the string yourself: the path is written
          * WITHOUT apostrophes (`m/44/195/…`, not `m/44'/…`), and the segment
          * order comes from the vault's own configuration, not from a convention.
+         *
+         * Both are open to any MEMBER of the vault; they are not
+         * administrator-only.
+         *
+         * `values` is keyed by `Route.code` and the generated type says only
+         * `unknown` per entry, because the schema's `string | number` union does
+         * not survive generation. What the server accepts: for a static route a
+         * variant `code` or its numeric `pathId`, for a dynamic route an integer
+         * in `[0, 2^31-1]`. A missing route, an unknown variant or a disabled one
+         * is a 400, not a silently skipped segment.
+         */
+        buildDerivationPath: (code: string, body: BuildPathBody) => Promise<BuildPathResponse>;
+        /**
+         * Breaks a path back into the network and one entry per route.
+         *
+         * `segments[].variant` is absent for a dynamic route — that is the normal
+         * case, not a lookup failure. For a static route it is present even when
+         * the variant is disabled, so that legacy addresses still parse.
          */
-        buildDerivationPath: (code: string, body: unknown) => Promise<unknown>;
-        parseDerivationPath: (code: string, body: unknown) => Promise<unknown>;
+        parseDerivationPath: (code: string, body: ParsePathBody) => Promise<ParsedPathResponse>;
     };
-    /** Liveness probe. Needs no authentication. */
+    /**
+     * Liveness probe. Needs no authentication.
+     *
+     * It answers "is the worker deployed at all?" and nothing more: the handler
+     * never touches the database, so a healthy answer does NOT mean D1 is
+     * reachable. Use a real read for that.
+     */
     health(): Promise<Health>;
     /** The caller's own profile, devices and permissions. */
     readonly me: MeResource;

package/dist/cjs/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAO,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,MAAM,EACN,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAA;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,0BAA0B,CAAA;IACvD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,CAAA;AAExC;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,CAAA;AAEjC,qBAAa,UAAU;IACrB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IAEzB,YAAY,OAAO,GAAE,aAAkB,EAMtC;IAED,sEAAsE;IACtE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkB9B;IAED,QAAQ,CAAC,MAAM;QACb;;;;WAIG;QACH,IAAI,QAAM,OAAO,CAAC,aAAa,EAAE,CAAC;QAGlC;;;;;;;;WAQG;QACH,GAAG,SAAS,MAAM,KAAG,OAAO,CAAC,WAAW,CAAC;QAGzC,2BAA2B;QAC3B,MAAM,UAAU,eAAe,KAAG,OAAO,CAAC,WAAW,CAAC;QAGtD;;;;;;;;;;;;;;;;WAgBG;QACH,mBAAmB,SAAS,MAAM,QAAQ,aAAa,KAAG,OAAO,CAAC,iBAAiB,CAAC;QAOpF;;;;;;WAMG;QACH,mBAAmB,SAAS,MAAM,QAAQ,aAAa,KAAG,OAAO,CAAC,kBAAkB,CAAC;MAMtF;IAED;;;;;;OAMG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAExB;IAED,yDAAyD;IACzD,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;IAEvB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IAEvC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAE7B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC5B"}

package/dist/cjs/client.js

@@ -51,8 +51,21 @@ class CoreClient {
         };
     }
     vaults = {
-        /** Administrators only: a plain member sees their own vault through `me.vault()`. */
+        /**
+         * Administrators only: a plain member sees their own vault through
+         * `me.vault()`. Not paginated and not filterable — the whole list comes
+         * back, newest first.
+         */
         list: () => this.http.request('GET', '/api/v1/vaults'),
+        /**
+         * Full configuration of one vault: every connected network and the whole
+         * `routes` tree, disabled variants included.
+         *
+         * Open to any MEMBER of the vault, unlike `list()`, which is
+         * administrator-only (an administrator passes the membership check too).
+         * The richer payload is also why the return type differs from a list
+         * item: see `VaultSummary`.
+         */
         get: (code) => this.http.request('GET', `/api/v1/vaults/${(0, http_js_1.seg)(code)}`),
         /** Administrators only. */
         create: (input) => this.http.request('POST', '/api/v1/vaults', { body: input }),
@@ -62,11 +75,34 @@ class CoreClient {
          * Use these rather than building the string yourself: the path is written
          * WITHOUT apostrophes (`m/44/195/…`, not `m/44'/…`), and the segment
          * order comes from the vault's own configuration, not from a convention.
+         *
+         * Both are open to any MEMBER of the vault; they are not
+         * administrator-only.
+         *
+         * `values` is keyed by `Route.code` and the generated type says only
+         * `unknown` per entry, because the schema's `string | number` union does
+         * not survive generation. What the server accepts: for a static route a
+         * variant `code` or its numeric `pathId`, for a dynamic route an integer
+         * in `[0, 2^31-1]`. A missing route, an unknown variant or a disabled one
+         * is a 400, not a silently skipped segment.
          */
         buildDerivationPath: (code, body) => this.http.request('POST', `/api/v1/vaults/${(0, http_js_1.seg)(code)}/derivation-path/build`, { body }),
+        /**
+         * Breaks a path back into the network and one entry per route.
+         *
+         * `segments[].variant` is absent for a dynamic route — that is the normal
+         * case, not a lookup failure. For a static route it is present even when
+         * the variant is disabled, so that legacy addresses still parse.
+         */
         parseDerivationPath: (code, body) => this.http.request('POST', `/api/v1/vaults/${(0, http_js_1.seg)(code)}/derivation-path/parse`, { body }),
     };
-    /** Liveness probe. Needs no authentication. */
+    /**
+     * Liveness probe. Needs no authentication.
+     *
+     * It answers "is the worker deployed at all?" and nothing more: the handler
+     * never touches the database, so a healthy answer does NOT mean D1 is
+     * reachable. Use a real read for that.
+     */
     health() {
         return this.http.request('GET', '/');
     }

package/dist/cjs/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/errors.d.ts

@@ -5,14 +5,30 @@
  * wrapper has three gaps the client has to close itself — otherwise a precise
  * error turns into "something went wrong":
  *
- *   1. Bodies without an `error` key pass through untouched. Batch sharing
- *      endpoints answer 400 with `{results:[…]}`, which is not a failure of
- *      the whole call but "some subjects were rejected", and has to be read
- *      item by item.
- *   2. Validation failures arrive as a plain string — `{error: "path: msg"}`
- *      — with no code and no details.
- *   3. Inside a batch result `message` equals the code (`{code:"X",
- *      message:"X"}`), so it must never be shown to a person as-is.
+ *   1. Bodies without an `error` key pass through untouched — the wrapper
+ *      keys off that one field. Batch sharing endpoints answer 400 with
+ *      `{results:[…]}`, which is not a failure of the whole call but "some
+ *      subjects were rejected", and has to be read item by item.
+ *   2. Non-JSON bodies have no wrapper at all: the layer leaves by
+ *      content-type, and a thrown `HTTPException` carries its own response
+ *      past it. So a 502 from the edge, a WAF 403 or a platform 429 arrive as
+ *      text. `core/http.ts` reduces a short one to a flat `{error: "…"}`
+ *      (dropping HTML pages) before it reaches this parser, which is why the
+ *      flat string shape below is still read — and why the per-status
+ *      fallback wording here is what a person ends up seeing.
+ *   3. `message` sometimes IS the code. Handlers answer `{error: "<CODE>",
+ *      code: "<CODE>"}` and batch items carry `{code:"X", message:"X"}`; the
+ *      wrapper copies the former into `message` faithfully. A code is not a
+ *      sentence, so it must never be shown to a person as-is.
+ *
+ * What is NOT a gap any more: zod validation failures. The route hook does
+ * build a flat `{error: "amount: Required; …"}` (backend
+ * `openapi/common.ts`), but that is an intermediate form.
+ * `middleware/errorEnvelope` rewraps every JSON body carrying a string
+ * `error` into the canonical envelope, `code` derived from the status —
+ * `BAD_REQUEST` here, because the hook sets none of its own. The same layer
+ * answers an unmatched path and an uncaught throw. Reading `body.error` as a
+ * string against today's API therefore hands you an object.
  *
  * Because of that `code` is always present here: either the server sent one,
  * or it is derived from the HTTP status. Branch on `code`, display `message`.
@@ -54,8 +70,12 @@ export declare function isCoreError(e: unknown): e is CoreError;
 /** Convenience for `catch`: `if (hasCode(e, 'INSUFFICIENT_BALANCE'))`. */
 export declare function hasCode(e: unknown, ...codes: readonly string[]): boolean;
 /**
- * Status to code, mirroring the mapping the API uses, so that both sides call
- * the same thing by the same name.
+ * Status to code, used only when a body carried no code of its own: a proxy's
+ * HTML 502, a platform 429, an empty body.
+ *
+ * The names are the API's own names for the same statuses, so that one
+ * condition has one name whichever side produced it. 502 and 504 are the
+ * exception — the API has no envelope for them, they arrive from the edge.
  */
 export declare function codeFromStatus(status: number): string;
 /**