cricinfo-cli-go 0.1.2 → 0.1.4

package/internal/cricinfo/matches_phase7_test.go

@@ -101,11 +101,18 @@ func TestMatchServicePhase7ScorecardAndSituation(t *testing.T) {
 	if situationResult.Kind != EntityMatchSituation {
 		t.Fatalf("expected situation kind %q, got %q", EntityMatchSituation, situationResult.Kind)
 	}
-	if situationResult.Status != ResultStatusEmpty {
-		t.Fatalf("expected sparse situation to return empty status, got %q", situationResult.Status)
+	if situationResult.Status == ResultStatusEmpty {
+		t.Fatalf("expected sparse situation to synthesize live fallback data")
 	}
-	if strings.TrimSpace(situationResult.Message) == "" {
-		t.Fatalf("expected sparse situation message to be populated")
+	situation, ok := situationResult.Data.(*MatchSituation)
+	if !ok {
+		t.Fatalf("expected situation data type *MatchSituation, got %T", situationResult.Data)
+	}
+	if situation.Live == nil {
+		t.Fatalf("expected synthesized live situation view")
+	}
+	if len(situation.Live.RecentBalls) == 0 {
+		t.Fatalf("expected recent balls in synthesized live situation view")
 	}
 }
 

package/internal/cricinfo/normalize_entities.go

@@ -223,6 +223,7 @@ func NormalizeTeamRosterEntries(data []byte, team Team, scope TeamScope, matchID
 			PlayerRef:     athleteRef,
 			DisplayName:   displayName,
 			TeamID:        team.ID,
+			TeamName:      nonEmpty(team.ShortName, team.Name, team.ID),
 			TeamRef:       team.Ref,
 			MatchID:       strings.TrimSpace(matchID),
 			Scope:         scope,
@@ -260,6 +261,7 @@ func NormalizeTeamAthletePage(data []byte, team Team) ([]TeamRosterEntry, error)
 			PlayerID:  refIDs(playerRef)["athleteId"],
 			PlayerRef: playerRef,
 			TeamID:    team.ID,
+			TeamName:  nonEmpty(team.ShortName, team.Name, team.ID),
 			TeamRef:   team.Ref,
 			Scope:     TeamScopeGlobal,
 		})
@@ -670,12 +672,18 @@ func NormalizeDeliveryEvent(data []byte) (*DeliveryEvent, error) {
 	dismissal := mapField(payload, "dismissal")
 	batsman := mapField(payload, "batsman")
 	bowler := mapField(payload, "bowler")
+	otherBatsman := mapField(payload, "otherBatsman")
+	otherBowler := mapField(payload, "otherBowler")
 	fielder := mapField(dismissal, "fielder")
 	batsmanRef := nonEmpty(nestedRef(payload, "batsman", "athlete"), refFromField(payload, "batsman"))
 	bowlerRef := nonEmpty(nestedRef(payload, "bowler", "athlete"), refFromField(payload, "bowler"))
+	otherBatsmanRef := nonEmpty(nestedRef(payload, "otherBatsman", "athlete"), refFromField(payload, "otherBatsman"))
+	otherBowlerRef := nonEmpty(nestedRef(payload, "otherBowler", "athlete"), refFromField(payload, "otherBowler"))
 	fielderRef := nonEmpty(nestedRef(payload, "dismissal", "fielder", "athlete"), nestedRef(payload, "dismissal", "fielder"))
 	batsmanID := nonEmpty(stringField(batsman, "playerId"), stringField(batsman, "id"), refIDs(batsmanRef)["athleteId"])
 	bowlerID := nonEmpty(stringField(bowler, "playerId"), stringField(bowler, "id"), refIDs(bowlerRef)["athleteId"])
+	otherBatsmanID := nonEmpty(stringField(otherBatsman, "playerId"), stringField(otherBatsman, "id"), refIDs(otherBatsmanRef)["athleteId"])
+	otherBowlerID := nonEmpty(stringField(otherBowler, "playerId"), stringField(otherBowler, "id"), refIDs(otherBowlerRef)["athleteId"])
 	fielderID := nonEmpty(stringField(fielder, "playerId"), stringField(fielder, "id"), refIDs(fielderRef)["athleteId"])
 	teamRef := refFromField(payload, "team")
 	teamIDs := refIDs(teamRef)
@@ -685,41 +693,65 @@ func NormalizeDeliveryEvent(data []byte) (*DeliveryEvent, error) {
 	bbbTimestamp := int64Field(payload, "bbbTimestamp")
 
 	event := &DeliveryEvent{
-		Ref:              ref,
-		ID:               nonEmpty(stringField(payload, "id"), ids["detailId"]),
-		LeagueID:         ids["leagueId"],
-		EventID:          ids["eventId"],
-		CompetitionID:    ids["competitionId"],
-		MatchID:          ids["competitionId"],
-		TeamID:           nonEmpty(teamIDs["teamId"], teamIDs["competitorId"]),
-		Period:           intField(payload, "period"),
-		PeriodText:       stringField(payload, "periodText"),
-		OverNumber:       intField(over, "number"),
-		BallNumber:       intField(over, "ball"),
-		ScoreValue:       intField(payload, "scoreValue"),
-		ShortText:        stringField(payload, "shortText"),
-		Text:             stringField(payload, "text"),
-		HomeScore:        stringField(payload, "homeScore"),
-		AwayScore:        stringField(payload, "awayScore"),
-		BatsmanRef:       batsmanRef,
-		BowlerRef:        bowlerRef,
-		BatsmanPlayerID:  batsmanID,
-		BowlerPlayerID:   bowlerID,
-		FielderPlayerID:  fielderID,
-		AthletePlayerIDs: athletePlayerIDs,
-		PlayType:         playType,
-		Dismissal:        dismissal,
-		DismissalType:    stringField(dismissal, "type"),
-		DismissalName:    nonEmpty(stringField(dismissal, "name"), stringField(dismissal, "type")),
-		DismissalCard:    stringField(dismissal, "dismissalCard"),
-		DismissalText:    stringField(dismissal, "text"),
-		SpeedKPH:         floatField(payload, "speedKPH"),
-		XCoordinate:      xCoordinate,
-		YCoordinate:      yCoordinate,
-		BBBTimestamp:     bbbTimestamp,
-		CoordinateX:      xCoordinate,
-		CoordinateY:      yCoordinate,
-		Timestamp:        bbbTimestamp,
+		Ref:                 ref,
+		ID:                  nonEmpty(stringField(payload, "id"), ids["detailId"]),
+		LeagueID:            ids["leagueId"],
+		EventID:             ids["eventId"],
+		CompetitionID:       ids["competitionId"],
+		MatchID:             ids["competitionId"],
+		TeamID:              nonEmpty(teamIDs["teamId"], teamIDs["competitorId"]),
+		Period:              intField(payload, "period"),
+		PeriodText:          stringField(payload, "periodText"),
+		OverNumber:          intField(over, "number"),
+		BallNumber:          intField(over, "ball"),
+		ScoreValue:          intField(payload, "scoreValue"),
+		ShortText:           stringField(payload, "shortText"),
+		Text:                stringField(payload, "text"),
+		HomeScore:           stringField(payload, "homeScore"),
+		AwayScore:           stringField(payload, "awayScore"),
+		BatsmanRef:          batsmanRef,
+		BowlerRef:           bowlerRef,
+		OtherBatsmanRef:     otherBatsmanRef,
+		OtherBowlerRef:      otherBowlerRef,
+		BatsmanPlayerID:     batsmanID,
+		BowlerPlayerID:      bowlerID,
+		OtherBatsmanID:      otherBatsmanID,
+		OtherBowlerID:       otherBowlerID,
+		FielderPlayerID:     fielderID,
+		AthletePlayerIDs:    athletePlayerIDs,
+		BatsmanRuns:         intField(batsman, "runs"),
+		BatsmanTotalRuns:    intField(batsman, "totalRuns"),
+		BatsmanBalls:        intField(batsman, "faced"),
+		BatsmanFours:        intField(batsman, "fours"),
+		BatsmanSixes:        intField(batsman, "sixes"),
+		OtherBatterRuns:     intField(otherBatsman, "totalRuns"),
+		OtherBatterBalls:    intField(otherBatsman, "faced"),
+		OtherBatterFours:    intField(otherBatsman, "fours"),
+		OtherBatterSixes:    intField(otherBatsman, "sixes"),
+		BowlerOvers:         floatField(bowler, "overs"),
+		BowlerBalls:         intField(bowler, "balls"),
+		BowlerMaidens:       intField(bowler, "maidens"),
+		BowlerConceded:      intField(bowler, "conceded"),
+		BowlerWickets:       intField(bowler, "wickets"),
+		OtherBowlerOvers:    floatField(otherBowler, "overs"),
+		OtherBowlerBalls:    intField(otherBowler, "balls"),
+		OtherBowlerMaidens:  intField(otherBowler, "maidens"),
+		OtherBowlerConceded: intField(otherBowler, "conceded"),
+		OtherBowlerWickets:  intField(otherBowler, "wickets"),
+		Sequence:            intField(payload, "sequence"),
+		PlayType:            playType,
+		Dismissal:           dismissal,
+		DismissalType:       stringField(dismissal, "type"),
+		DismissalName:       nonEmpty(stringField(dismissal, "name"), stringField(dismissal, "type")),
+		DismissalCard:       stringField(dismissal, "dismissalCard"),
+		DismissalText:       stringField(dismissal, "text"),
+		SpeedKPH:            floatField(payload, "speedKPH"),
+		XCoordinate:         xCoordinate,
+		YCoordinate:         yCoordinate,
+		BBBTimestamp:        bbbTimestamp,
+		CoordinateX:         xCoordinate,
+		CoordinateY:         yCoordinate,
+		Timestamp:           bbbTimestamp,
 		Extensions: extensionsFromMap(payload,
 			"$ref", "id", "period", "periodText", "over", "scoreValue", "shortText", "text", "homeScore", "awayScore",
 			"batsman", "bowler", "playType", "dismissal", "speedKPH", "xCoordinate", "yCoordinate", "bbbTimestamp",

package/internal/cricinfo/players.go

@@ -546,9 +546,36 @@ func (s *PlayerService) statistics(ctx context.Context, query string, opts Playe
 		playerStats.PlayerRef = strings.TrimSpace(lookup.player.Ref)
 	}
 
+	warnings := append([]string{}, lookup.warnings...)
+	if playerStatsLooksPlaceholder(playerStats, resolved) {
+		fallbackResolved, fallbackStats, fallbackWarnings, ok := s.fallbackPlayerStatsFromMatchContext(ctx, lookup, opts)
+		warnings = append(warnings, fallbackWarnings...)
+		if ok {
+			warnings = append(warnings, "global athlete statistics were placeholder; using match-context statistics")
+			compact := compactWarnings(warnings)
+			result := NewDataResult(EntityPlayerStats, *fallbackStats)
+			if len(compact) > 0 {
+				result = NewPartialResult(EntityPlayerStats, *fallbackStats, compact...)
+			}
+			if fallbackResolved != nil {
+				result.RequestedRef = fallbackResolved.RequestedRef
+				result.CanonicalRef = fallbackResolved.CanonicalRef
+			}
+			return result, nil
+		}
+		warnings = append(warnings, fmt.Sprintf("global athlete statistics for %q appear placeholder and no match-context fallback was found", nonEmpty(lookup.player.DisplayName, lookup.entity.Name, query)))
+		result := NewDataResult(EntityPlayerStats, *playerStats)
+		if compact := compactWarnings(warnings); len(compact) > 0 {
+			result = NewPartialResult(EntityPlayerStats, *playerStats, compact...)
+		}
+		result.RequestedRef = resolved.RequestedRef
+		result.CanonicalRef = resolved.CanonicalRef
+		return result, nil
+	}
+
 	result := NewDataResult(EntityPlayerStats, *playerStats)
-	if len(lookup.warnings) > 0 {
-		result = NewPartialResult(EntityPlayerStats, *playerStats, lookup.warnings...)
+	if compact := compactWarnings(warnings); len(compact) > 0 {
+		result = NewPartialResult(EntityPlayerStats, *playerStats, compact...)
 	}
 	result.RequestedRef = resolved.RequestedRef
 	result.CanonicalRef = resolved.CanonicalRef
@@ -603,6 +630,213 @@ func (s *PlayerService) resolvePlayerLookup(ctx context.Context, query string, o
 	}, nil
 }
 
+func playerStatsLooksPlaceholder(stats *PlayerStatistics, resolved *ResolvedDocument) bool {
+	if stats == nil {
+		return true
+	}
+	if hasMeaningfulStatValues(stats.Categories) {
+		return false
+	}
+
+	playerRefID := strings.TrimSpace(refIDs(stats.PlayerRef)["athleteId"])
+	if playerRefID == "" {
+		return true
+	}
+	if strings.Contains(strings.TrimSpace(stats.Ref), "/athletes//statistics") {
+		return true
+	}
+	if resolved != nil && strings.Contains(strings.TrimSpace(resolved.CanonicalRef), "/athletes//statistics") {
+		return true
+	}
+	return false
+}
+
+func hasMeaningfulStatValues(categories []StatCategory) bool {
+	for _, category := range categories {
+		for _, stat := range category.Stats {
+			display := strings.TrimSpace(stat.DisplayValue)
+			if display != "" && display != "-" && display != "0" && display != "0.0" && display != "0.00" {
+				return true
+			}
+			if statAsFloat(stat) > 0 {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func (s *PlayerService) fallbackPlayerStatsFromMatchContext(
+	ctx context.Context,
+	lookup *playerLookup,
+	opts PlayerLookupOptions,
+) (*ResolvedDocument, *PlayerStatistics, []string, bool) {
+	if lookup == nil || s == nil || s.resolver == nil {
+		return nil, nil, nil, false
+	}
+
+	warnings := make([]string, 0)
+	matchHelper := &MatchService{client: s.client, resolver: s.resolver}
+	candidateIDs := compactWarnings([]string{
+		strings.TrimSpace(lookup.player.ID),
+		strings.TrimSpace(lookup.entity.ID),
+		strings.TrimSpace(refIDs(lookup.player.Ref)["athleteId"]),
+	})
+	candidateNames := compactWarnings([]string{
+		strings.TrimSpace(lookup.player.DisplayName),
+		strings.TrimSpace(lookup.player.FullName),
+		strings.TrimSpace(lookup.player.Name),
+		strings.TrimSpace(lookup.player.BattingName),
+		strings.TrimSpace(lookup.player.FieldingName),
+		strings.TrimSpace(lookup.entity.Name),
+		strings.TrimSpace(lookup.entity.ShortName),
+	})
+	playerQuery := nonEmpty(
+		strings.TrimSpace(lookup.player.ID),
+		strings.TrimSpace(lookup.player.DisplayName),
+		strings.TrimSpace(lookup.player.FullName),
+		strings.TrimSpace(lookup.player.BattingName),
+		strings.TrimSpace(lookup.player.FieldingName),
+		strings.TrimSpace(lookup.entity.Name),
+	)
+	seenMatch := map[string]struct{}{}
+	candidateMatches := make([]Match, 0, 40)
+	appendCandidateMatch := func(match Match) {
+		key := nonEmpty(strings.TrimSpace(match.ID), strings.TrimSpace(match.Ref))
+		if key == "" {
+			return
+		}
+		if _, ok := seenMatch[key]; ok {
+			return
+		}
+		seenMatch[key] = struct{}{}
+		candidateMatches = append(candidateMatches, match)
+	}
+
+	appendMatchesFromListResult := func(result NormalizedResult, source string) {
+		if result.Status == ResultStatusError {
+			if strings.TrimSpace(result.Message) != "" {
+				warnings = append(warnings, fmt.Sprintf("%s match-context source failed: %s", source, result.Message))
+			}
+			return
+		}
+		warnings = append(warnings, result.Warnings...)
+		for _, item := range result.Items {
+			switch typed := item.(type) {
+			case Match:
+				appendCandidateMatch(typed)
+			case *Match:
+				if typed != nil {
+					appendCandidateMatch(*typed)
+				}
+			}
+		}
+	}
+
+	liveResult, liveErr := matchHelper.Live(ctx, MatchListOptions{
+		Limit:    24,
+		LeagueID: strings.TrimSpace(opts.LeagueID),
+	})
+	if liveErr != nil {
+		warnings = append(warnings, fmt.Sprintf("match-context live source failed: %v", liveErr))
+	} else {
+		appendMatchesFromListResult(liveResult, "live")
+	}
+
+	listResult, listErr := matchHelper.List(ctx, MatchListOptions{
+		Limit:    36,
+		LeagueID: strings.TrimSpace(opts.LeagueID),
+	})
+	if listErr != nil {
+		warnings = append(warnings, fmt.Sprintf("match-context list source failed: %v", listErr))
+	} else {
+		appendMatchesFromListResult(listResult, "list")
+	}
+
+	if len(candidateMatches) == 0 {
+		matchSearch, err := s.resolver.Search(ctx, EntityMatch, "", ResolveOptions{
+			Limit:    24,
+			LeagueID: strings.TrimSpace(opts.LeagueID),
+		})
+		if err != nil {
+			warnings = append(warnings, fmt.Sprintf("match-context fallback unavailable: %v", err))
+			return nil, nil, compactWarnings(warnings), false
+		}
+		warnings = append(warnings, matchSearch.Warnings...)
+
+		for _, entity := range matchSearch.Entities {
+			ref := buildMatchRef(entity)
+			if ref == "" {
+				continue
+			}
+			matchResolved, matchErr := matchHelper.resolveRefChainResilient(ctx, ref)
+			if matchErr != nil {
+				warnings = append(warnings, fmt.Sprintf("match %s: %v", ref, matchErr))
+				continue
+			}
+			match, normalizeErr := NormalizeMatch(matchResolved.Body)
+			if normalizeErr != nil {
+				warnings = append(warnings, fmt.Sprintf("match %s: %v", matchResolved.CanonicalRef, normalizeErr))
+				continue
+			}
+			appendCandidateMatch(*match)
+		}
+	}
+
+	if len(candidateMatches) == 0 {
+		warnings = append(warnings, "match-context fallback found no recent matches")
+		return nil, nil, compactWarnings(warnings), false
+	}
+
+	for _, match := range candidateMatches {
+		team, roster, routeWarnings, found := s.findPlayerRosterEntry(ctx, match, playerQuery, candidateIDs, candidateNames)
+		warnings = append(warnings, routeWarnings...)
+		if !found {
+			continue
+		}
+
+		team = s.enrichTeamIdentityFromIndex(team)
+		roster = s.enrichRosterEntryFromIndex(roster)
+		statsRef := rosterPlayerStatisticsRef(match, team, roster)
+		if statsRef == "" {
+			warnings = append(warnings, fmt.Sprintf("match %s has no roster statistics route for player %s", match.ID, nonEmpty(roster.PlayerID, lookup.player.ID)))
+			continue
+		}
+
+		statsResolved, categories, statsErr := s.fetchStatCategories(ctx, statsRef)
+		if statsErr != nil {
+			warnings = append(warnings, fmt.Sprintf("player statistics %s: %v", statsRef, statsErr))
+			continue
+		}
+		if !hasMeaningfulStatValues(categories) {
+			warnings = append(warnings, fmt.Sprintf("player statistics %s returned no meaningful values", statsResolved.CanonicalRef))
+			continue
+		}
+
+		playerID := nonEmpty(strings.TrimSpace(lookup.player.ID), strings.TrimSpace(lookup.entity.ID), strings.TrimSpace(roster.PlayerID))
+		playerRef := nonEmpty(strings.TrimSpace(lookup.player.Ref), strings.TrimSpace(roster.PlayerRef))
+		stats := &PlayerStatistics{
+			Ref:          statsResolved.CanonicalRef,
+			PlayerID:     playerID,
+			PlayerRef:    playerRef,
+			SplitID:      "match-context",
+			Name:         "Match Context",
+			Abbreviation: "LIVE",
+			Categories:   categories,
+			Extensions: map[string]any{
+				"source":        "match-context-fallback",
+				"matchId":       strings.TrimSpace(match.ID),
+				"teamId":        strings.TrimSpace(team.ID),
+				"teamName":      teamDisplayLabel(team),
+				"statisticsRef": strings.TrimSpace(statsResolved.CanonicalRef),
+			},
+		}
+		return statsResolved, stats, compactWarnings(warnings), true
+	}
+
+	return nil, nil, compactWarnings(warnings), false
+}
+
 func (s *PlayerService) enrichPlayerProfile(ctx context.Context, player *Player) {
 	if s == nil || s.resolver == nil || player == nil {
 		return

package/internal/cricinfo/render_contract.go

@@ -16,6 +16,7 @@ const (
 	EntityMatch           EntityKind = "match"
 	EntityMatchScorecard  EntityKind = "match_scorecard"
 	EntityMatchSituation  EntityKind = "match_situation"
+	EntityMatchDuel       EntityKind = "match_duel"
 	EntityMatchPhases     EntityKind = "match_phases"
 	EntityCompetition     EntityKind = "competition"
 	EntityCompOfficial    EntityKind = "competition_official"
@@ -226,9 +227,78 @@ type MatchSituation struct {
 	MatchID       string         `json:"matchId,omitempty"`
 	OddsRef       string         `json:"oddsRef,omitempty"`
 	Data          map[string]any `json:"data,omitempty"`
+	Live          *MatchLiveView `json:"live,omitempty"`
 	Extensions    map[string]any `json:"extensions,omitempty"`
 }
 
+// MatchLiveView is a synthesized fan-first live snapshot when upstream situation payload is sparse.
+type MatchLiveView struct {
+	Fixture      string           `json:"fixture,omitempty"`
+	Status       string           `json:"status,omitempty"`
+	Score        string           `json:"score,omitempty"`
+	Overs        string           `json:"overs,omitempty"`
+	CurrentOver  int              `json:"currentOver,omitempty"`
+	BallInOver   int              `json:"ballInOver,omitempty"`
+	BattingTeam  string           `json:"battingTeam,omitempty"`
+	BowlingTeam  string           `json:"bowlingTeam,omitempty"`
+	Batters      []LiveBatterView `json:"batters,omitempty"`
+	Bowlers      []LiveBowlerView `json:"bowlers,omitempty"`
+	RecentBalls  []DeliveryEvent  `json:"recentBalls,omitempty"`
+	CurrentBalls []DeliveryEvent  `json:"currentOverBalls,omitempty"`
+	LastDetailID string           `json:"lastDetailId,omitempty"`
+	LastUpdateMS int64            `json:"lastUpdateMs,omitempty"`
+	SnapshotAt   string           `json:"snapshotAt,omitempty"`
+	SourceRoute  string           `json:"sourceRoute,omitempty"`
+	Stale        bool             `json:"stale"`
+	StaleReason  string           `json:"staleReason,omitempty"`
+}
+
+// LiveBatterView captures in-progress batter figures.
+type LiveBatterView struct {
+	PlayerID   string  `json:"playerId,omitempty"`
+	PlayerName string  `json:"playerName,omitempty"`
+	Runs       int     `json:"runs,omitempty"`
+	Balls      int     `json:"balls,omitempty"`
+	Fours      int     `json:"fours,omitempty"`
+	Sixes      int     `json:"sixes,omitempty"`
+	StrikeRate float64 `json:"strikeRate,omitempty"`
+	OnStrike   bool    `json:"onStrike"`
+}
+
+// LiveBowlerView captures in-progress bowler figures.
+type LiveBowlerView struct {
+	PlayerID   string  `json:"playerId,omitempty"`
+	PlayerName string  `json:"playerName,omitempty"`
+	Overs      float64 `json:"overs,omitempty"`
+	Balls      int     `json:"balls,omitempty"`
+	Maidens    int     `json:"maidens,omitempty"`
+	Conceded   int     `json:"conceded,omitempty"`
+	Wickets    int     `json:"wickets,omitempty"`
+	Economy    float64 `json:"economy,omitempty"`
+}
+
+// MatchDuel summarizes a batter-vs-bowler matchup in one match.
+type MatchDuel struct {
+	MatchID      string          `json:"matchId,omitempty"`
+	Fixture      string          `json:"fixture,omitempty"`
+	Score        string          `json:"score,omitempty"`
+	BatterID     string          `json:"batterId,omitempty"`
+	BatterName   string          `json:"batterName,omitempty"`
+	BowlerID     string          `json:"bowlerId,omitempty"`
+	BowlerName   string          `json:"bowlerName,omitempty"`
+	Balls        int             `json:"balls,omitempty"`
+	Runs         int             `json:"runs,omitempty"`
+	Dots         int             `json:"dots,omitempty"`
+	Fours        int             `json:"fours,omitempty"`
+	Sixes        int             `json:"sixes,omitempty"`
+	Wickets      int             `json:"wickets,omitempty"`
+	StrikeRate   float64         `json:"strikeRate,omitempty"`
+	RecentBalls  []DeliveryEvent `json:"recentBalls,omitempty"`
+	LastUpdateMS int64           `json:"lastUpdateMs,omitempty"`
+	SnapshotAt   string          `json:"snapshotAt,omitempty"`
+	SourceRoute  string          `json:"sourceRoute,omitempty"`
+}
+
 // Competition is the normalized competition metadata root view.
 type Competition struct {
 	Ref              string         `json:"ref,omitempty"`
@@ -488,6 +558,7 @@ type TeamRosterEntry struct {
 	PlayerRef     string         `json:"playerRef,omitempty"`
 	DisplayName   string         `json:"displayName,omitempty"`
 	TeamID        string         `json:"teamId,omitempty"`
+	TeamName      string         `json:"teamName,omitempty"`
 	TeamRef       string         `json:"teamRef,omitempty"`
 	MatchID       string         `json:"matchId,omitempty"`
 	Scope         TeamScope      `json:"scope,omitempty"`
@@ -692,43 +763,67 @@ type InningsWicket struct {
 
 // DeliveryEvent is the normalized ball-level event shape.
 type DeliveryEvent struct {
-	Ref              string         `json:"ref,omitempty"`
-	ID               string         `json:"id,omitempty"`
-	LeagueID         string         `json:"leagueId,omitempty"`
-	EventID          string         `json:"eventId,omitempty"`
-	CompetitionID    string         `json:"competitionId,omitempty"`
-	MatchID          string         `json:"matchId,omitempty"`
-	TeamID           string         `json:"teamId,omitempty"`
-	Period           int            `json:"period,omitempty"`
-	PeriodText       string         `json:"periodText,omitempty"`
-	OverNumber       int            `json:"overNumber,omitempty"`
-	BallNumber       int            `json:"ballNumber,omitempty"`
-	ScoreValue       int            `json:"scoreValue,omitempty"`
-	ShortText        string         `json:"shortText,omitempty"`
-	Text             string         `json:"text,omitempty"`
-	HomeScore        string         `json:"homeScore,omitempty"`
-	AwayScore        string         `json:"awayScore,omitempty"`
-	BatsmanRef       string         `json:"batsmanRef,omitempty"`
-	BowlerRef        string         `json:"bowlerRef,omitempty"`
-	BatsmanPlayerID  string         `json:"batsmanPlayerId,omitempty"`
-	BowlerPlayerID   string         `json:"bowlerPlayerId,omitempty"`
-	FielderPlayerID  string         `json:"fielderPlayerId,omitempty"`
-	AthletePlayerIDs []string       `json:"athletePlayerIds,omitempty"`
-	Involvement      []string       `json:"involvement,omitempty"`
-	PlayType         map[string]any `json:"playType,omitempty"`
-	Dismissal        map[string]any `json:"dismissal,omitempty"`
-	DismissalType    string         `json:"dismissalType,omitempty"`
-	DismissalName    string         `json:"dismissalName,omitempty"`
-	DismissalCard    string         `json:"dismissalCard,omitempty"`
-	DismissalText    string         `json:"dismissalText,omitempty"`
-	SpeedKPH         float64        `json:"speedKPH,omitempty"`
-	XCoordinate      *float64       `json:"xCoordinate"`
-	YCoordinate      *float64       `json:"yCoordinate"`
-	BBBTimestamp     int64          `json:"bbbTimestamp"`
-	CoordinateX      *float64       `json:"coordinateX,omitempty"`
-	CoordinateY      *float64       `json:"coordinateY,omitempty"`
-	Timestamp        int64          `json:"timestamp,omitempty"`
-	Extensions       map[string]any `json:"extensions,omitempty"`
+	Ref                 string         `json:"ref,omitempty"`
+	ID                  string         `json:"id,omitempty"`
+	LeagueID            string         `json:"leagueId,omitempty"`
+	EventID             string         `json:"eventId,omitempty"`
+	CompetitionID       string         `json:"competitionId,omitempty"`
+	MatchID             string         `json:"matchId,omitempty"`
+	TeamID              string         `json:"teamId,omitempty"`
+	Period              int            `json:"period,omitempty"`
+	PeriodText          string         `json:"periodText,omitempty"`
+	OverNumber          int            `json:"overNumber,omitempty"`
+	BallNumber          int            `json:"ballNumber,omitempty"`
+	ScoreValue          int            `json:"scoreValue,omitempty"`
+	ShortText           string         `json:"shortText,omitempty"`
+	Text                string         `json:"text,omitempty"`
+	HomeScore           string         `json:"homeScore,omitempty"`
+	AwayScore           string         `json:"awayScore,omitempty"`
+	BatsmanRef          string         `json:"batsmanRef,omitempty"`
+	BowlerRef           string         `json:"bowlerRef,omitempty"`
+	OtherBatsmanRef     string         `json:"otherBatsmanRef,omitempty"`
+	OtherBowlerRef      string         `json:"otherBowlerRef,omitempty"`
+	BatsmanPlayerID     string         `json:"batsmanPlayerId,omitempty"`
+	BowlerPlayerID      string         `json:"bowlerPlayerId,omitempty"`
+	OtherBatsmanID      string         `json:"otherBatsmanPlayerId,omitempty"`
+	OtherBowlerID       string         `json:"otherBowlerPlayerId,omitempty"`
+	FielderPlayerID     string         `json:"fielderPlayerId,omitempty"`
+	AthletePlayerIDs    []string       `json:"athletePlayerIds,omitempty"`
+	Involvement         []string       `json:"involvement,omitempty"`
+	BatsmanRuns         int            `json:"batsmanRuns,omitempty"`
+	BatsmanTotalRuns    int            `json:"batsmanTotalRuns,omitempty"`
+	BatsmanBalls        int            `json:"batsmanBalls,omitempty"`
+	BatsmanFours        int            `json:"batsmanFours,omitempty"`
+	BatsmanSixes        int            `json:"batsmanSixes,omitempty"`
+	OtherBatterRuns     int            `json:"otherBatterRuns,omitempty"`
+	OtherBatterBalls    int            `json:"otherBatterBalls,omitempty"`
+	OtherBatterFours    int            `json:"otherBatterFours,omitempty"`
+	OtherBatterSixes    int            `json:"otherBatterSixes,omitempty"`
+	BowlerOvers         float64        `json:"bowlerOvers,omitempty"`
+	BowlerBalls         int            `json:"bowlerBalls,omitempty"`
+	BowlerMaidens       int            `json:"bowlerMaidens,omitempty"`
+	BowlerConceded      int            `json:"bowlerConceded,omitempty"`
+	BowlerWickets       int            `json:"bowlerWickets,omitempty"`
+	OtherBowlerOvers    float64        `json:"otherBowlerOvers,omitempty"`
+	OtherBowlerBalls    int            `json:"otherBowlerBalls,omitempty"`
+	OtherBowlerMaidens  int            `json:"otherBowlerMaidens,omitempty"`
+	OtherBowlerConceded int            `json:"otherBowlerConceded,omitempty"`
+	OtherBowlerWickets  int            `json:"otherBowlerWickets,omitempty"`
+	Sequence            int            `json:"sequence,omitempty"`
+	PlayType            map[string]any `json:"playType,omitempty"`
+	Dismissal           map[string]any `json:"dismissal,omitempty"`
+	DismissalType       string         `json:"dismissalType,omitempty"`
+	DismissalName       string         `json:"dismissalName,omitempty"`
+	DismissalCard       string         `json:"dismissalCard,omitempty"`
+	DismissalText       string         `json:"dismissalText,omitempty"`
+	SpeedKPH            float64        `json:"speedKPH,omitempty"`
+	XCoordinate         *float64       `json:"xCoordinate"`
+	YCoordinate         *float64       `json:"yCoordinate"`
+	BBBTimestamp        int64          `json:"bbbTimestamp"`
+	CoordinateX         *float64       `json:"coordinateX,omitempty"`
+	CoordinateY         *float64       `json:"coordinateY,omitempty"`
+	Timestamp           int64          `json:"timestamp,omitempty"`
+	Extensions          map[string]any `json:"extensions,omitempty"`
 }
 
 // StatCategory is the normalized grouped statistics shape.
@@ -962,6 +1057,8 @@ func kindPlural(kind EntityKind) string {
 		return "match scorecards"
 	case EntityMatchSituation:
 		return "match situations"
+	case EntityMatchDuel:
+		return "match duels"
 	case EntityMatchPhases:
 		return "match phase reports"
 	case EntityCompetition:
@@ -1039,11 +1136,16 @@ func kindPlural(kind EntityKind) string {
 
 func compactWarnings(warnings []string) []string {
 	out := make([]string, 0, len(warnings))
+	seen := map[string]struct{}{}
 	for _, warning := range warnings {
 		warning = strings.TrimSpace(warning)
 		if warning == "" {
 			continue
 		}
+		if _, ok := seen[warning]; ok {
+			continue
+		}
+		seen[warning] = struct{}{}
 		out = append(out, warning)
 	}
 	if len(out) == 0 {