graz 0.4.0 → 0.4.2

package/dist/index.d.mts

@@ -1,14 +1,14 @@
 /// <reference types="../types/global" />
 import { DirectSignResponse, OfflineDirectSigner, Coin } from '@cosmjs/proto-signing';
 import { Key as Key$1, Keplr, ChainInfo, KeplrSignOptions, KeplrIntereactionOptions, OfflineAminoSigner as OfflineAminoSigner$1, AppCurrency } from '@keplr-wallet/types';
-import { OfflineAminoSigner, StdSignDoc, AminoSignResponse, StdSignature } from '@cosmjs/amino';
+import { OfflineAminoSigner } from '@cosmjs/amino';
 import { WalletConnectModalConfig } from '@walletconnect/modal';
 import { SignClientTypes } from '@walletconnect/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryResult } from '@tanstack/react-query';
 import { ParaWeb } from '@getpara/web-sdk';
 export { ParaWeb } from '@getpara/web-sdk';
-import { ParaGrazConfig as ParaGrazConfig$1 } from '@getpara/graz-connector';
+import { ParaGrazConfig as ParaGrazConfig$1, ParaGrazConnector } from '@getpara/graz-connector';
 import * as _cosmjs_cosmwasm_stargate from '@cosmjs/cosmwasm-stargate';
 import { SigningCosmWasmClient, InstantiateOptions, CosmWasmClient, InstantiateResult, ExecuteResult, SigningCosmWasmClientOptions } from '@cosmjs/cosmwasm-stargate';
 import { SigningStargateClient, StdFee, DeliverTxResponse, QueryClient, StakingExtension, StargateClient, SigningStargateClientOptions } from '@cosmjs/stargate';
@@ -127,6 +127,92 @@ interface SuggestChainAndConnectArgs {
 }
 declare const suggestChainAndConnect: (args: SuggestChainAndConnectArgs) => Promise<ConnectResult>;
 
+/**
+ * Logger types and interfaces for Graz
+ */
+declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3,
+    TRACE = 4
+}
+declare enum LogCategory {
+    WALLET = "wallet",// Wallet connections, disconnections
+    TRANSACTION = "transaction",// Transaction signing and broadcasting
+    QUERY = "query",// Blockchain queries
+    STORE = "store",// State management
+    MULTICHAIN = "multichain",// Multi-chain operations
+    EVENT = "event",// Wallet events
+    PERFORMANCE = "performance"
+}
+/**
+ * Error reporter interface for integration with error tracking services
+ * (e.g., Sentry, custom error tracking)
+ */
+interface ErrorReporter {
+    captureException: (error: Error, context?: {
+        category?: string;
+        context?: Record<string, unknown>;
+    }) => void;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerOptions {
+    /**
+     * Enable/disable logging
+     * @default true in development, false in production
+     */
+    enabled?: boolean;
+    /**
+     * Log level configuration:
+     * - Single LogLevel: Minimum level (e.g., LogLevel.INFO logs INFO, WARN, ERROR)
+     * - Array of LogLevel: Only log these specific levels
+     * - undefined/not specified: Log all levels
+     * @default undefined (all levels)
+     */
+    level?: LogLevel | LogLevel[];
+    /**
+     * Categories to log:
+     * - Array of categories: Only log these specific categories
+     * - Empty array or undefined: Log all categories
+     * @default undefined (all categories)
+     */
+    categories?: (keyof typeof LogCategory)[];
+    /**
+     * Optional error reporter for error tracking integration
+     */
+    errorReporter?: ErrorReporter;
+}
+/**
+ * Logger interface
+ */
+interface Logger {
+    error(category: LogCategory, message: string, context?: Record<string, unknown>): void;
+    warn(category: LogCategory, message: string, context?: Record<string, unknown>): void;
+    info(category: LogCategory, message: string, context?: Record<string, unknown>): void;
+    debug(category: LogCategory, message: string, context?: Record<string, unknown>): void;
+    trace(category: LogCategory, message: string, context?: Record<string, unknown>): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+    group(label: string): void;
+    groupEnd(): void;
+    setLevel(level: LogLevel | LogLevel[] | undefined): void;
+    setCategories(categories: (keyof typeof LogCategory)[] | undefined): void;
+    enable(): void;
+    disable(): void;
+}
+/**
+ * Global window extensions for Graz debugging
+ */
+declare global {
+    interface Window {
+        __GRAZ_DEBUG__?: boolean;
+        grazErrorReporter?: ErrorReporter;
+    }
+}
+
 /**
  * Para wallet entity (compatible with Wallet from @getpara/core-sdk)
  * Represents a wallet within the Para ecosystem (different from Graz Wallet)
@@ -196,10 +282,10 @@ interface ParaGrazConfig {
      */
     noModal?: boolean;
     /**
-     * Optional connector class constructor to use instead of default
-     * Allows for custom Para connector implementations
+     * Required connector class constructor
+     * Must be provided to use Para wallet functionality
      */
-    connectorClass?: new (config: ParaGrazConfig, chains?: ChainInfo[] | null) => ParaGrazConnector;
+    connectorClass: new (config: ParaGrazConfig, chains?: ChainInfo[] | null) => ParaGrazConnector;
     /**
      * Props for customizing the Para modal appearance and behavior
      * Only used when using @getpara/graz-integration with modal support
@@ -212,72 +298,6 @@ interface ParaGrazConfig {
      */
     queryClient?: _tanstack_react_query.QueryClient;
 }
