Lucra Sports Tournaments (Legacy) API

Drop-in replacement endpoints for the original tournament API operations.Request/response shapes are identical.---## Tournament Types### CASH_FIXEDThe total prize pool is defined upfront and has no relation to the amount collected from buy-ins.- Reward amounts are fixed regardless of how many participants join- The tenant bears the financial risk — if insufficient participants join, the tenant may pay out more in prizes than collected in entry fees- Prize values in `paymentStructure` represent absolute monetary amounts### CASH_PERCENTAGEThe prize pool is calculated from the total amount collected from entry fees, distributed according to percentage allocations.- The `value` in `paymentStructure` represents a percentage (e.g., 60 for 60%)- **The sum of all percentage values must equal exactly 100**- Actual payout amounts are calculated after fees are deducted from the collected pool**Payout Calculation:**```Pool Net Amount = MAX((Total Collected - Fee%), Min Payout Amount)Prize Amount = Pool Net Amount × (Tier Percentage ÷ 100)```---## Replayable TournamentsReplayable tournaments allow participants to join the same tournament multiple times, submitting new scores in an attempt to improve their standing. Each time a user rejoins, they pay the buy-in amount again (if applicable) and start a new attempt.| Attribute | Type | Default | Description ||-----------|------|---------|-------------|| `maxAttempts` | number | 1 | Maximum number of times a user can join/rebuy || `attemptFinished` | boolean | false | When submitting scores, marks the attempt as completed || `omitAttemptCompletedCheck` | boolean | false | If true, allows rebuys even when the current attempt is not finished |**How It Works:**1. **Initial Entry** — Users join by paying the buy-in amount (first attempt)2. **Submitting Scores** — While an attempt is active, users can submit/update scores. Set `attemptFinished: true` to lock the attempt3. **Rebuying** — Users can rejoin if they haven't reached `maxAttempts` and their current attempt is finished (unless `omitAttemptCompletedCheck: true`)4. **Leaderboard** — The user's best score across all attempts determines their final positionUse the `canSubmitNewScore` field in the leaderboard response to check if a user can submit scores or needs to rebuy.---## Position and Ranking| Field | Type | Description ||-------|------|-------------|| `position` | number | Automatically calculated rank based on scores (1, 2, 3, …) || `positionOverride` | number | Optional manual position that overrides automatic ranking for reward distribution |**Automatic Position** is calculated based on scores and `scoringType` (`HIGHEST_SCORE` or `LOWEST_SCORE`). Always unique — no ties.**Position Override** uses rank-based logic that handles ties (1, 2, 2, 4, …). Can also be manually set during tournament completion. Returns `null` when it equals `position`.When completing without specifying winners (auto-complete), the system:1. Sorts users by score according to `scoringType`2. Calculates `position` using sequential numbering (1, 2, 3, …)3. Calculates override position handling ties (1, 2, 2, 4, …)4. Sets `positionOverride` to non-null only when it differs from `position`5. Distributes rewards based on final positions**Best Practice:** Always use `positionOverride ?? position` to display a user's final ranking.---## Scoring Types- **HIGHEST_SCORE** — Higher scores rank better (e.g., points-based games)- **LOWEST_SCORE** — Lower scores rank better (e.g., golf, racing)---## Sign-Up WindowTournaments can optionally define a sign-up window using `signUpStart` and `signUpEnd`.When set, participants can only join during this window. If omitted, sign-ups follow thedefault behavior (open from creation until the tournament expires).| Constraint | Rule ||-----------|------|| `signUpEnd` ≤ `expiresAt` | Sign-ups must close before tournament expiration || `signUpStart` < `signUpEnd` | Window must have a positive duration |---## Tournament Lifecycle```OPEN → CONFIRMED → CLOSED ↓ ↓ CANCELED ← ←```