@v3finance/core-sdk 0.1.0 → 0.2.0

package/dist/esm/resources/reports.js

@@ -22,20 +22,59 @@ export class ReportsResource {
     get #base() {
         return `/api/v1/vaults/${this.#vault}`;
     }
-    /** Runs a report. The compiler requires whatever that type needs. */
+    /**
+     * Runs a report. The compiler requires whatever that type needs, and the
+     * answer is the schema of THAT type — see `ReportResult`.
+     *
+     * Money in a report is DECIMAL, not raw smallest units: every `AssetAmount`
+     * (`…ByAsset[].amount`), the `byAsset` rows, and the balances of
+     * `asset_movement`, `account_statement` and `balance_position` are strings
+     * like `"1.5"`. Read them with `parseDecimal`; `amount` would take `"1.5"`
+     * for an integer and reject it. The one exception is `address_activity`,
+     * whose `openingBalances`/`closingBalances` are raw (`balanceRaw`).
+     *
+     * Percentages — `comparison.*ChangePercent`, `observations[].changePercent`,
+     * the `…ShareUsd` and `…RatePercent` fields — are decimal STRINGS too
+     * (`"12.5"`, `"-40"`), and `null` where the figure cannot be worked out:
+     * no previous period to compare with, no USD valuation, a zero base.
+     */
     run(type, params) {
         return this.#http.request('GET', `${this.#base}/reports/${type}`, {
             query: { ...params },
         });
     }
-    /** The same thing through the unified endpoint, choosing the type by alias. */
+    /**
+     * The same thing through the unified endpoint, choosing the type by alias.
+     *
+     * The document types this endpoint's answer as `AnyReport`, the union of
+     * all ten. The type you pass decides which member arrives, so the return is
+     * narrowed to it; call it with a `ReportType` known only at runtime and you
+     * get the whole union back.
+     */
     runUnified(type, params) {
         return this.#http.request('GET', `${this.#base}/reports`, {
             query: { type, ...params },
         });
     }
