settings

type ChangeEvent struct {
	Key      string          `json:"key"`
	Scope    Scope           `json:"scope"`
	ScopeID  string          `json:"scope_id"`
	AppID    string          `json:"app_id"`
	OrgID    string          `json:"org_id"`
	Enforced bool            `json:"enforced"`
	OldValue json.RawMessage `json:"old_value,omitempty"`
	NewValue json.RawMessage `json:"new_value"`
}

type ChangeListener func(event ChangeEvent)

type DefOption func(*Definition)

type Definition struct {
	// Key is the unique dot-separated key, e.g. "password.min_length".
	Key string `json:"key"`

	// DisplayName is the human-readable label for UI surfaces.
	DisplayName string `json:"display_name"`

	// Description explains what this setting controls.
	Description string `json:"description"`

	// Type is the JSON schema type of the value.
	Type ValueType `json:"type"`

	// Default is the JSON-encoded default value (the "code default" in the cascade).
	Default json.RawMessage `json:"default"`

	// Scopes lists which scopes this setting can be overridden at.
	// An empty slice means only global.
	Scopes []Scope `json:"scopes"`

	// Enforceable marks this setting as lockable at higher scopes.
	// When enforced, lower scopes cannot override the value.
	Enforceable bool `json:"enforceable"`

	// Sensitive marks values that should be redacted in API responses.
	Sensitive bool `json:"sensitive"`

	// Validate is an optional validation function that receives the raw JSON
	// value and returns an error if the value is invalid. Called at write time.
	Validate func(value json.RawMessage) error `json:"-"`

	// Category groups related settings in UI displays.
	Category string `json:"category"`

	// Namespace is the owning plugin name (auto-set at registration).
	Namespace string `json:"namespace"`

	// UI holds rendering metadata for auto-generated settings forms.
	// When non-nil, the dashboard can auto-render this setting.
	UI *UIMetadata `json:"ui,omitempty"`
}

type DefinitionTyped[T any] struct {
	Def Definition
}

type EnforcementProvider interface {
	// EnforcementRules returns the current enforcement rules.
	// Called during settings resolution to check for forced values.
	EnforcementRules(ctx context.Context) ([]EnforcementRule, error)
}

type EnforcementRule struct {
	// Key is the setting key to enforce.
	Key string `json:"key"`

	// Value is the enforced value (JSON-encoded).
	Value json.RawMessage `json:"value"`

	// Scope is the scope at which enforcement applies.
	Scope Scope `json:"scope"`

	// ScopeID is the target scope ID (empty for global).
	ScopeID string `json:"scope_id"`

	// Reason explains why this enforcement exists (e.g., "SOC2 compliance").
	Reason string `json:"reason"`

	// Source is the plugin that created this rule.
	Source string `json:"source"`
}

type ListOpts struct {
	Limit     int
	Offset    int
	Namespace string
	Scope     Scope
	ScopeID   string
	AppID     string
	OrgID     string
}

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

type ManagerOption func(*Manager)

type NilStore struct{}

type ObjectFieldDef struct {
	// Key is the JSON field name (must match the struct's json tag).
	Key string `json:"key"`

	// DisplayName is the human-readable label.
	DisplayName string `json:"display_name"`

	// InputType is the form field type for this nested field.
	InputType formconfig.FieldType `json:"input_type"`

	// Placeholder is placeholder text for the input.
	Placeholder string `json:"placeholder,omitempty"`

	// Required marks this field as mandatory within each object.
	Required bool `json:"required,omitempty"`

	// Sensitive marks this field as a secret (renders as password input).
	Sensitive bool `json:"sensitive,omitempty"`

	// Options lists choices if InputType is select.
	Options []formconfig.SelectOption `json:"options,omitempty"`

	// HelpText is descriptive text shown below the nested input.
	HelpText string `json:"help_text,omitempty"`
}

type ResolveOpts struct {
	AppID  string
	OrgID  string
	UserID string
}

type ResolvedSetting struct {
	// Definition is the full setting definition including UI metadata.
	Definition *Definition `json:"definition"`

	// EffectiveValue is the final resolved value after cascade + enforcement.
	EffectiveValue json.RawMessage `json:"effective_value"`

	// ScopeValues lists the value at each scope that has an override.
	// Ordered from least specific (global) to most specific (user).
	ScopeValues []ScopeValue `json:"scope_values"`

	// CanOverride is true if the current scope context allows setting a value.
	// False when a higher scope has this setting enforced.
	CanOverride bool `json:"can_override"`

	// EnforcedAt is the scope that has this setting locked, if any.
	EnforcedAt *Scope `json:"enforced_at,omitempty"`
}

