api

type APIKeyInfo struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"`
	KeyPrefix   string       `json:"key_prefix"` // First 8 chars for display
	Permissions []Permission `json:"permissions,omitempty"`
	ExpiresAt   string       `json:"expires_at,omitempty"`
	CreatedAt   string       `json:"created_at"`
	LastUsedAt  string       `json:"last_used_at,omitempty"`
	IsActive    bool         `json:"is_active"`
}

type AccountServiceOverrideRequest struct {
	Enabled        *bool    `json:"enabled,omitempty"`
	Term           *int     `json:"term,omitempty"`
	Payment        *string  `json:"payment,omitempty"`
	Coverage       *float64 `json:"coverage,omitempty"`
	RampSchedule   *string  `json:"ramp_schedule,omitempty"`
	IncludeEngines []string `json:"include_engines,omitempty"`
	ExcludeEngines []string `json:"exclude_engines,omitempty"`
	IncludeRegions []string `json:"include_regions,omitempty"`
	ExcludeRegions []string `json:"exclude_regions,omitempty"`
	IncludeTypes   []string `json:"include_types,omitempty"`
	ExcludeTypes   []string `json:"exclude_types,omitempty"`
}

type AccountSummary struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	ExternalID string `json:"external_id"`
	Provider   string `json:"provider"`
}

type AccountTestResult struct {
	OK      bool   `json:"ok"`
	Message string `json:"message"`
}

type AdminExistsResponse struct {
	AdminExists bool `json:"admin_exists"`
}

type AnalyticsClientInterface interface {
	QueryHistory(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, provider string, start, end time.Time, interval string) ([]HistoryDataPoint, *HistorySummary, error)
	QueryBreakdown(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, start, end time.Time, dimension string) (map[string]BreakdownValue, error)
}

type AnalyticsCollectorInterface interface {
	Collect(ctx context.Context) error
}

type AnalyticsResponse struct {
	Start      string             `json:"start"`
	End        string             `json:"end"`
	Interval   string             `json:"interval"`
	Summary    *HistorySummary    `json:"summary"`
	DataPoints []HistoryDataPoint `json:"data_points"`
}

type AnalyticsSnapshotStoreInterface interface {
	QuerySavings(ctx context.Context, req analytics.QueryRequest) ([]analytics.SavingsSnapshot, error)
	QueryMonthlyTotals(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, months int) ([]analytics.MonthlySummary, error)
	QueryByProvider(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, startDate, endDate time.Time) ([]analytics.ProviderBreakdown, error)
	QueryByService(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, provider string, startDate, endDate time.Time) ([]analytics.ServiceBreakdown, error)
}

type AuthLevel int

type AuthServiceInterface interface {
	Login(ctx context.Context, req LoginRequest) (*LoginResponse, error)
	Logout(ctx context.Context, token string) error
	ValidateSession(ctx context.Context, token string) (*Session, error)
	ValidateCSRFToken(ctx context.Context, sessionToken, csrfToken string) error
	SetupAdmin(ctx context.Context, req SetupAdminRequest) (*LoginResponse, error)
	CheckAdminExists(ctx context.Context) (bool, error)
	RequestPasswordReset(ctx context.Context, email string) error
	ConfirmPasswordReset(ctx context.Context, req PasswordResetConfirm) error
	// ResetTokenStatus returns the runtime state of a reset token
	// without consuming it. Used by the GET /api/auth/reset-password/
	// status endpoint so the frontend can branch on expired / used
	// tokens before rendering the reset-password form (issues #460,
	// #461). state is one of "valid" | "expired" | "used"; flow is
	// "reset" | "invite".
	ResetTokenStatus(ctx context.Context, token string) (state string, flow string, err error)
	GetUser(ctx context.Context, userID string) (*User, error)
	UpdateUserProfile(ctx context.Context, userID string, email string, currentPassword string, newPassword string) error
	// User management - uses auth.API* types
	CreateUserAPI(ctx context.Context, req any) (any, error)
	UpdateUserAPI(ctx context.Context, actorUserID, userID string, req any) (any, error)
	DeleteUser(ctx context.Context, userID string) error
	ListUsersAPI(ctx context.Context) (any, error)
	ChangePasswordAPI(ctx context.Context, userID, currentPassword, newPassword string) error
	// MFA lifecycle (issue #497). All four require the user to be
	// already authenticated; setup + disable additionally require a
	// fresh password re-verify carried in the request body.
	MFASetupAPI(ctx context.Context, userID, password string) (secret, provisioningURI string, err error)
	MFAEnableAPI(ctx context.Context, userID, code string) (recoveryCodes []string, err error)
	MFADisableAPI(ctx context.Context, userID, password, codeOrRecovery string) error
	MFARegenerateRecoveryCodesAPI(ctx context.Context, userID, code string) (recoveryCodes []string, err error)
	// Group management - uses auth.API* types
	CreateGroupAPI(ctx context.Context, req any) (any, error)
	UpdateGroupAPI(ctx context.Context, groupID string, req any) (any, error)
	DeleteGroup(ctx context.Context, groupID string) error
	GetGroupAPI(ctx context.Context, groupID string) (any, error)
	ListGroupsAPI(ctx context.Context) (any, error)
	// Permission checking
	HasPermissionAPI(ctx context.Context, userID, action, resource string) (bool, error)
	// HasPermissionForConstraintsAPI checks action on resource against
	// request-derived constraint sets so per-permission Constraints
	// (MaxPurchaseAmount, Providers, Services, Regions, AccountIDs) are
	// enforced at execution time. Every constraint set must be granted by
	// at least one of the user's permissions (SEC-01, issue #1141).
	HasPermissionForConstraintsAPI(ctx context.Context, userID, action, resource string, constraintSets []auth.PermissionConstraints) (bool, error)
	// GetUserPermissionsAPI returns the effective permission set for a user
	// (union of all group permissions). Used by GET /api/auth/me/permissions.
	// Returns []auth.APIPermission converted to []PermissionEntry by the handler.
	GetUserPermissionsAPI(ctx context.Context, userID string) (any, error)
	// Account access - returns the union of allowed_accounts from all user groups (empty = all access)
	GetAllowedAccountsAPI(ctx context.Context, userID string) ([]string, error)
	// API Key management
	CreateAPIKeyAPI(ctx context.Context, userID string, req any) (any, error)
	ListUserAPIKeysAPI(ctx context.Context, userID string) (any, error)
	DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error
	RevokeAPIKeyAPI(ctx context.Context, userID, keyID string) error
	ValidateUserAPIKeyAPI(ctx context.Context, apiKey string) (any, any, error)
}

type BreakdownResponse struct {
	Dimension string                    `json:"dimension"`
	Start     string                    `json:"start"`
	End       string                    `json:"end"`
	Data      map[string]BreakdownValue `json:"data"`
}

type BreakdownValue struct {
	TotalSavings  float64 `json:"total_savings"`
	TotalUpfront  float64 `json:"total_upfront"`
	PurchaseCount int     `json:"purchase_count"`
	Percentage    float64 `json:"percentage"`
}

type ChangePasswordRequest struct {
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password"`
}

type CloudAccountRequest struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	ContactEmail string `json:"contact_email"`
	Provider     string `json:"provider"`
	ExternalID   string `json:"external_id"`
	Enabled      *bool  `json:"enabled"`
	// AWS
	AWSAuthMode             string `json:"aws_auth_mode"`
	AWSRoleARN              string `json:"aws_role_arn"`
	AWSExternalID           string `json:"aws_external_id"`
	AWSBastionID            string `json:"aws_bastion_id"`
	AWSWebIdentityTokenFile string `json:"aws_web_identity_token_file"`
	AWSIsOrgRoot            bool   `json:"aws_is_org_root"`
	// Azure
	AzureSubscriptionID string `json:"azure_subscription_id"`
	AzureTenantID       string `json:"azure_tenant_id"`
	AzureClientID       string `json:"azure_client_id"`
	AzureAuthMode       string `json:"azure_auth_mode"`
	// GCP
	GCPProjectID   string `json:"gcp_project_id"`
	GCPClientEmail string `json:"gcp_client_email"`
	GCPAuthMode    string `json:"gcp_auth_mode"`
	GCPWIFAudience string `json:"gcp_wif_audience"` // Full WIF provider resource, secret-free path only.
}

type CommitmentOptsInterface interface {
	Get(ctx context.Context) (commitmentopts.Options, error)
	Validate(ctx context.Context, provider, service string, term int, payment string) (bool, error)
}

type ConfigResponse struct {
	Global         *config.GlobalConfig   `json:"global"`
	Services       []config.ServiceConfig `json:"services"`
	SourceCloud    string                 `json:"source_cloud,omitempty"`
	SourceIdentity *sourceIdentity        `json:"source_identity,omitempty"`
}

