# Windsurf Setup

Learn how to setup Windsurf IDE to work with Tomba API using AI-powered development features.

## Quick Use

### Using Windsurf Chat

In Windsurf's AI chat interface, reference our documentation:

```
@web https://docs.tomba.io/llms.txt

Create a comprehensive email validation service using Tomba API with TypeScript, including rate limiting and caching
```

### Flow Mode

Use Windsurf's Flow mode for complex integrations:

```
Flow: Build Tomba Email Service
1. Fetch docs from https://docs.tomba.io/llms.txt
2. Create TypeScript interfaces for all API responses
3. Build service class with authentication
4. Add error handling and retry logic
5. Create unit tests
6. Add integration examples
```

## Project-level Setup

### Method 1: Project Configuration

Create a `.windsurf` directory in your project:

```bash
mkdir -p .windsurf
```

Download documentation:

```bash
curl -L https://docs.tomba.io/llms.txt -o .windsurf/tomba-api.md
```

Create configuration file `.windsurf/config.json`:

```json
{
    "contextFiles": [".windsurf/tomba-api.md"],
    "aiInstructions": "When generating API code, use Tomba API patterns from the documentation. Always include proper authentication headers (X-Tomba-Key, X-Tomba-Secret) and implement rate limiting.",
    "codeGeneration": {
        "preferredLanguages": ["typescript", "python", "rust"],
        "includeTests": true,
        "includeDocumentation": true
    }
}
```

### Method 2: Workspace Instructions

Create `.windsurf/instructions.md`:

```markdown
# Tomba API Development Instructions

## Authentication

Always use these headers:

- X-Tomba-Key: API key
- X-Tomba-Secret: Secret key

## Base URL

https://api.tomba.io/v1

## Rate Limiting

- Implement exponential backoff
- Respect 429 responses
- Cache responses when appropriate

## Error Handling

- Handle network errors
- Parse API error responses
- Provide meaningful error messages
```

## Windsurf-Specific Features

### 1. Multi-Agent Collaboration

Use multiple AI agents for complex tasks:

```
Agent 1: API Client Development
- Build TypeScript client for Tomba API
- Include all endpoints from documentation
- Add comprehensive type definitions

Agent 2: Testing & Validation
- Create unit tests for all methods
- Add integration tests
- Test error scenarios

Agent 3: Documentation
- Generate API usage examples
- Create README documentation
- Add code comments
```

### 2. Flow-Based Development

Create development flows for common patterns:

**Email Verification Flow:**

```
Flow: Email Verification Service
├── Parse Tomba API docs
├── Create TypeScript interfaces
├── Build verification service
├── Add caching layer
├── Implement rate limiting
├── Create tests
└── Generate usage examples
```

**Bulk Operations Flow:**

```
Flow: Bulk Email Processing
├── Design batch processing architecture
├── Implement queue system
├── Add progress tracking
├── Handle partial failures
├── Add retry mechanisms
└── Create monitoring dashboard
```

### 3. Code Generation Templates

Create reusable templates for Tomba integrations:

```typescript
// Template: Tomba Service Base
export abstract class TombaServiceBase {
    protected readonly apiKey: string;
    protected readonly secretKey: string;
    protected readonly baseUrl = "https://api.tomba.io/v1";

    constructor(apiKey: string, secretKey: string) {
        this.apiKey = apiKey;
        this.secretKey = secretKey;
    }

    protected getHeaders(): Record<string, string> {
        return {
            "X-Tomba-Key": this.apiKey,
            "X-Tomba-Secret": this.secretKey,
            "Content-Type": "application/json",
        };
    }

    protected async makeRequest<T>(
        endpoint: string,
        options?: RequestInit,
    ): Promise<T> {
        // Implementation details
    }
}
```

## Advanced Configuration

### Environment Setup

Create comprehensive environment configuration:

```bash
# .env.development
TOMBA_API_KEY=dev_key_here
TOMBA_SECRET_KEY=dev_secret_here
TOMBA_BASE_URL=https://api.tomba.io/v1
TOMBA_TIMEOUT=30000
TOMBA_RATE_LIMIT=100

# .env.production
TOMBA_API_KEY=prod_key_here
TOMBA_SECRET_KEY=prod_secret_here
TOMBA_BASE_URL=https://api.tomba.io/v1
TOMBA_TIMEOUT=60000
TOMBA_RATE_LIMIT=1000
```

### Windsurf Workspace Settings

Configure `.windsurf/workspace.json`:

