overtime-live-trading-utils 2.1.19 → 2.1.21

package/resolution_live_markets.md

@@ -1,351 +0,0 @@
-# Live Market Resolution - TypeId-Based Implementation Plan
-
-## Overview
-Enhance the resolution utilities to support checking if specific market types (identified by `typeId`) can be resolved based on which periods are complete in a live game.
-
-## Problem Statement
-The current `canResolveMarketForGameIdAndSport` function only checks if periods are complete, but doesn't answer the key question: **"Can I resolve market type 10021 (e.g., 1st Quarter Winner) right now?"**
-
-For live trading, we need to know which specific markets can be resolved based on:
-1. Which periods have been completed
-2. The market type (typeId)
-3. Whether the game is still live or fully completed
-
-## Understanding TypeIds
-
-TypeIds identify specific market types:
-- `10021` - 1st period/quarter/half markets (various bet types)
-- `10022` - 2nd period markets
-- `10031` - 1st period totals
-- `0`, `10001`, `10002` - Full game markets (should NOT resolve during live games)
-
-Example from codebase:
-```typescript
-{
-    sportId: 9806,
-    typeId: 10022,
-    marketName: '1st Half Moneyline',
-    type: 'Moneyline',
-}
-```
-
-## Solution Design
-
-### 1. Sport-Specific Period-to-TypeId Mappings
-Created three separate mappings for different sport period structures:
-
-```typescript
-// Sport period structure types
-export enum SportPeriodType {
-    HALVES_BASED = 'halves_based',      // Soccer, NCAAB
-    QUARTERS_BASED = 'quarters_based',   // NFL, NBA
-    INNINGS_BASED = 'innings_based',     // MLB, NPB, KBO, College Baseball
-}
-
-// HALVES-BASED (Soccer, NCAAB): 2 periods
-export const HALVES_PERIOD_TYPE_ID_MAPPING = {
-  1: [10021, 10031, 10041, 10051, ...], // Period 1 = 1st half
-  2: [10022, 10032, 10042, 10052, ...], // Period 2 = 2nd half
-};
-
-// QUARTERS-BASED (NFL, NBA): 4 quarters + overtime
-export const QUARTERS_PERIOD_TYPE_ID_MAPPING = {
-  1: [10021, 10031, 10041, ...],        // 1st quarter
-  2: [10022, 10032, 10042, 10051, ...], // 2nd quarter + 1st half (10051)
-  3: [10023, 10033, 10043, ...],        // 3rd quarter
-  4: [10024, 10034, 10044, 10052, ...], // 4th quarter + 2nd half (10052)
-  5: [10025, 10035, 10045, ...],        // Overtime
-};
-
-// INNINGS-BASED (MLB, NPB, KBO): 9+ innings
-export const INNINGS_PERIOD_TYPE_ID_MAPPING = {
-  1-4: [...],                           // Innings 1-4
-  5: [10025, 10035, 10045, 10051, ...], // 5th inning + 1st half (10051)
-  6-8: [...],                           // Innings 6-8
-  9: [10029, 10039, 10049, 10052, ...], // 9th inning + 2nd half (10052)
-};
-
-// Full game type IDs that should be skipped for live period resolution
-const FULL_GAME_TYPE_IDS = [0, 10001, 10002, 10003, 10004, 10010, 10011, 10012];
-```
-
-**Key Insight**: TypeId 10051 (1st half) resolves at different periods depending on sport type:
-- Soccer (HALVES): Period 1
-- NFL (QUARTERS): Period 2 (after both quarters 1 & 2)
-- MLB (INNINGS): Period 5 (after first 5 innings)
-
-### 2. Updated Function Signature
-
-**Before:**
-```typescript
-canResolveMarketForGameIdAndSport(
-    gameId: string,
-    event: OpticOddsEvent,
-    sportName?: string
-): boolean
-```
-
-**After:**
-```typescript
-// Single typeId overload
-canResolveMarketsForEvent(
-    event: OpticOddsEvent,
-    typeId: number,
-    sportType: SportPeriodType,  // REQUIRED
-    sportName?: string
-): boolean
-
-// Batch typeIds overload
-canResolveMarketsForEvent(
-    event: OpticOddsEvent,
-    typeIds: number[],
-    sportType: SportPeriodType,  // REQUIRED
-    sportName?: string
-): number[]
-```
-
-### 3. Implementation Logic
-
-```typescript
-// Helper function to select appropriate mapping based on sport type
-function selectMappingForSportType(sportType: SportPeriodType) {
-    switch (sportType) {
-        case SportPeriodType.HALVES_BASED:
-            return HALVES_PERIOD_TYPE_ID_MAPPING;
-        case SportPeriodType.QUARTERS_BASED:
-            return QUARTERS_PERIOD_TYPE_ID_MAPPING;
-        case SportPeriodType.INNINGS_BASED:
-            return INNINGS_PERIOD_TYPE_ID_MAPPING;
-    }
-}
-
-export function canResolveMarketsForEvent(
-    event: OpticOddsEvent,
-    typeIdOrTypeIds: number | number[],
-    sportType: SportPeriodType,  // REQUIRED - must specify sport type
-    sportName?: string
-): boolean | number[] {
-    // Get completed periods
-    const periodData = detectCompletedPeriods(event, sportName);
-    if (!periodData) {
-        return Array.isArray(typeIdOrTypeIds) ? [] : false;
-    }
-
-    // Check if game is fully completed
-    const status = (event.fixture?.status || event.status || '').toLowerCase();
-    const isCompleted = status === 'completed' || status === 'complete' || status === 'finished';
-
-    // Select appropriate mapping based on sport type
-    const mapping = selectMappingForSportType(sportType);
-
-    // Collect all resolvable typeIds based on completed periods
-    const resolvableTypeIds = new Set<number>();
-
-    for (const period of periodData.completedPeriods) {
-        const typeIdsForPeriod = mapping[period] || [];
-        typeIdsForPeriod.forEach(id => resolvableTypeIds.add(id));
-    }
-
-    // Full game typeIds can only be resolved when game is completed
-    if (isCompleted) {
-        // Could add full game typeIds to resolvable set here if needed
-        // For now, they're explicitly excluded during live games
-    }
-
-    // Single typeId check
-    if (typeId !== undefined) {
-        // Full game typeIds cannot be resolved during live games
-        if (!isCompleted && FULL_GAME_TYPE_IDS.includes(typeId)) {
-            return false;
-        }
-        return resolvableTypeIds.has(typeId);
-    }
-
-    // Batch typeIds check
-    if (typeIds !== undefined) {
-        return typeIds.filter(id => {
-            // Exclude full game typeIds during live games
-            if (!isCompleted && FULL_GAME_TYPE_IDS.includes(id)) {
-                return false;
-            }
-            return resolvableTypeIds.has(id);
-        });
-    }
-
-    return false;
-};
-```
-
-### 4. Why Sport Parameter is Needed
-
-Different sports have different period structures:
-- **Soccer**: 2 halves (periods 1-2)
-- **NFL/NBA**: 4 quarters (periods 1-4)
-- **MLB**: 9+ innings (periods 1-9)
-- **NHL**: 3 periods (periods 1-3)
-- **Tennis**: Sets (periods 1-5)
-
-The sport parameter allows future customization where period-to-typeId mappings could be sport-specific. For example:
-- Soccer might map period 1 → "1st Half" markets
-- Basketball might map period 1 → "1st Quarter" markets
-- Both use period 1, but represent different market types
-
-## Implementation Steps
-
-### Phase 1: Add Sport-Specific Mappings ✅ COMPLETED
-- [x] Add `SportPeriodType` enum to `src/types/resolution.ts`
-- [x] Add `HALVES_PERIOD_TYPE_ID_MAPPING` to `src/types/resolution.ts`
-- [x] Add `QUARTERS_PERIOD_TYPE_ID_MAPPING` to `src/types/resolution.ts`
-- [x] Add `INNINGS_PERIOD_TYPE_ID_MAPPING` to `src/types/resolution.ts`
-- [x] Add `FULL_GAME_TYPE_IDS` to `src/types/resolution.ts`
-- [x] Export all constants and enum
-
-### Phase 2: Update Resolution Function ✅ COMPLETED
-- [x] Update `canResolveMarketsForEvent` function signature to accept `sportType` parameter
-- [x] Implement sport-type-based mapping selection logic
-- [x] Update function overloads for clean API (no undefined placeholders)
-- [x] Handle full game typeIds exclusion during live games
-- [x] Keep backward compatibility with existing functions
-
-### Phase 3: Add Tests ✅ COMPLETED
-- [x] Test single typeId resolution
-- [x] Test batch typeIds resolution
-- [x] Test that full game typeIds are NOT resolved during live games
-- [x] Test with real event data (Soccer, NFL, MLB)
-- [x] Test edge cases (no completed periods, game in overtime, etc.)
-- [x] Add sport-specific tests for typeId 10051 (1st half) with HALVES, QUARTERS, INNINGS
-- [x] Add sport-specific tests for typeId 10052 (2nd half)
-- [x] Test default behavior (QUARTERS_BASED when no sportType provided)
-
-### Phase 4: Update Exports ✅ COMPLETED
-- [x] Export `SportPeriodType` enum from index.ts
-- [x] Export `HALVES_PERIOD_TYPE_ID_MAPPING` from index.ts
-- [x] Export `QUARTERS_PERIOD_TYPE_ID_MAPPING` from index.ts
-- [x] Export `INNINGS_PERIOD_TYPE_ID_MAPPING` from index.ts
-- [x] Export `FULL_GAME_TYPE_IDS` from index.ts
-- [x] Keep existing exports for backward compatibility
-
-### Phase 5: Testing & Validation ✅ COMPLETED
-- [x] Run full test suite
-- [x] Verify all 85 tests pass
-- [x] Test with real OpticOdds API responses (Soccer, NFL, MLB)
-- [x] Verify TypeScript compilation succeeds
-
-## Example Usage
-
-### Single TypeId Check
-```typescript
-import { canResolveMarketsForEvent, SportPeriodType } from 'overtime-live-trading-utils';
-
-// Check NFL (quarters-based) - Can we resolve "1st Quarter Winner" market (typeId 10021)?
-const canResolve = canResolveMarketsForEvent(
-    nflEvent,
-    10021,
-    SportPeriodType.QUARTERS_BASED
-);
-
-if (canResolve) {
-    // Resolve the 1st quarter market
-    resolveMarket(10021);
-}
-```
-
-### Sport-Specific TypeId 10051 (1st Half) Resolution
-```typescript
-// Soccer (halves-based): Resolves after period 1
-const soccerCanResolve = canResolveMarketsForEvent(
-    soccerEvent,
-    10051,
-    SportPeriodType.HALVES_BASED
-); // true if period 1 complete
-
-// NFL (quarters-based): Resolves after period 2
-const nflCanResolve = canResolveMarketsForEvent(
-    nflEvent,
-    10051,
-    SportPeriodType.QUARTERS_BASED
-); // true if period 2 complete
-
-// MLB (innings-based): Resolves after period 5
-const mlbCanResolve = canResolveMarketsForEvent(
-    mlbEvent,
-    10051,
-    SportPeriodType.INNINGS_BASED
-); // true if period 5 complete
-```
-
-### Batch TypeIds Check
-```typescript
-// Which of these markets can we resolve right now for an NFL game?
-const marketTypeIds = [10021, 10022, 10031, 10001];
-const resolvableMarkets = canResolveMarketsForEvent(
-    nflEvent,
-    marketTypeIds,
-    SportPeriodType.QUARTERS_BASED
-);
-
-// Returns: [10021, 10031] if only period 1 is complete
-// Full game typeId 10001 is excluded during live games
-resolvableMarkets.forEach(typeId => resolveMarket(typeId));
-```
-
-### Function Overloads (TypeScript)
-The function uses TypeScript overloads for clean API:
-```typescript
-// Single typeId → returns boolean
-function canResolveMarketsForEvent(
-    event: OpticOddsEvent,
-    typeId: number,
-    sportType: SportPeriodType,  // REQUIRED
-    sportName?: string
-): boolean;
-
-// Batch typeIds → returns number[]
-function canResolveMarketsForEvent(
-    event: OpticOddsEvent,
-    typeIds: number[],
-    sportType: SportPeriodType,  // REQUIRED
-    sportName?: string
-): number[];
-```
-
-## Testing Strategy
-
-### Test Cases
-1. **Period 1 Complete (Live Soccer 2nd Half)**
-   - Input: Soccer event in 2nd half, period 1 complete
-   - TypeIds: [10021, 10022, 10001]
-   - Expected: [10021] (only 1st half markets resolvable)
-
-2. **Periods 1-4 Complete (NFL Overtime)**
-   - Input: NFL event in overtime, all 4 quarters complete
-   - TypeIds: [10021, 10022, 10023, 10024, 10001]
-   - Expected: [10021, 10022, 10023, 10024] (all quarter markets, but not full game)
-
-3. **Game Completed**
-   - Input: Completed game with all periods
-   - TypeIds: [10021, 10001]
-   - Expected: [10021, 10001] (all markets including full game)
-
-4. **No Periods Complete**
-   - Input: Live game in 1st period
-   - TypeIds: [10021, 10022]
-   - Expected: [] (no markets resolvable yet)
-
-## Benefits
-
-1. **Centralized Logic**: Single source of truth for market resolution rules
-2. **Sport-Agnostic**: Works across all sports (Soccer, NFL, NBA, MLB, NHL, Tennis, etc.)
-3. **Flexible**: Supports both single and batch typeId checks
-4. **Safe**: Prevents resolving full game markets during live games
-5. **Efficient**: O(1) lookup for period→typeId mapping
-6. **Maintainable**: Easy to add new typeIds or modify mappings
-7. **Testable**: Clear input/output for comprehensive testing
-
-## Future Enhancements
-
-1. **Sport-Specific Mappings**: Different PERIOD_TYPE_ID_MAPPING per sport if needed
-2. **Dynamic Mapping**: Load period→typeId mappings from database/config
-3. **Market Type Validation**: Verify typeIds exist before checking resolution
-4. **Resolution Metadata**: Return additional info (which period completed, when, scores)
-5. **Caching**: Cache resolvable typeIds per event to avoid recalculation