cricinfo-cli-go 0.1.0

package/internal/cricinfo/coverage_ledger.go

@@ -0,0 +1,122 @@
+package cricinfo
+
+// TemplateCoverageEntry maps a researched endpoint template to public command coverage.
+type TemplateCoverageEntry struct {
+	Template      string
+	CommandFamily string
+	Command       string
+	View          string
+}
+
+// FieldPathCoverageEntry maps a field-path family to public command coverage.
+type FieldPathCoverageEntry struct {
+	Family        string
+	CommandFamily string
+	Command       string
+	View          string
+}
+
+var templateCoverageLedger = map[string]TemplateCoverageEntry{
+	"/":                                           {Template: "/", CommandFamily: "leagues", Command: "leagues list", View: "root discovery seed"},
+	"/athletes":                                   {Template: "/athletes", CommandFamily: "search", Command: "search players", View: "global athlete discovery seed"},
+	"/athletes/{id}":                              {Template: "/athletes/{id}", CommandFamily: "players", Command: "players profile", View: "player profile"},
+	"/athletes/{id}/news":                         {Template: "/athletes/{id}/news", CommandFamily: "players", Command: "players news", View: "player news list"},
+	"/athletes/{id}/statistics":                   {Template: "/athletes/{id}/statistics", CommandFamily: "players", Command: "players stats", View: "player statistics categories"},
+	"/events":                                     {Template: "/events", CommandFamily: "matches", Command: "matches list", View: "event discovery"},
+	"/events/{id}":                                {Template: "/events/{id}", CommandFamily: "matches", Command: "matches show", View: "event competition expansion"},
+	"/events/{id}/competitions/{id}":              {Template: "/events/{id}/competitions/{id}", CommandFamily: "competitions", Command: "competitions show", View: "competition summary"},
+	"/events/{id}/teams/{id}":                     {Template: "/events/{id}/teams/{id}", CommandFamily: "teams", Command: "teams show", View: "event-team identity subview"},
+	"/leagues":                                    {Template: "/leagues", CommandFamily: "leagues", Command: "leagues list", View: "league discovery"},
+	"/leagues/{id}":                               {Template: "/leagues/{id}", CommandFamily: "leagues", Command: "leagues show", View: "league summary"},
+	"/leagues/{id}/athletes/{id}":                 {Template: "/leagues/{id}/athletes/{id}", CommandFamily: "leagues", Command: "leagues athletes", View: "league athlete profile"},
+	"/leagues/{id}/athletes/{n}":                  {Template: "/leagues/{id}/athletes/{n}", CommandFamily: "leagues", Command: "leagues athletes", View: "league athlete index page"},
+	"/leagues/{id}/calendar":                      {Template: "/leagues/{id}/calendar", CommandFamily: "leagues", Command: "leagues calendar", View: "calendar root"},
+	"/leagues/{id}/calendar/offdays":              {Template: "/leagues/{id}/calendar/offdays", CommandFamily: "leagues", Command: "leagues calendar", View: "calendar offdays section"},
+	"/leagues/{id}/calendar/ondays":               {Template: "/leagues/{id}/calendar/ondays", CommandFamily: "leagues", Command: "leagues calendar", View: "calendar ondays section"},
+	"/leagues/{id}/events":                        {Template: "/leagues/{id}/events", CommandFamily: "leagues", Command: "leagues events", View: "league event list"},
+	"/leagues/{id}/events/{id}":                   {Template: "/leagues/{id}/events/{id}", CommandFamily: "leagues", Command: "leagues events", View: "event expansion"},
+	"/leagues/{id}/events/{id}/competitions/{id}": {Template: "/leagues/{id}/events/{id}/competitions/{id}", CommandFamily: "competitions", Command: "competitions show", View: "competition summary"},
+	"/leagues/{id}/events/{id}/competitions/{id}/broadcasts":                                                     {Template: "/leagues/{id}/events/{id}/competitions/{id}/broadcasts", CommandFamily: "competitions", Command: "competitions broadcasts", View: "competition broadcasts"},
+	"/leagues/{id}/events/{id}/competitions/{id}/details":                                                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/details", CommandFamily: "matches", Command: "matches details", View: "delivery ref page"},
+	"/leagues/{id}/events/{id}/competitions/{id}/details/{id}":                                                   {Template: "/leagues/{id}/events/{id}/competitions/{id}/details/{id}", CommandFamily: "matches", Command: "matches details", View: "delivery event detail"},
+	"/leagues/{id}/events/{id}/competitions/{id}/details/{n}":                                                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/details/{n}", CommandFamily: "matches", Command: "matches details", View: "delivery event detail"},
+	"/leagues/{id}/events/{id}/competitions/{id}/matchcards":                                                     {Template: "/leagues/{id}/events/{id}/competitions/{id}/matchcards", CommandFamily: "matches", Command: "matches scorecard", View: "batting/bowling/partnership cards"},
+	"/leagues/{id}/events/{id}/competitions/{id}/odds":                                                           {Template: "/leagues/{id}/events/{id}/competitions/{id}/odds", CommandFamily: "competitions", Command: "competitions odds", View: "competition odds"},
+	"/leagues/{id}/events/{id}/competitions/{id}/officials":                                                      {Template: "/leagues/{id}/events/{id}/competitions/{id}/officials", CommandFamily: "competitions", Command: "competitions officials", View: "competition officials"},
+	"/leagues/{id}/events/{id}/competitions/{id}/plays":                                                          {Template: "/leagues/{id}/events/{id}/competitions/{id}/plays", CommandFamily: "matches", Command: "matches plays", View: "play-derived delivery events"},
+	"/leagues/{id}/events/{id}/competitions/{id}/situation":                                                      {Template: "/leagues/{id}/events/{id}/competitions/{id}/situation", CommandFamily: "matches", Command: "matches situation", View: "match situation"},
+	"/leagues/{id}/events/{id}/competitions/{id}/situation/odds":                                                 {Template: "/leagues/{id}/events/{id}/competitions/{id}/situation/odds", CommandFamily: "matches", Command: "matches situation", View: "situation odds subview"},
+	"/leagues/{id}/events/{id}/competitions/{id}/status":                                                         {Template: "/leagues/{id}/events/{id}/competitions/{id}/status", CommandFamily: "matches", Command: "matches status", View: "match status"},
+	"/leagues/{id}/events/{id}/competitions/{id}/tickets":                                                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/tickets", CommandFamily: "competitions", Command: "competitions tickets", View: "competition tickets"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}":                                               {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}", CommandFamily: "teams", Command: "teams show --match <match>", View: "competitor summary"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/leaders":                                       {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/leaders", CommandFamily: "teams", Command: "teams leaders --match <match>", View: "team leaders"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores":                                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores", CommandFamily: "matches", Command: "matches innings", View: "team innings list"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}":                                {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}", CommandFamily: "matches", Command: "matches innings", View: "innings pointer"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}":                            {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}", CommandFamily: "matches", Command: "matches deliveries", View: "period innings detail"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/fow":                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/fow", CommandFamily: "matches", Command: "matches fow", View: "fall-of-wicket list"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/fow/{n}":                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/fow/{n}", CommandFamily: "matches", Command: "matches fow", View: "fall-of-wicket detail"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/leaders":                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/leaders", CommandFamily: "matches", Command: "matches deliveries", View: "period leaders subview"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/partnerships":               {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/partnerships", CommandFamily: "matches", Command: "matches partnerships", View: "partnership list"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/partnerships/{n}":           {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/partnerships/{n}", CommandFamily: "matches", Command: "matches partnerships", View: "partnership detail"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/statistics/{n}":             {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/linescores/{n}/{n}/statistics/{n}", CommandFamily: "matches", Command: "matches deliveries", View: "period statistics timelines"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/records":                                       {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/records", CommandFamily: "teams", Command: "teams records --match <match>", View: "team records categories"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster":                                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster", CommandFamily: "teams", Command: "teams roster --match <match>", View: "match roster entries"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/linescores":                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/linescores", CommandFamily: "players", Command: "players innings --match <match>", View: "player innings list"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/linescores/{n}/{n}/statistics/{n}": {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/linescores/{n}/{n}/statistics/{n}", CommandFamily: "players", Command: "players innings --match <match>", View: "player innings period statistics"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/statistics/{n}":                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/roster/{id}/statistics/{n}", CommandFamily: "players", Command: "players match-stats --match <match>", View: "player match statistics"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/scores":                                        {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/scores", CommandFamily: "teams", Command: "teams scores --match <match>", View: "team score"},
+	"/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/statistics":                                    {Template: "/leagues/{id}/events/{id}/competitions/{id}/competitors/{id}/statistics", CommandFamily: "teams", Command: "teams statistics --match <match>", View: "team statistics categories"},
+	"/leagues/{id}/seasons":                       {Template: "/leagues/{id}/seasons", CommandFamily: "leagues", Command: "leagues seasons", View: "season list"},
+	"/leagues/{id}/seasons/{id}":                  {Template: "/leagues/{id}/seasons/{id}", CommandFamily: "seasons", Command: "seasons show", View: "season detail"},
+	"/leagues/{id}/seasons/{id}/types":            {Template: "/leagues/{id}/seasons/{id}/types", CommandFamily: "seasons", Command: "seasons types", View: "season type list"},
+	"/leagues/{id}/seasons/{id}/types/{n}":        {Template: "/leagues/{id}/seasons/{id}/types/{n}", CommandFamily: "seasons", Command: "seasons types", View: "season type detail"},
+	"/leagues/{id}/seasons/{id}/types/{n}/groups": {Template: "/leagues/{id}/seasons/{id}/types/{n}/groups", CommandFamily: "seasons", Command: "seasons groups", View: "season group list"},
+	"/leagues/{id}/standings":                     {Template: "/leagues/{id}/standings", CommandFamily: "standings", Command: "standings show", View: "standings groups"},
+	"/teams/{id}":                                 {Template: "/teams/{id}", CommandFamily: "teams", Command: "teams show", View: "global team profile"},
+}
+
+var fieldPathFamilyCoverageLedger = map[string]FieldPathCoverageEntry{
+	"athlete":          {Family: "athlete", CommandFamily: "players", Command: "players profile", View: "player identity"},
+	"athletesInvolved": {Family: "athletesInvolved", CommandFamily: "matches", Command: "matches details", View: "delivery athlete involvement"},
+	"batsman":          {Family: "batsman", CommandFamily: "matches", Command: "matches details", View: "delivery batting context"},
+	"bowler":           {Family: "bowler", CommandFamily: "matches", Command: "matches details", View: "delivery bowling context"},
+	"broadcasts":       {Family: "broadcasts", CommandFamily: "competitions", Command: "competitions broadcasts", View: "competition broadcasts"},
+	"competitions":     {Family: "competitions", CommandFamily: "competitions", Command: "competitions metadata", View: "competition metadata root"},
+	"competitors":      {Family: "competitors", CommandFamily: "teams", Command: "teams show --match <match>", View: "match competitor view"},
+	"details":          {Family: "details", CommandFamily: "matches", Command: "matches details", View: "delivery detail refs"},
+	"dismissal":        {Family: "dismissal", CommandFamily: "players", Command: "players dismissals --match <match>", View: "dismissal metadata"},
+	"entries":          {Family: "entries", CommandFamily: "teams", Command: "teams roster --match <match>", View: "roster entries"},
+	"fow":              {Family: "fow", CommandFamily: "matches", Command: "matches fow", View: "fall-of-wicket timeline"},
+	"innings":          {Family: "innings", CommandFamily: "matches", Command: "matches innings", View: "innings summary"},
+	"items":            {Family: "items", CommandFamily: "matches", Command: "matches list", View: "page envelope items"},
+	"leagues":          {Family: "leagues", CommandFamily: "leagues", Command: "leagues show", View: "league hierarchy"},
+	"matchcards":       {Family: "matchcards", CommandFamily: "matches", Command: "matches scorecard", View: "scorecard cards"},
+	"odds":             {Family: "odds", CommandFamily: "competitions", Command: "competitions odds", View: "competition odds"},
+	"officials":        {Family: "officials", CommandFamily: "competitions", Command: "competitions officials", View: "competition officials"},
+	"over":             {Family: "over", CommandFamily: "matches", Command: "matches deliveries", View: "over timeline"},
+	"partnerships":     {Family: "partnerships", CommandFamily: "matches", Command: "matches partnerships", View: "partnership timeline"},
+	"seasons":          {Family: "seasons", CommandFamily: "seasons", Command: "seasons groups", View: "season hierarchy"},
+	"situation":        {Family: "situation", CommandFamily: "matches", Command: "matches situation", View: "situation snapshot"},
+	"splits":           {Family: "splits", CommandFamily: "players", Command: "players stats", View: "statistics splits and categories"},
+	"status":           {Family: "status", CommandFamily: "matches", Command: "matches status", View: "status summary"},
+	"teams":            {Family: "teams", CommandFamily: "teams", Command: "teams show", View: "team identity"},
+	"tickets":          {Family: "tickets", CommandFamily: "competitions", Command: "competitions tickets", View: "competition tickets"},
+}
+
+// TemplateCoverageLedger returns a copy of the researched-template coverage ledger.
+func TemplateCoverageLedger() map[string]TemplateCoverageEntry {
+	out := make(map[string]TemplateCoverageEntry, len(templateCoverageLedger))
+	for template, entry := range templateCoverageLedger {
+		out[template] = entry
+	}
+	return out
+}
+
+// FieldPathFamilyCoverageLedger returns a copy of the field-family coverage ledger.
+func FieldPathFamilyCoverageLedger() map[string]FieldPathCoverageEntry {
+	out := make(map[string]FieldPathCoverageEntry, len(fieldPathFamilyCoverageLedger))
+	for family, entry := range fieldPathFamilyCoverageLedger {
+		out[family] = entry
+	}
+	return out
+}

package/internal/cricinfo/coverage_ledger_test.go

@@ -0,0 +1,253 @@
+package cricinfo
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+func TestTemplateCoverageLedgerIncludesAllResearchedTemplates(t *testing.T) {
+	t.Parallel()
+
+	ledger := TemplateCoverageLedger()
+	if len(ledger) == 0 {
+		t.Fatalf("template coverage ledger is empty")
+	}
+
+	templates := researchedTemplatesFromTSV(t)
+	if len(templates) == 0 {
+		t.Fatalf("expected researched templates from TSV")
+	}
+
+	missing := make([]string, 0)
+	for _, template := range templates {
+		entry, ok := ledger[template]
+		if !ok {
+			missing = append(missing, template)
+			continue
+		}
+		if strings.TrimSpace(entry.Template) == "" || entry.Template != template {
+			t.Fatalf("template ledger entry mismatch for %q: %+v", template, entry)
+		}
+		if strings.TrimSpace(entry.CommandFamily) == "" {
+			t.Fatalf("template %q has empty command family", template)
+		}
+		if strings.TrimSpace(entry.Command) == "" {
+			t.Fatalf("template %q has empty command mapping", template)
+		}
+		if strings.TrimSpace(entry.View) == "" {
+			t.Fatalf("template %q has empty result view mapping", template)
+		}
+	}
+
+	extras := make([]string, 0)
+	expected := make(map[string]struct{}, len(templates))
+	for _, template := range templates {
+		expected[template] = struct{}{}
+	}
+	for template := range ledger {
+		if _, ok := expected[template]; !ok {
+			extras = append(extras, template)
+		}
+	}
+
+	sort.Strings(missing)
+	sort.Strings(extras)
+	if len(missing) > 0 || len(extras) > 0 {
+		t.Fatalf("template coverage drift: missing=%v extras=%v", missing, extras)
+	}
+}
+
+func TestFieldPathFamilyCoverageLedgerKnownFamiliesMapped(t *testing.T) {
+	t.Parallel()
+
+	ledger := FieldPathFamilyCoverageLedger()
+	if len(ledger) == 0 {
+		t.Fatalf("field-path family coverage ledger is empty")
+	}
+
+	catalogFamilies := researchedFieldPathFamilies(t)
+	if len(catalogFamilies) == 0 {
+		t.Fatalf("expected field-path families from catalog")
+	}
+
+	expectedFamilies := []string{
+		"athlete",
+		"athletesInvolved",
+		"batsman",
+		"bowler",
+		"broadcasts",
+		"competitions",
+		"competitors",
+		"details",
+		"dismissal",
+		"entries",
+		"fow",
+		"innings",
+		"items",
+		"leagues",
+		"matchcards",
+		"odds",
+		"officials",
+		"over",
+		"partnerships",
+		"seasons",
+		"situation",
+		"splits",
+		"status",
+		"teams",
+		"tickets",
+	}
+
+	missingLedger := make([]string, 0)
+	missingCatalog := make([]string, 0)
+	for _, family := range expectedFamilies {
+		entry, ok := ledger[family]
+		if !ok {
+			missingLedger = append(missingLedger, family)
+			continue
+		}
+		if strings.TrimSpace(entry.Family) == "" || entry.Family != family {
+			t.Fatalf("field-path ledger entry mismatch for %q: %+v", family, entry)
+		}
+		if strings.TrimSpace(entry.CommandFamily) == "" {
+			t.Fatalf("field-path family %q has empty command family", family)
+		}
+		if strings.TrimSpace(entry.Command) == "" {
+			t.Fatalf("field-path family %q has empty command mapping", family)
+		}
+		if strings.TrimSpace(entry.View) == "" {
+			t.Fatalf("field-path family %q has empty result view mapping", family)
+		}
+		if _, ok := catalogFamilies[family]; !ok {
+			missingCatalog = append(missingCatalog, family)
+		}
+	}
+
+	sort.Strings(missingLedger)
+	sort.Strings(missingCatalog)
+	if len(missingLedger) > 0 || len(missingCatalog) > 0 {
+		t.Fatalf("field-path family coverage drift: missing ledger=%v missing catalog=%v", missingLedger, missingCatalog)
+	}
+}
+
+func researchedTemplatesFromTSV(t *testing.T) []string {
+	t.Helper()
+
+	path := filepath.Join(repoRoot(t), "gg", "agent-outputs", "cricinfo-working-templates.tsv")
+	file, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open working templates TSV %q: %v", path, err)
+	}
+	defer file.Close()
+
+	seen := map[string]struct{}{}
+	templates := make([]string, 0, 64)
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "\t", 3)
+		if len(parts) < 2 {
+			t.Fatalf("unexpected TSV row %q", line)
+		}
+		template := strings.TrimSpace(parts[1])
+		if template == "" {
+			continue
+		}
+		if _, ok := seen[template]; ok {
+			continue
+		}
+		seen[template] = struct{}{}
+		templates = append(templates, template)
+	}
+	if err := scanner.Err(); err != nil {
+		t.Fatalf("scan working templates TSV %q: %v", path, err)
+	}
+
+	sort.Strings(templates)
+	return templates
+}
+
+func researchedFieldPathFamilies(t *testing.T) map[string]struct{} {
+	t.Helper()
+
+	path := filepath.Join(repoRoot(t), "gg", "agent-outputs", "cricinfo-field-path-catalog.txt")
+	file, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open field-path catalog %q: %v", path, err)
+	}
+	defer file.Close()
+
+	families := map[string]struct{}{}
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		path := strings.TrimSpace(scanner.Text())
+		if path == "" {
+			continue
+		}
+		family := firstFieldPathFamily(path)
+		if family == "" {
+			continue
+		}
+		families[family] = struct{}{}
+	}
+	if err := scanner.Err(); err != nil {
+		t.Fatalf("scan field-path catalog %q: %v", path, err)
+	}
+
+	return families
+}
+
+func firstFieldPathFamily(path string) string {
+	parts := strings.Split(path, ".")
+	for _, part := range parts {
+		token := strings.TrimSpace(part)
+		if token == "" || token == "$ref" {
+			continue
+		}
+		if isNumericToken(token) {
+			continue
+		}
+		return token
+	}
+	return ""
+}
+
+func isNumericToken(value string) bool {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return false
+	}
+	for _, r := range value {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	return true
+}
+
+func repoRoot(t *testing.T) string {
+	t.Helper()
+
+	dir, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+
+	for {
+		if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+			return dir
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			t.Fatalf("unable to locate repository root from %q", dir)
+		}
+		dir = parent
+	}
+}

package/internal/cricinfo/decode.go

@@ -0,0 +1,115 @@
+package cricinfo
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// DecodePage decodes a paginated envelope payload.
+func DecodePage[T any](data []byte) (*Page[T], error) {
+	var page Page[T]
+	if err := json.Unmarshal(data, &page); err != nil {
+		return nil, fmt.Errorf("decode paginated payload: %w", err)
+	}
+
+	if page.Items == nil {
+		page.Items = []T{}
+	}
+
+	return &page, nil
+}
+
+// DecodeObjectCollection decodes array-shaped or object-shaped collection fields.
+func DecodeObjectCollection[T any](data []byte, field string) ([]T, error) {
+	field = strings.TrimSpace(field)
+	if field == "" {
+		return nil, fmt.Errorf("collection field is required")
+	}
+
+	var envelope map[string]json.RawMessage
+	if err := json.Unmarshal(data, &envelope); err != nil {
+		return nil, fmt.Errorf("decode envelope: %w", err)
+	}
+
+	raw, ok := envelope[field]
+	if !ok {
+		return nil, fmt.Errorf("collection field %q not found", field)
+	}
+	trimmed := strings.TrimSpace(string(raw))
+	if trimmed == "" || trimmed == "null" {
+		return []T{}, nil
+	}
+
+	if strings.HasPrefix(trimmed, "[") {
+		var items []T
+		if err := json.Unmarshal(raw, &items); err != nil {
+			return nil, fmt.Errorf("decode array collection field %q: %w", field, err)
+		}
+		return items, nil
+	}
+
+	if strings.HasPrefix(trimmed, "{") {
+		var keyed map[string]json.RawMessage
+		if err := json.Unmarshal(raw, &keyed); err != nil {
+			return nil, fmt.Errorf("decode object collection field %q: %w", field, err)
+		}
+
+		keys := make([]string, 0, len(keyed))
+		for k := range keyed {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+
+		items := make([]T, 0, len(keys))
+		for _, key := range keys {
+			var item T
+			if err := json.Unmarshal(keyed[key], &item); err != nil {
+				return nil, fmt.Errorf("decode object collection field %q key %q: %w", field, key, err)
+			}
+			items = append(items, item)
+		}
+		return items, nil
+	}
+
+	return nil, fmt.Errorf("collection field %q is neither array nor object", field)
+}
+
+// DecodeStatsObject decodes a single-object stats payload.
+func DecodeStatsObject(data []byte) (*StatsObject, error) {
+	var stats StatsObject
+	if err := json.Unmarshal(data, &stats); err != nil {
+		return nil, fmt.Errorf("decode stats payload: %w", err)
+	}
+	return &stats, nil
+}
+
+// ExtractOptionalRef gets a nested {"$ref":"..."} field when present.
+func ExtractOptionalRef(data []byte, field string) (*Ref, bool, error) {
+	field = strings.TrimSpace(field)
+	if field == "" {
+		return nil, false, fmt.Errorf("field is required")
+	}
+
+	var envelope map[string]json.RawMessage
+	if err := json.Unmarshal(data, &envelope); err != nil {
+		return nil, false, fmt.Errorf("decode envelope: %w", err)
+	}
+
+	raw, ok := envelope[field]
+	if !ok || string(raw) == "null" {
+		return nil, false, nil
+	}
+
+	var ref Ref
+	if err := json.Unmarshal(raw, &ref); err != nil {
+		return nil, false, fmt.Errorf("decode ref field %q: %w", field, err)
+	}
+
+	if strings.TrimSpace(ref.URL) == "" {
+		return nil, false, nil
+	}
+
+	return &ref, true, nil
+}

package/internal/cricinfo/decode_test.go

@@ -0,0 +1,100 @@
+package cricinfo
+
+import (
+	"testing"
+)
+
+type testItem struct {
+	ID int `json:"id"`
+}
+
+func TestDecodePage(t *testing.T) {
+	t.Parallel()
+
+	page, err := DecodePage[Ref]([]byte(`{"count":1,"items":[{"$ref":"http://example.com/a"}],"pageCount":1,"pageIndex":1,"pageSize":20}`))
+	if err != nil {
+		t.Fatalf("DecodePage error: %v", err)
+	}
+
+	if page.Count != 1 || page.PageSize != 20 {
+		t.Fatalf("unexpected page metadata: %+v", page)
+	}
+	if len(page.Items) != 1 || page.Items[0].URL != "http://example.com/a" {
+		t.Fatalf("unexpected page items: %+v", page.Items)
+	}
+}
+
+func TestDecodeObjectCollectionArray(t *testing.T) {
+	t.Parallel()
+
+	items, err := DecodeObjectCollection[testItem]([]byte(`{"entries":[{"id":1},{"id":2}]}`), "entries")
+	if err != nil {
+		t.Fatalf("DecodeObjectCollection error: %v", err)
+	}
+	if len(items) != 2 || items[0].ID != 1 || items[1].ID != 2 {
+		t.Fatalf("unexpected array items: %+v", items)
+	}
+}
+
+func TestDecodeObjectCollectionObject(t *testing.T) {
+	t.Parallel()
+
+	items, err := DecodeObjectCollection[testItem]([]byte(`{"entries":{"b":{"id":2},"a":{"id":1}}}`), "entries")
+	if err != nil {
+		t.Fatalf("DecodeObjectCollection error: %v", err)
+	}
+	if len(items) != 2 || items[0].ID != 1 || items[1].ID != 2 {
+		t.Fatalf("unexpected object items order/content: %+v", items)
+	}
+}
+
+func TestDecodeObjectCollectionNull(t *testing.T) {
+	t.Parallel()
+
+	items, err := DecodeObjectCollection[testItem]([]byte(`{"entries":null}`), "entries")
+	if err != nil {
+		t.Fatalf("DecodeObjectCollection error: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("expected empty slice, got %+v", items)
+	}
+}
+
+func TestDecodeStatsObject(t *testing.T) {
+	t.Parallel()
+
+	stats, err := DecodeStatsObject([]byte(`{"$ref":"http://example.com/stats","athlete":{"$ref":"http://example.com/athletes/1"},"splits":{"categories":[]}}`))
+	if err != nil {
+		t.Fatalf("DecodeStatsObject error: %v", err)
+	}
+
+	if stats.Ref != "http://example.com/stats" {
+		t.Fatalf("unexpected stats ref: %q", stats.Ref)
+	}
+	if stats.Athlete == nil || stats.Athlete.URL == "" {
+		t.Fatalf("expected athlete ref in stats object")
+	}
+	if len(stats.Splits) == 0 {
+		t.Fatalf("expected splits payload")
+	}
+}
+
+func TestExtractOptionalRef(t *testing.T) {
+	t.Parallel()
+
+	ref, ok, err := ExtractOptionalRef([]byte(`{"status":{"$ref":"http://example.com/status"}}`), "status")
+	if err != nil {
+		t.Fatalf("ExtractOptionalRef error: %v", err)
+	}
+	if !ok || ref == nil || ref.URL != "http://example.com/status" {
+		t.Fatalf("unexpected optional ref output: ok=%v ref=%+v", ok, ref)
+	}
+
+	nilRef, nilOk, nilErr := ExtractOptionalRef([]byte(`{"status":null}`), "status")
+	if nilErr != nil {
+		t.Fatalf("ExtractOptionalRef null error: %v", nilErr)
+	}
+	if nilOk || nilRef != nil {
+		t.Fatalf("expected null optional ref, got ok=%v ref=%+v", nilOk, nilRef)
+	}
+}