history

type Action struct {
	Description    string // e.g. "Cancel item Sword-Pack"
	ButtonText     string // e.g. "Cancel"
	Endpoint       string // e.g. "/orders/backoffice/v1/orders/123/items/1/cancel"
	ConfirmMessage string // optional confirmation prompt; empty = submit immediately
	StatusText     string // non-empty = show label instead of button

	// true renders a link to Endpoint instead of a form, for an action that only
	// navigates. Ignores ConfirmMessage.
	Link bool

	// RequiredRole gates the whole action: "write" or "admin" means that role on
	// this service's own audience, "payment-service:admin" names another
	// audience. Empty means always shown. A viewer who may not perform the action
	// does not see it at all - a disabled button still tells a read-only user
	// which endpoint to curl.
	RequiredRole string
}

type AthenaConfig struct {
	// required Athena configuration
	Database       string
	Table          string
	WorkGroup      string
	OutputLocation string

	// optional AWS region
	Region string

	// LookupThreshold selects Athena over the local table once the tracked
	// object is older than this. Defaults to 24h when zero.
	LookupThreshold time.Duration

	// LookbackMargin is subtracted from the object creation time to form the
	// Athena query's MinTimestamp, bounding the scanned partitions. Defaults
	// to 30m when zero.
	LookbackMargin time.Duration
}

type AthenaQuery struct {
	GroupId GroupId

	// required athena configuration
	Database       string
	Table          string
	WorkGroup      string
	OutputLocation *url.URL

	// Optional region
	Region string

	// optional values to reduce the amount of data that
	// the query needs to scan. Either value can be left empty to
	MinTimestamp *time.Time
	MaxTimestamp *time.Time
}

type Cleanup struct {
	Interval time.Duration
	Jitter   time.Duration
	MaxAge   time.Duration
}

type EventCreator func(serviceId, serviceVersion string, rec RecordToSend) events.Event

type EventSender = events.EventSender

type EventSending struct {
	// EventSender sends the events created by EventCreator.
	EventSender EventSender
	// EventCreator builds the event that is sent for a tracked record.
	EventCreator EventCreator

	// ServiceId and ServiceVersion identify the sender of the events. If left
	// empty, they are loaded from the SERVICE_ID and SERVICE_VERSION environment
	// variables in New.
	ServiceId      string
	ServiceVersion string

	// Write events to the kafka outbox first. If false, events are sent async.
	WriteToOutbox bool
}

type FilterOption struct {
	Value string
	Label string
}

type GroupId struct {
	// GroupType is the logical type of a tracked object (e.g. "order", "player").
	// It disambiguates a Id so different object types can reuse the same id
	// space without colliding.
	// Must not be empty
	Type string

	// Must not be empty
	Id string
}

type GroupIds []GroupId

type Item interface {
	// HistoryString returns a human-readable description of this trace.Item.
	HistoryString() string
}

type Option func(*Service)

type Options struct {
	// DB starts the transactions used to create the table and to write records.
	DB ql.TxStarter

	// ServiceId identifies this service as the sender of the emitted events.
	ServiceId string
	// HistoryTable is the name of the table that history records are written to.
	HistoryTable string
	// EventCreator builds the event that is sent out for every tracked record.
	EventCreator EventCreator
	// Athena, when set, enables the Athena read fallback for old records
	// (see WithAthena and Service.RecordsAt).
	Athena *AthenaConfig
}

type OverviewConfig struct {
	Title     string
	Headers   []string
	Rows      []OverviewRow
	Filters   []OverviewFilter
	ScopeNote string

	// Page is the 1-based page number shown; 0 and 1 both mean the first page.
	// HasNext tells the pager that another page exists - the caller knows this by
	// loading one row more than it displays, so no count query is needed.
	Page    int
	HasNext bool
}

