@v3finance/core-sdk 0.1.0 → 0.2.0

package/src/generated/types.ts

@@ -1,14 +1,14 @@
 // Generated from openapi/spec.json by scripts/generate.ts — do not edit by hand.
 // Policy Engine REST API 1.0.0. Regenerate: npm run spec:update && npm run generate
 
-/** Единая форма ошибки для ВСЕХ эндпоинтов. Приводится слоем middleware/errorEnvelope независимо от того, как ошибку собрал хендлер */
+/** Единая форма ошибки. Приводится слоем middleware/errorEnvelope независимо от того, как ошибку собрал хендлер. Слой узнаёт ошибку по ключу `error` в корне тела; ответ со статусом ≥400 без этого ключа он не трогает — так отвечает пакетная выдача доступа, когда отклонены все получатели: 400 с телом `{results}` */
 export interface ApiErrorEnvelope {
   error: {
     /** Машиночитаемый код. Осмысленный там, где его задаёт хендлер (INSUFFICIENT_BALANCE, POLICY_DENIED, APPROVAL_UNSATISFIABLE…), иначе выведен из HTTP-статуса (NOT_FOUND, FORBIDDEN…) */
     code: string
     /** Человекочитаемое описание — можно показывать пользователю */
     message: string
-    /** Структурированные подробности, если есть */
+    /** Структурированные подробности, если есть (поля валидации, трейс политик). Сюда же слой переносит машиночитаемые ключи, которые хендлер положил рядом с error: `field` — ключ поля категории, не прошедшего валидацию; `stepIndex` — номер отказавшего шага композитной заявки */
     details?: unknown
   }
 }
