@awarizon/web3 1.0.0 → 1.0.2

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { Chain, WalletClient, Address, Abi, PublicClient } from 'viem';
+import { Chain, WalletClient, Address, Abi, PublicClient, Hex } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine } from '@awarizon/wallet-engine';
+import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ExternalWalletClient } from '@awarizon/wallet-engine';
 export { ChainSwitchError, InvalidMnemonicError, InvalidPrivateKeyError, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
+import { TransactionResult } from '@awarizon/tx-engine';
 export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
 export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
 
@@ -12,6 +13,12 @@ interface AwarizonConfig {
      *  - a viem Chain object: `import { base } from "viem/chains"`
      */
     chain: Chain | string;
+    /**
+     * Awarizon API key (required).
+     * Generate one at https://awarizon.com/dashboard/api-keys
+     * Format: "awz_live_..."
+     */
+    apiKey: string;
     /**
      * Optional RPC URL override.
      * If omitted, the chain's default public RPC endpoint is used.
@@ -19,9 +26,14 @@ interface AwarizonConfig {
     rpcUrl?: string;
     /**
      * Optional pre-connected external signer.
-     * Equivalent to calling `sdk.connectWallet(signer)` after construction.
+     * Equivalent to calling `awarizon.connectWallet(signer)` after construction.
      */
     signer?: WalletClient;
+    /**
+     * Base URL of the Awarizon API. Defaults to "https://awarizon.com".
+     * Override for local development or staging environments.
+     */
+    baseUrl?: string;
 }
 interface ContractConfig<TAbi extends Abi = Abi> {
     /** The deployed contract address */
@@ -39,7 +51,7 @@ interface PayableOptions {
     gas?: bigint;
 }
 /**
- * The dynamically-generated contract instance returned by sdk.contract().
+ * The dynamically-generated contract instance returned by awarizon.contract().
  *
  * Every function in the ABI is exposed as a method:
  *  - read functions (view/pure) → return decoded values
@@ -85,79 +97,163 @@ declare class UnsupportedChainError extends Error {
     readonly chain: string;
     constructor(chain: string);
 }
+declare class ApiKeyRequiredError extends Error {
+    readonly code: "API_KEY_REQUIRED";
+    constructor();
+}
+declare class InvalidApiKeyError extends Error {
+    readonly code: "INVALID_API_KEY";
+    constructor(message?: string);
+}
 
 /**
- * The primary entry point for the Awarizon Web3 SDK.
+ * Wraps WalletEngine and gates mutating operations (create, import) behind
+ * API key validation. Read-only operations (address, isConnected, etc.) are
+ * never gated since they need no network access.
+ */
+declare class WalletProxy {
+    private readonly engine;
+    private readonly ensureReady;
+    constructor(engine: WalletEngine, ensureReady: () => Promise<void>);
+    create(): Promise<CreatedWallet>;
+    importMnemonic(mnemonic: string, accountIndex?: number): Promise<ImportedWalletFromMnemonic>;
+    importPrivateKey(privateKey: Hex): Promise<ImportedWalletFromPrivateKey>;
+    address(): Address;
+    getSigner(): WalletClient;
+    getWalletClient(): WalletClient;
+    isConnected(): boolean;
+    hasExternalWallet(): boolean;
+    hasInternalWallet(): boolean;
+    connectExternal(c: ExternalWalletClient): void;
+    disconnectExternal(): void;
+    disconnect(): void;
+    switchChain(chain: Chain): Promise<void>;
+}
+/**
+ * Primary entry point for the Awarizon Web3 SDK.
+ *
+ * An API key is required — get yours at https://awarizon.com/dashboard/api-keys
  *
  * ```ts
- * const sdk = new AwarizonWeb3({ chain: "base" })
+ * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "awz_live_..." })
  *
  * // Internal wallet
- * const wallet = await sdk.wallet.create()
+ * const wallet = await awarizon.wallet.create()
  *
- * // Load a contract and call it
- * const staking = await sdk.contract({ address: "0x...", abi })
+ * // Load a contract
+ * const staking = await awarizon.contract({ address: "0x...", abi })
  * await staking.stake(100n)
- * const balance = await staking.getBalance(wallet.address)
- *
- * // Listen for events
  * staking.on("Staked", (log) => console.log(log))
  * ```
  */
 declare class AwarizonWeb3 {
-    /** The resolved viem Chain */
     readonly chain: Chain;
-    /** Internal wallet + signer management */
-    readonly wallet: WalletEngine;
-    /** The underlying viem PublicClient used for reads */
     readonly publicClient: PublicClient;
+    /** Wallet management — create, import, or connect external wallets */
+    readonly wallet: WalletProxy;
+    private readonly _engine;
+    private readonly _txEngine;
+    private readonly _telemetry;
+    private _contractCache;
     constructor(config: AwarizonConfig);
-    /**
-     * Connect an external wallet client (wagmi, WalletConnect, viem, EIP-1193).
-     * The connected signer takes priority over any internal wallet.
-     *
-     * @example
-     * sdk.connectWallet(walletClient)
-     */
     connectWallet(walletClient: WalletClient): this;
-    /**
-     * Disconnect the externally-connected wallet.
-     * Falls back to the internal wallet if one is loaded.
-     */
     disconnectWallet(): this;
+    switchChain(chain: Chain | string): Promise<this>;
+    getWalletInfo(): SDKWalletInfo;
     /**
-     * Switch the active chain.
-     * Rebuilds the PublicClient and internal WalletClient for the new chain.
+     * Load a deployed contract and return a fully typed, ABI-powered instance.
+     * Validates the API key on the first call — subsequent calls are instant.
+     *
+     * Results are cached by address — calling contract() twice with the same
+     * address and ABI object returns the same instance without rebuilding.
      */
-    switchChain(chain: Chain | string): Promise<this>;
+    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
     /**
-     * Returns a summary of the currently active wallet.
-     * @throws {WalletNotConnectedError} if no wallet is connected
+     * Load multiple contracts in parallel. Validates the API key once, then
+     * instantiates all contracts concurrently.
+     *
+     * @example
+     * ```ts
+     * const [token, staking, nft] = await awarizon.contracts([
+     *   { address: tokenAddr, abi: ERC20_ABI },
+     *   { address: stakingAddr, abi: STAKING_ABI },
+     *   { address: nftAddr, abi: ERC721_ABI },
+     * ])
+     * ```
      */
-    getWalletInfo(): SDKWalletInfo;
+    contracts(configs: Array<{
+        address: Address;
+        abi: Abi;
+    }>): Promise<ContractInstance[]>;
     /**
-     * Load a deployed smart contract and return a fully typed, ABI-powered
-     * instance. Every function in the ABI is exposed as a direct method.
+     * Call a read-only (view/pure) contract function directly without loading
+     * a full contract instance. Best for one-off reads.
      *
-     * **Read functions** (view / pure) use the PublicClient — no signer needed.
-     * **Write functions** (nonpayable / payable) use the active WalletClient.
+     * @example
+     * ```ts
+     * const balance = await awarizon.read<bigint>({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "balanceOf",
+     *   args: [userAddress],
+     * })
+     * ```
+     */
+    read<T = unknown>(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }): Promise<T>;
+    /**
+     * Execute a state-mutating contract function directly without loading a full
+     * contract instance. Best for one-off writes.
      *
      * @example
-     * const token = await sdk.contract({ address: "0x...", abi: ERC20_ABI })
-     * const balance = await token.balanceOf(address)   // read
-     * await token.transfer(to, 100n)                   // write
-     * token.on("Transfer", handler)                    // events
+     * ```ts
+     * const { hash, receipt } = await awarizon.write({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "transfer",
+     *   args: [recipient, 100n],
+     * })
+     * ```
      */
-    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
+    write(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }): Promise<TransactionResult>;
     /**
-     * Returns the chain ID of the current chain.
-     * Useful for runtime network validation.
+     * Batch multiple read calls into a single RPC round-trip using multicall3.
+     * Falls back to parallel individual reads on chains where multicall3 is
+     * not deployed.
+     *
+     * @example
+     * ```ts
+     * const [balance, supply, allowance] = await awarizon.multicall([
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "balanceOf", args: [userAddr] },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "totalSupply" },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "allowance", args: [userAddr, spenderAddr] },
+     * ])
+     * ```
      */
+    multicall(calls: Array<{
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }>): Promise<unknown[]>;
     get chainId(): number;
+    get isConnected(): boolean;
     /**
-     * Check whether any wallet (internal or external) is connected.
+     * Flush pending telemetry and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. on server shutdown).
      */
-    get isConnected(): boolean;
+    destroy(): Promise<void>;
 }
 
 declare const CHAINS: Record<string, Chain>;
