@v3finance/core-sdk 0.1.0 → 0.2.0

package/src/resources/balances.ts

@@ -1,18 +1,142 @@
 import { seg, type HttpClient } from '../core/http.js'
 import type { PageParams } from '../core/pagination.js'
-import type { BalancesAsOf, LedgerEntry, VaultBalancesResponse } from '../generated/types.js'
+import type {
+  BalancesAsOf,
+  BalancesAsOfAccount,
+  LedgerAccountItem,
+  LedgerEntriesPage,
+  LedgerEntry,
+  LedgerPosting as GeneratedLedgerPosting,
+  VaultBalancesResponse,
+} from '../generated/types.js'
+
+/**
+ * What a ledger account is FOR. A strict alias of the generated enum.
+ *
+ * `available` (spendable) and `reserved` (held for a transfer in flight)
+ * belong to an ADDRESS. `external` and `adjustment` are vault-level: they are
+ * the far side of the double entry — the outside world, and manual
+ * corrections — and belong to no address, which is why
+ * `LedgerAccountItem.address` is nullable.
+ */
+export type LedgerPurpose = LedgerAccountItem['purpose']
 
 export interface BalancesParams extends PageParams {
   /** Roll up the whole vault instead of listing per address. */
   summary?: boolean | undefined
   addressId?: string | undefined
   token?: string | undefined
-  /** `available` is spendable; `reserved` is held for transfers in flight. */
-  purpose?: 'available' | 'reserved' | undefined
+  /**
+   * Narrows `accounts` ONLY. `totals` ignores it and always reports
+   * `available` plus `reserved`, so `purpose: 'external'` lists the
+   * vault-level accounts beside totals that do not count them — the two
+   * halves of the answer are not filtered the same way.
+   */
+  purpose?: LedgerPurpose | undefined
   /** Include addresses shared with you. Off by default. */
   includeShared?: boolean | undefined
 }
 
+/**
+ * `balances/as-of` parameters, beyond the moment itself.
+ *
+ * A superset of what `list()` takes: a replay can also be narrowed to a token
+ * id or a folder.
+ *
+ * Written by hand, like every query type in this package: the generator emits
+ * schemas and never looks at `parameters`, so there is no generated shape to
+ * alias. `test/queryParams.test.ts` holds it to the document instead — a
+ * parameter the endpoint declares and this interface lacks fails there.
+ */
+export interface BalancesAsOfParams {
+  /** Token code, e.g. `usdt`. Ignored when `tokenId` is given. */
+  token?: string | undefined
+  /** Registry token id. Wins over `token`. */
+  tokenId?: string | undefined
+  addressId?: string | undefined
+  /**
+   * Every address in the folder, by its CURRENT membership — a replay of past
+   * balances through today's folder. REPLACES `addressId` rather than
+   * intersecting with it, so sending both silently drops `addressId`.
+   */
+  folderId?: string | undefined
+  purpose?: LedgerPurpose | undefined
+  /** Totals only. See the overloads: `accounts` is then ABSENT, not empty. */
+  summary?: boolean | undefined
+  includeShared?: boolean | undefined
+}
+
+/**
+ * What `asOf` answers WITHOUT `summary` — the body with `accounts` present.
+ *
+ * The generated `BalancesAsOf` describes both modes with one schema, so its
+ * `accounts` is optional: absent under `summary: true`, always there
+ * otherwise (an empty array when nothing moved before the moment). This is
+ * the second half of that sentence as a type, so a call that did not ask for
+ * a summary is not made to check for a key that cannot be missing.
+ */
+export type BalancesAsOfWithAccounts = BalancesAsOf & { accounts: BalancesAsOfAccount[] }
+
+/**
+ * What `asOf` answers under `summary: true` — the same body WITHOUT
+ * `accounts`.
+ *
+ * Not an empty array: the key is absent, which is how the API tells "accounts
+ * were not asked for" from "there are none". The document says the same —
+ * `BalancesAsOf.accounts` is optional — and this type is the summary half of
+ * it, with the key removed rather than left optional.
+ *
+ * Spellable without importing it: `Omit<BalancesAsOf, 'accounts'>`.
+ */
+export type BalancesAsOfSummary = Omit<BalancesAsOf, 'accounts'>
+
+/**
+ * One side of a ledger entry. A strict alias of the generated schema.
+ *
+ * Signed, with no `direction` field: which way the money went IS the sign of
+ * `amountRawSigned` — negative means debited from that account. A COMPLETE
+ * entry's postings sum to zero; see `entries` for why the ones you are shown
+ * may not. `ownerId` is the address id, or the vault id for a vault-level
+ * account, and `amountDecimalSigned` falls back to the raw figure when the
+ * posting's token is not in the registry.
+ */
+export type LedgerPosting = GeneratedLedgerPosting
+
+/**
+ * The values `entryType` takes, as the journal REPORTS them.
+ *
+ * Stored as `reserve`/`confirm`/`release` and renamed on the way out, which
+ * is why the filter accepts either spelling: `entryType: 'reserve'` and
+ * `entryType: 'transfer_reserve'` select the same rows. `topup`, `adjustment`
+ * and `genesis` have no transfer stage and are not renamed. `genesis` is the
+ * opening correction written when the ledger was first backfilled; nothing
+ * creates new ones.
+ *
+ * Kept by hand because the document does not carry it as a type: the
+ * generated `LedgerEntry.entryType` is a bare `string` whose DESCRIPTION
+ * lists these six. The API does not close the list either — a stored kind it
+ * has no name for is passed through as it is — so this union types the
+ * FILTER, where a misspelling answers an empty page rather than an error,
+ * and is not forced onto the entries that come back.
+ */
+export type LedgerEntryType =
+  | 'transfer_reserve'
+  | 'transfer_confirm'
+  | 'transfer_refund'
+  | 'topup'
+  | 'adjustment'
+  | 'genesis'
+
+/**
+ * One ledger entry. A strict alias of the generated `LedgerEntry`, kept under
+ * its earlier name.
+ *
+ * `token` is the entry's token by its FIRST posting, taken before postings
+ * are filtered for the caller — so it is present even when `postings` comes
+ * back empty for you.
+ */
+export type LedgerEntryItem = LedgerEntry
+
 /**
  * Balances and the ledger behind them.
  *
@@ -38,31 +162,79 @@ export class BalancesResource {
     )
   }
 
-  /** Balances as they stood at a moment in time, replayed from the ledger. */
-  asOf(at: string, params: { addressId?: string; token?: string } = {}): Promise<BalancesAsOf> {
-    return this.#http.request<BalancesAsOf>(
+  /**
+   * Balances as they stood at a moment in time, replayed from the ledger.
+   *
+   * `at` is positional because it is required — a replay with no instant is
+   * not a replay. `totals` covers `available` and `reserved` only; the
+   * vault-level accounts appear in `accounts` and never in the totals.
+   *
+   * UNITS DIFFER FROM `list()`. In `totals`, `available` and `reserved` are
+   * DECIMAL here — duplicates of `availableDecimal`/`reservedDecimal` — while
+   * the fields of the same name on `list()` are raw smallest units. Raw
+   * figures exist only per account, in `accounts[].balance`. Read the totals
+   * with `parseDecimal`, not `amount`.
+   */
+  asOf(
+    at: string,
+    params?: BalancesAsOfParams & { summary?: false | undefined },
+  ): Promise<BalancesAsOfWithAccounts>
+  /** `summary: true` — totals only, and the body carries no `accounts` key. */
+  asOf(
+    at: string,
+    params: BalancesAsOfParams & { summary: true },
+  ): Promise<BalancesAsOfSummary>
+  /**
+   * `summary` decided at runtime. The answer is then one shape or the other,
+   * so this signature hands back the union rather than guessing: narrow it
+   * with `'accounts' in result`.
+   */
+  asOf(
+    at: string,
+    params: BalancesAsOfParams,
+  ): Promise<BalancesAsOfWithAccounts | BalancesAsOfSummary>
+  asOf(
+    at: string,
+    params: BalancesAsOfParams = {},
+  ): Promise<BalancesAsOfWithAccounts | BalancesAsOfSummary> {
+    return this.#http.request<BalancesAsOfWithAccounts | BalancesAsOfSummary>(
       'GET',
       `/api/v1/vaults/${this.#vault}/balances/as-of`,
       { query: { at, ...params } },
     )
   }
 
