package sources

import (
	"context"

	"gitea.maximumdirect.net/ejr/feedkit/event"
)

// Input is the common surface shared by all source types.
//
// A source may be polling (PollSource) or event-driven (StreamSource).
// Both source types emit domain-agnostic event.Event values.
type Input interface {
	Name() string
}

// PollSource is a configured polling source that emits 0..N events per poll.
//
// PollSource implementations live in domain modules (weatherfeeder/newsfeeder/...)
// and are registered into a feedkit sources.Registry.
//
// feedkit infrastructure treats PollSource as opaque; it just calls Poll()
// on the configured cadence and publishes the resulting events.
type PollSource interface {
	// Name is the configured source name (used for logs and included in emitted events).
	Name() string

	// Poll fetches/processes one input batch and returns 0..N events.
	// A single poll can emit multiple event kinds.
	// Implementations should honor ctx.Done() for network calls and other I/O.
	Poll(ctx context.Context) ([]event.Event, error)
}

// Source is a compatibility alias for the legacy polling-source name.
type Source = PollSource

// StreamSource is an event-driven source (NATS/RabbitMQ/MQTT/etc).
//
// Run should block, producing events into `out` until ctx is cancelled or a fatal error occurs.
// It MUST NOT close out (the scheduler/daemon owns the bus).
type StreamSource interface {
	Input
	Run(ctx context.Context, out chan<- event.Event) error
}

// KindSource is an optional interface for sources that advertise one "primary" kind.
// This is legacy-friendly but no longer required.
type KindSource interface {
	Kind() event.Kind
}

// KindsSource is an optional interface for sources that advertise multiple kinds.
type KindsSource interface {
	Kinds() []event.Kind
}