be-components 7.4.7 → 7.5.1

package/src/BetRouter/types/MARKET_LINKING_WORKFLOW_V2.md

@@ -0,0 +1,627 @@
+# Market Linking Workflow - Complete Guide
+
+This guide explains the **complete workflow** for linking markets in the admin portal, including all the decision points and simplified flows.
+
+---
+
+## 🎯 Core Concepts
+
+### Markets Flow: Contest → Router Market → Partner Markets
+
+```
+Router Contest (Lakers vs Celtics)
+    ↓
+Router Market (Spread)
+    ↓
+Partner Markets (BettorEdge Spread, Kalshi Spread, etc.)
+    ↓
+Variables (-7, -3.5, -10, etc.)
+```
+
+---
+
+## 📋 Complete Workflow Decision Tree
+
+```
+1. Is this market supported for the contest?
+   NO  → Add to supported markets first
+   YES → Continue
+
+2. Does this partner have ANY raw markets linked for this market type?
+   NO  → [Link Market - Full Flow]
+   YES → Continue
+
+3. Does this market require variables? (variable_required = true)
+   NO  → Done (market already linked)
+   YES → Continue
+
+4. Do you want to add a new variable?
+   NO  → Done
+   YES → [Add Variable - Simplified Flow]
+```
+
+---
+
+## 🔧 Flow 1: Link Market (Full Flow)
+
+**When to use:** First time linking a market type for a partner
+
+### Important: Check Partner Requirements First
+
+Before showing the linking UI, check if the partner requires a `price_key`:
+
+```javascript
+// Get partner info from GET /partners
+const partner = partners.find(p => p.partner_id === selectedPartnerId);
+
+// Check if price_key is required
+if (partner.options?.price_key_required) {
+  // Show dropdown with options: partner.options.price_key_options
+  // Example: ["yes", "no"] for Kalshi
+  showPriceKeyDropdown = true;
+  priceKeyOptions = partner.options.price_key_options;
+}
+```
+
+**Partner Requirements:**
+- **BettorEdge**: No price_key required
+- **Kalshi**: price_key REQUIRED (options: "yes", "no")
+- **BetOpenly**: No price_key required
+
+### Step 1: Get Linking Data
+
+**Endpoint:** `GET /markets/:router_contest_id/:router_market_id/linking-data/:partner_id`
+
+**Example:**
+```bash
+GET /markets/contest-123/rm-spread/linking-data/bettoredge-id
+```
+
+**Response:**
+```json
+{
+  "router_contest": {
+    "router_contest_id": "contest-123",
+    "contest_label": "Lakers vs Celtics"
+  },
+  "router_market": {
+    "router_market_id": "rm-spread",
+    "market_label": "Spread",
+    "variable_required": true,
+    "default_variable_type": "spread"
+  },
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-spread-1",
+      "external_id": "2000003|1",
+      "pretty_title": "Spread"
+    }
+  ],
+  "participants": [
+    {
+      "partner_participant_id": "pp-lakers-1",
+      "name": "Los Angeles Lakers",
+      "participant_type": "team"
+    },
+    {
+      "partner_participant_id": "pp-celtics-1",
+      "name": "Boston Celtics",
+      "participant_type": "team"
+    }
+  ],
+  "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-game",
+      "timeframe_label": "Full Game"
+    }
+  ],
+  "variables": []  // Empty on first link
+}
+```
+
+### Step 2: User Input
+
+**For Spread Market:**
+```
+┌─────────────────────────────────────────────┐
+│ Link Spread Market - BettorEdge            │
+├─────────────────────────────────────────────┤
+│                                             │
+│ Raw Market: [Spread (2000003|1) ▼]         │
+│                                             │
+│ Variable: [7]  ← User enters (home/under)  │
+│                                             │
+│ Home Side:                                  │
+│   Participant: [Lakers ▼]                   │
+│   Timeframe: [Full Game ▼]                  │
+│   Price Key: [LAL] (optional)               │
+│                                             │
+│ Away Side:                                  │
+│   Participant: [Celtics ▼]                  │
+│   Timeframe: [Full Game ▼]                  │
+│   Price Key: [BOS] (optional)               │
+│                                             │
+│ [Link Both Sides]                           │
+└─────────────────────────────────────────────┘
+```
+
+### Step 3: Client Processing
+
+**Client automatically:**
+1. Takes user input: `7`
+2. Creates home side: variable = `+7` (positive)
+3. Creates away side: variable = `-7` (negative)
+4. Makes 2 API calls to link both sides
+
+### Step 4: API Calls
+
+**Call 1 - Home Side:**
+```json
+POST /markets/link
+{
+  "raw_market_id": "raw-be-spread-1",
+  "router_market_id": "rm-spread",
+  "market_side_id": "side-home",
+  "partner_participant_id": "pp-lakers-1",
+  "timeframe_id": "tf-full-game",
+  "variable": 7,
+  "variable_type": "spread",
+  "price_key": "LAL"
+}
+```
+
+**Call 2 - Away Side:**
+```json
+POST /markets/link
+{
+  "raw_market_id": "raw-be-spread-1",
+  "router_market_id": "rm-spread",
+  "market_side_id": "side-away",
+  "partner_participant_id": "pp-celtics-1",
+  "timeframe_id": "tf-full-game",
+  "variable": -7,
+  "variable_type": "spread",
+  "price_key": "BOS"
+}
+```
+
+---
+
+## 🚀 Flow 2: Add Variable (Simplified Flow)
+
+**When to use:** Market is already linked, you just want to add another variable (e.g., add -10 when -7 already exists)
+
+> **🚨 CRITICAL REQUIREMENT:**
+>
+> The "Add Variable" modal MUST include:
+> 1. ✅ Variable number input field
+> 2. ✅ **Raw market dropdown selector** (ALWAYS visible, not conditional)
+>
+> The raw market dropdown:
+> - Shows ALL raw markets from the API response
+> - Defaults to the raw market currently used by existing variables
+> - Allows user to select any raw market
+> - Selected raw_market_id MUST be included in the API request
+
+### Step 1: View Existing Variables
+
+**Endpoint:** `GET /markets/:router_contest_id/:router_market_id/variables-and-raw/:partner_id`
+
+```bash
+GET /markets/contest-123/rm-spread/variables-and-raw/bettoredge-id
+```
+
+**Response:**
+```json
+{
+  "router_market": {
+    "router_market_id": "rm-spread",
+    "market_label": "Spread",
+    "variable_required": true,
+    "default_variable_type": "spread"
+  },
+  "existing_variables": [
+    {
+      "router_market_variable_id": "var-1",
+      "variable": -7,
+      "linked_count": 2
+    },
+    {
+      "router_market_variable_id": "var-2",
+      "variable": 7,
+      "linked_count": 2
+    }
+  ],
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-spread-1",
+      "external_id": "2000003|1",
+      "pretty_title": "Spread"
+    },
+    {
+      "raw_market_id": "raw-be-spread-2",
+      "external_id": "2000003|2",
+      "pretty_title": "Alternate Spread"
+    }
+  ]
+}
+```
+
+### Step 2: User Input (REQUIRED UI ELEMENTS)
+
+**CRITICAL: The client MUST display ALL available raw markets in a dropdown/selector.**
+
+```
+┌─────────────────────────────────────────────┐
+│ Add Variable to Spread                      │
+├─────────────────────────────────────────────┤
+│                                             │
+│ Existing Variables:                         │
+│   • -7 / +7  ✓                             │
+│                                             │
+│ New Variable: [10]  ← Enter number only    │
+│                                             │
+│ Raw Market: [Dropdown ▼]                   │
+│   • Spread (2000003|1)         ← selected  │
+│   • Alternate Spread (2000003|2)           │
+│   • Spread -3 (2000003|3)                  │
+│                                             │
+│ Note: Default selection is the raw market  │
+│ currently used by existing variables.      │
+│                                             │
+│ [Add Variable]                              │
+└─────────────────────────────────────────────┘
+```
+
+**Requirements:**
+- ✅ MUST show dropdown with ALL raw markets from API response
+- ✅ MUST default to the raw_market_id currently used by existing variables
+- ✅ MUST allow user to select any raw market from the list
+- ✅ MUST send selected raw_market_id in API request
+
+### Step 3: Client Processing
+
+**ALWAYS include the selected `raw_market_id` in the request.**
+
+```json
+POST /markets/add-variable
+{
+  "router_contest_id": "contest-123",
+  "router_market_id": "rm-spread",
+  "partner_id": "bettoredge-id",
+  "variable": 10,
+  "raw_market_id": "raw-be-spread-1"  // ← ALWAYS include the selected raw_market_id
+}
+```
+
+**How to determine which raw_market_id to use as default:**
+1. Get existing variables from the API response
+2. Look up the first existing variable's partner markets
+3. Get the `raw_market_id` from one of those partner markets
+4. Use that as the default selection in the dropdown
+5. User can change to any other raw market in the list
+
+**What happens on backend:**
+- Backend finds existing partner_markets as template for side structure
+- Creates new partner_markets with variable `+10` for home, `-10` for away
+- Uses the SPECIFIED `raw_market_id` (can be same as existing or different)
+- Copies participants, timeframes, price_keys from template
+- Returns created partner markets
+
+**Why always include raw_market_id:**
+- Simpler client logic (no conditional)
+- Explicit and clear what raw market is being used
+- Works for all cases (same raw market OR different raw market)
+- Backend handles both the same way
+
+---
+
+## 📊 Comparison: Full vs Simplified
+
+| Aspect | Full Flow | Simplified Flow |
+|--------|-----------|-----------------|
+| **When** | First link | Adding variables |
+| **User enters** | Variable, participants, timeframes, raw market, price keys | Variable number + raw market selection |
+| **Endpoint** | `POST /markets/link` (2 calls) | `POST /markets/add-variable` (1 call) |
+| **Client work** | Build 2 complete requests | Simple form with 2 fields |
+| **Backend work** | Create from scratch | Clone from template |
+| **Raw Market** | User manually selects | MUST show dropdown, defaults to existing |
+
+---
+
+## 🎨 UI State Management
+
+### Market Card Display
+
+```typescript
+interface MarketState {
+  router_market: RouterMarketProps;
+  has_linked_raw_markets: boolean;
+  existing_variables: Array<{ variable: number; linked_count: number }>;
+  raw_markets: RawMarketProps[];
+}
+
+function renderMarketCard(market: MarketState) {
+  if (!market.has_linked_raw_markets) {
+    return <Button>Link Market</Button>;  // Full flow
+  }
+
+  if (market.router_market.variable_required) {
+    return (
+      <>
+        <ExistingVariablesList variables={market.existing_variables} />
+        <Button>+ Add Variable</Button>  // Simplified flow
+      </>
+    );
+  }
+
+  return <CheckMark />;  // No variables needed, done
+}
+```
+
+### Add Variable Modal (CORRECT IMPLEMENTATION)
+
+```typescript
+interface AddVariableModalProps {
+  router_contest_id: string;
+  router_market_id: string;
+  partner_id: string;
+  existing_variables: Array<{ variable: number }>;
+  raw_markets: Array<{ raw_market_id: string; pretty_title: string; external_id: string }>;
+  onSuccess: () => void;
+}
+
+function AddVariableModal({
+  router_contest_id,
+  router_market_id,
+  partner_id,
+  existing_variables,
+  raw_markets,
+  onSuccess
+}: AddVariableModalProps) {
+  // Find the default raw market (the one currently used by existing variables)
+  const getDefaultRawMarketId = () => {
+    // In practice, you would look this up from existing partner markets
+    // For now, default to the first raw market in the list
+    return raw_markets[0]?.raw_market_id || '';
+  };
+
+  const [variable, setVariable] = useState('');
+  const [selectedRawMarket, setSelectedRawMarket] = useState(getDefaultRawMarketId());
+
+  const handleSubmit = async () => {
+    // ALWAYS include raw_market_id - this is CRITICAL
+    const payload = {
+      router_contest_id,
+      router_market_id,
+      partner_id,
+      variable: Number(variable),
+      raw_market_id: selectedRawMarket  // ← ALWAYS include this
+    };
+
+    const response = await fetch('/markets/add-variable', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+
+    if (response.ok) {
+      onSuccess();
+    }
+  };
+
+  return (
+    <Modal>
+      <h2>Add Variable</h2>
+
+      {/* Show existing variables for reference */}
+      <div>
+        <label>Existing Variables:</label>
+        <p>{existing_variables.map(v => v.variable).join(', ')}</p>
+      </div>
+
+      {/* Variable input - REQUIRED */}
+      <Input
+        label="New Variable"
+        type="number"
+        step="0.5"
+        value={variable}
+        onChange={setVariable}
+        placeholder="Enter number (e.g., 7, 10, 3.5)"
+        required
+      />
+
+      {/* Raw Market Selector - ALWAYS VISIBLE AND REQUIRED */}
+      <Select
+        label="Raw Market"
+        value={selectedRawMarket}
+        onChange={setSelectedRawMarket}
+        required
+      >
+        {raw_markets.map(rm => (
+          <option key={rm.raw_market_id} value={rm.raw_market_id}>
+            {rm.pretty_title} ({rm.external_id})
+          </option>
+        ))}
+      </Select>
+
+      <p className="help-text">
+        Select which raw market to attach this variable to.
+        The first option is the one currently used by existing variables.
+      </p>
+
+      <Button onClick={handleSubmit} disabled={!variable || !selectedRawMarket}>
+        Add Variable
+      </Button>
+    </Modal>
+  );
+}
+```
+
+**Key Points:**
+- ✅ Raw market dropdown is ALWAYS visible (not conditional)
+- ✅ raw_market_id is ALWAYS included in the request
+- ✅ First raw market is pre-selected by default
+- ✅ User can select any raw market from the list
+- ✅ No confusing radio buttons or conditional logic
+
+---
+
+## 🔑 Key Rules
+
+### Variable Entry (Client Logic)
+
+**For Spreads:**
+- User enters: `7`
+- Home side gets: `+7` (positive)
+- Away side gets: `-7` (negative)
+
+**For Totals:**
+- User enters: `220.5`
+- Over side gets: `220.5`
+- Under side gets: `220.5`
+
+### Backend Handles
+
+✅ Creating signed variables (`+7` and `-7`)
+✅ Looking up router_market_variable (or creating if needed)
+✅ Cloning side structure from template
+✅ Detecting duplicates (won't create if already exists)
+
+### Client Handles
+
+✅ Determining when to show "Link Market" vs "+ Add Variable"
+✅ Flipping the sign for away sides (home = positive, away = negative for spreads)
+✅ **ALWAYS displaying raw market dropdown** in Add Variable modal
+✅ Selecting default raw market (the one currently used)
+✅ **ALWAYS including raw_market_id** in the add-variable request
+✅ Making 2 calls for full flow, 1 call for simplified flow
+
+---
+
+## 🧪 Testing Checklist
+
+- [ ] Link first variable to Spread market (full flow)
+- [ ] Add second variable to same raw market (simplified, existing)
+- [ ] Add third variable to different raw market (simplified, new)
+- [ ] Link Total market (verify both sides use same variable)
+- [ ] Link Moneyline market (no variables required)
+- [ ] Verify duplicate detection works (try adding same variable twice)
+
+---
+
+## 🚨 Error Handling
+
+### Common Errors
+
+**"No existing partner markets found to use as template"**
+- Cause: Trying to use simplified flow before doing full flow
+- Solution: Use "Link Market" button first to create initial link
+
+**"Market not found"**
+- Cause: Invalid router_market_id or router_contest_id
+- Solution: Verify contest has market in supported markets
+
+**"Partner not linked to contest"**
+- Cause: Partner contest doesn't exist
+- Solution: Link the contest to the partner first
+
+---
+
+## 📝 Summary
+
+### Initial Setup (Per Partner, Per Market Type)
+1. Use **Full Flow** (`POST /markets/link` × 2)
+2. Requires all details: participants, timeframes, raw market, etc.
+
+### Adding More Variables
+1. Use **Simplified Flow** (`POST /markets/add-variable`)
+2. **Enter the variable number** (e.g., 7, 10, 3.5)
+3. **Select raw market from dropdown** (ALWAYS show dropdown, defaults to current)
+4. **ALWAYS include raw_market_id** in the request
+5. System clones everything else from template (participants, timeframes, price_keys)
+
+**Critical Requirements for Add Variable:**
+- ✅ MUST show raw market dropdown (not conditional, always visible)
+- ✅ MUST send raw_market_id in request (always include it)
+- ✅ Default to the raw market currently used by existing variables
+- ✅ Allow user to select any raw market from the list
+
+This approach gives you **maximum flexibility** (can attach to any raw market) while keeping the interface **super simple** (only 2 form fields: variable + raw market).
+
+---
+
+## 🔧 Partner-Specific Considerations
+
+### Kalshi Variable Handling
+
+**Important:** Kalshi markets include a `floor_strike` property that represents the variable value, but it requires conversion for spread markets.
+
+**Kalshi's Perspective:**
+- Kalshi phrases markets from the **favorite's perspective** (positive numbers)
+- Example: "Baltimore will win by more than 7.5" → `floor_strike: 7.5`
+
+**BetRouter's Perspective:**
+- Spreads are stored from the **standard perspective** (negative for favorite, positive for underdog)
+- Baltimore (favorite) → variable: `-7.5`
+- Opponent (underdog) → variable: `+7.5`
+
+**How Raw Markets Are Displayed:**
+- Spread markets: `pretty_title` includes `(±7.5)` to indicate both sides
+- Total markets: `pretty_title` includes `(220.5)` to show the line
+- Example: "Baltimore will win by more than 7.5 (±7.5)"
+
+**When Linking:**
+1. Admin sees: "Baltimore will win by more than 7.5 (±7.5)"
+2. For Baltimore (home/favorite) side: Enter `-7.5` as the variable
+3. For Opponent (away/underdog) side: Enter `+7.5` as the variable
+4. Both sides will use `price_key: "yes"` since the market is phrased from the favorite's perspective
+
+**Example Linking Flow:**
+
+```json
+// Home Side (Baltimore - Favorite)
+POST /markets/link
+{
+  "raw_market_id": "raw-kalshi-spread-1",
+  "router_market_id": "rm-spread",
+  "market_side_id": "side-home",
+  "partner_participant_id": "pp-baltimore",
+  "timeframe_id": "tf-full-game",
+  "variable": -7.5,
+  "variable_type": "spread",
+  "price_key": "yes"  // YES = Baltimore covers the spread
+}
+
+// Away Side (Opponent - Underdog)
+POST /markets/link
+{
+  "raw_market_id": "raw-kalshi-spread-1",
+  "router_market_id": "rm-spread",
+  "market_side_id": "side-away",
+  "partner_participant_id": "pp-opponent",
+  "timeframe_id": "tf-full-game",
+  "variable": 7.5,
+  "variable_type": "spread",
+  "price_key": "no"   // NO = Baltimore doesn't cover (opponent covers)
+}
+```
+
+**Key Rules for Kalshi Spreads:**
+- ✅ Favorite side: negative variable, `price_key: "yes"`
+- ✅ Underdog side: positive variable, `price_key: "no"`
+- ✅ Both sides link to the SAME raw_market
+- ✅ The `floor_strike` value is always positive in Kalshi's data, convert based on side
+