@movebridge/core 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -37,7 +37,11 @@ interface Transaction {
     hash: string;
     sender: string;
     sequenceNumber: string;
-    payload: TransactionPayload;
+    payload: {
+        function: string;
+        typeArguments: string[];
+        functionArguments: unknown[];
+    };
     timestamp: string;
 }
 /** Transaction response after confirmation */
@@ -48,12 +52,14 @@ interface TransactionResponse {
     gasUsed: string;
     events: ContractEvent[];
 }
-/** Transaction payload for entry functions */
+/** Transaction payload for entry functions (AIP-62 compatible) */
 interface TransactionPayload {
-    type: 'entry_function_payload';
+    /** Entry function identifier: address::module::function */
     function: string;
+    /** Type arguments for generic functions */
     typeArguments: string[];
-    arguments: unknown[];
+    /** Function arguments */
+    functionArguments: unknown[];
 }
 /** Signed transaction ready for submission */
 interface SignedTransaction {
@@ -97,9 +103,20 @@ interface ContractOptions {
     address: string;
     module: string;
 }
-/** Event subscription configuration */
+/** Event subscription configuration (new format) */
 interface EventSubscription {
+    /** Account address to watch for events */
+    accountAddress: string;
+    /** Event type (e.g., '0x1::coin::DepositEvent') */
+    eventType: string;
+    /** Callback function when events are received */
+    callback: (event: ContractEvent) => void;
+}
+/** Legacy event subscription (backward compatible) */
+interface LegacyEventSubscription$1 {
+    /** Event handle in format: 0xADDRESS::module::EventType */
     eventHandle: string;
+    /** Callback function when events are received */
     callback: (event: ContractEvent) => void;
 }
 
@@ -109,6 +126,20 @@ interface EventSubscription {
  * Uses Aptos Wallet Standard (AIP-62) for wallet interactions
  */
 
+/**
+ * AIP-62 Transaction Payload format
+ */
+interface AIP62TransactionPayload {
+    payload: {
+        function: string;
+        typeArguments: string[];
+        functionArguments: unknown[];
+    };
+}
+/**
+ * Unified wallet adapter interface
+ * Abstracts different wallet implementations into a common interface
+ */
 interface UnifiedWalletAdapter {
     name: string;
     icon: string;
@@ -117,16 +148,38 @@ interface UnifiedWalletAdapter {
         publicKey: string;
     }>;
     disconnect(): Promise<void>;
-    signAndSubmitTransaction(payload: any): Promise<{
+    signAndSubmitTransaction(payload: AIP62TransactionPayload): Promise<{
         hash: string;
     }>;
-    signTransaction(payload: any): Promise<Uint8Array>;
+    signTransaction(payload: AIP62TransactionPayload): Promise<Uint8Array>;
     onAccountChange(cb: (account: {
         address: string;
         publicKey: string;
     } | null) => void): void;
     onNetworkChange(cb: (network: string) => void): void;
 }
+/**
+ * Wallet Manager
+ * Manages wallet detection, connection, and state
+ *
+ * @example
+ * ```typescript
+ * const walletManager = new WalletManager();
+ *
+ * // Detect available wallets
+ * const wallets = walletManager.detectWallets();
+ *
+ * // Connect to a wallet
+ * await walletManager.connect('razor');
+ *
+ * // Get current state
+ * const state = walletManager.getState();
+ * console.log(state.address);
+ *
+ * // Disconnect
+ * await walletManager.disconnect();
+ * ```
+ */
 declare class WalletManager extends EventEmitter<WalletEvents> {
     private state;
     private currentWallet;
@@ -134,18 +187,50 @@ declare class WalletManager extends EventEmitter<WalletEvents> {
     private standardWallets;
     private detectedWallets;
     private unsubscribe;
+    /**
+     * Detects available wallets using AIP-62 standard
+     * @returns Array of detected wallet types
+     */
     detectWallets(): WalletType[];
+    /**
+     * Gets detailed wallet information for UI display
+     * @returns Array of wallet info objects
+     */
     getWalletInfo(): Array<{
         type: WalletType;
         name: string;
         icon: string;
     }>;
+    /**
+     * Connects to a wallet
+     * @param wallet - Wallet type to connect to
+     * @throws MovementError if wallet not found or connection fails
+     */
     connect(wallet: WalletType): Promise<void>;
+    /**
+     * Disconnects from the current wallet
+     */
     disconnect(): Promise<void>;
+    /**
+     * Gets the current wallet state
+     */
     getState(): WalletState;
+    /**
+     * Gets the currently connected wallet type
+     */
     getWallet(): WalletType | null;
+    /**
+     * Gets the wallet adapter for direct access
+     * @internal
+     */
     getAdapter(): UnifiedWalletAdapter | null;
+    /**
+     * Attempts to auto-connect to the last used wallet
+     */
     autoConnect(): Promise<void>;
+    /**
+     * Cleans up resources
+     */
     destroy(): void;
     private setupEventListeners;
     private saveLastWallet;
@@ -155,7 +240,7 @@ declare class WalletManager extends EventEmitter<WalletEvents> {
 
 /**
  * @movebridge/core - Transaction Builder
- * Constructs, signs, and submits transactions
+ * Constructs, signs, and submits transactions using AIP-62 wallet standard
  */
 
 /**
@@ -164,22 +249,19 @@ declare class WalletManager extends EventEmitter<WalletEvents> {
  *
  * @example
  * ```typescript
- * // Transfer tokens
- * const tx = await movement.transaction.transfer({
+ * // Transfer tokens using aptos_account::transfer (recommended)
+ * const hash = await movement.transaction.transfer({
  *   to: '0x123...',
- *   amount: '1000000',
+ *   amount: '1000000', // in octas
  * });
  *
- * // Build custom transaction
- * const tx = await movement.transaction.build({
- *   function: '0x1::coin::transfer',
- *   typeArguments: ['0x1::aptos_coin::AptosCoin'],
+ * // Build and submit custom transaction
+ * const payload = await movement.transaction.build({
+ *   function: '0x1::aptos_account::transfer',
+ *   typeArguments: [],
  *   arguments: ['0x123...', '1000000'],
  * });
- *
- * // Sign and submit
- * const signed = await movement.transaction.sign(tx);
- * const hash = await movement.transaction.submit(signed);
+ * const hash = await movement.transaction.signAndSubmit(payload);
  * ```
  */
 declare class TransactionBuilder {
@@ -188,50 +270,51 @@ declare class TransactionBuilder {
     constructor(aptosClient: Aptos, walletManager: WalletManager);
     /**
      * Builds a transfer transaction payload
+     * Uses 0x1::aptos_account::transfer which handles account creation
      * @param options - Transfer options
-     * @returns Transaction payload
+     * @returns Transaction payload ready for signing
      */
     transfer(options: TransferOptions): Promise<TransactionPayload>;
     /**
      * Builds a generic transaction payload
-     * @param options - Build options
-     * @returns Transaction payload
+     * @param options - Build options with function, typeArguments, and arguments
+     * @returns Transaction payload ready for signing
      */
     build(options: BuildOptions): Promise<TransactionPayload>;
-    /**
-     * Signs a transaction payload
-     * @param payload - Transaction payload to sign
-     * @returns Signed transaction
-     * @throws MovementError with code WALLET_NOT_CONNECTED if no wallet is connected
-     */
-    sign(payload: TransactionPayload): Promise<SignedTransaction>;
-    /**
-     * Submits a signed transaction to the network
-     * @param signed - Signed transaction
-     * @returns Transaction hash
-     */
-    submit(signed: SignedTransaction): Promise<string>;
     /**
      * Signs and submits a transaction in one step
+     * This is the recommended method for most use cases
      * @param payload - Transaction payload
      * @returns Transaction hash
+     * @throws MovementError with code WALLET_NOT_CONNECTED if no wallet connected
+     * @throws MovementError with code TRANSACTION_FAILED if submission fails
+     *
+     * Note: Transaction failures do NOT affect wallet connection state.
+     * The wallet remains connected even if a transaction fails.
      */
     signAndSubmit(payload: TransactionPayload): Promise<string>;
     /**
      * Simulates a transaction without submitting
+     * Useful for gas estimation and checking if transaction will succeed
      * @param payload - Transaction payload
-     * @returns Simulation result with gas estimate
+     * @returns Simulation result with success status and gas estimate
      */
     simulate(payload: TransactionPayload): Promise<{
         success: boolean;
         gasUsed: string;
         vmStatus: string;
     }>;
+    /**
+     * Convenience method: Transfer and wait for confirmation
+     * @param options - Transfer options
+     * @returns Transaction hash
+     */
+    transferAndSubmit(options: TransferOptions): Promise<string>;
 }
 
 /**
  * @movebridge/core - Contract Interface
- * Simplified interface for contract interactions
+ * Simplified interface for Move module interactions
  */
 
 /**
@@ -241,15 +324,15 @@ declare class TransactionBuilder {
  * @example
  * ```typescript
  * const contract = movement.contract({
- *   address: '0x123...',
- *   module: 'counter',
+ *   address: '0x1',
+ *   module: 'coin',
  * });
  *
- * // Read (view function)
- * const count = await contract.view('get_count', []);
+ * // Read (view function) - no wallet needed
+ * const balance = await contract.view('balance', ['0x123...'], ['0x1::aptos_coin::AptosCoin']);
  *
- * // Write (entry function)
- * const txHash = await contract.call('increment', []);
+ * // Write (entry function) - requires connected wallet
+ * const txHash = await contract.call('transfer', ['0x456...', '1000000'], ['0x1::aptos_coin::AptosCoin']);
  * ```
  */
 declare class ContractInterface {
@@ -262,33 +345,67 @@ declare class ContractInterface {
     constructor(aptosClient: Aptos, walletManager: WalletManager, options: ContractOptions);
     /**
      * Calls a view function (read-only)
+     * View functions don't require a wallet connection
+     *
      * @param functionName - Name of the view function
      * @param args - Function arguments
-     * @param typeArgs - Type arguments (optional)
+     * @param typeArgs - Type arguments for generic functions
      * @returns Function result
      * @throws MovementError with code VIEW_FUNCTION_FAILED if call fails
-     */
-    view<T = unknown>(functionName: string, args: unknown[], typeArgs?: string[]): Promise<T>;
+     *
+     * @example
+     * ```typescript
+     * // Get coin balance
+     * const balance = await contract.view('balance', [address], ['0x1::aptos_coin::AptosCoin']);
+     *
+     * // Check if account exists
+     * const exists = await contract.view('exists_at', [address]);
+     * ```
+     */
+    view<T = unknown>(functionName: string, args?: unknown[], typeArgs?: string[]): Promise<T>;
     /**
      * Calls an entry function (write operation)
+     * Requires a connected wallet
+     *
      * @param functionName - Name of the entry function
      * @param args - Function arguments
-     * @param typeArgs - Type arguments (optional)
+     * @param typeArgs - Type arguments for generic functions
      * @returns Transaction hash
-     * @throws MovementError with code WALLET_NOT_CONNECTED if no wallet is connected
+     * @throws MovementError with code WALLET_NOT_CONNECTED if no wallet connected
      * @throws MovementError with code TRANSACTION_FAILED if transaction fails
-     */
-    call(functionName: string, args: unknown[], typeArgs?: string[]): Promise<string>;
+     *
+     * @example
+     * ```typescript
+     * // Transfer coins
+     * const txHash = await contract.call('transfer', [recipient, amount], ['0x1::aptos_coin::AptosCoin']);
+     *
+     * // Call a custom function
+     * const txHash = await contract.call('increment', []);
+     * ```
+     */
+    call(functionName: string, args?: unknown[], typeArgs?: string[]): Promise<string>;
     /**
      * Checks if a resource exists at the contract address
-     * @param resourceType - Full resource type (e.g., '0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>')
+     * @param resourceType - Full resource type
      * @returns true if resource exists
+     *
+     * @example
+     * ```typescript
+     * const hasCoin = await contract.hasResource('0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>');
+     * ```
      */
     hasResource(resourceType: string): Promise<boolean>;
     /**
      * Gets a resource from the contract address
      * @param resourceType - Full resource type
      * @returns Resource data or null if not found
+     *
+     * @example
+     * ```typescript
+     * const coinStore = await contract.getResource<{ coin: { value: string } }>(
+     *   '0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>'
+     * );
+     * ```
      */
     getResource<T = unknown>(resourceType: string): Promise<T | null>;
     /**
@@ -301,25 +418,46 @@ declare class ContractInterface {
 
 /**
  * @movebridge/core - Event Listener
- * Subscribes to and handles contract events
+ * Subscribes to and handles blockchain events via polling
  */
 
+/**
+ * Event subscription configuration
+ */
+interface EventSubscriptionConfig {
+    /** Account address to watch for events */
+    accountAddress: string;
+    /** Event type (e.g., '0x1::coin::DepositEvent') */
+    eventType: string;
+    /** Callback function when events are received */
+    callback: (event: ContractEvent) => void;
+}
+/**
+ * Legacy event subscription (for backward compatibility)
+ */
+interface LegacyEventSubscription {
+    /** Event handle in format: 0xADDRESS::module::EventType */
+    eventHandle: string;
+    /** Callback function when events are received */
+    callback: (event: ContractEvent) => void;
+}
 /**
  * Event Listener
- * Manages event subscriptions and polling
+ * Manages event subscriptions and polling for blockchain events
  *
  * @example
  * ```typescript
- * // Subscribe to events
- * const subscriptionId = movement.events.subscribe({
- *   eventHandle: '0x123::counter::CounterChanged',
+ * // Subscribe to deposit events for an account
+ * const subId = movement.events.subscribe({
+ *   accountAddress: '0x123...',
+ *   eventType: '0x1::coin::DepositEvent',
  *   callback: (event) => {
- *     console.log('Counter changed:', event);
+ *     console.log('Deposit received:', event.data);
  *   },
  * });
  *
- * // Unsubscribe
- * movement.events.unsubscribe(subscriptionId);
+ * // Unsubscribe when done
+ * movement.events.unsubscribe(subId);
  * ```
  */
 declare class EventListener {
@@ -331,12 +469,40 @@ declare class EventListener {
         pollIntervalMs?: number;
     });
     /**
-     * Subscribes to contract events
+     * Subscribes to blockchain events
+     * Supports both new format (accountAddress + eventType) and legacy format (eventHandle)
+     *
      * @param subscription - Subscription configuration
-     * @returns Subscription ID
-     * @throws MovementError with code INVALID_EVENT_HANDLE if event handle is invalid
-     */
-    subscribe(subscription: EventSubscription): string;
+     * @returns Subscription ID for unsubscribing
+     *
+     * @example
+     * ```typescript
+     * // New format (recommended)
+     * const subId = events.subscribe({
+     *   accountAddress: '0x1',
+     *   eventType: '0x1::coin::DepositEvent',
+     *   callback: (event) => console.log(event),
+     * });
+     *
+     * // Legacy format (backward compatible)
+     * const subId = events.subscribe({
+     *   eventHandle: '0x1::coin::DepositEvent',
+     *   callback: (event) => console.log(event),
+     * });
+     * ```
+     */
+    subscribe(subscription: EventSubscriptionConfig | LegacyEventSubscription): string;
+    /**
+     * Parses a legacy event handle into account address and event type
+     * @internal
+     */
+    private parseEventHandle;
+    /**
+     * Validates event type format
+     * Expected format: address::module::EventType
+     * @internal
+     */
+    private isValidEventType;
     /**
      * Unsubscribes from events
      * @param subscriptionId - Subscription ID to remove
@@ -358,10 +524,52 @@ declare class EventListener {
      */
     hasSubscription(subscriptionId: string): boolean;
     /**
-     * Polls for new events
-     * @param subscriptionId - Subscription ID
+     * Polls for new events for a subscription
+     * @internal
      */
     private pollEvents;
+    /**
+     * Fetches events from the blockchain
+     * Handles different API response formats and fallback methods
+     * @internal
+     */
+    private fetchEvents;
+    /**
+     * Fetches events using the event handle API
+     * @internal
+     */
+    private fetchEventsViaEventHandle;
+    /**
+     * Fetches events by checking account resources
+     * This is a fallback method when indexer is not available
+     * @internal
+     */
+    private fetchEventsViaResources;
+    /**
+     * Gets the fullnode URL from the Aptos client config
+     * @internal
+     */
+    private getFullnodeUrl;
+    /**
+     * Sorts events by sequence number in ascending order
+     * @internal
+     */
+    private sortEventsBySequence;
+    /**
+     * Parses sequence number from various formats
+     * @internal
+     */
+    private parseSequenceNumber;
+    /**
+     * Normalizes event data to a consistent format
+     * @internal
+     */
+    private normalizeEventData;
+    /**
+     * Safely invokes a callback without letting errors propagate
+     * @internal
+     */
+    private safeInvokeCallback;
 }
 
 /**
@@ -599,4 +807,4 @@ declare function isMovementError(error: unknown): error is MovementError;
  */
 declare function wrapError(error: unknown, code: ErrorCode, context?: string): MovementError;
 
-export { type BuildOptions, type ContractEvent, ContractInterface, type ContractOptions, DEFAULT_COIN_TYPE, type ErrorCode, type ErrorDetails, Errors, EventListener, type EventSubscription, Movement, type MovementConfig, MovementError, NETWORK_CONFIG, type NetworkConfig, type NetworkType, type ResolvedConfig, type Resource, type SignedTransaction, type Transaction, TransactionBuilder, type TransactionPayload, type TransactionResponse, type TransferOptions, type WalletEvents, WalletManager, type WalletState, type WalletType, getExplorerAccountUrl, getExplorerTxUrl, isMovementError, isValidAddress, isValidEventHandle, resolveConfig, wrapError };
+export { type BuildOptions, type ContractEvent, ContractInterface, type ContractOptions, DEFAULT_COIN_TYPE, type ErrorCode, type ErrorDetails, Errors, EventListener, type EventSubscription, type EventSubscriptionConfig, type LegacyEventSubscription$1 as LegacyEventSubscription, Movement, type MovementConfig, MovementError, NETWORK_CONFIG, type NetworkConfig, type NetworkType, type ResolvedConfig, type Resource, type SignedTransaction, type Transaction, TransactionBuilder, type TransactionPayload, type TransactionResponse, type TransferOptions, type WalletEvents, WalletManager, type WalletState, type WalletType, getExplorerAccountUrl, getExplorerTxUrl, isMovementError, isValidAddress, isValidEventHandle, resolveConfig, wrapError };