Add Nounish Auctions fidget

.env.example

@@ -38,6 +38,7 @@ APP_MNEMONIC = ''
 NEYNAR_API_KEY = ''
 SUPABASE_SERVICE_KEY = ''
 YOUTUBE_API_KEY = ''
+MORALIS_API_KEY = ''
 
 # These are specific to the environment
 # and so need to be configured locally
@@ -47,6 +48,8 @@ NEXT_PUBLIC_SUPABASE_URL = ''
 NEXT_PUBLIC_SUPABASE_ANON_KEY = ''
 NEXT_PUBLIC_PRIVY_API_KEY = ''
 NEXT_PUBLIC_ALCHEMY_API_KEY = ''  # Also used for the Nouns Home fidget RPC fallback
+# Optional: used for Directory fidget (ERC20 + NFT holders)
+NEXT_PUBLIC_MORALIS_API_KEY = ''
 
 # Nouns Home fidget (optional overrides)
 # NOUNS_RPC_URL = ''

BRANCH_ANALYSIS.md

@@ -0,0 +1,260 @@
+# Branch Analysis: `codex/update-token-directory-api` vs `canary`
+
+## Summary
+- **Total Changes**: 38 files changed, 6,236 insertions(+), 31 deletions(-)
+- **Main Feature**: New Token Directory fidget with API endpoint for displaying token/NFT holders, Farcaster channel members, and CSV-uploaded directories
+
+---
+
+## Itemized Changes
+
+### 1. Core Feature Files
+
+#### 1.1 New Directory Fidget Component
+- **File**: `src/fidgets/token/Directory.tsx`
+- **Size**: 2,373 lines (new file)
+- **Purpose**: Main React component for displaying directory of token holders, Farcaster channel members, or CSV-uploaded users
+- **Key Features**:
+  - Three data sources: token holders, Farcaster channels, CSV uploads
+  - Two layout styles: cards and list
+  - Multiple sort options (token holdings, followers)
+  - Pagination
+  - Real-time data fetching with debouncing
+  - Settings backfill from `lastFetchSettings`
+
+#### 1.2 New API Endpoint
+- **File**: `src/pages/api/token/directory.ts`
+- **Size**: 1,105 lines (new file)
+- **Purpose**: Server-side API for fetching token holder data
+- **Key Features**:
+  - Supports ERC20 tokens and NFTs
+  - Multiple networks: Base, Polygon, Ethereum Mainnet
+  - Integrates with Moralis and Alchemy APIs
+  - Fetches ENS metadata
+  - Enriches with Neynar profile data
+  - Aggregates holders by FID
+
+### 2. Supporting Utility Modules
+
+#### 2.1 Data Transformation
+- **File**: `src/common/data/api/token/transform.ts` (316 lines)
+- **Purpose**: Transforms raw holder data into directory member format
+- **Functions**: `transformAndAggregate`, `extractNeynarProfileData`, `extractPrimaryAddress`
+
+#### 2.2 Type Definitions
+- **File**: `src/common/data/api/token/types.ts` (113 lines)
+- **Purpose**: Centralized TypeScript types for directory API
+
+#### 2.3 Utility Functions
+- **File**: `src/common/data/api/token/utils.ts` (137 lines)
+- **Purpose**: Helper functions (address normalization, balance parsing, social record parsing)
+
+#### 2.4 ENS Enrichment
+- **File**: `src/common/data/api/token/enrichEns.ts` (153 lines)
+- **Purpose**: Fetches ENS metadata using Enstate.rs and wagmi
+
+#### 2.5 Neynar Enrichment
+- **File**: `src/common/data/api/token/enrichNeynar.ts` (68 lines)
+- **Purpose**: Fetches Farcaster profile data via Neynar API
+
+#### 2.6 Moralis Integration
+- **File**: `src/common/data/api/token/fetchMoralis.ts` (121 lines)
+- **Purpose**: Fetches ERC20 token holders from Moralis API
+
+#### 2.7 Dependency Injection
+- **File**: `src/common/data/api/token/dependencies.ts` (39 lines)
+- **Purpose**: Provides dependency injection for testing
+
+### 3. Infrastructure Changes
+
+#### 3.1 FidgetWrapper Enhancement
+- **File**: `src/common/fidgets/FidgetWrapper.tsx` (+99 lines, -31 lines)
+- **Changes**: Added settings backfill logic using `lastFetchSettings` from fidget data
+- **Purpose**: Automatically populates empty settings from previous fetch configuration
+
+#### 3.2 New API Endpoints
+- **File**: `src/pages/api/farcaster/neynar/bulk-address.ts` (34 lines)
+- **Purpose**: Bulk Farcaster user lookup by Ethereum addresses
+
+### 4. Documentation
+
+#### 4.1 API Cleanup Opportunities
+- **File**: `docs/API_CLEANUP_OPPORTUNITIES.md` (569 lines)
+- **Purpose**: Documents potential API simplifications
+
+#### 4.2 Data Field Patterns
+- **File**: `docs/SYSTEMS/FIDGETS/DATA_FIELD_PATTERNS.md` (625 lines)
+- **Purpose**: Documents fidget data field patterns
+
+### 5. Minor Updates
+- Updated various components to support new Directory fidget
+- Added SVG icons (ens.svg, etherscan.svg, github.svg)
+- Updated package.json dependencies
+- Added environment variable examples
+
+---
+
+## Areas of Unnecessary Complexity
+
+### 🔴 Critical Issues
+
+#### 1. **Massive Single File: Directory.tsx (2,373 lines)**
+   - **Problem**: One component file contains:
+     - Component logic (45+ React hooks)
+     - Data fetching logic (3 different sources)
+     - CSV parsing logic
+     - Data transformation logic
+     - UI rendering (cards + list views)
+     - Helper functions (duplicated from API)
+   - **Impact**: Extremely difficult to maintain, test, and understand
+   - **Recommendation**: Split into:
+     - `Directory.tsx` (main component, ~200 lines)
+     - `useDirectoryData.ts` (data fetching hook)
+     - `useCsvParser.ts` (CSV parsing logic)
+     - `DirectoryCardView.tsx` (card layout)
+     - `DirectoryListView.tsx` (list layout)
+     - `directoryUtils.ts` (shared utilities)
+
+#### 2. **Duplicate Logic Between Component and API**
+   - **Problem**: Functions duplicated in both files:
+     - `parseSocialRecord` (exists in both Directory.tsx and API/utils.ts)
+     - `extractNeynarPrimaryAddress` (exists in both Directory.tsx and transform.ts)
+     - `extractNeynarSocialAccounts` (exists in both Directory.tsx and transform.ts)
+     - `normalizeAddress` (exists in both, though API version is exported)
+   - **Impact**: Code duplication, maintenance burden, potential inconsistencies
+   - **Recommendation**: Move all shared utilities to `src/common/data/api/token/utils.ts` and import
+
+#### 3. **Complex State Management in Component**
+   - **Problem**: Component uses 45+ React hooks (useState, useEffect, useCallback, useMemo, useRef)
+   - **Specific Issues**:
+     - Multiple interdependent useEffects
+     - Complex dependency arrays
+     - State synchronization logic scattered throughout
+     - AbortController management mixed with data fetching
+   - **Impact**: Difficult to debug, potential race conditions, performance issues
+   - **Recommendation**: Extract to custom hooks:
+     - `useDirectoryFetch.ts` (handles all fetching logic)
+     - `useDirectoryState.ts` (manages local UI state)
+     - `useDirectoryPagination.ts` (handles pagination)
+
+#### 4. **API Endpoint Too Large (1,105 lines)**
+   - **Problem**: Single API handler contains:
+     - Multiple data source fetchers (Moralis, Alchemy)
+     - ENS enrichment logic
+     - Neynar enrichment logic
+     - Data transformation
+     - Error handling
+   - **Impact**: Hard to test individual pieces, difficult to maintain
+   - **Recommendation**: Already partially modularized, but could further split:
+     - Keep main handler thin (~100 lines)
+     - Move fetchers to separate modules (already done)
+     - Create orchestration layer
+
+### 🟡 Moderate Issues
+
+#### 5. **Overly Complex CSV Parsing**
+   - **Problem**: CSV parsing logic embedded in component (~200 lines)
+   - **Issues**:
+     - Header detection logic
+     - Multiple type handling (address, fid, username)
+     - Fallback parsing logic
+     - Inline chunking utilities
+   - **Recommendation**: Extract to `src/common/data/api/token/csvParser.ts`
+
+#### 6. **Settings Backfill Logic in FidgetWrapper**
+   - **Problem**: Generic backfill logic added to FidgetWrapper (~70 lines)
+   - **Issues**:
+     - Uses `isEqual` from lodash for deep comparison
+     - Complex serialization/deserialization logic
+     - May affect all fidgets, not just Directory
+   - **Impact**: Could cause unexpected behavior in other fidgets
+   - **Recommendation**: Move to Directory-specific hook or make opt-in
+
+#### 7. **Multiple Data Source Handling**
+   - **Problem**: Three completely different data sources handled in one component
+   - **Issues**:
+     - Different fetch functions for each source
+     - Different data transformation logic
+     - Different error handling
+   - **Recommendation**: Create abstraction layer:
+     - `DirectoryDataSource` interface
+     - `TokenHoldersSource`, `FarcasterChannelSource`, `CsvSource` implementations
+     - Unified `fetchDirectoryData` function
+
+#### 8. **Complex Data Enrichment Pipeline**
+   - **Problem**: Multiple enrichment steps with conditional logic
+   - **Issues**:
+     - ENS enrichment (Enstate.rs + wagmi fallback)
+     - Neynar enrichment (batched lookups)
+     - Social account extraction
+     - Primary address resolution
+   - **Recommendation**: Create enrichment pipeline:
+     - `EnrichmentPipeline` class
+     - Individual enrichment steps as plugins
+     - Configurable enrichment options
+
+### 🟢 Minor Issues
+
+#### 9. **Type Safety Issues**
+   - **Problem**: Extensive use of `any` types in CSV parsing and Neynar response handling
+   - **Recommendation**: Add proper types for all API responses
+
+#### 10. **Hardcoded Constants**
+   - **Problem**: Magic numbers and strings scattered throughout:
+     - `PAGE_SIZE = 100`
+     - `CHANNEL_FETCH_DEBOUNCE_MS = 800`
+     - `STALE_AFTER_MS = 60 * 60 * 1000`
+     - Batch sizes (25, 50, 100)
+   - **Recommendation**: Move to config file or constants module
+
+#### 11. **Error Handling Inconsistency**
+   - **Problem**: Different error handling patterns:
+     - Some functions throw errors
+     - Some return empty objects/arrays
+     - Some log and continue
+   - **Recommendation**: Standardize error handling strategy
+
+#### 12. **Excessive Console Logging**
+   - **Problem**: Many `console.log` statements throughout code
+   - **Recommendation**: Use proper logging library or remove debug logs
+
+---
+
+## Recommendations Summary
+
+### Immediate Actions (High Priority)
+1. **Split Directory.tsx** into smaller, focused modules
+2. **Remove duplicate code** between component and API
+3. **Extract data fetching** to custom hooks
+4. **Create data source abstraction** for the three sources
+
+### Short-term Improvements (Medium Priority)
+5. Extract CSV parsing to separate module
+6. Simplify FidgetWrapper backfill logic (make opt-in)
+7. Standardize error handling
+8. Add proper TypeScript types
+
+### Long-term Refactoring (Low Priority)
+9. Create enrichment pipeline abstraction
+10. Move constants to config
+11. Implement proper logging
+12. Add comprehensive unit tests
+
+---
+
+## Code Metrics
+
+- **Directory.tsx**: 2,373 lines, ~179 functions/components
+- **API endpoint**: 1,105 lines, ~70 functions
+- **Total new code**: ~6,200 lines
+- **React hooks in Directory**: 45+ (useState, useEffect, useCallback, useMemo, useRef)
+- **Duplicate functions**: ~5 major functions duplicated between component and API
+
+---
+
+## Testing Coverage
+
+- **Test file**: `tests/tokenDirectory.api.test.ts` (359 lines)
+- **Coverage**: API endpoint tests present
+- **Missing**: Component tests, integration tests, CSV parsing tests
+