@lumenwipe/sdk 0.2.0 → 0.7.0

package/dist/index.d.ts

@@ -122,7 +122,11 @@ export declare interface AllowancesResult {
     warnings: PlanBlocker[];
 }
 
-export declare type ApiErrorBody = StructuredApiError | PlainApiError;
+export declare type ApiErrorBody = StructuredApiError;
+
+/** An `ErrorCode` the API can return, or `"upstream_error"` for a non-JSON failure from a proxy
+ *  or CDN in front of it. The open `string` arm keeps a newer API's code from breaking a build. */
+export declare type ApiErrorCode = ErrorCode | "upstream_error" | (string & {});
 
 export declare interface AquariusLpPosition extends DefiPositionBase {
     protocol: "aquarius";
@@ -154,6 +158,18 @@ export declare type AquariusPoolType = "constant_product" | "stable" | "concentr
  */
 export declare type AssetDisposition = "convert" | "issuer" | "transfer" | "leave";
 
+export declare interface BatchPlanResponse {
+    results: BatchPlanResult[];
+}
+
+/** One address's plan within a batch call - always present, even when the account could not be
+ *  read or planned safely (that failure surfaces as a `blocked` plan with its own blocker,
+ *  never as a missing entry). */
+export declare interface BatchPlanResult {
+    address: string;
+    plan: PlanResponse;
+}
+
 export declare interface BlendBorrowPosition extends DefiPositionBase {
     protocol: "blend";
     positionType: "borrow";
@@ -312,6 +328,12 @@ export declare interface ConversionPath {
     destMin: string;
 }
 
+export declare interface DailyActivity {
+    /** UTC day, YYYY-MM-DD. */
+    date: string;
+    accountsClosed: number;
+}
+
 export declare interface DataEntry {
     key: string;
     value: string;
@@ -329,6 +351,13 @@ export declare interface DecisionAnswer {
          * and the browser holds the built swap's own minimum to at least this figure.
          */
         minAmountOut?: string;
+        /**
+         * Pinned alongside `minAmountOut`: which provider's quote the user was shown and accepted.
+         * The build re-quotes and builds through exactly this provider, never a different one that
+         * might look better right now but that the user never saw priced (architecture.md, this
+         * feature's spec §5.2).
+         */
+        provider?: "soroswap" | "xbull";
         /**
          * Required by the `transfer_to_account` choice: the `G...` address the balance is paid to.
          *
@@ -433,12 +462,14 @@ export declare interface DefiPositionsResult {
 export declare type DefiPositionType = "supply" | "borrow" | "lp" | "cdp" | "stake";
 
 /**
- * Protocols LumenWipe actually knows how to exit (architecture.md §9's table). OctoPos itself
- * indexes more than this (e.g. "untangled-vault", "stellar-wallet") - those are dropped by the
- * adapter rather than represented here, since the type system should not claim LumenWipe can act
- * on a protocol it has no exit path for.
+ * Protocols LumenWipe knows how to act on: most are DeFi positions it knows how to exit
+ * (architecture.md §9's table); `xbull` is the one exception, a swap router with no position to
+ * exit, registered here only so it can share the contract registry's protocol-keyed lookups.
+ * OctoPos itself indexes more than this (e.g. "untangled-vault", "stellar-wallet") - those are
+ * dropped by the adapter rather than represented here, since the type system should not claim
+ * LumenWipe can act on a protocol it has no exit path for.
  */
-export declare type DefiProtocol = "blend" | "aquarius" | "soroswap" | "phoenix" | "fxdao";
+export declare type DefiProtocol = "blend" | "aquarius" | "soroswap" | "phoenix" | "fxdao" | "xbull";
 
 export declare interface DefiQueryKeys {
     rpcEndpoints: DefiRpcEndpoint[];
@@ -474,8 +505,18 @@ export declare interface DefiRpcPolicy {
 
 export declare type DemolishPhase = "IDLE" | "ANALYZING" | "PREFLIGHT_COMPLETE" | "SIGNER_SETUP" | "STEP_EXECUTING" | "STEP_CONFIRMED" | "STEP_FAILED" | "COMPLETE" | "ABORTED";
 
+/**
+ * Every code the API can put in `error.code`. A code is a contract: it is added here first and
+ * never renamed or removed without a deprecation window. The API's runtime list
+ * (apps/api/src/common/error-codes.ts) is checked against this union at compile time.
+ */
+export declare type ErrorCode = "account_not_found" | "account_read_failed" | "account_too_large" | "admin_api_not_configured" | "allowances_read_failed" | "api_key_not_found" | "aquarius_trustline_missing" | "backstop_emissions_unclaimed" | "backstop_token_unconvertible" | "backstop_withdrawal_cooling_down" | "backstop_withdrawal_not_queued" | "bad_request" | "blend_emissions_trustline_missing" | "blend_repay_asset_balance_unknown" | "blend_repay_asset_missing" | "confirmation_timeout" | "conversion_floor_missing" | "conversion_provider_unrecognized" | "defi_exit_blocked" | "defi_exit_unsupported" | "defi_position_unrecognized" | "defi_positions_blocked" | "defi_positions_stale" | "defi_positions_unavailable" | "destination_not_acknowledged" | "destination_read_failed" | "fee_bump_exceeds_cap" | "fee_bump_not_configured" | "forbidden" | "forward_amount_exceeds_balance" | "inner_fee_not_zero" | "integrator_api_not_configured" | "internal_error" | "invalid_address" | "invalid_addresses" | "invalid_body" | "invalid_challenge" | "invalid_decisions" | "invalid_destination" | "invalid_memo" | "invalid_network" | "invalid_owner" | "invalid_rate_limit" | "invalid_request" | "invalid_signature" | "invalid_signed_xdr" | "invalid_source" | "invalid_spender" | "invalid_token" | "invalid_tokens" | "invalid_transaction_xdr" | "invalid_tx_hash" | "issuer_read_failed" | "issuer_supply_not_acknowledged" | "key_limit_reached" | "mediator_key_misconfiguration" | "mediator_not_configured" | "memo_required" | "merge_destination_unusable" | "merged_account_not_found" | "missing_parameters" | "missing_transaction" | "needs_decisions" | "not_found" | "operation_not_sponsorable" | "owner_not_found" | "path_lookup_failed" | "payload_too_large" | "phoenix_trustline_missing" | "plan_failed" | "provider_response_unusable" | "quote_drifted" | "rate_limited" | "registry_expired" | "request_failed" | "revoke_build_failed" | "revoke_needs_restore" | "revoke_simulation_failed" | "revoke_unsafe" | "service_unavailable" | "signer_normalization_unsafe" | "soroban_token_conversion_failed" | "soroban_token_conversion_unavailable" | "soroban_token_conversion_unsafe" | "soroban_token_needs_restore" | "soroban_token_route_lost" | "soroban_token_transfer_failed" | "soroban_token_transfer_unsafe" | "soroban_token_unreadable" | "soroswap_trustline_missing" | "source_sequence_too_far" | "stats_unavailable" | "submit_failed" | "submit_rejected" | "too_many_addresses" | "transaction_structure_not_allowed" | "transactions_failed" | "transfer_destination_missing" | "transfer_destination_unusable" | "trustline_cannot_be_left" | "trustline_deauthorized_with_balance" | "trustline_maintain_liabilities_with_balance" | "tx_not_verified" | "unauthorized" | "unprocessable_entity" | "unsupported_media_type" | "unsupported_memo_type" | "vault_undercollateralized" | "withdraw_before_repay";
+
+/** One transaction the close is expected to take. */
 export declare interface ExecutionTxBreakdown {
+    /** Position among the transactions, from 0, in the order they are built and submitted. */
     order: number;
+    /** The plan step types this transaction carries operations for. */
     covers: StepType[];
     reason?: "op_batch" | "defi_dependency";
 }
@@ -589,11 +630,26 @@ export declare type IntentOperationBody = {
     type: "unknown";
 };
 
+/** Narrows an unknown error to a `LumenWipeApiError` carrying the given `code`. */
+export declare function isApiErrorCode<C extends ApiErrorCode>(error: unknown, code: C): error is LumenWipeApiError & {
+    code: C;
+};
+
+/** Thrown when the caller's `signal` aborts a request. Distinct from a timeout. */
+export declare class LumenWipeAbortError extends Error {
+    readonly reason?: unknown | undefined;
+    constructor(reason?: unknown | undefined);
+}
+
 /** Thrown when the API responds with a non-2xx status. `body` is the parsed error payload. */
 export declare class LumenWipeApiError extends Error {
     readonly status: number;
     readonly body: unknown;
-    constructor(status: number, body: unknown);
+    readonly code: ApiErrorCode;
+    readonly details: unknown;
+    readonly retryAfterMs: number | undefined;
+    readonly requestId: string | undefined;
+    constructor(status: number, body: unknown, headers?: Pick<Headers, "get">);
 }
 
 /**
@@ -604,39 +660,42 @@ export declare class LumenWipeApiError extends Error {
 export declare class LumenWipeClient {
     private readonly http;
     private readonly defaultNetwork;
+    private readonly log;
+    private warnedDefaultNetwork;
     constructor(options: LumenWipeClientOptions);
-    health(): Promise<HealthResponse>;
-    getAccount(address: string, network?: Network): Promise<AccountState>;
+    private resolveNetwork;
+    health(options?: RequestOptions): Promise<HealthResponse>;
+    getAccount(address: string, network?: Network, options?: RequestOptions): Promise<AccountState>;
     getPaths(params: {
         fromAsset: string;
         amount: string;
-    }, network?: Network): Promise<PathResponse>;
-    closePlan(body: ClosePlanRequest, network?: Network): Promise<PlanResponse>;
+    }, network?: Network, options?: RequestOptions): Promise<PathResponse>;
+    closePlan(body: ClosePlanRequest, network?: Network, options?: RequestOptions): Promise<PlanResponse>;
     /**
      * Builds the next unsigned transaction(s) for a close. A close can span several
-     * transactions (a fused close, or separate claim / cleanup / mediator-merge steps),
+     * transactions (a single transaction, or separate claim / cleanup / mediator-merge steps),
      * so the response's `remaining.requiresAnotherCall` says whether more follow: sign and
      * submit the returned transactions in `order`, wait for confirmation, then call this
      * again until `requiresAnotherCall` is false.
      */
-    closeTransactions(body: CloseTransactionsRequest, network?: Network): Promise<TransactionsResponse>;
-    submit(signedXdr: string, network?: Network): Promise<SubmitResponse>;
-    mediatorCheck(address: string, network?: Network): Promise<MediatorCheckResult>;
-    mediatorSign(transaction: string, network?: Network): Promise<MediatorSignResponse>;
+    closeTransactions(body: CloseTransactionsRequest, network?: Network, options?: RequestOptions): Promise<TransactionsResponse>;
+    submit(signedXdr: string, network?: Network, options?: RequestOptions): Promise<SubmitResponse>;
+    mediatorCheck(address: string, network?: Network, options?: RequestOptions): Promise<MediatorCheckResult>;
+    mediatorSign(transaction: string, network?: Network, options?: RequestOptions): Promise<MediatorSignResponse>;
     /** Wraps a wind-down transaction (its own fee already zero) in a signed CAP-15 fee-bump
      *  envelope for an account that cannot pay its own fee (architecture.md §8.1). The caller
      *  submits the returned XDR through `submit()`, exactly like any other close transaction. */
-    feeBumpSponsor(transaction: string, network?: Network): Promise<FeeBumpSponsorResponse>;
+    feeBumpSponsor(transaction: string, network?: Network, options?: RequestOptions): Promise<FeeBumpSponsorResponse>;
     /** Every live SEP-41 allowance the account has granted (architecture.md §12). Independent of
      *  closing an account - a standalone security utility. */
-    getAllowances(address: string, network?: Network): Promise<AllowancesResult>;
+    getAllowances(address: string, network?: Network, options?: RequestOptions): Promise<AllowancesResult>;
     /** Builds the unsigned `approve(owner, spender, 0, 0)` transaction that revokes one allowance.
      *  The caller signs and submits it through `submit()`, like any other transaction here. */
     revokeAllowance(params: {
         owner: string;
         token: string;
         spender: string;
-    }, network?: Network): Promise<RevokeAllowanceResponse>;
+    }, network?: Network, options?: RequestOptions): Promise<RevokeAllowanceResponse>;
 }
 
 export declare interface LumenWipeClientOptions {
@@ -644,12 +703,16 @@ export declare interface LumenWipeClientOptions {
     baseUrl: string;
     /** Integrator API key, sent as `Authorization: Bearer <apiKey>`. */
     apiKey: string;
-    /** Default network for calls that omit it. Defaults to `"testnet"`. */
+    /** Default network for calls that omit it. Defaults to `"testnet"`, with a one-time notice. */
     network?: Network;
     /** Custom fetch (for environments without a global `fetch`, or for testing). */
     fetch?: FetchLike;
     /** Per-request timeout in milliseconds. Defaults to 30000. `0`/`Infinity` disables it. */
     timeout?: number;
+    /** Opt-in retries. Off by default; never applied to `submit` or `mediatorSign`. */
+    retry?: RetryOptions;
+    /** Receives one-time notices (plaintext `baseUrl`, defaulted network). Defaults to `console.warn`. */
+    logger?: (message: string) => void;
 }
 
 /** Thrown when a request exceeds the configured timeout. */
@@ -666,6 +729,8 @@ export declare interface MediatorCheckResult {
     exchangeName: string | null;
     /** Whether the server can actually perform the mediator flow (secret configured). */
     available: boolean;
+    /** Whether the exchange registry is inside its verification window; false means exchange closes are refused. */
+    registryFresh: boolean;
 }
 
 /** Response from `POST /:network/mediator/sign`. */
@@ -673,6 +738,16 @@ export declare interface MediatorSignResponse {
     transaction: string;
 }
 
+/** One verified, counted close transaction. */
+export declare interface MergeRecord {
+    txHash: string;
+    network: Network;
+    accountsClosed: number;
+    xlmStroops: string;
+    /** Ledger close time of the transaction, ISO 8601. */
+    timestamp: string;
+}
+
 export declare type Network = "mainnet" | "testnet";
 
 export declare interface OpenOffer {
@@ -715,12 +790,6 @@ export declare interface PhoenixStakePosition extends DefiPositionBase {
     stakedAtEpoch: string;
 }
 
-/** @deprecated The API emits one envelope (`StructuredApiError`). Kept only so a consumer
- *  pinned to an older deployment still type-checks during a rollout; remove once none remain. */
-export declare interface PlainApiError {
-    error: string;
-}
-
 export declare interface PlanBlocker {
     message: string;
     helpUrl?: string;
@@ -766,8 +835,19 @@ export declare interface PlanResponse {
         feeStroops: string;
         freedReserveXlm: string;
     };
+    /**
+     * The transactions this close is expected to take, counted with the splitter the builder
+     * packs them with: Soroban token moves, the claim round, the classic close split at the
+     * per-transaction operation cap, and, for an exchange destination, the mediator transfer.
+     *
+     * `estimatedTransactionCount` is `null`, with `transactions` empty, when it cannot be known
+     * yet: the plan has a DeFi exit (its transaction count depends on live debt), a held token has
+     * no decision, or no destination was given. Never read it as a number without checking, and
+     * never show an unknown count as a figure. It is an estimate from the account as planned; the
+     * close re-reads live state each round.
+     */
     execution: {
-        estimatedTransactionCount: number;
+        estimatedTransactionCount: number | null;
         transactions: ExecutionTxBreakdown[];
     };
 }
@@ -783,6 +863,23 @@ export declare interface QuoteInfo {
     expiresAtLedger: number;
 }
 
+/** Response from `POST /v1/:network/stats/merges`. `counted` is false for an already-counted hash. */
+export declare interface RecordMergeResponse {
+    counted: boolean;
+}
+
+export declare interface RequestOptions {
+    /** Aborts the request. Rejects with `LumenWipeAbortError`, distinct from a timeout. */
+    signal?: AbortSignal;
+}
+
+export declare interface RetryOptions {
+    /** Total attempts including the first. Values below 2 disable retrying. */
+    attempts: number;
+    /** Base delay for exponential backoff when the response has no `Retry-After`. */
+    baseDelayMs: number;
+}
+
 /** Response from `POST /:network/allowances/revoke`. */
 export declare interface RevokeAllowanceResponse {
     transaction: string;
@@ -882,16 +979,31 @@ export declare type SponsoredEntry = {
     balanceId: string;
 };
 
+/** Response from `GET /v1/:network/stats/feed`. `daily` is oldest first, one entry per day. */
+export declare interface StatsFeed {
+    totals: StatsTotals;
+    recent: MergeRecord[];
+    daily: DailyActivity[];
+}
+
+/** Response from `GET /v1/:network/stats`. Stroops are decimal strings: the total can exceed 2^53. */
+export declare interface StatsTotals {
+    network: Network;
+    accountsClosed: number;
+    xlmRecoveredStroops: string;
+}
+
 export declare type StepStatus = "pending" | "signing" | "submitted" | "confirmed" | "failed" | "skipped";
 
 export declare type StepType = "NORMALIZE_SIGNERS" | "REVOKE_SPONSORSHIP" | "REMOVE_DATA_ENTRIES" | "CANCEL_OFFERS" | "ADD_TRUSTLINE_FOR_CLAIM" | "CLAIM_BALANCES" | "EXIT_POSITIONS" | "HANDLE_ASSETS" | "REMOVE_TRUSTLINES" | "CLOSE_ACCOUNT" | "MERGE";
 
-/** Structured error body used by the v1 (`/v1/...`) endpoints. */
+/** The single error envelope every API error response carries. */
 export declare interface StructuredApiError {
     error: {
         code: string;
         message: string;
         details?: unknown;
+        requestId?: string;
     };
 }
 
@@ -960,11 +1072,19 @@ export declare interface Trustline {
     asset: string;
     balance: string;
     limit?: string;
+    /** True only when `authorization` is `authorized`. */
     authorized: boolean;
+    authorization: TrustlineAuthorization;
+    /** The issuer can reclaim this balance at any time. */
+    clawbackEnabled: boolean;
     issuer: string;
     code: string;
 }
 
+/** The issuer's authorization of a trustline. Only `authorized` can send or receive payments;
+ *  `maintain_liabilities` keeps existing offers alive and nothing else. */
+export declare type TrustlineAuthorization = "authorized" | "maintain_liabilities" | "unauthorized";
+
 export declare interface TxIntent {
     summary: string;
     source: string;