API Contract (v1) — backend and web are both built against THIS file

Base URL: http://localhost:8000. JSON everywhere. Auth: Authorization: Bearer <jwt> for users, Authorization: Device <token> for devices. Errors: {"detail": str} with proper status codes. Dates are YYYY-MM-DD; timestamps are ISO-8601 UTC.

Auth & profile

• POST /v1/auth/signup {email, password, business_name} → {token, user:{id,email,role}} (role=advertiser)
• POST /v1/auth/login {email, password} → {token, user}
• GET /v1/me → {id, email, role, profile:{business_name, phone?, gstin?}}
• PATCH /v1/me/profile {business_name?, phone?, gstin?} → profile
• Seeded ops user: ops@dooh.local / env OPS_PASSWORD (default opsdev123), role=ops.

Creatives (advertiser)

• POST /v1/creatives multipart: file, name → {id, name, kind, duration_s, status:"pending", validation:{...}} Validation (automatic, on upload): image jpg/png ≤10MB; video mp4 h264 ≤50MB ≤10s; portrait or square preferred (warn, don't block). Reject → 422 with reasons.
• GET /v1/creatives → list. GET /v1/creatives/{id}/file → the media (also used by devices).
• PATCH /v1/creatives/{id} {name} → rename (owner only).
• POST /v1/creatives/{id}/file multipart file → REPLACE the media: revalidates (same rules as upload), updates kind/sha256/duration, and RESETS status to "pending" — a replaced file never plays until ops re-approves. Existing schedule entries stay booked but are excluded from device schedules while the creative is not approved (they resume on re-approval).
• DELETE /v1/creatives/{id} → 204; 409 if any booking references it.
• Approval gate at serve time: GET /v1/device/schedule only returns entries whose creative is currently approved (a re-pending creative's slots serve as idle until re-approved).

Screens & availability (advertiser browse)

• GET /v1/screens → [{id, venue_name, zone_name, label, orientation, loop_slots, slot_seconds, rate_per_slot_day}]
• GET /v1/screens/{id}/availability?start=YYYY-MM-DD&end=YYYY-MM-DD → [{date, slots_total, slots_booked, slots_free}]

Bookings

• POST /v1/bookings {campaign_name, creative_id, items:[{screen_id, slot_count, start_date, end_date}]} → {id, price_total, payment_status:"pending", status:"confirmed", items:[...]} 409 if any screen-date lacks free slots. Confirm materializes schedule_entries (creative must be approved; if creative still pending → booking status awaiting_creative, schedule materializes on approval).
• GET /v1/bookings → list with per-item delivery counts. POST /v1/bookings/{id}/cancel (future dates only).

Metrics (advertiser)

• GET /v1/metrics/campaigns/{booking_id}?from&to → {plays, ots, watchers, attention_ms_avg, attention_rate, age_bands:{"<18":n,"18-24":n,"25-34":n,"35-44":n,"45+":n}, gender:{male,female}, by_day:[{date, plays, ots, watchers}], by_screen:[{screen_id, label, plays, ots, watchers}], by_creative:[{creative_id, name, plays, watchers, attention_ms_avg}], by_hour:[{hour, watchers}]}
• GET /v1/metrics/campaigns/{booking_id}/export.csv → ledger rows (one row per play with audience summary), then — after a blank line — a qr_scans_by_creative section (creative_id,creative_name,qr_scanned). Scans attach to a creative, never to a single play row, so they live in their own section rather than as a fabricated per-row column; the ledger rows above are byte-identical to the plays table.
• GET /v1/metrics/live → [{screen_id, label, now_playing:{creative_name?, booking_id?}, watchers_now, updated_at}]
• GET /v1/metrics/overview?days=14 → portfolio at-a-glance across all the advertiser's campaigns: {window_days, plays, ots, watchers, attention_ms_avg, attention_rate|null, has_audience_data, screens_used, active_campaigns, by_day:[{date, plays, ots, watchers}]}
• GET /v1/metrics/screens/{screen_id}?from&to → one screen, scoped to the advertiser's own plays: {screen:{id,label,zone_name,venue_name,orientation,loop_slots,slot_seconds,rate_per_slot_day}, device:{status,last_seen_at,watchers_now}|null, occupancy_today:{slots_sold,slots_total}, plays, ots, watchers, attention_ms_avg, attention_rate|null, has_audience_data, by_hour, campaigns:[{booking_id,campaign_name,plays,watchers}], recent_plays:[≤20]}
• Null semantics: attention_rate is null (never 0.0) when ots=0 — no audience data is not the same as measured-zero attention. Clients must render "—/no audience data yet", not "0.0%". Booking rows now carry top-level delivered_plays (sum of items' plays_delivered).
• Audience-metric semantics (v1.2): metric responses carry plays_with_audience (plays whose audience summary is non-zero); attention_ms_avg averages over those plays only (camera-off plays never dilute it). watchers are WATCH EVENTS — per-play counts; the same person watching N plays counts N times (no cross-play identification, by design). Face-only sensors (browser/ iPad player) report ots == watchers — they cannot see non-lookers and must not invent OTS; clients treat ots == watchers > 0 as "OTS not measured" and suppress attention_rate.

Ops (role=ops)

• GET /v1/ops/creatives?status=pending · POST /v1/ops/creatives/{id}/approve {checklist, mall_signoff_ref?} (see Review checklist, 2026-10-24) · .../reject {reason}
• GET /v1/ops/venues → [{id, name, city, zones:[{id, name}]}]
• PATCH /v1/ops/venues/{id} {name?, city?} · PATCH /v1/ops/zones/{id} {name} → renamed object.
• DELETE /v1/ops/venues/{id} / DELETE /v1/ops/zones/{id} → 204; 409 unless empty (no zones / no screens).
• POST /v1/ops/venues {name, city} · POST /v1/ops/zones {venue_id, name} · POST /v1/ops/screens {zone_id, label, orientation, loop_slots?, slot_seconds?, rate_per_slot_day}
• GET /v1/ops/screens → registry incl. device:{id, status, last_seen_at}|null
• PATCH /v1/ops/screens/{id} {label?, orientation?, loop_slots?, slot_seconds?, rate_per_slot_day?} → updated screen; 409 if loop_slots would shrink below the busiest future day's booked slots
• POST /v1/ops/devices/claim {code, screen_id} → binds pairing code to screen
• POST /v1/ops/devices/{id}/revoke
• GET /v1/ops/fleet → [{screen_id, label, device_status, last_seen_at, last_batch_at, quarantined_batches}]
• GET /v1/ops/bookings (all) · POST /v1/ops/bookings/{id}/mark_paid

Device API (Authorization: Device <token>, except pairing)

• POST /v1/device/pairing/start {device_uid} → {code, poll_token} (code TTL 10 min)
• POST /v1/device/pairing/poll {device_uid, poll_token} → 202 pending | {device_token, screen:{...}}
• GET /v1/device/schedule?date=YYYY-MM-DD → {screen:{id,label,loop_slots,slot_seconds}, entries:[{slot_index, creative:{id, kind, url, duration_s, sha256}}], generated_at} (device caches this + media files; url is /v1/creatives/{id}/file)
• POST /v1/device/events {batch_seq, device_sent_at, plays:[{client_play_id, creative_id, slot_index, started_at, duration_ms, audience:{ots, watchers, attention_ms_total, age_bands:{...}, gender:{...}}}]} → {state:"recorded"|"duplicate"|"rejected", reason?} — idempotent on (device, batch_seq). Clock-drift rule (v1.1): device_sent_at = the device's current clock at upload time. Reject the whole batch (reason="clock_drift", body stored for review) iff |device_sent_at − server_now| > 60s OR any play has started_at > device_sent_at + 60s. Plays that are merely OLD are fine — late upload after offline periods (hours/days) is the normal contract (CLAUDE.md rule 5) and must be recorded, never quarantined for age.
• POST /v1/device/heartbeat {playing_creative_id?, watchers_now?} → 204 (feeds /v1/metrics/live)

Conventions

• Pagination not needed in v1 (small N). All list endpoints return newest-first.
• Money: integer rupees. IDs: UUID strings.

Interop clarifications (binding, agreed during build)

• Pairing poll with expired/unknown code → HTTP 410 (device restarts pairing, shows new code).
• pairing/start is idempotent: if the device already has an outstanding (unconsumed, unexpired) request — e.g. the player reloaded between the ops claim and its next poll — it returns the SAME code + poll_token (HTTP 200) instead of invalidating the claim. A fresh code is minted only when nothing usable is outstanding, so the on-screen code is stable until it truly expires.
• Duplicate events batch → HTTP 200 {"state":"duplicate"} (never an error status).
• rejected is terminal: server stores the batch body for review; devices never retry a rejected batch. A re-sent already-terminal seq answers duplicate.
• One batch per play; batch_seq strictly increasing per device, assigned at queue time, survives device restarts. Uploads arrive in seq order but possibly long after the plays.
• duration_ms = slot occupancy (slot_seconds × 1000), not creative runtime.
• Devices refetch schedule every 300s and on UTC date rollover; 401 anywhere → device drops its token and returns to pairing (queued batches preserved).
• Multi-item bookings: one booking row, items[] children. attention_ms_avg = Σattention_ms_total / plays; attention_rate = watchers/ots.

Interactive (game) creatives — v1.3

A creative with kind:"game" is a playable ad. It has no single media file: it has a JSON config (template + copy + rules + reward) and a set of image assets keyed by name. It goes through the same approval gate as image/video and books slots like any creative.

Config shape (template catch, the only template in v1.3)

{ "template": "catch",
  "mode": "basket" | "tap" | "camera",         // basket = drag a basket (touch); tap = tap items; camera = face steers basket
  "brand": "Fizz Cola", "colors": {"bg":"#160b0d","accent":"#d6202c"},
  "headline": "Catch the fizz.", "slogan": "Every cap counts.",
  "items": [ {"key":"item","points":1,"weight":7,"size":0.13},      // asset key "item_<key>"... see assets
             {"key":"bonus","points":3,"weight":1,"size":0.13},
             {"key":"decoy","points":-2,"weight":2,"size":0.11} ],
  "round_s": 25,                                // one round of play
  "slot_s": 30,                                 // loop occupancy when this creative's slot comes up (20–120)
  "reward": {"title":"10% off","code":"FIZZ10","url":"https://…","note":"Show at counter"} }

Asset keys: logo, hero, and item_<key> for every entry in items. All png/jpg ≤5MB. Validation (422 on failure): mode ∈ set, 1–6 items, points −10..10, weight ≥1, round_s 10–60, slot_s 20–120, reward.url must be http(s), strings ≤ 255.

Endpoints

• POST /v1/creatives/game {name, config} → creative (kind:"game", status:"pending", config, assets:{}) — 201. duration_s = config.slot_s.
• PUT /v1/creatives/{id}/game {name?, config} → creative; RESETS status to "pending".
• POST /v1/creatives/{id}/assets/{key} multipart file → creative; upserts the asset, RESETS status to "pending". 422 on bad key/type/size.
• DELETE /v1/creatives/{id}/assets/{key} → creative (status → pending).
• GET /v1/creatives/{id}/assets/{key} → the image (user or device auth).
• GET /v1/creatives/{id}/game → {id, name, config, assets:{key: "/v1/creatives/{id}/assets/{key}"}} (user or device auth). This is what the player and the portal preview load.
• GET /v1/creatives / creative dicts: game creatives carry config and assets (key→url); sha256 is a hash over config + asset hashes (changes whenever anything changes).
• Approval: a game creative may be approved only when logo, hero and every item_<key> asset exist (409 otherwise).

Player contract

• GET /v1/device/schedule entries for game creatives: creative:{id, kind:"game", url:"/v1/creatives/{id}/game", duration_s: config.slot_s, sha256}. The device fetches the JSON and every asset with its device token and caches them like media.
• A game slot occupies slot_s seconds (not screen.slot_seconds). If a round is in progress when the slot ends, the device may extend the slot until the round ends (≤ +60 s). The play's duration_ms is the ACTUAL occupancy.
• PlayIn.engagement (optional, game plays only): {sessions, completed, score_sum, best_score, qr_shown, starts_face, starts_tap} → stored append-only in engagement_summaries.
• Metrics: campaign/screen/overview responses add engagement:{sessions, completed, completion_rate, avg_score, best_score, qr_shown, qr_scanned, starts_face, starts_tap}|null (null when no game plays). qr_scanned counts anonymous opens of the reward claim page for the same creatives in range. starts_face / starts_tap sum how sessions began (camera vs touch).
• Overview responses add total_spend (integer rupees of non-cancelled bookings created in the window) and spend_by_day:[{date, spend}].

QR claim flow — v1.4

• The engine's reward QR points at the web claim page /r/{creative_id}?s=<score>&n=<nick> (parent passes creativeId in the gody:config embed message; without it the QR falls back to the self-contained demo claim view).
• POST /v1/qr/scans {creative_id, score?} → {ok:true} — 201. Anonymous (no auth): one append-only row per phone that opens the claim page. Counts only, no personal data. 404 unless the creative exists and is a game.
• GET /v1/qr/reward/{creative_id} → {creative_id, brand, reward:{title, code, url, note}} — anonymous. Served only for approved game creatives; 404 otherwise (the claim page then explains the offer isn't live).
• qr_scans is an append-only event log (same immutability discipline as the ledger).

Immediate push — v1.3

• screens.schedule_version (int) is bumped whenever the screen's playable loop changes: schedule materialization, booking cancel, creative approve/reject/replace/config/asset change (for every screen that has schedule entries for that creative, today or later), screen PATCH.
• GET /v1/device/schedule adds schedule_version.
• POST /v1/device/heartbeat now returns 200 {"schedule_version": n} (was 204). Devices compare with the cached version and refetch at once when it differs; the refreshed loop is applied at the NEXT slot boundary (not the loop wrap). Clients must tolerate 204 from older servers.

Optional premium layers (v1.3.1)

Two optional asset keys accept mp4 ≤ 20MB (sniffed by ftyp): background (looping clip behind the whole screen, played muted at reduced opacity) and hero_video (the product animated on a pure black background; the engine screen-blends it so the black disappears). Never required for approval; the engine falls back to the static hero when absent.

Spin template + wallet — v1.5

Template spin (game creative config)

{ "template":"spin", "brand", "colors":{bg,accent}, "headline", "slogan",
  "symbols":[{"key":"hero","label":"Hero","weight":5}, …],          // 4–8, images symbol_<key>
  "wilds":[{"key":"maker","label":"The Maker","multiplier":10}, …],  // 0–3, images wild_<key>; a wild matches any symbol
  "spin_s":6, "spins_per_session":3, "slot_s":45,                     // spin 4–10 s; 1–5 spins; slot 20–120 s
  "prizes":[ {"tier":"big",   "title":"Free movie ticket", "odds_one_in":200, "daily_budget":20},
             {"tier":"mid",   "title":"₹100 off popcorn",  "odds_one_in":15,  "daily_budget":200},
             {"tier":"small", "title":"10% off merch",     "odds_one_in":1,   "daily_budget":null} ],  // 1–3 tiers; exactly one with odds 1 (everyone wins)
  "reward":{...} }                                                    // legacy fallback (offline / preview) as in v1.3

Assets: logo, hero, symbol_<key> for every symbol, wild_<key> for every wild (all required for approval); optional win_clip (mp4 ≤20MB, plays on a big win), background, hero_video. Validation: tiers unique; odds_one_in ≥1; daily_budget ≥1 or null; symbol/wild keys ^[a-z0-9_]{1,24}$ unique.

Server-decided spins (device auth)

• POST /v1/device/spins {creative_id, booking_id?, client_spin_id} → {spin_id, outcome:{tier:"big"|"mid"|"small", title, symbol_key, wild_key|null, multiplier|null}, token, claim_url:"/w/claim/{token}", expires_at} — idempotent on (device, client_spin_id). The server draws the tier: for tiers in order big→mid, win iff random < 1/odds_one_in AND today's wins for (booking or creative) < daily_budget; else the odds-1 tier. It mints a win_tokens row (48 h expiry). The engine renders reels to match the outcome (promotional spins are outcome-first). Offline: the engine shows the small tier with the legacy reward QR (/r/{creative_id}), no token.
• win_tokens: id, creative_id, booking_id?, device_id, spin_id, tier, title, created_at, expires_at, claimed_at?, coupon_id?. Insert-only except claimed_at/coupon_id set once.

Wallet (public, phone-based — NEW personal-data class, see CLAUDE.md rule 3a)

• POST /v1/wallet/otp/start {phone} → 204. Indian mobile (^\+91[6-9]\d{9}$), 6-digit code, 5 min TTL, max 5 sends/phone/hour, 5 attempts/code. Delivery via services/sms.py: send_otp(phone, code) — v1 provider is a log stub; with env WALLET_OTP_DEV=1 the response is 200 {"dev_code": "…"}.
• POST /v1/wallet/otp/verify {phone, code, consent:true, consent_version:"2026-09"} → {wallet_token, user:{id, phone_masked:"+91••••••1234", consent_at}} (JWT role=wallet, 90 days). Consent is required (422 without). Stores wallet_users{id, phone_hash (HMAC-SHA256, secret), phone_enc (Fernet), consent_at, consent_version, created_at, last_seen_at, erased_at?}.
• GET /v1/wallet/claim/{token} (public) → {brand, tier, title, expires_at, status:"open"|"claimed"|"expired"}.
• POST /v1/wallet/claim {token} (wallet auth) → coupon (201). Rules: 410 expired; 409 claimed by another user; same user re-claim returns the existing coupon (200); ONE coupon per (user, booking) per day → 409 {detail, coupon} with the existing one. Coupon code "{BRAND4}-{XXXX}-{XXXX}".
• GET /v1/wallet/me → {phone_masked, coupons:[{id, brand, title, tier, code, status, campaign_name, issued_at, expires_at, redeemed_at}]} newest first. Coupons expire 30 days after issue.
• DELETE /v1/wallet/me → 204: erases phone_hash/phone_enc (right to erasure), coupons stay anonymised (wallet_user_id kept, user row marked erased_at).
• coupons: id, wallet_user_id, win_token_id, creative_id, booking_id?, tier, title, code (unique), status issued|redeemed|expired, issued_at, expires_at, redeemed_at?, redeemed_by_user_id?.

Redemption (advertiser owning the creative, or ops)

• POST /v1/redeem {code} → {ok:true, coupon:{brand, title, tier, status:"redeemed", redeemed_at}}; 409 already redeemed / expired; 404 unknown or not yours.

Metrics

• engagement gains spins, wins, claims, redemptions (spin creatives; 0 otherwise). Campaign CSV gains a coupons_by_tier section (tier,wins,claims,redemptions). Phone numbers NEVER appear in any advertiser/ops response; ops gets GET /v1/ops/wallet/stats → {users, coupons, redeemed} only.

Embed protocol additions (engine ⇄ parent)

• iframe → parent {type:"gody:spin", requestId}; parent → iframe {type:"gody:spin:result", requestId, outcome, claim_url|null}. The player answers by calling POST /v1/device/spins with its device token; the portal preview / ops play-test answers locally with a simulated outcome and claim_url:null (engine falls back to the legacy reward QR).

Spin grid (v1.5.1)

config.reels (3–5, default 3) × config.rows (3–5, default 3). The winning line is the middle row; on square grids both diagonals are also paylines (never used for a granted prize). A 5×5 grid needs 6+ symbols to read well; the editor says so. config.layout (v1.5.1): cabinet (default — one tall stack; centred 9:16 column with blurred art side-fill on wide screens) | split (art left, reels right on wide screens) | backdrop (key art full-bleed behind everything). /cabinet.html is a convenience entry that pins layout=cabinet. config.bonus (v1.5.2, spin only): {enabled, reels 3–5 (default 5), rows 3–5 (default 4), title} or null. When enabled the asset bonus_symbol is required for approval and a mid/big outcome is staged in two acts (base reels land R BONUS symbols → the stage opens → the top reels spin for the prize). Budget slot_s ≥ 90 for bonus ads.

Wheel template — v1.6

A prize wheel (reference: casino "wicked wheel" toppers). One tap spins; the wheel lands on the server-decided tier (outcome-first, same POST /v1/device/spins; spinnable templates = spin, wheel).

{ "template":"wheel", "brand", "colors":{bg,accent}, "headline", "slogan",
  "segments": 12,                 // 8–16 wheel segments
  "spin_s": 7,                    // 5–12 s of spinning
  "slot_s": 45,
  "prizes":[ {"tier":"big","title":"…","odds_one_in":40,"daily_budget":20,"segments":1},
             {"tier":"mid","title":"…","odds_one_in":6,"daily_budget":200,"segments":3},
             {"tier":"small","title":"…","odds_one_in":1,"daily_budget":null,"segments":8} ],
  "reward":{...} }                 // legacy fallback as in v1.3

prizes[].segments is VISUAL ONLY (how many wedges show that tier; must sum to segments); the server draws by odds_one_in + daily_budget exactly as for spin. One spin per session. Assets: logo, hero required; wheel_center (png, the hub), background, hero_video, win_clip optional. Metrics/wallet/claims identical to spin (engagement.spins counts wheel spins). Embed: GameFrame loads /wheel.html?embed=1 for template wheel; same gody:* protocol incl. gody:spin. Spin bonus (v1.5.2 note): when bonus.reels/rows are omitted the engine defaults the top grid to the base reel count × (rows+1), so a 3-reel base opens a 3-reel top and a 5-reel base a 5-reel top. config.bonus.kind (v1.6.1, spin): "reels" (the Wall: bigger reels on top) | "wheel" (the prize wheel on top, bonus.segments 8–16 wedges). bonus.reels/rows null → follow the base grid. Optional keyed fx clips (mp4 on pure black, luma-keyed by the engine): fx_ring (loops behind the wheel), fx_burst (trigger + grand win), fx_coins (wins). hero_video on spin is the "living poster" (played as the stage art, not keyed).

v1.6.2 — wheel characters + reveal (additive)

wheel config gains optional symbols[] (0–8 {key, label}, keys ^[a-z0-9_]{1,24}$, unique) and reveal ({key, label} or null). Once listed, symbol_<key> (one portrait per character) and wild_<key> (the reveal portrait) are REQUIRED for approval, exactly like spin symbols/wilds; keys not in the config are rejected with 422. Duplicate keys across symbols + reveal → 422. Wheel also accepts the optional fx clips fx_ring / fx_burst / fx_coins (mp4). Engine (/wheel.html): portraits cycle around the wedges; the reveal takes the grand wedge(s); hero_video plays as the living poster on the stage above the wheel; on a grand the reveal pops on the stage, fx_burst + fx_coins fire, then win_clip plays before the QR results. validation.checks.symbols = count.

Cricket wall template — v1.7 ("Hit for Six")

A floor-size portrait wall; phones are the controllers. Design: docs/CRICKET_DESIGN.md.

{ "template":"cricket", "brand", "colors":{bg,accent}, "headline", "slogan",
  "packs": 20,                      // 12–30 sponsor packs on the wall
  "balls": 6,                       // 3–10 packs each player picks
  "bag": {"0":4,"1":5,"2":4,"4":3,"6":2,"out":2},   // sums to packs, out >= 1; reshuffled per innings
  "prizes":[ {"tier":"big","title":"…","min_runs":24,"daily_budget":10},
             {"tier":"mid","title":"…","min_runs":12,"daily_budget":300},
             {"tier":"small","title":"…","min_runs":0,"daily_budget":null} ],   // exactly one min_runs 0
  "play_url": "",                   // display-only short URL under the QR
  "turn_timeout_s": 25,             // 10–120 s to tap Play once called
  "slot_s": 300,                    // 60–600: the wall holds the slot (takeover)
  "reward": {...} }                 // optional legacy fallback

Assets: logo, hero, pack required. Optional images board, scoreboard_logo, helmet_logo, jersey_logo, bat_sticker, batter, stadium; optional mp4 clip_six, clip_four, clip_out, clip_dot, clip_single, clip_double, clip_walkin. Engine: /cricket.html?embed=1. clip_bowl is the shared delivery (run-up to release, 2–4 s): when present the wall plays it before every outcome clip and hard-cuts to the outcome, so outcome clips should start at the crease with the ball already in the air. Without it, outcome clips play alone.

Phone (public, per-session secret; CORS open):

• GET /v1/play/{screen_id} → {screen:{id,label}, creative_id, config:{brand,headline,slogan,colors,packs,balls,prizes[{tier,title,min_runs}],turn_timeout_s}, assets:{key: "/v1/play/{screen}/assets/{key}"}, queue}. 404 when no approved cricket creative is booked on the screen today.
• GET /v1/play/{screen_id}/assets/{key} → the active creative's logo|hero|pack|board|batter|stadium (never clips).
• POST /v1/play/{screen_id}/join {name, avatar} → 201 {session_id, secret, …state}. 422 with a sentence when the name fails moderation; 429 when the queue is full.
• POST /v1/play/sessions/{id}/picks {secret, picks[]} → state. Exactly balls distinct indexes in [0, packs); 409 once sealed.
• GET /v1/play/sessions/{id}?secret= → {id,status,name,avatar,position,eta_s,picks,has_picks,turn_timeout_s,ready_at} + when done {balls,runs,balls_faced,out,rank,claim_url}.
• POST /v1/play/sessions/{id}/start {secret} → ready → playing (409 otherwise).
• GET /v1/play/sessions/{id}/card.png?secret= → 1080×1350 share card (409 until done).
• GET /v1/play/{screen_id}/board → {rows:[{id,name,avatar,runs,balls,out}], queue} (today, top 10).

status: queued | ready | playing | done | skipped | expired. Only players with sealed picks are promoted to ready; ready without Play within turn_timeout_s → skipped; playing without a wall report within 180 s → expired.

Wall (device token):

• GET /v1/device/cricket/{creative_id}/poll → {queue:{now,next[],waiting}, turn:{session:{id,name,avatar}, balls:[{pack,value}]}|null, board[]}. Runs housekeeping (timeouts + promotion). The wall polls every 2 s and forwards each as an engine event; a turn is forwarded once per session id.
• POST /v1/device/cricket/sessions/{id}/done {runs, balls, out} → {id,status,runs,balls,out,rank,claim_url}. Idempotent. Runs are re-derived server-side from the sealed balls; a prize is minted through the spin ledger (spins.symbol_key = "cricket", a win_tokens row) by the highest prizes[] band the runs reach with daily budget left.

Embed additions: gody:config carries screenId; host → engine gody:cricket:event {event} with event.type ∈ queue | turn | board; engine → host gody:cricket:turn_done {sessionId, runs, balls, out} plus the usual gody:round / gody:stats (innings, sixes, outs counters).

Tables: cricket_sessions (migration a1c7e9b2d4f6): display name + emoji only (rule 3).

v1.7.1 — the code + kiosk flow (replaces the phone picker)

The phone only receives a 4-digit code; the kiosk (a tablet beside the wall, /kiosk/{screen_id}) takes the code and the player picks one pack at a time. Config defaults change to packs: 10, bag: {"0":2,"1":2,"2":2,"4":2,"6":1,"out":1} (packs now 6–30). New optional tagline (≤ 60) is written onto the stadium's scoreboard in the footage. Migration b2d8f4a6c1e3 adds code, kiosk_key_hash, bag_order, shown to cricket_sessions.

Phone: POST /v1/play/{screen_id}/join {name, avatar, phone?} → 201 {session_id, secret, code, status:"queued", expires_in_s, packs, balls_per_over, …}. phone is optional and never stored: when WHATSAPP_PROVIDER=aisensy the code is also sent on WhatsApp through AiSensy (template freebee_cricket_code; a failed send is logged, never surfaced). GET /v1/play/sessions/{id}?secret= returns code only while queued; while playing it mirrors balls, runs, balls_faced; when done adds rank and claim_url. A ticket expires after 30 min unused (status: expired). picks and start are gone.

Kiosk (public; the code is the auth, then a per-innings key):

• GET /v1/kiosk/{screen_id} → same shape as GET /v1/play/{screen_id} (assets now include ball, ball_gold).
• POST /v1/kiosk/{screen_id}/claim {code} → {session_id, key, status:"playing", packs, balls_per_over, balls:[], wall_ready:true, …}. 404 unknown/used/expired code; 409 "<name> is batting" while another innings is live (one innings per wall). Claiming seals the innings' bag (bag_order).
• POST /v1/kiosk/sessions/{id}/ball {key, pack} → the innings plus ball:{pack,value}. 409 if the wall has not finished showing the previous ball (wall_ready:false), if the pack is already open, or if the innings is over; 422 for an out-of-range pack. The innings closes itself at balls picks or the first out and mints the prize through the spin ledger (claim_url).
• GET /v1/kiosk/sessions/{id}?key= → innings + shown + wall_ready. An innings idle for 90 s closes as it stands (or expires if no ball was played).

Wall (device token): GET /v1/device/cricket/{creative_id}/poll → turn now carries status and shown and grows ball by ball; after the innings closes it keeps returning until the wall has shown every ball. POST /v1/device/cricket/sessions/{id}/shown {shown} — the wall reports how many balls it has finished showing (this is what unlocks the kiosk's next pick). …/done is kept as an idempotent "shown everything" mark.

Embed: the host forwards turn whenever (session, balls.length, status) changes; the engine plays only the balls it has not shown and posts gody:cricket:shown {sessionId, shown} after each. Big moments take the whole wall; in attract the wall shows the big QR ("scan for your code · enter it at the kiosk · pick a ball at a time").

v1.8 — the Freebee dice (2026-10-21)

CricketConfig.mode is "bag" (v1.7.1 behaviour, the default for old rows) or "dice". In dice mode every ball is an independent roll of the six-faced Freebee dice, server side, from odds (percent per value, must sum to 100, out > 0; default 1 → 14, 2 → 14, 0 → 14, 4 → 20, out → 18, 6 → 20). bonus_on_six (default true) adds one ball to the innings for every six, up to max_balls (default 12, ≥ balls). packs and bag are ignored in dice mode and not validated.

• POST /v1/kiosk/sessions/{id}/ball body {key} — pack is optional and ignored in dice mode. Each ball carries face (1 single, 2 double, 3 dot, 4 four, 5 out, 6 six) and pack is the ball index.
• Kiosk and phone views carry mode and limit (balls this innings may face, growing by one per six). The wall poll's turn carries limit too, so the wall can draw the bonus slots.
• The innings ends at limit balls or the first out, as before.
• The wall (/cricket.html) in dice mode: the 3D dice tumbles in the stage and lands on the result — the bee umpire signals six, four and out; pips for 1, 2 and 3 with the sponsor's logo in the corner — then the delivery and outcome footage play and the over tracker fills; a gold +1 slot pops in on a six. The kiosk shows a single ROLL button instead of the packs.

v1.8 hardening (2026-10-21, after the end-to-end test)

• Report: GET /v1/metrics/campaigns/{booking} → engagement.cricket block (scans, claimed, innings, expired, claim_rate, avg_innings_s, total_play_s, balls, avg_balls, avg_runs, best_runs, sixes, fours, dots, outs, not_out, bonus_balls, runs_distribution, prizes{big,mid,small}, by_hour[]); null unless a ticket was issued in range. GET /v1/metrics/campaigns/{booking}/cricket.csv = one anonymous row per ticket (never a name, code or phone). Days and hours in all reports are now IST. Cricket prizes appear in coupons.csv like spin prizes.

• Kiosk safety: GET /v1/kiosk/{screen} tickets[] no longer carries code (who is waiting, never their code). POST /v1/kiosk/{screen}/claim returns 429 after 5 wrong codes on a screen within 2 minutes (60 s lock).

• Wall stall: a ball the wall has not reported shown for 20 s stops blocking the next ball (WALL_STALL_S); the kiosk is never held hostage.

• Idle innings (90 s without a roll) are closed with their prize minted.

• Names: the block list is normalised like the input (doubled letters and leet cannot slip through); only an unambiguous subset matches inside a name, so Anusha, Gandhi, Nazia, Suleman, Dhanush pass; names in Telugu / Hindi / Urdu script are accepted; Cyrillic look-alikes are folded. avatar must be one of the twelve phone avatars.

• Bookings: a second cricket game on the same screen and overlapping dates is refused with 409 (the phone and kiosk can only serve one).

• Wall reports shown / done accept up to 30 balls (bonus balls).

• WhatsApp: config.whatsapp is true only with WHATSAPP_PROVIDER=aisensy; the phone page then stops asking for a number nothing would use.

• Phone, kiosk and campaign pages: offline auto-retry, prize ladder on the phone, dice copy, kiosk wake lock and keyboard entry, report defaults to the campaign's own dates.

• Script: backend/scripts/e2e_cricket.py runs the whole API flow against a server (--base, --screen), exit 1 on any failure.

• Prizes are optional (v1.8): CricketConfig.prizes is 0–3 bands; at most one band may need 0 runs. With no bands (or runs below every band) the innings completes with claim_url: null and the phone says thanks for playing.

• Ad break (v1.8): optional video asset ad_break (a 10–15 s spot) plus CricketConfig.ad_break_every_s (15–600, default 45). While nobody is batting the wall plays it full screen every N seconds with the scan QR kept in the corner, muted like all wall footage. Cut off the moment a code is claimed.

• Page opens: the phone play page beacons POST /v1/qr/scans on open; GET /v1/play/{screen} now returns booking_id for that. The report's cricket block carries opens (≥ scans) so the funnel reads opened → got a code → entered the kiosk → finished → prize.

v1.9 — hourly windows: advertisers share a screen by the hour (2026-10-22)

• BookingItemIn gains optional start_time / end_time ("HH:MM", local IST). Windows start and end on the hour (WINDOW_STEP_MIN, 60 by default, 30 allowed) inside the mall day (MALL_OPEN_HOUR=10 → MALL_CLOSE_HOUR=22). A cricket wall game MUST have a window (422 otherwise); loop ads ignore it.

• Clash rule: a cricket window is refused with 409 if it overlaps ANY cricket window already booked on that screen on ANY shared day (partial overlaps included; a legacy all-day cricket booking blocks the whole day). Two overlapping items in one request are refused with 422. A window that has already ended today is refused with 422.

• Price of a windowed item = rate × slots × days × (window hours ÷ mall hours), rounded, minimum ₹1. Items carry start_time/end_time in booking JSON.

• GET /v1/screens/{id}/cricket-hours?start&end → {open_min, close_min, step_min, steps[{start_min,end_min,label,free,taken_by}], taken[]}: a step is free only if free on every day of the range.

• Resolution by the clock: /v1/play/{screen}, join, kiosk and board pick the cricket game whose window contains the local time now; a whole-mall-day window counts as all day. Outside every window the 404 says when the next game starts. Grace: the kiosk home and claims keep working 5 minutes after a window ends (a live innings finishes; a code typed a minute late works); images stay served for 3 hours. A code issued for an earlier game is refused at the kiosk with 410 and expired.

• GET /v1/device/schedule entries carry window {start_min,end_min} or null; the player treats a slot outside its window as idle, so the wall switches games on the hour without a schedule push.

• Migration c3e5a7b9d1f2 adds booking_items.start_min/end_min.

• Per-screen hours (ops): Screen.open_min/close_min/window_step_min (migration d5a7c9e1f3b4). POST/PATCH /v1/ops/screens[/{id}] take open_time, close_time ("HH:MM") and window_step_min (30 or 60); 422 if closing ≤ opening or times are off the step; 409 if the new hours no longer contain a window a future booking already holds. Public GET /v1/screens carries open_time, close_time, window_step_min.

• Windows for every ad type: any BookingItemIn may carry a window; loop ads then play only inside it (device schedule window) and pay for that share of the screen's day. Only cricket windows are exclusive.

• GET /v1/screens/{id}/hours?start&end is the generic grid (cricket-hours remains as an alias).

• Ops metrics (v1.9): GET /v1/ops/metrics/network?from&to → totals + one row per screen (plays, OTS, watchers, attention, bookings, revenue booked, advertisers, cricket scans/innings, device, occupancy today). GET /v1/ops/metrics/screens/{id}?from&to = the screen detail across every advertiser plus by_advertiser[], bookings_in_range, revenue_booked and the cricket funnel. Ops may read any campaign's GET /v1/metrics/campaigns/{booking} (the advertiser's own report). GET /v1/ops/bookings rows carry advertiser_email, advertiser_id, phase.

• Preview asset (v1.9): optional preview key on every game creative — an mp4 recording or a png/jpg poster of the creative on the wall. Uploaded by the advertiser (POST /v1/creatives/{id}/assets/preview) or by ops (POST /v1/ops/creatives/{id}/assets/preview). Unlike every other asset it does NOT reset approval; it only feeds the booking picker's preview tile.

• Footage library (v1.9): platform_assets (migration e6b8d0f2a4c6). Ops: GET /v1/ops/library (every platform key with label, hint, video flag, url, size, updated_at), POST /v1/ops/library/{key} (mp4 for clips, png/jpg for stills), DELETE /v1/ops/library/{key}. Public GET /v1/library/{key} serves the file. Platform keys (CRICKET_PLATFORM_KEYS): the ten stadium clips plus stadium, batter, ball, ball_gold, trophy. A cricket creative's assets (bundle, creative dict, kiosk/phone assets) include every platform key it does not carry itself, pointing at the library; the sponsor's own upload of a key wins. Advertisers upload only brand keys (CRICKET_BRAND_KEYS): logo, hero, pack, board, scoreboard_logo, helmet_logo, jersey_logo, bat_sticker, ad_break, preview — the editor no longer offers footage uploads.

• Footage at three levels (v1.9): a cricket wall resolves each platform key as SCREEN override → the creative's own file → the library. Ops endpoints: POST/DELETE /v1/ops/creatives/{id}/assets/{key} (any key; never touches approval), GET /v1/ops/screens/{id}/assets (each key with its source), POST/DELETE /v1/ops/screens/{id}/assets/{key} (migration f7c9e1a3b5d7, screen_assets). Public GET /v1/screens/{id}/assets/{key}. The wall's GET /v1/creatives/{id}/game resolves for the calling device's screen; the portal preview (a user) resolves without a screen. The device schedule's sha256 for a cricket creative is a digest of the creative, the library and the screen's overrides, so walls refetch when any footage changes.

• Library per template (v1.9): PLATFORM_KEYS_BY_TEMPLATE — cricket: the stadium set; spin and wheel: fx_ring, fx_burst, fx_coins. /v1/ops/library items carry group and templates. Spin and wheel creatives inherit the effect clips the same way cricket inherits the stadium (screen > creative > library); their editors no longer offer effect uploads. Symbols, wilds, bonus, win film, background and living poster stay the brand's.

v1.8 — WhatsApp delivery through AiSensy (2026-10-24)

Every message to a shopper's phone goes through one module, app/services/aisensy.py (AiSensy campaign API; one POST per message). WHATSAPP_PROVIDER = log (default, delivers nothing) | aisensy. With aisensy, AISENSY_API_KEY is required and the backend refuses to boot without it in production.

• Wallet OTP POST /v1/wallet/otp/start → 204 after AiSensy accepts the authentication template freebee_otp ({{1}} = code, copy-code button = code). If AiSensy refuses or is unreachable → 502 {"detail": "We could not send the code right now. Try again in a minute."} and nothing is minted: the attempt does not count against the 5-per-hour allowance. WALLET_OTP_DEV=1 still returns {dev_code} with 200 and must be unset at launch.
• Cricket join code: template freebee_cricket_code ({{1}} code, {{2}} brand, {{3}} screen label); failures are logged and swallowed because the phone page shows the code anyway.
• Env: WHATSAPP_PROVIDER, AISENSY_API_KEY, AISENSY_OTP_CAMPAIGN, AISENSY_CRICKET_CAMPAIGN (campaign = the template name approved in AiSensy), AISENSY_API_URL, AISENSY_TIMEOUT_SECONDS, AISENSY_OTP_COPY_CODE_BUTTON.
• Privacy unchanged: phone leaves the server only in the AiSensy request body; logs carry +91••••••1234; the code is never logged and never in an error.

v1.8 — AI second opinion on wall names (2026-10-24)

POST /v1/play/{screen_id}/join and the kiosk name entry run the display name through the block list as before; when MODERATION_PROVIDER=anthropic (needs ANTHROPIC_API_KEY) a name that passes the list is also shown to Claude Haiku with one question (fine on a mall screen seen by families, in any Indian language or script?). BLOCK → the same 422 as the list, reason "That name can't go on the big screen. Please use your real name, without foul language." Timeouts (1.5 s) and errors fail open and log one warning; decisions are cached in memory per name. Only the name is sent, nothing else.

Billing — invoices, Razorpay behind env, void + credit (2026-10-24)

An invoice is issued the moment a booking becomes confirmed (creative already approved at booking time, or ops approving the creative of an awaiting_creative booking). Numbers are FB-<year>-<6 digits>, sequential per year, never reused (a voided invoice keeps its number). Money fields are integer paise; GST is added on top at gst_rate_bp (default 1800 = 18%), rounded half-up to the paise. Bookings keep price_total in integer rupees as before; subtotal_paise = price_total × 100.

Provider: PAYMENTS_PROVIDER = manual (default) | razorpay. With manual nothing online exists: /pay and /confirm answer 409, the web hides "Pay now" and says "Pay by bank transfer; details are on the invoice", ops record payments with mark_paid. With razorpay the three RAZORPAY_* env vars are required (the backend refuses to boot in production without them).

Advertiser (ops may read every invoice)

• GET /v1/billing/config → {provider, online_payments, key_id|null, bank_details:[str], due_days}. Never the secret.
• GET /v1/invoices → newest first: [{id, number, kind:"invoice"|"credit_note", credit_for_invoice_id, booking_id, campaign_name, creative_name, issued_at, due_at, status:"draft"|"issued"|"paid"|"void", subtotal_paise, gst_rate_bp, gst_paise, total_paise, currency:"INR", paid_at, payment_method: "razorpay"|"bank"|"cash"|"other"|null, razorpay_order_id, notes}]. Credit notes carry negative amounts.
• GET /v1/invoices/{id} → the row above plus seller:{name, gstin, address, state_code, bank_details}, buyer:{name, gstin, address_line1, address_line2, city, pincode, state_code}, items:[{screen_label, venue_name, slot_count, days, start_date, end_date, window, amount_paise}], credit_for_number, gst_split:"cgst_sgst"|"igst" (same state code on both sides → CGST+SGST), provider. 404 for another advertiser's invoice.
• POST /v1/invoices/{id}/pay → {order_id, amount, currency, key_id} for Razorpay Checkout (amount in paise; a second call reuses the same order). 409 when the provider is manual or the invoice is not issued; 502 when Razorpay cannot be reached.
• POST /v1/invoices/{id}/confirm {order_id, payment_id, signature} → verifies HMAC-SHA256(order_id|payment_id, key secret) and marks the invoice (and its booking) paid with method razorpay. 400 bad signature or order mismatch; 409 already paid by a different payment. Re-confirming the same payment id is a 200 no-op.
• POST /v1/webhooks/razorpay (no user auth; header X-Razorpay-Signature = HMAC-SHA256 of the raw body with RAZORPAY_WEBHOOK_SECRET). Handles payment.captured: finds the invoice by order_id, checks the amount, marks paid. Idempotent: the same payment twice → {"status":"duplicate"}, another payment on a paid invoice → already_paid, nothing changes either way. Other events → ignored. 400 bad signature, 503 when no webhook secret is configured.

Ops

• POST /v1/ops/bookings/{id}/mark_paid {method?: "razorpay"|"bank"|"cash"|"other", notes?} (body optional, default bank) → booking dict. Marks the booking's invoice paid with that method (issues one first if the booking somehow has none). 409 if already paid or cancelled.
• POST /v1/ops/invoices/{id}/void {reason} → voids an unpaid invoice (409 if paid or already void). The number is kept.
• POST /v1/ops/invoices/{id}/credit {amount_paise, reason} → 201 credit note row (kind: "credit_note", negative subtotal/gst/total, credit_for_invoice_id, its own sequential number). amount_paise is the amount before GST; GST is credited at the invoice's rate. 409 if the credit would exceed what is left on the invoice or the invoice is void. No money moves: Razorpay refunds are done by hand in the Razorpay dashboard for now.

Booking dict addition

• GET /v1/bookings, POST /v1/bookings, GET /v1/ops/bookings, mark_paid now include invoice: {id, number, status, total_paise, due_at, payment_method} | null (null until the booking is confirmed).

Profile (billing details)

• GET /v1/me profile and PATCH /v1/me/profile gain address_line1, address_line2, city, pincode, state_code (two-digit GST state code, ^\d{2}$, 422 otherwise). GSTIN is upper-cased. An empty string clears an optional field. Nothing beyond what a GST invoice needs is collected.

Env

PAYMENTS_PROVIDER, RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_WEBHOOK_SECRET, INVOICE_DUE_DAYS (7), INVOICE_GST_RATE_BP (1800), BILLING_SELLER_NAME, BILLING_SELLER_GSTIN, BILLING_SELLER_ADDRESS, BILLING_SELLER_STATE_CODE, BILLING_BANK_DETAILS (details separated by |, printed on unpaid invoices). Migration b1ll1n6a0001 (billing_invoices.py): tables invoices, invoice_sequences; five nullable columns on advertiser_profiles.

Review checklist (mall sign-off) — 2026-10-24

• POST /v1/ops/creatives/{id}/approve now REQUIRES a body: {checklist:{likeness_rights:true, prize_terms_clear:true, mall_rules_fit:true}, mall_signoff_ref?: str≤200}. Any tick missing or false → 422 {"detail": "Tick all three checks before approving: …"} (plain sentence, not a pydantic error list). The 409s (already rejected, missing game assets) are unchanged and are checked after the ticks.
• On success the ticks, the trimmed reference (null when blank) and checked_at are stored on creatives.review_checklist (JSON, nullable; migration a9d2f4c6e8b1, file legal_review_checklist.py) and returned as review_checklist on every ops creative response (GET /v1/ops/creatives, approve, reject). Advertiser responses (GET /v1/creatives) never carry it.
• Reject needs no checklist. Re-approval after a replace / config change asks for the ticks again and overwrites the stored checklist.
• Wallet consent: the web now sends consent_version:"2026-10" with the reworded consent text (web/lib/wallet.ts); the server stores whatever version the client sends, as before.

Accounts — password reset, messages, team roles (2026-10-24)

Migration a9b1c3d5e7f9 (accounts_reset_team_notifications.py): users.business_id (backfilled to the user's own id) + users.team_role (owner | editor | viewer, default owner); new tables password_resets, team_invites, notifications.

Email provider (app/services/email.py, mirrors aisensy.py): EMAIL_PROVIDER = log (default; logs subject + masked recipient p••••@brite.in, never the body) | resend (RESEND_API_KEY, EMAIL_FROM). WEB_URL is the base of every link in an email. EMAIL_DEV_ECHO=1 (dev only, with log; production refuses to boot) makes the two link-minting endpoints below return the link in JSON.

• POST /v1/auth/forgot {email} → 204 always (never says whether the email exists). Mints a single-use token (SHA-256 stored, 30 min, PASSWORD_RESET_TTL_MINUTES) and emails "Reset your Freebee password" with ${WEB_URL}/reset?token=…. With dev echo: 200 {reset_url} (null for unknown emails).
• POST /v1/auth/reset {token, password} → 204; sets the password and burns every outstanding token for that user. Invalid, used or expired → 410 "This reset link has expired or was already used. Request a new one."
• GET /v1/me and the auth responses' user now carry team_role and business_id (null for ops).

Notifications (one row per member of the business; the same text is emailed to each member when EMAIL_PROVIDER is not log; email failures are logged and swallowed):

• Emitted on: creative approved ("Your ad Diwali Sale is approved and will play from 2 Nov."), creative rejected (with the reason), booking confirmed (at booking time when the ad is already approved, or when approval confirms an awaiting booking), booking marked paid (once), campaign starts today, campaign ended yesterday + report ready. kind ∈ creative_approved | creative_rejected | booking_confirmed | booking_paid | campaign_started | campaign_ended. href is a portal path (/creatives, /campaigns/{booking_id}).
• GET /v1/notifications?unread=0|1&limit=100 → {unread, items[{id, kind, title, body, href, created_at, read_at}]} newest first.
• POST /v1/notifications/{id}/read → the row (404 if not yours). POST /v1/notifications/read-all → {marked, unread: 0}.
• POST /v1/ops/notifications/run-daily (ops) → {date, started, ended}. Idempotent per booking per user; there is no in-process scheduler, so call it once a day (IST date).

Team roles (thin slice). A business is keyed by its first user's id; creatives, campaigns, bookings, reports and overview metrics are scoped by User.business_key (business_id or own id), so every teammate sees the same account. Viewers get 403 "Your role on this team is view only…" on every write to creatives and bookings (upload, game create/update, assets, rename, replace, delete, book, cancel).

• GET /v1/team (advertisers) → {business_id, business_name, my_role, roles[{role, explains}], members[{id, email, role, joined_at}], invites[{id, email, role, created_at, expires_at}]} (pending, unexpired invites only).
• POST /v1/team/invites {email, role: owner|editor|viewer} (owners only, else 403) → 201 invite + emailed (+ invite_url with dev echo). Emails "<Business> invited you to Freebee" with ${WEB_URL}/signup?invite=<token> (7 days, TEAM_INVITE_TTL_DAYS). 409 if the address is already on the team or has an account with another business; a re-invite replaces the earlier link.
• DELETE /v1/team/invites/{id} (owners) → 204.
• POST /v1/auth/invite/lookup {token} (public; a POST so the token never sits in an access-log path) → {email, role, business_name} or 410.
• POST /v1/auth/signup accepts invite_token (then business_name is optional and ignored): the new user joins the inviter's business with the invited role; 403 if the email differs from the invited one, 410 if the invite is used or expired. Without an invite, business_name is required (422).

Prize fulfilment + upload rules (2026-10-24)

Prize tiers: stock and coupon life (additive, every game template)

SpinPrize / WheelPrize / CricketPrize gain stock_total (int ≥1 | null, default null = unlimited) and expires_days (1–365 | null, default null = COUPON_TTL_DAYS, 30).

• Stock: issued = win tokens ever minted at that tier for the booking (or the unbooked creative), the same bucket the daily cap uses. Once issued >= stock_total the draw skips the tier and falls through to the next one down (spin/wheel: big → mid → everyone-wins; cricket: down the run bands), exactly like a spent daily cap.
• Expiry: a coupon of that tier expires expires_days after it is claimed.
• GET /v1/metrics/campaigns/{booking} gains top-level prize_stock: [{tier, title, stock_total, issued, stock_left}] (all-time for the booking, not range-filtered; [] for non-game creatives; stock_left null when unlimited).

Per-phone fraud limits (claim time, keyed on the phone HASH)

Settings PRIZE_MAX_PER_PHONE_PER_CAMPAIGN_DAY (2) and PRIZE_MAX_PER_PHONE_PER_DAY (5). A "prize" here is a coupon above its game's everyone-wins tier; everyone-wins coupons never count and are never limited. The count joins coupons → wallet_users.phone_hash (UTC day), so a re-registered phone is the same shopper. When either limit is reached, POST /v1/wallet/claim still returns 201 but the coupon is minted at the everyone-wins tier with limited: true, message: "You have claimed today's prizes, come back tomorrow", original_tier kept on the row. Every coupon dict (claim, /wallet/me, 409 payload) now carries limited (bool) and message (string | null). The older one-coupon-per-(user, campaign)-per-day 409 rule is unchanged and applies first; the per-campaign limit therefore matters once that rule is relaxed. Double redemption of a code was already impossible (POST /v1/redeem → 409 "already redeemed"); tests/test_prizes_uploads.py::test_same_code_cannot_be_redeemed_twice proves it.

Expiry reminders

coupons gains reminded_at, limited, original_tier (migration prizes_coupon_fulfilment). remind_expiring_coupons() (app/services/prizes.py) selects coupons with status issued, reminded_at null and now < expires_at <= now + COUPON_REMINDER_WINDOW_HOURS (24), stamps reminded_at and, with WHATSAPP_PROVIDER=aisensy, sends template AISENSY_REMINDER_CAMPAIGN = freebee_coupon_reminder ({{1}} prize title, {{2}} brand, {{3}} expiry date DD Mon YYYY); with log it logs the masked phone only. Erased wallets are stamped and skipped. Codes are never logged.

• POST /v1/ops/coupons/run-reminders (ops) → {reminded, sent, skipped, failed}; idempotent per coupon, safe to call from a daily scheduler.

Ops fulfilment

• GET /v1/ops/wallet/fulfilment?days=7 (ops, 1–90) → {days, issued, redeemed, expiring_soon, blocked_by_limit, campaigns:[{booking_id, creative_id, campaign, brand, tier, title, issued, redeemed, stock_total, stock_left}]}. Counts only: never a phone, never a code.

Upload rules: conversion and edits

• POST /v1/creatives (and POST /v1/creatives/{id}/file) accept .mov .webm .mkv .avi .m4v when ffmpeg/ffprobe are on the host (app/services/transcode.py; Railway: see docs/DEPLOY.md). The upload is probed; anything that is not already H.264 yuv420p + AAC in an mp4 is re-encoded to H.264/AAC mp4, yuv420p, faststart, 30 fps, scaled to fit 1080×1920 (portrait, default) or 1920×1080 (sources wider than tall), padded black, cut at VIDEO_MAX_DURATION_S. The original is removed; the stored file is the mp4. Size limits are checked on the original as before.
  • Creative dict gains converted: bool and editable: bool (images always; videos only with ffmpeg). validation.conversion = {from:{filename, ext, codec, container, width, height, rotation, duration_s}, to:{ext, codec, audio, canvas, mode}, capped_to_s} when converted.
  • Without ffmpeg the foreign containers are refused: 422 {"reasons": ["unsupported file type '.mov': Our server cannot convert this format yet; export as H.264 MP4"]}. mp4 behaves exactly as before (including unreadable files: probe skipped, recorded in checks).
• POST /v1/creatives/{id}/edit (owner) body {trim: {start_s, end_s}} and/or {crop: "fit" | "crop"} → creative dict. Re-encodes into a NEW file (old removed), appends validation.edits[] = {op:"trim", start_s, end_s, mode} | {op:"crop", mode, canvas?}, keeps validation.conversion, RESETS status to pending and bumps the schedule version (same semantics as replacing the file). Trimmed length must be ≤ VIDEO_MAX_DURATION_S (422). Images: crop only (Pillow fit = black letterbox / crop = centre fill to the matching canvas); trim on an image → 422. Video without ffmpeg → 422 with the reason above. Game creatives → 409.

Device reliability + proof of play (2026-10-24)

Check-in health (additive, every field optional)

• POST /v1/device/heartbeat accepts, besides playing_creative_id and watchers_now: player_version (≤40 chars), uptime_s, last_error (≤200 chars), last_error_at, cache:{cached,total}, storage:{usage_bytes?,quota_bytes?}, camera: off|no_permission|counting, screen:{width,height}, online (bool), queued_events. When any of them is present the whole health part is stored as the device's latest snapshot (devices.health, plus reported_at); a check-in without them keeps the previous snapshot. The browser player reports player_version = "web-1.0.0".
• The answer is now {"schedule_version": n, "commands": [{id, kind}]} — commands are the device's pending remote commands, oldest first (empty for players that never get any). Older players ignore the extra key.

Remote commands

• Table device_commands (id, device_id, kind, created_by, created_at, acked_at, result). Kinds: reload | restart_engine | clear_cache | refetch_schedule.
• Ops: POST /v1/ops/devices/{device_id}/commands {kind} → 201 command; GET /v1/ops/devices/{device_id}/commands (last 20, newest first). Ops role required (403 otherwise); 404 for an unknown or revoked device.
• Device: POST /v1/device/commands/{id}/ack {result?} → {id, kind, acked_at, result}. Device token only; 404 when the command belongs to another device; idempotent (a second ack keeps the first result). The player executes: reload = page reload; restart_engine = tear down and rebuild the loop in place; clear_cache = drop Cache Storage + refetch; refetch_schedule.
• GET /v1/ops/devices → one card per active device: {id, device_uid, status, screen:{id,label,zone,venue}|null, last_seen_at, playing_creative_id, watchers_now, health, attention:[str], last_command, pending_commands}. attention is the server's plain-English list of reasons the device needs a look (no check-in for > 2 min, player reports offline, cache incomplete, camera permission denied, ≥ 10 queued records, recent error); the list is sorted most-attention first.

Offline cache + dedupe (unchanged contract, confirmed)

• Play records already carry client_play_id; the server ignores a play whose (device, client_play_id) was recorded before even when it arrives under a new batch_seq, and a re-sent batch_seq answers duplicate. A retry therefore never double-counts.

Proof of play

• GET /v1/bookings/{id}/proof?format=csv|json (advertiser owning the booking, or ops; 404 otherwise). Every play record of the booking, oldest first: play_id, screen_id, screen, creative_id, creative, started_at, duration_ms, watchers (null/blank when the screen had no working sensor). CSV ends with #proof booking_id=… records=n first=<iso> last=<iso> signature=<hex>; JSON carries proof:{records, first, last, signature}. Signature = HMAC-SHA256 with a key derived from SECRET_KEY (HMAC(SECRET_KEY, "proof-of-play")) over the CSV content before the footer, or over the canonical JSON (sort_keys, no spaces) of records.
• POST /v1/proof/verify (no auth; multipart field file or the file as the raw body) → {valid, records, first, last, reason?}. Any edit to a row, a removed row or a changed count gives valid: false; a non-proof file gives reason: "not a proof file".

Bidding for busy windows (2026-10-24)

Every window stays first come, first served at the fixed rate, except busy windows that ops mark on screens with bidding switched on. Sealed bids, first price: winners pay their own bid. Migration bidding_busy_windows (bidding_busy_windows.py): screens.bidding_enabled, table bidding_rounds, and bookings.bid_round_id / bid_per_slot_day / bid_at / cancel_reason.

Money unit. A bid and a floor are integer rupees per slot per day for that window (an hour window's share of the day is already inside the number). Price of a bid = bid × slots × days. The default floor is the fixed price of one slot for one day of that window (rate × window hours ÷ screen hours, rounded, min ₹1).

Ops (role=ops)

• PATCH /v1/ops/screens/{id} {bidding_enabled: bool} (with the other screen fields). Switching off while the screen has open rounds → 409. Screen dicts (ops and public GET /v1/screens) carry bidding_enabled.
• POST /v1/ops/screens/{id}/bidding/rounds {start_date, end_date, start_time?, end_time?, floor_per_slot_day?, closes_at?, slots_on_offer?, note?} → 201 round (ops shape below). Times are "HH:MM" IST on the screen's step (both omitted = all day). Defaults: floor as above, slots_on_offer = the screen's loop_slots (1…loop_slots), closes_at = BIDDING_CLOSE_LEAD_HOURS (48) before the window first starts (ISO; a value without a zone is read as UTC). 409 bidding off / overlaps another open round on the screen; 422 window not in the future, close not before the window start, default close already past ("pick a close time").
• GET /v1/ops/screens/{id}/bidding → {bidding_enabled, rate_per_slot_day, loop_slots, rounds[]} (open first). Ops round = public round + {note, created_at, closed_at, result:{winners, losers, slots_offered, slots_sold, winning_booking_ids}|null, bids:[{booking_id, campaign_name, advertiser_email, bid_per_slot_day, slot_count, bid_at, status, cancel_reason}]} (best first). Ops run the auction, so they see every amount.
• DELETE /v1/ops/bidding/rounds/{id} → 204 only while open with no bids ever placed; else 409.
• POST /v1/ops/bidding/rounds/{id}/close → {result, round}: force-close one round now.
• POST /v1/ops/bidding/close-due → {closed: n, rounds:[result]}: closes every open round whose closes_at has passed. Idempotent (a closed round is never decided twice; a second call closes 0); there is no in-process scheduler, so call it every few minutes from a cron.
• GET /v1/ops/bookings phase gains bidding; POST /v1/ops/bookings/{id}/mark_paid on a bidding booking → 409.

Advertiser

• GET /v1/screens/{id}/bidding?start&end (any signed-in user; dates optional, both or neither) → {bidding_enabled, rounds:[{id, screen_id, screen_label, start_date, end_date, start_time, end_time, floor_per_slot_day, slots_on_offer, closes_at, status, bidders}]} — open rounds only. Sealed: floor, bidder count (distinct businesses with a live bid) and close time; never an amount.
• POST /v1/bookings gains optional bid_per_slot_day (int ≥ 1).
  • Without it, any item whose dates and hours touch an open round (an all-day item touches every round on those days) → 409 with a sentence that explains bidding, the floor and the close time. Items outside busy hours book as before.
  • With it: exactly one item (422 otherwise), matching the round's dates and hours exactly (422), slot_count ≤ slots_on_offer (422), bid ≥ floor (422 "below the floor"), round open and not past closes_at (409), one bid per business per round, even after withdrawing (409 "raise it instead"), not a cricket game (422). → 201 booking with status:"bidding", no invoice, holds no capacity, price_total = bid × slots × days. Viewers → 403 as for any booking.
• POST /v1/bookings/{id}/bid {bid_per_slot_day} (editor/owner) → booking dict. Raise only: an amount ≤ the current bid → 422; round closed or past its close time → 409; viewers 403; another business's booking 404. A raise moves bid_at (ties go to whoever reached the amount first).
• POST /v1/bookings/{id}/cancel on an open bid withdraws it (cancel_reason:"withdrawn"); the business cannot bid again in that round.
• Booking dicts gain cancel_reason ("outbid" | "withdrawn" | null) and bid: null | {per_slot_day, bid_at, outcome:"open"|"won"|"outbid"|"withdrawn", round:<public round>, next_window:{screen_id, start_date, end_date, start_time, end_time}|null} — the caller's own bid only. next_window (outbid only) is the first run of the same length and hours after the busy window with enough free slots and no open round (60-day horizon); the web links it to /book?screen&start&end&from&to.
• Bidding bookings are left out of spend totals, screen revenue, cricket resolution and window clashes.

Close rule

At close: offer = min(slots_on_offer, free slots on the window's busiest day) (fixed bookings made before the window was marked busy keep theirs). Live bids are ranked by amount desc, then bid_at asc, then booking time; each bid wins if its slot_count still fits, otherwise loses (a smaller bid further down may still fill the remainder). Winners: price stays at their bid; ad approved → confirmed, schedule materialized and the invoice issued through the normal billing path (integer paise = price × 100 + GST); ad still in review → awaiting_creative (confirms + invoices on approval like any booking). Notification bid_won. Losers: cancelled, cancel_reason:"outbid", nothing charged, notification bid_lost naming the next free window. Notification kinds gain bid_won, bid_lost (href /campaigns/{booking_id}).

Env: BIDDING_CLOSE_LEAD_HOURS (48).

Security review (2026-10-24, branch fix/security-review)

Behaviour changes a client can observe; nothing else in this contract moved.

• POST /v1/invoices/{id}/confirm → 400 unless the invoice already has the Razorpay order that /pay created for it AND order_id equals it (the old check was skipped when /pay had never run, so another order's valid signature could mark the invoice paid).
• Viewers now get 403 on POST /v1/creatives/{id}/edit and PATCH /v1/me/profile too.
• 429 {detail} with Retry-After (seconds) from the throttles in app/core/ratelimit.py (in-process windows, client = right-most X-Forwarded-For) and DB counts: POST /v1/auth/login 30 attempts/IP/5 min and 20 wrong passwords/account/15 min (then even the right password waits); /auth/signup 20/IP/h; /auth/forgot 10/IP/h; /auth/reset + /auth/invite/lookup 30/IP/15 min; POST /v1/team/invites 30/business/24 h; POST /v1/wallet/otp/start 60/IP/h across phones (the 5/phone/h rule is unchanged); POST /v1/proof/verify 30/IP/min. Every number is an env var (LOGIN_MAX_ATTEMPTS_PER_IP, LOGIN_MAX_FAILURES_PER_EMAIL, SIGNUP_MAX_PER_IP, FORGOT_MAX_PER_IP, FORGOT_MAX_PER_USER, TOKEN_LOOKUPS_MAX_PER_IP, TEAM_INVITES_MAX_PER_BUSINESS, WALLET_OTP_MAX_STARTS_PER_IP, CRICKET_WHATSAPP_MAX_PER_IP, PROOF_VERIFY_MAX_PER_IP); RATE_LIMITS_ENABLED=0 turns the in-process ones off.
• POST /v1/auth/forgot still answers 204 for everything; beyond 3 links per account per hour it sends nothing. The email now goes out after the response.
• POST /v1/play/{screen}/join with phone: past 10 WhatsApp sends per IP per 10 min the ticket is still issued (201, code on screen) but no WhatsApp goes out.
• User JWTs carry pv (keyed fingerprint of the password hash). After a password reset (or an OPS_PASSWORD rotation) every earlier token answers 401 "Your password was changed. Sign in again." Tokens minted before this release carry no pv and expire normally.
• Creative uploads: a .png/.jpg must start with PNG/JPEG magic bytes and an .mp4 with an ISO-BMFF ftyp box, else 422 {"reasons": ["the file is named .png but is not a png or jpg image"]}; the served Content-Type follows the bytes. ffmpeg/ffprobe open uploads with -protocol_whitelist file -format_whitelist mov,matroska,avi only.
• Every API response carries X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer.
• Web /player/api/* proxies only v1/device/**, v1/creatives/{id}/(file|game|assets/{key}), v1/library/{key}, v1/screens/{id}/assets/{key} (404 otherwise) and forwards only a Device … Authorization header.

Platform jobs and hardening (2026-10-26, branch feat/jobs-hardening)

Built-in scheduler

app/core/scheduler.py: a daemon thread inside the API process runs the platform's background jobs, so no external cron is needed. It starts in the FastAPI lifespan when SCHEDULER_ENABLED is on (unset = on with ENVIRONMENT=production, off everywhere else, including tests). Every SCHEDULER_TICK_SECONDS (30) it reads the IST wall clock and runs what is due:

The due rule reads job_runs, so it survives restarts: a daily/weekly job is due when its most recent slot has passed and no run has started since; a late boot catches up within 12 h (24 h for the weekly report), otherwise it waits for the next slot. Every job was already idempotent, so a catch-up or a manual run next to a scheduled one changes nothing twice. A job that raises is rolled back, recorded with ok:false and logged once; the thread keeps going. Railway runs one uvicorn process, so one scheduler runs; with more replicas a DB lock is needed first (TODO in the code). The ops endpoints POST /v1/ops/bidding/close-due, /v1/ops/notifications/run-daily and /v1/ops/coupons/run-reminders remain and behave as before (they do not write job_runs).

Table job_runs (migration jobs_job_runs): id, job, trigger ("schedule"|"manual"), started_at, finished_at, ok (null while running), detail (a short scrubbed summary such as {"closed": 0} or RuntimeError: …; never a code, token or phone).

• GET /v1/ops/jobs (ops) → {scheduler:{enabled, running}, jobs:[{job, label, explains, schedule, next_run_at|null, running, last_run:{id, job, trigger, started_at, finished_at, ok, detail}|null}]} in the table's order. next_run_at is null while the scheduler is off.
• POST /v1/ops/jobs/{job}/run (ops) → the run row (trigger:"manual"; ok:false with detail when the job failed, still 200). 404 unknown job; 409 while the same job is already running.
• Web: ops Today page, "Background jobs" card: last run per job and a Run now button.

Proof of play v2

Downloads are now version 2: the signature binds the booking id, the booking's screen ids, its date range and the generation time as well as the rows.

• CSV: first line #proof version=2, then the header and rows as before, then the footer #proof booking_id=&lt;id&gt; screens=<id,id> from=&lt;YYYY-MM-DD&gt; to=&lt;YYYY-MM-DD&gt; generated_at=&lt;iso&gt; records=&lt;n&gt; first=&lt;iso&gt; last=&lt;iso&gt; signature=&lt;hex&gt;. The signature covers every byte of the file up to (not including) signature=.
• JSON: {version:2, booking_id, screen_ids[], start_date, end_date, generated_at, records[], proof:{records, first, last, signature}}; signature over the canonical JSON (sort_keys, no spaces) of every top-level field except proof.
• POST /v1/proof/verify → {valid, version: 2|1|null, records, first, last, …}. v2 adds the bound booking_id, screen_ids, start_date, end_date, generated_at. Version 1 files (rows-only signature, no version line) still verify and answer version: 1 plus warning: "This is a version 1 proof file. Its signature covers the play rows only, not the booking, screens or dates, so check those against your booking yourself." (no booking_id echoed). Removing the version line or field from a v2 file does not turn it into a valid v1 file. Non-proof input: version: null, reason: "not a proof file".

Roles

• POST /v1/redeem now needs an owner or editor (viewers 403, the usual view-only sentence); ops unchanged.
• PATCH /v1/team/members/{user_id} {role: owner|editor|viewer} (owners only, 403 otherwise) → member {id, email, role, joined_at}. 404 when the user is not on your team. 409 "A team needs at least one owner. Make someone else an owner first." when it would demote the only owner (an owner may change their own role while another owner exists). Takes effect on the next request.
• DELETE /v1/team/members/{user_id} (owners only) → 204. 409 for yourself ("You cannot remove yourself…"), for the last owner, and for the person who opened the account (every row of the business is keyed on their id: "Change their role instead, or ask our team to move the account"). 404 when not on your team. The removed person keeps their sign-in but becomes the owner of an empty account of their own (business_id = own id, profile business name cleared); their copies of the team's notifications are deleted. Access ends on their next request.
• Web: Team page members list gains a role select and a Remove button with an inline confirm (owners only; no Remove on yourself or on the person who opened the account).

Weekly report email

app/services/reports.py send_weekly(db) (the Monday job): for every business with activity in the last Monday-to-Sunday IST week (plays, reward QR scans, or spend), each member gets one email "Your weekly Freebee report" with plays, watchers (or "not measured on these screens" when no sensor counted anyone), QR code scans and spend (integer rupees of bookings made that week, not cancelled, not an open bid) and a link to ${WEB_URL}/reports, through app/services/email.py (EMAIL_PROVIDER=log sends nothing and logs the masked address). It is also recorded as a notification, kind weekly_report, title "Your weekly report is ready", href /reports?week=<monday>. Idempotent per member per week; an email failure is logged and swallowed. Result {week_start, week_end, businesses, notified, emailed, skipped, failed}.

Web content security policy

The frame-ancestors-only policy is replaced by a full CSP (web/lib/csp.mjs):

• Next pages: middleware.ts sets a fresh nonce per request; script-src 'self' 'nonce-…' plus *.posthog.com and checkout.razorpay.com. The root layout reads headers(), so every page is rendered per request (a page built ahead of time cannot carry a nonce).
• Game engine pages (/catch|spin|wheel|cricket|fortune|cabinet|clock.html, static files with inline scripts): script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com (qrcodejs). The trade-off is documented in lib/csp.mjs.
• Both: connect-src self, the API origin from NEXT_PUBLIC_API_URL, *.posthog.com, the Sentry ingest origin (from NEXT_PUBLIC_SENTRY_DSN, else *.sentry.io), api.razorpay.com, lumberjack.razorpay.com; img-src/media-src self, the API, data:, blob:; style-src self, 'unsafe-inline', Google Fonts; font-src self, data:, fonts.gstatic.com; frame-src self, api.razorpay.com, checkout.razorpay.com; worker-src self, blob:; frame-ancestors, form-action, base-uri self; object-src 'none'. next dev adds 'unsafe-eval' and ws:.

Dashboard extras (2026-10-26, branch feat/dashboard-extras)

Additive only; nothing above changes. Migration extras_weekly_report_waitlist (extras_weekly_report_waitlist.py): users.weekly_report (bool, default true) and table waitlist.

Home weekly line

• No API change: GET /v1/metrics/overview?days=14 already returns by_day:[{date, plays, ots, watchers}] (14 rows, oldest first, UTC days, zeros included). Home draws plays per day and, when any day has watchers, watchers as a second line.

Screen sparklines (ops)

• GET /v1/ops/metrics/screens/sparklines?days=7 (ops; days 2–31, default 7) → {days, dates:[YYYY-MM-DD], screens:[{screen_id, label, plays:[n per day], total}]}. One call for the whole network, IST days, oldest first, today last; every screen gets a row (zeros when idle). Declared before /v1/ops/metrics/screens/{screen_id}, which is unchanged.

Video thumbnails (poster frames)

• With ffmpeg on the host (transcode.available()), every stored video gets a JPEG poster frame next to its file (<stem>.thumb.jpg, frame at 1 s, or the first frame of a shorter clip, 480 px wide). Generated on POST /v1/creatives, POST /v1/creatives/{id}/file, POST /v1/creatives/{id}/edit, POST /v1/ops/library/{key} and POST /v1/ops/screens/{id}/assets/{key}; removed with the file. Never required: without ffmpeg, or when ffmpeg fails, nothing is stored and thumbnail_url is null (the web keeps its <video> preview).
• Creative dicts gain thumbnail_url: "/v1/creatives/{id}/thumbnail" for a video with a poster frame, else null (images and games are always null).
• GET /v1/creatives/{id}/thumbnail → image/jpeg (same access as /file: owner, ops or a paired device; 404 when there is none).
• GET /v1/ops/library items gain thumbnail_url ("/v1/library/{key}/thumbnail" | null); POST /v1/ops/library/{key} answers thumbnail_url too. GET /v1/ops/screens/{id}/assets items gain thumbnail_url (the screen override's, or the library's when the key falls back to the library; null for stills).
• Public, like the clips themselves: GET /v1/library/{key}/thumbnail, GET /v1/screens/{screen_id}/assets/{key}/thumbnail.
• POST /v1/ops/footage/thumbnails/backfill (ops) → {available, videos, created, already, missing_file, failed, message?}. One pass over video creatives, library clips and screen overrides; idempotent (a second call creates 0). Without ffmpeg: 200 with available:false, created:0 and a message.

Device commands

• No API change: the ops Devices page now offers refetch_schedule as a button ("Refetch schedule": a new booking or approval is not showing yet; downloads today's loop again).

Printable campaign report

• No API change. The web route /campaigns/{booking_id}/print renders the report as static tables (the four bands, the funnel, top screens, the proof-of-play summary from the signed CSV footer) and opens the browser's print window ("Choose Save as PDF"). ?noprint=1 skips the automatic print window. Audience values the camera never measured print as "Not measured", never as sample numbers.

Preferences

• GET /v1/me/preferences → {weekly_report: bool} (default true).
• PATCH /v1/me/preferences {weekly_report?: bool} → the same shape. Any signed-in user, viewers included: it is the caller's own inbox, not team data, and changes nothing a teammate sees or receives. 422 for a non-boolean.
• The weekly email job (backend/app/services/reports.py send_weekly, built on feat/jobs-hardening) must skip every user whose users.weekly_report is false. The Reports page promises: "Every Monday morning: plays, watchers, scans and spend for the week, with a link here."

Waitlist

• POST /v1/waitlist {business_name (1–200), email, city (1–100), screens_of_interest? (≤300), website?} → 201 {ok:true}. Public (no auth). website is a honeypot: when filled the answer is the same 201 and nothing is stored. A repeat email updates its row (never a duplicate, never revealed). Email is lower-cased. 422 bad email or blank name/city. 429 with Retry-After past WAITLIST_MAX_PER_IP (10) per IP per hour (in-process limiter).
• GET /v1/ops/waitlist (ops) → [{id, business_name, email, city, screens_of_interest, created_at, updated_at}] newest first.
• GET /v1/ops/waitlist.csv (ops) → created_at,business_name,email,city,screens_of_interest; cells a spreadsheet would run as a formula are prefixed with '.
• Stored: a prospective advertiser's business contact, given on purpose. Never shopper data.

AI helpers (2026-10-26, branch feat/ai-helpers)

Four helpers. AI suggests; the advertiser decides: nothing changes an ad until they click, and a kept change sends the ad back for approval like any other edit. Every route needs a user token; every POST needs an editor (viewers 403). Env: AI_PROVIDER (off default | anthropic, needs ANTHROPIC_API_KEY), AI_MODEL, AI_TIMEOUT_SECONDS (15), AI_CHECK_NAMES_TIMEOUT_SECONDS (4), AI_COPY_MAX_PER_BUSINESS_PER_HOUR (20), AI_CHECK_NAMES_MAX_PER_BUSINESS_PER_HOUR (300), AI_COPY_CACHE_HOURS (24), ANTHROPIC_API_URL (tests/stub only; the wall name check uses it too). Production refuses to boot with AI_PROVIDER=anthropic and no key.

Status

• GET /v1/ai/status → {copy:{ready, reason, limits:{headline:28, slogan:60, prize_titles:32, whatsapp_blurb:160}, langs:{te, hi}, per_hour}, check_names:{ready, reason}, enhance:{ready:true, reason:null, presets:[{key, label, what}]}, preview_clip:{ready, reason, seconds:[6,8,10], motions:[slow_zoom, pan_left, pan_right]}}. reason when not ready: copy / names "Not set up yet; our team can switch this on", clips "Our server cannot render clips yet; our team can switch this on".

Copy suggestions

• POST /v1/ai/copy {kind: headline|slogan|prize_titles|whatsapp_blurb, brand (1-80), product (1-160), audience?, tone?, game_template?, offer? (prize titles: the offer in the advertiser's words), lang?: te|hi, competitors?: [str]} → {kind, limit, lang, options:[{text, why, chars, translation?}], cached}. 1 to 5 options.
• Server-side rules applied to whatever the model returns (an option that breaks one is dropped, never cut): text ≤ the limit above, no em-dashes, no claim words (best, number one, No. 1, #1, cheapest, guaranteed, cure, immunity, doctor, weight loss, invest, profit, loan, ...), no name from competitors, no duplicates; why ≤ 120 chars; translation dropped (null) if over the limit. The system prompt also forbids other brands, real people and invented facts.
• 503 {detail:"Not set up yet; our team can switch this on"} when off. 422 when competitors is non-empty (never sent to the model) or the model refuses ("No suggestions: <reason>"). 502 provider error, unreadable answer, or nothing passed the rules. 429 with Retry-After past AI_COPY_MAX_PER_BUSINESS_PER_HOUR model calls per business per hour (in-process window).
• Cached in memory by a hash of the normalised request (case and spacing ignored) + model for AI_COPY_CACHE_HOURS; a cache hit returns cached:true and does not count against the limit. Only the copy inputs are sent: no email, phone or account id.

Wrong-name guard

• POST /v1/ai/check-names {texts:[1-20 strings ≤255], brand?} → always 200 {ready, checked, flags:[{index, text, kind: celebrity|competitor|misspelt_brand, name, reason}]}. Fail-open: provider off, over AI_CHECK_NAMES_MAX_PER_BUSINESS_PER_HOUR, error, timeout or an odd answer → checked:false and only cached flags. reason is fixed server text: celebrity "This looks like a real, famous person's name; we cannot show a real person's name or likeness without their written permission." · competitor "This looks like another company's brand; your ad cannot name or give away a brand you do not own without their permission." · misspelt_brand "This looks like a misspelling of a famous brand (X); check the spelling, because a near-copy of a real brand will not be approved." The advertiser's own brand is never flagged. Cached per (brand, text).
• GET /v1/ops/creatives/{id}/name-check (ops) → the same shape for a saved game ad's brand, headline, slogan, tagline, prize titles and reward title; each flag adds field ("Brand", "Headline", "Prize (big)", "Reward", ...). Non-game creatives → flags:[].

Image enhance (Pillow, always on)

• Presets: auto (60% auto-contrast, half-strength grey-world colour balance, mild unsharp mask; size unchanged), brighten (auto + lifted shadows), punchy (auto + contrast 1.12, colour 1.25), fit_portrait / fit_landscape (auto, then contain on 1080x1920 / 1920x1080 over a darkened blur of the image; transparent padding for images with alpha). Never changes what is in the picture.
• POST /v1/creatives/{id}/enhance/preview {preset, asset_key?} → image/jpeg, Before | After side by side (each ≤720 px), Cache-Control: no-store. Nothing is saved.
• POST /v1/creatives/{id}/enhance {preset, asset_key?} ("Keep this") → creative dict. Image creatives: a NEW file (png stays png, else jpg), revalidated like an upload, validation.edits[] gains {op:"enhance", preset, at}. Game ads: asset_key (logo, hero, pack, any image asset but preview) gets a new file (≤5MB; a too-big png falls back to jpg, else 422). Both keep the previous file and append validation.versions[] = {filename, sha256, replaced_at, by, key?}; status RESETS to pending, the sha changes and the schedule version bumps. Versions survive later edits, replaces and game saves and are deleted with the creative.
• 422: video creative, asset_key on a non-game or missing on a game, a video/preview asset, unreadable image. 404: unknown asset key or not the owner.

Preview clip from an image

• POST /v1/creatives/{id}/preview-clip {seconds: 6|8|10 (default 8), motion: slow_zoom|pan_left| pan_right (default slow_zoom), name?} → 201 a NEW video creative (name default "<image name> (clip)", status pending, validation.made_from = {creative_id, op:"preview_clip", seconds, motion, at}). Silent H.264 yuv420p mp4, 30 fps, faststart, 1920x1080 for images wider than tall else 1080x1920; ffmpeg only ever reads a png our server rendered. The image creative is untouched.
• 422 {"reasons": ["Our server cannot render clips yet; our team can switch this on"]} when ffmpeg is missing or TRANSCODE_ENABLED=0; 422 for a non-image creative or a bad body.

People counting on the browser player (2026-10-26, branch feat/audience-counting)

The browser player can now count everyone who walks past, not only the faces that look. No change to play events or metrics; one additive heartbeat field.

• Play events (unchanged shape). In people mode audience.ots = distinct people seen during the play (counted once per person, see docs/AUDIENCE_MEASUREMENT.md), never less than watchers; watchers and attention_ms_total are the face-based counts as before (a watcher is a face detected for 1 s or more). So ots > watchers is normal for a people-mode screen. In faces mode (the fallback on a weak box) the player keeps reporting ots == watchers, and clients keep treating ots == watchers > 0 as "who passed was not measured". Camera off: all zeros, as before.
• Metrics (unchanged). has_audience_data = ots > 0 and attention_rate = watchers / ots on the campaign report, /v1/metrics/overview, /v1/metrics/screens/{id}, /v1/ops/metrics/screens/{id} and /v1/ops/metrics/network; a screen that starts sending people counts switches from sample numbers to real numbers with no server change.
• Heartbeat, additive and optional. POST /v1/device/heartbeat accepts vision: {mode: "people"|"faces", model: str ≤ 80, fps: 0..120, cpu: 0..100} while the camera is counting (camera: "counting"). cpu is the player's estimate of the percent of one CPU core spent on detection; fps is detection passes per second. It is stored with the rest of the health snapshot and shows up as health.vision on GET /v1/ops/devices. Other values for mode are refused with 422; older players simply do not send it.
• Player switches. /player?vision=people|faces|off sets the counting mode and saves it on the device (vision_mode in the player's local storage); ?vision=1 turns the camera on in the saved mode (people when none was saved), ?vision=0 turns it off. People mode falls back to faces by itself when the person model does not load and warm up within 10 s, or one detection pass takes longer than 1.5 s; the status overlay says which mode is running and why.
• The browser player now reports player_version = "web-1.1.0".

Sound on the wall (2026-10-26, branch feat/deck-sound)

• screens.sound_enabled (bool, default false, migration screen_sound_enabled). Malls often forbid audio, so game engines play sound cues only on screens where ops switched it on.
• PATCH /v1/ops/screens/{id} accepts sound_enabled; GET /v1/ops/screens and the PATCH response return it. The PATCH bumps schedule_version as before, so devices refetch.
• GET /v1/device/schedule → screen adds sound_enabled.
• Engine embed protocol (web/components/game-frame.tsx): gody:config carries sound (boolean); later changes arrive as {type:"gody:sound", on} (a second gody:config would reload the engine). Engines also honour ?sound=1. The web player passes sound_enabled && !muted (per-device mute on the StatusOverlay; ?sound=1|0 overrides for field tests). See docs/SOUND.md.

Mall partner, holiday hours, maintenance, partner API keys, mall branding (2026-10-26)

Migration mall_partner (mall_partner.py, down_revision screen_sound_enabled): users.venue_id, venues.revenue_share_bp (default 3000) + venues.brand (JSON), screens.special_hours (JSON) + maintenance / maintenance_reason / maintenance_since, tables mall_payouts and api_keys.

Mall partner role

• users.role gains mall. A mall user belongs to exactly one venue (users.venue_id) and signs in at the normal POST /v1/auth/login; user and GET /v1/me carry venue:{id, name} (null for other roles). The web sends mall users to /mall.
• A mall token is refused with 403 "Mall partner accounts can only open the mall pages." on everything except /v1/mall/*, /v1/me, /v1/api-keys, /v1/notifications, /v1/auth/*. Advertisers and ops get 403 on /v1/mall/*.
• Privacy: mall responses carry counts, brands, dates and the mall's share only. Never an advertiser's email, phone, team, gross invoice or rate. A campaign's "brand" is the game creative's config.brand, else the advertiser's business name.

Mall (read only, always scoped to the caller's venue; any other id → 404)

• GET /v1/mall/venue → {id, name, city, revenue_share_bp, brand:{name, accent, logo_url, display_name}}
• GET /v1/mall/overview?from&to → {venue, revenue_share_bp, from, to, totals:{plays, ots, watchers, attention_ms_avg, attention_rate|null, bookings, cricket_scans, cricket_innings, screens, online, share_booked_paise}, screens_total, screens_online, screens_maintenance, hours_booked_today, share_this_month_paise, share_unpaid_paise, upcoming:[{brand, start_date, end_date, screens, live}]}. Totals are the network totals limited to the venue, with revenue_booked replaced by share_booked_paise = round_half_up(revenue booked in range × 100 × share_bp / 10000).
• GET /v1/mall/screens → [{id, label, zone_name, orientation, device:"online"|"offline"|"unpaired", last_seen_at, status:"online"|"offline"|"unpaired"|"maintenance"|"closed", status_now, maintenance, today:{closed, open_time, close_time, open_min, close_min, special, note, spans:[{start_min, end_min, brand, all_day, booking_key}], hours_booked, now_playing (brand)|null, watchers_now|null}, special_hours[]}]. GET /v1/mall/screens/{id} → one card; 404 for a screen of another venue.
• GET /v1/mall/statement → {venue, revenue_share_bp, months:[{month:"YYYY-MM", booked_paise, share_bp, amount_due_paise, lines, status:"pending"|"paid", in_progress, paid_amount_paise|null, paid_at|null, reference|null}] (newest first, always includes the current month), totals:{booked_paise, due_paise, paid_paise}}.
• GET /v1/mall/statement/{YYYY-MM} → the month row plus venue and items:[{month, date, kind: "invoice"|"credit_note", invoice_number, brand, screens[], start_date, end_date, booked_paise}].

Statement maths (integer paise, half-up). Month = IST calendar month of the invoice's paid_at (credit notes: their issued_at). For every paid invoice of a booking with items on the venue's screens: booked = round_half_up(subtotal_paise × Σ(item.price on this venue) / booking.price_total). A credit note against a paid invoice counts negative, split the same way. Unpaid, void and bidding invoices never count. amount_due = round_half_up(Σ booked × share_bp / 10000) per month. Example: ₹2,000 on venue A + ₹666 on venue B, paid → A books 200000 paise, B 66600; a ₹100 credit → A −7502 (−7501.875 rounded half-up away from zero); at 30% A is due 57749. A month is paid once ops record a payout; the paid row keeps the amount actually paid (paid_amount_paise).

Ops: the venue's partner side

• GET /v1/ops/venues rows (and POST/PATCH responses) gain revenue_share_bp, brand:{name, accent, logo_url, display_name}, mall_users:[{id, email, created_at}].
• PATCH /v1/ops/venues/{id} takes revenue_share_bp (0–10000) and brand:{name?, accent?} (accent ^#[0-9a-fA-F]{6}$ or empty; 422 otherwise). DELETE /v1/ops/venues/{id} → 409 while it has mall contacts.
• POST /v1/ops/venues/{id}/mall-users {email} → 201 {user:{id, email, venue_id, created_at}, temporary_password, emailed}. The temporary password is returned ONCE and never emailed (the email, when a provider delivers, only says a login exists). 409 when the email has an account.
• DELETE /v1/ops/mall-users/{id} → 204: removes the login and revokes its API keys.
• GET /v1/ops/venues/{id}/statement and /statement/{YYYY-MM}: the mall's statement, for ops.
• POST /v1/ops/venues/{id}/payouts {month, reference?} → 201 the month row, now paid with paid_amount_paise = the amount due at that moment. 409 for the current or a future month, or a month already paid.
• POST /v1/ops/venues/{id}/logo multipart file (png/jpg, sniffed, ≤ the game asset limit) → the brand dict; DELETE /v1/ops/venues/{id}/logo removes it. Public GET /v1/venues/{id}/logo (404 when none).

Holiday hours and maintenance (ops, per screen)

• PATCH /v1/ops/screens/{id} takes special_hours:[{date, closed, open_time?, close_time?, note?}] (the full list replaces the stored one; past dates are dropped; one row per date; an open row needs both times with close after open, else 422 with a sentence), maintenance: bool and maintenance_reason (≤200). Ops screen dicts gain special_hours[] (times as "HH:MM"), maintenance, maintenance_reason, maintenance_since, status_now:{state, on_air, reason, message}, venue_id.
• A date that becomes closed (or gets shorter hours) notifies every business with a live booking on that screen that day, once per change: kind screen_closed, "Screen X is closed on 2 Nov, your plays will be made up." (href /campaigns/{booking_id}). Nothing is re-booked automatically yet; making up the plays is an ops job.
• POST /v1/bookings: an item whose dates include a closed day → 409 "X is closed on 2 Nov (Diwali). Pick dates around it or book another screen."; a windowed item outside a short day's hours → 409 "X is only open 12:00–18:00 on 2 Nov, …". All-day items on a short day are fine.
• GET /v1/screens/{id}/hours (and cricket-hours) gain closed_dates[] and special_days[{date, open_min, close_min}]; with a closed day in range every step is free:false with taken_by: "Closed on 2 Nov"; on a short day the steps outside its hours say "Short hours on 2 Nov".
• Device: POST /v1/device/heartbeat answers status:{state:"on_air"|"maintenance"|"closed", on_air, message} and maintenance: bool; GET /v1/device/schedule carries the same status and day:{closed, open_min, close_min, special}. Closed = a closed special day, or outside a special day's own hours (normal days are unchanged). The maintenance reason never reaches the device. Heartbeats accept showing: "ads"|"back_soon" (stored in the health snapshot).
• Player: while not on air it shows a calm "Back soon" card with the Freebee wordmark and the message, treats every slot as idle (no play record is written behind the card) and reports showing:"back_soon". Ops Today lists screens in maintenance in the alerts strip.

Partner API keys

• api_keys: id, name, scope (venue | business | network), owner_user_id, venue_id, business_id, key_hash (SHA-256, unique), prefix (first 12 chars), created_at, last_used_at, revoked_at. A key is fbk_ + 40 url-safe characters; the full key is in the create response only.
• GET /v1/api-keys → [{id, name, scope, prefix, venue_id, venue_name, created_at, last_used_at, revoked_at}] (ops: all; mall: its venue's; advertiser: its business's).
• POST /v1/api-keys {name, venue_id?} → 201 the row plus key. Ops: venue_id → venue key, none → network key. Mall owners → a key for their venue. Advertiser owners → a business key. Editors and viewers → 403 "Only an owner can create or revoke API keys." At most 10 live keys per venue or business (409).
• DELETE /v1/api-keys/{id} → 200 the row with revoked_at (idempotent); 404 for a key you cannot see. A revoked key answers 401 from the next request.
• Auth for /v1/partner/*: header X-API-Key. 401 missing / unknown / revoked; 429 with Retry-After past PARTNER_API_MAX_PER_MIN (60) requests per key per minute; 403 when the key's scope does not fit the endpoint. last_used_at updates at most once a minute.

GET /v1/partner/screens (venue or network key) → [{id, label, zone_name, orientation, venue_id, status, device, last_seen_at, maintenance, today:{closed, open_time, close_time, special, hours_booked}}]

curl -s https://api.example/v1/partner/screens -H "X-API-Key: fbk_…"

GET /v1/partner/metrics?from=YYYY-MM-DD&to=YYYY-MM-DD (venue key → {scope:"venue", venue_id, from, to, totals (as mall overview, with share_booked_paise), screens_total, screens_online, hours_booked_today, revenue_share_bp}; network key → {scope:"network", from, to, totals})

curl -s "https://api.example/v1/partner/metrics?from=2026-10-01&to=2026-10-31" -H "X-API-Key: fbk_…"

GET /v1/partner/proof/{booking_id}?format=json|csv (business key: the business's own bookings only, 404 otherwise; network key: any) → the same signed proof-of-play file as GET /v1/bookings/{id}/proof.

curl -s "https://api.example/v1/partner/proof/7f3c…?format=csv" -H "X-API-Key: fbk_…" -o proof.csv

Mall branding on the shopper pages

• venues.brand = {name?, accent?, logo?}. GET /v1/play/{screen}, GET /v1/kiosk/{screen} and GET /v1/wallet/claim/{token} carry venue_brand: {name, logo_url, accent} | null (null until ops set a name, logo or accent; name falls back to the venue name). The kiosk, phone join page and claim page show "At <name>" with the logo; Freebee's own wordmark stays.

Env: PARTNER_API_MAX_PER_MIN (60), MALL_DEFAULT_REVENUE_SHARE_BP (3000). Seed: mall@dooh.local / malldev123 tied to the seeded venue.