@v3finance/core-sdk 0.2.0 → 0.2.2

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

@@ -11,17 +11,45 @@ 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 repeat; the transfer already existed.
+ *   replayed (200) — a transfer with this `idempotencyKey` already existed,
+ *                    and this is that transfer as it stands NOW.
  *
  * They cannot be told apart by the body. Showing "sent" on `pending` tells
  * the person money has gone when it is frozen.
+ *
+ * `replayed` does not mean "sent" either. It says only that the request was
+ * seen before; what became of it is in `data.transaction.status`:
+ *
+ *   confirmed, submitted     — it left;
+ *   awaiting_approval        — waiting for signatures, funds reserved;
+ *   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.
  */
 export declare class TransfersResource {
     #private;
     constructor(http: HttpClient, vaultCode: string);
-    /** Sends a transfer. The timeout is long: the path calls the wallet service. */
+    /**
+     * Sends a transfer. The timeout is long: the path calls the wallet service.
+     *
+     * 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;
         timeoutMs?: number;
@@ -29,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>;
     /**
@@ -45,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>;
     /**
@@ -68,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/esm/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;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;;IAI5B,YAAY,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAG9C;IAED,gFAAgF;IAC1E,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/esm/resources/transfers.js

@@ -6,12 +6,28 @@ import { toGated } from '../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 repeat; the transfer already existed.
+ *   replayed (200) — a transfer with this `idempotencyKey` already existed,
+ *                    and this is that transfer as it stands NOW.
  *
  * They cannot be told apart by the body. Showing "sent" on `pending` tells
  * the person money has gone when it is frozen.
+ *
+ * `replayed` does not mean "sent" either. It says only that the request was
+ * seen before; what became of it is in `data.transaction.status`:
+ *
+ *   confirmed, submitted     — it left;
+ *   awaiting_approval        — waiting for signatures, funds reserved;
+ *   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.
  */
 export class TransfersResource {
     #http;
@@ -20,7 +36,19 @@ export class TransfersResource {
         this.#http = http;
         this.#base = `/api/v1/vaults/${seg(vaultCode)}/transfers`;
     }
-    /** Sends a transfer. The timeout is long: the path calls the wallet service. */
+    /**
+     * Sends a transfer. The timeout is long: the path calls the wallet service.
+     *
+     * 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, {
             body: input,
@@ -35,7 +63,9 @@ export 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}/${seg(transferId)}`);
@@ -53,11 +83,30 @@ export 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}/${seg(transferId)}/approvals`, { body: input });
@@ -80,19 +129,34 @@ export class TransfersResource {
         return this.#http.request('POST', `${this.#base}/${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}/${seg(transferId)}/reconcile`, { body: input });

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

@@ -1 +1 @@
-{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AAgBtD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED,gFAAgF;IAChF,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,OAAO,CAAmD,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,GAAG,CAAC,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,GAAG,CAAC,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,GAAG,CAAC,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,GAAG,CAAC,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,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AAgBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,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,OAAO,CAAmD,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,GAAG,CAAC,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,GAAG,CAAC,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,GAAG,CAAC,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,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}

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

@@ -34,10 +34,6 @@ import type { AddressDetail as GeneratedAddressDetail, AddressListItem, CreateTr
  * the two must not be merged, because "no account" and "empty account"
  * deserve different wording. Amounts are raw smallest units; put them through
  * the helpers in `units.ts` rather than `Number`.
- *
- * One field is thinner than the type admits: `sharing` is optional because
- * `PATCH /addresses/{id}` reuses this schema WITHOUT it (the document says so
- * itself, on the property). Listings and the detail endpoint do send it.
  */
 export type Address = AddressListItem;
 /** A single address with its sharing and access details. */

package/dist/esm/resources/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}

package/dist/esm/version.d.ts

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

package/dist/esm/version.js

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.2.0';
+export const SDK_VERSION = '0.2.2';
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev';
 //# sourceMappingURL=version.js.map

package/docs/concepts.md

@@ -57,7 +57,7 @@ The API expresses this with the HTTP status, because **the response bodies are i
 | --- | --- |
 | 201 | applied — it happened |
 | 202 | pending — funds are RESERVED, nothing has moved, there is a request to sign |
-| 200 | replayed — the same idempotency key; it already happened earlier |
+| 200 | replayed — the same idempotency key; the transfer already existed, in whatever state it is now |
 
 The SDK turns that into `Gated`:
 
@@ -65,13 +65,16 @@ The SDK turns that into `Gated`:
 switch (result.outcome) {
   case 'applied':  return toast('Transfer sent')
   case 'pending':  return toast('Awaiting signatures — funds are reserved')
-  case 'replayed': return toast('This transfer was already sent')
+  case 'replayed': return toast(describeStatus(result.data.transaction.status))
 }
 ```
 
 `replayed` is kept apart from `applied` on purpose: a replay means the previous attempt reached the
-server and only the answer was lost, so the person should be told "already sent" rather than being
-told "sent" a second time.
+server and only the answer was lost — not that it succeeded. The body is that transfer as it stands
+now, so `replayed` must not be shown as "sent": `data.transaction.status` says whether it went out
+(`confirmed`, or `submitted`), is waiting for signatures (`awaiting_approval`), is still executing
+or waiting for an administrator to reconcile it (`pending`) or did not go out (`failed`, `rejected`,
+`cancelled`).
 
 **Only `transfers.send` can return it.** `idempotencyKey` exists on exactly one request body in the
 whole API — the transfer — so it is the only place where a 200 means "this already happened". On

package/docs/errors.md

@@ -87,7 +87,10 @@ that status so that one condition has one name whichever side produced it.
 502 and 504 are the exception, and they are the two statuses to **branch on by
 `status` rather than by `code`**: the API has no envelope for them — its own
 derivation would call both `INTERNAL_ERROR` — they arrive from the edge as HTML,
-and the SDK is the only side naming them.
+and the SDK is the only side naming them. A 502 that carries a code of its own
+came from the API and is not this case: on `POST /transfers` it can be
+`TRANSFER_OUTCOME_UNKNOWN`, which must not be treated as a failure. Check `code`
+before `status`.
 
 One asymmetry left on the server side, worth knowing only so you read it
 correctly: the API's envelope would derive `UNAUTHORIZED` for a 401 whose body
@@ -102,6 +105,7 @@ the authentication middleware with `UNAUTHENTICATED`.
 |---|---|---|---|
 | `INSUFFICIENT_BALANCE` | 400 | The atomic reserve failed: the address does not have that much of that token available. A concurrent transfer may have taken it. | Show the shortfall. Refresh balances before offering a retry — the amount that fits may have changed. Do not retry blind. |
 | `INVALID_AMOUNT` | 400 | Amount is not a positive decimal string, or has more decimals than the token allows. | Fix client-side. A user-facing validation message, not a retry. |
+| `INVALID_DESTINATION_ADDRESS` | 400 | `toAddress` is not a valid address on the sending address's network: TRON — base58check (34 characters, `T…`, checksum); EVM — `0x` + 40 hex, with the EIP-55 checksum when mixed-case. The string is checked as sent, so leading or trailing whitespace fails too. Checked before AML, the policy and the reserve — nothing was created or reserved. `details` is `{field: "toAddress", network}`. A network of a type the API does not know is not checked here. | Fix client-side: an error on the recipient field. Not a retry. |
 | `TOKEN_NOT_FOUND` | 400 | The asset is not in the registry, or is disabled (kill-switched during an incident). | Refresh the token registry. If it is still missing, the asset is unavailable — say so; do not retry. |
 | `TOKEN_NETWORK_MISMATCH` | 400 | The token lives on a different network than the sending address. | A client bug or a stale form. Re-resolve the token for the address's network. |
 | `ADDRESS_NOT_FOUND` | 404 | No such address id. | Refresh the address list; the address was deleted or the id is stale. |
@@ -109,10 +113,13 @@ the authentication middleware with `UNAUTHENTICATED`.
 | `ADDRESS_TRANSFER_FORBIDDEN` | 403 | You are neither the owner nor an admin, and you hold no grant with transfer rights on this address. Checked before the policy engine. | Show the address as view-only. The remedy is a `contributor` grant from the owner — direct the user there, not to a retry. |
 | `POLICY_DENIED` | 403 | The policy engine said `block`, or no policy permits the action (default-deny). `details` carries the full decision, including `trace`. | Terminal for this request. Show `message` — it already names the rule that fired. Changing the amount or the destination may make the same request pass; retrying it unchanged will not. |
 | `APPROVAL_UNSATISFIABLE` | 409 | Signatures are required but cannot be gathered: fewer eligible approvers than the threshold. `details` has `{threshold, eligibleApprovers}`. | **Do not retry.** Nobody can approve this. Tell the user to contact an administrator — the policy or the approver group has to change. See [Easily confused](#easily-confused). |
+| `IDEMPOTENCY_KEY_REUSED` | 409 | The `idempotencyKey` already belongs to a different transfer: another sending address, recipient, amount, asset or network — their names are in `details.fields` (the amount is compared by value, `1.5` equals `1.50`); or it was used by another person or in another vault, and then there is no `details`. Nothing was created or moved. | Not a replay — a key reused for a new attempt. A new transfer needs a new key; a retry of the same transfer needs the old key with the same body. |
 | `APPROVAL_FAILED` | 409 | The approval request could not be created for some other reason. The reserve has already been returned, so no funds are stuck. | Retry once with a **new** idempotency key. If it repeats, it is a server-side fault — escalate. |
 | `VAULT_HAS_NO_WALLET_SERVICE` | 500 | The vault has no `walletServiceUrl` configured. | Configuration fault, not a user error. Transfers from this vault cannot work at all. Contact an administrator. |
 | `GAS_STATION_FAILED` | 502 | Energy/bandwidth provisioning failed. The transfer is marked `failed` and the reserve is already returned. | Retry with a **new** idempotency key (the old one is bound to the failed row). If it persists, an upstream service is down. |
-| `WALLET_SERVICE_ERROR` | 502, or 400 when the signing service itself answered 4xx | The signing service was unreachable, errored, or returned no transaction id. The transfer is `failed` and the reserve is returned. | Same as above: retry with a new key. On the 400 variant the signing service rejected the request and a retry will fail identically — but `message` now gives only its status (`Wallet Service returned 400`): the service's own body is not echoed to clients, it goes to the worker log. Show that the signing service refused and report the transfer id; do not try to explain the refusal from `message`. |
+| `WALLET_SERVICE_ERROR` | 400 | The signing service refused the request (answered 4xx). A definite refusal: the transfer is `failed` and the reserve is returned. Every other failure of the signing service is `TRANSFER_OUTCOME_UNKNOWN`, not this. | A retry will fail identically. `message` gives only the service's status (`Wallet Service returned 400`): its own body is not echoed to clients, it goes to the worker log. Show that the signing service refused and report it; do not try to explain the refusal from `message`. A new attempt needs a new key. |
+| `TRANSFER_OUTCOME_UNKNOWN` | 502 | The signing service gave no definite answer — none within 60 s, a broken connection, a 5xx or 524, or a 2xx without a transaction id — so the transaction may or may not have reached the network. The transfer stays `pending` with the funds reserved; `details` is `{transactionId, status: "pending"}`. An administrator's reconciliation settles it. | **Neither a refusal nor a success.** Show that the outcome is being established. **Never retry with a new key** — that can send the money twice. A retry with the same key answers 200 (`replayed`) with the transfer as it stands and does not execute it again. Follow the transfer by `details.transactionId`. |
+| `TRANSFER_BROADCAST_UNRECORDED` | 502 | The transaction went to the network (`details.txHash`), but by then reconciliation had already returned its reserve, so the send is not recorded in the ledger. | **The money left — do not retry.** An administrator has to post a correcting entry; report the hash. |
 | `TRANSFER_NOT_EXECUTABLE` | 404 / 409 / 500 | The transfer is missing, or is not in the status execution requires. | Re-read the transfer and drive the UI from its real status. Do not retry. |
 
 ### Voting on a transfer
@@ -124,24 +131,33 @@ the authentication middleware with `UNAUTHENTICATED`.
 | `TRANSFER_NOT_FOUND` | 404 | No such transfer, or an `awaiting_approval` transfer has no approval request — which is a data inconsistency, not a normal state. | Refresh the list. If a transfer you can see keeps producing this, report it. |
 | `NOT_AWAITING_APPROVAL` | 409 | Voting is over: someone else's vote already resolved it, or it was cancelled. | Not an error worth an alert. Refresh the transfer and show its real status. |
 | `NOT_AN_APPROVER` | 403 | You are not in the approver snapshot taken when the request was created. Editing the policy or the group afterwards does not add you. | Hide the approve/reject controls for this item. Terminal. |
-| `ALREADY_VOTED` | 409 | You already voted. One vote per person. | Refresh; show your recorded vote. |
+| `ALREADY_VOTED` | 409 | You already voted. One vote per person. Repeating the **same** decision is not refused when it can finish what an earlier call left undone (it recorded the vote and broke off): a repeated reject completes the veto, a repeated approve executes the transfer once the threshold is met. A different decision over a recorded vote is always this 409. | Refresh; show your recorded vote. |
+| `REQUEST_INCOMPLETE` | 409 | The approval request behind the transfer was not created completely — signature steps it refers to are missing — so it can never be approved. The `approve` that got this 409 **is recorded**. | Do not offer approve again. The request is closed by its initiator or an admin (cancel; anyone else gets 403 `NOT_INITIATOR`), or by a veto from an approver who has not voted yet; the reserve is returned. Then create the transfer anew. |
 | `NOT_INITIATOR` | 403 | Only the initiator or an admin can cancel. | Hide the cancel control. |
 
 ### Reconciling a stuck transfer
 
-`POST /transfers/{id}/reconcile`, admin only. For a transfer left in `pending` because the worker died mid-execution — cancel does not reach those, it requires `awaiting_approval`.
+`POST /transfers/{id}/reconcile`, admin only. For a transfer nothing else can close: `pending` because execution died or its outcome is unknown (`TRANSFER_OUTCOME_UNKNOWN`); `awaiting_approval` with no live (`PENDING`) approval request; and a closed transfer — `failed`, `rejected` or `cancelled` — whose reserve is still held, where the reserve is returned, the status stays, and the answer carries that status.
+
+A `pending` transfer is decided by the hash: with `txHash` it is driven to `confirmed`; without one the reserve is returned (`failed`) — that is the reconciler's statement that nothing was broadcast, not something the server checks. So for a `pending` transfer with no hash, look on the chain from the sending address first: returning the reserve of a transaction that did go out creates money. A `pending` transfer that already has a hash saved from the signing service is settled only by that hash, sent explicitly. The other two cases never executed: they take no hash, and the reserve is returned.
 
 | Code | Status | When | What to do |
 |---|---|---|---|
-| `TRANSFER_STILL_EXECUTING` | 409 | The transfer entered `pending` less than 10 minutes ago. | **This is "wait", not "no".** Execution may still be in flight; intervening now risks a second broadcast. Back off and offer the action again after the window. See [Easily confused](#easily-confused). |
-| `TRANSFER_NOT_STUCK` | 409 | The transfer is not in `pending` at all, or was closed by another path while you were reconciling. | Re-read it. It resolved itself; nothing to do. |
-| `RESERVE_ALREADY_CONSUMED` | 409 | You asked to return the reserve, but a `confirm` posting has already spent it — the transaction went to the network. | **Never retry as a release.** The money left. Finish the transfer by supplying its `txHash` instead. |
+| `TRANSFER_STILL_EXECUTING` | 409 | The transfer changed less than 10 minutes ago (`updatedAt`). An unknown outcome counts as a change: the clock starts when execution stopped waiting for the signing service. | **This is "wait", not "no".** Execution may still be in flight; intervening now risks a second broadcast. Back off and offer the action again after the window. See [Easily confused](#easily-confused). |
+| `TRANSFER_NOT_STUCK` | 409 | Nothing to reconcile: the transfer is in none of the states above (an `awaiting_approval` one still has a live request, a closed one holds no reserve), or another path changed it while you were reconciling. | Re-read it. It resolved itself, or it is closed by a vote or a cancel; nothing to do here. |
+| `RESERVE_ALREADY_CONSUMED` | 409 | Without `txHash`: a `confirm` posting has already spent the reserve — the transaction went to the network. With `txHash`: the reserve was returned in parallel, for instance by a reconciliation without a hash. | Without a hash: **never retry as a release.** The money left. Finish the transfer by supplying its `txHash` instead. With a hash: re-read the transfer. |
+| `TRANSFER_BROADCAST` | 409 | No `txHash` sent, but the `pending` transfer has a hash saved from the signing service — it went to the network. `details.txHash` is that hash. Nothing moved. | Reconcile again with that `txHash`. Never as a release. |
+| `TXHASH_MISMATCH` | 409 | The `txHash` differs from the hash saved on the transfer, which is in `details.txHash`. Nothing moved. | Check the hash. The saved one came from the signing service. |
+| `TXHASH_IN_USE` | 409 | The `txHash` is already recorded on another transfer. Nothing moved. | Almost certainly the wrong hash. Check it. |
+| `TRANSFER_NOT_EXECUTED` | 409 | `txHash` sent for a transfer that never executed — `awaiting_approval`, or closed with its reserve still held. | Reconcile without `txHash`; the reserve is returned. |
+| `RESERVE_MISSING` | 409 | `txHash` sent for a transfer whose funds were never reserved, so it cannot have executed. | Reconcile without `txHash`; it closes as `failed` with no money moved. |
+| `RESERVE_RELEASED` | 409 | `txHash` sent, but the reserve had already been returned: on a `pending` transfer the returned funds are already spent and the send cannot be charged to them; a closed transfer is not confirmed by reconciliation at all. Nothing moved. | An administrator has to post a correcting entry. Escalate. |
 
 ### Not error codes, though they look like them
 
 Two sets of uppercase strings travel inside **successful** bodies and will mislead anyone grepping for codes:
 
-- **`applyError` on a 200 vote response** — `STALE`, `APPLY_FAILED`, `APPLY_FAILED_ROLLED_BACK`, `APPLY_FAILED_PARTIAL`, `TRANSFER_EXECUTION_FAILED`. The vote itself succeeded and the request reached its final status; what failed was applying the approved change. No exception is thrown, so you must read this field. `TRANSFER_EXECUTION_FAILED` in particular means the approval went through and the transfer then failed — the reserve has been returned.
+- **`applyError` on a 200 vote response** — `STALE`, `APPLY_FAILED`, `APPLY_FAILED_ROLLED_BACK`, `APPLY_FAILED_PARTIAL`, `TRANSFER_EXECUTION_FAILED`. The vote itself succeeded and the request reached its final status; what failed was applying the approved change. No exception is thrown, so you must read this field. `TRANSFER_EXECUTION_FAILED` in particular means the approval went through and the transfer was not executed — usually `failed` with the reserve returned; the transfer itself says which. An unknown outcome is **not** reported here: there is no `TRANSFER_OUTCOME_UNKNOWN` in a vote answer. The transfer route answers `status: "pending"` with `executionError: null`, the request route `APPROVED` with `finalized: false` and `applyError: null` — the outcome is not established by that answer; read it from the transfer.
 - **Policy `reason` strings** inside `POLICY_DENIED`'s `details`, and `observations[].code` in report bodies. The first are author-defined — an administrator writes `DAILY_LIMIT_EXCEEDED` or `AMOUNT_EXCEEDED` into a policy by hand, so the set is open and unstable. The second are report findings, not failures. Do not branch on either as if it were an error code.
 
   The observation set, unlike the policy reasons, is closed, and it is all nine of these — each with a `severity` of `info` or `warning`, which is the field to drive presentation from:
@@ -181,6 +197,16 @@ Two sets of uppercase strings travel inside **successful** bodies and will misle
 
 Address creation that requires signatures is **not** an error: the server answers **202** with `{status:"awaiting_approval", approvalRequestId, approvalThreshold}`. Nothing is thrown. (`POLICY_REQUIRES_APPROVAL` exists in the server's type but is never sent — see [Declared but never returned](#declared-but-never-returned).)
 
+Creating an address **into a folder** (`groupId`) can succeed without the folder, and that is not an error either. The right to the folder is checked before anything is created — a refusal there is `GROUP_CREATE_FORBIDDEN` above — but the address is put into the folder only after the signing service and monitoring, and the right is checked again at that moment. If that fails, the address still exists and the answer is still **201**, with `warnings: [{code, message}]` in the body:
+
+| Code | Meaning |
+|---|---|
+| `FOLDER_NOT_FOUND` | The folder was deleted. |
+| `FOLDER_FORBIDDEN` | The address's creator may no longer add addresses to the folder. |
+| `FOLDER_WRITE_FAILED` | Writing the membership failed. |
+
+The same three arrive in `applyWarnings` of a **200** vote that applied an approved `create_address`: there the folder is checked when the request is applied, not when it was filed, and the request's history gets a `folder_skipped` event. Nothing is thrown in either case, so read the field. The address is fine; do not show it inside the folder.
+
 ## Grants and sharing
 
 Address shares, folder shares, member-visibility grants. All grant `POST`s are idempotent: repeating a pair changes the rights, and a revoked grant is reactivated. There is no `GRANT_EXISTS` anywhere.
@@ -258,7 +284,8 @@ In the single-subject form the per-subject code is returned as a normal error
 | `NOT_FOUND` | 404 | No such request in this vault. | Refresh the list. |
 | `NOT_PENDING` | 409 | The request is already `APPROVED` / `REJECTED` / `CANCELLED`. Voting is over. | Refresh and show the final status. Expected under concurrency; not worth an alert. |
 | `NOT_APPROVER` | 403 | You are not in the approver snapshot. The snapshot is frozen at creation — later policy or group edits do not add you. | Hide the controls for this request. Terminal. |
-| `ALREADY_VOTED` | 409 | One vote per person, already cast. | Refresh; show your vote. |
+| `ALREADY_VOTED` | 409 | One vote per person, already cast. Repeating the **same** decision on a `PENDING` request is not refused when it can finish what an earlier call left undone: a repeated reject completes the veto, a repeated approve completes the approval once the threshold is met. | Refresh; show your vote. |
+| `REQUEST_INCOMPLETE` | 409 | The request was not created completely — signature steps its approvers refer to are missing — so it can never be approved. The `approve` that got this 409 **is recorded**. | Do not offer approve again. It is closed by its initiator or an admin (cancel; anyone else gets 403 `NOT_INITIATOR`), or by a veto from an approver who has not voted yet. Then create the action anew. |
 | `NOT_INITIATOR` | 403 | Only the initiator or an admin can cancel. | Hide the cancel control. |
 | `UNSATISFIABLE` | 409 | The request cannot be created: a step has fewer eligible approvers than its threshold, or every step is auto-approved so no request is needed. | **Do not retry.** An administrator has to fix the policy. Same situation as `APPROVAL_UNSATISFIABLE` on a transfer. |
 | `DB_REQUIRED` | 500 | A money-path request was handled without the database binding. Deliberately fail-closed, so no reserve is left locked. | Infrastructure fault. Nothing the user can do; escalate. |
@@ -385,7 +412,17 @@ A risk threshold in a policy is expressed as a **level**, not a numeric score, a
 
 `/api/auth/*` is the auth library's own namespace. It answers with a flat `{code, message}` that the API's envelope does not rewrite; `CoreError` reads it, so `code` is populated, but the values come from that library and are not part of this API's contract. Do not branch on a fixed list there — branch on `status`, and show `message`.
 
-Rate limiting is not implemented in the API itself. A 429 therefore comes from the platform in front of it, usually without a JSON body, which means `code: "RATE_LIMITED"` and no `details`. Back off and retry.
+One of the library's codes is named here anyway, because the API itself refers to it: `FAILED_TO_GET_SESSION`. The library raises it when it fails to read or renew a session — a sign-out or a revocation deleting the session in the middle of a renewal is one way to get there. The API retries the session lookup once on it; on the API's own paths a failure that survives the retry arrives as `INTERNAL_ERROR`, and only `/api/auth/*` can hand you `FAILED_TO_GET_SESSION` itself, in the library's flat form. Treat it by `status`, like the rest of that namespace.
+
+Three refusals the API puts **in front of** the library are its own: they arrive in the API's envelope, and their codes can be branched on.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `ADMIN_CANNOT_APPROVE_WEB_LOGIN` | 403 | `POST /api/auth/device/approve` by a platform administrator. Approving a web login gives the holder of the code a new session of the approving user, and a platform administrator's session is not handed to the web version at all. | Terminal. Approve from an account that is not a platform administrator. |
+| `WEB_SESSION_CANNOT_APPROVE` | 403 | The same approval sent with a session that was itself obtained through a web login. Only a session signed in another way may approve, so one leaked web token cannot keep minting new ones. | Approve from the mobile app. |
+| `WEB_SESSION_CANNOT_MANAGE_SESSIONS` | 403 | A web-login session called `list-sessions`, `revoke-session`, `revoke-sessions` or `revoke-other-sessions`. Signing out (`sign-out`) is not affected. | Hide session management in a web client; it is done from the mobile app. |
+
+Rate limiting outside `/api/auth/*` is not implemented in the API itself. A 429 there comes from the platform in front of it, usually without a JSON body, which means `code: "RATE_LIMITED"` and no `details`. Inside `/api/auth/*` a 429 can also come from the library's own limiter, as a bare `{message}`; and requesting a web-login code (`/api/auth/device/code`) is limited by the API itself, with a 429 in the API's envelope and `code: "RATE_LIMITED"`. Whichever answered, back off — for `X-Retry-After` seconds when the header is there — and retry.
 
 ## Easily confused
 
@@ -393,7 +430,7 @@ Rate limiting is not implemented in the API itself. A 429 therefore comes from t
 
 **`TRANSFER_STILL_EXECUTING` means "wait", not "no".** The transfer went into `pending` less than 10 minutes ago and execution may still be in flight. The server refuses on purpose: intervening could cause a **second broadcast**, which is far more expensive than waiting. Do not surface it as a failure, do not loop on it — back off past the window and offer the action again.
 
-**`RESERVE_ALREADY_CONSUMED` means the money left.** It appears when a release is attempted over a transfer whose reserve was already spent by a `confirm` posting. Idempotency does not protect you here: confirm and release are different keys that draw on the same balance, so a release layered on a completed confirm would create money out of nothing. The correct next step is always to finish the transfer by its `txHash`, never to retry the release.
+**`RESERVE_ALREADY_CONSUMED` means the money left.** It appears when a release is attempted over a transfer whose reserve was already spent by a `confirm` posting. Idempotency does not protect you here: confirm and release are different keys that draw on the same balance, so a release layered on a completed confirm would create money out of nothing. The correct next step is always to finish the transfer by its `txHash`, never to retry the release. (Reconciling **with** a `txHash` can get the same code for the opposite reason — the reserve was returned in parallel; then re-read the transfer.)
 
 **`CONCURRENCY_CONFLICT` on address creation is the opposite of the above: retry it.** It means the server could not allocate a unique derivation index because other creations were racing it. Nothing was created, nothing is half-done, and the next attempt will usually succeed. Make this the one 409 in the SDK you retry automatically.
 
@@ -438,19 +475,20 @@ try {
   } else throw e
 }
 
-if (result.outcome === 'replayed') showAlreadySent(result.data)
-else if (result.outcome === 'pending') showAwaitingApproval(result.data)
-else showSent(result.data)
+if (result.outcome === 'pending') showAwaitingApproval(result.data)
+else if (result.outcome === 'applied') showSent(result.data)
+else showByStatus(result.data.transaction.status) // replayed: NOT necessarily sent — see below
 ```
 
 Rules that follow from how the server handles the key:
 
 - **The key is reserved before any external call.** A replay is therefore recognised even if the first attempt died mid-broadcast. The server answers **200** and does not broadcast again; the SDK labels that `outcome: 'replayed'`.
-- **Tell "replayed" apart from "sent".** A replay means the earlier attempt did reach the server and only the answer was lost. Say "already sent", not "sent" a second time.
-- **A new key after a `failed` or `rejected` transfer.** The old key is bound to that row, and reusing it returns the dead transfer instead of sending a new one.
+- **`replayed` does not mean "sent".** It means "a transfer with this key already exists": the earlier attempt did reach the server and only its answer was lost. `data` is that transfer as it stands **now**, and what happened to it is in `data.transaction.status` — `confirmed` (or `submitted`): it left; `awaiting_approval`: it is waiting for signatures, funds reserved; `pending`: it is still executing, or its outcome is unknown and waits for an administrator's reconciliation; `failed`, `rejected` or `cancelled`: it did not leave. Tell the person that, not "sent".
+- **A new key after a `failed` or `rejected` transfer.** The old key is bound to that row, and reusing it returns the dead transfer instead of sending a new one. The same key with any other parameters is not a replay at all: 409 `IDEMPOTENCY_KEY_REUSED`.
 - **No key sent, and a timeout?** Do **not** retry. Fetch the transfer list or the operation history first and establish whether the transfer exists. Make the SDK's own callers always pass a key so this situation cannot arise.
 - **`network` and `aborted` carry the same uncertainty as `timeout`** on money paths. The request may have been received and executed; only the response was lost. Treat all three identically: same key, or verify first.
 - **A thrown `GAS_STATION_FAILED` or `WALLET_SERVICE_ERROR` is different.** Those are definite: the transfer is `failed` and the reserve has been returned. Retry those with a **new** key.
+- **A thrown `TRANSFER_OUTCOME_UNKNOWN` is not.** It is a 502 that carries the same uncertainty as a timeout: the transaction may have left. Only the same key, which returns the transfer and does not execute it again; the outcome is set by reconciliation. `TRANSFER_BROADCAST_UNRECORDED` means it did leave — no retry at all.
 - **Nothing a client does can leave funds locked.** Every failure path either returns the reserve or leaves a `pending` transfer that an admin can reconcile. Timeouts are a reporting problem, not a custody one — but a double send is permanent, so the key matters more than the retry.
 
 ## Declared but never returned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v3finance/core-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The official TypeScript SDK for the V3 Finance Core API — custodial addresses, transfers under policy control, approvals, shared access, labelling and reports",
   "license": "MIT",
   "repository": {

package/src/core/gated.ts

@@ -15,8 +15,10 @@
  * frozen.
  *
  * `replayed` is kept separate from `applied` on purpose. A replay means the
- * previous attempt DID reach the server and only the answer was lost, so the
- * person should be told "already sent", not "sent" a second time.
+ * previous attempt DID reach the server and only the answer was lost — not
+ * that it succeeded. The body is that operation as it stands now: a replayed
+ * transfer may have gone out, be waiting for signatures, be still executing
+ * or have failed, and only its own status says which.
  */
 
 export type GatedOutcome = 'applied' | 'pending' | 'replayed'
@@ -74,7 +76,11 @@ export function toGated<TApplied, TPending>(
   }
 }
 
