controller

type AuthConfig struct {
	BaseURL       string
	Username      string
	Password      string
	APIKey        string
	ReauthTimeout time.Duration
	ReauthMinGap  time.Duration
}

type ClientConfig struct {
	BaseURL      string
	Username     string
	Password     string
	APIKey       string
	VerifyTLS    bool
	CACertPath   string
	Timeout      time.Duration
	Debug        bool
	ReauthMinGap time.Duration // thundering-herd guard: skip re-auth if last one was < this ago
	EnableIPv6   bool          // dial IPv6 — false by default, set true only with working IPv6 path
}

type Controller interface {
	// Firewall Groups (address lists) — legacy mode only
	ListFirewallGroups(ctx context.Context, site string) ([]FirewallGroup, error)
	CreateFirewallGroup(ctx context.Context, site string, g FirewallGroup) (FirewallGroup, error)
	UpdateFirewallGroup(ctx context.Context, site string, g FirewallGroup) error
	DeleteFirewallGroup(ctx context.Context, site string, id string) error

	// Legacy Rules (WAN_IN / WANv6_IN) — legacy mode only
	ListFirewallRules(ctx context.Context, site string) ([]FirewallRule, error)
	CreateFirewallRule(ctx context.Context, site string, r FirewallRule) (FirewallRule, error)
	UpdateFirewallRule(ctx context.Context, site string, r FirewallRule) error
	DeleteFirewallRule(ctx context.Context, site string, id string) error

	// Zone-Based Policies — integration v1
	ListZonePolicies(ctx context.Context, site string) ([]ZonePolicy, error)
	CreateZonePolicy(ctx context.Context, site string, p ZonePolicy) (ZonePolicy, error)
	UpdateZonePolicy(ctx context.Context, site string, p ZonePolicy) error
	DeleteZonePolicy(ctx context.Context, site string, id string) error
	GetPolicyOrdering(ctx context.Context, site, srcZoneID, dstZoneID string) (PolicyOrdering, error)
	SetPolicyOrdering(ctx context.Context, site, srcZoneID, dstZoneID string, ordering PolicyOrdering) error

	// Traffic Matching Lists — integration v1, zone mode only
	ListTrafficMatchingLists(ctx context.Context, site string) ([]TrafficMatchingList, error)
	CreateTrafficMatchingList(ctx context.Context, site string, list TrafficMatchingList) (TrafficMatchingList, error)
	UpdateTrafficMatchingList(ctx context.Context, site string, list TrafficMatchingList) error
	DeleteTrafficMatchingList(ctx context.Context, site string, id string) error

	// Site and Zone Resolution — integration v1
	GetSiteID(ctx context.Context, siteName string) (string, error)
	GetZoneID(ctx context.Context, site, zoneName string) (string, error)
	DiscoverZones(ctx context.Context, site string) ([]Zone, error)
	DiscoverSites(ctx context.Context) ([]string, error)

	// InvalidateZoneCache evicts all cached zone IDs, site IDs, and feature flags
	// for the given site. Call before re-resolving zone names to ensure fresh data.
	InvalidateZoneCache(site string)

	// Feature Detection
	HasFeature(ctx context.Context, site string, feature string) (bool, error)

	// Session
	Ping(ctx context.Context) error
	Close() error
}

type ErrConflict struct {
	Msg string
}

type ErrNotFound struct {
	URL string
}

type ErrRateLimit struct {
	RetryAfter time.Duration
}

type ErrUnauthorized struct {
	Msg string
}

type FirewallGroup struct {
	ID           string
	Name         string
	GroupType    string // "address-group" or "ipv6-address-group"
	GroupMembers []string
}

type FirewallRule struct {
	ID                  string
	Name                string
	Enabled             bool
	RuleIndex           int
	Action              string // "drop" or "reject"
	Ruleset             string // "WAN_IN", "WANv6_IN", etc.
	Description         string
	Logging             bool
	Protocol            string
	SrcFirewallGroupIDs []string
}

type PolicyOrdering struct {
	BeforeSystemDefined []string
	AfterSystemDefined  []string
}

type TrafficMatchingList struct {
	ID        string
	Type      string // "IPV4_ADDRESSES", "IPV6_ADDRESSES", "PORTS"
	Name      string
	GroupType string // legacy compat hint: "address-group", "ipv6-address-group"
	Items     []TrafficMatchingListItem
}

type TrafficMatchingListItem struct {
	Type  string `json:"-"` // "IP_ADDRESS", "SUBNET", "PORT_NUMBER"; omitted from JSON to match wire format
	Value string
}

type Zone struct {
	ID     string
	Name   string
	Origin string // metadata.origin from integration v1 API, e.g. "USER_DEFINED"
}

type ZonePolicy struct {
	ID                     string
	Name                   string
	Enabled                bool
	Action                 string // "BLOCK", "ALLOW", "REJECT"
	AllowReturnTraffic     bool   // only valid for ALLOW action
	Description            string
	SrcZone                string
	DstZone                string
	IPVersion              string   // "IPV4", "IPV6", "BOTH"
	TrafficMatchingListIDs []string // proxy API: source.ip_group_id (single ID)
	Predefined             bool     // true for built-in policies managed by UniFi
	ConnectionStateFilter  []string // e.g. ["NEW", "INVALID"]
	LoggingEnabled         bool
	SrcPortTMLID           string // TML of type "PORTS" for source port filter (empty = any)
	DstPortTMLID           string // TML of type "PORTS" for destination port filter (empty = any)
	DstIPTMLID             string // TML of type IPV4_ADDRESSES or IPV6_ADDRESSES for dst IP filter (empty = any)
}