@tuwaio/pulsar-core 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -34,13 +34,6 @@ declare enum TransactionStatus {
     /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
     Replaced = "Replaced"
 }
-/**
- * Defines the shape of the identifier for a Gelato transaction task.
- */
-type GelatoTxKey = {
-    /** The unique identifier assigned by the Gelato relay service. */
-    taskId: string;
-};
 /**
  * A union type representing the unique identifier returned by an `actionFunction`
  * after a transaction is submitted to the network or a relay service.
@@ -50,10 +43,9 @@ type GelatoTxKey = {
  *
  * It can be one of the following:
  * - A standard `0x...` transaction hash (`Hex`).
- * - A structured object from a relay service like Gelato (`GelatoTxKey`).
  * - A Solana transaction signature (string).
  */
-type ActionTxKey = `0x${string}` | GelatoTxKey | string;
+type ActionTxKey = `0x${string}` | string;
 /**
  * The fundamental structure for any transaction being tracked by Pulsar.
  * This serves as the base upon which chain-specific transaction types are built.
@@ -82,8 +74,8 @@ type BaseTransaction = {
     isTrackedModalOpen?: boolean;
     /** The local timestamp (in seconds) when the transaction was initiated by the user. */
     localTimestamp: number;
-    /** Any additional, custom data associated with the transaction. */
-    payload?: object;
+    /** Custom data (strings or numbers) to associate with the transaction. */
+    payload?: Record<string, string | number>;
     /** A flag indicating if the transaction is still awaiting on-chain confirmation. */
     pending: boolean;
     /** The final on-chain status of the transaction. */
@@ -105,6 +97,12 @@ type BaseTransaction = {
     type: string;
     /** The type of connector used to sign the transaction (e.g., 'injected', 'walletConnect'). */
     connectorType: string;
+    /** The number of confirmations required for the transaction to be considered confirmed. */
+    requiredConfirmations?: number;
+    /** The number of confirmations received. A string value indicates a confirmed transaction, while `null` means it's pending. */
+    confirmations?: number | string | null;
+    /** The RPC URL to use for the transaction. Required for Solana transactions. */
+    rpcUrl?: string;
 };
 /**
  * Represents an EVM-specific transaction, extending the base properties with EVM fields.
@@ -143,10 +141,6 @@ type SolanaTransaction = BaseTransaction & {
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
     slot?: number;
-    /** The number of confirmations received. A string value indicates a confirmed transaction, while `null` means it's pending. */
-    confirmations?: number | string | null;
-    /** The RPC URL used to submit and track this transaction. */
-    rpcUrl?: string;
 };
 /**
  * Represents a Starknet-specific transaction, extending the base properties.
@@ -167,25 +161,17 @@ type Transaction = EvmTransaction | SolanaTransaction | StarknetTransaction;
 /**
  * Represents the parameters required to initiate a new transaction tracking flow.
  */