-  /** The raw ledger. Append-only: corrections arrive as reversing entries. */
+  /**
+   * The raw ledger. Append-only: corrections arrive as reversing entries.
+   *
+   * Non-admins see only the entries that touch their own addresses, and
+   * within such an entry only their own postings plus the vault-level ones.
+   * The postings of a page therefore need not sum to zero, even though every
+   * complete entry does.
+   */
   entries(
     params: PageParams & {
+      /**
+       * Entries with a posting on this address. For a non-admin it narrows
+       * WITHIN their own addresses: somebody else's id answers an empty page,
+       * not a 403.
+       */
       addressId?: string
-      /** Kind of posting: `reserve`, `confirm`, `release`, `topup`, `adjustment`. */
-      entryType?: string
-      operationType?: string
+      /** Either spelling of the stage — see `LedgerEntryType`. */
+      entryType?: LedgerEntryType | 'reserve' | 'confirm' | 'release' | undefined
+      operationType?: 'deposit' | 'transfer' | undefined
+      /** The transfer or deposit id. Only applied together with `operationType`. */
       operationId?: string
       token?: string
       tokenId?: string
       from?: string
       to?: string
     } = {},
-  ): Promise<{ items: LedgerEntry[]; nextCursor: string | null }> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/ledger/entries`, {
-      query: { ...params },
-    })
+  ): Promise<LedgerEntriesPage> {
+    return this.#http.request<LedgerEntriesPage>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/ledger/entries`,
+      { query: { ...params } },
+    )
   }
 }

package/src/resources/categories.ts

@@ -2,6 +2,9 @@ import { seg, type HttpClient } from '../core/http.js'
 import { toGated, type Gated } from '../core/gated.js'
 import type { PageParams } from '../core/pagination.js'
 import type {
+  AddOperationCategoryApproverBody,
+  AddOperationCategoryFieldBody,
+  AddOperationCategoryGrantBody,
   ApprovalRequestCreated,
   AssignCategoryBody,
   EditAssignmentBody,
@@ -9,13 +12,27 @@ import type {
   CreateOperationCategoryBody,
   OperationCategoriesPage,
   OperationCategory,
+  OperationCategoryApprover,
   OperationCategoryAssignment,
   OperationCategoryAssignmentVersion,
+  OperationCategoryField,
+  OperationCategoryGrant,
+  OperationType as GeneratedOperationType,
   PatchOperationCategoryBody,
+  PatchOperationCategoryFieldBody,
 } from '../generated/types.js'
 
-/** Operation kind in a labelling path: `transfer`, `deposit`, … */
-export type OperationType = string
+/**
+ * Operation kind in a labelling path. Exactly two values exist.
+ *
+ * A strict alias, not `string`. Because `src/index.ts` re-exports this name
+ * explicitly, and an explicit re-export beats `export type *`, the old
+ * `= string` was what consumers actually got for a schema that eight
+ * operations reference by name — so a misspelled kind compiled here and came
+ * back as a 400 from production instead. Every endpoint that takes the kind
+ * as a path segment refuses anything but these two outright.
+ */
+export type OperationType = GeneratedOperationType
 
 /**
  * Configurable labelling of operations.
@@ -74,13 +91,32 @@ export class CategoriesResource {
     return this.#http.request<OperationCategory>('GET', `${this.#catalogue}/${seg(categoryId)}`)
   }
 
-  /** Categories this person may apply to this operation, with their fields. */
-  available(type: OperationType, operationId: string): Promise<unknown> {
+  /**
+   * Categories this person may apply to this operation, with their fields.
+   *
+   * This is the endpoint to build a labelling form from, not `list()`: it
+   * accounts for grants and for access to the operation's own address, and it
+   * leaves out archived fields. `grants` and `approvers` never come back here
+   * — that is access configuration, and only an administrator sees it.
+   */
+  available(
+    type: OperationType,
+    operationId: string,
+  ): Promise<{ items: OperationCategory[] }> {
     return this.#http.request('GET', `${this.#assignments(type, operationId)}/available`)
   }
 
-  /** What is currently applied to an operation. */
-  assignments(type: OperationType, operationId: string): Promise<unknown> {
+  /**
+   * What is currently applied to an operation.
+   *
+   * Only the assignments whose values this person may see; a category they
+   * have no view access to is absent rather than empty. Within a visible one,
+   * sensitive fields come back as `null` with their keys in `redactedFields`.
+   */
+  assignments(
+    type: OperationType,
+    operationId: string,
+  ): Promise<{ items: OperationCategoryAssignment[] }> {
     return this.#http.request('GET', this.#assignments(type, operationId))
   }
 
@@ -129,11 +165,12 @@ export class CategoriesResource {
     return toGated<OperationCategoryAssignment, ApprovalRequestCreated>(res.status, res.data)
   }
 
+  /** Soft: the assignment goes to `removed` and its history survives. */
   removeAssignment(
     type: OperationType,
     operationId: string,
     assignmentId: string,
-  ): Promise<unknown> {
+  ): Promise<{ removed: boolean }> {
     return this.#http.request(
       'DELETE',
       `${this.#assignments(type, operationId)}/${seg(assignmentId)}`,
@@ -166,12 +203,27 @@ export class CategoriesResource {
 
   // --- administrator only -------------------------------------------------
 
-  /** Creates a category. Administrator only. */
+  /**
+   * Creates a category. Administrator only.
+   *
+   * `viewScope`, `assignScope` and `editScope` say what the category opens to
+   * people WITHOUT a grant, and each takes one of two values: `owner_only` —
+   * nothing beyond access through the operation's own address and the
+   * category's grants — or `vault_members`, every member of the vault.
+   *
+   * The API still accepts a third spelling on input, `restricted`, as an
+   * alias of `owner_only`: it is stored as `owner_only` and never comes back
+   * in an answer. `CategoryAccessScope` leaves it out on purpose, so it does
+   * not compile here — send `owner_only`.
+   */
   create(input: CreateOperationCategoryBody): Promise<OperationCategory> {
     return this.#http.request<OperationCategory>('POST', this.#catalogue, { body: input })
   }
 
-  /** Administrator only. `key` cannot be changed. */
+  /**
+   * Administrator only. `key` cannot be changed. The three scopes take the
+   * same two values as on `create`.
+   */
   update(categoryId: string, input: PatchOperationCategoryBody): Promise<OperationCategory> {
     return this.#http.request<OperationCategory>(
       'PATCH',
@@ -180,16 +232,42 @@ export class CategoriesResource {
     )
   }
 
-  /** Administrator only. A field's `key` and `type` are fixed once created. */
-  addField(categoryId: string, input: unknown): Promise<unknown> {
-    return this.#http.request('POST', `${this.#catalogue}/${seg(categoryId)}/fields`, {
-      body: input,
-    })
+  /**
+   * Administrator only. A field's `key` and `type` are fixed once created.
+   *
+   * `currencyFieldKey` is only for `type: 'currency'` and must name a sibling
+   * field of this same category that holds the ticker; the server refuses a
+   * dangling or wrongly typed link with 400 `CATEGORY_FIELD_LINK`.
+   */
+  addField(
+    categoryId: string,
+    input: AddOperationCategoryFieldBody,
+  ): Promise<OperationCategoryField> {
+    return this.#http.request<OperationCategoryField>(
+      'POST',
+      `${this.#catalogue}/${seg(categoryId)}/fields`,
+      { body: input },
+    )
   }
 
-  /** Administrator only. */
-  updateField(categoryId: string, fieldId: string, input: unknown): Promise<unknown> {
-    return this.#http.request(
+  /**
+   * Administrator only.
+   *
+   * `key` and `type` are absent from the body on purpose — they are
+   * immutable, since stored values, reports and snapshots are keyed by them;
+   * `scale` is not patchable either, so a field's precision is decided once.
+   * For `select`, `optionsJson` is the FULL new list and options may only be
+   * added. `archived: true` is how a field is retired, because a field with
+   * history cannot be deleted. Passing `currencyFieldKey: null` drops the
+   * amount↔ticker link, after which reports go back to adding different
+   * currencies into one meaningless total.
+   */
+  updateField(
+    categoryId: string,
+    fieldId: string,
+    input: PatchOperationCategoryFieldBody,
+  ): Promise<OperationCategoryField> {
+    return this.#http.request<OperationCategoryField>(
       'PATCH',
       `${this.#catalogue}/${seg(categoryId)}/fields/${seg(fieldId)}`,
       { body: input },
@@ -197,29 +275,46 @@ export class CategoriesResource {
   }
 
   /** Administrator only. Who approves edits gated by `approvalScope`. */
-  addApprover(categoryId: string, input: unknown): Promise<unknown> {
-    return this.#http.request('POST', `${this.#catalogue}/${seg(categoryId)}/approvers`, {
-      body: input,
-    })
+  addApprover(
+    categoryId: string,
+    input: AddOperationCategoryApproverBody,
+  ): Promise<OperationCategoryApprover> {
+    return this.#http.request<OperationCategoryApprover>(
+      'POST',
+      `${this.#catalogue}/${seg(categoryId)}/approvers`,
+      { body: input },
+    )
   }
 
-  /** Administrator only. */
-  removeApprover(categoryId: string, approverId: string): Promise<unknown> {
+  /** Administrator only. `deleted: false` means there was nothing to remove. */
+  removeApprover(categoryId: string, approverId: string): Promise<{ deleted: boolean }> {
     return this.#http.request(
       'DELETE',
       `${this.#catalogue}/${seg(categoryId)}/approvers/${seg(approverId)}`,
     )
   }
 
-  /** Administrator only. Who may see or edit values of this category. */
-  addGrant(categoryId: string, input: unknown): Promise<unknown> {
-    return this.#http.request('POST', `${this.#catalogue}/${seg(categoryId)}/grants`, {
-      body: input,
-    })
+  /**
+   * Administrator only. Who may see or edit values of this category.
+   *
+   * Idempotent, like every grant in this API: calling it again for the same
+   * subject updates the rights and revives a revoked grant, so there is no
+   * "already exists" error to handle. `canEdit` implies `canView` — the
+   * server fills it in, because the other combination is unenforceable.
+   */
+  addGrant(
+    categoryId: string,
+    input: AddOperationCategoryGrantBody,
+  ): Promise<OperationCategoryGrant> {
+    return this.#http.request<OperationCategoryGrant>(
+      'POST',
+      `${this.#catalogue}/${seg(categoryId)}/grants`,
+      { body: input },
+    )
   }
 
-  /** Administrator only. */
-  removeGrant(categoryId: string, grantId: string): Promise<unknown> {
+  /** Administrator only. Soft revoke; `revoked: false` means no such grant. */
+  removeGrant(categoryId: string, grantId: string): Promise<{ revoked: boolean }> {
     return this.#http.request(
       'DELETE',
       `${this.#catalogue}/${seg(categoryId)}/grants/${seg(grantId)}`,

package/src/resources/counterparties.ts

@@ -110,15 +110,23 @@ export class CounterpartiesResource {
     return toGated<CounterpartyAddressCreated, ApprovalRequestCreated>(res.status, res.data)
   }
 
+  /**
+   * Narrows any allow-list built on this counterparty, so it is gated like
+   * the rest — under the `counterparty_update` policy, not one of its own.
+   *
+   * Operations already attributed to this address KEEP the counterparty: at
+   * the time they happened the address did belong to it, and that is a
+   * historical fact. Only new operations stop matching.
+   */
   async removeAddress(
     counterpartyId: string,
     addressId: string,
-  ): Promise<Gated<unknown, ApprovalRequestCreated>> {
+  ): Promise<Gated<{ deleted: true }, ApprovalRequestCreated>> {
     const res = await this.#http.requestRaw<unknown>(
       'DELETE',
       `${this.#base}/${seg(counterpartyId)}/addresses/${seg(addressId)}`,
     )
-    return toGated<unknown, ApprovalRequestCreated>(res.status, res.data)
+    return toGated<{ deleted: true }, ApprovalRequestCreated>(res.status, res.data)
   }
 }
 
@@ -173,24 +181,33 @@ export class CounterpartyGroupsResource {
     return toGated<CounterpartyGroup, ApprovalRequestCreated>(res.status, res.data)
   }
 
+  /**
+   * WIDENS any allow-list built on this group, and does so the moment it
+   * applies — which is why it is gated by its own policy
+   * (`counterparty_group_add`) rather than riding on the group's update.
+   */
   async addMember(
     groupId: string,
     counterpartyId: string,
-  ): Promise<Gated<unknown, ApprovalRequestCreated>> {
+  ): Promise<Gated<{ added: true }, ApprovalRequestCreated>> {
     const res = await this.#http.requestRaw<unknown>('POST', `${this.#base}/${seg(groupId)}/members`, {
       body: { counterpartyId },
     })
-    return toGated<unknown, ApprovalRequestCreated>(res.status, res.data)
+    return toGated<{ added: true }, ApprovalRequestCreated>(res.status, res.data)
   }
 
+  /**
+   * Payments to this counterparty under the group's allow-list stop at once.
+   * `removed: false` means it was not in the group — not a failure.
+   */
   async removeMember(
     groupId: string,
     counterpartyId: string,
-  ): Promise<Gated<unknown, ApprovalRequestCreated>> {
+  ): Promise<Gated<{ removed: boolean }, ApprovalRequestCreated>> {
     const res = await this.#http.requestRaw<unknown>(
       'DELETE',
       `${this.#base}/${seg(groupId)}/members/${seg(counterpartyId)}`,
     )
-    return toGated<unknown, ApprovalRequestCreated>(res.status, res.data)
+    return toGated<{ removed: boolean }, ApprovalRequestCreated>(res.status, res.data)
   }
 }

package/src/resources/folders.ts

@@ -1,14 +1,17 @@
 import { seg, type HttpClient } from '../core/http.js'
 import type {
   AddFolderAddressBody,
+  AddressAccessGrant,
   AddressGroup,
   AddressGroupDetail,
   AddressGroupsList,
+  AddressSharesList,
   CreateAddressGroupBody,
   GrantGroupBody,
   ParticipantsResponse,
   PatchAddressGroupBody,
   PatchGroupGrantBody,
+  ShareGrantCreated,
 } from '../generated/types.js'
 
 /**
@@ -62,39 +65,92 @@ export class FoldersResource {
     })
   }
 
-  delete(folderId: string): Promise<unknown> {
-    return this.#http.request('DELETE', `${this.#base}/${seg(folderId)}`)
+  /** Deleting takes the membership rows with it, and the grants on the folder. */
+  delete(folderId: string): Promise<{ deleted: boolean }> {
+    return this.#http.request<{ deleted: boolean }>('DELETE', `${this.#base}/${seg(folderId)}`)
   }
 
