tronlink-signer 0.1.1 → 0.1.3

package/README.md

@@ -16,8 +16,9 @@ import { TronSigner } from "tronlink-signer";
 const signer = new TronSigner();
 await signer.start();
 
-const { address } = await signer.connectWallet();
+const { address, network } = await signer.connectWallet();
 const { txId } = await signer.sendTrx("TXxx...", 1);
+const { txId: txId2, status } = await signer.signTransaction(tx, "nile", true); // broadcast + auto-confirm
 const { balance } = await signer.getBalance("TXxx...");
 
 await signer.stop();
@@ -41,21 +42,22 @@ Stops the server and clears all pending requests.
 
 Returns the current configuration.
 
-### `signer.connectWallet(network?: TronNetwork): Promise<{ address: string }>`
+### `signer.connectWallet(network?, options?): Promise<{ address: string; network: string }>`
 
-Opens the browser to connect TronLink and retrieve the wallet address.
+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<{ txId: string }>`
 
 Sends TRX to a recipient address. Opens a browser approval page for the user to confirm.
 
 | 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<{ txId: string }>`
 
 Sends TRC20 tokens. Opens a browser approval page.
 
@@ -63,15 +65,16 @@ Sends TRC20 tokens. Opens a browser approval page.
 | --------- | ---- | ----------- |
 | `contractAddress` | `string` | TRC20 token contract address |
 | `to` | `string` | Recipient Tron address (base58) |
-| `amount` | `string` | Amount in smallest unit |
+| `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) |
 | `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,25 +89,107 @@ const { signature } = await signer.signTypedData({
 });
 ```
 
-### `signer.signTransaction(transaction, network?): Promise<{ signedTransaction: Record<string, unknown> }>`
+### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status? }>`
 
-Signs a raw transaction without broadcasting it.
+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 (returns `status: "success"` or `"pending"`).
+
+| 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, broadcast, and wait for confirmation (default)
+const { signedTransaction, txId, status } = await signer.signTransaction(tx, "nile", true);
+// status === "success" — confirmed on-chain
+// status === "pending" — broadcast succeeded but not confirmed within timeout
+
+// 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),
+});
+```
+
+### `signer.waitForTransaction(txId, network?, options?): Promise<"success" | "pending">`
+
+Polls the network for transaction confirmation. Returns `"success"` when the transaction is confirmed on-chain, or `"pending"` if the timeout is reached. Throws if the transaction execution failed (e.g., `OUT_OF_ENERGY`, Solidity revert).
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `txId` | `string` | Transaction ID to monitor |
+| `network` | `TronNetwork` | Optional network override |
+| `options` | `WaitForTransactionOptions` | Optional — `timeoutMs` (default: 30000), `signal` |
+
+```ts
+const status = await signer.waitForTransaction(txId, "nile");
+if (status === "success") {
+  console.log("Confirmed on-chain");
+}
+```
+
+> **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`)
-2. A local HTTP server starts on port 3386 and the browser opens an approval page
+2. A local HTTP server starts on port 3386 and a **single browser tab** opens the approval page
 3. The approval page discovers the wallet via **TIP-6963** protocol (fallback to `window.tron`)
 4. Auto-unlocks wallet and switches network if needed
-5. User reviews and clicks Approve / Reject
-6. TronLink handles signing in the browser
-7. The result is returned to your code
+5. For `connectWallet`, if the wallet is already connected, it auto-completes without user interaction
+6. For signing/sending, the user reviews the transaction details and clicks Approve / Reject
+7. The approval page parses transaction types (TRX transfer, TRC20, TRC721 NFT, stake, delegate, vote, etc.) into human-readable display
+8. TronLink handles signing in the browser
+9. The result is returned to your code — the page stays open and polls for the next request
 
-The local server binds to `127.0.0.1` only. If port 3386 is in use, it auto-increments. Requests timeout after 5 minutes.
+All subsequent operations reuse the same browser tab. Each server session has a unique ID — old browser tabs from previous sessions are automatically invalidated. The page detects server disconnection via heartbeat and shows a session expired message. The local server binds to `127.0.0.1` only. If port 3386 is in use, it auto-increments. Requests timeout after 5 minutes. The server gracefully shuts down on process exit (SIGINT/SIGTERM).
 
 ## Networks
 
@@ -140,6 +225,18 @@ 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;
+}
 ```
 
 ## Exports
@@ -157,6 +254,7 @@ export type {
   PendingRequestType, PendingRequest,
   ConnectData, SendTrxData, SendTrc20Data,
   SignMessageData, SignTypedDataData, SignTransactionData,
+  SignerOptions, WaitForTransactionOptions,
 } from "./types.js";
 ```
 

package/dist/index.d.ts

@@ -14,7 +14,7 @@ interface PendingRequest<T = unknown> {
 }
 interface SendTrxData {
     to: string;
-    amount: number;
+    amount: string | number;
 }
 interface SendTrc20Data {
     contractAddress: string;
@@ -30,46 +30,97 @@ interface SignTypedDataData {
 }
 interface SignTransactionData {
     transaction: Record<string, unknown>;
+    broadcast?: boolean;
 }
 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;
+    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();
     start(): Promise<void>;
     private getPort;
     stop(): Promise<void>;
     getConfig(): AppConfig;
     private resolveNetwork;
-    connectWallet(network?: TronNetwork): Promise<{
+    /** @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<{
+    /**
+     * 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<{
         txId: string;
     }>;
-    sendTrc20(contractAddress: string, to: string, amount: string, decimals?: number, network?: TronNetwork): Promise<{
+    sendTrc20(contractAddress: string, to: string, amount: string, decimals?: number, network?: TronNetwork, options?: SignerOptions): Promise<{
         txId: string;
     }>;
-    signMessage(message: string, network?: TronNetwork): Promise<{
+    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): Promise<{
+    signTransaction(transaction: Record<string, unknown>, network?: TronNetwork, broadcast?: boolean, options?: SignerOptions): Promise<{
         signedTransaction: Record<string, unknown>;
+        txId?: string;
+        status?: "success" | "pending";
     }>;
     getBalance(address: string, network?: TronNetwork): Promise<{
         balance: string;
         balanceSun: number;
     }>;
+    private getTronWebFor;
+    waitForTransaction(txId: string, network?: TronNetwork, options?: WaitForTransactionOptions): Promise<"success" | "pending">;
 }
 
 declare const NETWORKS: Record<TronNetwork, NetworkConfig>;
@@ -77,4 +128,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, 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 };