type ConvertibleRIsResponse struct {
	Instances []ec2svc.ConvertibleRI `json:"instances"`
}

type CoverageBreakdownResponse struct {
	Providers []ProviderCoverageSection `json:"providers"`
}

type CoverageServiceRow struct {
	Service         string   `json:"service"`
	CoveredMonthly  float64  `json:"covered_monthly"`
	OnDemandMonthly float64  `json:"on_demand_monthly"`
	CoveragePct     *float64 `json:"coverage_pct"`
}

type CreateAPIKeyRequest struct {
	Name        string       `json:"name"`
	Permissions []Permission `json:"permissions,omitempty"`
	ExpiresAt   *time.Time   `json:"expires_at,omitempty"`
}

type CreateAPIKeyResponse struct {
	APIKey string      `json:"api_key"` // Full key - only returned on creation
	KeyID  string      `json:"key_id"`
	Info   *APIKeyInfo `json:"info"`
}

type CreateGroupRequest struct {
	Name            string       `json:"name"`
	Description     string       `json:"description,omitempty"`
	Permissions     []Permission `json:"permissions"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
}

type CreatePlannedPurchasesRequest struct {
	Count     int    `json:"count"`
	StartDate string `json:"start_date"`
}

type CreatePlannedPurchasesResponse struct {
	Created int `json:"created"`
}

type CreateUserRequest struct {
	Email    string   `json:"email"`
	Password string   `json:"password"`
	Groups   []string `json:"groups,omitempty"`
}

type CredentialsRequest struct {
	CredentialType string                 `json:"credential_type"`
	Payload        map[string]interface{} `json:"payload"`
}

type CurrentUserResponse struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
}

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

type DashboardSummaryResponse struct {
	PotentialMonthlySavings float64                   `json:"potential_monthly_savings"`
	TotalRecommendations    int                       `json:"total_recommendations"`
	ActiveCommitments       int                       `json:"active_commitments"`
	CommittedMonthly        float64                   `json:"committed_monthly"`
	CurrentCoverage         float64                   `json:"current_coverage"`
	TargetCoverage          float64                   `json:"target_coverage"`
	YTDSavings              float64                   `json:"ytd_savings"`
	ByService               map[string]ServiceSavings `json:"by_service"`
}

type DeploymentInfoResponse struct {
	// APIKeySecretURL is the AWS Console deep-link to the Secrets Manager
	// secret holding the CUDly API key.
	APIKeySecretURL string `json:"api_key_secret_url,omitempty"`
	// DeploymentAWSAccountID is the AWS account ID of the Lambda host,
	// resolved via STS GetCallerIdentity. Empty on non-AWS deployments
	// or when STS is unreachable. Used by the frontend to distinguish
	// legitimate ambient-credential executions from orphan rows (#608).
	DeploymentAWSAccountID string `json:"deployment_aws_account_id,omitempty"`
}

type DiscoverOrgRequest struct {
	AccountID string `json:"account_id"`
}

type DiscoverOrgResult struct {
	Discovered int `json:"discovered"`
	Created    int `json:"created"`
	Skipped    int `json:"skipped"`
}

type EmptyServiceConfigResponse struct{}

type ExchangeExecuteRequestBody struct {
	RIIDs            []string             `json:"ri_ids"`
	Targets          []ExchangeTargetBody `json:"targets,omitempty"`
	TargetOfferingID string               `json:"target_offering_id,omitempty"`
	TargetCount      int32                `json:"target_count,omitempty"`
	MaxPaymentDueUSD string               `json:"max_payment_due_usd"`
	Region           string               `json:"region,omitempty"`
}

type ExchangeExecuteResponse struct {
	ExchangeID string                         `json:"exchange_id"`
	Quote      *exchange.ExchangeQuoteSummary `json:"quote"`
}

type ExchangeQuoteRequestBody struct {
	RIIDs            []string             `json:"ri_ids"`
	Targets          []ExchangeTargetBody `json:"targets,omitempty"`
	TargetOfferingID string               `json:"target_offering_id,omitempty"`
	TargetCount      int32                `json:"target_count,omitempty"`
	Region           string               `json:"region,omitempty"`
}

type ExchangeTargetBody struct {
	OfferingID string `json:"offering_id"`
	Count      int32  `json:"count"`
}

type ExchangeableAzureRIsResponse struct {
	Reservations []azurecompute.ExchangeableReservation `json:"reservations"`
}

type ExecutePurchaseRequest struct {
	Recommendations []config.RecommendationRecord `json:"recommendations"`
	// CapacityPercent is what fraction (1..100) of the originally-
	// recommended counts the user chose in the bulk Purchase flow.
	// Audit-only: the Recommendations slice already carries scaled
	// counts, so backend math ignores this field for purchase work.
	// 0 / absent defaults to 100 ("full capacity").
	CapacityPercent int `json:"capacity_percent,omitempty"`
	// ExecuteMode controls whether this request bypasses the approval
	// email and executes the purchase immediately. The only accepted
	// non-empty value is "direct"; any other value is treated as the
	// default approval-required flow. The handler re-checks the
	// execute-any/execute-own RBAC gate before honouring "direct",
	// even if the session already passed the execute:purchases gate in
	// validateExecutePurchaseRequest, so a client that sets this field
	// without the privilege receives a 403 rather than silent fallback.
	ExecuteMode string `json:"execute_mode,omitempty"`
}

type FederationIaCResponse struct {
	Filename        string `json:"filename"`
	Content         string `json:"content"`
	ContentType     string `json:"content_type"`
	ContentEncoding string `json:"content_encoding,omitempty"` // "base64" for binary (zip)
}

type Group struct {
	ID              string       `json:"id"`
	Name            string       `json:"name"`
	Description     string       `json:"description,omitempty"`
	Permissions     []Permission `json:"permissions"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
	CreatedAt       string       `json:"created_at,omitempty"`
	UpdatedAt       string       `json:"updated_at,omitempty"`
}

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

