@v3finance/core-sdk 0.1.0 → 0.2.0

package/src/resources/reports.ts

@@ -1,10 +1,29 @@
 import { seg, type HttpClient, type Query } from '../core/http.js'
 import type {
-  ActivityReport,
+  AccountStatementReport,
+  AddressActivityReport,
+  AnyReport,
+  ApprovalActivityReport,
+  AssetMovementReport,
+  BalancePositionReport,
   CategoryAnalytics,
+  CounterpartyActivityReport,
+  CounterpartyGroupActivityReport,
+  CreateReportExportBody,
+  CreateReportSnapshotBody,
+  CreateReportTemplateBody,
+  DrilldownResponse,
+  OperationsExceptionsReport,
+  PatchReportTemplateBody,
+  ReportDrilldownBody,
   ReportExport,
+  ReportMeta,
   ReportSnapshot,
+  ReportSnapshotDetail as GeneratedReportSnapshotDetail,
+  ReportSnapshotList,
+  ReportSnapshotListItem as GeneratedReportSnapshotListItem,
   ReportTemplate,
+  TransactionActivityReport,
 } from '../generated/types.js'
 
 /**
@@ -12,18 +31,13 @@ import type {
  * the `?type=` alias, in a snapshot's `reportType` and in `report.type` of
  * the answer. Paths and the alias once used kebab-case while snapshots used
  * snake, so a client with a single `fetchReport` got a 400 on every snapshot.
+ *
+ * Taken from the document's own enum (`report.type` of an answer) rather than
+ * spelled out here, so a type the API grows shows up at once — as a compile
+ * error in `ReportParams` and `ReportResult`, which are keyed by it and would
+ * then lack an entry.
  */
-export type ReportType =
-  | 'account_statement'
-  | 'address_activity'
-  | 'approval_activity'
-  | 'asset_movement'
-  | 'balance_position'
-  | 'category_analytics'
-  | 'counterparty_activity'
-  | 'counterparty_group_activity'
-  | 'operations_exceptions'
-  | 'transaction_activity'
+export type ReportType = ReportMeta['type']
 
 /**
  * Filters shared by the reporting endpoints.
@@ -41,8 +55,8 @@ export interface ReportFilters {
   to?: string | undefined
   timezone?: string | undefined
   /** Which date the period is measured by. */
-  dateBasis?: string | undefined
-  groupBy?: string | undefined
+  dateBasis?: ReportMeta['dateBasis'] | undefined
+  groupBy?: 'day' | 'week' | 'month' | undefined
   /** Currency the totals are expressed in. */
   baseCurrency?: string | undefined
   statuses?: readonly string[] | undefined
