@v3finance/core-sdk 0.1.0 → 0.2.0

package/src/resources/history.ts

@@ -10,9 +10,33 @@ import type { HistoryItem } from '../generated/types.js'
  * client from two cursors.
  */
 
+/**
+ * The statuses the feed can be FILTERED by.
+ *
+ * One value short of `TransactionStatus`, which is the right set for reading
+ * a transfer: `submitted` is missing here. It is a legacy status — still the
+ * column default in the schema, so old rows carry it — and the endpoint's
+ * enum does not accept it, so filtering by it is a 400 rather than an empty
+ * page. Hence a separate type: taking the reader's union would have the
+ * package suggest a value its own filter rejects.
+ */
+export type HistoryStatusFilter =
+  | 'awaiting_approval'
+  | 'pending'
+  | 'confirmed'
+  | 'failed'
+  | 'rejected'
+  | 'cancelled'
+
 export interface HistoryParams extends PageParams {
   direction?: 'in' | 'out' | undefined
-  status?: string | undefined
+  /**
+   * Outgoing only, whichever value you pass: a status belongs to a transfer,
+   * so setting this EXCLUDES the incoming side of the feed even without
+   * `direction: 'out'`. The same goes for `awaitingMyApproval` and
+   * `decisionPolicyId`.
+   */
+  status?: HistoryStatusFilter | undefined
   /** Only what awaits MY signature. For the approvals screen. */
   awaitingMyApproval?: boolean | undefined
   asset?: string | undefined
@@ -23,7 +47,8 @@ export interface HistoryParams extends PageParams {
   counterpartyId?: string | undefined
   counterpartyGroupId?: string | undefined
   counterpartyAddressId?: string | undefined
-  flowType?: string | undefined
+  /** `internal` — the other side is an address of this vault; `external` — it is not. */
+  flowType?: 'internal' | 'external' | undefined
   category?: string | undefined
   paymentPurpose?: string | undefined
   decisionPolicyId?: string | undefined

package/src/resources/me.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from '../core/http.js'
 import type {
   AllowedSegmentsResponse,
+  MeVaultResponse,
   PatchProfileBody,
   PushToken,
   RegisterPushTokenBody,
@@ -19,6 +20,14 @@ export class MeResource {
     return this.#http.request<UserProfile>('GET', '/api/v1/me/profile')
   }
 
+  /**
+   * Partial update of your own profile: `name`, `username`, `image`, `color`,
+   * `emoji`. `null` clears a field (except `name`). `username` is unique
+   * across the whole platform — taken answers 409 `USERNAME_TAKEN`.
+   *
+   * Answers with the full profile, the same shape `profile()` returns —
+   * `needsEmail` included, so there is no need to re-read it after an update.
+   */
   updateProfile(input: PatchProfileBody): Promise<UserProfile> {
     return this.#http.request<UserProfile>('PATCH', '/api/v1/me/profile', { body: input })
   }
@@ -37,9 +46,21 @@ export class MeResource {
     })
   }
 
-  /** The vault the caller belongs to — where most screens start. */
-  vault(): Promise<unknown> {
-    return this.#http.request('GET', '/api/v1/me/vault')
+  /**
+   * The vault the caller belongs to — where most screens start. Carries the
+   * derivation-path structure (`routes`, enabled variants only), which is
+   * what an address-creation form is built from.
+   *
+   * ONE vault, even if there are several memberships: the first one found is
+   * returned. Membership is a `VaultMembership`, not "has at least one policy
+   * group", so somebody with no groups still gets their vault here — they can
+   * open the application and will simply be refused every action.
+   *
+   * No membership anywhere answers 404, which is a legitimate state for a
+   * brand-new account rather than an error to report as a fault.
+   */
+  vault(): Promise<MeVaultResponse> {
+    return this.#http.request<MeVaultResponse>('GET', '/api/v1/me/vault')
   }
 
   /**
@@ -60,7 +81,11 @@ export class MeResource {
     return this.#http.request<PushToken>('POST', '/api/v1/me/push-tokens', { body: input })
   }
 
-  removePushToken(token: string): Promise<unknown> {
-    return this.#http.request('DELETE', `/api/v1/me/push-tokens/${encodeURIComponent(token)}`)
+  /** `deleted: false` simply means the token was not registered — not a failure. */
+  removePushToken(token: string): Promise<{ deleted: boolean }> {
+    return this.#http.request<{ deleted: boolean }>(
+      'DELETE',
+      `/api/v1/me/push-tokens/${encodeURIComponent(token)}`,
+    )
   }
 }

