@v3finance/core-sdk 0.2.1 → 0.2.3

package/dist/cjs/resources/transfers.d.ts

@@ -11,7 +11,10 @@ export interface VoteInput {
  * The result of sending is `Gated`, and that is the main thing to understand
  * here. The same `{transaction}` body comes back in three situations:
  *
- *   applied (201)  — executed, the money left;
+ *   applied (201)  — executed, the money left (rarely the status is still
+ *                    `pending` with a `txHash`: it went out, but its
+ *                    accounting was not recorded, and an administrator's
+ *                    reconciliation finishes it — do not send it again);
  *   pending (202)  — awaiting signatures, funds RESERVED but not sent;
  *   replayed (200) — a transfer with this `idempotencyKey` already existed,
  *                    and this is that transfer as it stands NOW.
@@ -24,7 +27,10 @@ export interface VoteInput {
  *
  *   confirmed, submitted     — it left;
  *   awaiting_approval        — waiting for signatures, funds reserved;
- *   pending                  — still executing;
+ *   pending                  — still executing, or its outcome is unknown
+ *                              (the first answer was 502
+ *                              `TRANSFER_OUTCOME_UNKNOWN`) until an
+ *                              administrator reconciles it;
  *   failed, rejected,
  *   cancelled                — it did not leave.
  */
@@ -37,6 +43,12 @@ export declare class TransfersResource {
      * On `outcome: 'replayed'` read `data.transaction.status` before telling
      * anyone anything — a replay of an attempt that failed, or that is still
      * waiting for signatures, comes back the same way as one that went out.
+     *
+     * A thrown 502 `TRANSFER_OUTCOME_UNKNOWN` is not a failure: the signing
+     * service gave no definite answer, the transaction may have left, and the
+     * transfer stays `pending` with its funds reserved (`details.transactionId`).
+     * Retry it only with the SAME key — that returns the transfer without
+     * executing it again; a new key can send the money twice.
      */
     send(input: CreateTransferBody, options?: {
         signal?: AbortSignal;
@@ -45,7 +57,9 @@ export declare class TransfersResource {
     /**
      * One transfer in full. Note the shape: this is the transaction itself, not
      * the `{ transaction }` wrapper that `send()` returns — and it carries more,
-     * including `amlLevel`, `approvers`, `usdRate` and `failureReason`.
+     * including `amlLevel`, `approvers`, `usdRate` and `failureReason` — the
+     * last only on `failed`, `rejected` and `cancelled`, `null` on any other
+     * status.
      */
     get(transferId: string): Promise<TransactionDetail>;
     /**
@@ -61,11 +75,30 @@ export declare class TransfersResource {
      *   awaiting_approval — counted, more signatures still needed;
      *   rejected          — a `reject` is a veto, and the reserve is released;
      *   confirmed/failed  — this vote completed the threshold, so execution ran
-     *                       INSIDE this request (gas, then broadcast, ~10s).
+     *                       INSIDE this request (gas, then broadcast, ~10s);
+     *   pending           — with no `executionError`: the outcome is NOT
+     *                       established by this answer. The signing service
+     *                       gave no definite answer (the transaction may have
+     *                       left; an administrator's reconciliation settles
+     *                       it), another call is executing the transfer, or
+     *                       the execution broke off. Re-read the transfer:
+     *                       `confirmed`/`failed` is the outcome, `pending` for
+     *                       over 10 minutes by `updatedAt` is waiting for
+     *                       reconciliation. Never send it again.
      *
      * `failed` means the money is back: execution broke after approval and the
      * reserve was released, with the reason in `executionError`. Treating the
-     * call as "approved, done" hides both the success and that failure.
+     * call as "approved, done" hides both the success and that failure. The
+     * exception is a `failed` transfer that has a `txHash`: it went out after
+     * reconciliation had already returned the reserve, and an administrator has
+     * to correct the ledger. `executionError` beside `rejected` or `cancelled`
+     * means the transfer was no longer waiting for signatures when approved,
+     * and nothing was executed.
+     *
+     * Repeating the same decision while the transfer is still waiting finishes
+     * what an earlier call left undone (it recorded the vote and broke off) — a
+     * veto, or execution once the threshold is met — instead of 409
+     * `ALREADY_VOTED`.
      */
     vote(transferId: string, input: VoteInput): Promise<VoteResult>;
     /**
@@ -84,19 +117,34 @@ export declare class TransfersResource {
      */
     cancel(transferId: string): Promise<CancelResult>;
     /**
-     * Settles a transfer stuck in `pending` — the case where the worker died
-     * mid-execution, so cancelling does not apply. Administrators only.
+     * Settles a transfer nothing else can close. Administrators only.
+     *
+     *   pending            — execution died, or its outcome is unknown (the
+     *                        send answered 502 `TRANSFER_OUTCOME_UNKNOWN`);
+     *   awaiting_approval  — with no live approval request to vote on;
+     *   failed, rejected,
+     *   cancelled          — closed, but the reserve is still held: it is
+     *                        returned, and the status stays.
+     *
+     * A pending transfer is decided by the HASH: send `txHash` and it is driven
+     * to `confirmed`; send none and the reserve is returned (`failed`). Sending
+     * none is YOUR statement that nothing was broadcast — the server does not
+     * check it, so look on the chain first: returning the reserve of a
+     * transaction that did go out creates money. If the transfer already holds
+     * a hash from the signing service, only that hash, sent explicitly, settles
+     * it — 409 `TRANSFER_BROADCAST` without one, `TXHASH_MISMATCH` with another,
+     * the saved hash in `details.txHash`. The other two cases never executed
+     * and take no hash.
      *
-     * The decision is made by the HASH: send `txHash` and the transfer is
-     * driven to `confirmed`, because the signing service did put it on the
-     * chain; send none and the reserve is returned, because there was no
-     * broadcast. A FRESH pending transfer is refused on purpose — while
-     * execution may still be in flight, intervening risks a SECOND broadcast,
-     * which costs more than waiting.
+     * A FRESH transfer is refused on purpose — while execution may still be in
+     * flight, intervening risks a SECOND broadcast, which costs more than
+     * waiting.
      *
-     * Pass `fee` along with the hash if you know it: this is the only moment
-     * it can be recorded on a transfer settled this way, and it stays null
-     * otherwise. The answer says which way it went — `confirmed` or `failed`.
+     * Pass `fee` along with the hash if you know it: this is the only moment it
+     * can be recorded on a transfer settled this way; otherwise it stays as it
+     * is, null unless the signing service reported one. The answer says which
+     * way it went — `confirmed`, `failed`, or the unchanged `rejected` /
+     * `cancelled` of a closed transfer.
      */
     reconcile(transferId: string, input?: ReconcileTransferBody): Promise<ReconcileTransferResult>;
 }

package/dist/cjs/resources/transfers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfers.d.ts","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAiB;;IAI5B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAED;;;;;;OAMG;IACG,IAAI,CACR,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAUzC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAM9D;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAEhD;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,qBAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;CACF"}
+{"version":3,"file":"transfers.d.ts","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAiB;;IAI5B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAED;;;;;;;;;;;;OAYG;IACG,IAAI,CACR,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAUzC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElD;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAM9D;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAEhD;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,qBAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAMlC;CACF"}

package/dist/cjs/resources/transfers.js

@@ -9,7 +9,10 @@ const gated_js_1 = require("../core/gated.js");
  * The result of sending is `Gated`, and that is the main thing to understand
  * here. The same `{transaction}` body comes back in three situations:
  *
- *   applied (201)  — executed, the money left;
+ *   applied (201)  — executed, the money left (rarely the status is still
+ *                    `pending` with a `txHash`: it went out, but its
+ *                    accounting was not recorded, and an administrator's
+ *                    reconciliation finishes it — do not send it again);
  *   pending (202)  — awaiting signatures, funds RESERVED but not sent;
  *   replayed (200) — a transfer with this `idempotencyKey` already existed,
  *                    and this is that transfer as it stands NOW.
@@ -22,7 +25,10 @@ const gated_js_1 = require("../core/gated.js");
  *
  *   confirmed, submitted     — it left;
  *   awaiting_approval        — waiting for signatures, funds reserved;
- *   pending                  — still executing;
+ *   pending                  — still executing, or its outcome is unknown
+ *                              (the first answer was 502
+ *                              `TRANSFER_OUTCOME_UNKNOWN`) until an
+ *                              administrator reconciles it;
  *   failed, rejected,
  *   cancelled                — it did not leave.
  */
@@ -39,6 +45,12 @@ class TransfersResource {
      * On `outcome: 'replayed'` read `data.transaction.status` before telling
      * anyone anything — a replay of an attempt that failed, or that is still
      * waiting for signatures, comes back the same way as one that went out.
+     *
+     * A thrown 502 `TRANSFER_OUTCOME_UNKNOWN` is not a failure: the signing
+     * service gave no definite answer, the transaction may have left, and the
+     * transfer stays `pending` with its funds reserved (`details.transactionId`).
+     * Retry it only with the SAME key — that returns the transfer without
+     * executing it again; a new key can send the money twice.
      */
     async send(input, options = {}) {
         const res = await this.#http.requestRaw('POST', this.#base, {
@@ -54,7 +66,9 @@ class TransfersResource {
     /**
      * One transfer in full. Note the shape: this is the transaction itself, not
      * the `{ transaction }` wrapper that `send()` returns — and it carries more,
-     * including `amlLevel`, `approvers`, `usdRate` and `failureReason`.
+     * including `amlLevel`, `approvers`, `usdRate` and `failureReason` — the
+     * last only on `failed`, `rejected` and `cancelled`, `null` on any other
+     * status.
      */
     get(transferId) {
         return this.#http.request('GET', `${this.#base}/${(0, http_js_1.seg)(transferId)}`);
@@ -72,11 +86,30 @@ class TransfersResource {
      *   awaiting_approval — counted, more signatures still needed;
      *   rejected          — a `reject` is a veto, and the reserve is released;
      *   confirmed/failed  — this vote completed the threshold, so execution ran
-     *                       INSIDE this request (gas, then broadcast, ~10s).
+     *                       INSIDE this request (gas, then broadcast, ~10s);
+     *   pending           — with no `executionError`: the outcome is NOT
+     *                       established by this answer. The signing service
+     *                       gave no definite answer (the transaction may have
+     *                       left; an administrator's reconciliation settles
+     *                       it), another call is executing the transfer, or
+     *                       the execution broke off. Re-read the transfer:
+     *                       `confirmed`/`failed` is the outcome, `pending` for
+     *                       over 10 minutes by `updatedAt` is waiting for
+     *                       reconciliation. Never send it again.
      *
      * `failed` means the money is back: execution broke after approval and the
      * reserve was released, with the reason in `executionError`. Treating the
-     * call as "approved, done" hides both the success and that failure.
+     * call as "approved, done" hides both the success and that failure. The
+     * exception is a `failed` transfer that has a `txHash`: it went out after
+     * reconciliation had already returned the reserve, and an administrator has
+     * to correct the ledger. `executionError` beside `rejected` or `cancelled`
+     * means the transfer was no longer waiting for signatures when approved,
+     * and nothing was executed.
+     *
+     * Repeating the same decision while the transfer is still waiting finishes
+     * what an earlier call left undone (it recorded the vote and broke off) — a
+     * veto, or execution once the threshold is met — instead of 409
+     * `ALREADY_VOTED`.
      */
     vote(transferId, input) {
         return this.#http.request('POST', `${this.#base}/${(0, http_js_1.seg)(transferId)}/approvals`, { body: input });
@@ -99,19 +132,34 @@ class TransfersResource {
         return this.#http.request('POST', `${this.#base}/${(0, http_js_1.seg)(transferId)}/cancel`);
     }
     /**
-     * Settles a transfer stuck in `pending` — the case where the worker died
-     * mid-execution, so cancelling does not apply. Administrators only.
+     * Settles a transfer nothing else can close. Administrators only.
+     *
+     *   pending            — execution died, or its outcome is unknown (the
+     *                        send answered 502 `TRANSFER_OUTCOME_UNKNOWN`);
+     *   awaiting_approval  — with no live approval request to vote on;
+     *   failed, rejected,
+     *   cancelled          — closed, but the reserve is still held: it is
+     *                        returned, and the status stays.
+     *
+     * A pending transfer is decided by the HASH: send `txHash` and it is driven
+     * to `confirmed`; send none and the reserve is returned (`failed`). Sending
+     * none is YOUR statement that nothing was broadcast — the server does not
+     * check it, so look on the chain first: returning the reserve of a
+     * transaction that did go out creates money. If the transfer already holds
+     * a hash from the signing service, only that hash, sent explicitly, settles
+     * it — 409 `TRANSFER_BROADCAST` without one, `TXHASH_MISMATCH` with another,
+     * the saved hash in `details.txHash`. The other two cases never executed
+     * and take no hash.
      *
-     * The decision is made by the HASH: send `txHash` and the transfer is
-     * driven to `confirmed`, because the signing service did put it on the
-     * chain; send none and the reserve is returned, because there was no
-     * broadcast. A FRESH pending transfer is refused on purpose — while
-     * execution may still be in flight, intervening risks a SECOND broadcast,
-     * which costs more than waiting.
+     * A FRESH transfer is refused on purpose — while execution may still be in
+     * flight, intervening risks a SECOND broadcast, which costs more than
+     * waiting.
      *
-     * Pass `fee` along with the hash if you know it: this is the only moment
-     * it can be recorded on a transfer settled this way, and it stays null
-     * otherwise. The answer says which way it went — `confirmed` or `failed`.
+     * Pass `fee` along with the hash if you know it: this is the only moment it
+     * can be recorded on a transfer settled this way; otherwise it stays as it
+     * is, null unless the signing service reported one. The answer says which
+     * way it went — `confirmed`, `failed`, or the unchanged `rejected` /
+     * `cancelled` of a closed transfer.
      */
     reconcile(transferId, input = {}) {
         return this.#http.request('POST', `${this.#base}/${(0, http_js_1.seg)(transferId)}/reconcile`, { body: input });

package/dist/cjs/resources/transfers.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":";;;AAAA,6CAAsD;AACtD,+CAAsD;AAgBtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IACW,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,IAAA,aAAG,EAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,IAAA,kBAAO,EAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5F,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":";;;AAAA,6CAAsD;AACtD,+CAAsD;AAgBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACW,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,IAAA,aAAG,EAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,IAAA,kBAAO,EAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5F,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,IAAA,aAAG,EAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}

package/dist/cjs/version.d.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export declare const SDK_VERSION = "0.2.1";
+export declare const SDK_VERSION = "0.2.3";
 /** Default API base URL. */
 export declare const DEFAULT_BASE_URL = "https://policy-engine-rest.ezig.workers.dev";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/version.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BASE_URL = exports.SDK_VERSION = void 0;
 /** SDK version, sent in the `user-agent` header. */
-exports.SDK_VERSION = '0.2.1';
+exports.SDK_VERSION = '0.2.3';
 /** Default API base URL. */
 exports.DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev';
 //# sourceMappingURL=version.js.map

package/dist/esm/generated/operations.js

@@ -9,7 +9,7 @@
 // the API does not slip in unclassified.
 //
 // Operations: 171 · admin: 40 · both: 1 · member: 127 · service: 3
-// Spec sha256: 017bae30075b232ab4efdcfb7785335020be3060b46e3569b1cd887fcf037597
+// Spec sha256: 1f0f2a38668572c443a84cb0207d4070b419a16c293b8e975f5e21c68e85b15a
 export const OPERATIONS = {
     "DELETE /api/v1/me/push-tokens/{token}": {
         "method": "delete",

package/dist/esm/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;