type HandlerConfig struct {
	ConfigStore       config.StoreInterface
	CredentialStore   credentials.CredentialStore
	PurchaseManager   PurchaseManagerInterface
	Scheduler         SchedulerInterface
	AuthService       AuthServiceInterface
	APIKeySecretARN   string
	EnableDashboard   bool
	DashboardBucket   string
	CORSAllowedOrigin string // CORS allowed origin (default "*")
	RateLimiter       RateLimiterInterface
	EmailNotifier     email.SenderInterface // Optional: used to send purchase approval emails
	DashboardURL      string                // Base URL for approval/cancel links in emails
	// Analytics configuration (optional)
	AnalyticsClient    AnalyticsClientInterface
	AnalyticsCollector AnalyticsCollectorInterface
	// AnalyticsSnapshots serves the savings-snapshot time-series (coverage %,
	// utilization, committed spend, realized savings over time) backed by the
	// savings_snapshots store. Optional; nil disables /api/analytics/trends.
	AnalyticsSnapshots AnalyticsSnapshotStoreInterface
	// OIDCSigner is the cloud-agnostic signer that backs
	// /.well-known/openid-configuration and /.well-known/jwks.json.
	// Nil disables the OIDC issuer endpoints (they return 404).
	OIDCSigner oidc.Signer
	// OIDCIssuerURL is the canonical issuer URL the OIDC handlers
	// publish in the Discovery document. Must match what Azure AD
	// federated credentials are registered with.
	OIDCIssuerURL string
	// CommitmentOpts discovers which (term, payment) combinations each
	// AWS service actually sells and validates saves against that data.
	// Nil disables both the /api/commitment-options endpoint (returns
	// unavailable) and save-side validation in updateServiceConfig.
	CommitmentOpts CommitmentOptsInterface
	// EncryptionKeySource is the env var name that resolved the credential
	// encryption key (e.g. "CREDENTIAL_ENCRYPTION_KEY_SECRET_NAME"). Empty
	// when no credStore is configured. Used by the /health endpoint to
	// surface which key source is in use and detect dev-key state.
	EncryptionKeySource string
}

