@volr/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,640 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { KeyStorageType as KeyStorageType$1, WalletProviderPort, PrecheckInput, PrecheckQuote, RelayInput, RelayResult, SignerPort, ExtendedRPCClient, Call, PasskeyProviderPort } from '@volr/sdk-core';
+export { AuthorizationTuple, Call, MpcTransport, PrecheckInput, PrecheckQuote, PrfInput, RelayInput, RelayMode, RelayResult, SessionAuth, UploadBlobOptions, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, sealMasterSeed, uploadBlob } from '@volr/sdk-core';
+import { Address, Abi, PublicClient } from 'viem';
+
+/**
+ * API client with automatic token refresh
+ */
+/**
+ * API client configuration
+ */
+type APIClientConfig = {
+    baseUrl: string;
+    apiKey?: string;
+};
+/**
+ * API client
+ */
+declare class APIClient {
+    private refreshPromise;
+    private accessToken;
+    private apiKey;
+    private api;
+    constructor(config: APIClientConfig);
+    /**
+     * Set API key
+     */
+    setApiKey(apiKey: string | null): void;
+    /**
+     * Get API key
+     */
+    getApiKey(): string | null;
+    /**
+     * Set access token
+     */
+    setAccessToken(token: string | null): void;
+    /**
+     * Get access token
+     */
+    getAccessToken(): string | null;
+    /**
+     * Refresh access token (single-flight)
+     */
+    private refreshAccessToken;
+    /**
+     * Make API request with automatic retry on 401
+     */
+    request<T>(endpoint: string, options?: RequestInit, idempotencyKey?: string): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, body: any, idempotencyKey?: string): Promise<T>;
+    /**
+     * POST request that returns raw binary (ArrayBuffer)
+     * - Uses axios instance with interceptors (auto 401 refresh)
+     * - Applies X-API-Key and Authorization automatically
+     */
+    postBinary(endpoint: string, body: any): Promise<ArrayBuffer>;
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string): Promise<T>;
+}
+
+/**
+ * API Response DTOs
+ * Backend API로부터 받는 응답 타입 정의
+ */
+
+/**
+ * PRF Input DTO
+ * WebAuthn PRF 확장을 위한 입력 파라미터
+ */
+interface PrfInputDto {
+    origin: string;
+    projectId: string;
+    credentialId: string;
+    salt?: Uint8Array;
+}
+/**
+ * User DTO
+ * 백엔드로부터 받는 사용자 정보
+ */
+interface UserDto {
+    id: string;
+    email: string;
+    accountId?: string;
+    evmAddress?: `0x${string}`;
+    keyStorageType?: KeyStorageType$1;
+    signerType?: 'passkey' | 'external_wallet' | 'mpc';
+    walletConnector?: string;
+    lastWalletChainId?: number;
+    blobUrl?: string;
+    prfInput?: PrfInputDto;
+    credentialId?: string;
+}
+/**
+ * Auth Refresh Response DTO
+ * /auth/refresh 엔드포인트 응답
+ */
+interface AuthRefreshResponseDto {
+    accessToken: string;
+    user?: UserDto;
+}
+/**
+ * Network DTO
+ * /networks/:chainId 엔드포인트 응답
+ */
+interface NetworkDto {
+    chainId: string;
+    name: string;
+    rpcUrl?: string;
+    isActive: boolean;
+    invokerAddress: `0x${string}`;
+}
+/**
+ * Transaction Status
+ * 트랜잭션 상태 값
+ */
+type TransactionStatus = 'QUEUED' | 'PENDING' | 'CONFIRMED' | 'FAILED';
+/**
+ * Transaction DTO
+ * /wallet/transactions/:txId 엔드포인트 응답
+ */
+interface TransactionDto {
+    txId: string;
+    status: TransactionStatus;
+    txHash?: `0x${string}`;
+    gasUsed?: string;
+    meta?: any;
+}
+/**
+ * API Response Wrapper
+ * 모든 API 응답의 공통 래퍼
+ */
+interface ApiResponse<T> {
+    ok: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+type KeyStorageType = "passkey" | "mpc";
+type SignerType = "passkey" | "external_wallet" | "mpc";
+
+/**
+ * ERC-20 token configuration
+ */
+interface Erc20Token$1 {
+    address: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    iconUrl?: string;
+}
+/**
+ * Deposit asset configuration (native or ERC-20)
+ */
+interface DepositAsset$1 {
+    chainId: number;
+    token: "native" | Erc20Token$1;
+}
+/**
+ * Deposit/Topup configuration
+ */
+interface DepositConfig {
+    supportedAssets: DepositAsset$1[];
+    pollIntervalMs?: number;
+}
+/**
+ * User information
+ */
+interface VolrUser {
+    id?: string;
+    email?: string;
+    accountId?: string;
+    evmAddress?: `0x${string}`;
+    keyStorageType?: KeyStorageType;
+    signerType?: SignerType;
+    walletConnector?: string;
+    lastWalletChainId?: number;
+    blobUrl?: string;
+    prfInput?: PrfInputDto;
+    credentialId?: string;
+}
+/**
+ * Volr configuration
+ */
+type VolrConfig = {
+    apiBaseUrl: string;
+    defaultChainId: number;
+    projectApiKey: string;
+    rpcOverrides?: Record<string, string>;
+    autoRecoverOnLogin?: boolean;
+    providerPolicy?: {
+        enforceOnFirstLogin?: boolean;
+    };
+    /**
+     * Deposit/Topup configuration for multi-chain, multi-token support
+     */
+    deposit?: DepositConfig;
+    /**
+     * @internal 개발용: API Base URL 오버라이드
+     * 일반 사용자는 타입 체크로 접근 불가
+     * 개발 시에는 @ts-expect-error 주석 필요
+     */
+    __devApiBaseUrl?: string;
+};
+/**
+ * Public context value
+ */
+type VolrContextValue = {
+    config: VolrConfig;
+    user: VolrUser | null;
+    provider: WalletProviderPort | null;
+    setProvider: (provider: WalletProviderPort) => Promise<void>;
+    setUser: (user: VolrUser | null) => void;
+    chainId: number;
+    precheck: (input: PrecheckInput) => Promise<PrecheckQuote>;
+    relay: (input: RelayInput, opts?: {
+        idempotencyKey?: string;
+    }) => Promise<RelayResult>;
+    logout: () => Promise<void>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Internal auth context (for advanced use)
+ */
+type InternalAuthContextType = {
+    session: {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    refreshAccessToken: () => Promise<void>;
+    setAccessToken: (token: string) => void;
+    client: APIClient;
+};
+
+/**
+ * VolrProvider props
+ */
+type VolrProviderProps = {
+    config: VolrConfig;
+    children: ReactNode;
+};
+/**
+ * VolrProvider component
+ */
+declare function VolrProvider({ config, children }: VolrProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useVolr hook - Access Volr context
+ */
+/**
+ * Get Volr context value
+ * @throws Error if used outside VolrProvider
+ */
+declare function useVolr(): VolrContextValue;
+
+/**
+ * usePrecheck hook - Precheck transaction batch
+ */
+
+/**
+ * usePrecheck return type
+ */
+type UsePrecheckReturn = {
+    precheck: (input: PrecheckInput) => Promise<PrecheckQuote>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * usePrecheck hook
+ */
+declare function usePrecheck(): UsePrecheckReturn;
+
+/**
+ * useRelay hook - Relay transaction batch
+ */
+
+/**
+ * useRelay return type
+ */
+type UseRelayReturn = {
+    relay: (input: Omit<RelayInput, "sessionSig" | "authorizationList">, opts?: {
+        signer: SignerPort;
+        rpcClient?: ExtendedRPCClient;
+        idempotencyKey?: string;
+    }) => Promise<RelayResult>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * useRelay hook
+ */
+declare function useRelay(): UseRelayReturn;
+
+/**
+ * Call builder utilities for better developer experience
+ */
+
+/**
+ * Options for building a call from function data
+ */
+type BuildCallOptions = {
+    target: Address;
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+    value?: bigint;
+    gasLimit?: bigint;
+    /**
+     * Estimate gas automatically (future feature)
+     * Currently noop - will use precheck result to inject gasLimit
+     */
+    estimateGas?: boolean;
+};
+/**
+ * Build a Call object from function data (auto-encodes data)
+ *
+ * @example
+ * ```ts
+ * const call = buildCall({
+ *   target: '0x...',
+ *   abi: erc20Abi,
+ *   functionName: 'transfer',
+ *   args: ['0x...', BigInt(1000000)],
+ *   value: BigInt(0),
+ *   gasLimit: BigInt(100000),
+ *   estimateGas: true, // Future: will auto-estimate from precheck
+ * });
+ * ```
+ */
+declare function buildCall(options: BuildCallOptions): Call;
+/**
+ * Build multiple calls from function data
+ *
+ * @example
+ * ```ts
+ * const calls = buildCalls([
+ *   {
+ *     target: tokenAddress,
+ *     abi: erc20Abi,
+ *     functionName: 'approve',
+ *     args: [spender, amount],
+ *     gasLimit: BigInt(50000),
+ *   },
+ *   {
+ *     target: routerAddress,
+ *     abi: routerAbi,
+ *     functionName: 'swap',
+ *     args: [tokenIn, tokenOut, amountIn],
+ *     gasLimit: BigInt(200000),
+ *   },
+ * ]);
+ * ```
+ */
+declare function buildCalls(options: BuildCallOptions[]): Call[];
+
+type SendTxOptions = {
+    /**
+     * 프로젝트별 policyId. 제공하지 않으면 백엔드에서 자동으로 계산됩니다.
+     * Zero policyId (0x0000...0000)는 사용할 수 없습니다.
+     */
+    policyId?: `0x${string}`;
+    signer?: SignerPort;
+    expiresInSec?: number;
+    idempotencyKey?: string;
+    mode?: 'sponsored' | 'self';
+    from?: `0x${string}`;
+    /**
+     * Run best-effort RPC preflight (eth_estimateGas) before prompting passkey.
+     * Defaults to true.
+     */
+    preflight?: boolean;
+};
+
+/**
+ * useVolrWallet hook - Developer-friendly facade for wallet operations
+ */
+
+/**
+ * sendBatch function overloads
+ */
+type SendBatchOverloads = {
+    /**
+     * Send a batch of pre-built Call objects
+     * @param calls - Array of Call objects with target, data, value, gasLimit
+     * @param opts - Transaction options including policyId, expiresInSec, from
+     * @example
+     * ```ts
+     * const calls: Call[] = [
+     *   { target: '0x...', data: '0x...', value: 0n, gasLimit: 100000n }
+     * ];
+     * await evm(chainId).sendBatch(calls, { policyId: '0x...' });
+     * ```
+     */
+    (calls: Call[], opts: SendTxOptions & {
+        from?: `0x${string}`;
+    }): Promise<RelayResult>;
+    /**
+     * Send a batch by providing BuildCallOptions - calls will be built internally
+     * @param calls - Array of BuildCallOptions with target, abi, functionName, args
+     * @param opts - Transaction options including policyId, expiresInSec, from
+     * @example
+     * ```ts
+     * await evm(chainId).sendBatch(
+     *   [
+     *     {
+     *       target: tokenAddress,
+     *       abi: erc20Abi,
+     *       functionName: 'transfer',
+     *       args: [recipient, amount],
+     *       gasLimit: 100000n,
+     *     }
+     *   ],
+     *   { policyId: '0x...' }
+     * );
+     * ```
+     */
+    (calls: BuildCallOptions[], opts: SendTxOptions & {
+        from?: `0x${string}`;
+    }): Promise<RelayResult>;
+};
+/**
+ * useVolrWallet hook return type
+ */
+type UseVolrWalletReturn = {
+    evm: (chainId: number) => {
+        readContract: <TAbi extends readonly unknown[], TFunctionName extends string, TReturnType = Awaited<ReturnType<PublicClient['readContract']>>>(args: Parameters<PublicClient['readContract']>[0] & {
+            abi: TAbi;
+            functionName: TFunctionName;
+        }) => Promise<TReturnType>;
+        sendTransaction: (tx: {
+            to: `0x${string}`;
+            data: `0x${string}`;
+            value?: bigint;
+        }, opts: SendTxOptions) => Promise<RelayResult>;
+        sendBatch: SendBatchOverloads;
+    };
+};
+/**
+ * useVolrWallet hook - Developer-friendly facade
+ */
+declare function useVolrWallet(): UseVolrWalletReturn;
+
+/**
+ * useVolrLogin hook - Login handlers for various authentication methods
+ */
+
+type SocialProvider = "google" | "twitter" | "apple";
+/**
+ * Authentication result after successful login/verification
+ */
+interface AuthResult {
+    userId: string;
+    isNewUser: boolean;
+    /** Key storage type: 'passkey' or 'mpc'. Null if user hasn't set up key storage yet. */
+    keyStorageType: KeyStorageType | null;
+    /** Signer type: how the user signs transactions */
+    signerType?: SignerType | null;
+    /** Access token for API authentication. Always present after successful login. */
+    accessToken: string;
+}
+interface UseVolrLoginReturn {
+    requestEmailCode: (email: string) => Promise<void>;
+    verifyEmailCode: (email: string, code: string) => Promise<AuthResult>;
+    handleSocialLogin: (provider: SocialProvider) => Promise<void>;
+    requestSiweNonce: () => Promise<string>;
+    verifySiweSignature: (message: string, signature: string, options?: {
+        walletConnector?: string;
+        chainId?: number;
+    }) => Promise<AuthResult>;
+    handlePasskeyComplete: () => Promise<void>;
+}
+/**
+ * useVolrLogin hook
+ * Provides login handlers for email, social, wallet, and passkey authentication
+ */
+declare function useVolrLogin(): UseVolrLoginReturn;
+
+type Erc20Token = {
+    address: `0x${string}`;
+    decimals: number;
+};
+type DepositAsset = {
+    kind: "native";
+} | {
+    kind: "erc20";
+    token: Erc20Token;
+};
+type DepositStatus = {
+    state: "idle";
+} | {
+    state: "listening";
+    balance: bigint;
+} | {
+    state: "detected";
+    previousBalance: bigint;
+    newBalance: bigint;
+    delta: bigint;
+} | {
+    state: "error";
+    message: string;
+};
+declare function useDepositListener(input: {
+    chainId: number;
+    asset: DepositAsset;
+    address: `0x${string}`;
+    pollIntervalMs?: number;
+}): DepositStatus;
+
+/**
+ * usePasskeyEnrollment hook
+ * React-specific logic for passkey enrollment
+ */
+type PasskeyEnrollmentStep = 'idle' | 'creating' | 'encrypting' | 'uploading' | 'registering';
+interface UsePasskeyEnrollmentReturn {
+    /** Start passkey enrollment */
+    enroll: () => Promise<void>;
+    /** Current enrollment step */
+    step: PasskeyEnrollmentStep;
+    /** Whether enrollment is in progress */
+    isEnrolling: boolean;
+    /** Error message if enrollment failed */
+    error: Error | null;
+}
+/**
+ * usePasskeyEnrollment hook
+ * Provides passkey enrollment functionality
+ */
+declare function usePasskeyEnrollment(): UsePasskeyEnrollmentReturn;
+
+/**
+ * useMpcConnection hook
+ * React-specific logic for MPC connection
+ */
+type MpcConnectionStep = 'idle' | 'connecting' | 'registering';
+interface UseMpcConnectionReturn {
+    /** Start MPC connection */
+    connect: () => Promise<void>;
+    /** Current connection step */
+    step: MpcConnectionStep;
+    /** Whether connection is in progress */
+    isConnecting: boolean;
+    /** Error message if connection failed */
+    error: Error | null;
+}
+/**
+ * useMpcConnection hook
+ * Provides MPC connection functionality
+ */
+declare function useMpcConnection(): UseMpcConnectionReturn;
+
+declare function uploadBlobViaPresign(params: {
+    baseUrl: string;
+    apiKey: string;
+    blob: Blob;
+    contentType?: string;
+}): Promise<{
+    s3Key: string;
+}>;
+
+/**
+ * useInternalAuth hook - Access internal auth context
+ */
+/**
+ * Get internal auth context value
+ * @throws Error if used outside VolrProvider
+ */
+declare function useInternalAuth(): InternalAuthContextType;
+
+/**
+ * Passkey adapter for WebAuthn
+ * Implements PasskeyProviderPort interface
+ */
+
+/**
+ * Passkey adapter options
+ */
+type PasskeyAdapterOptions = {
+    rpId?: string;
+    rpName?: string;
+    userDisplayName?: string;
+    userHandle?: Uint8Array;
+};
+/**
+ * Create passkey adapter
+ */
+declare function createPasskeyAdapter(options?: PasskeyAdapterOptions): PasskeyProviderPort;
+
+/**
+ * Default constants for wallet facade
+ */
+/**
+ * Default session expiry time in seconds (15 minutes)
+ */
+declare const DEFAULT_EXPIRES_IN_SEC = 900;
+/**
+ * Default relay mode
+ */
+declare const DEFAULT_MODE: 'sponsored' | 'self';
+/**
+ * Generate default idempotency key
+ * Uses crypto.randomUUID() if available, otherwise falls back to time+random
+ */
+declare function defaultIdempotencyKey(): string;
+
+type NetworkInfo = {
+    name: string;
+    rpcUrl?: string;
+};
+type CreateGetNetworkInfoDeps = {
+    client: APIClient;
+    rpcOverrides?: Record<string, string>;
+};
+/**
+ * Factory to create a getNetworkInfo resolver bound to provided deps.
+ * Returns chain name and optionally RPC URL.
+ * Priority: 1) rpcOverrides (for RPC URL) 2) Backend API (cached)
+ */
+declare function createGetNetworkInfo(deps: CreateGetNetworkInfoDeps): (chainId: number, includeRpcUrl?: boolean) => Promise<NetworkInfo>;
+
+/**
+ * Hex string normalization utilities
+ */
+/**
+ * Normalize hex string to lowercase with 0x prefix
+ * Ensures consistent format for hashing and comparison
+ */
+declare function normalizeHex(value: `0x${string}` | string): `0x${string}`;
+/**
+ * Normalize multiple hex strings
+ */
+declare function normalizeHexArray(values: (`0x${string}` | string)[]): `0x${string}`[];
+
+export { type ApiResponse, type AuthRefreshResponseDto, type AuthResult, type BuildCallOptions, DEFAULT_EXPIRES_IN_SEC, DEFAULT_MODE, type DepositAsset$1 as DepositAsset, type DepositConfig, type Erc20Token$1 as Erc20Token, type KeyStorageType, type MpcConnectionStep, type NetworkDto, type NetworkInfo, type PasskeyAdapterOptions, type PasskeyEnrollmentStep, type PrfInputDto, type SendTxOptions, type SignerType, type SocialProvider, type TransactionDto, type TransactionStatus, type UseMpcConnectionReturn, type UsePasskeyEnrollmentReturn, type UsePrecheckReturn, type UseRelayReturn, type UseVolrLoginReturn, type UseVolrWalletReturn, type UserDto, type VolrConfig, type VolrContextValue, VolrProvider, type VolrUser, buildCall, buildCalls, createGetNetworkInfo, createPasskeyAdapter, defaultIdempotencyKey, normalizeHex, normalizeHexArray, uploadBlobViaPresign, useDepositListener, useInternalAuth, useMpcConnection, usePasskeyEnrollment, usePrecheck, useRelay, useVolr, useVolrLogin, useVolrWallet };