type Scope string

type ScopeValue struct {
	// Scope is the specificity level (global, app, org, user).
	Scope Scope `json:"scope"`

	// ScopeID is the ID of the entity at this scope (app ID, org ID, user ID).
	ScopeID string `json:"scope_id,omitempty"`

	// Value is the JSON-encoded setting value at this scope.
	Value json.RawMessage `json:"value"`

	// Enforced indicates whether this scope has the value locked.
	Enforced bool `json:"enforced"`

	// Version is the setting version at this scope.
	Version int64 `json:"version,omitempty"`

	// UpdatedBy is who last changed the value at this scope.
	UpdatedBy string `json:"updated_by,omitempty"`

	// UpdatedAt is when the value was last changed at this scope.
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

type Setting struct {
	ID        id.SettingID    `json:"id"`
	Key       string          `json:"key"`
	Value     json.RawMessage `json:"value"`
	Scope     Scope           `json:"scope"`
	ScopeID   string          `json:"scope_id"`
	AppID     string          `json:"app_id"`
	OrgID     string          `json:"org_id"`
	Enforced  bool            `json:"enforced"`
	Namespace string          `json:"namespace"`
	Version   int64           `json:"version"`
	UpdatedBy string          `json:"updated_by"`
	CreatedAt time.Time       `json:"created_at"`
	UpdatedAt time.Time       `json:"updated_at"`
}

type Store interface {
	// GetSetting retrieves a single setting by key + scope + scope_id.
	// Returns ErrNotFound if no setting exists for the given combination.
	GetSetting(ctx context.Context, key string, scope Scope, scopeID string) (*Setting, error)

	// SetSetting creates or updates a setting. Upsert semantics on (key, scope, scope_id).
	SetSetting(ctx context.Context, s *Setting) error

	// DeleteSetting removes a specific setting override.
	DeleteSetting(ctx context.Context, key string, scope Scope, scopeID string) error

	// ListSettings returns all settings matching the filter.
	ListSettings(ctx context.Context, opts ListOpts) ([]*Setting, error)

	// ResolveSettings performs cascade lookup for a key across all scopes.
	// Returns all matching settings ordered by specificity (global → app → org → user).
	// The Manager uses these to apply enforcement logic.
	ResolveSettings(ctx context.Context, key string, opts ResolveOpts) ([]*Setting, error)

	// BatchResolve resolves multiple keys at once for performance.
	// Returns a map of key → list of matching settings (ordered by specificity).
	BatchResolve(ctx context.Context, keys []string, opts ResolveOpts) (map[string][]*Setting, error)

	// DeleteSettingsByNamespace removes all settings for a given namespace.
	DeleteSettingsByNamespace(ctx context.Context, namespace string) error
}

type UIMetadata struct {
	// InputType is the form field type (text, number, switch, select, etc.).
	InputType formconfig.FieldType `json:"input_type"`

	// Placeholder is placeholder text for the input field.
	Placeholder string `json:"placeholder,omitempty"`

	// HelpText is descriptive text shown below the input field.
	HelpText string `json:"help_text,omitempty"`

	// Options lists choices for select/radio/checkbox fields.
	Options []formconfig.SelectOption `json:"options,omitempty"`

	// Validation defines client-side validation hints.
	Validation *formconfig.Validation `json:"validation,omitempty"`

	// Order controls display ordering within a category (lower = first).
	Order int `json:"order"`

	// ReadOnly marks the field as non-editable in the UI.
	ReadOnly bool `json:"read_only,omitempty"`

	// Condition defines conditional visibility based on another setting.
	Condition *VisibilityCondition `json:"condition,omitempty"`

	// Section is an optional sub-group label within a category.
	Section string `json:"section,omitempty"`

	// ObjectFields describes the schema for each object in an object_array field.
	// Only used when InputType is FieldObjectArray.
	ObjectFields []ObjectFieldDef `json:"object_fields,omitempty"`
}

type ValueType string

type VisibilityCondition struct {
	// Key is the setting key to evaluate.
	Key string `json:"key"`

	// Value is the expected value (JSON-encoded).
	Value json.RawMessage `json:"value"`

	// Operator is the comparison operator: "eq" (default), "ne", "in".
	Operator string `json:"operator,omitempty"`
}