@v3finance/core-sdk 0.1.0 → 0.2.1

package/src/index.ts

@@ -11,7 +11,20 @@
  * Signing up is possible only on an administrator's invitation.
  */
 
-export { CoreClient, type VaultScope, type VaultSummary, type Profile } from './client.js'
+export { CoreClient, type VaultScope } from './client.js'
+
+/**
+ * Kept so that existing imports keep resolving. Both are now strict aliases
+ * of generated schemas — `VaultSummary` of `VaultListItem`, `Profile` of
+ * `UserProfile` — and new code should name those instead.
+ *
+ * They are listed apart from `CoreClient` on purpose: an explicit re-export
+ * SHADOWS the same name coming from `export type * from './generated/types'`
+ * below, so a hand-written type parked in this list quietly becomes the one
+ * consumers get. Anything added here has to be identical to the schema it
+ * covers, or carry a name the schemas do not use.
+ */
+export type { VaultSummary, Profile } from './client.js'
 
 export {
   HttpClient,
@@ -76,13 +89,29 @@ export {
 } from './resources/addresses.js'
 
 export { TransfersResource, type VoteInput } from './resources/transfers.js'
-export { HistoryResource, type HistoryParams } from './resources/history.js'
+export {
+  HistoryResource,
+  type HistoryParams,
+  type HistoryStatusFilter,
+} from './resources/history.js'
 export { MeResource } from './resources/me.js'
 export { SharingResource } from './resources/sharing.js'
 export { FoldersResource } from './resources/folders.js'
 export { MembersResource } from './resources/members.js'
-export { RegistriesResource } from './resources/registries.js'
+export { RegistriesResource, type AmlScore } from './resources/registries.js'
 export { CategoriesResource, type OperationType } from './resources/categories.js'
+/**
+ * `ReportSnapshotListItem` and `ReportSnapshotDetail` are also the names of
+ * generated schemas, and listing them here shadows those. That is safe only
+ * because both are strict aliases (`export type X = GeneratedX`) — see the
+ * note on `VaultSummary` above, and `test/nameShadowing.test.ts`, which fails
+ * the moment one of them stops being identical. The same goes for
+ * `LedgerPosting` in the balances block below.
+ *
+ * The report schemas themselves — `TransactionActivityReport`,
+ * `BalancePositionReport`, `AnyReport` and the rest of what `ReportResult`
+ * maps to — are not listed: they reach consumers through `export type *`.
+ */
 export {
   ReportsResource,
   type ReportType,
@@ -90,12 +119,40 @@ export {
   type ReportParams,
   type ReportResult,
   type ReportSnapshotListItem,
+  type ReportSnapshotDetail,
+  type DrilldownQuery,
+  type DrilldownFilters,
+  type DrilldownSelection,
 } from './resources/reports.js'
-export { AdminResource } from './resources/admin.js'
+export {
+  AdminResource,
+  type PlatformRole,
+  type PolicyRow,
+  type PolicyRowWithGroup,
+  type VaultPoliciesParams,
+} from './resources/admin.js'
 export { AuthResource } from './resources/auth.js'
-export { OperationsResource, type OperationKind } from './resources/operations.js'
-export { ApprovalsResource, type ListApprovalsParams } from './resources/approvals.js'
-export { BalancesResource, type BalancesParams } from './resources/balances.js'
+export {
+  OperationsResource,
+  type OperationKind,
+  type ListRelationsParams,
+} from './resources/operations.js'
+export {
+  ApprovalsResource,
+  type ListApprovalsParams,
+  type ApprovalRequestStatus,
+} from './resources/approvals.js'
+export {
+  BalancesResource,
+  type BalancesParams,
+  type BalancesAsOfParams,
+  type BalancesAsOfSummary,
+  type BalancesAsOfWithAccounts,
+  type LedgerEntryItem,
+  type LedgerEntryType,
+  type LedgerPosting,
+  type LedgerPurpose,
+} from './resources/balances.js'
 export {
   CounterpartiesResource,
   CounterpartyGroupsResource,

package/src/resources/addresses.ts

@@ -1,20 +1,29 @@
 import { seg, type HttpClient } from '../core/http.js'
 import type { Page, PageParams } from '../core/pagination.js'
 import { toGated, type Gated } from '../core/gated.js'
-
-/** Returned when creating an address required approval instead of running. */
-export interface PendingApproval {
-  status: string
-  approvalRequestId: string
-  approvalThreshold: number
-}
 import type { Address, AddressDetail } from './types.js'
 import type {
   CreateAddressBody,
   CreateAddressResult,
   PatchAddressBody,
+  PendingApproval as GeneratedPendingApproval,
 } from '../generated/types.js'
 
+/**
+ * Returned when creating an address required approval instead of running.
+ *
+ * A strict alias, not a hand-written copy. The copy declared `status: string`
+ * and, because `src/index.ts` re-exports this name explicitly, it won the
+ * contest against `export type *` and became what consumers saw — a wider
+ * type than the API can produce, where the only value is the literal
+ * `"awaiting_approval"`.
+ *
+ * Do not reach for `status` to tell the two outcomes apart: `Gated` already
+ * distinguishes them by `outcome`, and this branch is only ever reached when
+ * nothing was created.
+ */
+export type PendingApproval = GeneratedPendingApproval
+
 export interface ListAddressesParams extends PageParams {
   /** Token code: `usdt`, `a7a5`. */
   token?: string | undefined
@@ -61,7 +70,14 @@ export class AddressesResource {
     return toGated<CreateAddressResult, PendingApproval>(res.status, res.data)
   }
 
-  /** Metadata only: this touches neither money nor the derivation path. */
+  /**
+   * Metadata only: this touches neither money nor the derivation path.
+   *
+   * Answers with the same row as the listing — `owner`, `access` and
+   * `sharing` included — so it can replace the address in a list without a
+   * refetch. Recent operations and `shares`, which `get()` carries, are not
+   * in it.
+   */
   update(addressId: string, input: PatchAddressBody): Promise<Address> {
     return this.#http.request<Address>('PATCH', `${this.#base}/${seg(addressId)}`, { body: input })
   }

package/src/resources/admin.ts

@@ -1,8 +1,17 @@
 import { seg, type HttpClient } from '../core/http.js'
 import type { PageParams } from '../core/pagination.js'
 import type {
+  AcceptDebugBody,
+  AcceptResult,
+  ActionType,
   CreateInvitationBody,
+  Effect,
+  Invitation,
+  InvitationListItem,
+  InvitationPublic,
+  Membership,
   PolicyGroup,
+  PolicyGroupWithCounts,
   PolicyTableItem,
   PolicyWithRules,
   CreateSeatBody,
@@ -17,10 +26,49 @@ import type {
   PolicyDetail,
   PolicyGroupDetail,
   PolicyVersionList,
+  UserGroupItem,
   VaultPoliciesPage,
   VisibilityGrant,
 } from '../generated/types.js'
 
+/**
+ * A policy as the two LISTING endpoints return it. A strict alias of the
+ * generated `PolicyTableItem`, kept under its earlier name.
+ *
+ * There is NO `conditionJson` and no `approvalJson` here: neither listing
+ * selects them, so a row cannot tell you whether a policy is conditional —
+ * and treating the absence as "applies always" is the opposite of what a
+ * condition usually says. Load one policy (`policies.get`) when you need the
+ * rule itself; the vault-scoped page (`vault().policies`) does carry both
+ * fields.
+ */
+export type PolicyRow = PolicyTableItem
+
+/** Filters of the vault-scoped policy page (`vault().policies`). */
+export interface VaultPoliciesParams extends PageParams {
+  actionType?: ActionType | undefined
+  /**
+   * `requireApproval` is accepted here and nowhere else. A policy's own
+   * effect has been `allow | block` only since approval became a property of
+   * an allowing policy rather than an effect of its own, so this third value
+   * exists for rows written before that change — not for new ones.
+   */
+  effect?: Effect | 'requireApproval' | undefined
+  enabled?: boolean | undefined
+}
+
+/** A policy from the flat vault listing, which also names its owner group. */
+export interface PolicyRowWithGroup extends PolicyRow {
+  groupId: string
+  group: {
+    id: string
+    code: string
+    name: string
+    color: string | null
+    emoji: string | null
+  }
+}
+
 /**
  * Administrative endpoints.
  *
@@ -33,6 +81,12 @@ import type {
  * this OBJECT" — grants — lives with the resources it belongs to
  * (`sharing`, `folders`, `categories`).
  */
+/**
+ * The PLATFORM role, from the spec's own enum. Not a role inside a vault —
+ * a platform `admin` sees every vault while belonging to none.
+ */
+export type PlatformRole = 'admin' | 'user'
+
 export class AdminResource {
   readonly #http: HttpClient
 
@@ -63,15 +117,26 @@ export class AdminResource {
     /**
      * `vaultId` is REQUIRED — the endpoint lists policies of one vault and
      * answers 400 without it. It is also NOT paginated: everything comes
-     * back in one array.
+     * back in one array, sorted group then code.
+     *
+     * `actionType` is spelled out rather than left as a string because the
+     * API does not validate it here: an unrecognised value is passed to the
+     * query as-is and comes back as an EMPTY list, which reads like "this
+     * vault has no transfer policies" instead of "you misspelled it". The
+     * vault-scoped twin (`vault().policies`) declares the same ten values as
+     * an enum, so one spelling serves both.
+     *
+     * `effect` is `allow | block` only. Approval stopped being an effect when
+     * it became a property of an allowing policy; the vault-scoped twin still
+     * accepts the historical third value, this one does not and answers 400.
      */
     list: (params: {
       vaultId: string
-      groupId?: string
-      actionType?: string
-      effect?: string
-      enabled?: boolean
-    }) => this.#http.request<{ items: PolicyTableItem[] }>('GET', '/api/v1/policies', {
+      groupId?: string | undefined
+      actionType?: ActionType | undefined
+      effect?: Effect | undefined
+      enabled?: boolean | undefined
+    }) => this.#http.request<{ items: PolicyRowWithGroup[] }>('GET', '/api/v1/policies', {
       query: { ...params },
     }),
 
@@ -109,10 +174,23 @@ export class AdminResource {
     get: (groupId: string) =>
       this.#http.request<PolicyGroupDetail>('GET', `/api/v1/policy-groups/${seg(groupId)}`),
 
-    policies: (groupId: string) =>
-      this.#http.request('GET', `/api/v1/policy-groups/${seg(groupId)}/policies`),
+    /** This group's policies for a table view: every field but the rules. */
+    policies: (groupId: string, params: { actionType?: ActionType | undefined } = {}) =>
+      this.#http.request<PolicyRow[]>('GET', `/api/v1/policy-groups/${seg(groupId)}/policies`, {
+        query: { ...params },
+      }),
 
-    /** What this group's members can reach. */
+    /**
+     * What this group's members can reach: the group, its member count, its
+     * policies and the three kinds of grant held by the group as a subject
+     * (addresses, member visibility, operation categories).
+     *
+     * Left untyped. The API declares this body inline, so there is no
+     * generated name to import, and it nests four different resources —
+     * hand-writing them here would add exactly the kind of duplicated shape
+     * that drifts from the API with nothing to notice it. Narrow it at the
+     * call site, or read the single-purpose endpoints.
+     */
     access: (groupId: string) =>
       this.#http.request('GET', `/api/v1/policy-groups/${seg(groupId)}/access`),
 
@@ -129,13 +207,21 @@ export class AdminResource {
      * used to drift apart, leaving people with policies but no membership.
      */
     addMember: (groupId: string, userId: string) =>
-      this.#http.request('POST', `/api/v1/policy-groups/${seg(groupId)}/members`, {
+      this.#http.request<Membership>('POST', `/api/v1/policy-groups/${seg(groupId)}/members`, {
         body: { userId },
       }),
 
-    /** Takes the MEMBERSHIP id, not the user id — a user id answers 404. */
+    /**
+     * Takes the MEMBERSHIP id, not the user id — a user id answers 404. The
+     * id comes from `users.policyGroups`, which returns it as `membershipId`
+     * for this purpose.
+     *
+     * Removing somebody from their last group does NOT remove them from the
+     * vault: membership is its own record, so they stay in the directory with
+     * no policies — able to be granted access, refused every action.
+     */
     removeMember: (groupId: string, membershipId: string) =>
-      this.#http.request(
+      this.#http.request<{ deleted: true }>(
         'DELETE',
         `/api/v1/policy-groups/${seg(groupId)}/members/${seg(membershipId)}`,
       ),
