contract

type AuditSummary struct {
	ID       string `json:"id"`
	Action   string `json:"action"`
	Resource string `json:"resource"`
	Key      string `json:"key"`
	Outcome  string `json:"outcome"`
	TenantID string `json:"tenantId,omitempty"`
	UserID   string `json:"userId,omitempty"`
	// Error is the failure's message, read from the row's metadata. It is
	// empty on a success row and on a failure row that recorded none.
	Error     string `json:"error,omitempty"`
	CreatedAt string `json:"createdAt"`
}

type ConfigEntrySummary struct {
	ID    string `json:"id"`
	Key   string `json:"key"`
	Value any    `json:"value"`
	// ValueType is the label stored with the entry. The store keeps it as
	// free text, so it is not always one of the six the vault validates:
	// see KnownType.
	ValueType string `json:"valueType"`
	// KnownType is false for a label the vault does not validate (the templ
	// page's "yaml", say). Such an entry is readable but its value cannot be
	// judged, so ValueMatchesType is false for it as well.
	KnownType bool `json:"knownType"`
	// ValueMatchesType is false when the stored value is not a value of
	// ValueType, e.g. a string "abc" on an int entry.
	ValueMatchesType bool              `json:"valueMatchesType"`
	Version          int64             `json:"version"`
	Description      string            `json:"description"`
	Metadata         map[string]string `json:"metadata"`
	CreatedAt        string            `json:"createdAt"`
	UpdatedAt        string            `json:"updatedAt"`
}

type ConfigVersionSummary struct {
	Version          int64  `json:"version"`
	Value            any    `json:"value"`
	ValueMatchesType bool   `json:"valueMatchesType"`
	CreatedAt        string `json:"createdAt"`
	Current          bool   `json:"current"`
}

type Deps struct {
	// Vault is the composed vault. Required. Every handler operates on
	// Vault.AppID() and nothing else: no request carries an app id.
	Vault *vault.Vault

	// Logger receives an Error-level entry for every error a handler maps
	// to CodeInternal, so an operator can find out why a dashboard request
	// failed. Optional: nil means nothing is logged.
	Logger forge.Logger
}

type FlagOverrideSummary struct {
	TenantID         string `json:"tenantId"`
	Value            any    `json:"value"`
	ValueMatchesType bool   `json:"valueMatchesType"`
	UpdatedAt        string `json:"updatedAt"`
}

type FlagRuleSummary struct {
	ID       string `json:"id"`
	Priority int    `json:"priority"`
	Type     string `json:"type"`
	// Implemented is false for when_tenant_tag and custom: the engine never
	// matches them.
	Implemented bool     `json:"implemented"`
	TenantIDs   []string `json:"tenantIds"`
	UserIDs     []string `json:"userIds"`
	Percentage  int      `json:"percentage"`
	// StartAt and EndAt are UTC RFC3339, omitted for an open end.
	StartAt           *string        `json:"startAt,omitempty"`
	EndAt             *string        `json:"endAt,omitempty"`
	TagKey            string         `json:"tagKey,omitempty"`
	TagValue          string         `json:"tagValue,omitempty"`
	Evaluator         string         `json:"evaluator,omitempty"`
	Params            map[string]any `json:"params,omitempty"`
	ReturnValue       any            `json:"returnValue"`
	ReturnMatchesType bool           `json:"returnMatchesType"`
}

type FlagSummary struct {
	ID   string `json:"id"`
	Key  string `json:"key"`
	Type string `json:"type"`
	// DefaultValue is whatever is stored, which is not always a value of
	// Type: see DefaultMatchesType.
	DefaultValue any `json:"defaultValue"`
	// DefaultMatchesType is false when the stored default is not a value of
	// Type, e.g. the templ page's string "true" on a bool flag.
	DefaultMatchesType bool     `json:"defaultMatchesType"`
	Description        string   `json:"description"`
	Tags               []string `json:"tags"`
	Enabled            bool     `json:"enabled"`
	CreatedAt          string   `json:"createdAt"`
	UpdatedAt          string   `json:"updatedAt"`
}

type FlagTraceStep struct {
	RuleID   string `json:"ruleId"`
	Priority int    `json:"priority"`
	Type     string `json:"type"`
	Matched  bool   `json:"matched"`
	Reached  bool   `json:"reached"`
	Note     string `json:"note"`
}

type FlagVariantSummary struct {
	Value       any    `json:"value"`
	Description string `json:"description"`
}

type OverrideSummary struct {
	Key      string `json:"key"`
	TenantID string `json:"tenantId"`
	Value    any    `json:"value"`
	// ValueMatchesType is judged against the type of the key's entry, and is
	// false when the entry no longer exists.
	ValueMatchesType bool `json:"valueMatchesType"`
	// KeyExists is false for an orphan: an override whose config entry is
	// gone. It still resolves for its tenant, because the resolver returns
	// an override before it reads the entry. Deleting the key normally
	// removes the overrides with it, so an orphan is an older or foreign
	// write, and overrides.delete can remove it.
	KeyExists bool   `json:"keyExists"`
	UpdatedAt string `json:"updatedAt"`
}

type RotationPolicySummary struct {
	ID              string `json:"id"`
	SecretKey       string `json:"secretKey"`
	IntervalSeconds int64  `json:"intervalSeconds"`
	Enabled         bool   `json:"enabled"`
	// Rotatable reports whether an application has registered a rotator
	// for this key. A policy without one will never rotate, however due it
	// gets: the loop logs an error every minute and changes nothing.
	Rotatable      bool    `json:"rotatable"`
	LastRotatedAt  *string `json:"lastRotatedAt,omitempty"`
	NextRotationAt *string `json:"nextRotationAt,omitempty"` // omitted when disabled
	CreatedAt      string  `json:"createdAt"`
	UpdatedAt      string  `json:"updatedAt"`
}

type RotationRecordSummary struct {
	ID         string `json:"id"`
	OldVersion int64  `json:"oldVersion"`
	NewVersion int64  `json:"newVersion"`
	RotatedBy  string `json:"rotatedBy,omitempty"`
	RotatedAt  string `json:"rotatedAt"`
}

type SecretSummary struct {
	ID      string `json:"id"`
	Key     string `json:"key"`
	Version int64  `json:"version"`
	// EncryptionAlg names the algorithm the stored value was encrypted
	// with. It has no omitempty: an empty string must reach the client as
	// "", because absence and "not encrypted" must not be confusable, and
	// "" is what every row written by an unconfigured Vault produces.
	EncryptionAlg string            `json:"encryptionAlg"`
	ExpiresAt     *string           `json:"expiresAt,omitempty"` // RFC3339
	AppID         string            `json:"appId"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	CreatedAt     string            `json:"createdAt"`
	UpdatedAt     string            `json:"updatedAt"`
}

type SecretVersionSummary struct {
	ID        string `json:"id"`
	Version   int64  `json:"version"`
	CreatedBy string `json:"createdBy,omitempty"`
	CreatedAt string `json:"createdAt"`
	// Encryption is "encrypted", "plaintext", or "unknown" for a version
	// written before versions recorded how they were stored and not yet
	// classified.
	Encryption string `json:"encryption"`
}