cheapo/internal/game/game.go

// Package game defines the provider-agnostic free-game offer type shared by
// all store clients (epic, steam, ...).
package game

import (
	"context"
	"time"
)

// Game describes one free game offer, independent of the store it came from.
type Game struct {
	Title         string    `json:"title"`
	ID            string    `json:"id"`   // store-stable ID (epic offer id / steam appid)
	Slug          string    `json:"slug"` // store page slug or empty
	URL           string    `json:"url"`  // full store page URL
	Store         string    `json:"store"`
	Kind          string    `json:"kind,omitempty"` // e.g. "free-now", "upcoming", "free-to-keep", "free-weekend"
	Description   string    `json:"description,omitempty"`
	Seller        string    `json:"seller,omitempty"`
	StartDate     time.Time `json:"start_date,omitempty"`
	EndDate       time.Time `json:"end_date,omitempty"`              // end of the free period, zero = unknown
	PriceFmt      string    `json:"price_formatted,omitempty"`       // original price, formatted
	FinalPriceFmt string    `json:"final_price_formatted,omitempty"` // discounted price, formatted (deals only)
	DiscountPct   int       `json:"discount_pct,omitempty"`          // e.g. 90 = 90 % off (deals only)
}

// Provider is implemented by every store client.
type Provider interface {
	// Name returns the store identifier, e.g. "epic" or "steam".
	Name() string
	// GetFreeGames returns the games that are currently free.
	GetFreeGames(ctx context.Context) ([]Game, error)
}

// UpcomingProvider is implemented by stores that announce future giveaways.
// Providers without it are skipped when upcoming offers are requested.
type UpcomingProvider interface {
	// GetUpcomingGames returns announced games that will become free.
	GetUpcomingGames(ctx context.Context) ([]Game, error)
}

// DealProvider is implemented by stores that expose discounted offers.
// Providers without it are skipped when deals are requested.
type DealProvider interface {
	// GetDeals returns currently discounted games (free ones included).
	GetDeals(ctx context.Context) ([]Game, error)
}