@@ -173,4 +269,62 @@ declare function resolveChain(chain: Chain | string): Chain;
 /** Returns a list of all unique supported chain IDs */
 declare function getSupportedChainIds(): number[];
 
-export { type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type EventUnsubscribe, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, UnsupportedChainError, getSupportedChainIds, resolveChain };
+type TelemetryEventType = 'contract.read' | 'contract.write' | 'contract.gas_estimate' | 'wallet.create' | 'wallet.import' | 'chain.switch';
+interface TelemetryEvent {
+    type: TelemetryEventType;
+    chain: string;
+    chainId: number;
+    functionName?: string;
+    success: boolean;
+    durationMs: number;
+    ts: number;
+}
+/**
+ * Handles SDK-to-Awarizon API communication:
+ *   1. Validates the API key on first meaningful operation (5s timeout)
+ *   2. Batches usage events and flushes them fire-and-forget
+ *   3. Flushes remaining events via sendBeacon on browser page unload
+ *
+ * All telemetry failures are swallowed — they never surface to the caller.
+ * The only hard error is InvalidApiKeyError thrown from ensureValidated().
+ */
+declare class TelemetryClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private validated;
+    private validationPromise;
+    private queue;
+    private flushTimer;
+    private unloadListener;
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Ensures the API key has been validated against the Awarizon API.
+     * Idempotent — safe to call on every operation; only hits the network once.
+     * Times out after 5 seconds to avoid hanging in degraded network conditions.
+     *
+     * @throws {InvalidApiKeyError} if the key is invalid, revoked, or unreachable
+     */
+    ensureValidated(): Promise<void>;
+    /**
+     * Queue a usage event. Events are batched and sent periodically.
+     * Must only be called after ensureValidated() has resolved.
+     */
+    track(event: TelemetryEvent): void;
+    /**
+     * Flush pending events and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. server shutdown).
+     */
+    destroy(): Promise<void>;
+    private _validate;
+    private _startTimers;
+    private _stopTimers;
+    /**
+     * Unified flush. Pass `await = true` for graceful shutdown,
+     * `await = false` for fire-and-forget mid-session flushes.
+     */
+    private _flush;
+    /** Uses sendBeacon for guaranteed delivery on page unload */
+    private _flushBeacon;
+}
+
+export { ApiKeyRequiredError, type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type EventUnsubscribe, InvalidApiKeyError, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, TelemetryClient, type TelemetryEvent, type TelemetryEventType, UnsupportedChainError, getSupportedChainIds, resolveChain };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { Chain, WalletClient, Address, Abi, PublicClient } from 'viem';
+import { Chain, WalletClient, Address, Abi, PublicClient, Hex } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine } from '@awarizon/wallet-engine';
+import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ExternalWalletClient } from '@awarizon/wallet-engine';
 export { ChainSwitchError, InvalidMnemonicError, InvalidPrivateKeyError, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
+import { TransactionResult } from '@awarizon/tx-engine';
 export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
 export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
 
@@ -12,6 +13,12 @@ interface AwarizonConfig {
      *  - a viem Chain object: `import { base } from "viem/chains"`
      */
     chain: Chain | string;
+    /**
+     * Awarizon API key (required).
+     * Generate one at https://awarizon.com/dashboard/api-keys
+     * Format: "awz_live_..."
+     */
+    apiKey: string;
     /**
      * Optional RPC URL override.
      * If omitted, the chain's default public RPC endpoint is used.
@@ -19,9 +26,14 @@ interface AwarizonConfig {
     rpcUrl?: string;
     /**
      * Optional pre-connected external signer.
-     * Equivalent to calling `sdk.connectWallet(signer)` after construction.
+     * Equivalent to calling `awarizon.connectWallet(signer)` after construction.
      */
     signer?: WalletClient;
+    /**
+     * Base URL of the Awarizon API. Defaults to "https://awarizon.com".
+     * Override for local development or staging environments.
+     */
+    baseUrl?: string;
 }
 interface ContractConfig<TAbi extends Abi = Abi> {
     /** The deployed contract address */
@@ -39,7 +51,7 @@ interface PayableOptions {
     gas?: bigint;
 }
 /**
- * The dynamically-generated contract instance returned by sdk.contract().
+ * The dynamically-generated contract instance returned by awarizon.contract().
  *
  * Every function in the ABI is exposed as a method:
  *  - read functions (view/pure) → return decoded values
@@ -85,79 +97,163 @@ declare class UnsupportedChainError extends Error {
     readonly chain: string;
     constructor(chain: string);
 }
+declare class ApiKeyRequiredError extends Error {
+    readonly code: "API_KEY_REQUIRED";
+    constructor();
+}
+declare class InvalidApiKeyError extends Error {
+    readonly code: "INVALID_API_KEY";
+    constructor(message?: string);
+}
 
 /**
- * The primary entry point for the Awarizon Web3 SDK.
+ * Wraps WalletEngine and gates mutating operations (create, import) behind
+ * API key validation. Read-only operations (address, isConnected, etc.) are
+ * never gated since they need no network access.
+ */
+declare class WalletProxy {
+    private readonly engine;
+    private readonly ensureReady;
+    constructor(engine: WalletEngine, ensureReady: () => Promise<void>);
+    create(): Promise<CreatedWallet>;
+    importMnemonic(mnemonic: string, accountIndex?: number): Promise<ImportedWalletFromMnemonic>;
+    importPrivateKey(privateKey: Hex): Promise<ImportedWalletFromPrivateKey>;
+    address(): Address;
+    getSigner(): WalletClient;
+    getWalletClient(): WalletClient;
+    isConnected(): boolean;
+    hasExternalWallet(): boolean;
+    hasInternalWallet(): boolean;
+    connectExternal(c: ExternalWalletClient): void;
+    disconnectExternal(): void;
+    disconnect(): void;
+    switchChain(chain: Chain): Promise<void>;
+}
+/**
+ * Primary entry point for the Awarizon Web3 SDK.
+ *
+ * An API key is required — get yours at https://awarizon.com/dashboard/api-keys
  *
  * ```ts
- * const sdk = new AwarizonWeb3({ chain: "base" })
+ * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "awz_live_..." })
  *
  * // Internal wallet
- * const wallet = await sdk.wallet.create()
+ * const wallet = await awarizon.wallet.create()
  *
- * // Load a contract and call it
- * const staking = await sdk.contract({ address: "0x...", abi })
+ * // Load a contract
+ * const staking = await awarizon.contract({ address: "0x...", abi })
  * await staking.stake(100n)
- * const balance = await staking.getBalance(wallet.address)
- *
- * // Listen for events
  * staking.on("Staked", (log) => console.log(log))
  * ```
  */
 declare class AwarizonWeb3 {
-    /** The resolved viem Chain */
     readonly chain: Chain;
-    /** Internal wallet + signer management */
-    readonly wallet: WalletEngine;
-    /** The underlying viem PublicClient used for reads */
     readonly publicClient: PublicClient;
+    /** Wallet management — create, import, or connect external wallets */
+    readonly wallet: WalletProxy;
+    private readonly _engine;
+    private readonly _txEngine;
+    private readonly _telemetry;
+    private _contractCache;
     constructor(config: AwarizonConfig);
-    /**
-     * Connect an external wallet client (wagmi, WalletConnect, viem, EIP-1193).
-     * The connected signer takes priority over any internal wallet.
-     *
-     * @example
-     * sdk.connectWallet(walletClient)
-     */
     connectWallet(walletClient: WalletClient): this;
-    /**
-     * Disconnect the externally-connected wallet.
-     * Falls back to the internal wallet if one is loaded.
-     */
     disconnectWallet(): this;
+    switchChain(chain: Chain | string): Promise<this>;
+    getWalletInfo(): SDKWalletInfo;
     /**
-     * Switch the active chain.
-     * Rebuilds the PublicClient and internal WalletClient for the new chain.
+     * Load a deployed contract and return a fully typed, ABI-powered instance.
+     * Validates the API key on the first call — subsequent calls are instant.
+     *
+     * Results are cached by address — calling contract() twice with the same
+     * address and ABI object returns the same instance without rebuilding.
      */
-    switchChain(chain: Chain | string): Promise<this>;
+    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
     /**
-     * Returns a summary of the currently active wallet.
-     * @throws {WalletNotConnectedError} if no wallet is connected
+     * Load multiple contracts in parallel. Validates the API key once, then
+     * instantiates all contracts concurrently.
+     *
+     * @example
+     * ```ts
+     * const [token, staking, nft] = await awarizon.contracts([
+     *   { address: tokenAddr, abi: ERC20_ABI },
+     *   { address: stakingAddr, abi: STAKING_ABI },
+     *   { address: nftAddr, abi: ERC721_ABI },
+     * ])
+     * ```
      */
-    getWalletInfo(): SDKWalletInfo;
+    contracts(configs: Array<{
+        address: Address;
+        abi: Abi;
+    }>): Promise<ContractInstance[]>;
     /**
-     * Load a deployed smart contract and return a fully typed, ABI-powered
-     * instance. Every function in the ABI is exposed as a direct method.
+     * Call a read-only (view/pure) contract function directly without loading
+     * a full contract instance. Best for one-off reads.
      *
-     * **Read functions** (view / pure) use the PublicClient — no signer needed.
-     * **Write functions** (nonpayable / payable) use the active WalletClient.
+     * @example
+     * ```ts
+     * const balance = await awarizon.read<bigint>({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "balanceOf",
+     *   args: [userAddress],
+     * })
+     * ```
+     */
+    read<T = unknown>(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }): Promise<T>;
+    /**
+     * Execute a state-mutating contract function directly without loading a full
+     * contract instance. Best for one-off writes.
      *
      * @example
-     * const token = await sdk.contract({ address: "0x...", abi: ERC20_ABI })
-     * const balance = await token.balanceOf(address)   // read
-     * await token.transfer(to, 100n)                   // write
-     * token.on("Transfer", handler)                    // events
+     * ```ts
+     * const { hash, receipt } = await awarizon.write({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "transfer",
+     *   args: [recipient, 100n],
+     * })
+     * ```
      */
-    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
+    write(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }): Promise<TransactionResult>;
     /**
-     * Returns the chain ID of the current chain.
-     * Useful for runtime network validation.
+     * Batch multiple read calls into a single RPC round-trip using multicall3.
+     * Falls back to parallel individual reads on chains where multicall3 is
+     * not deployed.
+     *
+     * @example
+     * ```ts
+     * const [balance, supply, allowance] = await awarizon.multicall([
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "balanceOf", args: [userAddr] },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "totalSupply" },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "allowance", args: [userAddr, spenderAddr] },
+     * ])
+     * ```
      */
+    multicall(calls: Array<{
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }>): Promise<unknown[]>;
     get chainId(): number;
+    get isConnected(): boolean;
     /**
-     * Check whether any wallet (internal or external) is connected.
+     * Flush pending telemetry and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. on server shutdown).
      */
-    get isConnected(): boolean;
+    destroy(): Promise<void>;
 }
 
 declare const CHAINS: Record<string, Chain>;
