This is a wrapper API for the LemonFox AI speech generation service with usage tracking and rate limiting. It simplifies the interface by only exposing the essential parameters while handling authentication, usage tracking, and configuration internally.

• Authentication: RevenueCat subscription verification + admin bypass
• Usage Tracking: Monthly character limits with SQLite storage
• Rate Limiting: 4 million characters per calendar month per customer
• Modular Architecture: Separated middleware and database modules

├── backend/
│   ├── index.ts              # Main Hono app
│   ├── middleware/
│   │   ├── auth.ts          # Authentication middleware
│   │   └── usage.ts         # Usage tracking middleware
│   ├── database/
│   │   └── usage.ts         # Database operations
│   └── README.md
├── main.tsx                  # Frontend (if applicable)
└── README.md

1. LEMONFOX_API_KEY - Your LemonFox API key
2. REVENUECAT_API_KEY - Your RevenueCat API key for subscription verification
3. ADMIN_ACCESS_KEY - Admin bypass key for development/testing

Update the REVENUECAT_PROJECT_ID constant in /backend/middleware/auth.ts with your actual RevenueCat project ID.

All API endpoints (except /health) require authentication via the Authorization header:

Authorization: Bearer YOUR_ADMIN_ACCESS_KEY

Authorization: Bearer CUSTOMER_ID

or

Authorization: Customer CUSTOMER_ID

The API will verify the customer has active entitlements via RevenueCat before allowing access.

• Monthly Limit: 4,000,000 characters per customer
• Reset Period: Calendar month (1st to last day of month)
• Admin Users: Unlimited usage
• Tracking: Automatic usage recording after successful requests

Generates speech from text using the LemonFox AI service.

Request Body:

{
  "voice": "sarah",
  "input": "Text to convert to speech"
}

Response:

{
  "audio": "_base_64_encoded_audio_here", 
  "word_timestamps": [
    {
      "word": "Hello!", 
      "start": 0.275, 
      "end": 0.7
    }
  ]
}

Error Response (Rate Limited):

{
  "error": "Monthly character limit exceeded",
  "details": {
    "monthly_limit": 4000000,
    "current_usage": 3950000,
    "requested_characters": 100000,
    "remaining_characters": 50000
  }
}

Get current month's usage statistics for the authenticated customer.

Response:

{
  "monthly_limit": 4000000,
  "current_usage": 150000,
  "remaining_characters": 3850000,
  "usage_percentage": 4
}

Admin Query Parameter:

GET /api/usage?customer_id=specific_customer_id

Health check endpoint that returns the service status.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

The system uses SQLite to track usage with the following schema:

Table: customer_usage_v1

• id - Auto-incrementing primary key
• customer_id - Customer identifier from RevenueCat
• character_count - Number of characters in the request
• request_timestamp - ISO timestamp of the request
• created_at - Database insertion timestamp

The API automatically configures:

• response_format: Always set to "mp3"
• word_timestamps: Always set to true

Only voice and input parameters need to be provided by the client.

• 400 - Bad Request (missing required fields)
• 401 - Unauthorized (missing/invalid auth header)
• 403 - Forbidden (no active subscription)
• 429 - Too Many Requests (monthly limit exceeded)
• 500 - Internal Server Error