package iot

import "context"

// Provider is a pluggable source of IoT devices. Implementations own the device
// state and enforce the control_rules (capability constraints) for each device
// type, so a type's set of supported actions is its capability.
//
// Implementations must be safe for concurrent use, because the Manager may serve
// List/Control/Status from multiple goroutines.
type Provider interface {
	// Name returns the stable provider identifier, used for logging and to
	// disambiguate providers registered on one Manager.
	Name() string
	// List returns every device currently known to the provider.
	List(ctx context.Context) ([]Device, error)
	// Control applies action with params to the named device and returns the
	// post-transition device. It returns ErrDeviceNotFound for an unknown device
	// and ErrUnsupported for an action the device's type does not support.
	Control(ctx context.Context, deviceID, action string, params map[string]any) (*Device, error)
	// Status returns the current state of the named device. It returns
	// ErrDeviceNotFound when the device is unknown.
	Status(ctx context.Context, deviceID string) (*Device, error)
}