-/**
- * Para wallet connector interface
- * Implements the Graz Wallet interface with Para-specific methods
- */
-interface ParaGrazConnector extends Omit<Wallet, "experimentalSuggestChain"> {
-    /**
-     * Enable connection to one or more chains
-     * @param chainIds - Single chain ID or array of chain IDs
-     */
-    enable(chainIds: string | string[]): Promise<void>;
-    /**
-     * Disconnect from Para wallet
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Get the Para Web SDK client instance
-     */
-    getParaWebClient(): ParaWeb;
-    /**
-     * Get the connector configuration
-     */
-    getConfig(): ParaGrazConfig;
-    /**
-     * Get account key for a specific chain
-     * @param chainId - The chain identifier
-     */
-    getKey(chainId: string): Promise<Key>;
-    /**
-     * Get offline signer that only supports Amino signing
-     * @param chainId - The chain identifier
-     */
-    getOfflineSignerOnlyAmino(chainId: string): OfflineAminoSigner;
-    /**
-     * Get hybrid offline signer supporting both Amino and Direct signing
-     * @param chainId - The chain identifier
-     */
-    getOfflineSigner(chainId: string): OfflineAminoSigner & OfflineDirectSigner;
-    /**
-     * Get offline signer, automatically choosing between Amino and Direct
-     * @param chainId - The chain identifier
-     */
-    getOfflineSignerAuto(chainId: string): Promise<OfflineAminoSigner | OfflineDirectSigner>;
-    /**
-     * Sign transaction using Amino format
-     * @param chainId - The chain identifier
-     * @param signer - The signer address
-     * @param signDoc - The Amino sign document
-     * @param signOptions - Optional signing options
-     */
-    signAmino(chainId: string, signer: string, signDoc: StdSignDoc, signOptions?: KeplrSignOptions): Promise<AminoSignResponse>;
-    /**
-     * Sign transaction using Direct/Protobuf format
-     * @param chainId - The chain identifier
-     * @param signer - The signer address
-     * @param signDoc - The Direct sign document
-     * @param signOptions - Optional signing options
-     */
-    signDirect(chainId: string, signer: string, signDoc: SignDoc, signOptions?: KeplrSignOptions): Promise<DirectSignResponse>;
-    /**
-     * Sign arbitrary data
-     * @param chainId - The chain identifier
-     * @param signer - The signer address
-     * @param data - Data to sign (string or bytes)
-     */
-    signArbitrary(chainId: string, signer: string, data: string | Uint8Array): Promise<StdSignature>;
-}
 
 interface ChainConfig {
     path?: string;
@@ -324,6 +344,14 @@ interface GrazInternalStore {
      * Interval in milliseconds to ping the wallet.
      */
     pingInterval: number;
+    /**
+     * Logger configuration
+     */
+    loggerConfig: {
+        enabled: boolean;
+        level?: LogLevel | LogLevel[];
+        categories?: (keyof typeof LogCategory)[];
+    } | null;
     _notFoundFn: () => void;
     _reconnect: boolean;
     _reconnectConnector: WalletType | null;
@@ -354,6 +382,14 @@ interface ConfigureGrazArgs {
      */
     iframeOptions?: IframeOptions;
     pingInteval?: number;
+    /**
+     * Logger configuration
+     */
+    logger?: {
+        enabled?: boolean;
+        level?: LogLevel | LogLevel[] | undefined;
+        categories?: (keyof typeof LogCategory)[] | undefined;
+    };
 }
 declare const configureGraz: (args: ConfigureGrazArgs) => ConfigureGrazArgs;
 
@@ -440,6 +476,88 @@ declare const isLeapDappBrowser: () => boolean;
 declare const isWalletConnect: (type: WalletType) => boolean;
 declare const isPara: (type: WalletType) => type is WalletType.PARA;
 
+/**
+ * Logger Categories
+ * Used for categorizing logs throughout the Graz library
+ */
+declare const LOG_CATEGORIES: {
+    /** Wallet connections, disconnections, and adapter operations */
+    readonly WALLET: "wallet";
+    /** Transaction signing and broadcasting */
+    readonly TRANSACTION: "transaction";
+    /** Blockchain queries (balance, contract queries, etc.) */
+    readonly QUERY: "query";
+    /** State management operations (store updates) */
+    readonly STORE: "store";
+    /** Multi-chain parallel operations */
+    readonly MULTICHAIN: "multichain";
+    /** Wallet events and listeners */
+    readonly EVENT: "event";
+    /** Performance metrics and timing */
+    readonly PERFORMANCE: "performance";
+};
+/**
+ * Logger Function Names
+ * Action/method function names used in logging context
+ */
+declare const LOG_FUNCTIONS: {
+    readonly CONNECT: "connect";
+    readonly DISCONNECT: "disconnect";
+    readonly RECONNECT: "reconnect";
+    readonly GET_WALLET: "getWallet";
+    readonly CLEAR_RECENT_CHAIN: "clearRecentChain";
+    readonly GET_RECENT_CHAIN_IDS: "getRecentChainIds";
+    readonly GET_RECENT_CHAINS: "getRecentChains";
+    readonly GET_CHAIN_INFO: "getChainInfo";
+    readonly GET_CHAIN_INFOS: "getChainInfos";
+    readonly ADD_CHAIN: "addChain";
+    readonly SUGGEST_CHAIN: "suggestChain";
+    readonly SUGGEST_CHAIN_AND_CONNECT: "suggestChainAndConnect";
+    readonly SEND_TOKENS: "sendTokens";
+    readonly SEND_IBC_TOKENS: "sendIbcTokens";
+    readonly INSTANTIATE_CONTRACT: "instantiateContract";
+    readonly EXECUTE_CONTRACT: "executeContract";
+    readonly GET_QUERY_SMART: "getQuerySmart";
+    readonly GET_QUERY_RAW: "getQueryRaw";
+    readonly CREATE_MULTI_CHAIN_ASYNC_FUNCTION: "createMultiChainAsyncFunction";
+    readonly HANDLE_FOCUS: "handleFocus";
+    readonly AUTO_CONNECT_IFRAME: "autoConnectIframe";
+    readonly RECONNECT_EFFECT: "reconnectEffect";
+    readonly SUBSCRIPTION: "subscription";
+};
+/**
+ * Logger Hook Names
+ * React hook names used in logging context
+ */
+declare const LOG_HOOKS: {
+    readonly USE_CONNECT: "useConnect";
+    readonly USE_DISCONNECT: "useDisconnect";
+    readonly USE_CHECK_WALLET: "useCheckWallet";
+    readonly USE_ADD_CHAIN: "useAddChain";
+    readonly USE_SUGGEST_CHAIN: "useSuggestChain";
+    readonly USE_SUGGEST_CHAIN_AND_CONNECT: "useSuggestChainAndConnect";
+    readonly USE_STARGATE_CLIENT: "useStargateClient";
+    readonly USE_COSMWASM_CLIENT: "useCosmWasmClient";
+    readonly USE_STARGATE_SIGNING_CLIENT: "useStargateSigningClient";
+    readonly USE_COSMWASM_SIGNING_CLIENT: "useCosmWasmSigningClient";
+    readonly USE_SEND_TOKENS: "useSendTokens";
+    readonly USE_SEND_IBC_TOKENS: "useSendIbcTokens";
+    readonly USE_INSTANTIATE_CONTRACT: "useInstantiateContract";
+    readonly USE_EXECUTE_CONTRACT: "useExecuteContract";
+};
+
+/**
+ * Get the singleton logger instance
+ * @returns Logger instance
+ */
+declare const getLogger: () => Logger;
+/**
+ * Configure the logger with custom options
+ * This will recreate the logger instance with new options
+ * @param options Logger configuration options
+ */
+declare const configureLogger: (options: LoggerOptions) => void;
+
 type CactusCosmosWallet = Pick<Keplr, "enable" | "getOfflineSigner" | "signDirect" | "signAmino" | "signArbitrary" | "getKey">;
 declare const getCactusCosmos: () => Wallet;
 
@@ -867,7 +985,7 @@ declare const useDisconnect: ({ onError, onLoading, onSuccess }?: MutationEventA
 declare function useOfflineSigners<const TChainIds extends readonly string[]>(args: {
     chainId: TChainIds;
 }): UseMultiChainQueryResult<TChainIds, OfflineSigners>;
-declare function useOfflineSigners(args?: {}): UseMultiChainQueryResult<undefined, OfflineSigners>;
+declare function useOfflineSigners(args?: Record<string, never>): UseMultiChainQueryResult<undefined, OfflineSigners>;
 /**
  * graz query hook to retrieve staked balance for a specific chain and address.
  *
@@ -1752,11 +1870,20 @@ interface GrazProviderProps {
  * Graz uses `@tanstack/react-query`'s features under the hood, hence you need to wrap `GrazProvider` with `QueryClientProvider`.
  * @example
  * ```tsx
+ * import { GrazProvider, LogLevel } from "graz";
+ *
  * // example next.js application in _app.tsx
  * export default function CustomApp({ Component, pageProps }: AppProps) {
  *   return (
  *     <QueryClientProvider queryClient={queryClient}>
- *       <GrazProvider grazOptions={grazOptions}>
+ *       <GrazProvider grazOptions={{
+ *         chains: [cosmoshubChainInfo, osmosisChainInfo],
+ *         logger: {
+ *           enabled: true,
+ *           level: LogLevel.DEBUG,
+ *           categories: ['wallet', 'transaction'],
+ *         }
+ *       }}>
  *         <Component {...pageProps} />
  *       </GrazProvider>
  *     </QueryClientProvider>
@@ -1781,4 +1908,4 @@ declare const useGrazEvents: () => null;
  */
 declare const GrazEvents: FC;
 
-export { type ActionChainId, type AddChainArgs, type CactusCosmosWallet, type ConfigureGrazArgs, type ConnectArgs, type ConnectResult, type Dictionary, type ExecuteContractArgs, type ExecuteContractMutationArgs, GrazEvents, GrazProvider, type GrazProviderProps, type InstantiateContractArgs, type InstantiateContractMutationArgs, type Key, type KnownKeys, type Maybe, type OfflineSigners, type ParaGrazConfig, type ParaGrazConnector, type ParaGrazConnectorEvents, type ParaModalProps, type ParaWallet, type ReconnectArgs, type SendIbcTokensArgs, type SendTokensArgs, type SignAminoParams, type SignDirectParams, type SignDoc, type SuggestChainAndConnectArgs, type SuggestChainArgs, type UseAccountArgs, type UseAccountResult, type UseAddChainArgs, type UseConnectChainArgs, type UseExecuteContractArgs, type UseInstantiateContractArgs, type UseSuggestChainAndConnectArgs, type UseSuggestChainArgs, WALLET_TYPES, type Wallet, WalletType, addChain, checkWallet, clearRecentChain, clearSession, configureGraz, connect, defineChainInfo, defineChains, disconnect, executeContract, getAvailableWallets, getCactusCosmos, getChainInfo, getChainInfos, getCosmostation, getKeplr, getLeap, getMetamaskSnapLeap, getOfflineSigners, getOkx, getPara, getQueryRaw, getQuerySmart, getRecentChainIds, getRecentChains, getVectis, getWCCosmostation, getWCKeplr, getWCLeap, getWallet, getWalletConnect, instantiateContract, isLeapDappBrowser, isLeapSnaps, isPara, isWalletConnect, reconnect, sendIbcTokens, sendTokens, suggestChain, suggestChainAndConnect, useAccount, useActiveChainCurrency, useActiveChainIds, useActiveChains, useActiveWalletType, useAddChain, useBalance, useBalanceStaked, useBalances, useChainInfo, useChainInfos, useCheckWallet, useConnect, useCosmWasmClient, useCosmWasmSigningClient, useDisconnect, useExecuteContract, useGrazEvents, useInstantiateContract, useOfflineSigners, useQueryClientValidators, useQueryRaw, useQuerySmart, useRecentChainIds, useRecentChains, useSendIbcTokens, useSendTokens, useStargateClient, useStargateSigningClient, useSuggestChain, useSuggestChainAndConnect };
+export { type ActionChainId, type AddChainArgs, type CactusCosmosWallet, type ConfigureGrazArgs, type ConnectArgs, type ConnectResult, type Dictionary, type ErrorReporter, type ExecuteContractArgs, type ExecuteContractMutationArgs, GrazEvents, GrazProvider, type GrazProviderProps, type InstantiateContractArgs, type InstantiateContractMutationArgs, type Key, type KnownKeys, LOG_CATEGORIES, LOG_FUNCTIONS, LOG_HOOKS, LogCategory, LogLevel, type Logger, type LoggerOptions, type Maybe, type OfflineSigners, type ParaGrazConfig, type ParaGrazConnectorEvents, type ParaModalProps, type ParaWallet, type ReconnectArgs, type SendIbcTokensArgs, type SendTokensArgs, type SignAminoParams, type SignDirectParams, type SignDoc, type SuggestChainAndConnectArgs, type SuggestChainArgs, type UseAccountArgs, type UseAccountResult, type UseAddChainArgs, type UseConnectChainArgs, type UseExecuteContractArgs, type UseInstantiateContractArgs, type UseSuggestChainAndConnectArgs, type UseSuggestChainArgs, WALLET_TYPES, type Wallet, WalletType, addChain, checkWallet, clearRecentChain, clearSession, configureGraz, configureLogger, connect, defineChainInfo, defineChains, disconnect, executeContract, getAvailableWallets, getCactusCosmos, getChainInfo, getChainInfos, getCosmostation, getKeplr, getLeap, getLogger, getMetamaskSnapLeap, getOfflineSigners, getOkx, getPara, getQueryRaw, getQuerySmart, getRecentChainIds, getRecentChains, getVectis, getWCCosmostation, getWCKeplr, getWCLeap, getWallet, getWalletConnect, instantiateContract, isLeapDappBrowser, isLeapSnaps, isPara, isWalletConnect, reconnect, sendIbcTokens, sendTokens, suggestChain, suggestChainAndConnect, useAccount, useActiveChainCurrency, useActiveChainIds, useActiveChains, useActiveWalletType, useAddChain, useBalance, useBalanceStaked, useBalances, useChainInfo, useChainInfos, useCheckWallet, useConnect, useCosmWasmClient, useCosmWasmSigningClient, useDisconnect, useExecuteContract, useGrazEvents, useInstantiateContract, useOfflineSigners, useQueryClientValidators, useQueryRaw, useQuerySmart, useRecentChainIds, useRecentChains, useSendIbcTokens, useSendTokens, useStargateClient, useStargateSigningClient, useSuggestChain, useSuggestChainAndConnect };