package/src/resources/members.ts

@@ -1,8 +1,10 @@
 import { seg, type HttpClient } from '../core/http.js'
 import type { PageParams } from '../core/pagination.js'
 import type {
+  MemberCard,
   MemberDetail,
   MembersPage,
+  UserGroup,
   UserGroupDetail,
   UserGroupMembers,
 } from '../generated/types.js'
@@ -43,16 +45,33 @@ export class MembersResource {
    * By username only — an email address will not resolve. This is the step
    * before granting access to someone: you need their id, and you can only
    * resolve people you are allowed to see.
+   *
+   * A person you cannot see answers 404, the same as one who does not exist.
+   * That is deliberate: a distinguishable answer would let anyone probe which
+   * usernames are taken. So a 404 here means "no such visible member", and
+   * the fix may be a visibility grant rather than a different spelling.
    */
-  resolve(username: string): Promise<unknown> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/members/resolve`, {
-      query: { username },
-    })
+  resolve(username: string): Promise<MemberCard> {
+    return this.#http.request<MemberCard>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/members/resolve`,
+      { query: { username } },
+    )
   }
 
-  /** Policy groups as a member sees them. */
-  groups(): Promise<unknown> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/user-groups`)
+  /**
+   * Policy groups as a member sees them: id, name, icon and `memberCount`
+   * only — enough to pick one as the subject of a grant. `search` matches the
+   * name.
+   *
+   * No cursor: the whole list comes back at once.
+   */
+  groups(params: { search?: string | undefined } = {}): Promise<{ items: UserGroup[] }> {
+    return this.#http.request<{ items: UserGroup[] }>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/user-groups`,
+      { query: { ...params } },
+    )
   }
 
   /**

package/src/resources/operations.ts

@@ -3,14 +3,40 @@ import type { PageParams } from '../core/pagination.js'
 import type {
   ApprovalRelations,
   CreateOperationRelationBody,
+  IncomingTransactionDetail,
   OperationMetadata,
   OperationRelation,
   OperationRelationsPage,
+  OperationType,
   PatchOperationMetadataBody,
 } from '../generated/types.js'
 
-/** Operation kind in a path: `transfer`, `deposit`, … */
-export type OperationKind = string
+/**
+ * Operation kind in a path. Exactly two values exist.
+ *
+ * The document has no schema of this name, so nothing was being shadowed —
+ * but `= string` was still wider than the contract, and the endpoints below
+ * answer 400 to anything but these two. Kept as a name of its own rather than
+ * dropped, because it is exported from the package root; it is now the same
+ * type as `OperationType`, which the relation records themselves carry, so
+ * the two can be mixed freely.
+ */
+export type OperationKind = OperationType
+
+export interface ListRelationsParams extends PageParams {
+  relationType?: 'refund' | 'reversal' | 'correction' | 'replacement' | undefined
+  sourceOperationId?: string | undefined
+  targetOperationId?: string | undefined
+  /** Links that carry a partial amount in this token. */
+  tokenId?: string | undefined
+  /**
+   * Window over when the LINK was recorded, not over the operations it joins.
+   * Half-open: `from` is inclusive, `to` exclusive, so consecutive days can
+   * be paged without double-counting the boundary.
+   */
+  from?: string | undefined
+  to?: string | undefined
+}
 
 /**
  * Everything hanging off a single operation: free-form metadata, links to
@@ -69,13 +95,38 @@ export class OperationsResource {
    * How the operation's status changed, with timestamps. For a transfer this
    * is the honest record of the path through approval, reservation and
    * settlement — useful when "why is it still pending" needs an answer.
+   *
+   * Ordered oldest first. Operations that predate this log have a single
+   * baseline row, so one entry does not mean only one transition happened.
+   * `changedById` is `null` where no person made the move — the wallet
+   * webhook crediting a deposit, a confirmed broadcast, reconciliation by
+   * hash — so do not render it as an unknown user. Read `reason` instead; it
+   * carries the machine code (`webhook_topup`, `broadcast_confirmed`,
+   * `approval_threshold_reached`, …). The row has no schema name of its own
+   * in the document, which is why it is spelled out here.
    */