@@ -159,6 +159,8 @@ export interface AddressAccessGrant {
   canCreateAddress: boolean
   grantorId: string
   status: "active" | "revoked"
+  revokedAt: string | null
+  revokedById: string | null
   /** format: date-time */
   createdAt: string
   /** format: date-time */
@@ -367,8 +369,17 @@ export interface AddressGroupDetail {
   createdAt: string
   /** format: date-time */
   updatedAt: string
-  /** range: -9007199254740991..9007199254740991 */
+  /**
+   * Сколько адресов в папке. Приходит в списке и детали
+   *
+   * range: -9007199254740991..9007199254740991
+   */
   memberCount?: number
+  /** Служебный счётчик ORM — приезжает в списке и детали рядом с memberCount и равен ему. Читайте memberCount: это поле — деталь реализации, объявлено только потому, что фактически отдаётся */
+  _count?: {
+    /** range: -9007199254740991..9007199254740991 */
+    members: number
+  }
   /** Как у меня доступ к группе */
   access?: "manager" | "granted" | "admin"
   /** Открыта ли папка кому-то ещё + сколько ЛЮДЕЙ имеют доступ. Ортогонально полю access: своя расшаренная папка — это access=manager + isShared=true */
@@ -404,8 +415,17 @@ export interface AddressGroup {
   createdAt: string
   /** format: date-time */
   updatedAt: string
-  /** range: -9007199254740991..9007199254740991 */
+  /**
+   * Сколько адресов в папке. Приходит в списке и детали
+   *
+   * range: -9007199254740991..9007199254740991
+   */
   memberCount?: number
+  /** Служебный счётчик ORM — приезжает в списке и детали рядом с memberCount и равен ему. Читайте memberCount: это поле — деталь реализации, объявлено только потому, что фактически отдаётся */
+  _count?: {
+    /** range: -9007199254740991..9007199254740991 */
+    members: number
+  }
   /** Как у меня доступ к группе */
   access?: "manager" | "granted" | "admin"
   /** Открыта ли папка кому-то ещё + сколько ЛЮДЕЙ имеют доступ. Ортогонально полю access: своя расшаренная папка — это access=manager + isShared=true */
@@ -931,7 +951,7 @@ export interface AssignCategoryBody {
    * Значения полей; обязательные (required) должны быть заполнены
    * @defaultValue {}
    */
-  values: {
+  values?: {
     [key: string]: unknown
   }
   /** length: 0..500 */
@@ -1001,7 +1021,12 @@ export interface CancelResult {
 /** Тело не требуется — инициатор из сессии */
 export type CancelTransferBody = Record<string, never>
 
-export type CategoryAccessScope = unknown
+/**
+ * Что категория открывает по умолчанию, без гранта (какое именно право — зависит от поля: viewScope, assignScope, editScope). owner_only — ничего сверх доступа через адрес операции (свои операции, совместный доступ) и грантов категории; vault_members — право есть у каждого участника Vault'а.
+ *
+ * В ответах приходят только эти два значения. В ЗАПРОСЕ дополнительно принимается устаревший псевдоним "restricted": записывается как "owner_only" (вёл себя так же; миграция 0037 убрала его из данных). В перечень значений он не входит намеренно: описание общее для запроса и ответа, а в ответе его не бывает. Новому коду слать его незачем
+ */
+export type CategoryAccessScope = "owner_only" | "vault_members"
 
 export interface CompositeApplied {
   /** Все шаги allow/bypass — цепочка применена сразу, без заявки */
@@ -1838,6 +1863,8 @@ export type EvaluationResult = {
 export interface PolicyTrace {
   policyId: string
   policyCode: string
+  /** Редакция политики, которая оценивалась (Ф4) — та же, что попадёт в `decisionPolicyVersionId` перевода. null — у политики ещё нет версий */
+  policyVersionId: string | null
   policyName: string
   effect: string
   applied: boolean
@@ -2546,21 +2573,38 @@ export interface Participant {
   userId: string
   user: UserCard | null
   role: ShareRole
-  /**
-   * ОТКУДА доступ — и, следовательно, что делать, чтобы его убрать:
-   * - {kind:"direct", grantId} — прямой грант, отзывается точечно
-   * - {kind:"user_group", groupId, groupName} — грант выдан ГРУППЕ пользователей: точечно не отзывается, нужно вывести человека из группы
-   * - {kind:"address_group", groupId, groupName} — доступ через папку, куда входит адрес
-   *
-   * Источников может быть НЕСКОЛЬКО сразу; итоговая роль — максимум прав
-   */
-  via: Array<{
-    [key: string]: unknown
-  }>
+  /** Источников может быть НЕСКОЛЬКО сразу; итоговая роль — максимум прав */
+  via: ParticipantVia[]
   /** true — есть прямой грант, участника можно убрать одной операцией */
   removable: boolean
 }
 
+/**
+ * ОТКУДА доступ — и, следовательно, что делать, чтобы его убрать:
+ * - direct — прямой грант, отзывается точечно
+ * - user_group — грант выдан ГРУППЕ пользователей: точечно не отзывается, нужно вывести человека из группы
+ * - address_group — доступ через папку, куда входит адрес (у участников самой папки не встречается)
+ */
+export type ParticipantVia = {
+  kind: "direct"
+  /** Грант на сам объект — отзывается точечно */
+  grantId: string
+} | {
+  kind: "user_group"
+  /** Грант, выданный группе пользователей */
+  grantId: string
+  groupId: string
+  /** Имя группы — чтобы объяснить «доступ у вас от группы Казначеи» */
+  groupName: string
+} | {
+  kind: "address_group"
+  /** Грант, выданный на папку */
+  grantId: string
+  /** Папка, в которой лежит адрес */
+  groupId: string
+  groupName: string
+}
+
 /** Кто имеет доступ к объекту — списком ЛЮДЕЙ, а не грантов. Админы не включаются: их доступ надзорный, есть ко всему сразу и совместным доступом не является */
 export interface ParticipantsResponse {
   /** Владелец объекта: у адреса — создатель, у папки — менеджер. Не участник */
@@ -2798,6 +2842,7 @@ export interface PendingApproval {
 
 export interface PolicyApprover {
   id: string
+  policyId: string
   /** "user" | "group" */
   kind: string
   userId: string | null
@@ -2832,6 +2877,14 @@ export interface PolicyDetail {
   createdAt: string
   /** format: date-time */
   updatedAt: string
+  /**
+   * Текущая редакция политики (PolicyVersion.id, Ф4). На редакцию, а не на политику, ссылается решение: `decisionPolicyVersionId` у перевода и `policyVersionId` в ответе /evaluate.
+   *
+   * POST /policies отдаёт id ПЕРВОЙ редакции, PATCH — редакции, снятой этой правкой. Раньше POST всегда отвечал null, хотя версия к этому моменту уже была снята (ответ собирался из строки, прочитанной до снимка), и за значением приходилось идти вторым запросом.
+   *
+   * null — редакции нет или её id не удалось прочитать: у POST значение дочитывается отдельным запросом, и его сбой создание не отменяет. Получив null, спросите GET /policies/{id}
+   */
+  currentVersionId: string | null
   /** LEGACY: движок их не читает, решает conditionJson */
   rules: Rule[]
   /** Явные одобряющие (для allow-политики с approval{}) */
@@ -2982,6 +3035,14 @@ export interface Policy {
   createdAt: string
   /** format: date-time */
   updatedAt: string
+  /**
+   * Текущая редакция политики (PolicyVersion.id, Ф4). На редакцию, а не на политику, ссылается решение: `decisionPolicyVersionId` у перевода и `policyVersionId` в ответе /evaluate.
+   *
+   * POST /policies отдаёт id ПЕРВОЙ редакции, PATCH — редакции, снятой этой правкой. Раньше POST всегда отвечал null, хотя версия к этому моменту уже была снята (ответ собирался из строки, прочитанной до снимка), и за значением приходилось идти вторым запросом.
+   *
+   * null — редакции нет или её id не удалось прочитать: у POST значение дочитывается отдельным запросом, и его сбой создание не отменяет. Получив null, спросите GET /policies/{id}
+   */
+  currentVersionId: string | null
 }
 
 export interface PolicyTableItem {
@@ -3000,10 +3061,6 @@ export interface PolicyTableItem {
   adminBypass: boolean
   allowInitiatorApproval: boolean
   enabled: boolean
-  /** Условие применимости — булево дерево. ЭТО ЧИТАЕТ ДВИЖОК. null — политика применима всегда. Legacy-таблица rules движком не используется и удаляется в Ф5 */
-  conditionJson: PolicyCondition | null
-  /** Требование подписи. null — политика разрешает без одобрения */
-  approvalJson: PolicyApprovalInput | null
   /** format: date-time */
   createdAt: string
   /** format: date-time */
@@ -3065,6 +3122,14 @@ export interface PolicyWithRules {
   createdAt: string
   /** format: date-time */
   updatedAt: string
+  /**
+   * Текущая редакция политики (PolicyVersion.id, Ф4). На редакцию, а не на политику, ссылается решение: `decisionPolicyVersionId` у перевода и `policyVersionId` в ответе /evaluate.
+   *
+   * POST /policies отдаёт id ПЕРВОЙ редакции, PATCH — редакции, снятой этой правкой. Раньше POST всегда отвечал null, хотя версия к этому моменту уже была снята (ответ собирался из строки, прочитанной до снимка), и за значением приходилось идти вторым запросом.
+   *
+   * null — редакции нет или её id не удалось прочитать: у POST значение дочитывается отдельным запросом, и его сбой создание не отменяет. Получив null, спросите GET /policies/{id}
+   */
+  currentVersionId: string | null
   /** LEGACY: движок их не читает, решает conditionJson */
   rules: Rule[]
   /** Явные одобряющие (для allow-политики с approval{}) */
@@ -3184,21 +3249,45 @@ export interface SeatCreated {
   expiresAt: string
 }
 
+export interface ShareBatchAllRejected {
+  /** items: 1..∞ */
+  results: ShareBatchRejectedItem[]
+}
+
+export interface ShareBatchRejectedItem {
+  subjectType: "user" | "group"
+  subjectUserId: string | null
+  subjectGroupId: string | null
+  ok: false
+  outcome: null
+  grant: null
+  error: {
+    /** SELF_SHARE — себе; OWNER_SUBJECT — владельцу адреса; NOT_MEMBER — не участник Vault'а; NOT_VISIBLE — получатель вам не виден (нет гранта видимости); GROUP_NOT_FOUND — группы нет в этом Vault'е */
+    code: string
+    /** Сейчас дублирует code — человеческий текст собирает клиент */
+    message: string
+  }
+}
+
+export interface ShareBatchGrantedItem {
+  subjectType: "user" | "group"
+  subjectUserId: string | null
+  subjectGroupId: string | null
+  ok: true
+  /** created — новый грант; updated — у действующего гранта сменили права; reactivated — снят отзыв с ранее отозванного */
+  outcome: "created" | "updated" | "reactivated"
+  grant: AddressAccessGrant
+  error: null
+}
+
+export type ShareBatchItem = ShareBatchGrantedItem | ShareBatchRejectedItem
+
 export interface ShareBatchResult {
-  results: Array<{
-    subjectType: "user" | "group"
-    subjectUserId: string | null
-    subjectGroupId: string | null
-    ok: boolean
-    outcome: "created" | "updated" | "reactivated" | null
-    grant: AddressAccessGrant | null
-    error: {
-      code: string
-      message: string
-    } | null
-  }>
+  results: ShareBatchItem[]
 }
 
+export type ShareGrantCreated = AddressAccessGrant | ShareBatchResult
+
 export interface Token {
   /** cuid */
   id: string
@@ -3311,6 +3400,16 @@ export interface TransactionDetail {
   amlScore: number | null
   /** Когда провайдер сделал проверку */
   amlCheckedAt: string | null
+  /** USD-оценка перевода: amountDecimal × usdRate, decimal-СТРОКА. Считается один раз при создании и live-курсом не пересчитывается; null — курс был недоступен */
+  usdValue: string | null
+  /** Редакция политики, принявшая решение (PolicyVersion.id, Ф4). ЕДИНСТВЕННЫЙ способ связать перевод с правилами, которые действовали в момент решения: `decisionPolicyId` ведёт на политику, а её с тех пор могли переписать. Снимок — GET /policies/{id}/versions. null — решение принято до введения версий */
+  decisionPolicyVersionId: string | null
+  /** Группы контрагентов получателя НА МОМЕНТ РЕШЕНИЯ (id групп). Версия политики хранит id групп белого списка, но не их состав — без этого снимка нельзя объяснить, почему платёж прошёл, после того как контрагента из группы убрали. null — получатель не был контрагентом */
+  decisionCounterpartyGroupsJson: string[] | null
+  /** Контрагент, сопоставленный по toAddress при создании. Дублирует `counterparty.id` — отдаётся как колонка перевода */
+  counterpartyId: string | null
+  /** Клиентский ключ попытки, с которым перевод создан (см. тело POST /transfers). null — ключ не передавали */
+  idempotencyKey: string | null
   amountDecimal: string
   assetSymbol: string
 }
@@ -3408,7 +3507,7 @@ export interface UserProfile {
   color: string | null
   /** Emoji-иконка */
   emoji: string | null
-  /** true — аккаунт создан по пригласительной ссылке и настоящая почта ещё НЕ указана (в email лежит технический адрес). Клиент обязан попросить адрес: пока его нет, человеку некуда прислать magic-link, и при истечении сессии он потеряет доступ. Привязка — POST /me/email */
+  /** true — аккаунт создан по пригласительной ссылке и настоящая почта ещё НЕ указана (в email лежит технический адрес). Клиент обязан попросить адрес: пока его нет, человеку некуда прислать magic-link, и при истечении сессии он потеряет доступ. Привязка — POST /me/profile/email. Приходит и в GET, и в ответе PATCH */
   needsEmail: boolean
   /** format: date-time */
   createdAt: string
@@ -3498,6 +3597,7 @@ export interface VaultPoliciesPage {
   items: Array<{
     /** cuid */
     id: string
+    groupId: string
     code: string
     name: string
     description: string | null
@@ -3519,11 +3619,17 @@ export interface VaultPoliciesPage {
     createdAt: string
     /** format: date-time */
     updatedAt: string
+    /**
+     * Текущая редакция политики (PolicyVersion.id, Ф4). На редакцию, а не на политику, ссылается решение: `decisionPolicyVersionId` у перевода и `policyVersionId` в ответе /evaluate.
+     *
+     * POST /policies отдаёт id ПЕРВОЙ редакции, PATCH — редакции, снятой этой правкой. Раньше POST всегда отвечал null, хотя версия к этому моменту уже была снята (ответ собирался из строки, прочитанной до снимка), и за значением приходилось идти вторым запросом.
+     *
+     * null — редакции нет или её id не удалось прочитать: у POST значение дочитывается отдельным запросом, и его сбой создание не отменяет. Получив null, спросите GET /policies/{id}
+     */
+    currentVersionId: string | null
     _count: {
       /** range: -9007199254740991..9007199254740991 */
       rules: number
-      /** range: -9007199254740991..9007199254740991 */
-      limits?: number
     }
     /** Owner-группа политики */
     group: GroupRef
@@ -3572,8 +3678,12 @@ export interface VisibilityGrant {
   } | null
   status: string
   grantorId: string
+  revokedAt: string | null
+  revokedById: string | null
   /** format: date-time */
   createdAt: string
+  /** format: date-time */
+  updatedAt: string
 }
 
 export interface VoteBody {
@@ -3649,36 +3759,111 @@ export type WebhookResult = {
   eventId: string
 }
 
-export interface ActivityReport {
+export interface AccountStatementReport {
   report: ReportMeta
-  summary?: ReportSummary
-  byAsset?: ByAssetRow[]
-  byCounterparty?: ByCounterpartyRow[]
-  byOwnAddress?: ByOwnAddressRow[]
-  byStatus?: ByStatusRow[]
-  byCategory?: ByCategoryRow[]
-  byAddressOwner?: ByAddressOwnerRow[]
-  timeline?: TimelinePoint[]
-  approvals?: ReportApprovals
-  observations?: Observation[]
-  dataQuality?: DataQuality
-  comparison?: Comparison | null
+  balancesByAsset: StatementTokenRow[]
+  timeline: Array<{
+    /** Начало интервала (как periodStart у остальных) */
+    period: string
+    /** Задел; сейчас всегда пустая строка */
+    opening: string
+    /** Приток ТЕКСТОМ для печати: "1.5 USDT; 20 TRX" — сумма с символом, активы через «; ». Числом не разбирать. Перечислен КАЖДЫЙ актив, по которому в интервале были операции, даже если притока по нему не было: тогда он приходит как "0 USDT", а не пропадает */
+    incoming: string
+    /** Отток, в том же текстовом виде и с теми же нулевыми позициями */
+    outgoing: string
+    /** Задел; сейчас всегда "0" */
+    adjustments: string
+    /** Задел; сейчас всегда пустая строка */
+    closing: string
+  }>
+  dataQuality: DataQuality
 }
 
 export interface ReportMeta {
-  id?: string | null
-  /** snake_case: transaction_activity и т.д. */
-  type: string
-  from: string | null
-  to: string | null
-  timezone: string | null
-  dateBasis?: string | null
-  baseCurrency?: string | null
-  classificationMode?: string | null
-  dataCutoff?: string | null
-  schemaVersion?: string | number | null
+  /** Задел под сохранённый отчёт. У живого отчёта всегда null */
+  id: string | null
+  /** Тип отчёта, snake_case — тот же, что в пути и в ?type= */
+  type: "counterparty_activity" | "counterparty_group_activity" | "transaction_activity" | "asset_movement" | "address_activity" | "balance_position" | "account_statement" | "approval_activity" | "operations_exceptions" | "category_analytics"
   generatedAt: string
-  generatedById?: string | null
+  /** Кто запросил отчёт */
+  generatedById: string
+  /** Начало периода (включительно), ISO-8601 UTC. У balance_position from = to = момент позиции */
+  from: string
+  /** Конец периода (НЕ включительно), ISO-8601 UTC */
+  to: string
+  /** IANA-зона, в которой нарезан timeline. У balance_position всегда UTC */
+  timezone: string
+  /** По какой дате операция отнесена к периоду. Если параметр не прислан: blockchainAt у counterparty_activity и counterparty_group_activity, createdAt у остальных */
+  dateBasis: "createdAt" | "blockchainAt" | "confirmedAt"
+  baseCurrency: "USD"
+  /** Значение параметра counterpartyClassification (по умолчанию historical). У balance_position всегда current */
+  classificationMode: "current" | "historical"
+  dataCutoff: {
+    /** Операции новее в отчёт не вошли */
+    timestamp: string
+    /** Задел; сейчас всегда null */
+    blockNumber: number | null
+  }
+  /** Версия формата результата; сейчас всегда "reporting_v1" */
+  schemaVersion: string
+}
+
+export interface StatementTokenRow {
+  tokenId: string
+  assetCode: string
+  assetSymbol: string
+  /** Network.slug */
+  network: string
+  openingAvailable: string
+  openingReserved: string
+  openingTotal: string
+  incomingExternal: string
+  outgoingExternal: string
+  incomingInternal: string
+  outgoingInternal: string
+  /** Ручные корректировки ledger (kind=adjustment) за период */
+  adjustments: string
+  closingAvailable: string
+  closingReserved: string
+  closingTotal: string
+  /** (opening + движения + adjustments) − closing из ledger. Ожидается "0"; ненулевое значение — операции и ledger разошлись, и оно же считается в dataQuality.ledgerReconciliationDifferences */
+  reconciliationDifference: string
+}
+
+export interface DataQuality {
+  totalOperations: number
+  unmatchedOperations: number
+  retroactivelyMatchedOperations: number
+  operationsWithoutUsdRate: number
+  operationsWithoutSelectedDate: number
+  operationsWithoutBlockchainTime: number
+  operationsWithoutPaymentPurpose: number
+  operationsWithoutBusinessReference: number
+  uncategorizedOperations: number
+  conflictingCounterpartyClassifications: number
+  invalidOperationRelations: number
+  missingLedgerEntries: number
+  ledgerReconciliationDifferences: number
+}
+
+/** УСТАРЕЛО: используйте схему конкретного отчёта (TransactionActivityReport, AssetMovementReport, …) или AnyReport. Имя сохранено для совместимости сгенерированных клиентов: это объединение девяти отчётов, кроме category_analytics */
+export type ActivityReport = TransactionActivityReport | CounterpartyActivityReport | CounterpartyGroupActivityReport | AssetMovementReport | AddressActivityReport | AccountStatementReport | OperationsExceptionsReport | ApprovalActivityReport | BalancePositionReport
+
+export interface TransactionActivityReport {
+  report: ReportMeta
+  summary: ReportSummary
+  byAsset: ByAssetRow[]
+  byCounterparty: ByCounterpartyRow[]
+  byOwnAddress: ByOwnAddressRow[]
+  /** Только при ?breakdownBy=owner. Без параметра ключа в ответе НЕТ — это не то же самое, что пустой массив */
+  byAddressOwner?: ByAddressOwnerRow[]
+  byStatus: ByStatusRow[]
+  byCategory: ByCategoryRow[]
+  timeline: TimelinePoint[]
+  approvals: ReportApprovals
+  comparison: Comparison
+  observations: Observation[]
+  dataQuality: DataQuality
 }
 
 export interface ReportSummary {
@@ -3709,32 +3894,39 @@ export interface ReportSummary {
   minimumAmountByAsset: AssetAmount[]
   /** @defaultValue [] */
   maximumAmountByAsset: AssetAmount[]
-  confirmedCount?: number
-  pendingCount?: number
-  awaitingApprovalCount?: number
-  rejectedCount?: number
-  cancelledCount?: number
-  failedCount?: number
-  activeDays?: number | null
-  firstOperationAt?: string | null
-  lastOperationAt?: string | null
+  confirmedCount: number
+  pendingCount: number
+  awaitingApprovalCount: number
+  rejectedCount: number
+  cancelledCount: number
+  failedCount: number
+  /** Число календарных дней (в timezone отчёта) с хотя бы одной операцией */
+  activeDays: number
+  /** createdAt самой ранней операции выборки; null — выборка пуста */
+  firstOperationAt: string | null
+  /** createdAt самой поздней операции выборки; null — выборка пуста */
+  lastOperationAt: string | null
 }
 
 export interface AssetAmount {
-  tokenId: string | null
-  assetCode: string | null
+  tokenId: string
+  /** Token.code из реестра */
+  assetCode: string
   assetSymbol: string
-  network: string | null
-  contractAddress?: string | null
-  /** raw smallest units, строкой */
+  /** Network.slug */
+  network: string
+  /** DECIMAL-строка в единицах актива ("1.5"), НЕ raw smallest units; хвостовые нули убраны. Со знаком только у netFlow* ("-12.5" — отток больше притока), у остальных блоков неотрицательна */
   amount: string
 }
 
 export interface ByAssetRow {
-  tokenId: string | null
-  assetCode: string | null
+  tokenId: string
+  /** Token.code из реестра */
+  assetCode: string
   assetSymbol: string
-  network: string | null
+  /** Network.slug */
+  network: string
+  /** null у нативного актива сети */
   contractAddress: string | null
   incoming: string
   outgoing: string
@@ -3758,8 +3950,11 @@ export interface ByAssetRow {
 }
 
 export interface ByCounterpartyRow {
+  /** null — операции без сопоставленного контрагента (одна строка на все) */
   counterpartyId: string | null
+  /** Имя контрагента. У строки без контрагента (counterpartyId = null) сюда приходит английская заглушка "unmatched counterparty" — она не локализуется, поэтому различать такую строку надо по counterpartyId */
   name: string | null
+  /** Свободная категория контрагента (exchange, client…); null — не задана */
   kind: string | null
   /** @defaultValue [] */
   incomingByAsset: AssetAmount[]
@@ -3781,7 +3976,7 @@ export interface ByOwnAddressRow {
     [key: string]: unknown
   } | null
   /**
-   * Папки, в которых адрес состоял (зависит от folderClassification)
+   * Задел под папки адреса. Сейчас ВСЕГДА пустой массив
    * @defaultValue []
    */
   folderSnapshots: unknown[]
@@ -3794,6 +3989,20 @@ export interface ByOwnAddressRow {
   operationsCount: number
 }
 
+export interface ByAddressOwnerRow {
+  /** Владелец адресов (создатель) */
+  userId: string
+  /** Считается от вызывающего: у двух людей один отчёт разложится по-разному */
+  isMe: boolean
+  /** Сколько адресов этого владельца попало в выборку */
+  addressesCount: number
+  incomingByAsset: AssetAmount[]
+  outgoingByAsset: AssetAmount[]
+  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+  grossTurnoverUsd: string | null
+  operationsCount: number
+}
+
 export interface ByStatusRow {
   status: string
   count: number
@@ -3814,17 +4023,6 @@ export interface ByCategoryRow {
   usdValue: string | null
 }
 
-export interface ByAddressOwnerRow {
-  ownerId: string | null
-  owner?: {
-    [key: string]: unknown
-  } | null
-  isMe: boolean
-  operationsCount: number
-  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
-  grossTurnoverUsd: string | null
-}
-
 export interface TimelinePoint {
   periodStart: string
   periodEnd: string
@@ -3854,75 +4052,456 @@ export interface ReportApprovals {
   maximumApprovalSeconds: number | null
 }
 
+export interface Comparison {
+  /** none | previous_period | previous_year */
+  mode: string
+  previousFrom: string | null
+  previousTo: string | null
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — сравнивать не с чем: mode=none, прошлое значение нулевое при ненулевом текущем, либо нет USD-оценки */
+  incomingUsdChangePercent: string | null
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — сравнивать не с чем: mode=none, прошлое значение нулевое при ненулевом текущем, либо нет USD-оценки */
+  outgoingUsdChangePercent: string | null
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — сравнивать не с чем: mode=none, прошлое значение нулевое при ненулевом текущем, либо нет USD-оценки */
+  grossTurnoverUsdChangePercent: string | null
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — сравнивать не с чем: mode=none, прошлое значение нулевое при ненулевом текущем, либо нет USD-оценки */
+  operationsCountChangePercent: string | null
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — сравнивать не с чем: mode=none, прошлое значение нулевое при ненулевом текущем, либо нет USD-оценки */
+  averageOperationUsdChangePercent: string | null
+}
+
 export interface Observation {
+  /** Машиночитаемый код: COUNTERPARTY_TURNOVER_INCREASED, SINGLE_OPERATION_CONCENTRATION, UNMATCHED_OPERATIONS_PRESENT… */
   code: string
-  severity: string
+  severity: "info" | "warning"
   title: string
   description: string
   metric: string | null
   currentValue: string | null
+  /** Задел; сейчас всегда null */
   comparisonValue: string | null
-  changePercent: number | null
-  drilldownFilters?: {
+  /** Изменение к прошлому периоду в процентах — decimal-СТРОКА ("12.5", "-40"), не число. null — наблюдение не про сравнение периодов (концентрация, качество данных, зависшие операции). Не null только у наблюдений о росте или падении оборота и среднего платежа — там это то же значение, что в comparison */
+  changePercent: string | null
+  /** Готовое уточнение для drill-down, раскрывающее наблюдение до операций; {} — раскрывать нечем */
+  drilldownFilters: {
     [key: string]: unknown
-  } | null
+  }
 }
 
-export interface DataQuality {
-  totalOperations: number
-  unmatchedOperations: number
-  retroactivelyMatchedOperations: number
-  operationsWithoutUsdRate: number
-  operationsWithoutSelectedDate: number
-  operationsWithoutBlockchainTime: number
-  operationsWithoutPaymentPurpose: number
-  operationsWithoutBusinessReference: number
-  uncategorizedOperations: number
-  conflictingCounterpartyClassifications: number
-  invalidOperationRelations: number
-  missingLedgerEntries: number
-  ledgerReconciliationDifferences: number
+export interface CounterpartyActivityReport {
+  report: ReportMeta
+  /** Карточка контрагента на момент построения отчёта */
+  counterparty: {
+    id: string
+    name: string
+    kind: string | null
+    /** Архивный контрагент отчёт не блокирует — история по нему остаётся */
+    archived: boolean
+    /** Адресов в справочнике у контрагента */
+    addressesCount: number
+    /** Группы контрагентов, в которых он состоит СЕЙЧАС */
+    groupIds: string[]
+  }
+  summary: ReportSummary
+  byAsset: ByAssetRow[]
+  byCounterpartyAddress: ByCounterpartyAddressRow[]
+  byOwnAddress: ByOwnAddressRow[]
+  /** Только при ?breakdownBy=owner. Без параметра ключа в ответе НЕТ — это не то же самое, что пустой массив */
+  byAddressOwner?: ByAddressOwnerRow[]
+  byStatus: ByStatusRow[]
+  byCategory: ByCategoryRow[]
+  timeline: TimelinePoint[]
+  approvals: ReportApprovals
+  comparison: Comparison
+  observations: Observation[]
+  dataQuality: DataQuality
+}
+
+export interface ByCounterpartyAddressRow {
+  /** Запись справочника адресов контрагента; null — адрес в справочник не внесён */
+  counterpartyAddressId: string | null
+  /** Внешний адрес (on-chain) */
+  address: string
+  /** Network.slug */
+  network: string
+  /** Задел; сейчас всегда null */
+  label: string | null
+  incomingByAsset: AssetAmount[]
+  outgoingByAsset: AssetAmount[]
+  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+  grossTurnoverUsd: string | null
+  operationsCount: number
+  incomingCount: number
+  outgoingCount: number
+  /** Доля адреса в USD-обороте отчёта, проценты decimal-строкой; null — нет USD-оценки или оборот нулевой */
+  turnoverShareUsd: string | null
+  firstOperationAt: string | null
+  lastOperationAt: string | null
+  /** true — до начала периода операций с этим адресом не было (в любом статусе, включая внутренние потоки) */
+  isNewInPeriod: boolean
 }
 
-export interface Comparison {
-  mode: string
-  previousFrom: string | null
-  previousTo: string | null
-  incomingUsdChangePercent: number | null
-  outgoingUsdChangePercent: number | null
-  grossTurnoverUsdChangePercent: number | null
-  operationsCountChangePercent: number | null
-  averageOperationUsdChangePercent: number | null
+export interface CounterpartyGroupActivityReport {
+  report: ReportMeta
+  group: {
+    id: string
+    code: string
+    name: string
+    /** Сколько контрагентов в группе СЕЙЧАС. При counterpartyClassification=historical выборка идёт по составу на момент отчёта и может не совпасть с этим числом */
+    counterpartiesCount: number
+  }
+  summary: ReportSummary
+  /** Только при ?breakdownBy=owner. Без параметра ключа в ответе НЕТ — это не то же самое, что пустой массив */
+  byAddressOwner?: ByAddressOwnerRow[]
+  byCounterparty: ByGroupCounterpartyRow[]
+  byAsset: ByAssetRow[]
+  byStatus: ByStatusRow[]
+  byCategory: ByCategoryRow[]
+  timeline: TimelinePoint[]
+  approvals: ReportApprovals
+  comparison: Comparison
+  observations: Observation[]
+  dataQuality: DataQuality
+}
+
+export interface ByGroupCounterpartyRow {
+  counterpartyId: string | null
+  name: string | null
+  kind: string | null
+  incomingByAsset: AssetAmount[]
+  outgoingByAsset: AssetAmount[]
+  /** Приток минус отток по активу, со знаком */
+  netFlowByAsset: AssetAmount[]
+  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+  grossTurnoverUsd: string | null
+  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+  netFlowUsd: string | null
+  operationsCount: number
+  /** Доля контрагента в USD-обороте группы, проценты decimal-строкой ("37.5"); null — у оборота нет USD-оценки или он нулевой */
+  shareOfGroupTurnoverUsd: string | null
+  firstOperationAt: string | null
+  lastOperationAt: string | null
 }
 
-export interface BalancesAsOf {
-  /** Момент среза (echo параметра ?at=) */
+export interface AssetMovementReport {
+  report: ReportMeta
+  asset: {
+    tokenId: string
+    /** Token.code из реестра */
+    code: string
+    symbol: string
+    name: string
+    decimals: number
+    /** Network.slug */
+    network: string
+    /** null у нативного актива сети */
+    contractAddress: string | null
+  }
+  /** Остаток актива на начало периода (from), из ledger. DECIMAL в единицах актива — не raw, в отличие от openingBalances у address_activity */
+  openingBalance: {
+    /** decimal */
+    available: string
+    /** decimal */
+    reserved: string
+    /** available + reserved, decimal */
+    total: string
+  }
+  /** Остаток актива на конец периода (to), из ledger. DECIMAL в единицах актива — не raw, в отличие от openingBalances у address_activity */
+  closingBalance: {
+    /** decimal */
+    available: string
+    /** decimal */
+    reserved: string
+    /** available + reserved, decimal */
+    total: string
+  }
+  summary: ReportSummary
+  byCounterparty: ByCounterpartyBriefRow[]
+  byOwnAddress: ByOwnAddressRow[]
+  /** Только при ?breakdownBy=owner. Без параметра ключа в ответе НЕТ — это не то же самое, что пустой массив */
+  byAddressOwner?: ByAddressOwnerRow[]
+  byStatus: ByStatusRow[]
+  byCategory: ByCategoryRow[]
+  timeline: TimelinePoint[]
+  comparison: Comparison
+  observations: Observation[]
+  dataQuality: DataQuality
+}
+
+export interface ByCounterpartyBriefRow {
+  /** null — операции без сопоставленного контрагента (одна строка на все) */
+  counterpartyId: string | null
+  /** Имя контрагента. У строки без контрагента (counterpartyId = null) сюда приходит английская заглушка "unmatched counterparty" — она не локализуется, поэтому различать такую строку надо по counterpartyId */
+  name: string | null
+  incomingByAsset: AssetAmount[]
+  outgoingByAsset: AssetAmount[]
+  /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+  grossTurnoverUsd: string | null
+  operationsCount: number
+}
+
+export interface AddressActivityReport {
+  report: ReportMeta
+  /** Цель отчёта, и форма у неё ДВЕ: при addressId — карточка адреса, при folderId — {folder:{id,name}}. Имя ключа одно на оба случая исторически */
+  address: {
+    id: string
+    address: string
+    label: string | null
+    description: string | null
+    /** Без апострофов: m/44/195/… */
+    derivationPath: string
+    segmentsJson: {
+      [key: string]: unknown
+    }
+    /** Network.slug */
+    network: string
+    createdAt: string
+  } | {
+    folder: {
+      id: string
+      name: string
+    }
+  }
+  /** Папки адреса. Вторая дата зависит от folderClassification: historical (по умолчанию) — validFrom из истории членства, current — createdAt текущего членства. При folderId — всегда пустой массив */
+  folderMemberships: Array<{
+    folderId: string
+    validFrom: string
+  } | {
+    folderId: string
+    createdAt: string
+  }>
+  /** Балансы счетов на начало периода (from), RAW. При addressId — счета этого адреса. При folderId выборка НЕ сужается до папки: приходят все счета scope вызывающего (у admin — весь Vault, включая external и adjustment) */
+  openingBalances: ReportAccountBalance[]
+  /** Балансы счетов на конец периода (to), RAW. При addressId — счета этого адреса. При folderId выборка НЕ сужается до папки: приходят все счета scope вызывающего (у admin — весь Vault, включая external и adjustment) */
+  closingBalances: ReportAccountBalance[]
+  summary: ReportSummary
+  /** Только при ?breakdownBy=owner. Без параметра ключа в ответе НЕТ — это не то же самое, что пустой массив */
+  byAddressOwner?: ByAddressOwnerRow[]
+  /** Доля адреса (папки) в USD-обороте всего scope за тот же период, проценты decimal-строкой; null — нет USD-оценки или оборот scope нулевой */
+  shareOfUserActivityUsd: string | null
+  byAsset: ByAssetRow[]
+  byCounterparty: ByCounterpartyBriefRow[]
+  byStatus: ByStatusRow[]
+  byCategory: ByCategoryRow[]
+  timeline: TimelinePoint[]
+  observations: Observation[]
+  dataQuality: DataQuality
+}
+
+export interface ReportAccountBalance {
+  accountId: string
+  /** available / reserved — счета адресов; external / adjustment — счета уровня Vault'а (без адреса): встречная сторона двойной записи */
+  purpose: "available" | "reserved" | "external" | "adjustment"
+  tokenId: string
+  /** null у счетов уровня Vault'а */
+  addressId: string | null
+  /** Raw smallest units со знаком — НЕ decimal */
+  balanceRaw: string
+}
+
+export interface OperationsExceptionsReport {
+  report: ReportMeta
+  summary: {
+    operationsCount: number
+    /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+    usdValue: string | null
+    /** null — выборка пуста */
+    oldestOperationAt: string | null
+    /** Возраст считается от createdAt до момента построения отчёта */
+    averageAgeSeconds: number | null
+    medianAgeSeconds: number | null
+  }
+  /** Всегда шесть строк в этом порядке, включая пустые корзины */
+  ageBuckets: Array<{
+    bucket: "0-15m" | "15-60m" | "1-6h" | "6-24h" | "1-3d" | ">3d"
+    count: number
+    /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+    usdValue: string | null
+  }>
+  byStatus: ByStatusRow[]
+  byAsset: ByAssetRow[]
+  byCounterparty: Array<{
+    /** null — операции без сопоставленного контрагента (одна строка на все) */
+    counterpartyId: string | null
+    /** Имя контрагента. У строки без контрагента (counterpartyId = null) сюда приходит английская заглушка "unmatched counterparty" — она не локализуется, поэтому различать такую строку надо по counterpartyId */
+    name: string | null
+    count: number
+    /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+    usdValue: string | null
+  }>
+  byInitiator: Array<{
+    /** null — у операции нет инициатора (депозиты) */
+    initiatorId: string | null
+    count: number
+    /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+    usdValue: string | null
+  }>
+  byDecisionPolicy: Array<{
+    /** null — решение по операции политика не принимала */
+    decisionPolicyId: string | null
+    code: string | null
+    count: number
+  }>
+  dataQuality: DataQuality
+}
+
+export interface ApprovalActivityReport {
+  report: ReportMeta
+  summary: {
+    requestsCount: number
+    pendingCount: number
+    approvedCount: number
+    rejectedCount: number
+    cancelledCount: number
+    /** approved / (approved + rejected) × 100, decimal-строка; null — решённых заявок нет. Отменённые в знаменатель не входят */
+    approvalRatePercent: string | null
+    rejectionRatePercent: string | null
+    /** cancelled / все заявки × 100; null — заявок нет */
+    cancellationRatePercent: string | null
+    /** От создания заявки до resolvedAt; null — решённых нет */
+    averageResolutionSeconds: number | null
+    medianResolutionSeconds: number | null
+    maximumResolutionSeconds: number | null
+    /** От создания заявки до первого голоса; null — голосов нет */
+    averageFirstVoteSeconds: number | null
+    medianFirstVoteSeconds: number | null
+    requestsWithoutVotes: number
+  }
+  byAction: Array<{
+    /** ApprovalRequest.action: transfer, composite… */
+    action: string
+    count: number
+    approvedCount: number
+    rejectedCount: number
+    cancelledCount: number
+    pendingCount: number
+    averageResolutionSeconds: number | null
+  }>
+  byInitiator: Array<{
+    userId: string
+    name: string
+    requestsCount: number
+    approvedCount: number
+    rejectedCount: number
+    cancelledCount: number
+    averageResolutionSeconds: number | null
+  }>
+  byApprover: Array<{
+    userId: string
+    /** Имя; если пользователь не найден — его userId */
+    name: string
+    assignedRequestsCount: number
+    votedCount: number
+    approveVotes: number
+    rejectVotes: number
+    pendingVotes: number
+    averageVoteSeconds: number | null
+    medianVoteSeconds: number | null
+  }>
+  byDecisionPolicy: Array<{
+    decisionPolicyId: string | null
+    code: string | null
+    /** Задел; сейчас всегда null */
+    name: string | null
+    triggeredCount: number
+    approvedCount: number
+    rejectedCount: number
+    pendingCount: number
+    averageResolutionSeconds: number | null
+  }>
+  timeline: Array<{
+    periodStart: string
+    createdCount: number
+    /** approved + rejected; отменённые не входят */
+    resolvedCount: number
+    approvedCount: number
+    rejectedCount: number
+    cancelledCount: number
+  }>
+  /** Только эхо параметра comparison: процентов изменения этот отчёт НЕ считает. У живого отчёта previous_year приходит как none; в снапшоте и при запуске шаблона значение не переводится и приходит как прислано */
+  comparison: {
+    mode: "none" | "previous_period" | "previous_year"
+  }
+  dataQuality: DataQuality
+}
+
+export interface BalancePositionReport {
+  report: ReportMeta
+  /** Момент позиции, ISO-8601 UTC */
   asOf: string
-  /** @defaultValue [] */
-  totals: Array<{
-    [key: string]: unknown
+  totalsByAsset: Array<{
+    tokenId: string
+    assetCode: string
+    assetSymbol: string
+    /** Network.slug */
+    network: string
+    /** decimal */
+    available: string
+    /** decimal */
+    reserved: string
+    /** available + reserved, decimal */
+    total: string
+    usdRate: string | null
+    /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+    usdValue: string | null
   }>
-  /** @defaultValue [] */
-  accounts: Array<{
-    [key: string]: unknown
+  byAddress: Array<{
+    addressId: string
+    address: string
+    label: string | null
+    balances: Array<{
+      tokenId: string
+      /** decimal */
+      available: string
+      /** decimal */
+      reserved: string
+      /** decimal */
+      total: string
+      /** USD-оценка, decimal-строка. null — курса на момент операции не было */
+      usdValue: string | null
+    }>
   }>
+  concentration: {
+    /** Доля крупнейшего адреса в USD, проценты decimal-строкой; null без USD-оценки */
+    largestAddressShareUsd: string | null
+    /** Доля пяти крупнейших адресов, проценты decimal-строкой; null без USD-оценки */
+    top5AddressesShareUsd: string | null
+  }
+  dataQuality: DataQuality
 }
 
+/** Один из десяти отчётов. Форму определяет report.type: у каждого типа своя схема, общих для всех блоков — только report и (кроме category_analytics) dataQuality */
+export type AnyReport = TransactionActivityReport | CounterpartyActivityReport | CounterpartyGroupActivityReport | AssetMovementReport | AddressActivityReport | AccountStatementReport | OperationsExceptionsReport | ApprovalActivityReport | BalancePositionReport | CategoryAnalytics
+
 export interface CategoryAnalytics {
-  report: ReportMeta
+  report: {
+    /** Тип отчёта, snake_case — тот же, что в пути и в ?type= */
+    type: "counterparty_activity" | "counterparty_group_activity" | "transaction_activity" | "asset_movement" | "address_activity" | "balance_position" | "account_statement" | "approval_activity" | "operations_exceptions" | "category_analytics"
+    generatedAt: string
+    /** Начало периода (включительно), ISO-8601 UTC. У balance_position from = to = момент позиции */
+    from: string
+    /** Конец периода (НЕ включительно), ISO-8601 UTC */
+    to: string
+    /** IANA-зона, в которой нарезан timeline. У balance_position всегда UTC */
+    timezone: string
+  }
   categoryKey: string
+  /** Операции с активным назначением этой категории */
   operationsCount: number
+  /** null — metricField не задан */
   metric: {
     fieldKey: string
-    agg: string
+    agg: "sum" | "avg" | "min" | "max" | "median" | "count"
     /** null, когда метрика деноминирована — см. byCurrency */
     value: string | null
     byCurrency: {
       [key: string]: unknown
     } | null
   } | null
+  /** null — groupByField не задан */
   groups: Array<{
+    /** Значение поля groupByField; null — у назначения поле не заполнено */
     key: string | null
+    /** Число НАЗНАЧЕНИЙ категории в группе, а не операций: у одной операции их может быть несколько, поэтому сумма по группам бывает больше operationsCount отчёта */
     operationsCount: number
     metric: string | null
     metricByCurrency: {
@@ -3931,6 +4510,80 @@ export interface CategoryAnalytics {
   }> | null
 }
 
+export interface BalancesAsOfAccount {
+  accountId: string
+  /** available / reserved — счета адресов; external / adjustment — счета уровня Vault'а (без адреса): встречная сторона двойной записи */
+  purpose: "available" | "reserved" | "external" | "adjustment"
+  tokenId: string
+  /** null у vault-level счетов */
+  addressId: string | null
+  /** Raw smallest units со знаком (vault-level счета бывают отрицательными) */
+  balance: string
+  /** То же в единицах актива. Если токена счёта нет в реестре — raw, как в balance */
+  balanceDecimal: string
+}
+
+export interface BalancesAsOf {
+  /** Момент среза: параметр ?at=, приведённый к ISO-8601 в UTC (не буквальное эхо) */
+  asOf: string
+  /** По строке на токен; складываются только available и reserved. Пустой массив — движений до момента среза не было (или ?purpose= выбрал external/adjustment): это «нет данных», а не «ноль» */
+  totals: BalancesAsOfTotal[]
+  /** Счета, по которым были движения до момента среза. ОТСУТСТВУЕТ при ?summary=true. Участник видит только счета адресов из своего scope; vault-level счета (external/adjustment) — только admin */
+  accounts?: BalancesAsOfAccount[]
+}
+
+export interface BalancesAsOfTotal {
+  token: {
+    code: string
+    symbol: string
+    decimals: number
+    /** Network.slug */
+    network: string
+  }
+  tokenId: string
+  /** DECIMAL (не raw!) — дубль availableDecimal; у GET /balances это поле raw */
+  available: string
+  availableDecimal: string
+  /** DECIMAL (не raw!) — дубль reservedDecimal; у GET /balances это поле raw */
+  reserved: string
+  reservedDecimal: string
+  /** available + reserved, decimal: резерв — ещё не расход, пока перевод не подтверждён */
+  ownedTotal: string
+}
+
+export interface CreateReportExportBody {
+  /** json — canonical JSON результата; csv — плоский реестр операций. xlsx и pdf схема принимает, а хендлер отклоняет: 400 REPORT_UNSUPPORTED_FORMAT */
+  format: "json" | "csv" | "xlsx" | "pdf"
+  /** Зарезервировано: сейчас не влияет на файл */
+  locale?: string
+  /** Зарезервировано: сейчас не влияет на файл */
+  timezone?: string
+  /** Зарезервировано: сейчас не влияет на файл (csv — всегда реестр, json — всегда результат) */
+  includeOperationRegister?: boolean
+}
+
+export interface CreateReportSnapshotBody {
+  reportType: "counterparty_activity" | "counterparty_group_activity" | "transaction_activity" | "asset_movement" | "address_activity" | "balance_position" | "account_statement" | "approval_activity" | "operations_exceptions" | "category_analytics"
+  /** Те же параметры, что уходили в живой отчёт query-строкой (from, to, timezone, фильтры, includeShared, цель отчёта). Сохраняются в снапшоте как есть — под именем `parametersJson` */
+  parameters: {
+    [key: string]: unknown
+  }
+}
+
+export interface CreateReportTemplateBody {
+  /** length: 1..120 */
+  name: string
+  /** length: 0..500 */
+  description?: string
+  reportType: "counterparty_activity" | "counterparty_group_activity" | "transaction_activity" | "asset_movement" | "address_activity" | "balance_position" | "account_statement" | "approval_activity" | "operations_exceptions" | "category_analytics"
+  /** Параметры отчёта, как в query живого отчёта. Вместо from/to можно задать relativePeriod {unit: day|week|month, offset} — даты вычислятся при запуске. В ответе лежат под именем `parametersJson` */
+  parameters: {
+    [key: string]: unknown
+  }
+  /** true — только admin */
+  isShared?: boolean
+}
+
 export interface DrilldownResponse {
   /** Операции с полями и categoryAssignments (sensitive-значения отредактированы по правам: значение null + ключ в redactedFields) */
   items: Array<{
@@ -3946,94 +4599,251 @@ export interface DrilldownResponse {
   }
 }
 
+export interface LedgerEntriesPage {
+  items: LedgerEntry[]
+  nextCursor: string | null
+}
+
 export interface LedgerEntry {
   id: string
   vaultId: string
-  /** deposit | transfer | adjustment … */
+  /** topup | transfer_reserve | transfer_confirm | transfer_refund | adjustment | genesis. Это НЕ хранимый kind: три вида переименованы на выходе (reserve → transfer_reserve, confirm → transfer_confirm, release → transfer_refund), остальные отдаются как есть. Фильтр ?entryType= понимает оба написания */
   entryType: string
-  reference: string | null
-  description: string | null
-  operationType: string | null
+  /** Документ-источник; null у корректировок и genesis */
+  operationType: "transfer" | "deposit" | null
+  /** id перевода или депозита — по operationType */
   operationId: string | null
-  token: {
-    [key: string]: unknown
-  } | null
-  effectiveAt: string
+  /** Время записи в журнал. По нему идут сортировка, фильтр from/to и балансы as-of */
   postedAt: string
+  /** Экономическое время события (для on-chain — время блока) */
+  effectiveAt: string
+  /** Ключ идемпотентности проводки (sourceKey), уникален: "topup:{eventId}", "reserve:{transferId}", "confirm:{transferId}", "release:{transferId}" */
+  reference: string
+  /** Примечание к проводке (memo) */
+  description: string | null
+  /** Токен проводки — по её ПЕРВОМУ постингу, взятому до фильтрации под права: присутствует, даже если postings у вызывающего пуст */
+  token: LedgerEntryToken | null
+  postings: LedgerPosting[]
+  /** То же значение, что postedAt */
   createdAt: string
-  postings: Array<{
-    id: string
-    accountId: string
-    amount: string
-    amountDecimal?: string
-    direction?: string
-    token?: {
-      [key: string]: unknown
-    } | null
-    account?: {
-      [key: string]: unknown
-    } | null
-  }>
+}
+
+export interface LedgerEntryToken {
+  id: string
+  code: string
+  symbol: string
+  decimals: number
+  /** Network.slug */
+  network: string
+  /** null у нативного актива сети */
+  contractAddress: string | null
+}
+
+export interface LedgerPosting {
+  id: string
+  accountId: string
+  /** available / reserved — счета адресов; external / adjustment — счета уровня Vault'а (без адреса): встречная сторона двойной записи */
+  accountPurpose: "available" | "reserved" | "external" | "adjustment"
+  /** address — счёт адреса; vault — счёт уровня Vault'а (external/adjustment) */
+  ownerType: "address" | "vault"
+  /** addressId для ownerType=address, иначе vaultId */
+  ownerId: string
+  /** null у vault-level счетов */
+  addressId: string | null
+  /** Raw smallest units со знаком: "2500000" | "-2500000" */
+  amountRawSigned: string
+  /** Та же сумма в единицах актива, со знаком: "-2.5". Если токена постинга нет в реестре (чего при живом FK быть не должно), сюда попадает raw — значение совпадёт с amountRawSigned */
+  amountDecimalSigned: string
+}
+
+export interface PatchReportTemplateBody {
+  /** length: 1..120 */
+  name?: string
+  /** length: 0..500 */
+  description?: string
+  reportType?: "counterparty_activity" | "counterparty_group_activity" | "transaction_activity" | "asset_movement" | "address_activity" | "balance_position" | "account_statement" | "approval_activity" | "operations_exceptions" | "category_analytics"
+  /** Параметры отчёта, как в query живого отчёта. Вместо from/to можно задать relativePeriod {unit: day|week|month, offset} — даты вычислятся при запуске. В ответе лежат под именем `parametersJson` */
+  parameters?: {
+    [key: string]: unknown
+  }
+  /** true — только admin */
+  isShared?: boolean
+}
+
+export interface ReportDrilldownBody {
+  reportType?: string
+  /** @defaultValue {} */
+  filters?: {
+    [key: string]: unknown
+  }
+  /** @defaultValue {} */
+  drilldown?: {
+    [key: string]: unknown
+  }
+  snapshotId?: string | null
+  /**
+   * range: 1..500
+   * @defaultValue 100
+   */
+  limit?: number
+  cursor?: string | null
 }
 
 export interface ReportExport {
   id: string
+  vaultId: string
   snapshotId: string
+  /** json | csv */
   format: string
+  /** queued | processing | completed | failed; экспорт синхронный, поэтому сейчас всегда completed */
   status: string
-  filename: string | null
+  requestedById: string
+  requestedAt: string
+  completedAt: string | null
+  /** Задел под R2; сейчас всегда null */
+  storageKey: string | null
   mimeType: string | null
+  filename: string | null
+  /** Длина содержимого в СИМВОЛАХ, а не в байтах: для не-ASCII текста (кириллица в подписях адресов) файл на диске будет больше */
   sizeBytes: number | null
+  /** sha256 содержимого файла */
   fileHash: string | null
-  requestedById: string
-  completedAt: string | null
+  errorCode: string | null
+  errorMessage: string | null
 }
 
-export interface ReportSnapshot {
+export interface ReportSnapshotDetail {
   id: string
-  vaultId: string
   /** snake_case, как и везде */
   reportType: string
-  status: string
-  schemaVersion: string | null
+  /** Версия формата результата; сейчас всегда "reporting_v1" */
+  schemaVersion: string
+  /** Тело `parameters` запроса создания, как есть */
   parametersJson: {
     [key: string]: unknown
-  } | null
-  /** Хеш нормализованных параметров — одинаковый запрос даёт одинаковый хеш */
-  normalizedParametersHash: string | null
-  result?: {
-    [key: string]: unknown
-  } | null
-  /** canonical sha256 результата — доказательство, что содержимое не подменили */
-  resultHash: string | null
-  /** Задел под R2; сейчас всегда null */
-  resultStorageKey: string | null
-  rowCount: number | null
-  /** Манифест: ключи операций, вошедших в снапшот (для drill-down по снапшоту) */
-  includedOperationKeysJson?: string[] | null
-  includedOperationKeysStorageKey?: string | null
-  dataCutoffAt: string | null
+  }
+  generatedById: string
+  generatedAt: string
+  /** Срез данных: операции новее в снапшот не вошли. Совпадает с generatedAt */
+  dataCutoffAt: string
+  /** Число операций в манифесте; 0, если манифеста нет — у отчётов без пооперационной выборки (balance_position, approval_activity) */
+  rowCount: number
+  /** sha256 canonical JSON результата — доказательство, что содержимое не подменили */
+  resultHash: string
+  /** generating | completed | failed; создание синхронное, поэтому сейчас всегда completed */
+  status: string
+  createdAt: string
+  vaultId: string
+  /** sha256 canonical JSON параметров — одинаковый запрос даёт одинаковый хеш */
+  normalizedParametersHash: string
+  /** Задел; сейчас всегда null */
   dataCutoffBlock: number | null
+  /** current | historical — из параметра counterpartyClassification, по умолчанию historical */
   counterpartyClassificationMode: string | null
+  /** current | historical — из параметра folderClassification, по умолчанию historical */
   folderClassificationMode: string | null
+  /** Задел под R2; сейчас всегда null */
+  resultStorageKey: string | null
+  /** Манифест: ключи операций, вошедших в снапшот (по нему строится drill-down по снапшоту). null — у отчёта нет пооперационной выборки или манифест собрать не удалось */
+  includedOperationKeysJson: string[] | null
+  /** Задел под R2; сейчас всегда null */
+  includedOperationKeysStorageKey: string | null
   errorCode: string | null
   errorMessage: string | null
+  /** В ответах всегда null: скрытый (soft-delete) снапшот не отдаётся вовсе — 404 */
+  deletedAt: string | null
+  /** Результат отчёта, зафиксированный при создании. В ответе создания то же самое называется `result`. null возможен только у снапшота, который не достроился (status ≠ completed) */
+  resultJson: {
+    [key: string]: unknown
+  } | null
+}
+
+export interface ReportSnapshotListItem {
+  id: string
+  /** snake_case, как и везде */
+  reportType: string
+  /** Версия формата результата; сейчас всегда "reporting_v1" */
+  schemaVersion: string
+  /** Тело `parameters` запроса создания, как есть */
+  parametersJson: {
+    [key: string]: unknown
+  }
+  generatedById: string
+  generatedAt: string
+  /** Срез данных: операции новее в снапшот не вошли. Совпадает с generatedAt */
+  dataCutoffAt: string
+  /** Число операций в манифесте; 0, если манифеста нет — у отчётов без пооперационной выборки (balance_position, approval_activity) */
+  rowCount: number
+  /** sha256 canonical JSON результата — доказательство, что содержимое не подменили */
+  resultHash: string
+  /** generating | completed | failed; создание синхронное, поэтому сейчас всегда completed */
+  status: string
+  createdAt: string
+}
+
+export interface ReportSnapshotList {
+  items: ReportSnapshotListItem[]
+}
+
+export interface ReportSnapshot {
+  id: string
+  /** snake_case, как и везде */
+  reportType: string
+  /** Версия формата результата; сейчас всегда "reporting_v1" */
+  schemaVersion: string
+  /** Тело `parameters` запроса создания, как есть */
+  parametersJson: {
+    [key: string]: unknown
+  }
   generatedById: string
   generatedAt: string
+  /** Срез данных: операции новее в снапшот не вошли. Совпадает с generatedAt */
+  dataCutoffAt: string
+  /** Число операций в манифесте; 0, если манифеста нет — у отчётов без пооперационной выборки (balance_position, approval_activity) */
+  rowCount: number
+  /** sha256 canonical JSON результата — доказательство, что содержимое не подменили */
+  resultHash: string
+  /** generating | completed | failed; создание синхронное, поэтому сейчас всегда completed */
+  status: string
   createdAt: string
+  vaultId: string
+  /** sha256 canonical JSON параметров — одинаковый запрос даёт одинаковый хеш */
+  normalizedParametersHash: string
+  /** Задел; сейчас всегда null */
+  dataCutoffBlock: number | null
+  /** current | historical — из параметра counterpartyClassification, по умолчанию historical */
+  counterpartyClassificationMode: string | null
+  /** current | historical — из параметра folderClassification, по умолчанию historical */
+  folderClassificationMode: string | null
+  /** Задел под R2; сейчас всегда null */
+  resultStorageKey: string | null
+  /** Манифест: ключи операций, вошедших в снапшот (по нему строится drill-down по снапшоту). null — у отчёта нет пооперационной выборки или манифест собрать не удалось */
+  includedOperationKeysJson: string[] | null
+  /** Задел под R2; сейчас всегда null */
+  includedOperationKeysStorageKey: string | null
+  errorCode: string | null
+  errorMessage: string | null
+  /** В ответах всегда null: скрытый (soft-delete) снапшот не отдаётся вовсе — 404 */
   deletedAt: string | null
+  /** Результат отчёта — тот же объект, что вернул бы живой отчёт. ТОЛЬКО в ответе создания; деталь отдаёт его как `resultJson` */
+  result: {
+    [key: string]: unknown
+  }
 }
 
 export interface ReportTemplate {
   id: string
   vaultId: string
+  /** Создатель шаблона */
+  ownerId: string
   name: string
+  description: string | null
   reportType: string
+  /** Тело `parameters` запроса создания, как есть (включая relativePeriod) */
   parametersJson: {
     [key: string]: unknown
-  } | null
+  }
   isShared: boolean
-  createdById: string
   createdAt: string
-  updatedAt?: string
+  updatedAt: string
 }