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
}

// 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)
}