type HealthCheck struct {
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

type HealthResponse struct {
	Status    string                 `json:"status"`
	Timestamp time.Time              `json:"timestamp"`
	Checks    map[string]HealthCheck `json:"checks"`
}

type HistoryDataPoint struct {
	Timestamp         time.Time          `json:"timestamp"`
	TotalSavings      float64            `json:"total_savings"`
	TotalUpfront      float64            `json:"total_upfront"`
	PurchaseCount     int                `json:"purchase_count"`
	CumulativeSavings float64            `json:"cumulative_savings"`
	ByService         map[string]float64 `json:"by_service,omitempty"`
	ByProvider        map[string]float64 `json:"by_provider,omitempty"`
}

type HistoryResponse struct {
	Summary   HistorySummary                 `json:"summary"`
	Purchases []config.PurchaseHistoryRecord `json:"purchases"`
}

type HistorySummary struct {
	TotalPurchases int `json:"total_purchases"`
	TotalCompleted int `json:"total_completed"`
	TotalPending   int `json:"total_pending"`
	// TotalInProgress counts executions that have been approved but whose
	// synchronous purchase has not finalized (status approved/running/paused).
	// Tracked separately from pending and excluded from the dollar totals so an
	// interrupted approval (issue #621) stays visible without inflating
	// committed spend/savings.
	TotalInProgress     int     `json:"total_in_progress"`
	TotalFailed         int     `json:"total_failed"`
	TotalExpired        int     `json:"total_expired"`
	TotalUpfront        float64 `json:"total_upfront"`
	TotalMonthlySavings float64 `json:"total_monthly_savings"`
	TotalAnnualSavings  float64 `json:"total_annual_savings"`
}

type HistorySummaryAnalytics struct {
	TotalPeriodSavings      float64 `json:"total_period_savings"`
	TotalUpfrontSpent       float64 `json:"total_upfront_spent"`
	PurchaseCount           int     `json:"purchase_count"`
	AverageSavingsPerPeriod float64 `json:"average_savings_per_period"`
	PeakSavings             float64 `json:"peak_savings"`
}

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

type InventoryCommitment struct {
	ID            string    `json:"id"`
	Provider      string    `json:"provider"`
	AccountID     string    `json:"account_id"`
	AccountName   string    `json:"account_name,omitempty"`
	Service       string    `json:"service"`
	ResourceType  string    `json:"resource_type,omitempty"`
	Region        string    `json:"region"`
	Count         int       `json:"count"`
	TermYears     int       `json:"term_years"`
	PaymentOption string    `json:"payment_option,omitempty"`
	StartDate     time.Time `json:"start_date"`
	EndDate       time.Time `json:"end_date"`
	UpfrontCost   float64   `json:"upfront_cost"`
	// MonthlyCost is nil when the source purchase_history row has a NULL
	// monthly_cost (provider did not return a monthly breakdown). The
	// frontend renders "—" for nil and "$X.XX" when non-nil.
	MonthlyCost      *float64 `json:"monthly_cost"`
	EstimatedSavings float64  `json:"estimated_savings"`
	Status           string   `json:"status"`
}

type InventoryCommitmentsResponse struct {
	Commitments []InventoryCommitment `json:"commitments"`
}

type LambdaInvokerInterface interface {
	Invoke(ctx context.Context, params *lambda.InvokeInput, optFns ...func(*lambda.Options)) (*lambda.InvokeOutput, error)
}

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
	MFACode  string `json:"mfa_code,omitempty"`
}

type LoginResponse struct {
	Token     string    `json:"token"`
	ExpiresAt string    `json:"expires_at"`
	User      *UserInfo `json:"user"`
	CSRFToken string    `json:"csrf_token,omitempty"`
}

type MFADisableRequest struct {
	Password string `json:"password"`
	Code     string `json:"code"`
}

type MFAEnableRequest struct {
	Code string `json:"code"`
}

type MFAEnableResponse struct {
	RecoveryCodes []string `json:"recovery_codes"`
}

type MFARegenerateRequest struct {
	Code string `json:"code"`
}

type MFARegenerateResponse struct {
	RecoveryCodes []string `json:"recovery_codes"`
}

type MFASetupRequest struct {
	Password string `json:"password"`
}

type MFASetupResponse struct {
	Secret          string `json:"secret"`
	ProvisioningURI string `json:"provisioning_uri"`
}

type PasswordResetConfirm struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

type PasswordResetRequest struct {
	Email string `json:"email"`
}

type PatchPlanRequest struct {
	Name                   *string `json:"name,omitempty"`
	Enabled                *bool   `json:"enabled,omitempty"`
	AutoPurchase           *bool   `json:"auto_purchase,omitempty"`
	NotificationDaysBefore *int    `json:"notification_days_before,omitempty"`
}

type Permission struct {
	Action      string                `json:"action"`
	Resource    string                `json:"resource"`
	Constraints *PermissionConstraint `json:"constraints,omitempty"`
}

type PermissionConstraint struct {
	Accounts  []string `json:"accounts,omitempty"`
	Providers []string `json:"providers,omitempty"`
	Services  []string `json:"services,omitempty"`
	Regions   []string `json:"regions,omitempty"`
	MaxAmount float64  `json:"max_amount,omitempty"`
}

type PermissionEntry struct {
	Action   string `json:"action"`
	Resource string `json:"resource"`
}

type PlanRequest struct {
	Name                   string `json:"name"`
	Description            string `json:"description,omitempty"`
	Enabled                bool   `json:"enabled"`
	AutoPurchase           bool   `json:"auto_purchase"`
	NotificationDaysBefore int    `json:"notification_days_before"`
	// Frontend sends these as top-level fields
	Provider       string `json:"provider,omitempty"`
	Service        string `json:"service,omitempty"`
	Term           int    `json:"term,omitempty"`
	Payment        string `json:"payment,omitempty"`
	TargetCoverage int    `json:"target_coverage,omitempty"`
	// Ramp schedule as string from frontend (immediate, weekly-25pct, monthly-10pct, custom)
	RampSchedule       string `json:"ramp_schedule,omitempty"`
	CustomStepPercent  int    `json:"custom_step_percent,omitempty"`
	CustomIntervalDays int    `json:"custom_interval_days,omitempty"`

	// TargetAccounts is the list of cloud_account UUIDs the plan will purchase
	// for. Required (non-empty) on POST /plans -- a plan with no rows in
	// plan_accounts is a "universal plan", which the design no longer allows:
	// every plan must be tied to at least one explicit account. The handler
	// inserts the plan_accounts rows immediately after CreatePurchasePlan so
	// the two writes are observed together by downstream consumers.
	TargetAccounts []string `json:"target_accounts,omitempty"`
}

type PlannedPurchase struct {
	ID               string  `json:"id"`
	PlanID           string  `json:"plan_id"`
	PlanName         string  `json:"plan_name"`
	ScheduledDate    string  `json:"scheduled_date"`
	Provider         string  `json:"provider"`
	Service          string  `json:"service"`
	ResourceType     string  `json:"resource_type"`
	Region           string  `json:"region"`
	Count            int     `json:"count"`
	Term             int     `json:"term"`
	Payment          string  `json:"payment"`
	EstimatedSavings float64 `json:"estimated_savings"`
	UpfrontCost      float64 `json:"upfront_cost"`
	Status           string  `json:"status"`
	StepNumber       int     `json:"step_number"`
	TotalSteps       int     `json:"total_steps"`
	// CreatedByUserID is the UUID of the user who created the scheduled
	// purchase, mirroring PurchaseHistoryRecord.CreatedByUserID. The
	// frontend gates the row action buttons on creator-scope ownership
	// (issue #950); omitted for legacy rows with a NULL creator.
	CreatedByUserID *string `json:"created_by_user_id,omitempty"`
}

type PlannedPurchasesResponse struct {
	Purchases []PlannedPurchase `json:"purchases"`
}

type PlansResponse struct {
	Plans []config.PurchasePlan `json:"plans"`
}

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

type ProfileUpdateRequest struct {
	Email           string `json:"email"`
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password,omitempty"`
}

type ProviderCoverageSection struct {
	Provider           string               `json:"provider"`
	Services           []CoverageServiceRow `json:"services"`
	OverallCoveragePct *float64             `json:"overall_coverage_pct"`
}

type PublicInfoResponse struct {
	Version     string `json:"version"`
	AdminExists bool   `json:"admin_exists"`
}

type PurchaseManagerInterface interface {
	ApproveExecution(ctx context.Context, execID, token, actor string) error
	ApproveAndExecute(ctx context.Context, execID, actor string, transitionedBy *string) error
	CancelExecution(ctx context.Context, execID, token, actor string) error
}

type RIExchangeConfigResponse struct {
	AutoExchangeEnabled      bool    `json:"auto_exchange_enabled"`
	Mode                     string  `json:"mode"`
	UtilizationThreshold     float64 `json:"utilization_threshold"`
	MaxPaymentPerExchangeUSD float64 `json:"max_payment_per_exchange_usd"`
	MaxPaymentDailyUSD       float64 `json:"max_payment_daily_usd"`
	LookbackDays             int     `json:"lookback_days"`
}

