README-VERCEL.md

Vercel Deployment Guide

This guide covers deploying the Whisperer API endpoints to Vercel for secure, scalable production use.

Overview

The Whisperer app uses Vercel as a secure proxy for OpenAI API calls, providing:

• Secure API Key Management: Keys stored as environment variables, never in client code
• Usage Monitoring: Built-in analytics and logging
• Global CDN: Fast response times worldwide
• Cost Control: Monitor and limit API usage
• Auto-scaling: Handles traffic spikes automatically

Quick Setup

1. Install Vercel CLI (Nix + nixpkgs)

nix shell nixpkgs#nodejs_22 -c npx -y vercel --version

2. Deploy from Project Root

# From the Whisperer project directory
make deploy

# Or manually:
vercel --prod

3. Configure Environment Variables

In your Vercel dashboard or via CLI:

nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_TRANSCRIBE_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_MODEL production
# recommended value for OPENAI_CHAT_MODEL: gpt-4o-mini

API Endpoints

The deployment creates three serverless functions:

/api/chat - ChatGPT Completions

• Method: POST
• Purpose: Proxy ChatGPT API calls
• Input: JSON with messages array
• Output: ChatGPT response

/api/transcribe - Audio Transcription

• Method: POST
• Purpose: Convert audio to text via Whisper
• Input: Multipart form with audio file
• Output: Transcribed text

/api/stats - Health Check

• Method: GET
• Purpose: Verify API connectivity and status
• Output: Connection status and basic stats

Environment Variables

Configure these in your Vercel dashboard:

Variable	Description	Required
OPENAI_CHAT_API_KEY	OpenAI key used by /api/chat and /api/title	Yes
OPENAI_TRANSCRIBE_API_KEY	OpenAI key used by /api/transcribe	Yes (for voice transcription)
OPENAI_CHAT_MODEL	Chat model allowlist enforced server-side	Yes (gpt-4o-mini)
WHISPERER_REQUEST_SIGNING_SECRET	HMAC secret used to verify signed watch requests	Yes
WHISPERER_CLIENT_ID	Allowed client identifier (whisperer-watch)	Yes
OPENAI_API_KEY	Legacy fallback key (all endpoints)	Optional

Setting Environment Variables

Via Vercel Dashboard

1. Go to your project settings
2. Navigate to "Environment Variables"
3. Add OPENAI_API_KEY with your key

Via CLI

nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_TRANSCRIBE_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_MODEL production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add WHISPERER_REQUEST_SIGNING_SECRET production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add WHISPERER_CLIENT_ID production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env ls

Configuration

Update App Configuration

After deployment, update the API URL in your app:

1. Open Whisperer/APIService.swift
2. Update the baseURL:

private let baseURL = "https://your-app-name.vercel.app"

Vercel Configuration File

The project includes vercel.json for deployment configuration:

{
  "functions": {
    "api/chat.js": {
      "maxDuration": 30
    },
    "api/transcribe.js": {
      "maxDuration": 30
    }
  }
}

Security Best Practices

API Key Security

• Store API keys as Vercel environment variables
• Never commit API keys to version control
• Use different keys for development/production
• Regularly rotate API keys
• Use separate keys for chat and transcription
• Restrict chat key to one model (gpt-4o-mini) in OpenAI project settings

Create a Locked-Down OpenAI Key for Whisperer

Use OpenAI Project API keys (not a global org key):

1. Create a new OpenAI project named Whisperer.
2. Set a low monthly project budget and alerts.
3. Under model permissions, allow only gpt-4o-mini for chat usage.
4. Create a project API key for chat and store it as OPENAI_CHAT_API_KEY.
5. If you use voice transcription, create a second key with transcription access and store it as OPENAI_TRANSCRIBE_API_KEY.
6. Set OPENAI_CHAT_MODEL=gpt-4o-mini in Vercel so the server ignores client-supplied models.
7. Generate a long random secret (at least 32 bytes) and store it as WHISPERER_REQUEST_SIGNING_SECRET.
8. Set WHISPERER_CLIENT_ID=whisperer-watch.

Request Validation

• Validate request formats
• Implement rate limiting if needed
• Log suspicious activity

CORS Configuration

The API endpoints include proper CORS headers for web access while maintaining security.

Monitoring and Analytics

Vercel Analytics

• View function invocations
• Monitor response times
• Track error rates
• Analyze usage patterns

OpenAI Usage Monitoring

• Monitor API usage in OpenAI dashboard
• Set up usage alerts
• Track costs per endpoint