-    /** Drill-down: the operations behind a figure in a report. */
-    queryOperations(body) {
+    /**
+     * Drill-down: the operations behind a figure in a report.
+     *
+     * A PERIOD IS REQUIRED even though every field of the body is optional. The
+     * endpoint takes it from `drilldown.periodStart` or else from
+     * `filters.from`/`filters.to`, and with neither it answers 400
+     * `REPORT_INVALID_PERIOD` — `queryOperations({})` is not a "whole history"
+     * query.
+     *
+     * The other defaults narrow harder than people expect: with no
+     * `filters.statuses` only `confirmed` operations are listed, and with no
+     * `filters.flowTypes` only `external` ones. Pass the report's own filters
+     * through, or the breakdown comes back smaller than the figure it explains.
+     *
+     * `totals.byAsset[].amount` is a DECIMAL string, like every `AssetAmount`
+     * in the reports. Read it with `parseDecimal`, not `amount` — the latter
+     * would take `'1.5'` for an integer and reject it.
+     */
+    queryOperations(body = {}) {
         return this.#http.request('POST', `${this.#base}/reports/query/operations`, { body });
     }
     // --- saved templates ----------------------------------------------------
@@ -46,9 +85,47 @@ export class ReportsResource {
     template(templateId) {
         return this.#http.request('GET', `${this.#base}/report-templates/${seg(templateId)}`);
     }
+    /**
+     * Saves a set of report parameters under a name.
+     *
+     * `parameters` is what the live report takes, as an object — with one
+     * addition: instead of `from`/`to` it may carry
+     * `relativePeriod: { unit: 'day' | 'week' | 'month', offset }`, resolved to
+     * dates each time the template runs.
+     *
+     * NOTHING IN `parameters` IS CHECKED ON SAVE — it is a free-form bag to the
+     * API. A template with no period, or one aimed at a counterparty that does
+     * not exist, saves fine and fails at `runTemplate`.
+     *
+     * `isShared: true` makes the template visible to the whole vault and is for
+     * administrators only. Sharing lends nobody the author's reach: the scope
+     * is worked out for whoever RUNS it, on every run, so two people get
+     * different figures from the same template.
+     *
+     * THE BAG IS NOT A QUERY STRING, and three things that work on a live
+     * report silently do not work here. It is stored and later handed to the
+     * report builder as it is — nothing parses it, nothing fills defaults:
+     *
+     *  - a multi-value filter must be a real ARRAY; a comma-separated string is
+     *    not split;
+     *  - `categoryField` IS IGNORED. A live report parses `'ticker:EUR'` into a
+     *    filter; this path does not, so a template or snapshot built from the
+     *    filters of a report narrowed by `categoryField` answers 200 with
+     *    figures for EVERY value — the wrong report, with no error. Until the
+     *    API parses it here, send the parsed form the builder reads instead:
+     *    `categoryFieldValues: { ticker: ['EUR'] }`;
+     *  - `timezone` has no default. The live endpoints fall back to `UTC`; here
+     *    an absent one reaches the builder as `undefined`. Always pass it.
+     *
+     * So spreading a `ReportFilters` value into `parameters` is safe only when
+     * it carries no `categoryField` and does carry a `timezone`. (The spread
+     * itself is needed because the type is an index signature, which an
+     * interface-typed value does not fit directly.)
+     */
     createTemplate(body) {
         return this.#http.request('POST', `${this.#base}/report-templates`, { body });
     }
+    /** Partial: only the fields you send change. `parameters` is replaced whole, not merged. */
     updateTemplate(templateId, body) {
         return this.#http.request('PATCH', `${this.#base}/report-templates/${seg(templateId)}`, { body });
     }
@@ -63,6 +140,18 @@ export class ReportsResource {
      * template's period while believing you had asked for another one. To
      * change the filters, read the template and call `run()` with them, or
      * edit the template.
+     *
+     * The answer is `AnyReport`: which of the ten shapes arrives depends on the
+     * template's `reportType`, which is not known to the compiler. `report.type`
+     * says which one it is at runtime, but it does NOT narrow the union — the
+     * document types that field as the same ten-value enum on every member. So
+     * narrow by a block only that report has (`'totalsByAsset' in report`), or
+     * check `report.type` and assert the type yourself.
+     *
+     * This is also where a template's mistakes surface, since its parameters
+     * were not checked when it was saved: no period is a 400, a target that no
+     * longer exists a 404, and a template built for somebody else's `userId`
+     * run by a non-administrator a 403.
      */
     runTemplate(templateId) {
         return this.#http.request('POST', `${this.#base}/report-templates/${seg(templateId)}/run`);
@@ -77,18 +166,55 @@ export class ReportsResource {
      * cursor, so a larger history is simply cut off rather than continued.
      */
     snapshots(params = {}) {
-        return this.#http.request('GET', `${this.#base}/report-snapshots`, { query: { ...params } });
+        return this.#http.request('GET', `${this.#base}/report-snapshots`, {
+            query: { ...params },
+        });
     }
+    /**
+     * One snapshot WITH its figures — under `resultJson`, not `result`; see
+     * `ReportSnapshotDetail`. A non-admin can only read snapshots they
+     * generated themselves, and a missing one is 404 either way, so "not yours"
+     * and "not there" are indistinguishable.
+     */
     snapshot(snapshotId) {
         return this.#http.request('GET', `${this.#base}/report-snapshots/${seg(snapshotId)}`);
     }
+    /**
+     * Builds the report and freezes it. The answer carries the figures under
+     * `result` — the detail (`snapshot(id)`) calls the same thing `resultJson`.
+     *
+     * `parameters` follows the same rules as a template's — read them at
+     * `createTemplate`, because two of them fail silently: `categoryField` is
+     * ignored (the snapshot would freeze UNFILTERED figures; send
+     * `categoryFieldValues` instead) and `timezone` has no default. Unlike a
+     * template the parameters ARE used at once, so a bad period or a missing
+     * target fails here.
+     *
+     * `result` is the report of type `reportType`, but the type cannot say so:
+     * the spec declares it as a free-form object. Narrow it yourself —
+     * `snap.result as unknown as ReportResult['transaction_activity']` (the
+     * double cast is required; the detail's `resultJson` takes the same one).
+     * For the same reason the per-type REQUIRED parameters are not checked by
+     * the compiler here, as they are in `run()`.
+     *
+     * A result over roughly 900 KB is refused with 400
+     * `REPORT_PERIOD_TOO_LARGE` — narrow the filters.
+     */
     createSnapshot(body) {
         return this.#http.request('POST', `${this.#base}/report-snapshots`, { body });
     }
     deleteSnapshot(snapshotId) {
         return this.#http.request('DELETE', `${this.#base}/report-snapshots/${seg(snapshotId)}`);
     }
-    /** Starts an export of a snapshot. The file is fetched separately. */
+    /**
+     * Exports a snapshot. The file is fetched separately, with `downloadExport`.
+     *
+     * Only `format` matters, and only two of its four values work: `json` (the
+     * frozen result) and `csv` (a flat register of operations). `xlsx` and
+     * `pdf` pass validation and are then refused with 400
+     * `REPORT_UNSUPPORTED_FORMAT`. `locale`, `timezone` and
+     * `includeOperationRegister` are accepted and currently change nothing.
+     */
     createExport(snapshotId, body) {
         return this.#http.request('POST', `${this.#base}/report-snapshots/${seg(snapshotId)}/exports`, { body });
     }
@@ -100,7 +226,9 @@ export class ReportsResource {
      * be CSV or another binary format, and parsing that as JSON fails every
      * time. Read it with `.blob()`, `.text()` or `.arrayBuffer()`.
      *
-     * Poll `export()` until it reports ready before calling this.
+     * Exports are produced synchronously today, so the record `createExport`
+     * answers with is already `completed` and can be downloaded at once. The
+     * `status` field exists for a queued path — check it rather than assuming.
      */
     downloadExport(exportId) {
         return this.#http.fetchRaw('GET', `${this.#base}/report-exports/${seg(exportId)}/download`);

package/dist/esm/resources/reports.js.map

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

package/dist/esm/resources/sharing.d.ts

@@ -1,5 +1,5 @@
 import { type HttpClient } from '../core/http.js';
-import type { AddressAccessGrant, AddressSharesList, GrantAddressShareBody, ParticipantsResponse, PatchAddressShareBody, ShareBatchResult } from '../generated/types.js';
+import type { AddressAccessGrant, AddressSharesList, GrantAddressShareBody, ParticipantsResponse, PatchAddressShareBody, ShareGrantCreated } from '../generated/types.js';
 /**
  * Shared access to addresses.
  *
@@ -30,23 +30,74 @@ export declare class SharingResource {
      * 400 comes only when every subject was rejected. A consumer that trusts
      * the status code silently loses the people who were refused.
      *
+     * WHERE THE REASONS GO WHEN EVERY SUBJECT FAILED. That 400 is not an error
+     * envelope: the API sends the same `{results:[…]}` body with a 400 instead
+     * of a 201. The document describes both forms of that status — the
+     * envelope for a body that failed validation, and `ShareBatchAllRejected`
+     * for a batch in which every subject was refused. The SDK does not lose the
+     * second, but it does throw: `core/errors.ts` finds neither `error` nor
+     * `code` in the body, so it builds a `CoreError` with `code: 'BAD_REQUEST'`
+     * and puts the WHOLE body in `details`:
+     *
+     * ```ts
+     * catch (e) {
+     *   if (isCoreError(e) && e.status === 400) {
+     *     const per = (e.details as ShareBatchAllRejected | undefined)?.results
+     *     // per[i].error.code — why that one subject was refused
+     *   }
+     * }
+     * ```
+     *
+     * `details` is `undefined` for the other 400, the validation one — hence
+     * the `| undefined` in the cast, and the reason to check before reading.
+     *
+     * Reading `message` instead gets you "The request was rejected", because
+     * the server sent no message to pass on. Per-subject `error.message` equals
+     * its `code`, so neither is a sentence to show a person as-is.
+     *
      * The single-subject form answers with the grant itself rather than a
-     * batch, which is why the return type is a union.
+     * batch, which is why the return type is a union — `ShareGrantCreated`,
+     * the grant or the batch; tell them apart with `'results' in answer`. It
+     * also reports failure differently: one subject refused is a plain 403 with
+     * no `results[]` at all, so the batch form is the one to use when you need
+     * reasons.
      */
-    share(addressId: string, input: GrantAddressShareBody): Promise<ShareBatchResult | AddressAccessGrant>;
+    share(addressId: string, input: GrantAddressShareBody): Promise<ShareGrantCreated>;
     update(addressId: string, shareId: string, input: PatchAddressShareBody): Promise<AddressAccessGrant>;
-    revoke(addressId: string, shareId: string): Promise<unknown>;
+    /** Soft: the row survives with `revokedAt`/`revokedById` for the audit trail. */
+    revoke(addressId: string, shareId: string): Promise<{
+        revoked: boolean;
+    }>;
     /**
      * Everyone who reaches the address, as PEOPLE rather than grants: the
      * owner, direct grantees and members of granted groups. Each entry explains
      * where the access comes from, which is also how you learn how to revoke it.
      */
     participants(addressId: string): Promise<ParticipantsResponse>;
-    /** Addresses you have shared with others. */
-    sharedByMe(): Promise<unknown>;
-    /** Addresses others have shared with you. */
-    sharedWithMe(): Promise<unknown>;
-    /** Gives up access someone granted you. Your own grant, your own decision. */
-    leave(grantId: string): Promise<unknown>;
+    /**
+     * What you have opened to others — addresses AND folders, so the entries
+     * are not all of one `targetType`. Same shape as `list()`.
+     */
+    sharedByMe(): Promise<AddressSharesList>;
+    /**
+     * Addresses others have shared with you — DIRECT grants on an address
+     * only. Access that reaches you through a shared FOLDER is not here, which
+     * is the trap: an empty answer does not mean nothing is shared with you.
+     * For shared access of every kind ask the addresses list with
+     * `access: 'shared'`, or `'all'` to include your own.
+     */
+    sharedWithMe(): Promise<AddressSharesList>;
+    /**
+     * Gives up access someone granted you. Your own grant, your own decision —
+     * the owner is not asked.
+     *
+     * Works on a grant made to you PERSONALLY. Access you have through a user
+     * group cannot be dropped this way, because it belongs to the whole group:
+     * that answers 409 `ACCESS_VIA_GROUP`, with the group's id and name in
+     * `details`, so the interface can say which group to leave instead.
+     */
+    leave(grantId: string): Promise<{
+        left: boolean;
+    }>;
 }
 //# sourceMappingURL=sharing.d.ts.map

package/dist/esm/resources/sharing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharing.d.ts","sourceRoot":"","sources":["../../../src/resources/sharing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;;IAI1B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAMD,sCAAsC;IACtC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;;;;;OAUG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,kBAAkB,CAAC,CAMhD;IAED,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAM7B;IAED,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAED;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAK7D;IAED,6CAA6C;IAC7C,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAE7B;IAED,6CAA6C;IAC7C,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAE/B;IAED,8EAA8E;IAC9E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKvC;CACF"}
+{"version":3,"file":"sharing.d.ts","sourceRoot":"","sources":["../../../src/resources/sharing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;;IAI1B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAMD,sCAAsC;IACtC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAMjF;IAED,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAM7B;IAED,iFAAiF;IACjF,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAKxE;IAED;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAK7D;IAED;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAKvC;IAED;;;;;;OAMG;IACH,YAAY,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAKzC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAKjD;CACF"}

package/dist/esm/resources/sharing.js

@@ -38,8 +38,37 @@ export class SharingResource {
      * 400 comes only when every subject was rejected. A consumer that trusts
      * the status code silently loses the people who were refused.
      *
+     * WHERE THE REASONS GO WHEN EVERY SUBJECT FAILED. That 400 is not an error
+     * envelope: the API sends the same `{results:[…]}` body with a 400 instead
+     * of a 201. The document describes both forms of that status — the
+     * envelope for a body that failed validation, and `ShareBatchAllRejected`
+     * for a batch in which every subject was refused. The SDK does not lose the
+     * second, but it does throw: `core/errors.ts` finds neither `error` nor
+     * `code` in the body, so it builds a `CoreError` with `code: 'BAD_REQUEST'`
+     * and puts the WHOLE body in `details`:
+     *
+     * ```ts
+     * catch (e) {
+     *   if (isCoreError(e) && e.status === 400) {
+     *     const per = (e.details as ShareBatchAllRejected | undefined)?.results
+     *     // per[i].error.code — why that one subject was refused
+     *   }
+     * }
+     * ```
+     *
+     * `details` is `undefined` for the other 400, the validation one — hence
+     * the `| undefined` in the cast, and the reason to check before reading.
+     *
+     * Reading `message` instead gets you "The request was rejected", because
+     * the server sent no message to pass on. Per-subject `error.message` equals
+     * its `code`, so neither is a sentence to show a person as-is.
+     *
      * The single-subject form answers with the grant itself rather than a
-     * batch, which is why the return type is a union.
+     * batch, which is why the return type is a union — `ShareGrantCreated`,
+     * the grant or the batch; tell them apart with `'results' in answer`. It
+     * also reports failure differently: one subject refused is a plain 403 with
+     * no `results[]` at all, so the batch form is the one to use when you need
+     * reasons.
      */
     share(addressId, input) {
         return this.#http.request('POST', `${this.#address(addressId)}/shares`, { body: input });
@@ -47,6 +76,7 @@ export class SharingResource {
     update(addressId, shareId, input) {
         return this.#http.request('PATCH', `${this.#address(addressId)}/shares/${seg(shareId)}`, { body: input });
     }
+    /** Soft: the row survives with `revokedAt`/`revokedById` for the audit trail. */
     revoke(addressId, shareId) {
         return this.#http.request('DELETE', `${this.#address(addressId)}/shares/${seg(shareId)}`);
     }
@@ -58,15 +88,32 @@ export class SharingResource {
     participants(addressId) {
         return this.#http.request('GET', `${this.#address(addressId)}/participants`);
     }
-    /** Addresses you have shared with others. */
+    /**
+     * What you have opened to others — addresses AND folders, so the entries
+     * are not all of one `targetType`. Same shape as `list()`.
+     */
     sharedByMe() {
         return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/shared-by-me`);
     }
-    /** Addresses others have shared with you. */
+    /**
+     * Addresses others have shared with you — DIRECT grants on an address
+     * only. Access that reaches you through a shared FOLDER is not here, which
+     * is the trap: an empty answer does not mean nothing is shared with you.
+     * For shared access of every kind ask the addresses list with
+     * `access: 'shared'`, or `'all'` to include your own.
+     */
     sharedWithMe() {
         return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/shared-with-me`);
     }
-    /** Gives up access someone granted you. Your own grant, your own decision. */
+    /**
+     * Gives up access someone granted you. Your own grant, your own decision —
+     * the owner is not asked.
+     *
+     * Works on a grant made to you PERSONALLY. Access you have through a user
+     * group cannot be dropped this way, because it belongs to the whole group:
+     * that answers 409 `ACCESS_VIA_GROUP`, with the group's id and name in
+     * `details`, so the interface can say which group to leave instead.
+     */
     leave(grantId) {
         return this.#http.request('DELETE', `/api/v1/vaults/${this.#vault}/shared-with-me/${seg(grantId)}`);
     }

package/dist/esm/resources/sharing.js.map

@@ -1 +1 @@
-{"version":3,"file":"sharing.js","sourceRoot":"","sources":["../../../src/resources/sharing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AAWtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,eAAe;IACjB,KAAK,CAAY;IACjB,MAAM,CAAQ;IAEvB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IAC9B,CAAC;IAED,QAAQ,CAAC,SAAiB;QACxB,OAAO,kBAAkB,IAAI,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,CAAC,EAAE,CAAA;IACpE,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,SAAiB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;IAC3F,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CACH,SAAiB,EACjB,KAA4B;QAE5B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,EACpC,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED,MAAM,CACJ,SAAiB,EACjB,OAAe,EACf,KAA4B;QAE5B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,OAAO,EACP,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,EAAE,EACpD,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED,MAAM,CAAC,SAAiB,EAAE,OAAe;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC3F,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,KAAK,EACL,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,eAAe,CAC3C,CAAA;IACH,CAAC;IAED,6CAA6C;IAC7C,UAAU;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,IAAI,CAAC,MAAM,eAAe,CAAC,CAAA;IAChF,CAAC;IAED,6CAA6C;IAC7C,YAAY;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,IAAI,CAAC,MAAM,iBAAiB,CAAC,CAAA;IAClF,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,OAAe;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,QAAQ,EACR,kBAAkB,IAAI,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,EAAE,CAC/D,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"sharing.js","sourceRoot":"","sources":["../../../src/resources/sharing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AAWtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,eAAe;IACjB,KAAK,CAAY;IACjB,MAAM,CAAQ;IAEvB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IAC9B,CAAC;IAED,QAAQ,CAAC,SAAiB;QACxB,OAAO,kBAAkB,IAAI,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,CAAC,EAAE,CAAA;IACpE,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,SAAiB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;IAC3F,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,KAAK,CAAC,SAAiB,EAAE,KAA4B;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,EACpC,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED,MAAM,CACJ,SAAiB,EACjB,OAAe,EACf,KAA4B;QAE5B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,OAAO,EACP,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,EAAE,EACpD,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,SAAiB,EAAE,OAAe;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,QAAQ,EACR,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,EAAE,CACrD,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,KAAK,EACL,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,eAAe,CAC3C,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,KAAK,EACL,kBAAkB,IAAI,CAAC,MAAM,eAAe,CAC7C,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,KAAK,EACL,kBAAkB,IAAI,CAAC,MAAM,iBAAiB,CAC/C,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAe;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,QAAQ,EACR,kBAAkB,IAAI,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,EAAE,CAC/D,CAAA;IACH,CAAC;CACF"}

package/dist/esm/resources/transfers.d.ts

@@ -1,6 +1,6 @@
 import { type HttpClient } from '../core/http.js';
 import { type Gated } from '../core/gated.js';
-import type { CreateTransactionResult, CreateTransferBody, ReconcileTransferBody, ReconcileTransferResult, TransactionDetail } from '../generated/types.js';
+import type { CancelResult, CreateTransactionResult, CreateTransferBody, ReconcileTransferBody, ReconcileTransferResult, TransactionDetail, VoteResult } from '../generated/types.js';
 export interface VoteInput {
     decision: 'approve' | 'reject';
     comment?: string | undefined;
@@ -38,13 +38,35 @@ export declare class TransfersResource {
      * Only people captured in the approver SNAPSHOT taken when the request was
      * created may vote: editing a policy or a group afterwards does not change
      * an in-flight request.
+     *
+     * READ `status` FROM THE ANSWER — it is the status of the TRANSFER after
+     * the vote, and the vote is where the money moves:
+     *
+     *   awaiting_approval — counted, more signatures still needed;
+     *   rejected          — a `reject` is a veto, and the reserve is released;
+     *   confirmed/failed  — this vote completed the threshold, so execution ran
+     *                       INSIDE this request (gas, then broadcast, ~10s).
+     *
+     * `failed` means the money is back: execution broke after approval and the
+     * reserve was released, with the reason in `executionError`. Treating the
+     * call as "approved, done" hides both the success and that failure.
      */
-    vote(transferId: string, input: VoteInput): Promise<unknown>;
+    vote(transferId: string, input: VoteInput): Promise<VoteResult>;
     /**
      * Cancels your own transfer that is awaiting signatures and releases the
-     * reserve. A transfer already broadcast cannot be cancelled.
+     * reserve. A transfer already broadcast cannot be cancelled; administrators
+     * may cancel somebody else's, so a stuck request is not hostage to an
+     * absent initiator.
+     *
+     * The resulting status is its own value, `cancelled` — not the `rejected`
+     * of a veto and not `failed`. Worth keeping apart in the interface: "you
+     * withdrew this" and "somebody refused it" are different events.
+     *
+     * Clear a stuck transfer through this endpoint and never by writing the
+     * status directly: the reserve is released by a ledger posting, not by the
+     * status, so a hand-edited row leaves the funds locked for good.
      */
-    cancel(transferId: string): Promise<unknown>;
+    cancel(transferId: string): Promise<CancelResult>;
     /**
      * Settles a transfer stuck in `pending` — the case where the worker died
      * mid-execution, so cancelling does not apply. Administrators only.

package/dist/esm/resources/transfers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfers.d.ts","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;;IAI5B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAED,gFAAgF;IAC1E,IAAI,CACR,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAUzC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;OAMG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,qBAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;CACF"}
+{"version":3,"file":"transfers.d.ts","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;;IAI5B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAED,gFAAgF;IAC1E,IAAI,CACR,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAUzC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAM9D;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAEhD;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,qBAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;CACF"}

package/dist/esm/resources/transfers.js

@@ -46,13 +46,35 @@ export class TransfersResource {
      * Only people captured in the approver SNAPSHOT taken when the request was
      * created may vote: editing a policy or a group afterwards does not change
      * an in-flight request.
+     *
+     * READ `status` FROM THE ANSWER — it is the status of the TRANSFER after
+     * the vote, and the vote is where the money moves:
+     *
+     *   awaiting_approval — counted, more signatures still needed;
+     *   rejected          — a `reject` is a veto, and the reserve is released;
+     *   confirmed/failed  — this vote completed the threshold, so execution ran
+     *                       INSIDE this request (gas, then broadcast, ~10s).
+     *
+     * `failed` means the money is back: execution broke after approval and the
+     * reserve was released, with the reason in `executionError`. Treating the
+     * call as "approved, done" hides both the success and that failure.
      */
     vote(transferId, input) {
         return this.#http.request('POST', `${this.#base}/${seg(transferId)}/approvals`, { body: input });
     }
     /**
      * Cancels your own transfer that is awaiting signatures and releases the
-     * reserve. A transfer already broadcast cannot be cancelled.
+     * reserve. A transfer already broadcast cannot be cancelled; administrators
+     * may cancel somebody else's, so a stuck request is not hostage to an
+     * absent initiator.
+     *
+     * The resulting status is its own value, `cancelled` — not the `rejected`
+     * of a veto and not `failed`. Worth keeping apart in the interface: "you
+     * withdrew this" and "somebody refused it" are different events.
+     *
+     * Clear a stuck transfer through this endpoint and never by writing the
+     * status directly: the reserve is released by a ledger posting, not by the
+     * status, so a hand-edited row leaves the funds locked for good.
      */
     cancel(transferId) {
         return this.#http.request('POST', `${this.#base}/${seg(transferId)}/cancel`);

package/dist/esm/resources/transfers.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AActD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,OAAO,CAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAClG,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC9E,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AAgBtD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,OAAO,CAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5F,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}

package/dist/esm/resources/types.d.ts

@@ -13,11 +13,31 @@ import type { AddressDetail as GeneratedAddressDetail, AddressListItem, CreateTr
 /**
  * An address as it appears in listings.
  *
+ * Which shape comes from where: `GET /addresses` and `PATCH /addresses/{id}`
+ * both answer with `AddressListItem` — that is why this is an alias of it and
+ * not of the schema called `Address`. `GET /addresses/{id}` answers with the
+ * larger `AddressDetail` (transactions, shares, vault).
+ *
+ * The document DOES also declare a schema named `Address`, and this export
+ * shadows it — `src/index.ts` re-exports this name explicitly, and an
+ * explicit re-export beats `export type *`. That is deliberate, and the
+ * reason belongs here so nobody "fixes" it the wrong way round: no operation
+ * references the `Address` schema (zero `$ref`), and its sixteen properties
+ * are a strict subset of `AddressListItem`'s twenty-three, identical in type
+ * and in optionality. The alias is therefore narrower than the schema it
+ * hides, never wider, and the hidden schema describes no response at all.
+ * Pointing this name at `Address` would be the real break: the seven extra
+ * fields would vanish from the type while still arriving on the wire.
+ *
  * `balance` is `string | null`, and the `null` matters: it means the address
  * has NO ledger account yet — nothing has ever arrived. That is not zero, and
  * the two must not be merged, because "no account" and "empty account"
  * deserve different wording. Amounts are raw smallest units; put them through
  * the helpers in `units.ts` rather than `Number`.
+ *
+ * One field is thinner than the type admits: `sharing` is optional because
+ * `PATCH /addresses/{id}` reuses this schema WITHOUT it (the document says so
+ * itself, on the property). Listings and the detail endpoint do send it.
  */
 export type Address = AddressListItem;
 /** A single address with its sharing and access details. */

package/dist/esm/resources/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}

package/dist/esm/units.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAWD,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAO5E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAcpF;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CASnF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,MAAM,CAWR;AAaD,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,0CAA0C;AAC1C,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAKxD;AAED,eAAO,MAAM,MAAM,MAAO,MAAM,KAAG,OAA+B,CAAA;AAClE,eAAO,MAAM,UAAU,MAAO,MAAM,KAAG,OAA6B,CAAA"}
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAmBD,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAO5E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAcpF;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CASnF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,MAAM,CAoBR;AAaD,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,0CAA0C;AAC1C,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAKxD;AAED,eAAO,MAAM,MAAM,MAAO,MAAM,KAAG,OAA+B,CAAA;AAClE,eAAO,MAAM,UAAU,MAAO,MAAM,KAAG,OAA6B,CAAA"}

package/dist/esm/units.js

@@ -23,8 +23,15 @@ export class AmountError extends Error {
 }
 const RAW_RE = /^-?\d+$/;
 const DECIMAL_RE = /^-?\d+(\.\d+)?$/;
+/**
+ * The API's own ceiling: `CreateTokenBody.decimals` is `int().min(0).max(38)`
+ * in the policy engine's `src/openapi/models.ts`. A lower bound here would
+ * contradict the rest of the package — `registries.createToken` would accept a
+ * token this module then refuses to do arithmetic on.
+ */
+const MAX_DECIMALS = 38;
 function assertDecimals(decimals) {
-    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {
         throw new AmountError(`Invalid decimals: ${decimals}`);
     }
 }
@@ -76,8 +83,17 @@ export function toDecimalString(a, options = {}) {
  */
 export function format(a, options = {}) {
     const decimal = toDecimalString(a, { trim: false });
+    // The padding is clamped to `decimals` because `decimals` is the maximum
+    // below, and Intl throws RangeError when a minimum exceeds its maximum. So
+    // the default of two digits made `format` unusable — not merely unpadded —
+    // for any token with 0 or 1 decimals, and such tokens are reachable: the API
+    // allows `decimals: 0` on a token, and a `currency` category field takes
+    // `scale: 0` today. Clamping rather than raising the maximum: digits past
+    // `decimals` do not exist in the asset, and printing them would claim a
+    // divisibility the token does not have.
+    const minFraction = Math.min(options.minFractionDigits ?? 2, a.decimals);
     const formatter = new Intl.NumberFormat(options.locale ?? 'en-US', {
-        minimumFractionDigits: options.minFractionDigits ?? 2,
+        minimumFractionDigits: minFraction,
         maximumFractionDigits: a.decimals,
     });
     // The runtime accepts a string and keeps precision; lib.es5 still types the

package/dist/esm/units.js.map

@@ -1 +1 @@
-{"version":3,"file":"units.js","sourceRoot":"","sources":["../../src/units.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../../src/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAED,MAAM,MAAM,GAAG,SAAS,CAAA;AACxB,MAAM,UAAU,GAAG,iBAAiB,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,EAAE,CAAA;AAEvB,SAAS,cAAc,CAAC,QAAgB;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;QAC3E,MAAM,IAAI,WAAW,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAA;IACxD,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,QAAgB,EAAE,KAAc;IAClE,cAAc,CAAC,QAAQ,CAAC,CAAA;IACxB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,WAAW,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAA;IACtF,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAAgB,EAAE,KAAc;IAC1E,cAAc,CAAC,QAAQ,CAAC,CAAA;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAA;IAEzE,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IAClC,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE,QAAQ,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC7E,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,WAAW,CACnB,6BAA6B,QAAQ,CAAC,MAAM,sBAAsB,QAAQ,EAAE,CAC7E,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;IAClF,OAAO,MAAM,CAAC,GAAG,QAAQ,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAA;AAC/E,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,OAAO,GAAuB,EAAE;IACzE,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IACtC,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAChF,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAA;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACpC,IAAI,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK;QAAE,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAClE,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAChC,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,EAAE,CAAA;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CACpB,CAAS,EACT,OAAO,GAAyE,EAAE;IAElF,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IACnD,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,wCAAwC;IACxC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;IACxE,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,EAAE;QACjE,qBAAqB,EAAE,WAAW;QAClC,qBAAqB,EAAE,CAAC,CAAC,QAAQ;KAClC,CAAC,CAAA;IACF,4EAA4E;IAC5E,4BAA4B;IAC5B,MAAM,IAAI,GAAI,SAAS,CAAC,MAA+C,CAAC,OAAO,CAAC,CAAA;IAChF,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9E,OAAO,GAAG,IAAI,GAAG,MAAM,EAAE,CAAA;AAC3B,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAS,EAAE,CAAS;IAC5C,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,WAAW,CAAC,kDAAkD,CAAC,CAAC,QAAQ,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;IACzG,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;QAC9C,wEAAwE;QACxE,6EAA6E;QAC7E,MAAM,IAAI,WAAW,CAAC,oCAAoC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;IACrF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,CAAS;IACtC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtB,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,CAAA;AAC3F,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,CAAS;IACtC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtB,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,CAAA;AAC3F,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,OAAO,CAAC,CAAS,EAAE,CAAS;IAC1C,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACvB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACvB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACnC,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;AAClE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA"}