This backend provides a speech synthesis API with usage tracking and authentication.

• index.ts - Main Hono app with route definitions
• middleware/auth.ts - User identification and authentication middleware (RevenueCat + admin key)
• middleware/usage.ts - Usage tracking, rate limiting, and subscription status retrieval
• database/usage.ts - Database operations for usage tracking

• Admin access via ADMIN_ACCESS_KEY environment variable
• Customer authentication via RevenueCat subscription verification
• Authorization header format: Bearer {customer_id} or Customer {customer_id}

• Premium users: 900,000 characters per calendar month
• Free users: 45,000 characters lifetime limit
• Calendar month-based tracking for premium users (resets on 1st of each month)
• Automatic usage recording for successful requests
• Usage stats endpoint provides detailed subscription and usage information

The customer_usage_v1 table stores:

• 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

Converts text to speech using LemonFox API.

Headers:

• Authorization: Bearer {customer_id} or Authorization: Bearer {admin_key}

Body:

{
  "voice": "voice_name",
  "input": "text to convert"
}

Response:

{
  "audio": "base64_encoded_audio",
  "word_timestamps": [
    {
      "word": "hello",
      "start": 0.0,
      "end": 0.5
    }
  ]
}

Get current usage statistics and subscription details.

Headers:

• Authorization: Bearer {customer_id} or Authorization: Customer {customer_id}

Response (Premium users):

{
  "user_tier": "premium",
  "monthly_limit": 900000,
  "current_usage": 150000,
  "remaining_characters": 750000,
  "usage_percentage": 17,
  "reset_date": "2024-02-01T00:00:00.000Z",
  "plan_renewal_date": "February 5, 2024",
  "plan_term": "monthly",
  "plan_term_in_days": 30,
  "plan_key": "plus",
  "plan_gross_cost": 2.99,
  "trialing": false
}

Response (Trial users):

{
  "user_tier": "premium",
  "monthly_limit": 900000,
  "current_usage": 150000,
  "remaining_characters": 750000,
  "usage_percentage": 17,
  "reset_date": "2024-02-01T00:00:00.000Z",
  "plan_renewal_date": "February 7, 2024",
  "plan_term": "trial",
  "plan_term_in_days": 7,
  "plan_key": "plus",
  "plan_gross_cost": 0,
  "trialing": true
}

Response (Free users):

{
  "user_tier": "free",
  "lifetime_limit": 45000,
  "current_usage": 15000,
  "remaining_characters": 30000,
  "usage_percentage": 33,
  "message": "Upgrade to premium for a monthly character allowance.",
  "plan_renewal_date": null,
  "plan_term": null,
  "plan_term_in_days": null,
  "plan_key": null,
  "plan_gross_cost": null,
  "trialing": false
}

Health check endpoint.

Response:

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

• ADMIN_ACCESS_KEY - Admin authentication key
• REVENUECAT_API_KEY - RevenueCat API key
• LEMONFOX_API_KEY - LemonFox API key

• Premium users: 900,000 characters per calendar month
• Free users: 45,000 characters lifetime limit
• Admin users have unlimited usage
• Requests that would exceed the limit are rejected with HTTP 429
• Usage is tracked after successful requests only

• 401 - Missing or invalid authorization
• 403 - No active subscription or subscription verification failed
• 429 - Monthly character limit exceeded
• 500 - Internal server error