@@ -69,12 +83,12 @@ export interface ReportFilters {
   minimumAmount?: string | undefined
   maximumAmount?: string | undefined
   includeInternal?: boolean | undefined
-  counterpartyClassification?: string | undefined
-  folderClassification?: string | undefined
-  comparison?: string | undefined
+  counterpartyClassification?: ReportMeta['classificationMode'] | undefined
+  folderClassification?: ReportMeta['classificationMode'] | undefined
+  comparison?: 'none' | 'previous_period' | 'previous_year' | undefined
   userId?: string | undefined
   /** Split the figures by owner of the address. */
-  breakdownBy?: string | undefined
+  breakdownBy?: 'owner' | undefined
   /** Include addresses shared with you. */
   includeShared?: boolean | undefined
 
@@ -87,7 +101,7 @@ export interface ReportFilters {
   categoryKey?: string | undefined
   groupByField?: string | undefined
   metricField?: string | undefined
-  agg?: string | undefined
+  agg?: 'sum' | 'avg' | 'min' | 'max' | 'median' | 'count' | undefined
   at?: string | undefined
   includeAdjustments?: boolean | undefined
   minimumAgeSeconds?: number | undefined
@@ -99,24 +113,28 @@ export interface ReportFilters {
 
 /**
  * What a snapshot looks like IN A LISTING — eleven fields, not the whole
- * record. The figures themselves (`result`) are not among them: a list of
- * snapshots would otherwise carry every report it mentions. Fetch one with
- * `snapshot(id)` when you need its contents.
+ * record. A strict alias of the generated schema.
+ *
+ * The figures themselves are not among them: a list of snapshots would
+ * otherwise carry every report it mentions. Fetch one with `snapshot(id)`
+ * when you need its contents.
  */
-export type ReportSnapshotListItem = Pick<
-  ReportSnapshot,
-  | 'id'
-  | 'reportType'
-  | 'schemaVersion'
-  | 'parametersJson'
-  | 'generatedById'
-  | 'generatedAt'
-  | 'dataCutoffAt'
-  | 'rowCount'
-  | 'resultHash'
-  | 'status'
-  | 'createdAt'
->
+export type ReportSnapshotListItem = GeneratedReportSnapshotListItem
+
+/**
+ * A single snapshot, as `snapshot(id)` answers. A strict alias of the
+ * generated schema.
+ *
+ * The figures come back under `resultJson`, which is the column's own name.
+ * Only the CREATE call names the same thing `result` — hence two schemas,
+ * `ReportSnapshot` for `createSnapshot` and this one for the detail. Reading
+ * `result` off a detail, or `resultJson` off a fresh snapshot, is a compile
+ * error rather than an `undefined`.
+ *
+ * `resultJson` is `null` only for a snapshot that did not finish
+ * (`status` other than `completed`).
+ */
+export type ReportSnapshotDetail = GeneratedReportSnapshotDetail
 
 /** A period. Required by every report except `balance_position`. */
 interface Period {
@@ -133,10 +151,29 @@ interface Period {
  */
 export interface ReportParams {
   account_statement: Period
-  address_activity: Period
+  /**
+   * Exactly one of the two. Neither, or both, is a 400 — and from this
+   * endpoint it arrives as `REPORT_INVALID_PERIOD`, a code that points at the
+   * dates and sends the reader looking in the wrong place.
+   */
+  address_activity: Period &
+    ({ addressId: string; folderId?: never } | { folderId: string; addressId?: never })
   approval_activity: Period
   asset_movement: Period & { tokenId: string }
-  balance_position: Record<string, never>
+  /**
+   * Nothing is required: the moment is `?at=` (omitted means now), and it
+   * lives in `ReportFilters` with the rest of what this report reads —
+   * `tokenIds`, `addressIds`, `folderIds`, `userId`, `includeShared`.
+   *
+   * `Record<never, never>` and NOT `Record<string, never>`. The latter is an
+   * easy thing to reach for and silently breaks the type: it carries an index
+   * signature, and in the intersection `ReportFilters & ReportParams[T]` that
+   * signature applies to every filter as well, narrowing each of them to
+   * `never`. The report then accepted no arguments at all — `{}` compiled and
+   * `{ at }` did not. `Record<never, never>` has no index signature, so it
+   * contributes no keys and takes none away.
+   */
+  balance_position: Record<never, never>
   category_analytics: Period & { categoryKey: string }
   counterparty_activity: Period & { counterpartyId: string }
   counterparty_group_activity: Period & { counterpartyGroupId: string }
@@ -144,18 +181,130 @@ export interface ReportParams {
   transaction_activity: Period
 }
 
-/** `category_analytics` answers with its own shape, not the activity report. */
+/**
+ * The report filters a DRILL-DOWN honours.
+ *
+ * Deliberately narrower than `ReportFilters`: the drill-down endpoint takes
+ * `filters` as a free-form bag and reads only these keys out of it, so
+ * anything else is accepted and then dropped — the silence that makes a
+ * figure and its breakdown disagree. Built with `Pick` so the two cannot
+ * drift apart as filters are added.
+ */
+export type DrilldownFilters = Pick<
+  ReportFilters,
+  | 'from'
+  | 'to'
+  | 'dateBasis'
+  | 'tokenIds'
+  | 'networkIds'
+  | 'addressIds'
+  | 'ownAddressIds'
+  | 'folderIds'
+  | 'counterpartyIds'
+  | 'counterpartyGroupIds'
+  | 'counterpartyAddressIds'
+  | 'statuses'
+  | 'flowTypes'
+  | 'categories'
+  | 'categoryKeys'
+  | 'categoryField'
+  | 'initiatorIds'
+  | 'decisionPolicyIds'
+  | 'counterpartyClassification'
+  | 'userId'
+> & {
+  /** `in`/`out`. The query-string reports have no equivalent filter. */
+  directions?: readonly ('in' | 'out')[] | undefined
+  /**
+   * A STRING, not the boolean this flag is everywhere else in the package.
+   * `filters` reaches the handler unparsed and the comparison there is
+   * against `'true'`, so a boolean `true` is read as "not shared" and the
+   * shared addresses quietly drop out of the list.
+   */
+  includeShared?: 'true' | 'false' | undefined
+}
+
+/**
+ * WHICH cell of the report was clicked.
+ *
+ * These REFINE `filters`; where a key means the same thing in both, the click
+ * REPLACES the filter — with one exception, `categoryField`, where the two
+ * are combined instead. `periodStart` alone covers the following 24 hours;
+ * pass `periodEnd` for any other span.
+ */
+export interface DrilldownSelection {
+  direction?: 'in' | 'out' | undefined
+  periodStart?: string | undefined
+  periodEnd?: string | undefined
+  tokenId?: string | undefined
+  ownAddressId?: string | undefined
+  counterpartyId?: string | undefined
+  counterpartyAddressId?: string | undefined
+  status?: string | undefined
+  category?: string | undefined
+  /**
+   * One group of a category-field report: `ticker:EUR`. COMBINED with
+   * `filters.categoryField` rather than replacing it, so a report already
+   * narrowed by field stays narrowed when a group of it is opened.
+   */
+  categoryField?: string | undefined
+  initiatorId?: string | undefined
+  decisionPolicyId?: string | undefined
+}
+
+/** `ReportDrilldownBody` minus the two free-form bags refined below. */
+type DrilldownEnvelope = Omit<ReportDrilldownBody, 'filters' | 'drilldown'>
+
+/**
+ * Body of the drill-down request.
+ *
+ * The generated `ReportDrilldownBody` is the same request with `filters` and
+ * `drilldown` as free-form bags (`{ [key: string]: unknown }`) — which is
+ * what the API validates, and also why it is not used as-is: the endpoint
+ * reads a fixed set of keys out of each bag and drops the rest in silence.
+ * `DrilldownFilters` and `DrilldownSelection` name those keys. Everything
+ * else is taken from the generated schema, so a field the API adds to the
+ * envelope appears here without an edit:
+ *
+ *   • `reportType` — informational, the handler does not branch on it;
+ *   • `snapshotId` — build the list from a snapshot's manifest instead of
+ *     from live data;
+ *   • `limit` — 1..500, 100 by default;
+ *   • `cursor` — `nextCursor` of the previous page.
+ *
+ * Each of those may also be passed as an explicit `undefined`, which is left
+ * out of the request.
+ */
+export type DrilldownQuery = {
+  [K in keyof DrilldownEnvelope]: DrilldownEnvelope[K] | undefined
+} & {
+  filters?: DrilldownFilters | undefined
+  drilldown?: DrilldownSelection | undefined
+}
+
+/**
+ * What each report type ANSWERS with — one generated schema per type.
+ *
+ * The ten reports share almost nothing beyond `report` (and, except for
+ * `category_analytics`, `dataQuality`): a position report has `totalsByAsset`
+ * and no `summary`, an approval report counts requests rather than money, an
+ * account statement is opening and closing balances. So `run('x', …)` hands
+ * back the schema of `x`, and a block that report does not have is a compile
+ * error instead of an `undefined` at runtime.
+ *
+ * `ReportResult[ReportType]` — every entry at once — is `AnyReport`.
+ */
 export interface ReportResult {
-  account_statement: ActivityReport
-  address_activity: ActivityReport
-  approval_activity: ActivityReport
-  asset_movement: ActivityReport
-  balance_position: ActivityReport
+  account_statement: AccountStatementReport
+  address_activity: AddressActivityReport
+  approval_activity: ApprovalActivityReport
+  asset_movement: AssetMovementReport
+  balance_position: BalancePositionReport
   category_analytics: CategoryAnalytics
-  counterparty_activity: ActivityReport
-  counterparty_group_activity: ActivityReport
-  operations_exceptions: ActivityReport
-  transaction_activity: ActivityReport
+  counterparty_activity: CounterpartyActivityReport
+  counterparty_group_activity: CounterpartyGroupActivityReport
+  operations_exceptions: OperationsExceptionsReport
+  transaction_activity: TransactionActivityReport
 }
 
 /**
@@ -184,7 +333,22 @@ export class ReportsResource {
     return `/api/v1/vaults/${this.#vault}`
   }
 
-  /** Runs a report. The compiler requires whatever that type needs. */
+  /**
+   * Runs a report. The compiler requires whatever that type needs, and the
+   * answer is the schema of THAT type — see `ReportResult`.
+   *
+   * Money in a report is DECIMAL, not raw smallest units: every `AssetAmount`
+   * (`…ByAsset[].amount`), the `byAsset` rows, and the balances of
+   * `asset_movement`, `account_statement` and `balance_position` are strings
+   * like `"1.5"`. Read them with `parseDecimal`; `amount` would take `"1.5"`
+   * for an integer and reject it. The one exception is `address_activity`,
+   * whose `openingBalances`/`closingBalances` are raw (`balanceRaw`).
+   *
+   * Percentages — `comparison.*ChangePercent`, `observations[].changePercent`,
+   * the `…ShareUsd` and `…RatePercent` fields — are decimal STRINGS too
+   * (`"12.5"`, `"-40"`), and `null` where the figure cannot be worked out:
+   * no previous period to compare with, no USD valuation, a zero base.
+   */
   run<T extends ReportType>(
     type: T,
     params: ReportFilters & ReportParams[T],
@@ -194,7 +358,14 @@ export class ReportsResource {
     })
   }
 
-  /** The same thing through the unified endpoint, choosing the type by alias. */
+  /**
+   * The same thing through the unified endpoint, choosing the type by alias.
+   *
+   * The document types this endpoint's answer as `AnyReport`, the union of
+   * all ten. The type you pass decides which member arrives, so the return is
+   * narrowed to it; call it with a `ReportType` known only at runtime and you
+   * get the whole union back.
+   */
   runUnified<T extends ReportType>(
     type: T,
     params: ReportFilters & ReportParams[T],
@@ -204,9 +375,30 @@ export class ReportsResource {
     })
   }
 
-  /** Drill-down: the operations behind a figure in a report. */
-  queryOperations(body: unknown): Promise<unknown> {
-    return this.#http.request('POST', `${this.#base}/reports/query/operations`, { body })
+  /**
+   * Drill-down: the operations behind a figure in a report.
+   *
+   * A PERIOD IS REQUIRED even though every field of the body is optional. The
+   * endpoint takes it from `drilldown.periodStart` or else from
+   * `filters.from`/`filters.to`, and with neither it answers 400
+   * `REPORT_INVALID_PERIOD` — `queryOperations({})` is not a "whole history"
+   * query.
+   *
+   * The other defaults narrow harder than people expect: with no
+   * `filters.statuses` only `confirmed` operations are listed, and with no
+   * `filters.flowTypes` only `external` ones. Pass the report's own filters
+   * through, or the breakdown comes back smaller than the figure it explains.
+   *
+   * `totals.byAsset[].amount` is a DECIMAL string, like every `AssetAmount`
+   * in the reports. Read it with `parseDecimal`, not `amount` — the latter
+   * would take `'1.5'` for an integer and reject it.
+   */
+  queryOperations(body: DrilldownQuery = {}): Promise<DrilldownResponse> {
+    return this.#http.request<DrilldownResponse>(
+      'POST',
+      `${this.#base}/reports/query/operations`,
+      { body },
+    )
   }
 
   // --- saved templates ----------------------------------------------------
@@ -223,11 +415,49 @@ export class ReportsResource {
     )
   }
 
-  createTemplate(body: unknown): Promise<ReportTemplate> {
+  /**
+   * Saves a set of report parameters under a name.
+   *
+   * `parameters` is what the live report takes, as an object — with one
+   * addition: instead of `from`/`to` it may carry
+   * `relativePeriod: { unit: 'day' | 'week' | 'month', offset }`, resolved to
+   * dates each time the template runs.
+   *
+   * NOTHING IN `parameters` IS CHECKED ON SAVE — it is a free-form bag to the
+   * API. A template with no period, or one aimed at a counterparty that does
+   * not exist, saves fine and fails at `runTemplate`.
+   *
+   * `isShared: true` makes the template visible to the whole vault and is for
+   * administrators only. Sharing lends nobody the author's reach: the scope
+   * is worked out for whoever RUNS it, on every run, so two people get
+   * different figures from the same template.
+   *
+   * THE BAG IS NOT A QUERY STRING, and three things that work on a live
+   * report silently do not work here. It is stored and later handed to the
+   * report builder as it is — nothing parses it, nothing fills defaults:
+   *
+   *  - a multi-value filter must be a real ARRAY; a comma-separated string is
+   *    not split;
+   *  - `categoryField` IS IGNORED. A live report parses `'ticker:EUR'` into a
+   *    filter; this path does not, so a template or snapshot built from the
+   *    filters of a report narrowed by `categoryField` answers 200 with
+   *    figures for EVERY value — the wrong report, with no error. Until the
+   *    API parses it here, send the parsed form the builder reads instead:
+   *    `categoryFieldValues: { ticker: ['EUR'] }`;
+   *  - `timezone` has no default. The live endpoints fall back to `UTC`; here
+   *    an absent one reaches the builder as `undefined`. Always pass it.
+   *
+   * So spreading a `ReportFilters` value into `parameters` is safe only when
+   * it carries no `categoryField` and does carry a `timezone`. (The spread
+   * itself is needed because the type is an index signature, which an
+   * interface-typed value does not fit directly.)
+   */
+  createTemplate(body: CreateReportTemplateBody): Promise<ReportTemplate> {
     return this.#http.request<ReportTemplate>('POST', `${this.#base}/report-templates`, { body })
   }
 
-  updateTemplate(templateId: string, body: unknown): Promise<ReportTemplate> {
+  /** Partial: only the fields you send change. `parameters` is replaced whole, not merged. */
+  updateTemplate(templateId: string, body: PatchReportTemplateBody): Promise<ReportTemplate> {
     return this.#http.request<ReportTemplate>(
       'PATCH',
       `${this.#base}/report-templates/${seg(templateId)}`,
@@ -235,7 +465,7 @@ export class ReportsResource {
     )
   }
 
-  deleteTemplate(templateId: string): Promise<unknown> {
+  deleteTemplate(templateId: string): Promise<{ deleted: true }> {
     return this.#http.request('DELETE', `${this.#base}/report-templates/${seg(templateId)}`)
   }
 
@@ -247,9 +477,21 @@ export class ReportsResource {
    * template's period while believing you had asked for another one. To
    * change the filters, read the template and call `run()` with them, or
    * edit the template.
+   *
+   * The answer is `AnyReport`: which of the ten shapes arrives depends on the
+   * template's `reportType`, which is not known to the compiler. `report.type`
+   * says which one it is at runtime, but it does NOT narrow the union — the
+   * document types that field as the same ten-value enum on every member. So
+   * narrow by a block only that report has (`'totalsByAsset' in report`), or
+   * check `report.type` and assert the type yourself.
+   *
+   * This is also where a template's mistakes surface, since its parameters
+   * were not checked when it was saved: no period is a 400, a target that no
+   * longer exists a 404, and a template built for somebody else's `userId`
+   * run by a non-administrator a 403.
    */
-  runTemplate(templateId: string): Promise<ActivityReport> {
-    return this.#http.request<ActivityReport>(
+  runTemplate(templateId: string): Promise<AnyReport> {
+    return this.#http.request<AnyReport>(
       'POST',
       `${this.#base}/report-templates/${seg(templateId)}/run`,
     )
@@ -267,27 +509,64 @@ export class ReportsResource {
    */
   snapshots(
     params: { reportType?: ReportType; limit?: number } = {},
-  ): Promise<{ items: ReportSnapshotListItem[] }> {
-    return this.#http.request('GET', `${this.#base}/report-snapshots`, { query: { ...params } })
+  ): Promise<ReportSnapshotList> {
+    return this.#http.request<ReportSnapshotList>('GET', `${this.#base}/report-snapshots`, {
+      query: { ...params },
+    })
   }
 
-  snapshot(snapshotId: string): Promise<ReportSnapshot> {
-    return this.#http.request<ReportSnapshot>(
+  /**
+   * One snapshot WITH its figures — under `resultJson`, not `result`; see
+   * `ReportSnapshotDetail`. A non-admin can only read snapshots they
+   * generated themselves, and a missing one is 404 either way, so "not yours"
+   * and "not there" are indistinguishable.
+   */
+  snapshot(snapshotId: string): Promise<ReportSnapshotDetail> {
+    return this.#http.request<ReportSnapshotDetail>(
       'GET',
       `${this.#base}/report-snapshots/${seg(snapshotId)}`,
     )
   }
 
-  createSnapshot(body: unknown): Promise<ReportSnapshot> {
+  /**
+   * Builds the report and freezes it. The answer carries the figures under
+   * `result` — the detail (`snapshot(id)`) calls the same thing `resultJson`.
+   *
+   * `parameters` follows the same rules as a template's — read them at
+   * `createTemplate`, because two of them fail silently: `categoryField` is
+   * ignored (the snapshot would freeze UNFILTERED figures; send
+   * `categoryFieldValues` instead) and `timezone` has no default. Unlike a
+   * template the parameters ARE used at once, so a bad period or a missing
+   * target fails here.
+   *
+   * `result` is the report of type `reportType`, but the type cannot say so:
+   * the spec declares it as a free-form object. Narrow it yourself —
+   * `snap.result as unknown as ReportResult['transaction_activity']` (the
+   * double cast is required; the detail's `resultJson` takes the same one).
+   * For the same reason the per-type REQUIRED parameters are not checked by
+   * the compiler here, as they are in `run()`.
+   *
+   * A result over roughly 900 KB is refused with 400
+   * `REPORT_PERIOD_TOO_LARGE` — narrow the filters.
+   */
+  createSnapshot(body: CreateReportSnapshotBody): Promise<ReportSnapshot> {
     return this.#http.request<ReportSnapshot>('POST', `${this.#base}/report-snapshots`, { body })
   }
 
-  deleteSnapshot(snapshotId: string): Promise<unknown> {
+  deleteSnapshot(snapshotId: string): Promise<{ deleted: true }> {
     return this.#http.request('DELETE', `${this.#base}/report-snapshots/${seg(snapshotId)}`)
   }
 
-  /** Starts an export of a snapshot. The file is fetched separately. */
-  createExport(snapshotId: string, body: unknown): Promise<ReportExport> {
+  /**
+   * Exports a snapshot. The file is fetched separately, with `downloadExport`.
+   *
+   * Only `format` matters, and only two of its four values work: `json` (the
+   * frozen result) and `csv` (a flat register of operations). `xlsx` and
+   * `pdf` pass validation and are then refused with 400
+   * `REPORT_UNSUPPORTED_FORMAT`. `locale`, `timezone` and
+   * `includeOperationRegister` are accepted and currently change nothing.
+   */
+  createExport(snapshotId: string, body: CreateReportExportBody): Promise<ReportExport> {
     return this.#http.request<ReportExport>(
       'POST',
       `${this.#base}/report-snapshots/${seg(snapshotId)}/exports`,
@@ -307,7 +586,9 @@ export class ReportsResource {
    * be CSV or another binary format, and parsing that as JSON fails every
    * time. Read it with `.blob()`, `.text()` or `.arrayBuffer()`.
    *
-   * Poll `export()` until it reports ready before calling this.
+   * Exports are produced synchronously today, so the record `createExport`
+   * answers with is already `completed` and can be downloaded at once. The
+   * `status` field exists for a queued path — check it rather than assuming.
    */
   downloadExport(exportId: string): Promise<Response> {
     return this.#http.fetchRaw('GET', `${this.#base}/report-exports/${seg(exportId)}/download`)

package/src/resources/sharing.ts

@@ -6,7 +6,7 @@ import type {
   GrantAddressShareBody,
   ParticipantsResponse,
   PatchAddressShareBody,
-  ShareBatchResult,
+  ShareGrantCreated,
 } from '../generated/types.js'
 
 /**
@@ -52,14 +52,40 @@ export class SharingResource {
    * 400 comes only when every subject was rejected. A consumer that trusts
    * the status code silently loses the people who were refused.
    *
+   * WHERE THE REASONS GO WHEN EVERY SUBJECT FAILED. That 400 is not an error
+   * envelope: the API sends the same `{results:[…]}` body with a 400 instead
+   * of a 201. The document describes both forms of that status — the
+   * envelope for a body that failed validation, and `ShareBatchAllRejected`
+   * for a batch in which every subject was refused. The SDK does not lose the
+   * second, but it does throw: `core/errors.ts` finds neither `error` nor
+   * `code` in the body, so it builds a `CoreError` with `code: 'BAD_REQUEST'`
+   * and puts the WHOLE body in `details`:
+   *
+   * ```ts
+   * catch (e) {
+   *   if (isCoreError(e) && e.status === 400) {
+   *     const per = (e.details as ShareBatchAllRejected | undefined)?.results
+   *     // per[i].error.code — why that one subject was refused
+   *   }
+   * }
+   * ```
+   *
+   * `details` is `undefined` for the other 400, the validation one — hence
+   * the `| undefined` in the cast, and the reason to check before reading.
+   *
+   * Reading `message` instead gets you "The request was rejected", because
+   * the server sent no message to pass on. Per-subject `error.message` equals
+   * its `code`, so neither is a sentence to show a person as-is.
+   *
    * The single-subject form answers with the grant itself rather than a
-   * batch, which is why the return type is a union.
+   * batch, which is why the return type is a union — `ShareGrantCreated`,
+   * the grant or the batch; tell them apart with `'results' in answer`. It
+   * also reports failure differently: one subject refused is a plain 403 with
+   * no `results[]` at all, so the batch form is the one to use when you need
+   * reasons.
    */
-  share(
-    addressId: string,
-    input: GrantAddressShareBody,
-  ): Promise<ShareBatchResult | AddressAccessGrant> {
-    return this.#http.request<ShareBatchResult | AddressAccessGrant>(
+  share(addressId: string, input: GrantAddressShareBody): Promise<ShareGrantCreated> {
+    return this.#http.request<ShareGrantCreated>(
       'POST',
       `${this.#address(addressId)}/shares`,
       { body: input },
@@ -78,8 +104,12 @@ export class SharingResource {
     )
   }
 
-  revoke(addressId: string, shareId: string): Promise<unknown> {
-    return this.#http.request('DELETE', `${this.#address(addressId)}/shares/${seg(shareId)}`)
+  /** Soft: the row survives with `revokedAt`/`revokedById` for the audit trail. */
+  revoke(addressId: string, shareId: string): Promise<{ revoked: boolean }> {
+    return this.#http.request<{ revoked: boolean }>(
+      'DELETE',
+      `${this.#address(addressId)}/shares/${seg(shareId)}`,
+    )
   }
 
   /**
@@ -94,19 +124,42 @@ export class SharingResource {
     )
   }
 
-  /** Addresses you have shared with others. */
-  sharedByMe(): Promise<unknown> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/shared-by-me`)
+  /**
+   * What you have opened to others — addresses AND folders, so the entries
+   * are not all of one `targetType`. Same shape as `list()`.
+   */
+  sharedByMe(): Promise<AddressSharesList> {
+    return this.#http.request<AddressSharesList>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/shared-by-me`,
+    )
   }
 
-  /** Addresses others have shared with you. */
-  sharedWithMe(): Promise<unknown> {
-    return this.#http.request('GET', `/api/v1/vaults/${this.#vault}/shared-with-me`)
+  /**
+   * Addresses others have shared with you — DIRECT grants on an address
+   * only. Access that reaches you through a shared FOLDER is not here, which
+   * is the trap: an empty answer does not mean nothing is shared with you.
+   * For shared access of every kind ask the addresses list with
+   * `access: 'shared'`, or `'all'` to include your own.
+   */
+  sharedWithMe(): Promise<AddressSharesList> {
+    return this.#http.request<AddressSharesList>(
+      'GET',
+      `/api/v1/vaults/${this.#vault}/shared-with-me`,
+    )
   }
 
-  /** Gives up access someone granted you. Your own grant, your own decision. */
-  leave(grantId: string): Promise<unknown> {
-    return this.#http.request(
+  /**
+   * Gives up access someone granted you. Your own grant, your own decision —
+   * the owner is not asked.
+   *
+   * Works on a grant made to you PERSONALLY. Access you have through a user
+   * group cannot be dropped this way, because it belongs to the whole group:
+   * that answers 409 `ACCESS_VIA_GROUP`, with the group's id and name in
+   * `details`, so the interface can say which group to leave instead.
+   */
+  leave(grantId: string): Promise<{ left: boolean }> {
+    return this.#http.request<{ left: boolean }>(
       'DELETE',
       `/api/v1/vaults/${this.#vault}/shared-with-me/${seg(grantId)}`,
     )