@v3finance/core-sdk 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes to this package are documented in this file. The format is based on
 [Keep a Changelog](https://keepachangelog.com), and this project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.2.2 — 2026-11-12
+
+Spec snapshot refreshed from the live API (commit `3ca1538`,
+[v3-finance/policy-engine#22](https://github.com/v3-finance/policy-engine/pull/22)). No operation
+was added or removed, and no code in this package changed: the API's money path did.
+
+### Changed
+
+- `transfers.send()` — when the signing service gives no definite answer, the transfer is no
+  longer failed: it stays `pending` with its funds reserved, the call throws 502
+  `TRANSFER_OUTCOME_UNKNOWN` (`details.transactionId`), and an administrator's reconciliation
+  settles it. Retry only with the same `idempotencyKey`. `WALLET_SERVICE_ERROR` on a transfer is
+  now only the 400 of a definite refusal; the documented 502 "retry with a new key" is gone.
+- `transfers.send()` — the same key with different parameters is 409 `IDEMPOTENCY_KEY_REUSED`, not
+  the earlier transfer; `toAddress` is checked against the network before anything is reserved,
+  400 `INVALID_DESTINATION_ADDRESS`.
+- `transfers.vote()` and `approvals.vote()` — an unknown outcome is not an error: `pending` with
+  `executionError: null`, or `APPROVED` with `finalized: false` and `applyError: null`. That answer
+  does not establish the outcome; read the transfer. Repeating the same vote on an open request
+  finishes it instead of answering 409 `ALREADY_VOTED`.
+- `transfers.reconcile()` — `ReconcileTransferResult.status` gains `rejected` and `cancelled`
+  (a closed transfer whose reserve is still held: the reserve is returned, the status stays). An
+  exhaustiveness check over `confirmed | failed` stops compiling. A `pending` transfer that holds a
+  hash from the signing service is settled only by that hash, sent explicitly.
+- `failureReason` is `null` on every status except `failed`, `rejected` and `cancelled`.
+- `docs/errors.md`: the new codes — `TRANSFER_OUTCOME_UNKNOWN`, `TRANSFER_BROADCAST_UNRECORDED`,
+  `IDEMPOTENCY_KEY_REUSED`, `INVALID_DESTINATION_ADDRESS`, `REQUEST_INCOMPLETE`, and for
+  reconciliation `TRANSFER_BROADCAST`, `TXHASH_MISMATCH`, `TXHASH_IN_USE`, `TRANSFER_NOT_EXECUTED`,
+  `RESERVE_MISSING`, `RESERVE_RELEASED`.
+
 ## 0.2.1 — 2026-11-12
 
 ### Added

package/README.md

@@ -127,7 +127,8 @@ switch (result.outcome) {
 Reporting "sent" on `pending` tells a person their money has gone when it is frozen. `replayed` is
 not "sent" either: it means a transfer with this key already existed, and its `status` says whether
 it went out (`confirmed` or `submitted`), is waiting for signatures (`awaiting_approval`), is still
-executing (`pending`) or did not go out (`failed`, `rejected`, `cancelled`).
+executing or waiting for an administrator to reconcile it (`pending`) or did not go out (`failed`,
+`rejected`, `cancelled`).
 
 **Always pass `idempotencyKey`** on a transfer and keep it until you have an answer: after a
 timeout it is the only way to retry without sending money twice. The key is read from the request

package/dist/cjs/generated/operations.js

@@ -10,7 +10,7 @@
 // the API does not slip in unclassified.
 //
 // Operations: 171 · admin: 40 · both: 1 · member: 127 · service: 3
-// Spec sha256: 017bae30075b232ab4efdcfb7785335020be3060b46e3569b1cd887fcf037597
+// Spec sha256: 30be5f9b9733d1d1d67eebf21e0bfaa457651e951676211ec9fa464cca5d3795
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OPERATIONS = void 0;
 exports.isAdminOperation = isAdminOperation;

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

@@ -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;
@@ -1625,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;
@@ -1639,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
      */
@@ -1915,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;
@@ -2991,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;
@@ -2999,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 {
@@ -3018,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;
@@ -3179,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;
@@ -3496,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-голосов
@@ -3506,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;