@aurum-sdk/core 0.2.6 → 0.2.8

package/dist/index.d.mts

@@ -1,274 +1,61 @@
-import { Chain } from 'viem';
-import { WalletId, WalletName, AurumRpcProvider, AurumConfig, NonNullableBrandConfig, UserInfo, WalletsConfig, EmailAuthStartResult, EmailAuthVerifyResult, WalletConnectSessionResult } from '@aurum-sdk/types';
-import { SignInWithEmailResult, VerifyEmailOTPResult } from '@coinbase/cdp-core';
+export { A as Aurum } from './Aurum-B0Okb4Qv.mjs';
+import 'viem';
+import '@aurum-sdk/types';
+import '@coinbase/cdp-core';
 
-interface WalletConnectionResult {
-    address: string;
-    provider: AurumRpcProvider;
-    walletId: WalletId;
-    email?: string;
+/**
+ * Typed error hierarchy for @aurum-sdk/core.
+ *
+ * Consumers can discriminate failures via `instanceof UserRejectedError` or
+ * `err.code === 'USER_REJECTED'` instead of sniffing error message strings.
+ *
+ * All errors thrown from the public AurumCore API extend AurumError.
+ */
+declare abstract class AurumError extends Error {
+    abstract readonly code: string;
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
-interface WalletAdapter {
-    readonly id: WalletId;
-    readonly name: WalletName;
-    readonly icon: string;
-    readonly hide: boolean;
-    readonly downloadUrl: string | null;
-    readonly wcDeepLinkUrl: string | null;
-    isInstalled(): boolean;
-    getProvider(): AurumRpcProvider | null;
-    connect(): Promise<WalletConnectionResult>;
-    tryRestoreConnection(): Promise<WalletConnectionResult | null>;
-    disconnect(): Promise<void>;
-    emailAuthStart?(email: string): Promise<SignInWithEmailResult>;
-    emailAuthVerify?(email: string, otp: string): Promise<VerifyEmailOTPResult>;
-    openModal?(): Promise<WalletConnectionResult>;
-    onAccountsChanged(callback: (accounts: string[]) => void): void;
-    removeListeners(): void;
+declare class UserRejectedError extends AurumError {
+    readonly code = "USER_REJECTED";
+}
+declare class ChainSwitchRejectedError extends AurumError {
+    readonly code = "CHAIN_SWITCH_REJECTED";
+}
+declare class WalletNotInstalledError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_NOT_INSTALLED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class WalletNotConfiguredError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_NOT_CONFIGURED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class WalletExcludedError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_EXCLUDED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class ChainNotSupportedError extends AurumError {
+    readonly code = "CHAIN_NOT_SUPPORTED";
+}
+declare class InvalidConfigError extends AurumError {
+    readonly code = "INVALID_CONFIG";
+}
+declare class ConnectionError extends AurumError {
+    readonly code = "CONNECTION_FAILED";
+}
+interface NormalizeContext {
+    operation?: 'connect' | 'switchChain' | string;
 }
-
 /**
- * Aurum SDK - Web3 Wallet Integration Library
+ * Normalize an unknown thrown value into an AurumError.
+ *
+ * Used at public-method boundaries so errors from wallet adapters (which vary in shape)
+ * exit the core with a stable, typed surface. Centralized message-regex fallback means
+ * downstream consumers don't need to re-implement the heuristic.
  */
-declare class Aurum {
-    private core;
-    /**
-     * Creates a new Aurum instance.
-     *
-     * @param config - Configuration for branding and wallets
-     *
-     * @example
-     * ```typescript
-     * const aurum = new Aurum({
-     *   brand: { appName: 'Your App Name' },
-     *   wallets: {
-     *     embedded: { projectId: 'cdp-project-id' },
-     *     walletConnect: { projectId: 'reown-project-id' },
-     *   },
-     * });
-     * ```
-     */
-    constructor(config: AurumConfig);
-    /**
-     * EIP1193 compatible RPC provider that can be used to interact with the connected wallet.
-     * Compatible with viem, ethers.js, and other web3 libraries.
-     *
-     * @example
-     * ```typescript
-     * const balance = await aurum.rpcProvider.request({
-     *   method: 'eth_getBalance',
-     *   params: [address, 'latest']
-     * });
-     * ```
-     */
-    get rpcProvider(): AurumRpcProvider;
-    /**
-     * Indicates whether the SDK is finished initializing.
-     */
-    get ready(): boolean;
-    /**
-     * Returns the resolved brand configuration.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get brandConfig(): NonNullableBrandConfig;
-    /**
-     * Returns the wallet adapters configured for this instance.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get walletAdapters(): WalletAdapter[];
-    /**
-     * Returns the set of excluded wallet IDs.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get excludedWalletIds(): Set<WalletId>;
-    /**
-     * Waits for the SDK to finish initializing.
-     * This should be called before calling methods with the provider to ensure provider is set (such as after a page refresh).
-     *
-     * @example
-     * ```typescript
-     * await aurum.whenReady();
-     * const balance = await aurum.rpcProvider.request({
-     *   method: 'eth_getBalance',
-     *   params: [address, 'latest']
-     * });
-     * ```
-     */
-    whenReady(): Promise<void>;
-    /**
-     * Opens the wallet connection modal or connects directly to a specific wallet.
-     *
-     * @param walletId - Optional wallet ID for direct connection (bypasses modal).
-     *                   Cannot be 'email' or 'walletconnect' (use their dedicated methods).
-     * @returns The connected wallet address
-     * @throws Error if user closes the modal without connecting a wallet
-     *
-     * @example
-     * ```typescript
-     * // Open modal for user to choose
-     * const address = await aurum.connect();
-     *
-     * // Or connect directly to a specific wallet
-     * import { WalletId } from '@aurum-sdk/types';
-     * const address = await aurum.connect(WalletId.MetaMask);
-     * ```
-     */
-    connect(walletId?: WalletId): Promise<`0x${string}`>;
-    /**
-     * Disconnects the currently connected wallet and clears the connection state.
-     *
-     * @example
-     * ```typescript
-     * await aurum.disconnect();
-     * ```
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Gets information about the currently connected user.
-     *
-     * @returns User information including wallet address and wallet name, or undefined if no wallet is connected
-     *
-     * @example
-     * ```typescript
-     * const userInfo = await aurum.getUserInfo();
-     * if (userInfo) {
-     *   console.log(`Connected to ${userInfo.walletName}: ${userInfo.publicAddress}`);
-     * } else {
-     *   console.log('No wallet connected');
-     * }
-     * ```
-     */
-    getUserInfo(): Promise<UserInfo | undefined>;
-    /**
-     * Checks if a wallet is currently connected.
-     *
-     * @returns `true` if a wallet is connected, `false` otherwise
-     *
-     * @example
-     * ```typescript
-     * const isConnected = await aurum.isConnected();
-     * console.log('Is user connected:', isConnected);
-     * ```
-     */
-    isConnected(): Promise<boolean>;
-    /**
-     * Gets the current chain ID of the connected wallet.
-     *
-     * @returns The current chain ID as a number
-     *
-     * @example
-     * ```typescript
-     * const chainId = await aurum.getChainId();
-     * console.log('Connected to chain:', chainId);
-     * ```
-     */
-    getChainId(): Promise<number>;
-    /**
-     * Switches the connected wallet to a different blockchain network.
-     * If the chain is not added to the wallet, it will attempt to add it using the provided chain config.
-     *
-     * @param chainId - The chain ID to switch to (can be hex string, decimal string, or number)
-     * @param chain - Optional viem Chain object with chain configuration (required if chain needs to be added)
-     * @throws Error if the switch fails or the user rejects the request
-     *
-     * @example
-     * ```typescript
-     * import { sepolia } from 'viem/chains';
-     *
-     * await aurum.switchChain(sepolia.id, sepolia);
-     * ```
-     */
-    switchChain(chainId: `0x${string}` | string | number, chain?: Chain): Promise<void>;
-    /**
-     * Updates the brand configuration at runtime.
-     * Changes will be reflected the next time the connect modal is opened.
-     *
-     * @param newConfig - Partial brand config to merge with existing config
-     *
-     * @example
-     * ```typescript
-     * aurum.updateBrandConfig({
-     *   theme: 'light',
-     * });
-     * ```
-     */
-    updateBrandConfig(newConfig: Partial<NonNullableBrandConfig>): void;
-    /**
-     * Updates the wallets configuration at runtime.
-     * Changes will be reflected the next time the connect modal is opened.
-     *
-     * @param newConfig - Partial wallets config to update (currently supports `exclude`)
-     *
-     * @example
-     * ```typescript
-     * import { WalletId } from '@aurum-sdk/types';
-     *
-     * aurum.updateWalletsConfig({
-     *   exclude: [WalletId.Email, WalletId.WalletConnect],
-     * });
-     * ```
-     */
-    updateWalletsConfig(newConfig: Partial<Pick<WalletsConfig, 'exclude'>>): void;
-    /**
-     * Notifies the SDK of a widget-initiated connection.
-     * Updates internal state so getUserInfo(), isConnected(), etc. work correctly.
-     * @internal Used by ConnectWidget - not intended for direct use
-     */
-    handleWidgetConnection(result: WalletConnectionResult): Promise<UserInfo>;
-    /**
-     * Starts the email authentication flow by sending an OTP to the provided email.
-     * Use with `emailAuthVerify()` to complete the connection.
-     *
-     * @param email - The email address to send the OTP to
-     * @returns Object containing flowId to use with emailAuthVerify
-     * @throws Error if email wallet is not configured
-     *
-     * @example
-     * ```typescript
-     * const { flowId } = await aurum.emailAuthStart('user@example.com');
-     * // User receives OTP email, then verify:
-     * const { address, email, isNewUser } = await aurum.emailAuthVerify(flowId, '123456');
-     * ```
-     */
-    emailAuthStart(email: string): Promise<EmailAuthStartResult>;
-    /**
-     * Verifies the email OTP and completes the wallet connection.
-     *
-     * @param flowId - The flowId returned from emailAuthStart
-     * @param otp - The OTP code the user received via email
-     * @returns Object containing the connected address and email
-     * @throws Error if verification fails
-     *
-     * @example
-     * ```typescript
-     * const { flowId } = await aurum.emailAuthStart('user@example.com');
-     * // User receives OTP...
-     * const { address, email, isNewUser } = await aurum.emailAuthVerify(flowId, '123456');
-     * console.log(`Connected: ${address} (${email})`);
-     * ```
-     */
-    emailAuthVerify(flowId: string, otp: string): Promise<EmailAuthVerifyResult>;
-    /**
-     * Initiates a WalletConnect session and returns the URI for displaying a custom QR code.
-     * Use this for building custom QR code UIs instead of using the built-in modal.
-     *
-     * @returns Object containing the URI and a function to wait for the connection
-     * @throws Error if WalletConnect is not configured
-     *
-     * @example
-     * ```typescript
-     * // Get the WalletConnect URI
-     * const { uri, waitForConnection } = await aurum.getWalletConnectSession();
-     *
-     * // Display your custom QR code with the URI
-     * myQRCodeComponent.render(uri);
-     *
-     * // Wait for user to scan and approve
-     * const address = await waitForConnection();
-     * console.log('Connected:', address);
-     * ```
-     */
-    getWalletConnectSession(): Promise<WalletConnectSessionResult>;
-}
+declare function normalizeError(err: unknown, context?: NormalizeContext): AurumError;
 
-export { Aurum };
+export { AurumError, ChainNotSupportedError, ChainSwitchRejectedError, ConnectionError, InvalidConfigError, UserRejectedError, WalletExcludedError, WalletNotConfiguredError, WalletNotInstalledError, normalizeError };

package/dist/index.d.ts

@@ -1,274 +1,61 @@
-import { Chain } from 'viem';
-import { WalletId, WalletName, AurumRpcProvider, AurumConfig, NonNullableBrandConfig, UserInfo, WalletsConfig, EmailAuthStartResult, EmailAuthVerifyResult, WalletConnectSessionResult } from '@aurum-sdk/types';
-import { SignInWithEmailResult, VerifyEmailOTPResult } from '@coinbase/cdp-core';
+export { A as Aurum } from './Aurum-B0Okb4Qv.js';
+import 'viem';
+import '@aurum-sdk/types';
+import '@coinbase/cdp-core';
 
-interface WalletConnectionResult {
-    address: string;
-    provider: AurumRpcProvider;
-    walletId: WalletId;
-    email?: string;
+/**
+ * Typed error hierarchy for @aurum-sdk/core.
+ *
+ * Consumers can discriminate failures via `instanceof UserRejectedError` or
+ * `err.code === 'USER_REJECTED'` instead of sniffing error message strings.
+ *
+ * All errors thrown from the public AurumCore API extend AurumError.
+ */
+declare abstract class AurumError extends Error {
+    abstract readonly code: string;
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
-interface WalletAdapter {
-    readonly id: WalletId;
-    readonly name: WalletName;
-    readonly icon: string;
-    readonly hide: boolean;
-    readonly downloadUrl: string | null;
-    readonly wcDeepLinkUrl: string | null;
-    isInstalled(): boolean;
-    getProvider(): AurumRpcProvider | null;
-    connect(): Promise<WalletConnectionResult>;
-    tryRestoreConnection(): Promise<WalletConnectionResult | null>;
-    disconnect(): Promise<void>;
-    emailAuthStart?(email: string): Promise<SignInWithEmailResult>;
-    emailAuthVerify?(email: string, otp: string): Promise<VerifyEmailOTPResult>;
-    openModal?(): Promise<WalletConnectionResult>;
-    onAccountsChanged(callback: (accounts: string[]) => void): void;
-    removeListeners(): void;
+declare class UserRejectedError extends AurumError {
+    readonly code = "USER_REJECTED";
+}
+declare class ChainSwitchRejectedError extends AurumError {
+    readonly code = "CHAIN_SWITCH_REJECTED";
+}
+declare class WalletNotInstalledError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_NOT_INSTALLED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class WalletNotConfiguredError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_NOT_CONFIGURED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class WalletExcludedError extends AurumError {
+    readonly walletId: string;
+    readonly code = "WALLET_EXCLUDED";
+    constructor(walletId: string, cause?: unknown);
+}
+declare class ChainNotSupportedError extends AurumError {
+    readonly code = "CHAIN_NOT_SUPPORTED";
+}
+declare class InvalidConfigError extends AurumError {
+    readonly code = "INVALID_CONFIG";
+}
+declare class ConnectionError extends AurumError {
+    readonly code = "CONNECTION_FAILED";
+}
+interface NormalizeContext {
+    operation?: 'connect' | 'switchChain' | string;
 }
-
 /**
- * Aurum SDK - Web3 Wallet Integration Library
+ * Normalize an unknown thrown value into an AurumError.
+ *
+ * Used at public-method boundaries so errors from wallet adapters (which vary in shape)
+ * exit the core with a stable, typed surface. Centralized message-regex fallback means
+ * downstream consumers don't need to re-implement the heuristic.
  */
-declare class Aurum {
-    private core;
-    /**
-     * Creates a new Aurum instance.
-     *
-     * @param config - Configuration for branding and wallets
-     *
-     * @example
-     * ```typescript
-     * const aurum = new Aurum({
-     *   brand: { appName: 'Your App Name' },
-     *   wallets: {
-     *     embedded: { projectId: 'cdp-project-id' },
-     *     walletConnect: { projectId: 'reown-project-id' },
-     *   },
-     * });
-     * ```
-     */
-    constructor(config: AurumConfig);
-    /**
-     * EIP1193 compatible RPC provider that can be used to interact with the connected wallet.
-     * Compatible with viem, ethers.js, and other web3 libraries.
-     *
-     * @example
-     * ```typescript
-     * const balance = await aurum.rpcProvider.request({
-     *   method: 'eth_getBalance',
-     *   params: [address, 'latest']
-     * });
-     * ```
-     */
-    get rpcProvider(): AurumRpcProvider;
-    /**
-     * Indicates whether the SDK is finished initializing.
-     */
-    get ready(): boolean;
-    /**
-     * Returns the resolved brand configuration.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get brandConfig(): NonNullableBrandConfig;
-    /**
-     * Returns the wallet adapters configured for this instance.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get walletAdapters(): WalletAdapter[];
-    /**
-     * Returns the set of excluded wallet IDs.
-     * @internal Used by widget components (i.e. ConnectWidget)
-     */
-    get excludedWalletIds(): Set<WalletId>;
-    /**
-     * Waits for the SDK to finish initializing.
-     * This should be called before calling methods with the provider to ensure provider is set (such as after a page refresh).
-     *
-     * @example
-     * ```typescript
-     * await aurum.whenReady();
-     * const balance = await aurum.rpcProvider.request({
-     *   method: 'eth_getBalance',
-     *   params: [address, 'latest']
-     * });
-     * ```
-     */
-    whenReady(): Promise<void>;
-    /**
-     * Opens the wallet connection modal or connects directly to a specific wallet.
-     *
-     * @param walletId - Optional wallet ID for direct connection (bypasses modal).
-     *                   Cannot be 'email' or 'walletconnect' (use their dedicated methods).
-     * @returns The connected wallet address
-     * @throws Error if user closes the modal without connecting a wallet
-     *
-     * @example
-     * ```typescript
-     * // Open modal for user to choose
-     * const address = await aurum.connect();
-     *
-     * // Or connect directly to a specific wallet
-     * import { WalletId } from '@aurum-sdk/types';
-     * const address = await aurum.connect(WalletId.MetaMask);
-     * ```
-     */
-    connect(walletId?: WalletId): Promise<`0x${string}`>;
-    /**
-     * Disconnects the currently connected wallet and clears the connection state.
-     *
-     * @example
-     * ```typescript
-     * await aurum.disconnect();
-     * ```
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Gets information about the currently connected user.
-     *
-     * @returns User information including wallet address and wallet name, or undefined if no wallet is connected
-     *
-     * @example
-     * ```typescript
-     * const userInfo = await aurum.getUserInfo();
-     * if (userInfo) {
-     *   console.log(`Connected to ${userInfo.walletName}: ${userInfo.publicAddress}`);
-     * } else {
-     *   console.log('No wallet connected');
-     * }
-     * ```
-     */
-    getUserInfo(): Promise<UserInfo | undefined>;
-    /**
-     * Checks if a wallet is currently connected.
-     *
-     * @returns `true` if a wallet is connected, `false` otherwise
-     *
-     * @example
-     * ```typescript
-     * const isConnected = await aurum.isConnected();
-     * console.log('Is user connected:', isConnected);
-     * ```
-     */
-    isConnected(): Promise<boolean>;
-    /**
-     * Gets the current chain ID of the connected wallet.
-     *
-     * @returns The current chain ID as a number
-     *
-     * @example
-     * ```typescript
-     * const chainId = await aurum.getChainId();
-     * console.log('Connected to chain:', chainId);
-     * ```
-     */
-    getChainId(): Promise<number>;
-    /**
-     * Switches the connected wallet to a different blockchain network.
-     * If the chain is not added to the wallet, it will attempt to add it using the provided chain config.
-     *
-     * @param chainId - The chain ID to switch to (can be hex string, decimal string, or number)
-     * @param chain - Optional viem Chain object with chain configuration (required if chain needs to be added)
-     * @throws Error if the switch fails or the user rejects the request
-     *
-     * @example
-     * ```typescript
-     * import { sepolia } from 'viem/chains';
-     *
-     * await aurum.switchChain(sepolia.id, sepolia);
-     * ```
-     */
-    switchChain(chainId: `0x${string}` | string | number, chain?: Chain): Promise<void>;
-    /**
-     * Updates the brand configuration at runtime.
-     * Changes will be reflected the next time the connect modal is opened.
-     *
-     * @param newConfig - Partial brand config to merge with existing config
-     *
-     * @example
-     * ```typescript
-     * aurum.updateBrandConfig({
-     *   theme: 'light',
-     * });
-     * ```
-     */
-    updateBrandConfig(newConfig: Partial<NonNullableBrandConfig>): void;
-    /**
-     * Updates the wallets configuration at runtime.
-     * Changes will be reflected the next time the connect modal is opened.
-     *
-     * @param newConfig - Partial wallets config to update (currently supports `exclude`)
-     *
-     * @example
-     * ```typescript
-     * import { WalletId } from '@aurum-sdk/types';
-     *
-     * aurum.updateWalletsConfig({
-     *   exclude: [WalletId.Email, WalletId.WalletConnect],
-     * });
-     * ```
-     */
-    updateWalletsConfig(newConfig: Partial<Pick<WalletsConfig, 'exclude'>>): void;
-    /**
-     * Notifies the SDK of a widget-initiated connection.
-     * Updates internal state so getUserInfo(), isConnected(), etc. work correctly.
-     * @internal Used by ConnectWidget - not intended for direct use
-     */
-    handleWidgetConnection(result: WalletConnectionResult): Promise<UserInfo>;
-    /**
-     * Starts the email authentication flow by sending an OTP to the provided email.
-     * Use with `emailAuthVerify()` to complete the connection.
-     *
-     * @param email - The email address to send the OTP to
-     * @returns Object containing flowId to use with emailAuthVerify
-     * @throws Error if email wallet is not configured
-     *
-     * @example
-     * ```typescript
-     * const { flowId } = await aurum.emailAuthStart('user@example.com');
-     * // User receives OTP email, then verify:
-     * const { address, email, isNewUser } = await aurum.emailAuthVerify(flowId, '123456');
-     * ```
-     */
-    emailAuthStart(email: string): Promise<EmailAuthStartResult>;
-    /**
-     * Verifies the email OTP and completes the wallet connection.
-     *
-     * @param flowId - The flowId returned from emailAuthStart
-     * @param otp - The OTP code the user received via email
-     * @returns Object containing the connected address and email
-     * @throws Error if verification fails
-     *
-     * @example
-     * ```typescript
-     * const { flowId } = await aurum.emailAuthStart('user@example.com');
-     * // User receives OTP...
-     * const { address, email, isNewUser } = await aurum.emailAuthVerify(flowId, '123456');
-     * console.log(`Connected: ${address} (${email})`);
-     * ```
-     */
-    emailAuthVerify(flowId: string, otp: string): Promise<EmailAuthVerifyResult>;
-    /**
-     * Initiates a WalletConnect session and returns the URI for displaying a custom QR code.
-     * Use this for building custom QR code UIs instead of using the built-in modal.
-     *
-     * @returns Object containing the URI and a function to wait for the connection
-     * @throws Error if WalletConnect is not configured
-     *
-     * @example
-     * ```typescript
-     * // Get the WalletConnect URI
-     * const { uri, waitForConnection } = await aurum.getWalletConnectSession();
-     *
-     * // Display your custom QR code with the URI
-     * myQRCodeComponent.render(uri);
-     *
-     * // Wait for user to scan and approve
-     * const address = await waitForConnection();
-     * console.log('Connected:', address);
-     * ```
-     */
-    getWalletConnectSession(): Promise<WalletConnectSessionResult>;
-}
+declare function normalizeError(err: unknown, context?: NormalizeContext): AurumError;
 
-export { Aurum };
+export { AurumError, ChainNotSupportedError, ChainSwitchRejectedError, ConnectionError, InvalidConfigError, UserRejectedError, WalletExcludedError, WalletNotConfiguredError, WalletNotInstalledError, normalizeError };