@@ -144,27 +230,60 @@ export class AdminResource {
   // --- people -------------------------------------------------------------
 
   readonly users = {
-    policyGroups: (userId: string) =>
-      this.#http.request('GET', `/api/v1/users/${seg(userId)}/policy-groups`),
+    /**
+     * Every group this person is in, each with the `membershipId` that
+     * `policyGroups.removeMember` needs. Without `vaultId` it spans ALL
+     * vaults, so filter when you are rendering one vault's screen.
+     */
+    policyGroups: (userId: string, params: { vaultId?: string | undefined } = {}) =>
+      this.#http.request<UserGroupItem[]>('GET', `/api/v1/users/${seg(userId)}/policy-groups`, {
+        query: { ...params },
+      }),
 
-    /** The PLATFORM role, not a role within a vault. The two are different. */
-    setRole: (userId: string, role: string) =>
-      this.#http.request('PATCH', `/api/v1/users/${seg(userId)}/role`, { body: { role } }),
+    /**
+     * The PLATFORM role, not a role within a vault. The two are different:
+     * a platform `admin` sees every vault while belonging to none, whereas a
+     * vault membership carries its own role.
+     *
+     * The parameter is narrowed to the two values the spec declares, which is
+     * worth the compile error on a privilege path: `string` here let a caller
+     * pass anything and find out from a 400 — after sending a role change.
+     * The RESPONSE keeps `role: string`, because the spec declares it bare and
+     * narrowing an answer we do not control would be a guess.
+     */
+    setRole: (userId: string, role: PlatformRole) =>
+      this.#http.request<{ id: string; email: string; role: string }>(
+        'PATCH',
+        `/api/v1/users/${seg(userId)}/role`,
+        { body: { role } },
+      ),
   }
 
   /** Vault-scoped administrative listings and creation. */
   vault(vaultCode: string): {
-    invitations: () => Promise<unknown>
-    policies: (params?: Record<string, string | number | boolean>) => Promise<VaultPoliciesPage>
-    policyGroups: () => Promise<unknown>
+    invitations: (params?: {
+      status?: 'pending' | 'accepted' | 'revoked' | undefined
+    }) => Promise<InvitationListItem[]>
+    policies: (params?: VaultPoliciesParams) => Promise<VaultPoliciesPage>
+    policyGroups: () => Promise<PolicyGroupWithCounts[]>
     createSeat: (input: CreateSeatBody) => Promise<SeatCreated>
   } {
     const base = `/api/v1/vaults/${seg(vaultCode)}`
     return {
-      invitations: () => this.#http.request('GET', `${base}/invitations`),
+      /**
+       * Every invitation of the vault, newest first. The magic-link TOKEN is
+       * not in the listing — only `invitations.get` returns it, so that it
+       * cannot leak through a screenshot or a log of a list view.
+       */
+      invitations: (params = {}) =>
+        this.#http.request<InvitationListItem[]>('GET', `${base}/invitations`, {
+          query: { ...params },
+        }),
       policies: (params = {}) =>
