audit

type Event struct {
	ID         string
	OccurredAt time.Time
	Operation  string
	Actor      domain.Identity
	OrgID      string
	GroupID    string
	ActionData map[string]any
}

type EventRepository interface {
	// SaveEvent persists a single event to the database.
	SaveEvent(ctx context.Context, e Event) error

	// RetrieveEvents retrieves events from the database
	RetrieveEvents(ctx context.Context, pm PageMetadata) (EventsPage, error)

	// RetrieveEventsByOrg retrieves events belonging to a specific organization from the database
	RetrieveEventsByOrg(ctx context.Context, orgID string, pm PageMetadata) (EventsPage, error)

	// RetrieveEventsByGroup retrieves events belonging to a specific group from the database
	RetrieveEventsByGroup(ctx context.Context, groupID string, pm PageMetadata) (EventsPage, error)
}

type EventsPage struct {
	Total  uint64  `json:"total"`
	Events []Event `json:"events"`
}

type PageMetadata struct {
	Total      uint64         `json:"total,omitempty"`
	Offset     uint64         `json:"offset,omitempty"`
	Limit      uint64         `json:"limit,omitempty"`
	Order      string         `json:"order,omitempty"`
	Dir        string         `json:"dir,omitempty"`
	Email      string         `json:"email,omitempty"`
	Operation  string         `json:"operation,omitempty"`
	ActionData map[string]any `json:"action_data,omitempty"`
	From       time.Time      `json:"from,omitzero"`
	To         time.Time      `json:"to,omitzero"`
}

type Service interface {
	// RecordEvent records a single event.
	RecordEvent(ctx context.Context, e events.Event) error

	// ListEvents retrieves a list of audit events across all organizations.
	// The user authenticated by `token` must be a platform (root) admin.
	ListEvents(ctx context.Context, token string, pm PageMetadata) (EventsPage, error)

	// ListEventsByOrg retrieves a list of audit events occurred in a specific organization denoted by its ID.
	// The user authenticated by `token` must possess "admin" or higher privileges within the target organization.
	ListEventsByOrg(ctx context.Context, token string, orgID string, pm PageMetadata) (EventsPage, error)

	// ListEventsByGroup retrieves a list of audit events occurred in a specific group denoted by its ID.
	// The user authenticated by `token` must possess "admin" or higher privileges within the target group.
	ListEventsByGroup(ctx context.Context, token string, groupID string, pm PageMetadata) (EventsPage, error)
}