```json
{
    "version": "1.0",
    "ai": {
        "model": "claude-3.5-sonnet",
        "temperature": 0.1,
        "contextWindow": 200000,
        "customInstructions": "Focus on production-ready code with comprehensive error handling. Use TypeScript for type safety. Follow REST API best practices."
    },
    "codeGeneration": {
        "autoFormat": true,
        "addImports": true,
        "generateTests": true,
        "includeDocstrings": true
    },
    "development": {
        "autoSave": true,
        "liveReload": true,
        "typeChecking": true
    }
}
```

## Example Implementations

### 1. Complete TypeScript Client

**Prompt:**

```
Using the Tomba API documentation, create a complete TypeScript client with:

1. Full type definitions for all API responses
2. Service classes for each endpoint category
3. Request/response interceptors
4. Automatic retry with exponential backoff
5. Comprehensive error handling
6. Built-in caching
7. Rate limiting
8. Request logging
9. Unit tests for all methods
10. Integration examples
```

### 2. React Integration

**Prompt:**

```
Create a React integration for Tomba API that includes:

1. Custom hooks for email operations
2. Context provider for API configuration
3. Components for email finder and verifier
4. Loading states and error handling
5. Form validation integration
6. Caching with React Query
7. TypeScript throughout
8. Storybook stories
9. Jest tests
```

### 3. Node.js Microservice

**Prompt:**

```
Build a Node.js microservice using Tomba API with:

1. Express.js REST API
2. Input validation with Joi
3. Rate limiting middleware
4. Redis caching
5. Bull queue for background jobs
6. Comprehensive logging
7. Health checks
8. Prometheus metrics
9. Docker configuration
10. API documentation with Swagger
```

## Best Practices for Windsurf

### 1. Use Contextual Development

Provide rich context in your prompts:

```
Context: E-commerce platform user registration
Goal: Prevent fake email registrations
Constraints: Must handle 10k+ registrations/day
Requirements: Real-time validation, fallback strategies, audit logging

Using Tomba API, implement email verification in the user registration flow
```

### 2. Leverage Flow Mode

Break complex tasks into flows:

```
Flow: Email Verification System
├── Requirements Analysis
│   ├── Performance requirements
│   ├── Scalability needs
│   └── Integration points
├── Architecture Design
│   ├── Service design
│   ├── Data flow
│   └── Error handling strategy
├── Implementation
│   ├── Core service
│   ├── API endpoints
│   └── Background jobs
├── Testing
│   ├── Unit tests
│   ├── Integration tests
│   └── Performance tests
└── Deployment
    ├── Docker setup
    ├── CI/CD pipeline
    └── Monitoring
```

### 3. Use Multi-Agent Workflows

Assign specialized roles:

```
Primary Agent: Core Implementation
- Build main service classes
- Implement API calls
- Handle authentication

Quality Agent: Testing & Validation
- Generate comprehensive tests
- Validate error scenarios
- Performance testing

Documentation Agent: Documentation
- Generate API docs
- Create usage examples
- Write integration guides
```

## Integration Examples

### Express.js Middleware

```typescript
import { TombaEmailVerifier } from "./tomba-client";

export const emailVerificationMiddleware = (verifier: TombaEmailVerifier) => {
    return async (req: Request, res: Response, next: NextFunction) => {
        const { email } = req.body;

        if (!email) {
            return next();
        }

        try {
            const result = await verifier.verify(email);
            req.emailVerification = result;
            next();
        } catch (error) {
            res.status(400).json({
                error: "Email verification failed",
                details: error.message,
            });
        }
    };
};
```

### React Hook

```typescript
import { useCallback, useState } from "react";
import { useTombaClient } from "./TombaProvider";

export const useEmailVerification = () => {
    const [loading, setLoading] = useState(false);
    const [result, setResult] = useState(null);
    const [error, setError] = useState(null);
    const client = useTombaClient();

    const verify = useCallback(
        async (email: string) => {
            setLoading(true);
            setError(null);

            try {
                const verification = await client.verifyEmail(email);
                setResult(verification);
                return verification;
            } catch (err) {
                setError(err);
                throw err;
            } finally {
                setLoading(false);
            }
        },
        [client],
    );

    return { verify, loading, result, error };
};
```

## Troubleshooting

### AI Not Using Documentation

1. Verify `.windsurf/tomba-api.md` exists
2. Check workspace configuration
3. Restart Windsurf IDE
4. Clear AI context and retry

### Code Generation Issues

1. Be more specific in prompts
2. Provide additional context
3. Use Flow mode for complex tasks
4. Break large requests into smaller ones

### Performance Issues

1. Optimize context files
2. Use targeted prompts
3. Leverage caching features
4. Monitor token usage

## Additional Resources

- [Windsurf IDE Documentation](https://windsurf.ai/docs)
- [Tomba API Reference](/api)
- [Authentication Guide](/authentication)
- [Best Practices](/features)