type OverviewFilter struct {
	Label       string
	Name        string
	Value       string
	Placeholder string
	// Type is the HTML input type; empty means "text". "date" gets the browser's
	// own date picker, no JavaScript needed.
	Type string
	// Options, when non-empty, renders a <select> instead of an input. The empty
	// value must be part of the list to allow "no filter".
	Options []FilterOption
	// Hidden keeps the value in the form and in the pagination links without
	// showing a control - for a filter the page receives from elsewhere (a deep
	// link carrying a player id) rather than one the viewer types.
	Hidden bool
}

type OverviewModel struct {
	Title   string
	Headers []string
	Rows    []OverviewRow
	// Filters renders a GET form above the table; empty means no form. Only
	// free filters belong here (a player id, a request id). Tenant scope
	// (operator, shop) travels as a header set by backoffice, never as a form
	// field a viewer can retype.
	Filters []OverviewFilter
	// ScopeNote is one line naming the scope the rows were loaded with (e.g.
	// "operator bmh-audio-pt, all shops"), so the viewer sees why the list is
	// short.
	ScopeNote string

	// Page is the 1-based page currently shown; PrevLink/NextLink are empty when
	// there is no such page.
	Page     int
	PrevLink string
	NextLink string
}

type OverviewRow struct {
	Link  string
	Cells []string
}

type PageConfig struct {
	Summary   []SummaryItem
	Actions   []Action
	CreatedAt time.Time // zero = local-only, non-zero = Athena fallback

	// Viewer overrides the identity used for RequiredRole gating. Normally the
	// identity comes from the request context; set this when rendering outside a
	// request (a test, a report). No viewer at all means every gated element is
	// omitted - fail closed.
	Viewer *jwt.Identity
}

type PageModel struct {
	Title        string
	GroupType    string
	GroupId      string
	ErrorMessage string
	Summary      []SummaryItem
	Actions      []Action
	Records      []RecordView
}

type Record struct {
	Timestamp      time.Time       `db:"timestamp"`
	RequestTraceId RequestTraceId  `db:"request_trace_id"`
	Step           string          `db:"step"`
	Description    string          `db:"description"`
	Payload        json.RawMessage `db:"payload"`
	Trigger        Trigger         `db:"trigger"`

	// Optional field that might indicate the sender of an event. This is useful if the
	// event comes from an external source, e.g. athena.
	// For local data, it is set to either the serviceId or to `local`, if no serviceId
	// is specified.
	EventSender        string `db:"-"`
	EventSenderVersion string `db:"-"`
}

type RecordToSend struct {
	GroupIds       GroupIds
	Timestamp      time.Time
	Step           string
	Description    string
	Payload        json.RawMessage
	RequestTraceId RequestTraceId
	Trigger        Trigger
}

type RecordView struct {
	Record
	// JSON is the indented payload.
	JSON string
	// ShowSeparator is true when this record starts a new RequestTraceId group.
	ShowSeparator bool
}

type RequestTraceId struct {
	// contains filtered or unexported fields
}

type Service struct {
	// contains filtered or unexported fields
}

type SummaryItem struct {
	Label string
	Value string
	// Link, when non-empty, renders Value as an <a href> to this URL instead of
	// plain text - e.g. a cross-service backoffice link to the page that owns the
	// referenced entity (a payment or draw history page behind the api-gateway).
	Link string

	// RequiredRole gates the Link only, in the same notation as
	// Action.RequiredRole. A denied item still shows Label and Value, just not as
	// an anchor: the value itself is not the secret, the page behind it is.
	RequiredRole string
}

type Trigger struct {
	Source  string `json:"source"`            // e.g. http, message-broker, scheduler
	Detail  string `json:"detail,omitempty"`  // e.g. "POST /checkout", "topic payment_captured"
	RefType string `json:"refType,omitempty"` // kind of the source id, e.g. requestId, kafkaEventId
	Ref     string `json:"ref,omitempty"`     // the source id value (request/event this entry came from)

	// Actor is who initiated the work, filled from the context by triggerOf when
	// the caller did not set it. No migration: trigger is a JSON column and the
	// event field is a JSON string, so an older reader just ignores the key.
	Actor actor.Actor `json:"actor,omitzero"`
}