@etherkit/viem-tx-tracker 0.0.2 → 0.0.4

package/src/index.ts

@@ -1,15 +1,8 @@
 // Types
-export type {
-	BlockTag,
-	ExpectedEvent,
-	NonceOption,
-	TrackedRawTransactionParameters,
-	TrackedSendTransactionParameters,
-	TrackedTransaction,
-	TrackedWalletClient,
-	TrackedWriteContractParameters,
-	TransactionMetadata,
-} from './types.js';
+export type * from './types.js';
 
 // Factory
-export {createTrackedWalletClient} from './TrackedWalletClient.js';
+export {
+	createTrackedWalletClient,
+	type TrackedWalletClientBuilder,
+} from './TrackedWalletClient.js';

package/src/types.ts

@@ -28,100 +28,57 @@ export type BlockTag = 'latest' | 'pending' | 'earliest' | 'safe' | 'finalized';
  */
 export type NonceOption = number | BlockTag;
 
-/**
- * Expected event for success detection.
- * Even if tx hash changes due to replacement, we can detect success by watching for this event.
- */
-export interface ExpectedEvent {
-	address: Address;
-	eventName: string;
-	args?: Record<string, unknown>;
-}
+export type ExpectedUpdate =
+	| {
+			address: `0x${string}`;
+			event: {topics: `0x${string}`[]};
+	  }
+	| {
+			address: `0x${string}`;
+			call: {data: `0x${string}`; result: `0x${string}`};
+	  };
 
 /**
  * Metadata that can be attached to a transaction for tracking purposes.
  * All fields are optional and extensible.
  */
 export interface TransactionMetadata {
-	/**
-	 * Optional custom ID - if provided, used instead of tx hash for tracking.
-	 * Useful for correlating transactions with business logic (e.g., order IDs).
-	 */
 	id?: string;
-
-	/**
-	 * Human-readable title for the transaction.
-	 */
-	title?: string;
-
-	/**
-	 * Detailed description of what the transaction does.
-	 */
+	name?: string;
+	args?: any[];
 	description?: string;
-
-	/**
-	 * Expected event signature/filter for success detection.
-	 * Even if tx hash changes due to replacement, we can detect success by watching for this event.
-	 */
-	expectedEvent?: ExpectedEvent;
-
-	/**
-	 * Extensible: user can add any additional fields.
-	 */
+	expectedUpdate?: ExpectedUpdate;
 	[key: string]: unknown;
 }
 
 /**
- * A tracked transaction record with all relevant information for tracking.
+ * Conditional type that makes metadata required or optional based on TMetadata.
+ * If TMetadata includes undefined (e.g., `MyMeta | undefined`), metadata is optional.
+ * Otherwise, metadata is required.
  */
