{
  "name": "QuickReel API",
  "contract": "v2",
  "version": "2.5.0",
  "status": "online",
  "auth": {
    "model": "Firebase (anonymous | google) -> POST /api/auth/oauth -> 30d JWT",
    "header": "Authorization: Bearer <jwt>",
    "vip_policy": "Episodes 1-5 are free. Episode 6+ requires an active VIP membership.",
    "trial": "A uid that becomes a real (non-anonymous) account for the first time gets a one-off VIP trial. Days come from Workers KV key CONFIG_KV/trial_days (0 disables it). Only ever granted once per uid; deleting the account does not restore eligibility.",
    "ad_unlock": "Episodes granted per ad come from Workers KV keys CONFIG_KV/ad_unlock_rewarded and ad_unlock_interstitial. The same value is used for the number shown in the app and the number actually granted.",
    "ad_grant": "POST /api/ads/grant requires header X-Device-Id (sha256 of the device id). The per-day trigger cap is enforced per account AND per device (any one hitting the cap returns 429 AD_LIMIT_REACHED), so creating new anonymous accounts cannot bypass it. Caps default to 10/24h per source and can be overridden with AD_DAILY_CAP_REWARDED / AD_DAILY_CAP_INTERSTITIAL.",
    "ad_ssv": "GET /api/ads/ssv is the AdMob rewarded SSV callback. The signature is verified (DER ECDSA P-256 over the raw query string) and each callback is stored in ssv_events keyed by transaction_id, for audit/reconciliation only — it does NOT grant anything.",
    "ad_unlock_storage": "Each ad unlock writes ONE row to drama_unlock_ranges (a closed episode range). The pre-v9 unlock_grants table is kept for history but no longer read or written.",
    "language": "en|pt|id filter content strictly (a region subtag is stripped, so en-US means en). Any other value means NO language filter at all — every language is served.",
    "login_required": "403 LOGIN_REQUIRED is returned for anonymous users on favorites/history."
  },
  "response_envelope": {
    "success": "{ success: true, data: <object|array>, pagination?: {...} }",
    "failure": "{ success: false, error: \"MACHINE_CODE\" }"
  },
  "endpoints": [
    {
      "method": "POST",
      "path": "/api/auth/oauth",
      "auth": false,
      "desc": "Exchange Firebase ID Token for a QuickReel JWT"
    },
    {
      "method": "GET",
      "path": "/api/auth/me",
      "auth": true,
      "desc": "Current user + VIP status"
    },
    {
      "method": "POST",
      "path": "/api/auth/redeem",
      "auth": true,
      "desc": "Redeem a code to extend VIP"
    },
    {
      "method": "POST",
      "path": "/api/auth/upgrade-vip",
      "auth": true,
      "desc": "Disabled. Always fails with VIP_UPGRADE_DISABLED"
    },
    {
      "method": "POST",
      "path": "/api/auth/register",
      "auth": false,
      "desc": "DISABLED. Legacy username/password registration is no longer served (404)"
    },
    {
      "method": "POST",
      "path": "/api/auth/login",
      "auth": false,
      "desc": "DISABLED. Legacy username/password login is no longer served (404)"
    },
    {
      "method": "DELETE",
      "path": "/api/auth/account",
      "auth": true,
      "desc": "Delete the account and its user data (GDPR). The trial tombstone survives on purpose"
    },
    {
      "method": "GET",
      "path": "/api/config",
      "auth": false,
      "desc": "Runtime config: freeEpisodes, adUnlock (from KV), legal, trialDays (from KV), plans?"
    },
    {
      "method": "GET",
      "path": "/api/coins",
      "auth": true,
      "desc": "Coin balance + check-in streak + today’s reward"
    },
    {
      "method": "POST",
      "path": "/api/coins/checkin",
      "auth": true,
      "desc": "Daily check-in. Reward = min(10 + 2*(streak-1), 20), resets to 10 on a missed Beijing day"
    },
    {
      "method": "POST",
      "path": "/api/coins/ad",
      "auth": true,
      "desc": "Body: { source: \"interstitial\" } -> +5 coins. Rewarded coins are credited by the AdMob SSV callback instead"
    },
    {
      "method": "POST",
      "path": "/api/coins/unlock",
      "auth": true,
      "desc": "Body: { dramaId, episodeNo } -> spend 1 coin to unlock that episode. 402 NO_COINS when the balance is empty"
    },
    {
      "method": "GET",
      "path": "/api/home",
      "auth": false,
      "desc": "Home aggregate. Params: language. Echoes the normalised requested language even when it disables filtering"
    },
    {
      "method": "GET",
      "path": "/api/feed",
      "auth": false,
      "desc": "Paginated feed. Params: page, pageSize, category, seed, language"
    },
    {
      "method": "GET",
      "path": "/api/rankings",
      "auth": false,
      "desc": "Params: type (hot|trend|collect|new|episodes), limit, language"
    },
    {
      "method": "GET",
      "path": "/api/search",
      "auth": false,
      "desc": "Params: q, page, pageSize, language. Matches the normalised dramas.search_text column (title+subtitle+category+tags, diacritics folded); description is deliberately NOT searched. Title matches ranked first; language ranks same-language first but does not filter"
    },
    {
      "method": "GET",
      "path": "/api/categories",
      "auth": false,
      "desc": "Params: language. Returns [{ name, count }]; counts are cross-language when language is not en|pt|id"
    },
    {
      "method": "GET",
      "path": "/api/dramas",
      "auth": false,
      "desc": "Params: page, pageSize, category, language, sort"
    },
    {
      "method": "GET",
      "path": "/api/dramas/:id",
      "auth": false,
      "desc": "Drama detail"
    },
    {
      "method": "GET",
      "path": "/api/dramas/:id/episodes",
      "auth": false,
      "desc": "Episodes + play URLs. VIP unlocks ep 6+"
    },
    {
      "method": "GET",
      "path": "/api/play/:dramaId/:ep",
      "auth": false,
      "desc": "Streaming proxy. Params: quality, token"
    },
    {
      "method": "GET",
      "path": "/api/cover/:id",
      "auth": false,
      "desc": "Cover image proxy"
    },
    {
      "method": "GET",
      "path": "/api/user/favorites",
      "auth": true,
      "desc": "Requires a real (non-anonymous) account"
    },
    {
      "method": "POST",
      "path": "/api/user/favorites",
      "auth": true,
      "desc": "Toggle favorite. Body: { dramaId }"
    },
    {
      "method": "DELETE",
      "path": "/api/user/favorites",
      "auth": true,
      "desc": "Idempotent removal. Query: dramaId"
    },
    {
      "method": "GET",
      "path": "/api/user/history",
      "auth": true,
      "desc": "Requires a real (non-anonymous) account"
    },
    {
      "method": "POST",
      "path": "/api/user/history",
      "auth": true,
      "desc": "Body: { dramaId, lastEpisodeNo, progressSeconds }"
    },
    {
      "method": "DELETE",
      "path": "/api/user/history",
      "auth": true,
      "desc": "Idempotent removal. Query: dramaId"
    }
  ]
}