@v3finance/core-sdk 0.2.0 → 0.2.2

package/dist/esm/generated/types.d.ts

@@ -229,8 +229,8 @@ export interface AddressDetail {
     tokenId: string | null;
     /** format: date-time */
     createdAt: string;
-    /** Сводка совместного доступа. Приходит в списке и детали адреса; PATCH /addresses/{id} переиспользует эту же схему и sharing НЕ возвращает */
-    sharing?: SharingSummary;
+    /** Сводка совместного доступа. Приходит всегда: в списке, ответе PATCH и детали адреса */
+    sharing: SharingSummary;
     /** Код токена адреса (из segmentsJson + asset route) */
     asset: string | null;
     assetName: string | null;
@@ -297,6 +297,7 @@ export interface OutgoingTxSummary {
     status: string;
     txHash: string | null;
     fee: string | null;
+    /** Причина закрытия — только у failed/rejected/cancelled. У остальных статусов (awaiting_approval, pending, submitted, confirmed) — ВСЕГДА null: у незакрытого перевода причины отказа нет. Неясный исход исполнения (pending, транзакция могла уйти в сеть) здесь не показывается — его признак pending дольше 10 минут по updatedAt («ждёт сверки администратором») */
     failureReason: string | null;
     /** format: date-time */
     createdAt: string;
@@ -461,8 +462,8 @@ export interface AddressListItem {
     assetSymbol: string | null;
     /** Баланс в decimal (по token.decimals). NULL — ledger-счёта ещё нет */
     balanceDecimal: string | null;
-    /** Сводка совместного доступа. Приходит в списке и детали адреса; PATCH /addresses/{id} переиспользует эту же схему и sharing НЕ возвращает */
-    sharing?: SharingSummary;
+    /** Сводка совместного доступа. Приходит всегда: в списке, ответе PATCH и детали адреса */
+    sharing: SharingSummary;
     /** Владелец адреса (создатель) с UI-метаданными */
     owner: MemberCard | null;
     access: AddressAccess;
@@ -745,11 +746,11 @@ export interface ApprovalRequestDetail {
 }
 export interface ApprovalRequestEvent {
     id: string;
-    /** created|voted|approved|rejected|cancelled|applied|apply_failed|stale */
+    /** created|voted|approved|rejected|cancelled|applied|apply_failed|stale|folder_skipped. folder_skipped идёт ПОСЛЕ applied: адрес по заявке create_address создан, но в папку, выбранную при подаче, не положен (папку удалили или у инициатора отозвали право) — причина в comment */
     type: string;
     actorId: string | null;
     decision: string | null;
-    /** Пояснение ПОДПИСАНТА. У события applied всегда null — id созданного объекта лежит в resultId, чтобы клиент не напечатал его как комментарий */
+    /** У voted — пояснение ПОДПИСАНТА; у stale, apply_failed и folder_skipped — системное пояснение для человека. У события applied всегда null — id созданного объекта лежит в resultId, чтобы клиент не напечатал его как комментарий */
     comment: string | null;
     /** Только у applied: id созданного/изменённого объекта */
     resultId: string | null;
@@ -1250,7 +1251,7 @@ export interface CreateAddressBody {
      * length: 1..16
      */
     emoji?: string;
-    /** Создать адрес В группу адресов (нужно право create_address на группе). Новый адрес — member группы, доступен её участникам */
+    /** Создать адрес В группу адресов (нужно право create_address на группе). Новый адрес — member группы, доступен её участникам. Если создание ушло на подпись (202), папка сохраняется в заявке, а право на неё перепроверяется при применении: отозвали — адрес создаётся без папки, с оговоркой applyWarnings в ответе голосования. При прямом создании (201) то же — оговорка `warnings` в теле ответа */
     groupId?: string;
 }
 export interface CreateAddressGroupBody {
@@ -1274,6 +1275,14 @@ export interface CreateAddressResult {
         label: string | null;
         description: string | null;
     };
+    /** Создано, но не всё: адрес есть, а в папку из `groupId` не положен. Право на папку роут проверяет до создания (иначе 403), а запись членства — уже после Wallet Service и мониторинга; право могли отозвать в этом окне или запись могла не пройти. Есть только когда непусто; не показывать адрес в папке, если оговорка пришла */
+    warnings?: FolderSkipWarning[];
+}
+export interface FolderSkipWarning {
+    /** FOLDER_NOT_FOUND — папку удалили; FOLDER_FORBIDDEN — у создателя адреса больше нет права заводить в неё адреса; FOLDER_WRITE_FAILED — сбой записи */
+    code: "FOLDER_NOT_FOUND" | "FOLDER_FORBIDDEN" | "FOLDER_WRITE_FAILED";
+    /** Готовая фраза для человека */
+    message: string;
 }
 export interface CreateCompositeBody {
     /**
@@ -1617,7 +1626,7 @@ export interface CreateTransactionResult {
         amountDecimal: string;
         asset: string;
         network: string;
-        /** confirmed — новый успешный перевод; pending/failed возможны при replay по idempotencyKey */
+        /** 201 — confirmed (исполнен сейчас); редко pending с заполненным txHash (транзакция ушла в сеть, а учёт не записался — доводит сверка, повторять перевод нельзя); 202 — awaiting_approval; 200 (replay по idempotencyKey) — ТЕКУЩИЙ статус перевода, любой: pending (первый запрос ещё исполняется — или его исход неизвестен: первый ответ был 502 TRANSFER_OUTCOME_UNKNOWN; повтор НЕ исполняет перевод заново, исход устанавливает сверка), awaiting_approval, confirmed, failed, rejected, cancelled */
         status: string;
         txHash: string | null;
         fee: string | null;
@@ -1631,12 +1640,13 @@ export interface CreateTransactionResult {
 }
 export interface CreateTransferBody {
     fromAddressId: string;
+    /** Адрес получателя. Формат проверяется по типу сети адреса-отправителя ДО резерва средств: TRON — base58check (34 символа, «T…», контрольная сумма), EVM — 0x + 40 hex (смешанный регистр — контрольная сумма EIP-55). Не подошёл — 400 INVALID_DESTINATION_ADDRESS. Строка проверяется как есть, пробелы по краям — ошибка формата */
     toAddress: string;
     /** DECIMAL строка — конвертируется по token.decimals */
     amount: string;
     asset: string;
     /**
-     * Уникальный ключ попытки перевода (рекомендуется: uuid). Повторный запрос с тем же ключом вернёт существующую транзакцию без второго broadcast. Для новой попытки после failed — новый ключ.
+     * Уникальный ключ попытки перевода (рекомендуется: uuid). Повторный запрос с тем же ключом и теми же параметрами вернёт 200 с существующим переводом — без второго broadcast, без повторной оценки политик. Тот же ключ с другими параметрами — 409 IDEMPOTENCY_KEY_REUSED. Для новой попытки после failed — новый ключ.
      *
      * length: 8..128
      */
@@ -1907,6 +1917,7 @@ export interface HistoryOutItem {
     asset: string;
     assetSymbol: string;
     fee: string | null;
+    /** Причина закрытия — только у failed/rejected/cancelled. У остальных статусов (awaiting_approval, pending, submitted, confirmed) — ВСЕГДА null: у незакрытого перевода причины отказа нет. Неясный исход исполнения (pending, транзакция могла уйти в сеть) здесь не показывается — его признак pending дольше 10 минут по updatedAt («ждёт сверки администратором») */
     failureReason: string | null;
     fromAddress: {
         id: string;
@@ -2983,7 +2994,7 @@ export interface RatesResponse {
     }>;
 }
 export interface ReconcileTransferBody {
-    /** Хеш от подписывающего сервиса. ЕСТЬ — транзакция ушла в сеть, перевод доводится до confirmed. НЕТ (или null) — считаем, что broadcast'а не было, и возвращаем резерв (failed) */
+    /** Хеш от подписывающего сервиса. ЕСТЬ — транзакция ушла в сеть, перевод доводится до confirmed. НЕТ (или null) — сверяющий утверждает, что broadcast'а не было, и резерв возвращается (failed). Для pending с неясным исходом (у pending без txHash его не отличить по ответам API — failureReason у незакрытого перевода null) это утверждение нужно ПРОВЕРИТЬ по сети: возврат за ушедшую транзакцию печатает деньги. Если у pending-перевода хеш уже сохранён (broadcast прошёл), он обязателен: без него — 409 TRANSFER_BROADCAST, с другим — 409 TXHASH_MISMATCH (сохранённый — в error.details.txHash) */
     txHash?: string | null;
     /** Комиссия, если известна */
     fee?: string | null;
@@ -2991,7 +3002,8 @@ export interface ReconcileTransferBody {
     reason?: string | null;
 }
 export interface ReconcileTransferResult {
-    status: "confirmed" | "failed";
+    /** Статус перевода после сверки: confirmed (по хешу) | failed (резерв возвращён). rejected/cancelled — у закрытого перевода с невозвращённым резервом: резерв возвращён, статус прежний */
+    status: "confirmed" | "failed" | "rejected" | "cancelled";
     txHash: string | null;
 }
 export interface RegisterPushTokenBody {
@@ -3010,8 +3022,9 @@ export interface RequestVoteResult {
     approvals: number;
     /** range: -9007199254740991..9007199254740991 */
     threshold: number;
-    /** true — этот голос финализировал заявку (применена/отклонена) */
+    /** true — этот голос финализировал заявку (применена/отклонена). У заявки на перевод status=APPROVED при finalized=false значит, что исход рассчитал НЕ этот вызов: applyError пуст — перевод исполняет (исполнил) параллельный запрос ЛИБО исполнение, начатое другим вызовом, оборвалось (сам перевод тогда не закроется); исход — только по GET /transfers/{id}: confirmed/failed, а pending дольше 10 минут по updatedAt — ждёт сверки (admin). applyError TRANSFER_EXECUTION_FAILED — к моменту одобрения перевод уже не ждал подписей. finalized=false с пустым applyError приходит и тогда, когда одобрил ЭТОТ голос, но исход перевода им не установлен (перевод pending: подписывающий сервис не дал определённого ответа, транзакция могла уйти в сеть, а могла и нет): показывайте «голос учтён», не «применено». finalized=true с пустым applyError у перевода — исполнен этим вызовом (confirmed) */
     finalized: boolean;
+    /** Голос финализировал заявку, а применение не дало результата; status при этом итоговый. Коды: STALE — цель изменилась (status=REJECTED); APPLY_FAILED / APPLY_FAILED_ROLLED_BACK / APPLY_FAILED_PARTIAL — мутация не применена (целиком / цепочка откатана / частично). У action=transfer финальный approve ИСПОЛНЯЕТ перевод, status=APPROVED: TRANSFER_EXECUTION_FAILED — перевод не исполнен (обычно failed, резерв возвращён; точный статус — GET /transfers/{id}; при finalized=false — перевод уже не ждал подписей, одобрение его не исполняло). Неясный исход перевода (подписывающий сервис не дал определённого ответа, перевод pending, средства зарезервированы, транзакция могла уйти в сеть, исход установит сверка, admin) ошибкой НЕ отдаётся: applyError null, status APPROVED, finalized=false. Кода TRANSFER_OUTCOME_UNKNOWN здесь нет — он только у POST /transfers */
     applyError: {
         code: string;
         message: string;
@@ -3019,6 +3032,8 @@ export interface RequestVoteResult {
     resolvedResultId: string | null;
     /** Только для композитных заявок: прогресс по шагам */
     stepsProgress?: StepProgress[];
+    /** Применено, но не всё: адрес по заявке create_address создан (resolvedResultId), а в папку, выбранную при подаче, не положен. Право на папку проверяется при ПРИМЕНЕНИИ, а не при подаче. Есть только когда непусто; в истории заявки — событие folder_skipped */
+    applyWarnings?: FolderSkipWarning[];
 }
 export interface StepProgress {
     /** range: -9007199254740991..9007199254740991 */
@@ -3169,6 +3184,7 @@ export interface TransactionDetail {
     decisionPolicyCode: string | null;
     /** Человеческое название решающей политики (для UI вместо кода) */
     decisionPolicyName: string | null;
+    /** Причина закрытия — только у failed/rejected/cancelled. У остальных статусов (awaiting_approval, pending, submitted, confirmed) — ВСЕГДА null: у незакрытого перевода причины отказа нет. Неясный исход исполнения (pending, транзакция могла уйти в сеть) здесь не показывается — его признак pending дольше 10 минут по updatedAt («ждёт сверки администратором») */
     failureReason: string | null;
     /** format: date-time */
     createdAt: string;
@@ -3486,7 +3502,7 @@ export interface VoteRequestBody {
     comment?: string;
 }
 export interface VoteResult {
-    /** Статус перевода ПОСЛЕ голоса: awaiting_approval (голосов мало) | rejected | confirmed/failed (финальный approve исполняет сразу) */
+    /** Статус перевода ПОСЛЕ голоса: awaiting_approval (голосов мало) | rejected | confirmed/failed (финальный approve исполняет сразу). pending — исполнение не закончено, повторять перевод нельзя; executionError у pending всегда null, исход этим ответом НЕ установлен, ждать его «через секунды» нельзя. Так отдаётся и неясный исход (подписывающий сервис не дал определённого ответа, транзакция могла уйти в сеть, резерв стоит — доводит сверка, admin), и: txHash в GET /transfers/{id} есть — транзакция ушла в сеть, а учёт не записался, доводит сверка (admin) по этому хешу; перевод исполняет параллельный запрос (одновременный голос другого подписанта или исходный вызов при повторе голоса) ЛИБО исполнение оборвалось (клиент, который его начал, отключился — сам перевод тогда не закроется). Различает только время: перечитывайте GET; confirmed/failed — исход; pending дольше 10 минут по updatedAt — «ждёт сверки администратором» */
     status: string;
     /**
      * Собрано approve-голосов
@@ -3496,7 +3512,7 @@ export interface VoteResult {
     approvals: number;
     /** range: -9007199254740991..9007199254740991 */
     threshold: number;
-    /** Если финальный approve запустил исполнение и оно упало (средства возвращены) */
+    /** Финальный approve запустил исполнение, и оно перевод НЕ исполнило. code: TRANSFER_EXECUTION_FAILED — не исполнен (status=failed, средства возвращены; исключения: failed с txHash у перевода, см. описание ручки, и status=pending, если сам возврат резерва не записался — тогда перевод доводит сверка). Тот же код — если к моменту одобрения перевод уже не ждал подписей (status — его фактический: failed/rejected/cancelled): одобрение его не исполнило. Неясный исход (подписывающий сервис не дал определённого ответа, транзакция могла уйти в сеть) ошибкой НЕ отдаётся: status=pending, executionError=null — показывайте «исполняется, исход уточняется». Кода TRANSFER_OUTCOME_UNKNOWN в голосе нет, он только у POST /transfers */
     executionError: {
         code: string;
         message: string;