@v3finance/core-sdk 0.1.0 → 0.2.0

package/src/resources/transfers.ts

@@ -1,11 +1,13 @@
 import { seg, type HttpClient } from '../core/http.js'
 import { toGated, type Gated } from '../core/gated.js'
 import type {
+  CancelResult,
   CreateTransactionResult,
   CreateTransferBody,
   ReconcileTransferBody,
   ReconcileTransferResult,
   TransactionDetail,
+  VoteResult,
 } from '../generated/types.js'
 
 export interface VoteInput {
@@ -66,17 +68,43 @@ 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: string, input: VoteInput): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(transferId)}/approvals`, { body: input })
+  vote(transferId: string, input: VoteInput): Promise<VoteResult> {
+    return this.#http.request<VoteResult>(
+      '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: string): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(transferId)}/cancel`)
+  cancel(transferId: string): Promise<CancelResult> {
+    return this.#http.request<CancelResult>('POST', `${this.#base}/${seg(transferId)}/cancel`)
   }
 
   /**

package/src/resources/types.ts

@@ -21,11 +21,31 @@ import type {
 /**
  * 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
 

package/src/units.ts

@@ -35,8 +35,16 @@ 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: number): void {
-  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {
     throw new AmountError(`Invalid decimals: ${decimals}`)
   }
 }
@@ -96,8 +104,17 @@ export function format(
   options: { locale?: string; withAsset?: boolean; minFractionDigits?: number } = {},
 ): string {
   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/src/version.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.1.0'
+export const SDK_VERSION = '0.2.0'
 
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev'