tronlink-signer 0.1.2 → 0.1.4

package/README.md

@@ -17,7 +17,8 @@ const signer = new TronSigner();
 await signer.start();
 
 const { address, network } = await signer.connectWallet();
-const { txId } = await signer.sendTrx("TXxx...", 1);
+const { txId, status } = await signer.sendTrx("TXxx...", 1); // status: "success" | "pending" | "failed"
+const { txId: txId2, status: s2 } = await signer.signTransaction(tx, "nile", true); // broadcast + auto-confirm
 const { balance } = await signer.getBalance("TXxx...");
 
 await signer.stop();
@@ -41,37 +42,39 @@ Stops the server and clears all pending requests.
 
 Returns the current configuration.
 
-### `signer.connectWallet(network?: TronNetwork): Promise<{ address: string; network: string }>`
+### `signer.connectWallet(network?, options?): Promise<{ address: string; network: string }>`
 
 Opens the browser to connect TronLink and retrieve the wallet address and current network. If the wallet is already connected (same browser tab still open), auto-completes without user interaction.
 
-### `signer.sendTrx(to, amount, network?): Promise<{ txId: string }>`
+### `signer.sendTrx(to, amount, network?, options?): Promise<BroadcastResult>`
 
-Sends TRX to a recipient address. Opens a browser approval page for the user to confirm.
+Sends TRX to a recipient address. Opens a browser approval page for the user to confirm. Returns `{ txId, status, error? }` where `status` is `"success"`, `"pending"`, or `"failed"` (see [Broadcast Result](#broadcast-result)).
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `to` | `string` | Recipient Tron address (base58) |
-| `amount` | `number` | Amount of TRX to send |
+| `amount` | `string \| number` | Amount of TRX to send |
 | `network` | `TronNetwork` | Optional network override |
+| `options` | `SignerOptions` | Optional — pass `{ signal }` to enable cancellation |
 
-### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?): Promise<{ txId: string }>`
+### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?, options?): Promise<BroadcastResult>`
 
-Sends TRC20 tokens. Opens a browser approval page.
+Sends TRC20 tokens. Opens a browser approval page. Returns `{ txId, status, error? }` — see [Broadcast Result](#broadcast-result).
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `contractAddress` | `string` | TRC20 token contract address |
 | `to` | `string` | Recipient Tron address (base58) |
 | `amount` | `string` | Amount in human-readable units (e.g., `"1.5"` for 1.5 USDT). Decimals conversion is automatic. |
-| `decimals` | `number` | Token decimals (default: 6) |
+| `decimals` | `number` | Optional. Token decimals. Omit to auto-detect via the contract's `decimals()` view (recommended — avoids 10^N magnitude errors on non-6dp tokens like USDD/SUN/JST). |
 | `network` | `TronNetwork` | Optional network override |
+| `options` | `SignerOptions` | Optional — pass `{ signal }` to enable cancellation |
 
-### `signer.signMessage(message, network?): Promise<{ signature: string }>`
+### `signer.signMessage(message, network?, options?): Promise<{ signature: string }>`
 
 Signs a plain text message.
 
-### `signer.signTypedData(typedData, network?): Promise<{ signature: string }>`
+### `signer.signTypedData(typedData, network?, options?): Promise<{ signature: string }>`
 
 Signs EIP-712 typed data.
 
@@ -86,28 +89,108 @@ const { signature } = await signer.signTypedData({
 });
 ```
 
-### `signer.signTransaction(transaction, network?, broadcast?): Promise<{ signedTransaction: Record<string, unknown>; txId?: string }>`
+### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status?; error? }>`
 
-Signs a raw transaction. When `broadcast` is `true`, the signed transaction is also broadcast on-chain via TronLink and the `txId` is returned.
+Signs a raw transaction. When `broadcast` is `true`, the signed transaction is broadcast on-chain via TronLink and the SDK automatically polls for on-chain confirmation — see [Broadcast Result](#broadcast-result) for the possible `status` values.
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `transaction` | `Record<string, unknown>` | Raw transaction object to sign |
 | `network` | `TronNetwork` | Optional network override |
 | `broadcast` | `boolean` | Whether to broadcast after signing (default: `false`) |
+| `options` | `SignerOptions` | Optional — cancellation, confirmation control, broadcast callback |
 
 ```ts
 // Sign only
 const { signedTransaction } = await signer.signTransaction(tx);
 
-// Sign and broadcast
-const { signedTransaction, txId } = await signer.signTransaction(tx, "nile", true);
+// Sign, broadcast, and wait for confirmation (default)
+const { signedTransaction, txId, status, error } = await signer.signTransaction(tx, "nile", true);
+// status === "success" — confirmed on-chain
+// status === "pending" — broadcast succeeded but not confirmed within timeout
+// status === "failed"  — on-chain execution failed; `error` carries the reason
+
+// Broadcast without waiting for confirmation
+const result = await signer.signTransaction(tx, "nile", true, { confirm: false });
+
+// Get notified as soon as the tx enters the mempool
+const result = await signer.signTransaction(tx, "nile", true, {
+  onBroadcasted: ({ txId }) => console.log("Broadcast:", txId),
+});
 ```
 
+### Broadcast Result
+
+Broadcasting methods (`sendTrx`, `sendTrc20`, and `signTransaction` with `broadcast: true`) return a `BroadcastResult`:
+
+```ts
+interface BroadcastResult {
+  txId: string;
+  status: "success" | "pending" | "failed";
+  error?: string; // set when status === "failed"
+}
+```
+
+`"failed"` means the transaction reached the chain but execution failed (e.g. `OUT_OF_ENERGY`, Solidity revert). **It is not thrown** — inspect `status` instead. The SDK only throws when broadcast itself never happened (signature error, user rejection, network unreachable, etc.).
+
+### `signer.waitForTransaction(txId, network?, options?): Promise<{ status; error? }>`
+
+Polls the network for transaction confirmation. Returns `{ status: "success" }` when confirmed, `{ status: "pending" }` on timeout, or `{ status: "failed", error }` when the transaction reverted / ran out of energy.
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `txId` | `string` | Transaction ID to monitor |
+| `network` | `TronNetwork` | Optional network override |
+| `options` | `WaitForTransactionOptions` | Optional — `timeoutMs` (default: 30000), `signal` |
+
+```ts
+const { status, error } = await signer.waitForTransaction(txId, "nile");
+if (status === "success") console.log("Confirmed on-chain");
+else if (status === "failed") console.warn("Execution failed:", error);
+```
+
+> **Note:** When using `signTransaction` with `broadcast: true`, confirmation polling is automatic — you don't need to call `waitForTransaction` separately unless you set `confirm: false`.
+
 ### `signer.getBalance(address, network?): Promise<{ balance: string; balanceSun: number }>`
 
 Gets TRX balance for an address. No browser approval needed.
 
+### `signer.onBrowserDisconnect`
+
+Setter for a callback that fires when the approval page is closed or loses connection (heartbeat timeout). Useful for cleanup or re-prompting the user.
+
+```ts
+signer.onBrowserDisconnect = () => {
+  console.log("Browser approval page was closed");
+};
+```
+
+### Cancellation & Options
+
+All signing methods accept an optional `SignerOptions`:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `signal` | `AbortSignal` | Cancels the pending request. If already aborted, the browser page is not opened. |
+| `confirm` | `boolean` | Wait for on-chain confirmation after broadcast (default: `true`). Only applies when `broadcast: true`. |
+| `confirmTimeoutMs` | `number` | Max time (ms) to wait for confirmation (default: `30000`). |
+| `onBroadcasted` | `(info) => void` | Fires after the tx enters the mempool (before confirmation). Callback errors are swallowed. |
+
+```ts
+const controller = new AbortController();
+
+// Cancel after 30 seconds
+setTimeout(() => controller.abort(), 30_000);
+
+try {
+  const { txId } = await signer.sendTrx("TXxx...", 1, undefined, {
+    signal: controller.signal,
+  });
+} catch (e) {
+  // e.message === "CANCELLED_BY_CALLER"
+}
+```
+
 ## How It Works
 
 1. Your code calls a signing method (e.g., `signMessage`)
@@ -156,6 +239,26 @@ interface NetworkConfig {
   fullHost: string;
   explorerUrl: string;
 }
+
+interface SignerOptions {
+  signal?: AbortSignal;
+  confirm?: boolean;
+  confirmTimeoutMs?: number;
+  onBroadcasted?: (info: { txId: string; signedTransaction: Record<string, unknown> }) => void;
+}
+
+interface WaitForTransactionOptions {
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+type BroadcastStatus = "success" | "pending" | "failed";
+
+interface BroadcastResult {
+  txId: string;
+  status: BroadcastStatus;
+  error?: string;
+}
 ```
 
 ## Exports
@@ -171,8 +274,10 @@ export { NETWORKS, DEFAULT_HTTP_PORT, REQUEST_TIMEOUT_MS, loadConfig } from "./c
 export type {
   TronNetwork, NetworkConfig, AppConfig,
   PendingRequestType, PendingRequest,
-  ConnectData, SendTrxData, SendTrc20Data,
+  SendTrxData, SendTrc20Data,
   SignMessageData, SignTypedDataData, SignTransactionData,
+  SignerOptions, WaitForTransactionOptions,
+  BroadcastStatus, BroadcastResult,
 } from "./types.js";
 ```
 

package/dist/index.d.ts

@@ -14,13 +14,13 @@ interface PendingRequest<T = unknown> {
 }
 interface SendTrxData {
     to: string;
-    amount: number;
+    amount: string | number;
 }
 interface SendTrc20Data {
     contractAddress: string;
     to: string;
     amount: string;
-    decimals: number;
+    decimals?: number;
 }
 interface SignMessageData {
     message: string;
@@ -32,47 +32,107 @@ interface SignTransactionData {
     transaction: Record<string, unknown>;
     broadcast?: boolean;
 }
+type BroadcastStatus = "success" | "pending" | "failed";
+interface BroadcastResult {
+    txId: string;
+    status: BroadcastStatus;
+    /** Failure reason when status === "failed". */
+    error?: string;
+}
 interface AppConfig {
     network: TronNetwork;
     httpPort: number;
     apiKey?: string;
 }
+interface SignerOptions {
+    signal?: AbortSignal;
+    /** Wait for on-chain execution result after broadcast. Default: true. Only applies to broadcasting operations. */
+    confirm?: boolean;
+    /** Max time to wait for confirmation, in ms. Default: 30000. */
+    confirmTimeoutMs?: number;
+    /**
+     * Fires after the transaction has been broadcast to the Tron network
+     * (txId in mempool, not yet confirmed on-chain). Use this to start your
+     * own monitoring in parallel with the SDK's polling. Callback errors are swallowed.
+     */
+    onBroadcasted?: (info: {
+        txId: string;
+        signedTransaction: Record<string, unknown>;
+    }) => void;
+}
+interface WaitForTransactionOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
 
 declare class TronSigner {
     private config;
     private pendingStore;
     private httpServer;
     private tronWeb;
+    private browserWatchTimer;
+    private _onBrowserDisconnect;
+    private _onWalletChanged;
+    private connectedWallet;
+    private broadcastListeners;
+    set onBrowserDisconnect(cb: (() => void) | null);
+    /**
+     * Fires when the user switches account/network or disconnects inside TronLink.
+     * All pending requests have already been rejected with "WALLET_CHANGED: <reason>"
+     * and the internal connectedWallet cache has been invalidated by the time this
+     * callback runs. Reasons: "account" | "network" | "disconnect".
+     */
+    set onWalletChanged(cb: ((reason: string) => void) | null);
     constructor();
+    /** Register a listener that fires the moment the browser reports a successful broadcast
+     *  (before on-chain confirmation). Auto-removed when `promise` settles. */
+    private registerBroadcastListener;
     start(): Promise<void>;
     private getPort;
     stop(): Promise<void>;
     getConfig(): AppConfig;
     private resolveNetwork;
-    connectWallet(network?: TronNetwork): Promise<{
+    private confirmIfNeeded;
+    /** @returns true if the signal was already aborted */
+    private attachAbortSignal;
+    connectWallet(network?: TronNetwork, options?: SignerOptions): Promise<{
         address: string;
         network: string;
     }>;
-    sendTrx(to: string, amount: number, network?: TronNetwork): Promise<{
-        txId: string;
-    }>;
-    sendTrc20(contractAddress: string, to: string, amount: string, decimals?: number, network?: TronNetwork): Promise<{
-        txId: string;
-    }>;
-    signMessage(message: string, network?: TronNetwork): Promise<{
+    /**
+     * Returns the most recently connected wallet (cached in-memory).
+     * Cleared when the approval page disconnects (heartbeat timeout).
+     * Callers should treat this as a cache, not ground truth — the user may
+     * have switched accounts inside TronLink and the SDK has no way to know.
+     * To force a fresh read, call connectWallet() instead.
+     */
+    getConnectedWallet(): {
+        address: string;
+        network: TronNetwork;
+    } | null;
+    sendTrx(to: string, amount: string | number, network?: TronNetwork, options?: SignerOptions): Promise<BroadcastResult>;
+    sendTrc20(contractAddress: string, to: string, amount: string, decimals?: number, network?: TronNetwork, options?: SignerOptions): Promise<BroadcastResult>;
+    signMessage(message: string, network?: TronNetwork, options?: SignerOptions): Promise<{
         signature: string;
     }>;
-    signTypedData(typedData: Record<string, unknown>, network?: TronNetwork): Promise<{
+    signTypedData(typedData: Record<string, unknown>, network?: TronNetwork, options?: SignerOptions): Promise<{
         signature: string;
     }>;
-    signTransaction(transaction: Record<string, unknown>, network?: TronNetwork, broadcast?: boolean): Promise<{
+    signTransaction(transaction: Record<string, unknown>, network?: TronNetwork, broadcast?: boolean, options?: SignerOptions): Promise<{
         signedTransaction: Record<string, unknown>;
         txId?: string;
+        status?: BroadcastStatus;
+        error?: string;
     }>;
     getBalance(address: string, network?: TronNetwork): Promise<{
         balance: string;
         balanceSun: number;
     }>;
+    private getTronWebFor;
+    waitForTransaction(txId: string, network?: TronNetwork, options?: WaitForTransactionOptions): Promise<{
+        status: BroadcastStatus;
+        error?: string;
+    }>;
 }
 
 declare const NETWORKS: Record<TronNetwork, NetworkConfig>;
@@ -80,4 +140,4 @@ declare const DEFAULT_HTTP_PORT = 3386;
 declare const REQUEST_TIMEOUT_MS: number;
 declare function loadConfig(): AppConfig;
 
-export { type AppConfig, DEFAULT_HTTP_PORT, NETWORKS, type NetworkConfig, type PendingRequest, type PendingRequestType, REQUEST_TIMEOUT_MS, type SendTrc20Data, type SendTrxData, type SignMessageData, type SignTransactionData, type SignTypedDataData, type TronNetwork, TronSigner, loadConfig };
+export { type AppConfig, type BroadcastResult, type BroadcastStatus, DEFAULT_HTTP_PORT, NETWORKS, type NetworkConfig, type PendingRequest, type PendingRequestType, REQUEST_TIMEOUT_MS, type SendTrc20Data, type SendTrxData, type SignMessageData, type SignTransactionData, type SignTypedDataData, type SignerOptions, type TronNetwork, TronSigner, type WaitForTransactionOptions, loadConfig };