-        this.#http.request<VaultPoliciesPage>('GET', `${base}/policies`, { query: params }),
-      policyGroups: () => this.#http.request('GET', `${base}/policy-groups`),
+        this.#http.request<VaultPoliciesPage>('GET', `${base}/policies`, { query: { ...params } }),
+      /** Groups with `_count` of their policies and members. No cursor. */
+      policyGroups: () =>
+        this.#http.request<PolicyGroupWithCounts[]>('GET', `${base}/policy-groups`),
       /**
        * Creates a "seat": an account prepared in advance, before the person's
        * email is known, handed over as a link or a QR code. The link is
@@ -177,22 +296,44 @@ export class AdminResource {
   }
 
   readonly invitations = {
-    /** Public: lets an invited person see what they were invited to. */
+    /**
+     * Public: lets an invited person see what they were invited to — the
+     * vault and the groups, no token echoed back. The only endpoint here
+     * that needs no session, because it is what the /accept page calls.
+     *
+     * A revoked or already-accepted invitation answers 410, not 404: the
+     * difference is worth showing, since "this link was withdrawn" and "this
+     * link never existed" lead somewhere different.
+     */
     byToken: (token: string) =>
-      this.#http.request('GET', `/api/v1/invitations/by-token/${seg(token)}`),
+      this.#http.request<InvitationPublic>(
+        'GET',
+        `/api/v1/invitations/by-token/${seg(token)}`,
+      ),
 
