Backend API

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

Structure

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

Features

Authentication

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

Usage Tracking

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

Database Schema

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

API Endpoints

POST /api/speech

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 /api/usage

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
}

GET /health

Health check endpoint.