-  addAddress(folderId: string, input: AddFolderAddressBody): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(folderId)}/members`, { body: input })
+  addAddress(folderId: string, input: AddFolderAddressBody): Promise<{ added: boolean }> {
+    return this.#http.request<{ added: boolean }>(
+      'POST',
+      `${this.#base}/${seg(folderId)}/members`,
+      { body: input },
+    )
   }
 
-  removeAddress(folderId: string, addressId: string): Promise<unknown> {
-    return this.#http.request(
+  /**
+   * Taking an address out ends access that came FROM THE FOLDER. Grants on
+   * the address itself are untouched — they are a separate relationship.
+   */
+  removeAddress(folderId: string, addressId: string): Promise<{ removed: boolean }> {
+    return this.#http.request<{ removed: boolean }>(
       'DELETE',
       `${this.#base}/${seg(folderId)}/members/${seg(addressId)}`,
     )
   }
 
-  /** Grants on the folder itself — everything in it becomes reachable. */
-  grants(folderId: string): Promise<unknown> {
-    return this.#http.request('GET', `${this.#base}/${seg(folderId)}/grants`)
+  /**
+   * Grants on the folder itself — everything in it becomes reachable,
+   * including addresses added later.
+   *
+   * The same shape as the grants on a single address, and each entry carries
+   * `role`: do not rebuild it from the flags on the client, or you end up
+   * with a second translation that diverges from the first on the next right
+   * that is added.
+   *
+   * Owners of the addresses inside are NOT listed — their access comes from
+   * ownership, not from a grant. For people rather than grants, ask
+   * `participants()`.
+   */
+  grants(folderId: string): Promise<AddressSharesList> {
+    return this.#http.request<AddressSharesList>(
+      'GET',
+      `${this.#base}/${seg(folderId)}/grants`,
+    )
   }
 