Development Workflow

Local Development

# Link to your Vercel project
nix shell nixpkgs#nodejs_22 -c npx -y vercel link

# Pull environment variables
nix shell nixpkgs#nodejs_22 -c npx -y vercel env pull .env.local

# Run locally
nix shell nixpkgs#nodejs_22 -c npx -y vercel dev

Testing Endpoints

# Test health check
curl https://your-app.vercel.app/api/stats

# Test chat endpoint
curl -X POST https://your-app.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

Deployment Commands

Using Makefile

make deploy          # Deploy to production

Manual Deployment

vercel --prod        # Deploy to production
vercel               # Deploy to preview
vercel dev           # Run locally

Troubleshooting

Common Issues

1. Environment Variables Not Found

# Check environment variables
nix shell nixpkgs#nodejs_22 -c npx -y vercel env ls

# Add missing variables
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_TRANSCRIBE_API_KEY production
nix shell nixpkgs#nodejs_22 -c npx -y vercel env add OPENAI_CHAT_MODEL production

2. Function Timeout

• Increase maxDuration in vercel.json
• Optimize API calls
• Check OpenAI API response times

3. CORS Errors

• Verify CORS headers in API functions
• Check request origins
• Update allowed origins if needed

4. API Key Issues

• Verify key is correctly set in Vercel
• Check key permissions in OpenAI dashboard
• Ensure key hasn't expired

Debug Mode

# View function logs
nix shell nixpkgs#nodejs_22 -c npx -y vercel logs

# Run with verbose output
nix shell nixpkgs#nodejs_22 -c npx -y vercel --debug

Cost Optimization

Vercel Costs

• Function invocations (generous free tier)
• Bandwidth usage
• Build minutes

OpenAI Costs

• Monitor token usage
• Implement request caching if appropriate
• Set usage limits in OpenAI dashboard

Production Checklist

• Environment variables configured
• API endpoints tested
• App updated with production URL
• Monitoring set up
• Usage limits configured
• Security review completed
• Backup deployment strategy

Advanced Configuration

Custom Domains

vercel domains add your-domain.com

Team Collaboration

vercel teams switch your-team

Multiple Environments

• Use different Vercel projects for staging/production
• Configure environment-specific variables
• Implement proper CI/CD workflows

Support

For Vercel-specific issues:

• Vercel Documentation
• Vercel Community
• Vercel Support

For OpenAI API issues:

• OpenAI Documentation
• OpenAI Community
• OpenAI Support

API Endpoints

Chat Completions

• Endpoint: /api/chat
• Method: POST
• Purpose: Proxy for OpenAI chat completions
• Headers: X-Device-ID for usage tracking

Audio Transcription

• Endpoint: /api/transcribe
• Method: POST
• Purpose: Proxy for OpenAI Whisper transcriptions
• Headers: X-Device-ID for usage tracking

Usage Monitoring

The Vercel functions automatically log:

• Device IDs for usage tracking
• Token usage for chat completions
• Request timestamps
• Error rates

View logs in the Vercel dashboard under "Functions" -> "View Function Logs"

Security Benefits

1. No API Keys in App: The watch app no longer contains OpenAI API keys
2. Centralized Management: All API keys are managed in Vercel
3. Usage Tracking: Monitor API usage per device
4. Rate Limiting: Can be easily added to the Vercel functions
5. Access Control: Can restrict access by device ID or other criteria

CI/CD Pipeline

The Vercel integration automatically:

• Deploys on pushes to the main branch
• Runs in preview mode for pull requests
• Provides deployment URLs for testing

Local Development

For local development:

1. Copy .env.example to .env
2. Add your OpenAI API key to .env
3. Run the Vercel dev server:

vercel dev

4. Update APIService.swift to use http://localhost:3000 for local testing

Troubleshooting

Common Issues

1. API Key Not Found: Ensure OPENAI_API_KEY is set in Vercel environment variables
2. CORS Errors: The API includes CORS headers, but ensure your app's URL is correct
3. Timeout Issues: Increase timeout values if needed for large audio files

Debugging

Check Vercel function logs for detailed error information:

vercel logs

Cost Monitoring

Monitor OpenAI API costs through:

1. Vercel function logs (token usage)
2. OpenAI dashboard usage statistics
3. Custom analytics (can be added to the API functions)

Next Steps

Consider adding:

• Rate limiting per device
• User authentication
• Advanced usage analytics
• Caching for frequently used responses
• Error retry mechanisms