be-components 7.4.7 → 7.5.1

package/lib/module/BetRouter/types/MARKET_LINKING_WORKFLOW.md

@@ -0,0 +1,682 @@
+# Market Linking Workflow - Admin Portal Guide
+
+This guide explains how to manage markets at the contest level using the **two-step approach**:
+
+1. **Set Supported Markets** - Define which router markets are available for a contest (market_contests)
+2. **Link Raw Markets** - For each supported market, link raw markets from partners
+
+---
+
+## 🎯 Workflow Overview
+
+```
+Contest Detail Page
+    ↓
+1. View/Manage Supported Markets (market_contests)
+    ↓
+2. For each supported market:
+   - View which partners have raw markets linked
+   - Load available raw markets from partner
+   - Link raw markets to the supported market
+```
+
+---
+
+## 📋 Step 1: Manage Supported Markets
+
+**What are "Supported Markets"?**
+
+Supported markets (stored in `market_contests` table) define which **types of markets** are available for betting on a specific contest.
+
+**Example:**
+- Contest: "Lakers vs Celtics"
+- Supported Markets:
+  - ✅ Moneyline (router_market_id: "rm-moneyline")
+  - ✅ Spread (router_market_id: "rm-spread")
+  - ❌ Player Points (not supported for this contest)
+
+### a) Get Supported Markets
+
+**Endpoint:** `GET /markets/supported/:router_contest_id`
+
+```bash
+GET /markets/supported/contest-123
+```
+
+**Response:**
+```json
+{
+  "message": "Successfully fetched supported markets",
+  "market_contests": [
+    {
+      "market_contest_id": "mc-1",
+      "router_contest_id": "contest-123",
+      "router_market_id": "rm-moneyline",
+      "status": "open"
+    },
+    {
+      "market_contest_id": "mc-2",
+      "router_contest_id": "contest-123",
+      "router_market_id": "rm-spread",
+      "status": "open"
+    }
+  ],
+  "router_markets": [
+    {
+      "router_market_id": "rm-moneyline",
+      "market_key": "moneyline",
+      "market_label": "Moneyline",
+      "category": "game_result",
+      "variable_required": false
+    },
+    {
+      "router_market_id": "rm-spread",
+      "market_key": "spread",
+      "market_label": "Spread",
+      "category": "game_result",
+      "variable_required": true
+    }
+  ]
+}
+```
+
+### b) Add a Supported Market
+
+**Endpoint:** `POST /markets/supported`
+
+```bash
+POST /markets/supported
+Content-Type: application/json
+
+{
+  "router_contest_id": "contest-123",
+  "router_market_id": "rm-player-points"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Successfully added supported market",
+  "market_contest": {
+    "market_contest_id": "mc-3",
+    "router_contest_id": "contest-123",
+    "router_market_id": "rm-player-points",
+    "status": "open"
+  }
+}
+```
+
+### c) Remove a Supported Market
+
+**Endpoint:** `DELETE /markets/supported/:market_contest_id`
+
+```bash
+DELETE /markets/supported/mc-3
+```
+
+**Response:**
+```json
+{
+  "message": "Successfully removed supported market"
+}
+```
+
+---
+
+## 📋 Step 2: Link Raw Markets to Supported Markets
+
+Once you have defined which markets are supported for a contest, you can link raw markets from partners.
+
+### a) Get Available Raw Markets for a Specific Market
+
+**Endpoint:** `GET /markets/:router_contest_id/:router_market_id/available-raw/:partner_id`
+
+```bash
+GET /markets/contest-123/rm-moneyline/available-raw/bettoredge-partner-id
+```
+
+**What it does:**
+- Loads raw markets from BettorEdge for this contest
+- Filters to show only moneyline markets
+- Excludes already-linked raw markets
+- Shows what's already linked separately
+
+**Response:**
+```json
+{
+  "message": "Successfully fetched available raw markets",
+  "router_contest": {
+    "router_contest_id": "contest-123",
+    "contest_label": "Lakers vs Celtics"
+  },
+  "router_market": {
+    "router_market_id": "rm-moneyline",
+    "market_label": "Moneyline",
+    "market_key": "moneyline"
+  },
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-moneyline-1",
+      "partner_id": "bettoredge-partner-id",
+      "partner_contest_id": "pc-be-1",
+      "external_id": "2",
+      "pretty_title": "Winner",
+      "status": "active"
+    }
+  ],
+  "already_linked": []
+}
+```
+
+### b) Get Data for Linking Form
+
+**NEW Endpoint:** `GET /markets/:router_contest_id/:router_market_id/linking-data/:partner_id`
+
+This endpoint provides all the data needed to build the linking form in your admin UI.
+
+**Why this endpoint?**
+It returns enriched participant data with human-readable names, so the admin can select "Los Angeles Lakers" instead of seeing just an ID like "pp-lakers-123".
+
+```bash
+GET /markets/contest-123/rm-moneyline/linking-data/bettoredge-partner-id
+```
+
+**Response:**
+```json
+{
+  "router_contest": { ... },
+  "router_market": {
+    "router_market_id": "rm-moneyline",
+    "market_label": "Moneyline",
+    "variable_required": false,
+    "participant_type": "team"
+  },
+  "market_sides": [
+    {
+      "market_side_id": "side-home",
+      "side_key": "home",
+      "side_type": "team"
+    },
+    {
+      "market_side_id": "side-away",
+      "side_key": "away",
+      "side_type": "team"
+    }
+  ],
+  "timeframes": [
+    {
+      "timeframe_id": "tf-full",
+      "timeframe_key": "full_event",
+      "timeframe_label": "Full Game"
+    }
+  ],
+  "participants": [
+    {
+      "partner_participant_id": "pp-lakers-123",
+      "router_participant_id": "rp-lakers",
+      "name": "Los Angeles Lakers",
+      "participant_type": "team",
+      "external_id": "lakers-team-id",
+      "raw_name": "LA Lakers",
+      "tags": ["Los Angeles Lakers", "Lakers", "LAL"]
+    },
+    {
+      "partner_participant_id": "pp-celtics-456",
+      "router_participant_id": "rp-celtics",
+      "name": "Boston Celtics",
+      "participant_type": "team",
+      "external_id": "celtics-team-id",
+      "raw_name": "Boston Celtics",
+      "tags": ["Boston Celtics", "Celtics", "BOS"]
+    }
+  ],
+  "variables": [
+    {
+      "router_market_variable_id": "var-0",
+      "variable": 0,
+      "variable_type": "total"
+    }
+  ]
+}
+```
+
+**IMPORTANT: Variable Field UI Guidance**
+
+The `variables` array shows **previously used variable values** for this market. This is useful for:
+- Showing suggestions/autocomplete
+- Letting admins reuse common values
+
+However, **the variable field must accept manual numeric input**, not just dropdown selection. Here's why:
+
+1. **New markets have few/no existing variables** - A brand new Spread market might have 0 or 1 variable in the database
+2. **Raw markets have specific values** - The raw market from BettorEdge might have spread value `-3.5`, but that won't exist in the database yet
+3. **Variables are created dynamically** - When you link a market with a new variable value, it's automatically created
+
+**Recommended UI Pattern:**
+```
+Variable: [_____-3.5_____] (number input - allows negative values)
+          Previously used: 0, -7.0, +3.5 (clickable suggestions)
+
+Variable Type: [spread ▼] (dropdown)
+```
+
+**🎯 SIMPLIFIED: Spread Variables - Enter Once, Link Both Sides**
+
+For **spread markets**, the UI now simplifies variable entry:
+
+**How it works:**
+1. Admin enters the spread value **once** (e.g., `7` or `3.5`)
+2. Client automatically determines:
+   - **Home side (favorite):** Gets negative value `-7` or `-3.5`
+   - **Away side (underdog):** Gets positive value `+7` or `+3.5`
+3. Single "Link Both Sides" button creates both links at once
+
+**Example Spread Linking Workflow:**
+```
+User enters: 7
+
+Client creates:
+1. Home side: variable = -7, participant = Lakers
+2. Away side: variable = +7, participant = Celtics
+
+Backend stores two separate router_market_variable records:
+{ variable: -7, variable_type: 'spread' }    // For Lakers (home)
+{ variable: 7, variable_type: 'spread' }     // For Celtics (away)
+```
+
+**For Total markets:**
+- User enters the total once (e.g., `220.5`)
+- Both over/under sides use the same variable value
+- System creates one variable record, both sides link to it
+
+**Why This Matters:**
+- ✅ User enters variable value only once
+- ✅ No flip logic needed in backend - variables store actual signs
+- ✅ Variables match what partners display
+- ✅ Titles render correctly: "Lakers -7 Full Game", "Celtics +7 Full Game"
+- ✅ Simpler UX and cleaner code throughout system
+
+**Key Features of Enriched Participant Data:**
+- `name` - **Canonical name** from router_participant (e.g., "Los Angeles Lakers") - Use this for the dropdown label
+- `partner_participant_id` - The ID you need to submit in the link request
+- `raw_name` - What the partner calls them (e.g., "LA Lakers") - Optional: show in parentheses for context
+- `participant_type` - Already filtered to match `router_market.participant_type` (team/athlete/event)
+- `tags` - Name variations for search/autocomplete
+
+**Participant Filtering:**
+The participants array is automatically filtered to:
+1. Only include participants from the selected partner
+2. Only include participants matching the market's `participant_type`
+   - Moneyline/Spread → `participant_type: "team"`
+   - Player Props → `participant_type: "athlete"`
+   - Game Totals → `participant_type: "event"`
+
+### c) Link Raw Market to Router Market
+
+**Endpoint:** `POST /markets/link`
+
+```bash
+POST /markets/link
+Content-Type: application/json
+
+{
+  "raw_market_id": "raw-be-moneyline-1",
+  "router_market_id": "rm-moneyline",
+  "market_side_id": "side-home",
+  "partner_participant_id": "pp-lakers-123",
+  "timeframe_id": "tf-full",
+  "variable": 0,
+  "variable_type": "total",
+  "price_key": null
+}
+```
+
+**Required Parameters:**
+- `raw_market_id` - The raw market from the partner
+- `router_market_id` - The router market (moneyline, spread, etc.)
+- `market_side_id` - Which side (home, away, over, under) - **selected by admin from market_sides**
+- `partner_participant_id` - Which participant (team/athlete) - **selected by admin filtered by side_type**
+- `timeframe_id` - Full game, 1st half, etc. - **selected by admin from timeframes**
+- `variable` - The line/spread/total value - **entered/selected by admin if variable_required**
+- `variable_type` - 'spread' or 'total' - **selected by admin if variable_required**
+
+**Optional Parameters:**
+- `price_key` - For Kalshi markets: 'yes' or 'no'
+
+**Response:**
+```json
+{
+  "message": "Market linked successfully",
+  "partnerMarket": {
+    "partner_market_id": "pm-123",
+    "raw_market_id": "raw-be-moneyline-1",
+    "router_market_id": "rm-moneyline",
+    "market_side_id": "side-home",
+    "router_market_variable_id": "var-0",
+    "partner_id": "bettoredge-partner-id",
+    "external_id": "2"
+  }
+}
+```
+
+---
+
+## 🎨 Recommended UI Layout
+
+### Contest Detail Page - Markets Tab
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Lakers vs Celtics - Markets                                │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Supported Markets                                      │ │
+│  │                                                        │ │
+│  │ Available Router Markets:                             │ │
+│  │ [+ Add Market ▼]  (dropdown of all router markets)   │ │
+│  │                                                        │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │                                                        │ │
+│  │ ✅ Moneyline                     [Remove]            │ │
+│  │    BettorEdge: ✅ Linked (2 sides)                   │ │
+│  │    Kalshi:     ❌ Not Linked  [Link Markets]         │ │
+│  │    BetOpenly:  ✅ Linked (2 sides)                   │ │
+│  │                                                        │ │
+│  │ ✅ Spread                        [Remove]            │ │
+│  │    BettorEdge: ✅ Linked (4 sides)                   │ │
+│  │    Kalshi:     ❌ Not Linked  [Link Markets]         │ │
+│  │    BetOpenly:  ❌ Not Linked  [Link Markets]         │ │
+│  │                                                        │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### When "Link Markets" is Clicked (BettorEdge - Moneyline)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Link BettorEdge Markets: Moneyline                         │
+│                                                              │
+│  Step 1: Select Raw Market                                  │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ ○ Winner (external_id: 2)                             │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  Step 2: Link Each Side                                     │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Home Side                                              │ │
+│  │                                                        │ │
+│  │ Side:         [Home ▼]                                │ │
+│  │               • from market_sides                     │ │
+│  │                                                        │ │
+│  │ Participant:  [Los Angeles Lakers (LA Lakers) ▼]     │ │
+│  │               • Shows canonical name (raw_name)       │ │
+│  │               • Filtered to participant_type: team    │ │
+│  │               • Submits partner_participant_id        │ │
+│  │                                                        │ │
+│  │ Timeframe:    [Full Game ▼]                           │ │
+│  │ Variable:     0 (not required for moneyline)          │ │
+│  │ Variable Type: [total ▼]                              │ │
+│  │ Price Key:    (empty - only for Kalshi)               │ │
+│  │                                                        │ │
+│  │ [Link Home Side]                                      │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Away Side                                              │ │
+│  │                                                        │ │
+│  │ Side:         [Away ▼]                                 │ │
+│  │ Participant:  [Celtics ▼]                             │ │
+│  │ Timeframe:    [Full Game ▼]                           │ │
+│  │ Variable:     0                                       │ │
+│  │ Variable Type: [total ▼]                              │ │
+│  │                                                        │ │
+│  │ [Link Away Side]                                      │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Done]  [Cancel]                                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Complete Market Linking Flow
+
+```
+1. Admin opens "Lakers vs Celtics" contest
+   ↓
+2. Admin clicks "Markets" tab
+   ↓
+3. Page shows supported markets (via GET /markets/supported/:router_contest_id)
+   - Moneyline (2/3 partners linked)
+   - Spread (1/3 partners linked)
+   ↓
+4. Admin wants to link BettorEdge moneyline
+   ↓
+5. Admin clicks "Link Markets" for BettorEdge under Moneyline
+   ↓
+6. System calls TWO endpoints:
+   a) GET /markets/:router_contest_id/rm-moneyline/available-raw/:bettoredge_partner_id
+      → Returns raw_markets (available to link)
+   b) GET /markets/:router_contest_id/rm-moneyline/linking-data/:bettoredge_partner_id
+      → Returns market_sides, participants, timeframes, variables
+   ↓
+7. Modal shows:
+   - Raw markets to choose from
+   - Form for each side with dropdowns populated from linking-data
+   ↓
+8. Admin selects raw market: "Winner (external_id: 2)"
+   ↓
+9. Admin fills Home side form:
+   - Side: Home (from market_sides)
+   - Participant: Lakers (filtered by side_type: team)
+   - Timeframe: Full Game
+   - Variable: 0
+   - Variable Type: total
+   ↓
+10. Admin clicks "Link Home Side"
+    ↓
+11. System calls: POST /markets/link
+    {
+      "raw_market_id": "raw-be-moneyline",
+      "router_market_id": "rm-moneyline",
+      "market_side_id": "side-home",
+      "partner_participant_id": "pp-lakers-123",
+      "timeframe_id": "tf-full",
+      "variable": 0,
+      "variable_type": "total"
+    }
+    ↓
+12. Admin fills Away side form and links
+    ↓
+13. Success! BettorEdge moneyline now shows ✅ Linked (2 sides)
+```
+
+---
+
+## 📋 API Endpoint Summary
+
+### Managing Supported Markets (market_contests)
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/markets/supported/:router_contest_id` | Get supported markets for a contest |
+| POST | `/markets/supported` | Add a router market as supported for a contest |
+| DELETE | `/markets/supported/:market_contest_id` | Remove a supported market |
+
+### Linking Raw Markets
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/markets/:router_contest_id/:router_market_id/linking-data/:partner_id` | **NEW** Get form data (sides, participants, timeframes, variables) |
+| GET | `/markets/:router_contest_id/:router_market_id/available-raw/:partner_id` | Get available raw markets to link for a specific market + partner |
+| POST | `/markets/link` | Link a raw market to router market (requires: side, participant, timeframe, variable) |
+
+### Reference Data
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/markets/router` | Get all router markets |
+| GET | `/markets/sides` | Get all market sides |
+| GET | `/markets/variables` | Get all market variables |
+
+---
+
+## 💡 Key Concepts
+
+### Market Hierarchy
+
+```
+Router Market (Template)
+  ↓ has
+Market Sides (home, away, over, under)
+  ↓ with
+Market Variables (spreads, totals)
+  ↓ links to
+Raw Markets (partner-specific, contest-specific)
+  ↓ creates
+Partner Markets (the actual linkage)
+```
+
+### Example: Spread Market
+
+**Router Market:** "Spread" (market_key: "spread")
+
+**Market Sides:**
+- Home
+- Away
+
+**Market Variables:**
+- -3.5 (spread)
+- -7.0 (spread)
+- +2.5 (spread)
+
+**Raw Market from BettorEdge:**
+- external_id: "1"
+- pretty_title: "Spread"
+- partner_contest_id: "pc-be-1"
+
+**Partner Markets (4 total):**
+1. Home -3.5 → raw_market_id + router_market_id + side_home + variable_-3.5
+2. Away +3.5 → raw_market_id + router_market_id + side_away + variable_+3.5
+3. Home -7.0 → raw_market_id + router_market_id + side_home + variable_-7.0
+4. Away +7.0 → raw_market_id + router_market_id + side_away + variable_+7.0
+
+### Variable Types
+
+- **spread**: Handicap betting (e.g., -3.5 points)
+- **total**: Over/under betting (e.g., 215.5 total points)
+
+For moneyline markets, use `variable: 0` and `variable_type: 'total'`
+
+### Price Key (Kalshi Only)
+
+Kalshi markets are binary (yes/no). Use `price_key` to specify which:
+- `"yes"` - For one side (usually home or over)
+- `"no"` - For the other side (usually away or under)
+
+---
+
+## 🚀 Implementation Steps
+
+### Phase 1: View Supported Markets
+1. Show list of router markets supported for a contest
+2. Display which partners have markets linked for each supported market
+3. Show counts (e.g., "2/3 partners linked")
+
+### Phase 2: Add/Remove Supported Markets
+1. Dropdown to add router markets as supported
+2. Button to remove supported markets
+3. Validation (can't remove if partner markets exist)
+
+### Phase 3: Link Raw Markets
+1. "Link Markets" button for each partner under each supported market
+2. Modal/panel to select raw market and configure sides
+3. Form for each side with:
+   - Side dropdown (from router_market_sides)
+   - Variable input (if variable_required)
+   - Variable type dropdown
+   - Price key (if Kalshi)
+4. Submit to create partner_market
+
+### Phase 4: Bulk Linking
+1. Auto-detect matching markets by external_id patterns
+2. Bulk link all sides at once
+3. Smart defaults for common markets (moneyline, spread)
+
+---
+
+## ✅ Complete Example Workflow
+
+**Goal:** Link BettorEdge Moneyline market to "Lakers vs Celtics"
+
+```javascript
+// 1. Get supported markets
+const supportedRes = await fetch('/markets/supported/contest-123');
+const { market_contests, router_markets } = await supportedRes.json();
+// Shows: Moneyline is supported (market_contest exists)
+
+// 2. Get available raw markets for BettorEdge + Moneyline
+const availableRes = await fetch(
+  '/markets/contest-123/rm-moneyline/available-raw/bettoredge-partner-id'
+);
+const { raw_markets } = await availableRes.json();
+// Returns: raw_market with external_id: "2" (BettorEdge Winner market)
+
+// 3. Get linking form data (sides, participants, timeframes, variables)
+const formDataRes = await fetch(
+  '/markets/contest-123/rm-moneyline/linking-data/bettoredge-partner-id'
+);
+const { market_sides, participants, timeframes, router_market } = await formDataRes.json();
+
+// 4. Build participant dropdown (showing human-readable names)
+const participantOptions = participants.map(p => ({
+  value: p.partner_participant_id,  // Submit this ID
+  label: `${p.name}${p.raw_name ? ` (${p.raw_name})` : ''}`,  // Display canonical + partner name
+  // e.g., "Los Angeles Lakers (LA Lakers)"
+}));
+
+// 5. Admin selects:
+// - Raw market: raw_markets[0] (Winner)
+// - Side: 'side-home' (from market_sides)
+// - Participant: 'pp-lakers-123' (from participants dropdown)
+// - Timeframe: 'tf-full' (from timeframes)
+
+// 6. Link home side
+await fetch('/markets/link', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    raw_market_id: raw_markets[0].raw_market_id,
+    router_market_id: 'rm-moneyline',
+    market_side_id: 'side-home',
+    partner_participant_id: 'pp-lakers-123',  // Selected from dropdown
+    timeframe_id: 'tf-full',  // Selected from dropdown
+    variable: 0,
+    variable_type: 'total'
+  })
+});
+
+// 7. Link away side (with Celtics)
+await fetch('/markets/link', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    raw_market_id: raw_markets[0].raw_market_id,
+    router_market_id: 'rm-moneyline',
+    market_side_id: 'side-away',
+    partner_participant_id: 'pp-celtics-456',  // Selected from dropdown
+    timeframe_id: 'tf-full',
+    variable: 0,
+    variable_type: 'total'
+  })
+});
+
+// Done! BettorEdge Moneyline is now linked for this contest
+```
+
+---
+
+This two-step approach keeps the market management organized and scalable!