// Package telemetry implements the KeyCape telemetry pipeline (spec §6).
// Every auth and error code path MUST call Emit — there are no silent paths.
package telemetry

import "time"

// EventType identifies the category of a telemetry event.
type EventType string

const (
	EventAuthStart          EventType = "auth_start"
	EventAuthSuccess        EventType = "auth_success"
	EventAuthFailure        EventType = "auth_failure"
	EventTokenIssued        EventType = "token_issued"
	EventUnsupportedFeature EventType = "unsupported_feature"
	EventInvalidRequest     EventType = "invalid_request"
	EventMigration          EventType = "migration_event"
)

// Event carries all required telemetry fields from spec §6.2.
// Timestamp, Environment, TraceID, ClientID, Endpoint, Result, and EventType
// are mandatory for every event; other fields are conditional on context.
type Event struct {
	Timestamp   time.Time `json:"timestamp"`
	ClientID    string    `json:"client_id"`
	Endpoint    string    `json:"endpoint"`
	Feature     string    `json:"feature,omitempty"`
	Result      string    `json:"result"` // "success" | "failure"
	ErrorType   string    `json:"error_type,omitempty"`
	Scopes      []string  `json:"scopes,omitempty"`
	GrantType   string    `json:"grant_type,omitempty"`
	Environment string    `json:"environment"`
	TraceID     string    `json:"trace_id"`
	EventType   EventType `json:"event_type"`
}