@tuwaio/pulsar-core 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -4,14 +4,14 @@ import { PersistOptions } from 'zustand/middleware';
 
 /**
  * @file This file defines the core data structures and TypeScript types for the Pulsar transaction tracking engine.
- * It includes types for transactions, their statuses, store interfaces, and utility types for Zustand slices.
- * These types are framework-agnostic and form the foundation of the entire tracking system.
+ * It specifies the framework-agnostic models for transactions, their lifecycle statuses, and the interfaces for
+ * the Zustand-based store and chain-specific adapters.
  */
 
 /**
  * A utility type for creating modular Zustand store slices, enabling composable state management.
- * @template T - The type of the state slice.
- * @template S - The type of the full store state, defaulting to T.
+ * @template T The state slice being defined.
+ * @template S The full store state that includes the slice `T`.
  */
 type StoreSlice<T extends object, S extends object = T> = (set: StoreApi<S extends T ? S : S & T>['setState'], get: StoreApi<S extends T ? S : S & T>['getState']) => T;
 /**
@@ -31,22 +31,27 @@ declare enum TransactionAdapter {
 declare enum TransactionStatus {
     /** The transaction failed to execute due to an on-chain error or rejection. */
     Failed = "Failed",
-    /** The transaction was successfully mined and executed. */
+    /** The transaction was successfully mined and included in a block. */
     Success = "Success",
     /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
     Replaced = "Replaced"
 }
 /**
  * The fundamental structure for any transaction being tracked by Pulsar.
- * This forms the base upon which chain-specific transaction types are built.
- * @template T - The type of the tracker identifier (e.g., 'ethereum', 'gelato', 'safe').
+ * This serves as the base upon which chain-specific transaction types are built.
+ * @template T The type of the tracker identifier (e.g., 'ethereum', 'gelato').
  */
 type BaseTransaction<T> = {
-    /** A unique key identifying a re-executable action from the `TxActions` registry. */
-    actionKey?: string;
     /** The chain identifier (e.g., 1 for Ethereum Mainnet, 'SN_MAIN' for Starknet). */
     chainId: number | string;
-    /** A user-facing description. Can be a single string or an array for [pending, success, error, replaced] states. */
+    /**
+     * User-facing description. Can be a single string for all states, or a tuple for specific states.
+     * @example
+     * // A single description for all states
+     * description: 'Swap 1 ETH for 1,500 USDC'
+     * // Specific descriptions for each state in order: [pending, success, error, replaced]
+     * description: ['Swapping...', 'Swapped Successfully', 'Swap Failed', 'Swap Replaced']
+     */
     description?: string | [string, string, string, string];
     /** The error message if the transaction failed. */
     errorMessage?: string;
@@ -66,7 +71,14 @@ type BaseTransaction<T> = {
     pending: boolean;
     /** The final on-chain status of the transaction. */
     status?: TransactionStatus;
-    /** A user-facing title. Can be a single string or an array for [pending, success, error, replaced] states. */
+    /**
+     * User-facing title. Can be a single string for all states, or a tuple for specific states.
+     * @example
+     * // A single title for all states
+     * title: 'ETH/USDC Swap'
+     * // Specific titles for each state in order: [pending, success, error, replaced]
+     * title: ['Processing Swap', 'Swap Complete', 'Swap Error', 'Swap Replaced']
+     */
     title?: string | [string, string, string, string];
     /** The specific tracker responsible for monitoring this transaction's status. */
     tracker: T;
@@ -79,7 +91,7 @@ type BaseTransaction<T> = {
 };
 /**
  * Represents an EVM-specific transaction, extending the base properties with EVM fields.
- * @template T - The type of the tracker identifier.
+ * @template T The type of the tracker identifier.
  */
 type EvmTransaction<T> = BaseTransaction<T> & {
     adapter: TransactionAdapter.EVM;
@@ -102,7 +114,7 @@ type EvmTransaction<T> = BaseTransaction<T> & {
 };
 /**
  * Represents a Solana-specific transaction, extending the base properties.
- * @template T - The type of the tracker identifier.
+ * @template T The type of the tracker identifier.
  */
 type SolanaTransaction<T> = BaseTransaction<T> & {
     adapter: TransactionAdapter.SOLANA;
@@ -114,14 +126,14 @@ type SolanaTransaction<T> = BaseTransaction<T> & {
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
     slot?: number;
-    /** The number of confirmations the transaction has received, or null if the transaction is still pending. */
+    /** The number of confirmations received. `null` if the transaction is pending or unconfirmed. */
     confirmations?: number | null;
-    /** The RPC URL used for the transaction. */
+    /** The RPC URL used to submit and track this transaction. */
     rpcUrl?: string;
 };
 /**
  * Represents a Starknet-specific transaction, extending the base properties.
- * @template T - The type of the tracker identifier.
+ * @template T The type of the tracker identifier.
  */
 type StarknetTransaction<T> = BaseTransaction<T> & {
     adapter: TransactionAdapter.Starknet;
@@ -137,38 +149,33 @@ type StarknetTransaction<T> = BaseTransaction<T> & {
 };
 /** A union type representing any possible transaction structure that Pulsar can handle. */
 type Transaction<T> = EvmTransaction<T> | SolanaTransaction<T> | StarknetTransaction<T>;
-/**
- * A registry of functions that can be re-executed, keyed by `actionKey`.
- * Used for implementing "Retry" functionality.
- */
-type TxActions = Record<string, (...args: any[]) => Promise<unknown>>;
 /**
  * Represents the parameters required to initiate a new transaction tracking flow.
  */
-type InitialTransactionParams = {
+type InitialTransactionParams<A> = {
     adapter: TransactionAdapter;
-    /** A key to identify the re-executable action from the `TxActions` registry. */
-    actionKey?: string;
-    /** A user-facing description for the transaction. */
+    /** The function that executes the on-chain action (e.g., sending a transaction) and returns a preliminary identifier like a hash. */
+    actionFunction: (...args: any[]) => Promise<A | undefined>;
+    /** A user-facing description for the transaction. Supports state-specific descriptions. */
     description?: string | [string, string, string, string];
     /** The target chain ID for the transaction. */
     desiredChainID: number | string;
     /** Any custom data to associate with the transaction. */
     payload?: object;
-    /** A user-facing title for the transaction. */
+    /** A user-facing title for the transaction. Supports state-specific titles. */
     title?: string | [string, string, string, string];
     /** The application-specific type of the transaction. */
     type: string;
     /** If true, the detailed tracking modal will open automatically upon initiation. */
     withTrackedModal?: boolean;
-    /** Required for Solana transactions. The RPC URL to use for the transaction. */
+    /** The RPC URL to use for the transaction. Required for Solana transactions. */
     rpcUrl?: string;
 };
 /**
  * Represents a transaction in its temporary, pre-submission state.
  * This is used for UI feedback while the transaction is being signed and sent.
  */
-type InitialTransaction = InitialTransactionParams & {
+type InitialTransaction<A> = InitialTransactionParams<A> & {
     /** An error message if the initialization fails (e.g., user rejects signature). */
     errorMessage?: string;
     /** A flag indicating if the transaction is being processed (e.g., waiting for signature). */
@@ -180,9 +187,9 @@ type InitialTransaction = InitialTransactionParams & {
 };
 /**
  * Defines the interface for a transaction adapter, which provides chain-specific logic and utilities.
- * @template TR - The type of the tracker identifier (e.g., a string enum).
- * @template T - The specific transaction type, extending `Transaction<TR>`.
- * @template A - The type of the key returned by the `actionFunction` (e.g., a transaction hash).
+ * @template TR The type of the tracker identifier (e.g., a string enum).
+ * @template T The specific transaction type, extending `Transaction<TR>`.
+ * @template A The type of the key returned by the `actionFunction` (e.g., a transaction hash).
  */
 type TxAdapter<TR, T extends Transaction<TR>, A> = {
     /** The unique key identifying this adapter. */
@@ -192,18 +199,18 @@ type TxAdapter<TR, T extends Transaction<TR>, A> = {
         walletAddress: string;
         walletType: string;
     };
-    /** Ensures the connected wallet is on the correct network for the transaction. */
+    /** Ensures the connected wallet is on the correct network for the transaction. Throws an error if the chain is mismatched. */
     checkChainForTx: (chainId: string | number) => Promise<void>;
-    /** Determines the appropriate tracker and final `txKey` based on the result of an action. */
+    /** Determines the appropriate tracker and final `txKey` from the result of an action. */
     checkTransactionsTracker: (actionTxKey: A, walletType: string) => {
         txKey: string;
         tracker: TR;
     };
-    /** Initializes the correct background tracker for a given transaction. */
+    /** Selects and initializes the correct background tracker for a given transaction. */
     checkAndInitializeTrackerInStore: (params: {
         tx: T;
     } & Pick<ITxTrackingStore<TR, T, A>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'>) => Promise<void>;
-    /** Returns the base URL for the blockchain explorer. */
+    /** Returns the base URL for the blockchain explorer for the current network. */
     getExplorerUrl: () => string | undefined;
     /** Optional: Fetches a name from a chain-specific name service (e.g., ENS). */
     getName?: (address: string) => Promise<string | null>;
@@ -216,30 +223,32 @@ type TxAdapter<TR, T extends Transaction<TR>, A> = {
     /** Optional: Logic to retry a failed transaction. */
     retryTxAction?: (params: {
         txKey: string;
-        tx: InitialTransactionParams;
-        actions?: TxActions;
+        tx: InitialTransactionParams<A>;
         onClose: (txKey?: string) => void;
     } & Partial<Pick<ITxTrackingStore<TR, T, A>, 'handleTransaction'>>) => Promise<void>;
-    /** Optional: Constructs a full explorer URL for a specific transaction. */
+    /**
+     * Optional: Constructs a full explorer URL for a specific transaction.
+     * May require the full transaction pool to resolve details for replaced transactions.
+     */
     getExplorerTxUrl?: (transactionsPool: TransactionPool<TR, T>, txKey: string, replacedTxHash?: string) => string;
 };
 /**
  * The complete interface for the Pulsar transaction tracking store.
- * @template TR - The type of the tracker identifier.
- * @template T - The transaction type.
- * @template A - The return type of the `actionFunction`.
+ * @template TR The type of the tracker identifier.
+ * @template T The transaction type.
+ * @template A The return type of the `actionFunction`.
  */
-type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingStore<TR, T> & {
+type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingStore<TR, T, A> & {
     /**
-     * The core function that handles the entire lifecycle of a new transaction.
+     * The primary method for initiating and tracking a new transaction from start to finish.
      * It manages UI state, executes the on-chain action, and initiates background tracking.
-     * @param params - The parameters for handling the transaction.
+     * @param params The parameters for handling the transaction.
      */
     handleTransaction: (params: {
         /** The async function to execute (e.g., a smart contract write call). Must return a unique key or undefined. */
         actionFunction: () => Promise<A | undefined>;
         /** The metadata for the transaction. */
-        params: InitialTransactionParams;
+        params: Omit<InitialTransactionParams<A>, 'actionFunction'>;
         /** The default tracker to use if it cannot be determined automatically. */
         defaultTracker?: TR;
     }) => Promise<void>;
@@ -251,58 +260,64 @@ type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingS
 };
 
 /**
- * @file This file provides the core slice for the Zustand store, responsible for managing the state of transactions.
- * It includes functions and types for initializing the store and performing basic CRUD operations on the transaction pool.
+ * @file This file defines the core Zustand slice for managing the state of transactions. It includes the state,
+ * actions, and types necessary for initializing the store and performing CRUD operations on the transaction pool.
  */
 
 /**
- * Defines the structure of the transaction pool, which is a record of transactions indexed by their unique keys.
- * @template TR - The type of the tracker identifier.
- * @template T - The transaction type.
+ * Defines the structure of the transaction pool, a key-value store of transactions indexed by their unique keys.
+ * @template TR The type of the tracker identifier.
+ * @template T The transaction type.
  */
 type TransactionPool<TR, T extends Transaction<TR>> = Record<string, T>;
 /**
- * A utility type that extracts a subset of fields from the `Transaction` type
- * that are updatable via the `updateTxParams` action.
- * @template TR - The type of the tracker identifier.
+ * A utility type that creates a union of all fields that can be safely updated
+ * on a transaction object via the `updateTxParams` action. This ensures type safety
+ * and prevents accidental modification of immutable properties.
+ * @template TR The type of the tracker identifier.
  */
 type UpdatableTransactionFields<TR> = Partial<Pick<EvmTransaction<TR>, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'errorMessage' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>> & Partial<Pick<SolanaTransaction<TR>, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
 /**
- * Defines the interface for the base transaction tracking store slice.
- * It includes the state and actions for managing transactions.
- * @template TR - The type of the tracker identifier.
- * @template T - The transaction type.
+ * The interface for the base transaction tracking store slice.
+ * It includes the state and actions for managing the transaction lifecycle.
+ * @template TR The type of the tracker identifier.
+ * @template T The specific transaction type.
+ * @template A The return type of the initial action function.
  */
-interface IInitializeTxTrackingStore<TR, T extends Transaction<TR>> {
-    /** An optional callback function to be executed when a transaction successfully completes. */
+interface IInitializeTxTrackingStore<TR, T extends Transaction<TR>, A> {
+    /** A callback function executed when any transaction successfully completes. */
     onSucceedCallbacks?: (tx: T) => Promise<void> | void;
-    /** A pool of all transactions currently being tracked, indexed by their `txKey`. */
+    /** A pool of all transactions currently being tracked, indexed by `txKey`. */
     transactionsPool: TransactionPool<TR, T>;
-    /** The key of the most recently added transaction. */
+    /** The `txKey` of the most recently added transaction. */
     lastAddedTxKey?: string;
-    /** The state of a transaction that is currently being initiated but not yet submitted. */
-    initialTx?: InitialTransaction;
-    /** Adds a new transaction to the tracking pool. */
-    addTxToPool: (tx: T) => void;
-    /** Updates one or more parameters of an existing transaction in the pool. */
+    /** The state for a transaction being initiated, used for UI feedback before it's submitted to the chain. */
+    initialTx?: InitialTransaction<A>;
+    /** Adds a new transaction to the tracking pool and marks it as pending. */
+    addTxToPool: (tx: Transaction<TR>) => void;
+    /** Updates one or more properties of an existing transaction in the pool. */
     updateTxParams: (txKey: string, fields: UpdatableTransactionFields<TR>) => void;
-    /** Removes a transaction from the tracking pool using its key. */
+    /** Removes a transaction from the tracking pool by its key. */
     removeTxFromPool: (txKey: string) => void;
-    /** Closes the tracking modal for a specific transaction. */
+    /** Closes the tracking modal for a transaction and clears any initial transaction state. */
     closeTxTrackedModal: (txKey?: string) => void;
-    /** Returns the key of the last transaction that was added to the pool. */
+    /** A selector function to retrieve the key of the last transaction added to the pool. */
     getLastTxKey: () => string | undefined;
 }
 /**
- * Creates a Zustand store slice containing the core logic for transaction tracking.
- * This function is a slice creator and is meant to be used within `createStore` from Zustand.
- * @param {object} options - Configuration options for the store slice.
- * @param {function} [options.onSucceedCallbacks] - An optional async callback to run when a transaction succeeds.
- * @returns {StoreSlice<IInitializeTxTrackingStore<TR, T>>} A Zustand store slice.
+ * Creates a Zustand store slice with the core logic for transaction state management.
+ * This function is a slice creator intended for use with Zustand's `create` function.
+ *
+ * @template TR The type of the tracker identifier.
+ * @template T The specific transaction type.
+ * @template A The return type of the initial action function.
+ * @param options Configuration for the store slice.
+ * @param options.onSucceedCallbacks An optional async callback to run when a transaction succeeds.
+ * @returns A Zustand store slice implementing `IInitializeTxTrackingStore`.
  */
-declare function initializeTxTrackingStore<TR, T extends Transaction<TR>>({ onSucceedCallbacks, }: {
+declare function initializeTxTrackingStore<TR, T extends Transaction<TR>, A>({ onSucceedCallbacks, }: {
     onSucceedCallbacks?: (tx: T) => Promise<void> | void;
-}): StoreSlice<IInitializeTxTrackingStore<TR, T>>;
+}): StoreSlice<IInitializeTxTrackingStore<TR, T, A>>;
 
 /**
  * @file This file contains selector functions for deriving state from the transaction tracking store.
@@ -356,23 +371,23 @@ declare const selectPendingTransactionsByActiveWallet: <TR, T extends Transactio
 /**
  * Creates the main Pulsar store for transaction tracking.
  *
- * This function sets up a Zustand store with persistence, combining the core
- * transaction slice with adapter-specific logic to handle the entire lifecycle
- * of a transaction.
+ * This function configures a Zustand store enhanced with persistence. It combines the core transaction management
+ * slice with a powerful orchestration logic that leverages chain-specific adapters to handle the entire
+ * lifecycle of a transaction—from initiation and chain validation to execution and background status tracking.
  *
- * @template TR - The type of the tracker identifier (e.g., a string enum).
- * @template T - The specific transaction type, extending the base `Transaction`.
- * @template A - The type for the adapter-specific context or API.
+ * @template TR The type of the tracker identifier (e.g., a string enum).
+ * @template T The specific transaction type, extending the base `Transaction`.
+ * @template A The type of the key returned by the `actionFunction` (e.g., a transaction hash).
  *
- * @param {object} config - Configuration object for creating the store.
- * @param {function} [config.onSucceedCallbacks] - Optional async callback executed on transaction success.
- * @param {TxAdapter<TR, T, A>[]} config.adapters - An array of adapters for different transaction types or chains.
- * @param {PersistOptions<ITxTrackingStore<TR, T, A>>} [options] - Configuration for the Zustand persist middleware.
+ * @param config Configuration object for creating the store.
+ * @param config.onSucceedCallbacks Optional async callback executed on transaction success.
+ * @param config.adapter Adapter or an array of adapters for different chains or transaction types.
+ * @param options Configuration for the Zustand `persist` middleware.
  * @returns A fully configured Zustand store instance.
  */
-declare function createPulsarStore<TR, T extends Transaction<TR>, A>({ onSucceedCallbacks, adapters, ...options }: {
+declare function createPulsarStore<TR, T extends Transaction<TR>, A>({ onSucceedCallbacks, adapter, ...options }: {
     onSucceedCallbacks?: (tx: T) => Promise<void> | void;
-    adapters: TxAdapter<TR, T, A>[];
+    adapter: TxAdapter<TR, T, A> | TxAdapter<TR, T, A>[];
 } & PersistOptions<ITxTrackingStore<TR, T, A>>): Omit<zustand.StoreApi<ITxTrackingStore<TR, T, A>>, "setState" | "persist"> & {
     setState(partial: ITxTrackingStore<TR, T, A> | Partial<ITxTrackingStore<TR, T, A>> | ((state: ITxTrackingStore<TR, T, A>) => ITxTrackingStore<TR, T, A> | Partial<ITxTrackingStore<TR, T, A>>), replace?: false | undefined): unknown;
     setState(state: ITxTrackingStore<TR, T, A> | ((state: ITxTrackingStore<TR, T, A>) => ITxTrackingStore<TR, T, A>), replace: true): unknown;
@@ -511,13 +526,13 @@ declare function initializePollingTracker<R, T, TR>(config: PollingTrackerConfig
  *
  * @param {object} params - The parameters for the selection.
  * @param {TransactionAdapter} params.adapterKey - The key of the desired adapter.
- * @param {TxAdapter<TR, T, A>[]} params.adapters - An array of available transaction adapters.
+ * @param {TxAdapter<TR, T, A> | TxAdapter<TR, T, A>[]} params.adapter - Adapter or an array of adapters for different chains or transaction types.
  *
  * @returns {TxAdapter<TR, T, A> | undefined} The found transaction adapter, the fallback adapter, or undefined if the adapters array is empty.
  */
-declare const selectAdapterByKey: <TR, T extends Transaction<TR>, A>({ adapterKey, adapters, }: {
+declare const selectAdapterByKey: <TR, T extends Transaction<TR>, A>({ adapterKey, adapter, }: {
     adapterKey: TransactionAdapter;
-    adapters: TxAdapter<TR, T, A>[];
+    adapter: TxAdapter<TR, T, A> | TxAdapter<TR, T, A>[];
 }) => TxAdapter<TR, T, A> | undefined;
 
-export { type BaseTransaction, type EvmTransaction, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingTrackerConfig, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type Transaction, TransactionAdapter, type TransactionPool, TransactionStatus, type TxActions, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAdapterByKey, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };
+export { type BaseTransaction, type EvmTransaction, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingTrackerConfig, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type Transaction, TransactionAdapter, type TransactionPool, TransactionStatus, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAdapterByKey, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };