errors

type Config struct {
	// Environment tags every reported event ("production", "staging",
	// "preview"). Sentry's UI groups + filters by this; webhook
	// receivers see it in the payload. Leave empty in tests.
	Environment string

	// Release tags every event with a version / commit hash so the
	// receiver can group "errors introduced in v1.4.2" without
	// guessing. Typical wiring is a Go ldflags-injected variable or
	// the GIT_SHA env var.
	Release string

	// ServerName tags every event with the host that captured it.
	// Useful when split deployments have multiple instances reporting
	// the same fingerprint — the receiver sees which instance fired.
	// Defaults to os.Hostname().
	ServerName string

	// Capacity is the in-memory ring-buffer size for the dashboard
	// view. Old events evict when full. Defaults to 100.
	Capacity int

	// SampleRate is the fraction of captured events forwarded to
	// transports. 1.0 = every error, 0.1 = 10%, 0.0 = none (still
	// captured for the dashboard). Useful in preview environments
	// where noisy errors aren't worth a Sentry quota burn.
	// Defaults to 1.0.
	SampleRate float64

	// IgnorePaths is a list of request paths whose errors are NOT
	// captured. Useful for health checks and admin surfaces that
	// would otherwise fill the ring buffer with noise.
	// Default: ["/__nexus/health", "/__nexus/ready"].
	IgnorePaths []string

	// Transports is the slice of receivers each captured error is
	// forwarded to. Empty = dashboard-only (no external reporting).
	// Transports run sequentially per event; one transport failing
	// doesn't block the others.
	Transports []Transport

	// Disabled, when true, makes the plugin a no-op. Useful in
	// environments where another error reporter is wired (or you
	// just don't want external reporting from preview).
	Disabled bool
}

type Event struct {
	// Fingerprint is the grouping key — same fingerprint = same
	// "issue". Combines request method + path + the top stack
	// frame so the dashboard can show "this 500 fired 47 times in
	// the last hour" as a single row.
	Fingerprint string `json:"fingerprint"`

	// CapturedAt is the moment the plugin received the event.
	// Distinct from the trace event's Timestamp (which is when
	// the underlying span ended) by usually <1ms; tracked for
	// completeness.
	CapturedAt time.Time `json:"capturedAt"`

	// Service / Endpoint / Method / Path / Status mirror what was
	// in the trace event. Carried into the captured event so
	// transports don't need a back-reference.
	Service  string `json:"service,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
	Method   string `json:"method,omitempty"`
	Path     string `json:"path,omitempty"`
	Status   int    `json:"status,omitempty"`

	// Error is the human-readable error message. Empty when the
	// event was captured purely on Status >= 500 (server emitted
	// 500 with no error in c.Errors).
	Error string `json:"error,omitempty"`

	// Stack is the cleaned panic stack (debug.Stack output after
	// trace.CleanStack stripping). Empty when the error wasn't a
	// panic (returned-error or manual 500).
	Stack string `json:"stack,omitempty"`

	// Environment / Release / ServerName are tagging fields the
	// receiver uses to filter + group across deploys. Mirror the
	// fields Sentry expects so the Sentry transport doesn't need a
	// separate model.
	Environment string `json:"environment,omitempty"`
	Release     string `json:"release,omitempty"`
	ServerName  string `json:"serverName,omitempty"`

	// TraceID lets the receiver link back to the full request
	// trace via the dashboard's /__nexus/traces/<id>. Surfaces in
	// the Sentry / webhook payload as a tag.
	TraceID string `json:"traceId,omitempty"`
}

type Issue struct {
	Fingerprint string    `json:"fingerprint"`
	Method      string    `json:"method,omitempty"`
	Path        string    `json:"path,omitempty"`
	Service     string    `json:"service,omitempty"`
	Endpoint    string    `json:"endpoint,omitempty"`
	Error       string    `json:"error"`
	Status      int       `json:"status,omitempty"`
	Count       int       `json:"count"`
	FirstSeen   time.Time `json:"firstSeen"`
	LastSeen    time.Time `json:"lastSeen"`
	Sample      *Event    `json:"sample,omitempty"`
}

type Transport interface {
	// Name is the human-readable label shown in the dashboard's
	// errors status panel. Kept distinct from any internal type
	// name so the wire payload can identify the transport without
	// reflecting on the Go type.
	Name() string

	// Report ships one captured Event somewhere. Best-effort; an
	// error return is logged at the call site but does not retry.
	Report(ctx context.Context, e Event) error
}

type WebhookOption func(*webhookTransport)