-  /** Idempotent, and accepts several subjects at once. Check each result. */
-  grant(folderId: string, input: GrantGroupBody): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/${seg(folderId)}/grants`, { body: input })
+  /**
+   * Idempotent: repeating it for the same pair updates the rights and revives
+   * a revoked grant — no 409 to catch, no read-then-PATCH dance.
+   *
+   * With `subjects[]` it answers a batch (`results[]`, one entry per subject,
+   * each independent); with a single subject it answers the grant itself,
+   * hence the union. The all-failed case behaves as it does on
+   * `sharing.share` — 400 carrying the same `results[]` body
+   * (`ShareBatchAllRejected`), which the SDK surfaces as a `CoreError` with
+   * the body in `details`.
+   */
+  grant(folderId: string, input: GrantGroupBody): Promise<ShareGrantCreated> {
+    return this.#http.request<ShareGrantCreated>(
+      'POST',
+      `${this.#base}/${seg(folderId)}/grants`,
+      { body: input },
+    )
   }
 
-  updateGrant(folderId: string, grantId: string, input: PatchGroupGrantBody): Promise<unknown> {
-    return this.#http.request('PATCH', `${this.#base}/${seg(folderId)}/grants/${seg(grantId)}`, {
-      body: input,
-    })
+  /**
+   * `role` sets view and transfer together; the individual flags are the
+   * older way in. `canCreateAddress` is not part of either role and is
+   * changed on its own.
+   */
+  updateGrant(
+    folderId: string,
+    grantId: string,
+    input: PatchGroupGrantBody,
+  ): Promise<AddressAccessGrant> {
+    return this.#http.request<AddressAccessGrant>(
+      'PATCH',
+      `${this.#base}/${seg(folderId)}/grants/${seg(grantId)}`,
+      { body: input },
+    )
   }
 
-  revokeGrant(folderId: string, grantId: string): Promise<unknown> {
-    return this.#http.request('DELETE', `${this.#base}/${seg(folderId)}/grants/${seg(grantId)}`)
+  /** Soft: the row stays as `revoked` for the audit trail. Effective at once. */
+  revokeGrant(folderId: string, grantId: string): Promise<{ revoked: boolean }> {
+    return this.#http.request<{ revoked: boolean }>(
+      'DELETE',
+      `${this.#base}/${seg(folderId)}/grants/${seg(grantId)}`,
+    )
   }
 
   /** People who reach the folder, with the source of each person's access. */