-  statusHistory(kind: OperationKind, operationId: string): Promise<unknown> {
+  statusHistory(
+    kind: OperationKind,
+    operationId: string,
+  ): Promise<{
+    items: Array<{
+      id: string
+      fromStatus: string | null
+      toStatus: string
+      reason: string | null
+      changedById: string | null
+      changedAt: string
+    }>
+  }> {
     return this.#http.request('GET', `${this.#op(kind, operationId)}/status-history`)
   }
 
-  /** All links in the vault. */
-  listRelations(params: PageParams = {}): Promise<OperationRelationsPage> {
+  /**
+   * All links in the vault. Both directions: an operation appears here when
+   * it is the source AND when it is the target, so filtering by
+   * `sourceOperationId` alone will miss half of its links.
+   */
+  listRelations(params: ListRelationsParams = {}): Promise<OperationRelationsPage> {
     return this.#http.request<OperationRelationsPage>(
       'GET',
       `/api/v1/vaults/${this.#vault}/operation-relations`,
@@ -91,9 +142,23 @@ export class OperationsResource {
     )
   }
 
-  /** An incoming payment in detail. */
-  deposit(depositId: string): Promise<unknown> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/deposits/${seg(depositId)}`)
+  /**
+   * An incoming payment in detail.
+   *
+   * `amlLevel`/`amlScore`/`amlCheckedAt` are a SNAPSHOT of what was known
+   * about the SENDER when the money landed, not the sender's risk today. A
+   * `null` level means nobody checked — not that there is no risk — so it
+   * must not be drawn as a clean result; `/aml/score` answers for the present.
+   *
+   * `amount` is raw smallest units and `amountDecimal` is the same number
+   * scaled by the token's decimals. `usdRate` is the rate at the moment of
+   * the deposit and is `null` when no rate was available.
+   */
+  deposit(depositId: string): Promise<IncomingTransactionDetail> {
+    return this.#http.request<IncomingTransactionDetail>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/deposits/${seg(depositId)}`,
+    )
   }
 
   /**

package/src/resources/registries.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../core/http.js'
 import type {
+  AmlValue,
   CreateNetworkBody,
   CreateTokenBody,
   EvaluationRequest,
@@ -11,6 +12,38 @@ import type {
   TokenWithNetwork,
 } from '../generated/types.js'
 
+/**
+ * The AML risk of one address, as `amlScore` returns it.
+ *
+ * Hand-written because the API declares this body inline rather than as a
+ * named schema, so `src/generated/types.ts` has no name for it. The risk
+ * LEVEL is reused from the generated policy selector (`AmlValue.minLevel`):
+ * one list, so a sixth level added to the API cannot be read here as five.
+ */
+export interface AmlScore {
+  address: string
+  /** `tron` or `ethereum`, decided by the shape of the address. */
+  network: string
+  /** 0–10. Do not threshold on it — see `level`. */
+  score: number
+  /**
+   * Branch on THIS, not on `score`: the provider recalibrates its scores and
+   * ships its own thresholds with every answer, so a rule written in numbers
+   * drifts with their calibration while the level stays put.
+   */
+  level: AmlValue['minLevel']
+  /** Themes of the address's links: `Blacklisted`, `Sanction list`, `Exchange`… */
+  categories: Array<{ name: string; count: number }>
+  /** Counts of linked entities per level, plus incoming/outgoing/total. */
+  summary: Record<string, number> | null
+  /** When the PROVIDER ran the check. */
+  checkedAt: string
+  /** When we received it. With `cached: true` this is the age of the cache entry. */
+  fetchedAt: string
+  /** `true` — served from the 24h cache, no external call was made. */
+  cached: boolean
+}
+
 /**
  * Registries and preflight checks. Not scoped to a vault.
  *
@@ -34,9 +67,20 @@ export class RegistriesResource {
     return this.#http.request<TokenWithNetwork[]>('GET', '/api/v1/tokens', { query: { ...params } })
   }
 
-  /** USD rates used to value operations. */
-  rates(): Promise<RatesResponse> {
-    return this.#http.request<RatesResponse>('GET', '/api/v1/rates')
+  /**
+   * USD rates used to value operations.
+   *
+   * `codes` narrows the answer to the tokens you name; without it every
+   * enabled token of the registry comes back. The parameter goes out as one
+   * comma-separated value, which is what the endpoint parses — an array is
+   * joined for you.
+   *
+   * Rates are fetched live on every call and NOT cached, so this is the
+   * "right now" figure. The rate stored on an operation is a separate thing:
+   * a snapshot taken when it was created.
+   */
+  rates(params: { codes?: string | readonly string[] | undefined } = {}): Promise<RatesResponse> {
+    return this.#http.request<RatesResponse>('GET', '/api/v1/rates', { query: { ...params } })
   }
 
   /**
@@ -51,20 +95,55 @@ export class RegistriesResource {
    *   • it has no verdict for "there is nobody to sign". A chain that cannot
    *     be satisfied still previews as `requireApproval`, and the refusal
    *     arrives only when the request is actually created.
+   *
+   * `explain: true` adds a per-policy TRACE to the answer — why each policy
+   * did or did not apply, the main tool for debugging a rule set. All four
+   * decisions carry it then, a bare `deny` included, which is where it earns
+   * its keep: one entry per ENABLED policy the person has for this action,
+   * saying whether it applied and, for one that did not, the selector it
+   * failed on when one can be named. Somebody with no such policy gets an
+   * empty array rather than no key.
+   *
+   * Without the flag there is no `trace` at all. `EvaluationResult` keeps the
+   * field optional on every branch for that reason: the document describes
+   * both modes with one schema. The verdict itself is computed the same way
+   * either way.
    */
-  evaluate(input: EvaluationRequest): Promise<EvaluationResult> {
-    return this.#http.request<EvaluationResult>('POST', '/api/v1/evaluate', { body: input })
+  evaluate(
+    input: EvaluationRequest,
+    options: { explain?: boolean | undefined } = {},
+  ): Promise<EvaluationResult> {
+    return this.#http.request<EvaluationResult>('POST', '/api/v1/evaluate', {
+      body: input,
+      query: { ...options },
+    })
   }
 
   /**
-   * Current AML risk of an address.
+   * Current AML risk of an address. Call it BEFORE sending: the transfer form
+   * should show the recipient's risk before the button is pressed, not after.
+   *
+   * "Not checked" is NOT a value of `level` here. This endpoint either
+   * answers with a level or fails — 502 `AML_UNAVAILABLE` when the provider
+   * times out, 5xxs, or has no key configured, and 400 when the address
+   * matches neither the TRON nor the Ethereum shape. Treat the 502 as
+   * "could not check", never as a green badge; the `null` level that means
+   * "nobody ever checked" lives on OPERATIONS, not on this answer.
    *
-   * A missing level means NOT CHECKED, not "no risk" — a green badge on an
-   * unchecked address misleads about money. The level, not the numeric score,
-   * is the stable contract: providers recalibrate scores.
+   * What comes back is a snapshot cached for 24 hours — `cached` says whether
+   * an external call happened. `refresh` forces a fresh one and is the only
+   * way past the cache, so it belongs on an explicit user action ("check
+   * again"): it is slower and costs a provider call every time.
+   *
+   * Note what this is NOT: the risk recorded on a transfer or a deposit is a
+   * separate snapshot taken at the moment of the operation. This figure moves
+   * over time, so it will disagree with the one stored on an old operation,
+   * and that is the point of storing it there.
    */
-  amlScore(address: string): Promise<unknown> {
-    return this.#http.request('GET', '/api/v1/aml/score', { query: { address } })
+  amlScore(address: string, options: { refresh?: boolean | undefined } = {}): Promise<AmlScore> {
+    return this.#http.request<AmlScore>('GET', '/api/v1/aml/score', {
+      query: { address, ...options },
+    })
   }
 
   /**