@frontiertower/frontier-sdk 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# Frontier Wallet SDK
+
+Official SDK for building apps on Frontier Wallet.
+
+## Example Project
+
+Check out [**frontier-kickstarter**](https://github.com/BerlinhouseLabs/frontier-kickstarter) - a complete example project that demonstrates how to use this SDK to build a decentralized crowdfunding platform on Frontier Wallet.
+
+## Installation
+
+```bash
+npm install @frontier-wallet/sdk
+```
+
+## Quick Start
+
+```typescript
+import { FrontierSDK } from '@frontier-wallet/sdk';
+import { isInFrontierApp, renderStandaloneMessage } from '@frontier-wallet/sdk/ui-utils';
+
+// Initialize the SDK
+const sdk = new FrontierSDK();
+
+// Check if running in Frontier Wallet
+if (!isInFrontierApp()) {
+  renderStandaloneMessage(document.body, 'My App');
+  return;
+}
+
+// Access wallet information
+const balance = await sdk.getWallet().getBalance();
+const address = await sdk.getWallet().getAddress();
+
+// Use persistent storage
+await sdk.getStorage().set('myKey', { value: 'myData' });
+const data = await sdk.getStorage().get('myKey');
+```
+
+
+## Permissions
+
+Your app must declare required permissions in the Frontier app registry:
+
+### Wallet Permissions
+- `wallet:getBalance` - Access wallet balance
+- `wallet:getBalanceFormatted` - Access formatted wallet balance
+- `wallet:getAddress` - Access wallet address
+- `wallet:getSmartAccount` - Access smart account details
+- `wallet:transferERC20` - Transfer ERC20 tokens
+- `wallet:approveERC20` - Approve ERC20 token spending
+- `wallet:transferNative` - Transfer native currency (ETH)
+- `wallet:executeCall` - Execute arbitrary contract calls
+
+### Storage Permissions
+- `storage:get` - Read from storage
+- `storage:set` - Write to storage
+- `storage:remove` - Remove from storage
+- `storage:clear` - Clear all storage
+- `storage:*` - Full storage access (wildcard for all storage methods)
+
+### User Permissions
+- `user:getDetails` - Access current user details
+- `user:getProfile` - Access user profile information
+
+### Chain Permissions
+- `chain:getCurrentNetwork` - Get current network name
+- `chain:getAvailableNetworks` - Get list of available networks
+- `chain:switchNetwork` - Switch to a different network
+- `chain:getCurrentChainConfig` - Get full chain configuration
+
+## Security
+
+The SDK verifies that apps are running in legitimate Frontier Wallet instances. Allowed origins:
+
+- `http://localhost:5173` (development)
+- `https://sandbox.wallet.frontiertower.io`
+- `https://alpha.wallet.frontiertower.io`
+- `https://beta.wallet.frontiertower.io`
+- `https://wallet.frontiertower.io` (production)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the SDK
+npm run build
+
+# Watch mode for development
+npm run dev
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © Frontier Tower
+
+## Support
+
+For questions and support, please visit [Frontier Tower](https://frontiertower.io) or open an issue on GitHub.

package/dist/index.d.mts

@@ -0,0 +1,542 @@
+/**
+ * Smart account information
+ */
+interface SmartAccount {
+    /** Unique identifier for the smart account */
+    id: number;
+    /** Owner's EOA address */
+    ownerAddress: string;
+    /** Deployed smart contract address (null if not yet deployed) */
+    contractAddress: string | null;
+    /** Network identifier (e.g., 'sepolia', 'mainnet') */
+    network: string;
+    /** Deployment status */
+    status: string;
+    /** Transaction hash of the deployment */
+    deploymentTransactionHash: string;
+    /** Creation timestamp */
+    createdAt: string;
+}
+/**
+ * Transaction receipt from a user operation
+ */
+interface UserOperationReceipt {
+    /** User operation hash */
+    userOpHash: string;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block number */
+    blockNumber: bigint;
+    /** Whether the operation was successful */
+    success: boolean;
+}
+/**
+ * Gas override options for transactions
+ */
+interface GasOverrides {
+    /** Maximum fee per gas */
+    maxFeePerGas?: bigint;
+    /** Maximum priority fee per gas */
+    maxPriorityFeePerGas?: bigint;
+    /** Gas limit */
+    gasLimit?: bigint;
+}
+/**
+ * Execute call parameters for arbitrary contract interactions
+ */
+interface ExecuteCall {
+    /** Target contract address */
+    to: string;
+    /** Value to send (in wei) */
+    value?: bigint;
+    /** Calldata */
+    data: string;
+}
+/**
+ * Wallet access class for interacting with the user's wallet
+ *
+ * This class provides methods to:
+ * - Query wallet addresses and smart accounts
+ * - Check balances for stablecoins
+ * - Transfer ERC20 tokens and native currency
+ * - Execute arbitrary contract calls
+ *
+ * All methods use the current chain from the chain manager.
+ * All methods require appropriate permissions and may trigger biometric authentication.
+ */
+declare class WalletAccess {
+    private sdk;
+    constructor(sdk: FrontierSDK);
+    /**
+     * Get the current wallet balance
+     *
+     * Returns the total USD stablecoin balance for the current network,
+     * normalized to 18 decimals for consistency.
+     *
+     * @returns Balance as bigint (18 decimals)
+     * @throws {Error} If no wallet exists
+     *
+     * @example
+     * ```typescript
+     * const balance = await sdk.getWallet().getBalance();
+     * console.log('Balance:', balance.toString());
+     * ```
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Get the current wallet balance formatted for display
+     *
+     * Returns the total USD stablecoin balance as a formatted string
+     * with currency symbol (e.g., '$10.50').
+     *
+     * @returns Formatted balance string with $ sign
+     * @throws {Error} If no wallet exists
+     *
+     * @example
+     * ```typescript
+     * const balance = await sdk.getWallet().getBalanceFormatted();
+     * console.log('Balance:', balance); // '$10.50'
+     * ```
+     */
+    getBalanceFormatted(): Promise<string>;
+    /**
+     * Get the wallet address for the current network
+     *
+     * Returns the smart account contract address for the current chain.
+     *
+     * @returns The wallet address as a hex string
+     * @throws {Error} If no wallet exists
+     *
+     * @example
+     * ```typescript
+     * const address = await sdk.getWallet().getAddress();
+     * console.log('Address:', address);
+     * ```
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Get smart account for the current network
+     *
+     * Returns detailed information about the smart account including
+     * deployment status and network information.
+     *
+     * @returns Smart account information
+     * @throws {Error} If no smart account found for current network
+     *
+     * @example
+     * ```typescript
+     * const account = await sdk.getWallet().getSmartAccount();
+     * console.log('Contract address:', account.contractAddress);
+     * console.log('Network:', account.network);
+     * ```
+     */
+    getSmartAccount(): Promise<SmartAccount>;
+    /**
+     * Transfer ERC20 tokens
+     *
+     * Sends ERC20 tokens to a recipient address using the current network.
+     * Requires biometric authentication and sufficient balance.
+     *
+     * @param tokenAddress - ERC20 token contract address
+     * @param to - Recipient address
+     * @param amount - Amount to send (in token's smallest unit, e.g., wei)
+     * @param overrides - Optional gas overrides
+     * @returns User operation receipt with transaction details
+     * @throws {Error} If insufficient balance or transaction fails
+     *
+     * @example
+     * ```typescript
+     * import { parseUnits } from 'viem';
+     *
+     * const receipt = await sdk.getWallet().transferERC20(
+     *   '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC on Sepolia
+     *   '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+     *   parseUnits('10.5', 6) // 10.5 USDC (6 decimals)
+     * );
+     * console.log('Transaction:', receipt.transactionHash);
+     * ```
+     */
+    transferERC20(tokenAddress: string, to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+    /**
+     * Approve ERC20 tokens for spending
+     *
+     * Approves a spender to transfer tokens on your behalf.
+     * Required before interacting with DeFi protocols.
+     *
+     * @param tokenAddress - ERC20 token contract address
+     * @param spender - Address allowed to spend tokens
+     * @param amount - Amount to approve (in token's smallest unit)
+     * @param overrides - Optional gas overrides
+     * @returns User operation receipt with transaction details
+     * @throws {Error} If transaction fails
+     *
+     * @example
+     * ```typescript
+     * import { parseUnits } from 'viem';
+     *
+     * const receipt = await sdk.getWallet().approveERC20(
+     *   '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+     *   '0xProtocolAddress',
+     *   parseUnits('100', 6) // Approve 100 USDC
+     * );
+     * ```
+     */
+    approveERC20(tokenAddress: string, spender: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+    /**
+     * Transfer native currency (ETH)
+     *
+     * Sends native currency to a recipient address.
+     * Requires biometric authentication and sufficient balance.
+     *
+     * @param to - Recipient address
+     * @param amount - Amount to send in wei
+     * @param overrides - Optional gas overrides
+     * @returns User operation receipt with transaction details
+     * @throws {Error} If insufficient balance or transaction fails
+     *
+     * @example
+     * ```typescript
+     * import { parseEther } from 'viem';
+     *
+     * const receipt = await sdk.getWallet().transferNative(
+     *   '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+     *   parseEther('0.1') // 0.1 ETH
+     * );
+     * ```
+     */
+    transferNative(to: string, amount: bigint, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+    /**
+     * Execute arbitrary contract call
+     *
+     * Executes a custom contract interaction with full control over
+     * the target address, value, and calldata.
+     *
+     * @param call - Execute call parameters
+     * @param overrides - Optional gas overrides
+     * @returns User operation receipt with transaction details
+     * @throws {Error} If transaction fails
+     *
+     * @example
+     * ```typescript
+     * import { encodeFunctionData } from 'viem';
+     *
+     * const receipt = await sdk.getWallet().executeCall({
+     *   to: '0xContractAddress',
+     *   value: 0n,
+     *   data: encodeFunctionData({
+     *     abi: contractABI,
+     *     functionName: 'someFunction',
+     *     args: [arg1, arg2]
+     *   })
+     * });
+     * ```
+     */
+    executeCall(call: ExecuteCall, overrides?: GasOverrides): Promise<UserOperationReceipt>;
+}
+
+/**
+ * Storage access class for persistent app storage
+ */
+declare class StorageAccess {
+    private sdk;
+    constructor(sdk: FrontierSDK);
+    /**
+     * Get data from persistent storage
+     * Requires permission: storage:get or storage:*
+     */
+    get(key: string): Promise<any>;
+    /**
+     * Store data persistently
+     * Requires permission: storage:set or storage:*
+     */
+    set(key: string, value: any): Promise<void>;
+    /**
+     * Remove data from persistent storage
+     * Requires permission: storage:remove or storage:*
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clear all data from persistent storage
+     * Requires permission: storage:clear or storage:*
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Chain configuration information
+ */
+interface ChainConfig {
+    /** Chain ID */
+    id: number;
+    /** Chain name */
+    name: string;
+    /** Network identifier */
+    network: string;
+    /** Native currency information */
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    /** RPC URL */
+    rpcUrl: string;
+    /** Block explorer information */
+    blockExplorer: {
+        name: string;
+        url: string;
+    };
+    /** Whether this is a testnet */
+    testnet: boolean;
+}
+/**
+ * Chain access class for interacting with blockchain networks
+ *
+ * This class provides methods to:
+ * - Query current network information
+ * - Get available networks
+ * - Switch between networks
+ * - Get full chain configuration
+ *
+ * All methods require appropriate permissions.
+ */
+declare class ChainAccess {
+    private sdk;
+    constructor(sdk: FrontierSDK);
+    /**
+     * Get the current network name
+     *
+     * Returns the network identifier for the currently active chain
+     * (e.g., 'base', 'base-sepolia', 'ethereum').
+     *
+     * @returns Network identifier string
+     *
+     * @example
+     * ```typescript
+     * const network = await sdk.getChain().getCurrentNetwork();
+     * console.log('Current network:', network); // 'base-sepolia'
+     * ```
+     */
+    getCurrentNetwork(): Promise<string>;
+    /**
+     * Get all available networks
+     *
+     * Returns a list of network identifiers that the app can switch to.
+     *
+     * @returns Array of network identifier strings
+     *
+     * @example
+     * ```typescript
+     * const networks = await sdk.getChain().getAvailableNetworks();
+     * console.log('Available networks:', networks); // ['base', 'base-sepolia']
+     * ```
+     */
+    getAvailableNetworks(): Promise<string[]>;
+    /**
+     * Switch to a different network
+     *
+     * Changes the active blockchain network. This will affect all subsequent
+     * wallet operations and contract interactions.
+     *
+     * @param network - The network identifier to switch to
+     * @throws {Error} If the network is not available or switching fails
+     *
+     * @example
+     * ```typescript
+     * await sdk.getChain().switchNetwork('base');
+     * console.log('Switched to Base mainnet');
+     * ```
+     */
+    switchNetwork(network: string): Promise<void>;
+    /**
+     * Get full chain configuration for current network
+     *
+     * Returns detailed configuration including chain ID, RPC URLs,
+     * block explorer, and native currency information.
+     *
+     * @returns Complete chain configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = await sdk.getChain().getCurrentChainConfig();
+     * console.log('Chain ID:', config.id);
+     * console.log('Block explorer:', config.blockExplorer.url);
+     * ```
+     */
+    getCurrentChainConfig(): Promise<ChainConfig>;
+}
+
+/**
+ * Basic user information
+ */
+interface User {
+    /** Unique user identifier */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's first name (optional) */
+    firstName?: string;
+    /** User's last name (optional) */
+    lastName?: string;
+    /** Username (optional) */
+    username?: string;
+}
+/**
+ * Detailed user profile information
+ */
+interface UserProfile {
+    /** Profile ID */
+    id: number;
+    /** Associated user ID */
+    user: number;
+    /** First name */
+    firstName: string;
+    /** Last name */
+    lastName: string;
+    /** Nickname */
+    nickname: string;
+    /** Profile picture URL */
+    profilePicture: string;
+    /** Phone number */
+    phoneNumber: string;
+    /** Community identifier */
+    community: string;
+    /** Community name */
+    communityName: string;
+    /** Organization name */
+    organization: string;
+    /** Role in organization */
+    organizationRole: string;
+    /** Social media site */
+    socialSite: string;
+    /** Social media handle */
+    socialHandle: string;
+    /** GitHub username */
+    githubHandle: string;
+    /** Current work description */
+    currentWork: string;
+    /** Notable work achievements */
+    notableWork: string;
+    /** Whether user wants to receive updates */
+    receiveUpdates: boolean;
+    /** Notification preference: community events */
+    notificationCommunityEvent: boolean;
+    /** Notification preference: tower events */
+    notificationTowerEvent: boolean;
+    /** Notification preference: upcoming events */
+    notificationUpcomingEvent: boolean;
+    /** Notification preference: tweet picked */
+    notificationTweetPicked: boolean;
+    /** Notification preference: event invites */
+    notifyEventInvites: boolean;
+    /** Whether user opted in for SMS */
+    optInSms: boolean;
+    /** How user heard about the platform */
+    howDidYouHearAboutUs: string;
+    /** User's bragging statement */
+    braggingStatement: string;
+    /** User's contribution statement */
+    contributionStatement: string;
+    /** Whether user has a usable password */
+    hasUsablePassword: string;
+}
+/**
+ * User access class for interacting with user information
+ *
+ * This class provides methods to:
+ * - Get current user details
+ * - Get detailed user profiles
+ *
+ * All methods require appropriate permissions and authentication.
+ */
+declare class UserAccess {
+    private sdk;
+    constructor(sdk: FrontierSDK);
+    /**
+     * Get current user details
+     *
+     * Returns basic information about the currently authenticated user,
+     * including their ID, email, and name.
+     *
+     * @returns User object with basic information
+     * @throws {Error} If user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const user = await sdk.getUser().getDetails();
+     * console.log('User email:', user.email);
+     * console.log('User name:', `${user.firstName} ${user.lastName}`);
+     * ```
+     */
+    getDetails(): Promise<User>;
+    /**
+     * Get user profile by ID
+     *
+     * Returns detailed profile information for a specific user,
+     * including social media handles, preferences, and community information.
+     *
+     * @param id - The profile ID to fetch
+     * @returns UserProfile object with detailed information
+     * @throws {Error} If profile is not found or access is denied
+     *
+     * @example
+     * ```typescript
+     * const profile = await sdk.getUser().getProfile(123);
+     * console.log('Nickname:', profile.nickname);
+     * console.log('GitHub:', profile.githubHandle);
+     * console.log('Community:', profile.communityName);
+     * ```
+     */
+    getProfile(id: number): Promise<UserProfile>;
+}
+
+declare class FrontierSDK {
+    private requestId;
+    private pendingRequests;
+    private wallet;
+    private storage;
+    private chain;
+    private user;
+    constructor();
+    private handleMessage;
+    /**
+     * Internal request method used by access classes
+     * @internal
+     */
+    request(type: string, payload?: any): Promise<any>;
+    private notifyReady;
+    /**
+     * Get wallet access instance
+     */
+    getWallet(): WalletAccess;
+    /**
+     * Get storage access instance
+     */
+    getStorage(): StorageAccess;
+    /**
+     * Get chain access instance
+     */
+    getChain(): ChainAccess;
+    /**
+     * Get user access instance
+     */
+    getUser(): UserAccess;
+    /**
+     * Cleanup: Remove event listeners
+     * Call this when your app is being destroyed
+     */
+    destroy(): void;
+}
+
+interface SDKRequest {
+    type: string;
+    requestId: string;
+    payload?: any;
+}
+interface SDKResponse {
+    type: 'response' | 'error';
+    requestId: string;
+    result?: any;
+    error?: string;
+}
+
+export { ChainAccess, type ChainConfig, type ExecuteCall, FrontierSDK, type GasOverrides, type SDKRequest, type SDKResponse, type SmartAccount, StorageAccess, type User, UserAccess, type UserOperationReceipt, type UserProfile, WalletAccess };