@@ -173,4 +269,62 @@ declare function resolveChain(chain: Chain | string): Chain;
 /** Returns a list of all unique supported chain IDs */
 declare function getSupportedChainIds(): number[];
 
-export { type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type EventUnsubscribe, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, UnsupportedChainError, getSupportedChainIds, resolveChain };
+type TelemetryEventType = 'contract.read' | 'contract.write' | 'contract.gas_estimate' | 'wallet.create' | 'wallet.import' | 'chain.switch';
+interface TelemetryEvent {
+    type: TelemetryEventType;
+    chain: string;
+    chainId: number;
+    functionName?: string;
+    success: boolean;
+    durationMs: number;
+    ts: number;
+}
+/**
+ * Handles SDK-to-Awarizon API communication:
+ *   1. Validates the API key on first meaningful operation (5s timeout)
+ *   2. Batches usage events and flushes them fire-and-forget
+ *   3. Flushes remaining events via sendBeacon on browser page unload
+ *
+ * All telemetry failures are swallowed — they never surface to the caller.
+ * The only hard error is InvalidApiKeyError thrown from ensureValidated().
+ */
+declare class TelemetryClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private validated;
+    private validationPromise;
+    private queue;
+    private flushTimer;
+    private unloadListener;
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Ensures the API key has been validated against the Awarizon API.
+     * Idempotent — safe to call on every operation; only hits the network once.
+     * Times out after 5 seconds to avoid hanging in degraded network conditions.
+     *
+     * @throws {InvalidApiKeyError} if the key is invalid, revoked, or unreachable
+     */
+    ensureValidated(): Promise<void>;
+    /**
+     * Queue a usage event. Events are batched and sent periodically.
+     * Must only be called after ensureValidated() has resolved.
+     */
+    track(event: TelemetryEvent): void;
+    /**
+     * Flush pending events and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. server shutdown).
+     */
+    destroy(): Promise<void>;
+    private _validate;
+    private _startTimers;
+    private _stopTimers;
+    /**
+     * Unified flush. Pass `await = true` for graceful shutdown,
+     * `await = false` for fire-and-forget mid-session flushes.
+     */
+    private _flush;
+    /** Uses sendBeacon for guaranteed delivery on page unload */
+    private _flushBeacon;
+}
+
+export { ApiKeyRequiredError, type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type EventUnsubscribe, InvalidApiKeyError, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, TelemetryClient, type TelemetryEvent, type TelemetryEventType, UnsupportedChainError, getSupportedChainIds, resolveChain };