-type InitialTransactionParams = {
+type InitialTransactionParams = Pick<BaseTransaction, 'description' | 'title' | 'type' | 'requiredConfirmations' | 'rpcUrl' | 'payload'> & {
     /** The specific blockchain adapter for this transaction. */
     adapter: OrbitAdapter;
     /** 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<ActionTxKey | 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. 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;
-    /** The RPC URL to use for the transaction. Required for Solana transactions. */
-    rpcUrl?: string;
+    /** The specific tracker responsible for monitoring this transaction's status. Required for Gelato tracker. */
+    tracker?: TransactionTracker;
 };
 /**
  * Represents a transaction in its temporary, pre-submission state.
@@ -211,20 +197,38 @@ interface TrackerCallbacks<T extends Transaction> {
     onReplaced?: (newTx: T, oldTx: T) => Promise<void> | void;
 }
 /**
- * @deprecated Use `TrackerCallbacks<T>` instead.
- * Defines a callback function to be executed upon a successful transaction.
- * @template T The specific transaction type, extending `Transaction`.
+ * Callbacks for synchronizing local transaction state with a remote backend.
+ * These are injected into the store at creation time.
  */
-type OnSuccessCallback<T extends Transaction> = {
-    /** Callback to execute when the transaction is successfully submitted. */
-    onSuccessCallback?: (tx: T) => Promise<void> | void;
-};
+interface SyncCallbacks<T extends Transaction> {
+    /**
+     * Called immediately after a transaction is created locally (added to pool).
+     * Use this to POST the active pending transaction to the backend.
+     */
+    onRemoteCreate?: (tx: T) => Promise<void>;
+}
 /**
  * The configuration object containing one or more transaction adapters.
  * @template T The specific transaction type.
  */
 type PulsarAdapter<T extends Transaction> = OrbitGenericAdapter<TxAdapter<T>> & {
     maxTransactions?: number;
+    gelatoApiKey?: string;
+} & SyncCallbacks<T>;
+/**
+ * Represents a tracker for a specific transaction tied to an action and a connector.
+ *
+ * @typedef {Object} CheckTxTracker
+ * @property {ActionTxKey} actionTxKey - The key identifying the specific action related to the transaction.
+ * @property {string} connectorType - The type of connector used for the transaction (e.g., wallet provider, blockchain interface).
+ * @property {TransactionTracker} [tracker] - An optional tracker object that monitors the status and progress of the transaction.
+ * @property {string} [gelatoApiKey] - An optional Gelato API key for Gelato relayer integration.
+ */
+type CheckTxTracker = {
+    actionTxKey: ActionTxKey;
+    connectorType: string;
+    tracker?: TransactionTracker;
+    gelatoApiKey?: string;
 };
 /**
  * Defines the interface for a transaction adapter, which provides chain-specific logic and utilities.
@@ -250,11 +254,9 @@ type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
     checkChainForTx: (chainId: string | number) => Promise<void>;
     /**
      * Determines the appropriate tracker and final `txKey` from the result of an action.
-     * @param actionTxKey The preliminary key returned after an action function is executed.
-     * @param connectorType The type of connector used for the transaction.
      * @returns An object containing the final `txKey` and the `TransactionTracker` to be used.
      */
-    checkTransactionsTracker: (actionTxKey: ActionTxKey, connectorType: string) => {
+    checkTransactionsTracker: ({ actionTxKey, connectorType, tracker }: CheckTxTracker) => {
         txKey: string;
         tracker: TransactionTracker;
     };
@@ -264,6 +266,7 @@ type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
      */
     checkAndInitializeTrackerInStore: (params: {
         tx: T;
+        gelatoApiKey?: string;
     } & TrackerCallbacks<T> & Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'>) => Promise<void> | void;
     /**
      * Optional: Logic to cancel a pending EVM transaction.
@@ -307,7 +310,7 @@ type TransactionPool<T extends Transaction> = Record<string, T>;
  * on a transaction object via the `updateTxParams` action. This ensures type safety
  * and prevents accidental modification of immutable properties.
  */
-type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'error' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
+type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'error' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value' | 'confirmations' | 'requiredConfirmations'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
 /**
  * The interface for the base transaction tracking store slice.
  * It includes the state and actions for managing the transaction lifecycle.
@@ -376,6 +379,77 @@ type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
      * This is essential for resuming tracking after a page reload or application restart.
      */
     initializeTransactionsPool: () => Promise<void>;
+    /**
+     * Cross-device synchronization bridge.
+     * Injects remote pending transactions into the local pool and starts their lifecycle trackers.
+     * Also self-heals local pending transactions if the remote DB knows they are terminal.
+     */
+    injectExternalPendingTxs: (remoteTxs: T[]) => Promise<void>;
+};
+/**
+ * Represents the structure and behavior of an in-memory pagination system
+ * for managing transaction history.
+ */
+type TxInMemoryPagination = {
+    /** Indicates whether the store is currently loading transaction history. */
+    isLoading: boolean;
+    /** Indicates whether the last loading request ended with an error. */
+    isError: boolean;
+    /** Indicates whether more history pages are available. */
+    hasMore: boolean;
+    /** The current page number in the paginated history. */
+    currentPage: number;
+    /** Loads the next page of transaction history and appends it to the pool. */
+    fetchNextPage: (walletAddress: string) => Promise<void>;
+};
+/**
+ * The complete interface for the Pulsar transaction in-memory store.
+ * It keeps a paginated remote history in sync with a local transaction pool.
+ *
+ * @template T The transaction type.
+ */
+type ITxInMemoryStore<T extends Transaction> = {
+    /** A pool of all transactions currently being tracked and loaded from history, indexed by `txKey`. */
+    transactionsPool: TransactionPool<T>;
+    /** Loads the first page of transaction history. */
+    fetchInitial: (walletAddress: string) => Promise<void>;
+    /** Merges a local transaction pool into the in-memory store. */
+    syncWithLocalPool: (localPool: TransactionPool<T>) => void;
+} & TxInMemoryPagination;
+/**
+ * Parameters used to configure and manage an in-memory transaction store.
+ *
+ * @template T The transaction type.
+ */
+type ITxInMemoryStoreParameters<T extends Transaction> = {
+    /** A localTransactionsPool. */
+    localTransactionsPool: TransactionPool<T>;
+    /** * Callback fired when remote history is successfully fetched.
+     * Used to inject remote pending transactions into the persistent tracking store.
+     */
+    onHistoryFetched?: (remoteTxs: T[]) => void;
+    getHistory?: ({ page, walletAddress, }: {
+        /**
+         * Page number for pagination.
+         *
+         * @defaultValue `1`
+         */
+        page?: number;
+        walletAddress: string;
+    }) => Promise<{
+        /** Array of transactions for the current page. */
+        docs: T[];
+        /** Total number of transactions matching the query. */
+        totalDocs: number;
+        /** Total number of available pages. */
+        totalPages: number;
+        /** Current page number. */
+        page: number;
+        /** Indicates whether a next page exists. */
+        hasNextPage: boolean;
+        /** Indicates whether a previous page exists. */
+        hasPrevPage: boolean;
+    } | null>;
 };
 
 /**
@@ -391,7 +465,7 @@ type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
  * @param options Configuration for the store slice.
  * @returns A Zustand store slice implementing `IInitializeTxTrackingStore`.
  */
-declare function initializeTxTrackingStore<T extends Transaction>({ maxTransactions, }: {
+declare function initializeTxTrackingStore<T extends Transaction>({ maxTransactions, onRemoteCreate, }: Pick<PulsarAdapter<T>, 'onRemoteCreate'> & {
     maxTransactions: number;
 }): StoreSlice<IInitializeTxTrackingStore<T>>;
 
@@ -439,6 +513,22 @@ declare const selectAllTransactionsByActiveWallet: <T extends Transaction>(trans
  */
 declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<T>, from: string) => T[];
 
+/**
+ * Creates an in-memory transaction store with synchronized local and remote sources.
+ *
+ * The store is designed to:
+ * - keep a local transaction pool in sync with remote history
+ * - preserve terminal transaction states
+ * - support paginated history loading
+ * - avoid duplicated merge logic across store actions
+ *
+ * @template T The transaction type.
+ * @param params Store configuration parameters.
+ * @param params.getHistory Optional remote history fetcher.
+ * @returns A Zustand vanilla store instance for in-memory transaction management.
+ */
+declare function createTxInMemoryStore<T extends Transaction>({ localTransactionsPool, getHistory, onHistoryFetched, }: ITxInMemoryStoreParameters<T>): zustand.StoreApi<ITxInMemoryStore<T>>;
+
 /**
  * Creates the main Pulsar store for transaction tracking.
  *
@@ -453,7 +543,7 @@ declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(t
  * @param options Configuration for the Zustand `persist` middleware.
  * @returns A fully configured Zustand store instance.
  */
-declare function createPulsarStore<T extends Transaction>({ adapter, maxTransactions, ...options }: PulsarAdapter<T> & PersistOptions<ITxTrackingStore<T>>): Omit<zustand.StoreApi<ITxTrackingStore<T>>, "setState" | "persist"> & {
+declare function createPulsarStore<T extends Transaction>({ adapter, maxTransactions, onRemoteCreate, gelatoApiKey, ...options }: PulsarAdapter<T> & PersistOptions<ITxTrackingStore<T>>): Omit<zustand.StoreApi<ITxTrackingStore<T>>, "setState" | "persist"> & {
     setState(partial: ITxTrackingStore<T> | Partial<ITxTrackingStore<T>> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T> | Partial<ITxTrackingStore<T>>), replace?: false | undefined): unknown;
     setState(state: ITxTrackingStore<T> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T>), replace: true): unknown;
     persist: {
@@ -571,4 +661,4 @@ type PollingTrackerConfig<R, T extends Transaction> = {
  */
 declare function initializePollingTracker<R, T extends Transaction>(config: PollingTrackerConfig<R, T>): void;
 
-export { type ActionTxKey, type BaseTransaction, type EvmTransaction, type GelatoTxKey, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type OnSuccessCallback, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };
+export { type ActionTxKey, type BaseTransaction, type CheckTxTracker, type EvmTransaction, type IInitializeTxTrackingStore, type ITxInMemoryStore, type ITxInMemoryStoreParameters, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type SyncCallbacks, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, type TxInMemoryPagination, type UpdatableTransactionFields, createBoundedUseStore, createPulsarStore, createTxInMemoryStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };

package/dist/index.d.ts

@@ -34,13 +34,6 @@ declare enum TransactionStatus {
     /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
     Replaced = "Replaced"
 }
-/**
- * Defines the shape of the identifier for a Gelato transaction task.
- */
-type GelatoTxKey = {
-    /** The unique identifier assigned by the Gelato relay service. */
-    taskId: string;
-};
 /**
  * A union type representing the unique identifier returned by an `actionFunction`
  * after a transaction is submitted to the network or a relay service.
@@ -50,10 +43,9 @@ type GelatoTxKey = {
  *
  * It can be one of the following:
  * - A standard `0x...` transaction hash (`Hex`).
- * - A structured object from a relay service like Gelato (`GelatoTxKey`).
  * - A Solana transaction signature (string).
  */
-type ActionTxKey = `0x${string}` | GelatoTxKey | string;
+type ActionTxKey = `0x${string}` | string;
 /**
  * The fundamental structure for any transaction being tracked by Pulsar.
  * This serves as the base upon which chain-specific transaction types are built.
@@ -82,8 +74,8 @@ type BaseTransaction = {
     isTrackedModalOpen?: boolean;
     /** The local timestamp (in seconds) when the transaction was initiated by the user. */
     localTimestamp: number;
-    /** Any additional, custom data associated with the transaction. */
-    payload?: object;
+    /** Custom data (strings or numbers) to associate with the transaction. */
+    payload?: Record<string, string | number>;
     /** A flag indicating if the transaction is still awaiting on-chain confirmation. */
     pending: boolean;
     /** The final on-chain status of the transaction. */
@@ -105,6 +97,12 @@ type BaseTransaction = {
     type: string;
     /** The type of connector used to sign the transaction (e.g., 'injected', 'walletConnect'). */
     connectorType: string;
+    /** The number of confirmations required for the transaction to be considered confirmed. */
+    requiredConfirmations?: number;
+    /** The number of confirmations received. A string value indicates a confirmed transaction, while `null` means it's pending. */
+    confirmations?: number | string | null;
+    /** The RPC URL to use for the transaction. Required for Solana transactions. */
+    rpcUrl?: string;
 };
 /**
  * Represents an EVM-specific transaction, extending the base properties with EVM fields.
@@ -143,10 +141,6 @@ type SolanaTransaction = BaseTransaction & {
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
     slot?: number;
-    /** The number of confirmations received. A string value indicates a confirmed transaction, while `null` means it's pending. */
-    confirmations?: number | string | null;
-    /** The RPC URL used to submit and track this transaction. */
-    rpcUrl?: string;
 };
 /**
  * Represents a Starknet-specific transaction, extending the base properties.
@@ -167,25 +161,17 @@ type Transaction = EvmTransaction | SolanaTransaction | StarknetTransaction;
 /**
  * Represents the parameters required to initiate a new transaction tracking flow.
  */
-type InitialTransactionParams = {
+type InitialTransactionParams = Pick<BaseTransaction, 'description' | 'title' | 'type' | 'requiredConfirmations' | 'rpcUrl' | 'payload'> & {
     /** The specific blockchain adapter for this transaction. */
     adapter: OrbitAdapter;
     /** 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<ActionTxKey | 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. 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;
-    /** The RPC URL to use for the transaction. Required for Solana transactions. */
-    rpcUrl?: string;
+    /** The specific tracker responsible for monitoring this transaction's status. Required for Gelato tracker. */
+    tracker?: TransactionTracker;
 };
 /**
  * Represents a transaction in its temporary, pre-submission state.
@@ -211,20 +197,38 @@ interface TrackerCallbacks<T extends Transaction> {
     onReplaced?: (newTx: T, oldTx: T) => Promise<void> | void;
 }
 /**
- * @deprecated Use `TrackerCallbacks<T>` instead.
- * Defines a callback function to be executed upon a successful transaction.
- * @template T The specific transaction type, extending `Transaction`.
+ * Callbacks for synchronizing local transaction state with a remote backend.
+ * These are injected into the store at creation time.
  */
-type OnSuccessCallback<T extends Transaction> = {
-    /** Callback to execute when the transaction is successfully submitted. */
-    onSuccessCallback?: (tx: T) => Promise<void> | void;
-};
+interface SyncCallbacks<T extends Transaction> {
+    /**
+     * Called immediately after a transaction is created locally (added to pool).
+     * Use this to POST the active pending transaction to the backend.
+     */
+    onRemoteCreate?: (tx: T) => Promise<void>;
+}
 /**
  * The configuration object containing one or more transaction adapters.
  * @template T The specific transaction type.
  */
 type PulsarAdapter<T extends Transaction> = OrbitGenericAdapter<TxAdapter<T>> & {
     maxTransactions?: number;
+    gelatoApiKey?: string;
+} & SyncCallbacks<T>;
+/**
+ * Represents a tracker for a specific transaction tied to an action and a connector.
+ *
+ * @typedef {Object} CheckTxTracker
+ * @property {ActionTxKey} actionTxKey - The key identifying the specific action related to the transaction.
+ * @property {string} connectorType - The type of connector used for the transaction (e.g., wallet provider, blockchain interface).
+ * @property {TransactionTracker} [tracker] - An optional tracker object that monitors the status and progress of the transaction.
+ * @property {string} [gelatoApiKey] - An optional Gelato API key for Gelato relayer integration.
+ */
+type CheckTxTracker = {
+    actionTxKey: ActionTxKey;
+    connectorType: string;
+    tracker?: TransactionTracker;
+    gelatoApiKey?: string;
 };
 /**
  * Defines the interface for a transaction adapter, which provides chain-specific logic and utilities.
@@ -250,11 +254,9 @@ type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
     checkChainForTx: (chainId: string | number) => Promise<void>;
     /**
      * Determines the appropriate tracker and final `txKey` from the result of an action.
-     * @param actionTxKey The preliminary key returned after an action function is executed.
-     * @param connectorType The type of connector used for the transaction.
      * @returns An object containing the final `txKey` and the `TransactionTracker` to be used.
      */
-    checkTransactionsTracker: (actionTxKey: ActionTxKey, connectorType: string) => {
+    checkTransactionsTracker: ({ actionTxKey, connectorType, tracker }: CheckTxTracker) => {
         txKey: string;
         tracker: TransactionTracker;
     };
@@ -264,6 +266,7 @@ type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
      */
     checkAndInitializeTrackerInStore: (params: {
         tx: T;
+        gelatoApiKey?: string;
     } & TrackerCallbacks<T> & Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'>) => Promise<void> | void;
     /**
      * Optional: Logic to cancel a pending EVM transaction.
@@ -307,7 +310,7 @@ type TransactionPool<T extends Transaction> = Record<string, T>;
  * on a transaction object via the `updateTxParams` action. This ensures type safety
  * and prevents accidental modification of immutable properties.
  */
-type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'error' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
+type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'error' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value' | 'confirmations' | 'requiredConfirmations'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
 /**
  * The interface for the base transaction tracking store slice.
  * It includes the state and actions for managing the transaction lifecycle.
@@ -376,6 +379,77 @@ type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
      * This is essential for resuming tracking after a page reload or application restart.
      */
     initializeTransactionsPool: () => Promise<void>;
+    /**
+     * Cross-device synchronization bridge.
+     * Injects remote pending transactions into the local pool and starts their lifecycle trackers.
+     * Also self-heals local pending transactions if the remote DB knows they are terminal.
+     */
+    injectExternalPendingTxs: (remoteTxs: T[]) => Promise<void>;
+};
+/**
+ * Represents the structure and behavior of an in-memory pagination system
+ * for managing transaction history.
+ */
+type TxInMemoryPagination = {
+    /** Indicates whether the store is currently loading transaction history. */
+    isLoading: boolean;
+    /** Indicates whether the last loading request ended with an error. */
+    isError: boolean;
+    /** Indicates whether more history pages are available. */
+    hasMore: boolean;
+    /** The current page number in the paginated history. */
+    currentPage: number;
+    /** Loads the next page of transaction history and appends it to the pool. */
+    fetchNextPage: (walletAddress: string) => Promise<void>;
+};
+/**
+ * The complete interface for the Pulsar transaction in-memory store.
+ * It keeps a paginated remote history in sync with a local transaction pool.
+ *
+ * @template T The transaction type.
+ */
+type ITxInMemoryStore<T extends Transaction> = {
+    /** A pool of all transactions currently being tracked and loaded from history, indexed by `txKey`. */
+    transactionsPool: TransactionPool<T>;
+    /** Loads the first page of transaction history. */
+    fetchInitial: (walletAddress: string) => Promise<void>;
+    /** Merges a local transaction pool into the in-memory store. */
+    syncWithLocalPool: (localPool: TransactionPool<T>) => void;
+} & TxInMemoryPagination;
+/**
+ * Parameters used to configure and manage an in-memory transaction store.
+ *
+ * @template T The transaction type.
+ */
+type ITxInMemoryStoreParameters<T extends Transaction> = {
+    /** A localTransactionsPool. */
+    localTransactionsPool: TransactionPool<T>;
+    /** * Callback fired when remote history is successfully fetched.
+     * Used to inject remote pending transactions into the persistent tracking store.
+     */
+    onHistoryFetched?: (remoteTxs: T[]) => void;
+    getHistory?: ({ page, walletAddress, }: {
+        /**
+         * Page number for pagination.
+         *
+         * @defaultValue `1`
+         */
+        page?: number;
+        walletAddress: string;
+    }) => Promise<{
+        /** Array of transactions for the current page. */
+        docs: T[];
+        /** Total number of transactions matching the query. */
+        totalDocs: number;
+        /** Total number of available pages. */
+        totalPages: number;
+        /** Current page number. */
+        page: number;
+        /** Indicates whether a next page exists. */
+        hasNextPage: boolean;
+        /** Indicates whether a previous page exists. */
+        hasPrevPage: boolean;
+    } | null>;
 };
 
 /**
@@ -391,7 +465,7 @@ type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
  * @param options Configuration for the store slice.
  * @returns A Zustand store slice implementing `IInitializeTxTrackingStore`.
  */
-declare function initializeTxTrackingStore<T extends Transaction>({ maxTransactions, }: {
+declare function initializeTxTrackingStore<T extends Transaction>({ maxTransactions, onRemoteCreate, }: Pick<PulsarAdapter<T>, 'onRemoteCreate'> & {
     maxTransactions: number;
 }): StoreSlice<IInitializeTxTrackingStore<T>>;
 
@@ -439,6 +513,22 @@ declare const selectAllTransactionsByActiveWallet: <T extends Transaction>(trans
  */
 declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<T>, from: string) => T[];
 
+/**
+ * Creates an in-memory transaction store with synchronized local and remote sources.
+ *
+ * The store is designed to:
+ * - keep a local transaction pool in sync with remote history
+ * - preserve terminal transaction states
+ * - support paginated history loading
+ * - avoid duplicated merge logic across store actions
+ *
+ * @template T The transaction type.
+ * @param params Store configuration parameters.
+ * @param params.getHistory Optional remote history fetcher.
+ * @returns A Zustand vanilla store instance for in-memory transaction management.
+ */
+declare function createTxInMemoryStore<T extends Transaction>({ localTransactionsPool, getHistory, onHistoryFetched, }: ITxInMemoryStoreParameters<T>): zustand.StoreApi<ITxInMemoryStore<T>>;
+
 /**
  * Creates the main Pulsar store for transaction tracking.
  *
@@ -453,7 +543,7 @@ declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(t
  * @param options Configuration for the Zustand `persist` middleware.
  * @returns A fully configured Zustand store instance.
  */
-declare function createPulsarStore<T extends Transaction>({ adapter, maxTransactions, ...options }: PulsarAdapter<T> & PersistOptions<ITxTrackingStore<T>>): Omit<zustand.StoreApi<ITxTrackingStore<T>>, "setState" | "persist"> & {
+declare function createPulsarStore<T extends Transaction>({ adapter, maxTransactions, onRemoteCreate, gelatoApiKey, ...options }: PulsarAdapter<T> & PersistOptions<ITxTrackingStore<T>>): Omit<zustand.StoreApi<ITxTrackingStore<T>>, "setState" | "persist"> & {
     setState(partial: ITxTrackingStore<T> | Partial<ITxTrackingStore<T>> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T> | Partial<ITxTrackingStore<T>>), replace?: false | undefined): unknown;
     setState(state: ITxTrackingStore<T> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T>), replace: true): unknown;
     persist: {
@@ -571,4 +661,4 @@ type PollingTrackerConfig<R, T extends Transaction> = {
  */
 declare function initializePollingTracker<R, T extends Transaction>(config: PollingTrackerConfig<R, T>): void;
 
-export { type ActionTxKey, type BaseTransaction, type EvmTransaction, type GelatoTxKey, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type OnSuccessCallback, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };
+export { type ActionTxKey, type BaseTransaction, type CheckTxTracker, type EvmTransaction, type IInitializeTxTrackingStore, type ITxInMemoryStore, type ITxInMemoryStoreParameters, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type SyncCallbacks, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, type TxInMemoryPagination, type UpdatableTransactionFields, createBoundedUseStore, createPulsarStore, createTxInMemoryStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };

package/dist/index.js

@@ -1 +1 @@
-'use strict';var immer=require('immer'),orbitCore=require('@tuwaio/orbit-core'),C=require('dayjs'),middleware=require('zustand/middleware'),vanilla=require('zustand/vanilla'),zustand=require('zustand');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var C__default=/*#__PURE__*/_interopDefault(C);function h({maxTransactions:o}){return (t,a)=>({transactionsPool:{},lastAddedTxKey:void 0,initialTx:void 0,addTxToPool:e=>{t(r=>immer.produce(r,n=>{if(n.lastAddedTxKey=e.txKey,e.txKey){if(Object.keys(n.transactionsPool).length>=o){let d=Object.values(n.transactionsPool).sort((l,x)=>l.localTimestamp-x.localTimestamp);if(d.length>0){let l=d[0];delete n.transactionsPool[l.txKey];}}let s={...e,pending:true};n.transactionsPool[e.txKey]=s;}}));},updateTxParams:(e,r)=>{t(n=>immer.produce(n,i=>{let s=i.transactionsPool[e];s&&Object.assign(s,r);}));},removeTxFromPool:e=>{t(r=>immer.produce(r,n=>{delete n.transactionsPool[e];}));},closeTxTrackedModal:e=>{t(r=>immer.produce(r,n=>{if(e&&n.transactionsPool[e]){let i=n.transactionsPool[e];n.transactionsPool[e]={...i,isTrackedModalOpen:false};}n.initialTx=void 0;}));},getLastTxKey:()=>a().lastAddedTxKey})}var b=o=>Object.values(o).sort((t,a)=>Number(t.localTimestamp)-Number(a.localTimestamp)),_=o=>b(o).filter(t=>t.pending),H=(o,t)=>o[t],E=(o,t)=>b(o).filter(a=>a.from.toLowerCase()===t.toLowerCase()),V=(o,t)=>E(o,t).filter(a=>a.pending);function te({adapter:o,maxTransactions:t=50,...a}){return vanilla.createStore()(middleware.persist((e,r)=>({...h({maxTransactions:t})(e,r),getAdapter:()=>o,initializeTransactionsPool:async()=>{let n=Object.values(r().transactionsPool).filter(i=>i.pending);await Promise.all(n.map(i=>orbitCore.selectAdapterByKey({adapterKey:i.adapter,adapter:o})?.checkAndInitializeTrackerInStore({tx:i,...r()})));},executeTxAction:async({defaultTracker:n,actionFunction:i,params:s,...d})=>{let{desiredChainID:l,...x}=s,{onSuccess:g,onError:m,onReplaced:u}=d,y=C__default.default().unix();e({initialTx:{...s,actionFunction:i,localTimestamp:y,isInitializing:true}});let c=orbitCore.selectAdapterByKey({adapterKey:x.adapter,adapter:o}),A=T=>{e(f=>immer.produce(f,p=>{p.initialTx&&(p.initialTx.isInitializing=false,p.initialTx.error=orbitCore.normalizeError(T));}));};if(!c){let T=new Error("No adapter found for this transaction.");throw A(T),T}try{let{connectorType:T,walletAddress:f}=c.getConnectorInfo();await c.checkChainForTx(l);let p=await i();if(!p){e({initialTx:void 0});return}let{tracker:v,txKey:k}=c.checkTransactionsTracker(p,T),w={...x,connectorType:T,from:f,tracker:v||n,chainId:orbitCore.setChainId(l),localTimestamp:y,txKey:k,hash:v==="ethereum"?p:void 0,pending:!1,isTrackedModalOpen:s.withTrackedModal};r().addTxToPool(w),e(F=>immer.produce(F,S=>{S.initialTx&&(S.initialTx.isInitializing=!1,S.initialTx.lastTxKey=k);}));let R=r().transactionsPool[k];await c.checkAndInitializeTrackerInStore({tx:R,onSuccess:g,onError:m,onReplaced:u,...r()});}catch(T){throw A(T),T}}}),{...a}))}var U=(r=>(r.Ethereum="ethereum",r.Safe="safe",r.Gelato="gelato",r.Solana="solana",r))(U||{}),j=(e=>(e.Failed="Failed",e.Success="Success",e.Replaced="Replaced",e))(j||{});var ae=(o=>t=>zustand.useStore(o,t));var M=5e3,$=10;function ce(o){let{tx:t,fetcher:a,onInitialize:e,onSuccess:r,onFailure:n,onIntervalTick:i,onReplaced:s,removeTxFromPool:d,pollingInterval:l=M,maxRetries:x=$}=o;if(!t.pending)return;e?.();let g=x,m=true,u=c=>{m&&(m=false,d&&!c?.withoutRemoving&&d(t.txKey));};(async()=>{for(;m&&g>0;)try{if(await new Promise(c=>setTimeout(c,l)),!m)break;await a({tx:t,stopPolling:u,onSuccess:r,onFailure:n,onIntervalTick:i,onReplaced:s});}catch(c){console.error(`Polling fetcher for txKey ${t.txKey} threw an error:`,c),g--;}g<=0&&(console.warn(`Polling for txKey ${t.txKey} stopped after reaching the maximum number of retries.`),n(),u());})();}exports.TransactionStatus=j;exports.TransactionTracker=U;exports.createBoundedUseStore=ae;exports.createPulsarStore=te;exports.initializePollingTracker=ce;exports.initializeTxTrackingStore=h;exports.selectAllTransactions=b;exports.selectAllTransactionsByActiveWallet=E;exports.selectPendingTransactions=_;exports.selectPendingTransactionsByActiveWallet=V;exports.selectTxByKey=H;
+'use strict';var immer=require('immer'),vanilla=require('zustand/vanilla'),orbitCore=require('@tuwaio/orbit-core'),D=require('dayjs'),middleware=require('zustand/middleware'),zustand=require('zustand');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var D__default=/*#__PURE__*/_interopDefault(D);function E({maxTransactions:o,onRemoteCreate:t}){return (s,p)=>({transactionsPool:{},lastAddedTxKey:void 0,initialTx:void 0,addTxToPool:a=>{let e={...a,pending:true};s(n=>immer.produce(n,r=>{if(r.lastAddedTxKey=a.txKey,a.txKey){if(Object.keys(r.transactionsPool).length>=o){let l=Object.values(r.transactionsPool).sort((T,c)=>T.localTimestamp-c.localTimestamp);if(l.length>0){let T=l[0];delete r.transactionsPool[T.txKey];}}r.transactionsPool[a.txKey]=e;}})),t&&t(e).catch(n=>console.error("[Pulsar Sync] Create failed:",n));},updateTxParams:(a,e)=>{s(n=>immer.produce(n,r=>{let i=r.transactionsPool[a];i&&Object.assign(i,e);}));},removeTxFromPool:a=>{s(e=>immer.produce(e,n=>{delete n.transactionsPool[a];}));},closeTxTrackedModal:a=>{s(e=>immer.produce(e,n=>{if(a&&n.transactionsPool[a]){let r=n.transactionsPool[a];n.transactionsPool[a]={...r,isTrackedModalOpen:false};}n.initialTx=void 0;}));},getLastTxKey:()=>p().lastAddedTxKey})}var F=o=>Object.values(o).sort((t,s)=>Number(t.localTimestamp)-Number(s.localTimestamp)),Y=o=>F(o).filter(t=>t.pending),Z=(o,t)=>o[t],B=(o,t)=>F(o).filter(s=>s.from.toLowerCase()===t.toLowerCase()),ee=(o,t)=>B(o,t).filter(s=>s.pending);var N=(a=>(a.Ethereum="ethereum",a.Safe="safe",a.Gelato="gelato",a.Solana="solana",a))(N||{}),A=(p=>(p.Failed="Failed",p.Success="Success",p.Replaced="Replaced",p))(A||{});var $=o=>o==="Success"||o==="Replaced",M=(o,t)=>{let s=o[t.txKey];return $(s?.status)?false:(o[t.txKey]=t,true)};function Te({localTransactionsPool:o,getHistory:t,onHistoryFetched:s}){immer.setAutoFreeze(false);let p=e=>({isLoading:e,isError:false}),a=e=>e?(s&&queueMicrotask(()=>s(e.docs)),n=>immer.produce(n,r=>{let i=r.transactionsPool;for(let l of e.docs)M(i,l);r.currentPage=e.page,r.hasMore=e.hasNextPage,r.isLoading=false;})):n=>n;return vanilla.createStore()((e,n)=>({transactionsPool:o,isLoading:false,isError:false,hasMore:false,currentPage:1,syncWithLocalPool:r=>{e(i=>immer.produce(i,l=>{let T=l.transactionsPool;for(let c of Object.values(r))M(T,c);}));},fetchInitial:async r=>{if(!(!t||!r)){e(p(true));try{let i=await t({page:1,walletAddress:r});e(a(i));}catch(i){console.error("[Pulsar] Failed to fetch initial transaction history:",i),e({isLoading:false,isError:true});}}},fetchNextPage:async r=>{let{hasMore:i,isLoading:l,currentPage:T}=n();if(!(!t||!i||l||!r)){e(p(true));try{let c=T+1,m=await t({page:c,walletAddress:r});e(a(m));}catch(c){console.error(`[Pulsar] Failed to fetch transaction history page ${T+1}:`,c),e({isLoading:false,isError:true});}}}}))}function Ae({adapter:o,maxTransactions:t=50,onRemoteCreate:s,gelatoApiKey:p,...a}){return vanilla.createStore()(middleware.persist((e,n)=>({...E({maxTransactions:t,onRemoteCreate:s})(e,n),getAdapter:()=>o,initializeTransactionsPool:async()=>{let r=Object.values(n().transactionsPool).filter(i=>i.pending);await Promise.all(r.map(i=>orbitCore.selectAdapterByKey({adapterKey:i.adapter,adapter:o})?.checkAndInitializeTrackerInStore({tx:i,gelatoApiKey:p,...n()})));},injectExternalPendingTxs:async r=>{let l=n().getAdapter(),T=[];e(c=>immer.produce(c,m=>{let g=m.transactionsPool;r.forEach(d=>{let x=g[d.txKey];d.pending&&!x&&(g[d.txKey]=d,T.push(d));let S=d.status==="Success"||d.status==="Failed"||d.status==="Replaced";x?.pending&&S&&(x.status=d.status,x.pending=false,d.txKey&&(x.txKey=d.txKey),d.finishedTimestamp&&(x.finishedTimestamp=d.finishedTimestamp));});})),T.length>0&&await Promise.all(T.map(c=>orbitCore.selectAdapterByKey({adapterKey:c.adapter,adapter:l})?.checkAndInitializeTrackerInStore({tx:c,gelatoApiKey:p,...n()})));},executeTxAction:async({defaultTracker:r,actionFunction:i,params:l,...T})=>{let{desiredChainID:c,tracker:m,...g}=l,{onSuccess:d,onError:x,onReplaced:S}=T,K=D__default.default().unix();e({initialTx:{...l,actionFunction:i,localTimestamp:K,isInitializing:true}});let f=orbitCore.selectAdapterByKey({adapterKey:g.adapter,adapter:o}),w=u=>{e(k=>immer.produce(k,P=>{P.initialTx&&(P.initialTx.isInitializing=false,P.initialTx.error=orbitCore.normalizeError(u));}));};if(!f){let u=new Error("No adapter found for this transaction.");throw w(u),u}try{let{connectorType:u,walletAddress:k}=f.getConnectorInfo();await f.checkChainForTx(c);let P=await i();if(!P){e({initialTx:void 0});return}let{tracker:R,txKey:h}=f.checkTransactionsTracker({actionTxKey:P,connectorType:u,tracker:m,gelatoApiKey:p}),O={...g,connectorType:u,from:k,tracker:R||r,chainId:orbitCore.setChainId(c),localTimestamp:K,txKey:h,hash:R==="ethereum"?P:void 0,pending:!1,isTrackedModalOpen:l.withTrackedModal};n().addTxToPool(O),e(L=>immer.produce(L,I=>{I.initialTx&&(I.initialTx.isInitializing=!1,I.initialTx.lastTxKey=h);}));let z=n().transactionsPool[h];await f.checkAndInitializeTrackerInStore({tx:z,onSuccess:d,onError:x,onReplaced:S,gelatoApiKey:p,...n()});}catch(u){throw w(u),u}}}),{...a}))}var we=(o=>t=>zustand.useStore(o,t));var V=5e3,X=10;function Ee(o){let{tx:t,fetcher:s,onInitialize:p,onSuccess:a,onFailure:e,onIntervalTick:n,onReplaced:r,removeTxFromPool:i,pollingInterval:l=V,maxRetries:T=X}=o;if(!t.pending)return;p?.();let c=T,m=true,g=x=>{m&&(m=false,i&&!x?.withoutRemoving&&i(t.txKey));};(async()=>{for(;m&&c>0;)try{if(await new Promise(x=>setTimeout(x,l)),!m)break;await s({tx:t,stopPolling:g,onSuccess:a,onFailure:e,onIntervalTick:n,onReplaced:r});}catch(x){console.error(`Polling fetcher for txKey ${t.txKey} threw an error:`,x),c--;}c<=0&&(console.warn(`Polling for txKey ${t.txKey} stopped after reaching the maximum number of retries.`),e(),g());})();}exports.TransactionStatus=A;exports.TransactionTracker=N;exports.createBoundedUseStore=we;exports.createPulsarStore=Ae;exports.createTxInMemoryStore=Te;exports.initializePollingTracker=Ee;exports.initializeTxTrackingStore=E;exports.selectAllTransactions=F;exports.selectAllTransactionsByActiveWallet=B;exports.selectPendingTransactions=Y;exports.selectPendingTransactionsByActiveWallet=ee;exports.selectTxByKey=Z;

package/dist/index.mjs

@@ -1 +1 @@
-import {produce}from'immer';import {selectAdapterByKey,setChainId,normalizeError}from'@tuwaio/orbit-core';import C from'dayjs';import {persist}from'zustand/middleware';import {createStore}from'zustand/vanilla';import {useStore}from'zustand';function h({maxTransactions:o}){return (t,a)=>({transactionsPool:{},lastAddedTxKey:void 0,initialTx:void 0,addTxToPool:e=>{t(r=>produce(r,n=>{if(n.lastAddedTxKey=e.txKey,e.txKey){if(Object.keys(n.transactionsPool).length>=o){let d=Object.values(n.transactionsPool).sort((l,x)=>l.localTimestamp-x.localTimestamp);if(d.length>0){let l=d[0];delete n.transactionsPool[l.txKey];}}let s={...e,pending:true};n.transactionsPool[e.txKey]=s;}}));},updateTxParams:(e,r)=>{t(n=>produce(n,i=>{let s=i.transactionsPool[e];s&&Object.assign(s,r);}));},removeTxFromPool:e=>{t(r=>produce(r,n=>{delete n.transactionsPool[e];}));},closeTxTrackedModal:e=>{t(r=>produce(r,n=>{if(e&&n.transactionsPool[e]){let i=n.transactionsPool[e];n.transactionsPool[e]={...i,isTrackedModalOpen:false};}n.initialTx=void 0;}));},getLastTxKey:()=>a().lastAddedTxKey})}var b=o=>Object.values(o).sort((t,a)=>Number(t.localTimestamp)-Number(a.localTimestamp)),_=o=>b(o).filter(t=>t.pending),H=(o,t)=>o[t],E=(o,t)=>b(o).filter(a=>a.from.toLowerCase()===t.toLowerCase()),V=(o,t)=>E(o,t).filter(a=>a.pending);function te({adapter:o,maxTransactions:t=50,...a}){return createStore()(persist((e,r)=>({...h({maxTransactions:t})(e,r),getAdapter:()=>o,initializeTransactionsPool:async()=>{let n=Object.values(r().transactionsPool).filter(i=>i.pending);await Promise.all(n.map(i=>selectAdapterByKey({adapterKey:i.adapter,adapter:o})?.checkAndInitializeTrackerInStore({tx:i,...r()})));},executeTxAction:async({defaultTracker:n,actionFunction:i,params:s,...d})=>{let{desiredChainID:l,...x}=s,{onSuccess:g,onError:m,onReplaced:u}=d,y=C().unix();e({initialTx:{...s,actionFunction:i,localTimestamp:y,isInitializing:true}});let c=selectAdapterByKey({adapterKey:x.adapter,adapter:o}),A=T=>{e(f=>produce(f,p=>{p.initialTx&&(p.initialTx.isInitializing=false,p.initialTx.error=normalizeError(T));}));};if(!c){let T=new Error("No adapter found for this transaction.");throw A(T),T}try{let{connectorType:T,walletAddress:f}=c.getConnectorInfo();await c.checkChainForTx(l);let p=await i();if(!p){e({initialTx:void 0});return}let{tracker:v,txKey:k}=c.checkTransactionsTracker(p,T),w={...x,connectorType:T,from:f,tracker:v||n,chainId:setChainId(l),localTimestamp:y,txKey:k,hash:v==="ethereum"?p:void 0,pending:!1,isTrackedModalOpen:s.withTrackedModal};r().addTxToPool(w),e(F=>produce(F,S=>{S.initialTx&&(S.initialTx.isInitializing=!1,S.initialTx.lastTxKey=k);}));let R=r().transactionsPool[k];await c.checkAndInitializeTrackerInStore({tx:R,onSuccess:g,onError:m,onReplaced:u,...r()});}catch(T){throw A(T),T}}}),{...a}))}var U=(r=>(r.Ethereum="ethereum",r.Safe="safe",r.Gelato="gelato",r.Solana="solana",r))(U||{}),j=(e=>(e.Failed="Failed",e.Success="Success",e.Replaced="Replaced",e))(j||{});var ae=(o=>t=>useStore(o,t));var M=5e3,$=10;function ce(o){let{tx:t,fetcher:a,onInitialize:e,onSuccess:r,onFailure:n,onIntervalTick:i,onReplaced:s,removeTxFromPool:d,pollingInterval:l=M,maxRetries:x=$}=o;if(!t.pending)return;e?.();let g=x,m=true,u=c=>{m&&(m=false,d&&!c?.withoutRemoving&&d(t.txKey));};(async()=>{for(;m&&g>0;)try{if(await new Promise(c=>setTimeout(c,l)),!m)break;await a({tx:t,stopPolling:u,onSuccess:r,onFailure:n,onIntervalTick:i,onReplaced:s});}catch(c){console.error(`Polling fetcher for txKey ${t.txKey} threw an error:`,c),g--;}g<=0&&(console.warn(`Polling for txKey ${t.txKey} stopped after reaching the maximum number of retries.`),n(),u());})();}export{j as TransactionStatus,U as TransactionTracker,ae as createBoundedUseStore,te as createPulsarStore,ce as initializePollingTracker,h as initializeTxTrackingStore,b as selectAllTransactions,E as selectAllTransactionsByActiveWallet,_ as selectPendingTransactions,V as selectPendingTransactionsByActiveWallet,H as selectTxByKey};
+import {produce,setAutoFreeze}from'immer';import {createStore}from'zustand/vanilla';import {selectAdapterByKey,setChainId,normalizeError}from'@tuwaio/orbit-core';import D from'dayjs';import {persist}from'zustand/middleware';import {useStore}from'zustand';function E({maxTransactions:o,onRemoteCreate:t}){return (s,p)=>({transactionsPool:{},lastAddedTxKey:void 0,initialTx:void 0,addTxToPool:a=>{let e={...a,pending:true};s(n=>produce(n,r=>{if(r.lastAddedTxKey=a.txKey,a.txKey){if(Object.keys(r.transactionsPool).length>=o){let l=Object.values(r.transactionsPool).sort((T,c)=>T.localTimestamp-c.localTimestamp);if(l.length>0){let T=l[0];delete r.transactionsPool[T.txKey];}}r.transactionsPool[a.txKey]=e;}})),t&&t(e).catch(n=>console.error("[Pulsar Sync] Create failed:",n));},updateTxParams:(a,e)=>{s(n=>produce(n,r=>{let i=r.transactionsPool[a];i&&Object.assign(i,e);}));},removeTxFromPool:a=>{s(e=>produce(e,n=>{delete n.transactionsPool[a];}));},closeTxTrackedModal:a=>{s(e=>produce(e,n=>{if(a&&n.transactionsPool[a]){let r=n.transactionsPool[a];n.transactionsPool[a]={...r,isTrackedModalOpen:false};}n.initialTx=void 0;}));},getLastTxKey:()=>p().lastAddedTxKey})}var F=o=>Object.values(o).sort((t,s)=>Number(t.localTimestamp)-Number(s.localTimestamp)),Y=o=>F(o).filter(t=>t.pending),Z=(o,t)=>o[t],B=(o,t)=>F(o).filter(s=>s.from.toLowerCase()===t.toLowerCase()),ee=(o,t)=>B(o,t).filter(s=>s.pending);var N=(a=>(a.Ethereum="ethereum",a.Safe="safe",a.Gelato="gelato",a.Solana="solana",a))(N||{}),A=(p=>(p.Failed="Failed",p.Success="Success",p.Replaced="Replaced",p))(A||{});var $=o=>o==="Success"||o==="Replaced",M=(o,t)=>{let s=o[t.txKey];return $(s?.status)?false:(o[t.txKey]=t,true)};function Te({localTransactionsPool:o,getHistory:t,onHistoryFetched:s}){setAutoFreeze(false);let p=e=>({isLoading:e,isError:false}),a=e=>e?(s&&queueMicrotask(()=>s(e.docs)),n=>produce(n,r=>{let i=r.transactionsPool;for(let l of e.docs)M(i,l);r.currentPage=e.page,r.hasMore=e.hasNextPage,r.isLoading=false;})):n=>n;return createStore()((e,n)=>({transactionsPool:o,isLoading:false,isError:false,hasMore:false,currentPage:1,syncWithLocalPool:r=>{e(i=>produce(i,l=>{let T=l.transactionsPool;for(let c of Object.values(r))M(T,c);}));},fetchInitial:async r=>{if(!(!t||!r)){e(p(true));try{let i=await t({page:1,walletAddress:r});e(a(i));}catch(i){console.error("[Pulsar] Failed to fetch initial transaction history:",i),e({isLoading:false,isError:true});}}},fetchNextPage:async r=>{let{hasMore:i,isLoading:l,currentPage:T}=n();if(!(!t||!i||l||!r)){e(p(true));try{let c=T+1,m=await t({page:c,walletAddress:r});e(a(m));}catch(c){console.error(`[Pulsar] Failed to fetch transaction history page ${T+1}:`,c),e({isLoading:false,isError:true});}}}}))}function Ae({adapter:o,maxTransactions:t=50,onRemoteCreate:s,gelatoApiKey:p,...a}){return createStore()(persist((e,n)=>({...E({maxTransactions:t,onRemoteCreate:s})(e,n),getAdapter:()=>o,initializeTransactionsPool:async()=>{let r=Object.values(n().transactionsPool).filter(i=>i.pending);await Promise.all(r.map(i=>selectAdapterByKey({adapterKey:i.adapter,adapter:o})?.checkAndInitializeTrackerInStore({tx:i,gelatoApiKey:p,...n()})));},injectExternalPendingTxs:async r=>{let l=n().getAdapter(),T=[];e(c=>produce(c,m=>{let g=m.transactionsPool;r.forEach(d=>{let x=g[d.txKey];d.pending&&!x&&(g[d.txKey]=d,T.push(d));let S=d.status==="Success"||d.status==="Failed"||d.status==="Replaced";x?.pending&&S&&(x.status=d.status,x.pending=false,d.txKey&&(x.txKey=d.txKey),d.finishedTimestamp&&(x.finishedTimestamp=d.finishedTimestamp));});})),T.length>0&&await Promise.all(T.map(c=>selectAdapterByKey({adapterKey:c.adapter,adapter:l})?.checkAndInitializeTrackerInStore({tx:c,gelatoApiKey:p,...n()})));},executeTxAction:async({defaultTracker:r,actionFunction:i,params:l,...T})=>{let{desiredChainID:c,tracker:m,...g}=l,{onSuccess:d,onError:x,onReplaced:S}=T,K=D().unix();e({initialTx:{...l,actionFunction:i,localTimestamp:K,isInitializing:true}});let f=selectAdapterByKey({adapterKey:g.adapter,adapter:o}),w=u=>{e(k=>produce(k,P=>{P.initialTx&&(P.initialTx.isInitializing=false,P.initialTx.error=normalizeError(u));}));};if(!f){let u=new Error("No adapter found for this transaction.");throw w(u),u}try{let{connectorType:u,walletAddress:k}=f.getConnectorInfo();await f.checkChainForTx(c);let P=await i();if(!P){e({initialTx:void 0});return}let{tracker:R,txKey:h}=f.checkTransactionsTracker({actionTxKey:P,connectorType:u,tracker:m,gelatoApiKey:p}),O={...g,connectorType:u,from:k,tracker:R||r,chainId:setChainId(c),localTimestamp:K,txKey:h,hash:R==="ethereum"?P:void 0,pending:!1,isTrackedModalOpen:l.withTrackedModal};n().addTxToPool(O),e(L=>produce(L,I=>{I.initialTx&&(I.initialTx.isInitializing=!1,I.initialTx.lastTxKey=h);}));let z=n().transactionsPool[h];await f.checkAndInitializeTrackerInStore({tx:z,onSuccess:d,onError:x,onReplaced:S,gelatoApiKey:p,...n()});}catch(u){throw w(u),u}}}),{...a}))}var we=(o=>t=>useStore(o,t));var V=5e3,X=10;function Ee(o){let{tx:t,fetcher:s,onInitialize:p,onSuccess:a,onFailure:e,onIntervalTick:n,onReplaced:r,removeTxFromPool:i,pollingInterval:l=V,maxRetries:T=X}=o;if(!t.pending)return;p?.();let c=T,m=true,g=x=>{m&&(m=false,i&&!x?.withoutRemoving&&i(t.txKey));};(async()=>{for(;m&&c>0;)try{if(await new Promise(x=>setTimeout(x,l)),!m)break;await s({tx:t,stopPolling:g,onSuccess:a,onFailure:e,onIntervalTick:n,onReplaced:r});}catch(x){console.error(`Polling fetcher for txKey ${t.txKey} threw an error:`,x),c--;}c<=0&&(console.warn(`Polling for txKey ${t.txKey} stopped after reaching the maximum number of retries.`),e(),g());})();}export{A as TransactionStatus,N as TransactionTracker,we as createBoundedUseStore,Ae as createPulsarStore,Te as createTxInMemoryStore,Ee as initializePollingTracker,E as initializeTxTrackingStore,F as selectAllTransactions,B as selectAllTransactionsByActiveWallet,Y as selectPendingTransactions,ee as selectPendingTransactionsByActiveWallet,Z as selectTxByKey};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/pulsar-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
@@ -40,18 +40,18 @@
     }
   ],
   "peerDependencies": {
-    "@tuwaio/orbit-core": ">=0.2.7",
+    "@tuwaio/orbit-core": ">=0.2.8",
     "dayjs": "1.x.x",
     "immer": "11.x.x",
     "zustand": "5.x.x"
   },
   "devDependencies": {
-    "@tuwaio/orbit-core": "^0.2.7",
-    "dayjs": "^1.11.19",
-    "immer": "^11.1.3",
+    "@tuwaio/orbit-core": "^0.2.8",
+    "dayjs": "^1.11.20",
+    "immer": "^11.1.4",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "zustand": "^5.0.11"
+    "typescript": "^6.0.3",
+    "zustand": "^5.0.12"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",