+    /** The one place the magic-link token is returned. */
     get: (invitationId: string) =>
       this.#http.request<InvitationDetail>('GET', `/api/v1/invitations/${seg(invitationId)}`),
 
     create: (input: CreateInvitationBody) =>
       this.#http.request<InvitationCreated>('POST', '/api/v1/invitations', { body: input }),
 
+    /** Answers the invitation itself, now `revoked`. Already revoked → 400. */
     revoke: (invitationId: string) =>
-      this.#http.request('POST', `/api/v1/invitations/${seg(invitationId)}/revoke`),
+      this.#http.request<Invitation>('POST', `/api/v1/invitations/${seg(invitationId)}/revoke`),
 
-    /** Accepts an invitation without the email round-trip. For debugging. */
-    acceptDebug: (body: unknown) =>
-      this.#http.request('POST', '/api/v1/invitations/accept-debug', { body }),
+    /**
+     * Accepts an invitation without the email round-trip, for an account that
+     * already exists. For debugging and curl tests: in the real flow this
+     * happens inside the sign-up hook.
+     *
+     * Matches on the EMAIL in the body, not on a token — it finds the pending
+     * invitation for that address. No pending invitation → 404; the user
+     * already attached to another invitation → 400, so a repeat is refused
+     * rather than duplicating memberships.
+     */
+    acceptDebug: (body: AcceptDebugBody) =>
+      this.#http.request<AcceptResult>('POST', '/api/v1/invitations/accept-debug', { body }),
   }
 
   /**
@@ -204,15 +345,27 @@ export class AdminResource {
    * here.
    */
   visibilityGrants(vaultCode: string): {
-    list: () => Promise<unknown>
+    list: (params?: {
+      subjectUserId?: string | undefined
+      subjectGroupId?: string | undefined
+      includeRevoked?: boolean | undefined
+    }) => Promise<{ items: VisibilityGrant[] }>
     create: (input: CreateVisibilityGrantBody) => Promise<VisibilityGrant>
-    revoke: (grantId: string) => Promise<unknown>
+    revoke: (grantId: string) => Promise<{ revoked: true }>
   } {
     const base = `/api/v1/vaults/${seg(vaultCode)}/visibility-grants`
     return {
-      list: () => this.#http.request('GET', base),
+      /**
+       * Active grants with the cards of subject and target group. The subject
+       * filters answer "what is open to this person or group", which is what
+       * their detail screen needs; `includeRevoked` adds the soft-deleted
+       * rows, the only way to see what access was withdrawn and when.
+       */
+      list: (params = {}) =>
+        this.#http.request<{ items: VisibilityGrant[] }>('GET', base, { query: { ...params } }),
       create: (input) => this.#http.request<VisibilityGrant>('POST', base, { body: input }),
-      revoke: (grantId) => this.#http.request('DELETE', `${base}/${seg(grantId)}`),
+      /** Soft: the row stays as `revoked`. Effective immediately. */
+      revoke: (grantId) => this.#http.request<{ revoked: true }>('DELETE', `${base}/${seg(grantId)}`),
     }
   }
 }

package/src/resources/approvals.ts

@@ -4,14 +4,30 @@ import { toGated, type Gated } from '../core/gated.js'
 import type {
   ApprovalRequestCreated,
   ApprovalRequestDetail,
-  CompositeApplied,
   ApprovalRequestsPage,
+  CompositeApplied,
   CreateCompositeBody,
+  RequestVoteResult,
   VoteBody,
 } from '../generated/types.js'
 
+/**
+ * Status of an approval REQUEST — and in UPPER CASE.
+ *
+ * That is the trap this type exists for: a transfer's status is lowercase
+ * (`awaiting_approval`, `confirmed`), a request's is not, and the two live
+ * side by side on the same screen. `status: 'pending'` used to compile and
+ * answer 400.
+ *
+ * `APPROVED` is about the VOTES, not about the outcome. "Approved but it
+ * failed to apply" is still `APPROVED`, and the difference shows up in
+ * `applyError` and `resolvedResultId` on the vote's answer — so a listing
+ * filtered to `APPROVED` is not a listing of things that happened.
+ */
+export type ApprovalRequestStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED'
+
 export interface ListApprovalsParams extends PageParams {
-  status?: string | undefined
+  status?: ApprovalRequestStatus | undefined
   action?: string | undefined
   /** Requests I STARTED. Not the same as the ones waiting for me. */
   mine?: boolean | undefined
@@ -52,15 +68,45 @@ export class ApprovalsResource {
     return this.#http.request<ApprovalRequestDetail>('GET', `${this.#base}/${seg(requestId)}`)
   }
 
-  vote(requestId: string, input: VoteBody): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(requestId)}/approvals`, { body: input })
+  /**
+   * Typed from `RequestVoteResult`, which the spec declares as a component but
+   * never `$ref`s — the operation inlines its 200 instead. The two were
+   * compared key by key and type by type and are the same schema; the only
+   * difference is an `additionalProperties: false` that does not reach the
+   * TypeScript shape. Worth saying, because a component nothing references
+   * usually means the opposite: an orphan left behind, which is what the
+   * `Address` schema turned out to be.
+   *
+   * Read `finalized` with `applyError`: a vote can finalize a request AND
+   * fail to apply it, and then the money has not moved.
+   */
+  vote(requestId: string, input: VoteBody): Promise<RequestVoteResult> {
+    return this.#http.request<RequestVoteResult>(
+      'POST',
+      `${this.#base}/${seg(requestId)}/approvals`,
+      { body: input },
+    )
   }
 
-  /** Cancels your own request and releases whatever it reserved. */
-  cancel(requestId: string, reason?: string): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(requestId)}/cancel`, {
-      body: reason === undefined ? {} : { reason },
-    })
+  /**
+   * Cancels your own request and releases whatever it reserved.
+   *
+   * Only while the request is `PENDING`, and only as its initiator or as an
+   * admin — the admin case exists so a request whose initiator is gone can
+   * still be cleared instead of holding the reserve forever.
+   *
+   * @param reason IGNORED BY THE SERVER, and no longer sent. The endpoint
+   * declares no request body and the handler never reads one, so the reason
+   * reached nothing: not the cancellation event, not the audit trail. It
+   * stays in the signature only so that existing callers keep compiling —
+   * drop it from your call, and record the reason wherever you need it to
+   * actually survive.
+   */
+  cancel(requestId: string, reason?: string): Promise<{ status: 'CANCELLED' }> {
+    return this.#http.request<{ status: 'CANCELLED' }>(
+      'POST',
+      `${this.#base}/${seg(requestId)}/cancel`,
+    )
   }
 
   /**