# Claude Code Setup

Learn how to setup the Claude Code extension for VS Code to work effectively with Tomba API development.

## Quick Use

### Direct Documentation Reference

In the Claude Code chat panel, reference our documentation:

```
Please analyze the Tomba API documentation at https://docs.tomba.io/llms.txt and help me implement email verification in my React component with proper TypeScript types.
```

### Contextual Code Assistance

Select code in your editor and ask Claude Code:

```
@docs Based on the Tomba API documentation, refactor this email validation function to use Tomba's email verifier endpoint instead of regex validation.
```

## Installation & Setup

### 1. Install Claude Code Extension

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Claude Code"
4. Install the official Claude Code extension
5. Sign in to your Anthropic account

### 2. Project Configuration

Create a `.claude` directory in your project root:

```bash
mkdir .claude
```

Download Tomba API documentation:

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

### 3. Workspace Settings

Add Claude Code settings to your VS Code workspace settings:

```json
{
    "claude.contextFiles": [".claude/tomba-api.md"],
    "claude.systemPrompt": "You are a helpful coding assistant. When working with email-related APIs, prioritize using Tomba API patterns from the provided documentation. Always include proper authentication headers and error handling.",
    "claude.autoContext": {
        "includeWorkspace": true,
        "includeOpenFiles": true,
        "maxFiles": 10
    }
}
```

## Claude Code Features

### 1. Inline Code Generation

Use Claude Code directly in your editor:

1. **Select code** you want to modify
2. **Right-click** and select "Ask Claude"
3. **Type your request** with context

**Example**:

```typescript
// Select this basic email validation
function validateEmail(email: string): boolean {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email);
}

// Ask Claude: "Replace this with Tomba API email verification"
```

### 2. Chat Panel Integration

Open the Claude Code chat panel and reference files:

```
@file:src/types/api.ts @docs

Based on the Tomba API documentation, update my TypeScript interfaces to match all API response types exactly.
```

### 3. Multi-file Context

Work across multiple files:

```
@file:src/services/email.ts @file:src/utils/api.ts @docs

I need to refactor my email service to use Tomba API. The current service is in email.ts and uses the API utility in api.ts. Please update both files to integrate Tomba email verification.
```

## Development Workflows

### 1. API Client Development

**Step 1**: Create base structure

```
@docs Create a TypeScript class for Tomba API client with these requirements:
- Authentication with API key and secret
- All endpoints from the documentation
- Proper error handling
- Rate limiting support
- TypeScript interfaces for all responses
```

**Step 2**: Add specific methods

```typescript
// Select existing class and ask:
// "Add the email verification method based on Tomba API docs"

export class TombaClient {
    // existing code...
    // Claude will add the method here
}
```

**Step 3**: Error handling

```
@file:src/client/tomba.ts @docs

Add comprehensive error handling to this Tomba client including:
- Network errors
- API errors with status codes
- Rate limit handling
- Timeout handling
- Custom error types
```

### 2. React Component Integration

**Creating Email Verification Component**:

```typescript
// Start with basic component
import React, { useState } from 'react';

interface EmailVerificationProps {
  onVerification: (result: any) => void;
}

const EmailVerification: React.FC<EmailVerificationProps> = ({ onVerification }) => {
  const [email, setEmail] = useState('');

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter email address"
      />
      <button>Verify Email</button>
    </div>
  );
};

export default EmailVerification;
```

**Ask Claude Code**:

```
@docs Complete this React component to integrate Tomba email verification:
1. Add proper TypeScript types from API documentation
2. Implement verification logic with error handling
3. Add loading states
4. Show verification results
5. Handle rate limiting
```

### 3. Express.js Integration

**Middleware Development**:

```javascript
// Basic middleware structure
const emailVerificationMiddleware = (req, res, next) => {
    // TODO: Implement Tomba verification
    next();
};

module.exports = { emailVerificationMiddleware };
```

**Ask Claude Code**:

```
@docs @file:middleware/validation.js

Complete this Express middleware to use Tomba email verification:
- Extract email from request body
- Call Tomba verification API
- Add verification result to request object
- Handle errors appropriately
- Respect rate limits
```

## Code Examples & Patterns

### 1. Async/Await Pattern

**Prompt**:

```
@docs Create an async function for Tomba email verification with:
- Proper TypeScript types
- Error handling with try/catch
- Timeout handling
- Retry logic for failed requests
```

**Generated Code**:

