mirror of https://github.com/MODSetter/SurfSense.git synced 2026-05-09 07:42:39 +02:00

API Test Bot fd9eddf7fa test: Add Vitest configuration and initial tests for the DexScreener connect form.

2026-02-01 15:05:19 +07:00

13 KiB

Raw Blame History

Story 1.2: DexScreener Connector Frontend UI

📋 Story Overview

Story ID: 1.2
Story Title: DexScreener Connector Frontend UI
Epic: SurfSense Connectors Enhancement
Priority: High
Status: ✅ Implementation Complete (2026-02-01)
Created: 2026-01-31
Depends On: Story 1.1 (Backend API)

🎯 User Story

As a SurfSense user tracking cryptocurrency markets
I want an intuitive UI to configure my DexScreener connector
So that I can easily add/manage tracked tokens and view connector status

📝 Description

Implement frontend UI components for the DexScreener connector that allows users to:

Add new DexScreener connector with token configuration
Manage tracked tokens (add, edit, remove)
View connector status and indexed data
Configure periodic sync settings
Access connector documentation

This story implements the user-facing components following SurfSense's established connector UI patterns.

✅ Acceptance Criteria

AC1: Connect Form Component ✅

User can access DexScreener connector from connector popup
Form includes connector name field (min 3 characters)
User can add multiple tokens (up to 50)
Each token has: chain selector, token address input, optional name
Form validates token addresses (40-character hex)
User can remove tokens from list
Date range selector for initial indexing
Periodic sync toggle with frequency selector
"What you get" benefits section displayed
Form submits to backend API endpoint

AC2: Token Management UI ✅

Dynamic token list with add/remove buttons
Chain selector dropdown with popular chains:
- Ethereum
- BSC (Binance Smart Chain)
- Polygon
- Arbitrum
- Optimism
- Base
- Avalanche
- Solana
Token address input with validation
Optional token name/label field
Visual feedback for validation errors
Responsive design for mobile/desktop

AC3: Connector Config Component ✅

Edit mode for existing connector
Update connector name
Add/remove tokens from tracked list
View current token configuration
Save changes button
Cancel/discard changes option

AC4: Connector Benefits ✅

Display benefits list in connect form
Benefits include:
- "Real-time cryptocurrency trading pair data"
- "Track prices, volume, and liquidity across multiple DEXs"
- "Search and analyze token market data with AI"
- "Monitor your crypto portfolio with automated updates"
- "Access historical price and volume trends"

AC5: Documentation ✅

MDX documentation file created
Setup guide with screenshots
Token configuration instructions
Chain selection guide
Troubleshooting section
Link to DexScreener API docs

AC6: Integration ✅

Connector registered in connector registry
Icon/logo added to public assets
Connector appears in connector list
Form properly integrated with connector popup
Config component properly integrated

🏗️ Technical Implementation

1. Connect Form Component

File: surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/dexscreener-connect-form.tsx

Component Structure:

export const DexScreenerConnectForm: FC<ConnectFormProps> = ({ onSubmit, isSubmitting }) => {
  // State management
  const [tokens, setTokens] = useState<TokenConfig[]>([]);
  const [startDate, setStartDate] = useState<Date | undefined>();
  const [endDate, setEndDate] = useState<Date | undefined>();
  const [periodicEnabled, setPeriodicEnabled] = useState(false);
  const [frequencyMinutes, setFrequencyMinutes] = useState("1440");
  
  // Form validation schema
  const formSchema = z.object({
    name: z.string().min(3),
    tokens: z.array(tokenSchema).min(1).max(50),
  });
  
  // Token management functions
  const addToken = () => { /* ... */ };
  const removeToken = (index: number) => { /* ... */ };
  const updateToken = (index: number, field: string, value: string) => { /* ... */ };
  
  // Submit handler
  const handleSubmit = async (values) => {
    await onSubmit({
      name: values.name,
      connector_type: EnumConnectorName.DEXSCREENER_CONNECTOR,
      config: { tokens: values.tokens },
      // ... other fields
    });
  };
};

Token Config Schema:

interface TokenConfig {
  chain: string;
  address: string;
  name?: string;
}

const tokenSchema = z.object({
  chain: z.string().min(1, "Chain is required"),
  address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, "Invalid token address"),
  name: z.string().optional(),
});

UI Sections:

Alert: Info about DexScreener API (no auth required)
Connector Name: Text input with validation
Token List: Dynamic list with add/remove
- Chain selector (dropdown)
- Token address input
- Optional name field
- Remove button
Add Token Button: Add new token to list
Indexing Configuration:
- Date range selector
- Periodic sync toggle
- Frequency selector
Benefits Section: Display connector benefits

2. Connector Config Component

File: surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/dexscreener-config.tsx

Component Structure:

export const DexScreenerConfig: FC<ConnectorConfigProps> = ({ 
  connector, 
  onConfigChange, 
  onNameChange 
}) => {
  const [tokens, setTokens] = useState<TokenConfig[]>(
    connector.config?.tokens || []
  );
  const [name, setName] = useState(connector.name || "");
  
  // Update handlers
  const handleTokensChange = (newTokens: TokenConfig[]) => {
    setTokens(newTokens);
    onConfigChange({ ...connector.config, tokens: newTokens });
  };
  
  const handleNameChange = (newName: string) => {
    setName(newName);
    onNameChange?.(newName);
  };
};

UI Sections:

Connector Name: Editable text input
Token Configuration:
- List of current tokens
- Add/remove token functionality
- Edit token details

3. Connector Benefits

File: surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts

Add to benefits object:

DEXSCREENER_CONNECTOR: [
  "Real-time cryptocurrency trading pair data from multiple DEXs",
  "Track token prices, volume, and liquidity across chains",
  "Search and analyze market data with AI-powered insights",
  "Monitor your crypto portfolio with automated updates",
  "Access historical price trends and trading volumes",
],

4. Connector Registry

Files to Update:

surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx

Register Components:

// In connect-forms/index.tsx
import { DexScreenerConnectForm } from "./components/dexscreener-connect-form";

// Add to component map
case EnumConnectorName.DEXSCREENER_CONNECTOR:
  return <DexScreenerConnectForm {...props} />;

// In connector-configs/index.tsx
import { DexScreenerConfig } from "./components/dexscreener-config";

// Add to component map
case EnumConnectorName.DEXSCREENER_CONNECTOR:
  return <DexScreenerConfig {...props} />;

5. Documentation

File: surfsense_web/content/docs/connectors/dexscreener.mdx

Structure:

---
title: DexScreener
description: Connect DexScreener trading pair data to SurfSense
---

# DexScreener Integration Setup Guide

## How it works
- Fetches real-time trading pair data
- Tracks prices, volume, liquidity
- No API key required

## Authorization
No authentication needed - DexScreener API is public.

## Connecting to SurfSense
1. Navigate to Connector Dashboard
2. Select DexScreener Connector
3. Configure tracked tokens:
   - Select blockchain network
   - Enter token contract address
   - Add optional label
4. Configure sync settings
5. Click Connect

## What Gets Indexed
- Token pair information
- Price data (USD, native)
- Volume metrics (24h, 6h, 1h)
- Liquidity information
- DEX information

6. Assets

Files to Add:

surfsense_web/public/connectors/dexscreener.svg - Connector icon

Icon Requirements:

SVG format
24x24px viewBox
Monochrome design
Matches SurfSense design system

7. Enum Registration

File: surfsense_web/contracts/enums/connector.ts

Add to EnumConnectorName:

export enum EnumConnectorName {
  // ... existing connectors
  DEXSCREENER_CONNECTOR = "DEXSCREENER_CONNECTOR",
}

🔗 Dependencies

Internal Dependencies

Story 1.1 (Backend API) - MUST BE COMPLETED FIRST
@/components/ui/* - ShadCN UI components
@/contracts/enums/connector - Connector enums
React Hook Form - Form management
Zod - Validation schema

External Dependencies

None (DexScreener API is public)

📊 Data Models

Token Configuration

interface TokenConfig {
  chain: string;          // Blockchain network
  address: string;        // Token contract address (0x...)
  name?: string;          // Optional display name
}

Form Submission

interface DexScreenerConnectorSubmission {
  name: string;
  connector_type: "DEXSCREENER_CONNECTOR";
  config: {
    tokens: TokenConfig[];
  };
  is_indexable: true;
  periodic_indexing_enabled: boolean;
  indexing_frequency_minutes: number | null;
  startDate?: Date;
  endDate?: Date;
}

🧪 Testing Strategy

Unit Tests

Token validation logic
Add/remove token functionality
Form submission with valid data
Form validation with invalid data
Chain selector options
Token address format validation

Integration Tests

Form submission to backend API
Config component updates connector
Benefits display correctly
Documentation renders properly

Manual Testing

Add connector with single token
Add connector with multiple tokens (10+)
Edit existing connector
Remove tokens from config
Test all chain options
Verify responsive design
Test form validation errors

🎨 UI/UX Considerations

Design Patterns

Follow Luma connector UI patterns
Use consistent spacing and typography
Responsive design for mobile/tablet/desktop
Clear validation error messages
Loading states during submission

User Flow

User opens connector popup
Selects "DexScreener" from list
Enters connector name
Adds first token (chain + address)
Optionally adds more tokens
Configures sync settings
Reviews benefits
Clicks "Connect"
Sees success message

Error Handling

Invalid token address format
Duplicate tokens
Maximum tokens exceeded (50)
Network errors during submission
Backend validation errors

📈 Success Metrics

User can add DexScreener connector in < 2 minutes
Form validation prevents invalid submissions
Token management is intuitive
Documentation is clear and helpful
UI is responsive on all devices

🚀 Deployment Plan

Phase 1: Component Development

Create connect form component
Create config component
Add connector benefits
Register in connector registry

Phase 2: Documentation & Assets

Write MDX documentation
Add connector icon
Update connector list

Phase 3: Testing & QA

Unit tests
Integration tests
Manual testing
Bug fixes

Phase 4: Release

Merge to main branch
Deploy to staging
Verify functionality
Deploy to production

📚 Documentation Requirements

Component documentation (JSDoc)
User guide (MDX)
Developer notes for future maintenance
Screenshot examples in docs

🔒 Security Considerations

Token addresses validated on frontend
No sensitive data stored in config
HTTPS for all API calls
Input sanitization for token names

✅ Definition of Done

All acceptance criteria met
Components implemented and tested
Documentation complete
Code reviewed and approved
Merged to main branch
Deployed to production
User can successfully add DexScreener connector
Connector appears in connector list
Token management works correctly

Backend Story: Story 1.1
Luma Reference: surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/luma-connect-form.tsx
Connector Docs: surfsense_web/content/docs/connectors/

💡 Implementation Notes

DexScreener API is public (no auth required)
Token addresses must be valid EVM addresses (0x + 40 hex chars)
Support up to 50 tokens per connector
Chain list may need updates as new chains are added to DexScreener
Consider adding token search/autocomplete in future iteration

13 KiB Raw Blame History