-/** Narrowing: the operation ran, now or earlier, and money moved. */
+/**
+ * Narrowing: `applied` or `replayed`. For `applied` the operation ran now.
+ * For `replayed` it only existed already — whether money moved is in the
+ * body's own status, not in this check.
+ */
 export function isApplied<A, P>(
   r: Gated<A, P>,
 ): r is Extract<Gated<A, P>, { outcome: 'applied' | 'replayed' }> {

package/src/core/http.ts

@@ -157,13 +157,27 @@ export class HttpClient {
   constructor(options: ClientOptions & { baseUrl: string }) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, '')
     this.#options = options
-    const f = options.fetch ?? globalThis.fetch
-    if (typeof f !== 'function') {
+    const custom = options.fetch
+    if (typeof (custom ?? globalThis.fetch) !== 'function') {
       throw new Error(
         '@v3finance/core-sdk: fetch is unavailable in this runtime — pass one to the client options.',
       )
     }
-    this.#fetch = f
+    // NEVER store the function and call it as `this.#fetch(…)`. A private
+    // field call passes the client as the receiver, and a browser's `fetch`
+    // checks its receiver: anything but the window is
+    // `TypeError: Illegal invocation`, thrown before a single byte leaves.
+    // Node and React Native do not check, which is how every request from a
+    // web page failed while the whole test suite passed — and since a
+    // `TypeError` out of `fetch` is what a dropped connection looks like, the
+    // failure surfaced as a "network error" on a perfectly good network.
+    //
+    // The wrapper calls with no receiver at all. Without a custom fetch the
+    // global one is looked up per call rather than captured here, so whatever
+    // patches it later (instrumentation, a mock server) is still honoured.
+    this.#fetch = custom
+      ? (input, init) => custom(input, init)
+      : (input, init) => globalThis.fetch(input, init)
     this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
   }