# Cursor Setup

Learn how to setup Cursor AI editor to generate accurate Tomba API code using our comprehensive documentation.

## Quick Use

### Using Web Search in Cursor

In Cursor's chat interface, you can reference our documentation directly:

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

Create a TypeScript class for Tomba email finder with async/await patterns
```

### Using the Documentation Panel

1. Open Cursor's documentation panel
2. Add the Tomba API documentation URL: `https://docs.tomba.io/llms.txt`
3. Reference it in your prompts with `@docs`

## Project-level Setup

### Method 1: Project Documentation

Create a `.cursorrules` file in your project root:

```bash
# Download Tomba API documentation
curl -L https://docs.tomba.io/llms.txt -o .cursorrules
```

### Method 2: Custom Instructions

Create a `cursor-instructions.md` file in your project:

```bash
# Create project documentation
mkdir -p docs
curl -L https://docs.tomba.io/llms.txt -o docs/cursor-instructions.md
```

Add this to your project's `.cursor/` directory:

```json
{
    "includeInContext": ["docs/cursor-instructions.md"],
    "customInstructions": "Use the Tomba API documentation in docs/cursor-instructions.md for all API-related code generation. Follow the authentication patterns and endpoint structures defined in the documentation."
}
```

## Cursor-Specific Features

### 1. Multi-file Editing

Use Cursor's multi-file editing with Tomba API:

**Prompt:**

```
@docs Create a complete Tomba API client with separate files for:
- Authentication module
- Email finder service
- Email verifier service
- Error handling utilities
- TypeScript types
```

### 2. Codebase Chat

Reference your entire codebase when working with Tomba API:

```
@codebase How can I integrate Tomba email verification into my existing user registration flow?
```

### 3. Smart Rewrites

Select existing code and ask Cursor to enhance it:

```
@docs Refactor this email validation function to use Tomba's email verifier API instead of regex
```

## Configuration

### Cursor Settings

Add these settings to enhance Tomba API code generation:

```json
{
    "cursor.general.enableInlineCompletion": true,
    "cursor.chat.includeWorkspaceInContext": true,
    "cursor.ai.model": "claude-3.5-sonnet",
    "cursor.chat.customInstructions": "When generating API code, prioritize Tomba API endpoints and follow RESTful patterns. Include proper error handling and authentication."
}
```

### Environment Variables

Set up your environment for Cursor to understand your API keys:

```bash
# Create .env.example file
echo "TOMBA_API_KEY=your_api_key_here" > .env.example
echo "TOMBA_SECRET_KEY=your_secret_key_here" >> .env.example
```

## Example Use Cases

### 1. Building an Email Finder Component

**Prompt:**

```
@docs Create a React component that uses Tomba API to find emails for a company. Include:
- Input field for domain
- Loading state
- Results display
- Error handling
- TypeScript types
```

**Generated Code:**

```typescript
import React, { useState } from 'react';

interface EmailResult {
  email: string;
  first_name: string;
  last_name: string;
  position: string;
  confidence: number;
}

interface TombaResponse {
  data: {
    emails: EmailResult[];
  };
  meta: {
    total: number;
  };
}

const EmailFinder: React.FC = () => {
  const [domain, setDomain] = useState('');
  const [results, setResults] = useState<EmailResult[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const findEmails = async () => {
    if (!domain) return;

    setLoading(true);
    setError(null);

    try {
      const response = await fetch(`https://api.tomba.io/v1/domain-search?domain=${domain}`, {
        headers: {
          'X-Tomba-Key': process.env.REACT_APP_TOMBA_API_KEY!,
          'X-Tomba-Secret': process.env.REACT_APP_TOMBA_SECRET_KEY!,
        },
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data: TombaResponse = await response.json();
      setResults(data.data.emails);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'An error occurred');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="email-finder">
      <div className="input-group">
        <input
          type="text"
          value={domain}
          onChange={(e) => setDomain(e.target.value)}
          placeholder="Enter company domain (e.g., tomba.io)"
          className="domain-input"
        />
        <button onClick={findEmails} disabled={loading || !domain}>
          {loading ? 'Searching...' : 'Find Emails'}
        </button>
      </div>

      {error && <div className="error">{error}</div>}

      {results.length > 0 && (
        <div className="results">
          <h3>Found {results.length} emails:</h3>
          {results.map((email, index) => (
            <div key={index} className="email-result">
              <strong>{email.email}</strong>
              <div>{email.first_name} {email.last_name}</div>
              <div>{email.position}</div>
              <div>Confidence: {email.confidence}%</div>
            </div>
          ))}
        </div>
      )}
    </div>
  );
};

export default EmailFinder;
```

### 2. API Client with Error Handling

**Prompt:**

```
@docs Create a robust Tomba API client class with:
- Rate limiting
- Retry logic
- Comprehensive error handling
- TypeScript support
- All major endpoints
```

### 3. Integration with Form Validation

**Prompt:**

```
@docs Create a form validation hook that uses Tomba email verifier to validate email addresses in real-time
```

## Advanced Features

### 1. Custom Commands

Create custom Cursor commands for Tomba API:

```json
{
    "commands": [
        {
            "name": "Generate Tomba Email Finder",
            "command": "@docs Create an email finder function using Tomba API for the selected domain variable"
        },
        {
            "name": "Add Tomba Verification",
            "command": "@docs Add Tomba email verification to the selected email input field"
        }
    ]
}
```

### 2. Code Actions

Set up code actions for common Tomba API patterns:

```json
{
    "codeActions": {
        "tomba.addEmailVerification": {
            "title": "Add Tomba Email Verification",
            "kind": "refactor"
        }
    }
}
```

## Best Practices

### 1. Use Contextual Prompts

Instead of generic requests, provide context:

```
@docs In my user registration form, add Tomba email verification before allowing signup
```

### 2. Leverage Cursor's Understanding

Let Cursor understand your project structure:

```
@codebase @docs Integrate Tomba email finder into my existing user management system
```

### 3. Iterative Development

Build incrementally:

```
@docs Start with a basic Tomba email verification function
```

Then enhance:

```
@docs Add caching and rate limiting to the previous email verification function
```

## Troubleshooting

### Documentation Not Loading

1. Check your internet connection
2. Verify the URL: `https://docs.tomba.io/llms.txt`
3. Try refreshing the documentation panel

### API Code Not Working

1. Ensure your API keys are properly set
2. Check the generated endpoint URLs
3. Verify authentication headers are included

### Context Issues

1. Make sure `.cursorrules` is in your project root
2. Check that custom instructions are properly formatted
3. Try restarting Cursor after configuration changes

## Additional Resources

- [Cursor Documentation](https://docs.cursor.com/)
- [Tomba API Reference](/api)
- [Authentication Guide](/authentication)
- [Rate Limits](/rate-limits)