useStellarAccount hook done | closes #7

dongle/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "kiroAgent.configureMCP": "Disabled"
+}

dongle/hooks/useStellarAccount.md

@@ -0,0 +1,135 @@
+# useStellarAccount Hook
+
+A React hook for fetching and managing Stellar account data.
+
+## Overview
+
+`useStellarAccount` provides a simple interface to fetch Stellar account information including balances, with built-in loading and error state management.
+
+## Usage
+
+```tsx
+import { useStellarAccount } from '@/hooks/useStellarAccount';
+
+function AccountDashboard() {
+  const { account, balances, loading, error } = useStellarAccount();
+
+  if (loading) return <div>Loading account data...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!account) return <div>No account connected</div>;
+
+  return (
+    <div>
+      <h2>Account: {account.account_id}</h2>
+      <h3>Balances:</h3>
+      <ul>
+        {balances.map((balance, index) => (
+          <li key={index}>
+            {balance.asset_code || 'XLM'}: {balance.balance}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## API
+
+### Parameters
+
+- `publicKey` (optional): Stellar public key to fetch account data for. If not provided, uses the public key from the Wallet Context.
+
+### Return Value
+
+```typescript
+{
+  account: StellarAccount | null;  // Full account data
+  balances: StellarBalance[];      // Array of account balances
+  loading: boolean;                // Loading state
+  error: Error | null;             // Error state
+}
+```
+
+## Types
+
+### StellarAccount
+
+```typescript
+interface StellarAccount {
+  id: string;
+  account_id: string;
+  sequence: string;
+  subentry_count: number;
+  balances: StellarBalance[];
+}
+```
+
+### StellarBalance
+
+```typescript
+interface StellarBalance {
+  asset_type: string;
+  asset_code?: string;
+  asset_issuer?: string;
+  balance: string;
+}
+```
+
+## Examples
+
+### Using with Wallet Context
+
+```tsx
+// Uses public key from wallet context automatically
+const { account, balances, loading, error } = useStellarAccount();
+```
+
+### Using with Specific Public Key
+
+```tsx
+// Fetch data for a specific account
+const { account, balances, loading, error } = useStellarAccount(
+  'GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+);
+```
+
+### Handling States
+
+```tsx
+function AccountView() {
+  const { account, balances, loading, error } = useStellarAccount();
+
+  if (loading) {
+    return <Spinner />;
+  }
+
+  if (error) {
+    return <ErrorMessage message={error.message} />;
+  }
+
+  if (!account) {
+    return <ConnectWalletPrompt />;
+  }
+
+  return <AccountDetails account={account} balances={balances} />;
+}
+```
+
+## Dependencies
+
+This hook requires:
+
+1. **Stellar Service Layer** (#6) - Provides `getAccountInfo` method
+2. **Wallet Context** (#4) - Provides global wallet state with `publicKey`
+
+## Current Status
+
+⚠️ **Placeholder Implementation**: This hook currently uses mock implementations for its dependencies. Once the Stellar Service and Wallet Context are implemented, the placeholders will be replaced with actual integrations.
+
+## Future Enhancements
+
+- Add refresh/refetch functionality
+- Add caching to reduce API calls
+- Support for real-time account updates
+- Add retry logic for failed requests

dongle/hooks/useStellarAccount.ts

@@ -0,0 +1,89 @@
+import { useState, useEffect } from 'react';
+
+// Placeholder types - will be replaced when Stellar service is implemented
+interface StellarBalance {
+  asset_type: string;
+  asset_code?: string;
+  asset_issuer?: string;
+  balance: string;
+}
+
+interface StellarAccount {
+  id: string;
+  account_id: string;
+  sequence: string;
+  subentry_count: number;
+  balances: StellarBalance[];
+}
+
+interface UseStellarAccountReturn {
+  account: StellarAccount | null;
+  balances: StellarBalance[];
+  loading: boolean;
+  error: Error | null;
+}
+
+// Placeholder for Stellar service - will be replaced with actual service from #6
+const stellarService = {
+  getAccountInfo: async (publicKey: string): Promise<StellarAccount> => {
+    // Mock implementation - replace with actual Stellar SDK call
+    throw new Error('Stellar service not yet implemented');
+  }
+};
+
+// Placeholder for Wallet context - will be replaced with actual context from #4
+const useWallet = () => {
+  // Mock implementation - replace with actual wallet context
+  return {
+    publicKey: null as string | null
+  };
+};
+
+/**
+ * Custom hook to fetch and manage Stellar account data
+ * 
+ * @param publicKey - Optional Stellar public key. If not provided, uses key from wallet context
+ * @returns Account data, balances, loading state, and error state
+ */
+export function useStellarAccount(publicKey?: string): UseStellarAccountReturn {
+  const { publicKey: walletPublicKey } = useWallet();
+  const [account, setAccount] = useState<StellarAccount | null>(null);
+  const [loading, setLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const effectivePublicKey = publicKey || walletPublicKey;
+
+  useEffect(() => {
+    if (!effectivePublicKey) {
+      setAccount(null);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+
+    const fetchAccountData = async () => {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const accountData = await stellarService.getAccountInfo(effectivePublicKey);
+        setAccount(accountData);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to fetch account data');
+        setError(error);
+        setAccount(null);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchAccountData();
+  }, [effectivePublicKey]);
+
+  return {
+    account,
+    balances: account?.balances || [],
+    loading,
+    error
+  };
+}