TokenTwin 🎯

Record one curl → get a typed SDK

AI-powered TypeScript SDK generator from API requests. No OpenAPI specs needed.

✨ Features

• 🎯 One-command workflow: Record API calls, generate TypeScript SDKs
• 🔒 HTTP & HTTPS support: Works with both protocols (HTTPS via MITM proxy)
• 🤖 AI-powered: Uses OpenAI GPT-4 to analyze API patterns
• 📝 Type-safe: Generates TypeScript interfaces + Zod validation schemas
• 🚀 Ready to use: Creates complete API client with Axios
• 🌐 Global install: Available anywhere via tokentwin command

🚀 Quick Start

# Install globally
npm install -g tokentwin

# Record API calls
tokentwin record

# In another terminal, make your API call
curl -x http://localhost:8899 "http://api.example.com/users"

# Generate TypeScript SDK
tokentwin generate --base-url http://api.example.com

# Use the generated SDK
import { api } from './sdk';
const users = await api.getUsers();

📖 How It Works

1. Start the Proxy

# HTTP APIs (recommended for development)
tokentwin record

# HTTPS APIs (requires --insecure flag)
tokentwin record --https

2. Capture API Calls

# HTTP example
curl -x http://localhost:8899 "http://httpbin.org/json"

# HTTPS example  
curl -x http://localhost:8899 "https://jsonplaceholder.typicode.com/todos/1" --insecure

3. Generate SDK

tokentwin generate --base-url https://jsonplaceholder.typicode.com

4. Use Generated SDK

import { api, TodoSchema } from './sdk';

// Type-safe API calls
const todo = await api.getTodoById(); // Returns Promise<Todo>

// Runtime validation
const validatedData = TodoSchema.parse(response.data);

🔧 Commands

tokentwin record [--https]

Starts proxy server on port 8899 to capture API requests.

Options:

• --https - Enable HTTPS capture (requires MITM proxy with --insecure)

Examples:

tokentwin record           # HTTP proxy
tokentwin record --https   # HTTPS MITM proxy

tokentwin generate [--base-url <url>]

Generates TypeScript SDK from captured requests.

Options:

• -b, --base-url <url> - API base URL for the generated client

Examples:

tokentwin generate --base-url https://api.example.com
tokentwin generate -b http://localhost:3000

tokentwin install-ca

Displays instructions for installing the CA certificate for trusted HTTPS capture.

🔒 HTTPS Support

TokenTwin supports HTTPS via a built-in MITM (Man-in-the-Middle) proxy:

Quick HTTPS Testing (--insecure)

# Start HTTPS proxy
tokentwin record --https

# Test with --insecure flag
curl -x http://localhost:8899 "https://jsonplaceholder.typicode.com/todos/1" --insecure

# Generate SDK
tokentwin generate --base-url https://jsonplaceholder.typicode.com

Trusted HTTPS (Install CA Certificate)

# Get CA installation instructions
tokentwin install-ca

# Follow platform-specific instructions to install CA
# Then use without --insecure flag
curl -x http://localhost:8899 "https://api.example.com/endpoint"

📁 Generated Files

sdk.ts - Complete TypeScript SDK

// Generated interfaces
interface Todo {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

// Zod schemas for validation
export const TodoSchema = z.object({
  userId: z.number(),
  id: z.number(),
  title: z.string(),
  completed: z.boolean()
});

// API client class
export class ApiClient {
  constructor(private baseUrl: string = 'https://jsonplaceholder.typicode.com') {}
  
  async getTodoById(): Promise<Todo> {
    const { data } = await axios.get(`${this.baseUrl}/todos/1`);
    return TodoSchema.parse(data);
  }
}

// Ready-to-use instance
export const api = new ApiClient();

capture.json - Raw captured data

[
  {
    "method": "GET",
    "url": "https://jsonplaceholder.typicode.com/todos/1",
    "headers": {...},
    "timestamp": "2025-09-30T22:59:06.433Z",
    "response": {
      "status": 200,
      "headers": {...},
      "body": {
        "userId": 1,
        "id": 1,
        "title": "delectus aut autem",
        "completed": false
      }
    }
  }
]

🎯 Use Cases

API Discovery & Documentation

# Discover API endpoints
tokentwin record
curl -x http://localhost:8899 "https://api.github.com/user"
curl -x http://localhost:8899 "https://api.github.com/user/repos"

# Generate comprehensive SDK
tokentwin generate --base-url https://api.github.com

Legacy API Integration

# Capture existing API calls
tokentwin record --https
./existing-curl-script.sh  # Routes through proxy

# Generate modern TypeScript SDK
tokentwin generate --base-url https://legacy-api.com

Testing & Development

# Capture local development API
tokentwin record
curl -x http://localhost:8899 "http://localhost:3000/api/users"

# Generate SDK for frontend team
tokentwin generate --base-url http://localhost:3000

⚙️ Configuration

Environment Variables

export OPENAI_API_KEY="your-openai-api-key"  # Required for SDK generation

Proxy Settings

• Port: 8899 (fixed)
• Protocol: HTTP proxy for both HTTP and HTTPS targets
• Certificates: Stored in ~/.tokentwin/ca/ for HTTPS

🔍 Troubleshooting

HTTPS Certificate Issues

# Install CA certificate for trusted connections
tokentwin install-ca

# Or use --insecure for testing
curl -x http://localhost:8899 "https://api.com/endpoint" --insecure

Port Already in Use

# Check what's using port 8899
lsof -i :8899

# Kill existing tokentwin processes
pkill -f tokentwin

OpenAI API Errors

# Ensure API key is set
echo $OPENAI_API_KEY

# Or set it temporarily
OPENAI_API_KEY="your-key" tokentwin generate --base-url https://api.com

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• OpenAI GPT-4 for intelligent TypeScript generation
• node-forge for certificate management
• Zod for runtime type validation
• Axios for HTTP client functionality

Made with ❤️ for developers who want typed SDKs without the hassle