Editor Setup

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:

Code
 
@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:

Code
 
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:

Code
 
mkdir -p .windsurf

Download documentation:

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

Create configuration file .windsurf/config.json:

Code
 
{
    "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:

Code
 
# 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:

Code
 
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:

Code
 
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:

Code
 
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:

Code
 
// 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:

Code
 
# .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:

Code
 
{
    "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:

Code
 
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:

Code
 
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:

Code
 
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:

Code
 
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:

Code
 
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:

Code
 
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

Code
 
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

Code
 
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
• Tomba API Reference
• Authentication Guide
• Best Practices