Lucra Sports Tournaments (Legacy) API

Drop-in replacement endpoints for the original tournament API operations. Request/response shapes are identical. --- ## Tournament Types ### CASH_FIXED The 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_PERCENTAGE The 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 Tournaments Replayable 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 attempt 3. **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 position Use 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 Window Tournaments 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 the default 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 ← ← ```