package oppintel

import (
	"context"
	"errors"
)

// ErrThrottled signals a source hit its provider rate limit (a 429). The ingester treats it as a soft
// stop: it keeps and reports whatever was ingested before the limit, so one exhausted daily quota never
// loses the records already pulled or the other sources.
var ErrThrottled = errors.New("oppintel: source rate limited")

// OpportunitySource is the provider adapter contract. Each federal feed implements it, handling its own
// paging and iteration internally and calling yield once per normalized record. A yield error stops the
// pull and is returned, so a storage or database failure aborts the run fail closed. The streaming shape
// fits every feed: SAM loops its NAICS codes, an awards source paginates, a forecast source reads a CSV.
type OpportunitySource interface {
	// Name is the provenance label stamped on every record this source yields (for example SAM.gov).
	Name() string
	// Fetch pulls the source's configured scope and calls yield once per normalized record. On a
	// provider rate limit it returns ErrThrottled so the ingester can stop that source gracefully.
	Fetch(ctx context.Context, yield func(OpportunityRecord) error) error
}