@movebridge/core 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,602 @@
+import { Aptos } from '@aptos-labs/ts-sdk';
+import EventEmitter from 'eventemitter3';
+
+/**
+ * @movebridge/core - Type definitions
+ */
+/** Supported network types */
+type NetworkType = 'mainnet' | 'testnet';
+/** Supported wallet types for Movement Network */
+type WalletType = 'petra' | 'pontem' | 'nightly';
+/** Configuration options for Movement client */
+interface MovementConfig {
+    /** Network to connect to */
+    network: NetworkType;
+    /** Custom RPC URL (overrides network default) */
+    rpcUrl?: string;
+    /** Custom indexer URL (overrides network default) */
+    indexerUrl?: string;
+    /** Auto-connect to previously connected wallet */
+    autoConnect?: boolean;
+}
+/** Network-specific configuration */
+interface NetworkConfig {
+    chainId: number;
+    rpcUrl: string;
+    indexerUrl: string | null;
+    explorerUrl: string;
+    faucetUrl?: string;
+}
+/** Account resource from blockchain */
+interface Resource {
+    type: string;
+    data: Record<string, unknown>;
+}
+/** Transaction data */
+interface Transaction {
+    hash: string;
+    sender: string;
+    sequenceNumber: string;
+    payload: TransactionPayload;
+    timestamp: string;
+}
+/** Transaction response after confirmation */
+interface TransactionResponse {
+    hash: string;
+    success: boolean;
+    vmStatus: string;
+    gasUsed: string;
+    events: ContractEvent[];
+}
+/** Transaction payload for entry functions */
+interface TransactionPayload {
+    type: 'entry_function_payload';
+    function: string;
+    typeArguments: string[];
+    arguments: unknown[];
+}
+/** Signed transaction ready for submission */
+interface SignedTransaction {
+    payload: TransactionPayload;
+    signature: string;
+    sender: string;
+}
+/** Contract event data */
+interface ContractEvent {
+    type: string;
+    sequenceNumber: string;
+    data: Record<string, unknown>;
+}
+/** Wallet connection state */
+interface WalletState {
+    connected: boolean;
+    address: string | null;
+    publicKey: string | null;
+}
+/** Wallet event handlers */
+interface WalletEvents {
+    connect: (address: string) => void;
+    disconnect: () => void;
+    accountChanged: (newAddress: string) => void;
+    networkChanged: (network: string) => void;
+}
+/** Options for token transfer */
+interface TransferOptions {
+    to: string;
+    amount: string;
+    coinType?: string;
+}
+/** Options for building transactions */
+interface BuildOptions {
+    function: string;
+    typeArguments: string[];
+    arguments: unknown[];
+}
+/** Options for creating contract interface */
+interface ContractOptions {
+    address: string;
+    module: string;
+}
+/** Event subscription configuration */
+interface EventSubscription {
+    eventHandle: string;
+    callback: (event: ContractEvent) => void;
+}
+
+/**
+ * @movebridge/core - Wallet Manager
+ * Handles wallet detection, connection, and state management
+ * Uses Aptos Wallet Standard (AIP-62) for wallet interactions
+ */
+
+interface UnifiedWalletAdapter {
+    name: string;
+    icon: string;
+    connect(): Promise<{
+        address: string;
+        publicKey: string;
+    }>;
+    disconnect(): Promise<void>;
+    signAndSubmitTransaction(payload: any): Promise<{
+        hash: string;
+    }>;
+    signTransaction(payload: any): Promise<Uint8Array>;
+    onAccountChange(cb: (account: {
+        address: string;
+        publicKey: string;
+    } | null) => void): void;
+    onNetworkChange(cb: (network: string) => void): void;
+}
+declare class WalletManager extends EventEmitter<WalletEvents> {
+    private state;
+    private currentWallet;
+    private adapter;
+    private standardWallets;
+    private detectedWallets;
+    private unsubscribe;
+    detectWallets(): WalletType[];
+    getWalletInfo(): Array<{
+        type: WalletType;
+        name: string;
+        icon: string;
+    }>;
+    connect(wallet: WalletType): Promise<void>;
+    disconnect(): Promise<void>;
+    getState(): WalletState;
+    getWallet(): WalletType | null;
+    getAdapter(): UnifiedWalletAdapter | null;
+    autoConnect(): Promise<void>;
+    destroy(): void;
+    private setupEventListeners;
+    private saveLastWallet;
+    private getLastWallet;
+    private clearLastWallet;
+}
+
+/**
+ * @movebridge/core - Transaction Builder
+ * Constructs, signs, and submits transactions
+ */
+
+/**
+ * Transaction Builder
+ * Provides methods for building, signing, and submitting transactions
+ *
+ * @example
+ * ```typescript
+ * // Transfer tokens
+ * const tx = await movement.transaction.transfer({
+ *   to: '0x123...',
+ *   amount: '1000000',
+ * });
+ *
+ * // Build custom transaction
+ * const tx = await movement.transaction.build({
+ *   function: '0x1::coin::transfer',
+ *   typeArguments: ['0x1::aptos_coin::AptosCoin'],
+ *   arguments: ['0x123...', '1000000'],
+ * });
+ *
+ * // Sign and submit
+ * const signed = await movement.transaction.sign(tx);
+ * const hash = await movement.transaction.submit(signed);
+ * ```
+ */
+declare class TransactionBuilder {
+    private readonly aptosClient;
+    private readonly walletManager;
+    constructor(aptosClient: Aptos, walletManager: WalletManager);
+    /**
+     * Builds a transfer transaction payload
+     * @param options - Transfer options
+     * @returns Transaction payload
+     */
+    transfer(options: TransferOptions): Promise<TransactionPayload>;
+    /**
+     * Builds a generic transaction payload
+     * @param options - Build options
+     * @returns Transaction payload
+     */
+    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
+     * @param payload - Transaction payload
+     * @returns Transaction hash
+     */
+    signAndSubmit(payload: TransactionPayload): Promise<string>;
+    /**
+     * Simulates a transaction without submitting
+     * @param payload - Transaction payload
+     * @returns Simulation result with gas estimate
+     */
+    simulate(payload: TransactionPayload): Promise<{
+        success: boolean;
+        gasUsed: string;
+        vmStatus: string;
+    }>;
+}
+
+/**
+ * @movebridge/core - Contract Interface
+ * Simplified interface for contract interactions
+ */
+
+/**
+ * Contract Interface
+ * Provides simplified methods for interacting with Move modules
+ *
+ * @example
+ * ```typescript
+ * const contract = movement.contract({
+ *   address: '0x123...',
+ *   module: 'counter',
+ * });
+ *
+ * // Read (view function)
+ * const count = await contract.view('get_count', []);
+ *
+ * // Write (entry function)
+ * const txHash = await contract.call('increment', []);
+ * ```
+ */
+declare class ContractInterface {
+    private readonly aptosClient;
+    private readonly walletManager;
+    /** Contract address */
+    readonly address: string;
+    /** Module name */
+    readonly module: string;
+    constructor(aptosClient: Aptos, walletManager: WalletManager, options: ContractOptions);
+    /**
+     * Calls a view function (read-only)
+     * @param functionName - Name of the view function
+     * @param args - Function arguments
+     * @param typeArgs - Type arguments (optional)
+     * @returns Function result
+     * @throws MovementError with code VIEW_FUNCTION_FAILED if call fails
+     */
+    view<T = unknown>(functionName: string, args: unknown[], typeArgs?: string[]): Promise<T>;
+    /**
+     * Calls an entry function (write operation)
+     * @param functionName - Name of the entry function
+     * @param args - Function arguments
+     * @param typeArgs - Type arguments (optional)
+     * @returns Transaction hash
+     * @throws MovementError with code WALLET_NOT_CONNECTED if no wallet is connected
+     * @throws MovementError with code TRANSACTION_FAILED if transaction fails
+     */
+    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>')
+     * @returns true if resource exists
+     */
+    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
+     */
+    getResource<T = unknown>(resourceType: string): Promise<T | null>;
+    /**
+     * Gets the full function name for a function in this module
+     * @param functionName - Function name
+     * @returns Full function name (address::module::function)
+     */
+    getFullFunctionName(functionName: string): string;
+}
+
+/**
+ * @movebridge/core - Event Listener
+ * Subscribes to and handles contract events
+ */
+
+/**
+ * Event Listener
+ * Manages event subscriptions and polling
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to events
+ * const subscriptionId = movement.events.subscribe({
+ *   eventHandle: '0x123::counter::CounterChanged',
+ *   callback: (event) => {
+ *     console.log('Counter changed:', event);
+ *   },
+ * });
+ *
+ * // Unsubscribe
+ * movement.events.unsubscribe(subscriptionId);
+ * ```
+ */
+declare class EventListener {
+    private readonly aptosClient;
+    private subscriptions;
+    private subscriptionCounter;
+    private readonly pollIntervalMs;
+    constructor(aptosClient: Aptos, options?: {
+        pollIntervalMs?: number;
+    });
+    /**
+     * Subscribes to contract events
+     * @param subscription - Subscription configuration
+     * @returns Subscription ID
+     * @throws MovementError with code INVALID_EVENT_HANDLE if event handle is invalid
+     */
+    subscribe(subscription: EventSubscription): string;
+    /**
+     * Unsubscribes from events
+     * @param subscriptionId - Subscription ID to remove
+     */
+    unsubscribe(subscriptionId: string): void;
+    /**
+     * Unsubscribes from all events
+     */
+    unsubscribeAll(): void;
+    /**
+     * Gets active subscription count
+     * @returns Number of active subscriptions
+     */
+    getSubscriptionCount(): number;
+    /**
+     * Checks if a subscription exists
+     * @param subscriptionId - Subscription ID
+     * @returns true if subscription exists
+     */
+    hasSubscription(subscriptionId: string): boolean;
+    /**
+     * Polls for new events
+     * @param subscriptionId - Subscription ID
+     */
+    private pollEvents;
+}
+
+/**
+ * @movebridge/core - Movement Client
+ * Main entry point for SDK interactions
+ */
+
+/**
+ * Resolved configuration with all URLs
+ */
+interface ResolvedConfig {
+    network: NetworkType;
+    chainId: number;
+    rpcUrl: string;
+    indexerUrl: string | null;
+    explorerUrl: string;
+    autoConnect: boolean;
+}
+/**
+ * Movement SDK client
+ * Provides unified interface for Movement Network interactions
+ *
+ * @example
+ * ```typescript
+ * import { Movement } from '@movebridge/core';
+ *
+ * const movement = new Movement({ network: 'testnet' });
+ *
+ * // Get account balance
+ * const balance = await movement.getAccountBalance('0x1');
+ *
+ * // Connect wallet
+ * await movement.wallet.connect('petra');
+ * ```
+ */
+declare class Movement {
+    /** Resolved configuration */
+    readonly config: ResolvedConfig;
+    /** Aptos SDK client instance */
+    private readonly aptosClient;
+    /** Wallet manager instance */
+    readonly wallet: WalletManager;
+    /** Transaction builder instance */
+    readonly transaction: TransactionBuilder;
+    /** Event listener instance */
+    readonly events: EventListener;
+    /**
+     * Creates a new Movement client
+     * @param config - Configuration options
+     */
+    constructor(config: MovementConfig);
+    /**
+     * Gets the underlying Aptos client
+     * @returns Aptos SDK client instance
+     */
+    getAptosClient(): Aptos;
+    /**
+     * Gets the account balance for an address
+     * @param address - Account address
+     * @returns Balance as string in smallest unit (octas)
+     * @throws MovementError with code INVALID_ADDRESS if address is invalid
+     */
+    getAccountBalance(address: string): Promise<string>;
+    /**
+     * Gets all resources for an account
+     * @param address - Account address
+     * @returns Array of resources
+     * @throws MovementError with code INVALID_ADDRESS if address is invalid
+     */
+    getAccountResources(address: string): Promise<Resource[]>;
+    /**
+     * Gets a transaction by hash
+     * @param hash - Transaction hash
+     * @returns Transaction data
+     */
+    getTransaction(hash: string): Promise<Transaction>;
+    /**
+     * Waits for a transaction to be confirmed
+     * @param hash - Transaction hash
+     * @param options - Wait options
+     * @returns Transaction response
+     */
+    waitForTransaction(hash: string, options?: {
+        timeoutMs?: number;
+        checkIntervalMs?: number;
+    }): Promise<TransactionResponse>;
+    /**
+     * Creates a contract interface for interacting with a Move module
+     * @param options - Contract options
+     * @returns Contract interface
+     */
+    contract(options: ContractOptions): ContractInterface;
+}
+
+/**
+ * @movebridge/core - Network configuration
+ */
+
+/**
+ * Network configuration constants for Movement Network
+ */
+declare const NETWORK_CONFIG: Record<NetworkType, NetworkConfig>;
+/**
+ * Default coin type for native token transfers
+ */
+declare const DEFAULT_COIN_TYPE = "0x1::aptos_coin::AptosCoin";
+/**
+ * Resolves the full configuration from user options
+ * @param config - User-provided configuration
+ * @returns Resolved network configuration with all URLs
+ */
+declare function resolveConfig(config: MovementConfig): {
+    network: NetworkType;
+    chainId: number;
+    rpcUrl: string;
+    indexerUrl: string | null;
+    explorerUrl: string;
+    autoConnect: boolean;
+};
+/**
+ * Validates a Movement/Aptos address format
+ * @param address - Address to validate
+ * @returns true if valid, false otherwise
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Validates an event handle format
+ * @param eventHandle - Event handle to validate
+ * @returns true if valid, false otherwise
+ */
+declare function isValidEventHandle(eventHandle: string): boolean;
+/**
+ * Gets the explorer URL for a transaction
+ * @param network - Network type
+ * @param txHash - Transaction hash
+ * @returns Explorer URL for the transaction
+ */
+declare function getExplorerTxUrl(network: NetworkType, txHash: string): string;
+/**
+ * Gets the explorer URL for an account
+ * @param network - Network type
+ * @param address - Account address
+ * @returns Explorer URL for the account
+ */
+declare function getExplorerAccountUrl(network: NetworkType, address: string): string;
+
+/**
+ * @movebridge/core - Error handling
+ */
+/**
+ * Error codes for MovementError
+ */
+type ErrorCode = 'INVALID_ADDRESS' | 'WALLET_NOT_FOUND' | 'WALLET_CONNECTION_FAILED' | 'WALLET_NOT_CONNECTED' | 'TRANSACTION_FAILED' | 'TRANSACTION_TIMEOUT' | 'VIEW_FUNCTION_FAILED' | 'INVALID_EVENT_HANDLE' | 'NETWORK_ERROR' | 'ABI_FETCH_FAILED' | 'CODEGEN_FAILED' | 'INVALID_ARGUMENT';
+/**
+ * Error details - flexible record type for error context
+ */
+type ErrorDetails = Record<string, unknown>;
+/**
+ * Custom error class for MoveBridge SDK
+ * Provides structured error information with code, message, and details
+ */
+declare class MovementError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: ErrorDetails | undefined;
+    readonly name = "MovementError";
+    constructor(message: string, code: ErrorCode, details?: ErrorDetails | undefined);
+    /**
+     * Serializes the error to a JSON-compatible object
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Creates a string representation of the error
+     */
+    toString(): string;
+}
+/**
+ * Factory functions for creating common errors
+ */
+declare const Errors: {
+    /**
+     * Creates an invalid address error
+     */
+    invalidAddress(address: string, reason?: string): MovementError;
+    /**
+     * Creates a wallet not found error
+     */
+    walletNotFound(wallet: string, available: string[]): MovementError;
+    /**
+     * Creates a wallet connection failed error
+     */
+    walletConnectionFailed(wallet: string, originalError?: unknown): MovementError;
+    /**
+     * Creates a wallet not connected error
+     */
+    walletNotConnected(): MovementError;
+    /**
+     * Creates a transaction failed error
+     */
+    transactionFailed(hash: string, vmStatus: string, gasUsed?: string): MovementError;
+    /**
+     * Creates a transaction timeout error
+     */
+    transactionTimeout(hash: string): MovementError;
+    /**
+     * Creates a view function failed error
+     */
+    viewFunctionFailed(functionName: string, args: unknown[], originalError?: unknown): MovementError;
+    /**
+     * Creates an invalid event handle error
+     */
+    invalidEventHandle(eventHandle: string): MovementError;
+    /**
+     * Creates a network error
+     */
+    networkError(url: string, httpStatus?: number, responseBody?: unknown): MovementError;
+    /**
+     * Creates an ABI fetch failed error
+     */
+    abiFetchFailed(address: string, network: string, originalError?: unknown): MovementError;
+    /**
+     * Creates a codegen failed error
+     */
+    codegenFailed(reason: string, abi?: unknown): MovementError;
+    /**
+     * Creates an invalid argument error
+     */
+    invalidArgument(argument: string, reason: string): MovementError;
+};
+/**
+ * Type guard to check if an error is a MovementError
+ */
+declare function isMovementError(error: unknown): error is MovementError;
+/**
+ * Wraps an unknown error as a 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 };