-export interface TrackedTransaction<
-	M extends TransactionMetadata = TransactionMetadata,
-> {
-	/**
-	 * Tracking ID - either metadata.id or auto-generated UUID.
-	 */
-	trackingId: string;
-
-	/**
-	 * The transaction hash once known.
-	 */
-	txHash: Hash;
+export type MetadataField<TMetadata> = undefined extends TMetadata
+	? {metadata?: TMetadata}
+	: {metadata: TMetadata};
 
-	/**
-	 * Sender address.
-	 */
-	from: Address;
-
-	/**
-	 * Transaction nonce (actual nonce from fetched tx, or intended if fetch failed).
-	 */
-	nonce: number;
-
-	/**
-	 * Chain ID.
-	 */
-	chainId: number;
-
-	/**
-	 * The full metadata provided by the caller.
-	 */
-	metadata: M;
-
-	/**
-	 * Timestamp when the transaction was initiated (ms since epoch).
-	 */
-	initiatedAt: number;
-
-	/**
-	 * The original transaction request data.
-	 */
-	request: unknown;
+/**
+ * A tracked transaction record with all relevant information for tracking.
+ * The metadata field type matches what was provided to the TrackedWalletClient.
+ */
+export interface TrackedTransaction<TMetadata> {
+	chainId?: number;
+	readonly hash: `0x${string}`;
+	readonly from: `0x${string}`;
+	nonce?: number;
+	readonly broadcastTimestampMs: number;
+	readonly metadata: TMetadata;
 }
 
 /**
- * Extended WriteContractParameters with optional metadata and flexible nonce.
+ * Extended WriteContractParameters with metadata and flexible nonce.
+ * Metadata is required unless TMetadata includes undefined.
  */
 export type TrackedWriteContractParameters<
+	TMetadata,
 	TAbi extends Abi | readonly unknown[] = Abi,
 	TFunctionName extends ContractFunctionName<TAbi, 'nonpayable' | 'payable'> =
 		ContractFunctionName<TAbi, 'nonpayable' | 'payable'>,
@@ -144,11 +101,6 @@ export type TrackedWriteContractParameters<
 	>,
 	'nonce'
 > & {
-	/**
-	 * Optional metadata to attach to the transaction for tracking.
-	 */
-	metadata?: TransactionMetadata;
-
 	/**
 	 * Nonce option:
 	 * - number: exact nonce to use
@@ -156,12 +108,14 @@ export type TrackedWriteContractParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-};
+} & MetadataField<TMetadata>;
 
 /**
- * Extended SendTransactionParameters with optional metadata and flexible nonce.
+ * Extended SendTransactionParameters with metadata and flexible nonce.
+ * Metadata is required unless TMetadata includes undefined.
  */
 export type TrackedSendTransactionParameters<
+	TMetadata,
 	TChain extends Chain | undefined = Chain | undefined,
 	TAccount extends Account | undefined = Account | undefined,
 	TChainOverride extends Chain | undefined = Chain | undefined,
@@ -169,11 +123,6 @@ export type TrackedSendTransactionParameters<
 	SendTransactionParameters<TChain, TAccount, TChainOverride>,
 	'nonce'
 > & {
-	/**
-	 * Optional metadata to attach to the transaction for tracking.
-	 */
-	metadata?: TransactionMetadata;
-
 	/**
 	 * Nonce option:
 	 * - number: exact nonce to use
@@ -181,28 +130,27 @@ export type TrackedSendTransactionParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-};
+} & MetadataField<TMetadata>;
 
 /**
- * Parameters for sendRawTransaction with optional metadata.
+ * Parameters for sendRawTransaction with metadata.
  * The serialized transaction already contains from/nonce which will be decoded.
+ * Metadata is required unless TMetadata includes undefined.
  */
-export interface TrackedRawTransactionParameters {
+export type TrackedRawTransactionParameters<TMetadata> = {
 	/**
 	 * The RLP-encoded signed transaction.
 	 */
 	serializedTransaction: TransactionSerialized;
-
-	/**
-	 * Optional metadata to attach to the transaction for tracking.
-	 */
-	metadata?: TransactionMetadata;
-}
+} & MetadataField<TMetadata>;
 
 /**
  * A wallet client wrapper that tracks transactions with metadata.
+ * TMetadata is the first type parameter and is mandatory - it determines
+ * whether metadata is required or optional on transaction calls.
  */
 export interface TrackedWalletClient<
+	TMetadata,
 	TTransport extends Transport = Transport,
 	TChain extends Chain | undefined = Chain | undefined,
 	TAccount extends Account | undefined = Account | undefined,
@@ -222,7 +170,7 @@ export interface TrackedWalletClient<
 	// ============================================
 
 	/**
-	 * Write to a contract with optional metadata tracking.
+	 * Write to a contract with metadata tracking.
 	 * Returns immediately after broadcast with the transaction hash.
 	 */
 	writeContract<
@@ -236,6 +184,7 @@ export interface TrackedWalletClient<
 		TChainOverride extends Chain | undefined = undefined,
 	>(
 		args: TrackedWriteContractParameters<
+			TMetadata,
 			TAbi,
 			TFunctionName,
 			TArgs,
@@ -246,19 +195,26 @@ export interface TrackedWalletClient<
 	): Promise<Hash>;
 
 	/**
-	 * Send a transaction with optional metadata tracking.
+	 * Send a transaction with metadata tracking.
 	 * Returns immediately after broadcast with the transaction hash.
 	 */
 	sendTransaction<TChainOverride extends Chain | undefined = undefined>(
-		args: TrackedSendTransactionParameters<TChain, TAccount, TChainOverride>,
+		args: TrackedSendTransactionParameters<
+			TMetadata,
+			TChain,
+			TAccount,
+			TChainOverride
+		>,
 	): Promise<Hash>;
 
 	/**
-	 * Send a signed raw transaction with optional metadata tracking.
+	 * Send a signed raw transaction with metadata tracking.
 	 * The nonce and from address are decoded from the serialized transaction.
 	 * Returns immediately after broadcast with the transaction hash.
 	 */
-	sendRawTransaction(args: TrackedRawTransactionParameters): Promise<Hash>;
+	sendRawTransaction(
+		args: TrackedRawTransactionParameters<TMetadata>,
+	): Promise<Hash>;
 
 	// ============================================
 	// Sync methods (wait for confirmation, return receipt)
@@ -279,6 +235,7 @@ export interface TrackedWalletClient<
 		TChainOverride extends Chain | undefined = undefined,
 	>(
 		args: TrackedWriteContractParameters<
+			TMetadata,
 			TAbi,
 			TFunctionName,
 			TArgs,
@@ -293,7 +250,12 @@ export interface TrackedWalletClient<
 	 * Returns the transaction receipt after the transaction is confirmed.
 	 */
 	sendTransactionSync<TChainOverride extends Chain | undefined = undefined>(
-		args: TrackedSendTransactionParameters<TChain, TAccount, TChainOverride>,
+		args: TrackedSendTransactionParameters<
+			TMetadata,
+			TChain,
+			TAccount,
+			TChainOverride
+		>,
 	): Promise<TransactionReceipt>;
 
 	/**
@@ -301,7 +263,7 @@ export interface TrackedWalletClient<
 	 * Returns the transaction receipt after the transaction is confirmed.
 	 */
 	sendRawTransactionSync(
-		args: TrackedRawTransactionParameters,
+		args: TrackedRawTransactionParameters<TMetadata>,
 	): Promise<TransactionReceipt>;
 
 	// ============================================
@@ -311,11 +273,11 @@ export interface TrackedWalletClient<
 	/**
 	 * Subscribe to transaction broadcast events.
 	 * Called immediately after a transaction is successfully broadcast.
-	 * @param listener - Callback function receiving TrackedTransaction
+	 * @param listener - Callback function receiving TrackedTransaction with TMetadata
 	 * @returns Unsubscribe function
 	 */
 	onTransactionBroadcasted(
-		listener: (event: TrackedTransaction) => void,
+		listener: (event: TrackedTransaction<TMetadata>) => void,
 	): () => void;
 
 	/**
@@ -323,6 +285,6 @@ export interface TrackedWalletClient<
 	 * @param listener - The same listener function passed to onTransactionBroadcasted
 	 */
 	offTransactionBroadcasted(
-		listener: (event: TrackedTransaction) => void,
+		listener: (event: TrackedTransaction<TMetadata>) => void,
 	): void;
 }