type RIExchangeConfigUpdateRequest struct {
	AutoExchangeEnabled      bool    `json:"auto_exchange_enabled"`
	Mode                     string  `json:"mode"`
	UtilizationThreshold     float64 `json:"utilization_threshold"`
	MaxPaymentPerExchangeUSD float64 `json:"max_payment_per_exchange_usd"`
	MaxPaymentDailyUSD       float64 `json:"max_payment_daily_usd"`
	LookbackDays             int     `json:"lookback_days"`
}

type RIExchangeHistoryResponse struct {
	Records []config.RIExchangeRecord `json:"records"`
}

type RIUtilizationResponse struct {
	Utilization []recommendations.RIUtilization `json:"utilization"`
}

type RateLimitConfig struct {
	MaxAttempts int           // Maximum number of attempts allowed
	WindowSecs  int           // Time window in seconds
	Window      time.Duration // Computed time window (for convenience)
}

type RateLimiterInterface interface {
	// Allow checks if a request should be allowed based on rate limits
	// Returns (allowed bool, error)
	Allow(ctx context.Context, key string, endpoint string) (bool, error)

	// AllowWithIP is a convenience method for IP-based rate limiting
	AllowWithIP(ctx context.Context, ip string, endpoint string) (bool, error)

	// AllowWithEmail is a convenience method for email-based rate limiting
	AllowWithEmail(ctx context.Context, email string, endpoint string) (bool, error)

	// AllowWithUser is a convenience method for user-based rate limiting
	AllowWithUser(ctx context.Context, userID string, endpoint string) (bool, error)
}

type RecommendationDetailResponse struct {
	ID               string       `json:"id"`
	UsageHistory     []UsagePoint `json:"usage_history"`
	ConfidenceBucket string       `json:"confidence_bucket"`
	ProvenanceNote   string       `json:"provenance_note"`
	// HiddenBy is non-nil when the rec is filtered out by an account-service
	// override (issue #214). Each element names one failing dimension:
	// "enabled=false", "engine", "region", or "resource_type". The frontend
	// renders a "hidden by your override" banner when this field is present.
	// Absent (null) means the rec is fully visible.
	HiddenBy []string `json:"hidden_by,omitempty"`
}

type RecommendationsResponse struct {
	Recommendations []config.RecommendationRecord `json:"recommendations"`
	Summary         RecommendationsSummary        `json:"summary"`
	Regions         []string                      `json:"regions"`
}

type RecommendationsSummary struct {
	TotalCount          int     `json:"total_count"`
	TotalMonthlySavings float64 `json:"total_monthly_savings"`
	TotalUpfrontCost    float64 `json:"total_upfront_cost"`
	AvgPaybackMonths    float64 `json:"avg_payback_months"`
}

type RefreshResponse struct {
	StartedAt       time.Time  `json:"started_at"`
	LastCollectedAt *time.Time `json:"last_collected_at"`
}

type RegistrationRequest struct {
	Provider            string `json:"provider"`
	ExternalID          string `json:"external_id"`
	AccountName         string `json:"account_name"`
	ContactEmail        string `json:"contact_email"`
	Description         string `json:"description"`
	SourceProvider      string `json:"source_provider"`
	AWSRoleARN          string `json:"aws_role_arn"`
	AWSAuthMode         string `json:"aws_auth_mode"`
	AWSExternalID       string `json:"aws_external_id"`
	AzureSubscriptionID string `json:"azure_subscription_id"`
	AzureTenantID       string `json:"azure_tenant_id"`
	AzureClientID       string `json:"azure_client_id"`
	AzureAuthMode       string `json:"azure_auth_mode"`
	GCPProjectID        string `json:"gcp_project_id"`
	GCPClientEmail      string `json:"gcp_client_email"`
	GCPAuthMode         string `json:"gcp_auth_mode"`
	GCPWIFAudience      string `json:"gcp_wif_audience"`
	CredentialType      string `json:"credential_type"`
	CredentialPayload   string `json:"credential_payload"`
}

type RegistrationStatusResponse struct {
	Status          string `json:"status"`
	CreatedAt       string `json:"created_at"`
	RejectionReason string `json:"rejection_reason,omitempty"`
}

type RejectRequest struct {
	Reason string `json:"reason"`
}

type ReshapeRecommendationsResponse struct {
	Recommendations []exchange.ReshapeRecommendation `json:"recommendations"`
	RecsStaleness   string                           `json:"recs_staleness,omitempty"`
	RecsCollectedAt *time.Time                       `json:"recs_collected_at,omitempty"`
}

