@v3finance/core-sdk 0.1.0 → 0.2.1

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 {
@@ -21,10 +23,20 @@ export interface VoteInput {
  *
  *   applied (201)  — executed, the money left;
  *   pending (202)  — awaiting signatures, funds RESERVED but not sent;
- *   replayed (200) — a repeat; the transfer already existed.
+ *   replayed (200) — a transfer with this `idempotencyKey` already existed,
+ *                    and this is that transfer as it stands NOW.
  *
  * They cannot be told apart by the body. Showing "sent" on `pending` tells
  * the person money has gone when it is frozen.
+ *
+ * `replayed` does not mean "sent" either. It says only that the request was
+ * seen before; what became of it is in `data.transaction.status`:
+ *
+ *   confirmed, submitted     — it left;
+ *   awaiting_approval        — waiting for signatures, funds reserved;
+ *   pending                  — still executing;
+ *   failed, rejected,
+ *   cancelled                — it did not leave.
  */
 export class TransfersResource {
   readonly #http: HttpClient
@@ -35,7 +47,13 @@ export class TransfersResource {
     this.#base = `/api/v1/vaults/${seg(vaultCode)}/transfers`
   }
 
-  /** Sends a transfer. The timeout is long: the path calls the wallet service. */
+  /**
+   * Sends a transfer. The timeout is long: the path calls the wallet service.
+   *
+   * On `outcome: 'replayed'` read `data.transaction.status` before telling
+   * anyone anything — a replay of an attempt that failed, or that is still
+   * waiting for signatures, comes back the same way as one that went out.
+   */
   async send(
     input: CreateTransferBody,
     options: { signal?: AbortSignal; timeoutMs?: number } = {},
@@ -66,17 +84,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,6 +21,22 @@ 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"

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.1'
 
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev'