package scrape

import "context"

// Adapter is the read-side contract a tracker integration implements. The
// concrete implementations live in internal/integrations/trackers/<name>.go
// and register themselves with the trackers package's factory registry.
//
// The interface lives in scrape (not in trackers) so that the scheduler can
// depend on it without creating a scheduler → trackers → scrape import cycle
// (trackers depends on scrape for *Hygiene).
type Adapter interface {
	// Name returns the tracker_id this adapter is bound to.
	Name() string

	// FetchRatio scrapes the tracker's profile or stats endpoint and returns
	// the parsed snapshot. The caller (the scheduler) is responsible for
	// persisting the snapshot.
	FetchRatio(ctx context.Context) (RatioSnapshot, error)

	// Health is a cheap reachability check used by the health endpoint and
	// by integration-health metrics.
	Health(ctx context.Context) error
}

// RatioSnapshot is the typed result of a single FetchRatio. Pointer fields
// are NULL-able: nil means the tracker did not report the field.
type RatioSnapshot struct {
	RealUploadedBytes   *int64
	RealDownloadedBytes *int64
	RealRatio           *float64

	DisplayedUploadedBytes   *int64
	DisplayedDownloadedBytes *int64
	DisplayedRatio           *float64

	BonusPoints *int64
	UnsatCount  *int64
	UnsatLimit  *int64
	ClassOrRank string

	// RawJSON is the unparsed body the adapter consulted, persisted into the
	// snapshot's raw_json column for after-the-fact debugging.
	RawJSON string
}