type Route struct {
	// Pattern matching fields
	ExactPath  string // Exact path match (e.g., "/api/health")
	PathPrefix string // Path must start with this (e.g., "/api/users/")
	PathSuffix string // Path must end with this (e.g., "/revoke")
	Method     string // HTTP method (e.g., "GET", "POST")

	// Handler function
	Handler RouteHandler

	// Auth controls authentication level. REQUIRED — leaving this unset
	// (zero value) causes NewRouter to panic at startup so every route
	// author makes an explicit AuthAdmin / AuthUser / AuthPublic choice.
	// See AuthLevel doc for the history behind the mandatory-field rule.
	Auth AuthLevel
}

type RouteHandler func(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error)

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

type SchedulerInterface interface {
	CollectRecommendations(ctx context.Context) (*scheduler.CollectResult, error)
	ListRecommendations(ctx context.Context, filter config.RecommendationFilter) ([]config.RecommendationRecord, error)
	// GetRecommendationByID fetches a single rec by its application-level id,
	// bypassing account-override filtering so deep-linked URLs to override-
	// hidden recs resolve. hiddenBy is non-nil when the rec would be dropped by
	// the override filter; callers render a "hidden" banner. Returns nil, nil,
	// nil when the rec is absent or fully suppressed.
	GetRecommendationByID(ctx context.Context, id string) (rec *config.RecommendationRecord, hiddenBy []string, err error)
}

type ServiceSavings struct {
	PotentialSavings float64 `json:"potential_savings"`
	CurrentSavings   float64 `json:"current_savings"`
}

type Session struct {
	UserID string `json:"user_id"`
	Email  string `json:"email"`
}

type SetupAdminRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

type StatusResponse struct {
	Status string `json:"status"`
}

type TargetOfferingsResponse struct {
	Offerings []ec2svc.TargetOffering `json:"offerings"`
}

type TrendsResponse struct {
	Start    string                        `json:"start"`
	End      string                        `json:"end"`
	Months   int                           `json:"months"`
	Monthly  []analytics.MonthlySummary    `json:"monthly"`
	Provider []analytics.ProviderBreakdown `json:"by_provider"`
	Service  []analytics.ServiceBreakdown  `json:"by_service"`
}

type UpcomingPurchase struct {
	ExecutionID      string  `json:"execution_id"`
	PlanID           string  `json:"plan_id"`
	PlanName         string  `json:"plan_name"`
	ScheduledDate    string  `json:"scheduled_date"`
	Provider         string  `json:"provider"`
	Service          string  `json:"service"`
	StepNumber       int     `json:"step_number"`
	TotalSteps       int     `json:"total_steps"`
	EstimatedSavings float64 `json:"estimated_savings"`
	// CreatedByUserID propagates the underlying execution's
	// created_by_user_id so the dashboard widget can apply the same
	// creator-scope ownership gate the Plans page uses (issue #950).
	// Without it the widget renders a "Cancel" button on every row
	// while the backend now 403s for non-owners -- a UX hole that
	// surfaces as a confusing toast on click. Mirrors the field on
	// PlannedPurchase / PurchaseHistoryEntry. omitempty so legacy
	// NULL-creator rows keep the JSON shape they had pre-fix.
	CreatedByUserID *string `json:"created_by_user_id,omitempty"`
}

type UpcomingPurchaseResponse struct {
	Purchases []UpcomingPurchase `json:"purchases"`
}

type UpdateGroupRequest struct {
	Name            string       `json:"name,omitempty"`
	Description     string       `json:"description,omitempty"`
	Permissions     []Permission `json:"permissions,omitempty"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
}

type UpdateUserRequest struct {
	Email  string   `json:"email,omitempty"`
	Groups []string `json:"groups,omitempty"`
}

type UsagePoint struct {
	Timestamp string  `json:"timestamp"`
	CPUPct    float64 `json:"cpu_pct"`
	MemPct    float64 `json:"mem_pct"`
}

type User struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
	CreatedAt  string   `json:"created_at,omitempty"`
	UpdatedAt  string   `json:"updated_at,omitempty"`
}

type UserInfo struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
}

type UserPermissionsResponse struct {
	Permissions []PermissionEntry `json:"permissions"`
	IsAdmin     bool              `json:"is_admin"`
}

type VersionResponse struct {
	Version   string `json:"version"`
	GitSHA    string `json:"git_sha"`
	BuildTime string `json:"build_time"`
}