```typescript
import axios, { AxiosResponse } from "axios";

interface TombaVerificationResult {
    email: string;
    result: "valid" | "invalid" | "unknown";
    score: number;
    reason: string;
    // ... other fields from API docs
}

interface TombaApiError {
    error: string;
    message: string;
    status: number;
}

class TombaClient {
    private apiKey: string;
    private secretKey: string;
    private baseUrl = "https://api.tomba.io/v1";

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

    async verifyEmail(
        email: string,
        options: { timeout?: number; retries?: number } = {},
    ): Promise<TombaVerificationResult> {
        const { timeout = 30000, retries = 3 } = options;

        for (let attempt = 1; attempt <= retries; attempt++) {
            try {
                const response: AxiosResponse<TombaVerificationResult> =
                    await axios.get(`${this.baseUrl}/email-verifier`, {
                        params: { email },
                        headers: {
                            "X-Tomba-Key": this.apiKey,
                            "X-Tomba-Secret": this.secretKey,
                        },
                        timeout,
                    });

                return response.data;
            } catch (error) {
                if (axios.isAxiosError(error)) {
                    const apiError = error.response?.data as TombaApiError;

                    // Don't retry on client errors
                    if (error.response?.status && error.response.status < 500) {
                        throw new Error(
                            `Tomba API error: ${apiError?.message || error.message}`,
                        );
                    }

                    // Retry on server errors
                    if (attempt === retries) {
                        throw new Error(
                            `Tomba API failed after ${retries} attempts: ${error.message}`,
                        );
                    }

                    // Wait before retry (exponential backoff)
                    await new Promise((resolve) =>
                        setTimeout(resolve, Math.pow(2, attempt) * 1000),
                    );
                } else {
                    throw error;
                }
            }
        }

        throw new Error("Unexpected error in email verification");
    }
}
```

### 2. React Hook Pattern

**Prompt**:

```
@docs Create a React hook for Tomba email verification with:
- Loading states
- Error handling
- Caching with React Query
- TypeScript support
```

### 3. Node.js Service Pattern

**Prompt**:

```
@docs Create a Node.js service class for Tomba operations with:
- Connection pooling
- Rate limiting
- Caching with Redis
- Comprehensive logging
- Health checks
```

## Advanced Features

### 1. Code Generation from Selection

Select existing code and enhance it:

```typescript
// Select this basic function
async function processEmails(emails: string[]) {
    return emails.map((email) => ({ email, valid: true }));
}

// Ask: "Enhance this with Tomba bulk verification using the API documentation"
```

### 2. Refactoring Assistance

```typescript
// Select existing email validation logic
if (email.includes("@") && email.includes(".")) {
    // basic validation
    return true;
}

// Ask: "Replace this with proper Tomba email verification"
```

### 3. Test Generation

```
@file:src/services/tomba.ts @docs

Generate comprehensive Jest tests for this Tomba service including:
- Unit tests for all methods
- Mock API responses
- Error scenario testing
- Rate limit testing
- Integration tests
```

## Best Practices

### 1. Structured Prompts

Use clear, specific prompts:

```
Context: Building user registration system
Task: Integrate Tomba email verification
Requirements:
- Real-time validation during form input
- Fallback for API failures
- User-friendly error messages
- TypeScript throughout

@docs Please implement email verification for my registration form
```

### 2. Incremental Development

Build features step by step:

```
Step 1: @docs Create basic Tomba client class
Step 2: Add error handling to the client
Step 3: Add rate limiting logic
Step 4: Create React hook wrapper
Step 5: Add caching layer
```

### 3. Code Review Integration

```
@file:src/api/tomba.ts @docs

Please review this Tomba integration for:
- Security best practices
- Performance optimizations
- Error handling completeness
- TypeScript type safety
- Code maintainability
```

## Troubleshooting

### Extension Issues

1. **Claude Code not responding**: Restart VS Code
2. **Authentication problems**: Sign out and sign in again
3. **Context not loading**: Check file paths in settings

### Documentation Issues

1. **API docs not found**: Verify `.claude/tomba-api.md` exists
2. **Outdated information**: Re-download documentation
3. **Context too large**: Split into smaller files

### Code Generation Issues

1. **Incomplete responses**: Be more specific in prompts
2. **Wrong patterns**: Include more context about your project
3. **Type errors**: Ensure TypeScript is properly configured

## Integration with VS Code Features

### 1. IntelliSense Integration

Claude Code works with VS Code's IntelliSense:

- Type hints for generated code
- Auto-completion for Tomba API methods
- Error highlighting for incorrect usage

### 2. Debugging Support

Use Claude Code to help with debugging:

```
@file:src/debug.log @docs

I'm getting this error when calling Tomba API. Help me debug and fix the issue.
```

### 3. Git Integration

Get help with commit messages:

```
@git-diff @docs

Generate a commit message for these Tomba API integration changes.
```

## Additional Resources

- [Claude Code Extension](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-vscode)
- [VS Code Extension Guide](https://code.visualstudio.com/docs/editor/extension-marketplace)
- [Tomba API Reference](/api)
- [Authentication Guide](/authentication)