core

type AcknowledgeAlertRequest struct {
	AlertID        xid.ID `json:"alertId"        validate:"required"`
	AcknowledgedBy string `json:"acknowledgedBy"`
}

type AddOn struct {
	ID              xid.ID          `json:"id"`
	AppID           xid.ID          `json:"appId"`           // Scoped to app
	Name            string          `json:"name"`            // Display name
	Slug            string          `json:"slug"`            // URL-safe identifier
	Description     string          `json:"description"`     // Marketing description
	BillingPattern  BillingPattern  `json:"billingPattern"`  // How the add-on is billed
	BillingInterval BillingInterval `json:"billingInterval"` // Billing frequency
	Price           int64           `json:"price"`           // Price in cents
	Currency        string          `json:"currency"`        // ISO 4217 currency code
	Features        []PlanFeature   `json:"features"`        // Features provided by this add-on
	PriceTiers      []PriceTier     `json:"priceTiers"`      // For usage-based add-ons
	TierMode        TierMode        `json:"tierMode"`        // How tiers are applied
	Metadata        map[string]any  `json:"metadata"`        // Custom metadata
	IsActive        bool            `json:"isActive"`        // Available for purchase
	IsPublic        bool            `json:"isPublic"`        // Visible in public listing
	DisplayOrder    int             `json:"displayOrder"`    // Display order
	ProviderPriceID string          `json:"providerPriceId"` // Stripe Price ID
	CreatedAt       time.Time       `json:"createdAt"`
	UpdatedAt       time.Time       `json:"updatedAt"`

	// Constraints
	RequiresPlanIDs []xid.ID `json:"requiresPlanIds"` // Only available with these plans
	ExcludesPlanIDs []xid.ID `json:"excludesPlanIds"` // Not available with these plans
	MaxQuantity     int      `json:"maxQuantity"`     // Maximum quantity per subscription (0 = unlimited)
}

type AddPaymentMethodRequest struct {
	OrganizationID xid.ID            `json:"organizationId" validate:"required"`
	Type           PaymentMethodType `json:"type"           validate:"required"`
	SetAsDefault   bool              `json:"setAsDefault"`
	BillingName    string            `json:"billingName"`
	BillingEmail   string            `json:"billingEmail"   validate:"omitempty,email"`
	BillingPhone   string            `json:"billingPhone"`
	BillingAddress *BillingAddress   `json:"billingAddress"`
}

type Alert struct {
	ID             xid.ID  `json:"id"`
	AppID          xid.ID  `json:"appId"`
	OrganizationID xid.ID  `json:"organizationId"`
	ConfigID       *xid.ID `json:"configId"` // Reference to AlertConfig

	// Alert details
	Type     AlertType     `json:"type"`
	Severity AlertSeverity `json:"severity"`
	Status   AlertStatus   `json:"status"`
	Title    string        `json:"title"`
	Message  string        `json:"message"`

	// Context data
	MetricKey      string  `json:"metricKey"`
	CurrentValue   float64 `json:"currentValue"`
	ThresholdValue float64 `json:"thresholdValue"`
	LimitValue     float64 `json:"limitValue"`

	// Related entities
	SubscriptionID *xid.ID `json:"subscriptionId"`
	InvoiceID      *xid.ID `json:"invoiceId"`

	// Delivery tracking
	Channels       []AlertChannel    `json:"channels"`
	SentAt         *time.Time        `json:"sentAt"`
	DeliveryStatus map[string]string `json:"deliveryStatus"` // Channel -> status

	// Acknowledgment
	AcknowledgedAt *time.Time `json:"acknowledgedAt"`
	AcknowledgedBy string     `json:"acknowledgedBy"`

	// Resolution
	ResolvedAt *time.Time `json:"resolvedAt"`
	Resolution string     `json:"resolution"`

	// Metadata
	Metadata  map[string]any `json:"metadata"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
}

type AlertChannel string

type AlertConfig struct {
	ID             xid.ID `json:"id"`
	AppID          xid.ID `json:"appId"`
	OrganizationID xid.ID `json:"organizationId"`

	// Alert type settings
	AlertType AlertType `json:"alertType"`
	IsEnabled bool      `json:"isEnabled"`

	// Threshold settings (for usage alerts)
	ThresholdPercent float64 `json:"thresholdPercent"` // Trigger at X% (e.g., 80, 90, 100)
	MetricKey        string  `json:"metricKey"`        // Which metric to monitor

	// Timing settings
	DaysBeforeEnd int `json:"daysBeforeEnd"` // For trial/subscription ending alerts

	// Delivery settings
	Channels     []AlertChannel `json:"channels"`
	Recipients   []string       `json:"recipients"`   // Email addresses
	WebhookURL   string         `json:"webhookUrl"`   // For webhook channel
	SlackChannel string         `json:"slackChannel"` // For Slack channel

	// Frequency settings
	MinInterval     int `json:"minInterval"`     // Minimum minutes between alerts
	MaxAlertsPerDay int `json:"maxAlertsPerDay"` // Max alerts per day (0 = unlimited)

	// Snooze settings
	SnoozedUntil *time.Time `json:"snoozedUntil"`

	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type AlertSeverity string

type AlertStatus string

type AlertSummary struct {
	TotalAlerts        int                   `json:"totalAlerts"`
	PendingAlerts      int                   `json:"pendingAlerts"`
	SentAlerts         int                   `json:"sentAlerts"`
	AcknowledgedAlerts int                   `json:"acknowledgedAlerts"`
	BySeverity         map[AlertSeverity]int `json:"bySeverity"`
	ByType             map[AlertType]int     `json:"byType"`
	RecentAlerts       []Alert               `json:"recentAlerts"`
}

type AlertTemplate struct {
	ID        xid.ID       `json:"id"`
	AppID     xid.ID       `json:"appId"`
	AlertType AlertType    `json:"alertType"`
	Channel   AlertChannel `json:"channel"`

	// Template content
	Subject       string `json:"subject"` // For email
	TitleTemplate string `json:"titleTemplate"`
	BodyTemplate  string `json:"bodyTemplate"`

	IsDefault bool      `json:"isDefault"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type AlertType string

type AppliedDiscount struct {
	CouponID       xid.ID     `json:"couponId"`
	CouponCode     string     `json:"couponCode"`
	Type           CouponType `json:"type"`
	OriginalAmount int64      `json:"originalAmount"`
	DiscountAmount int64      `json:"discountAmount"`
	FinalAmount    int64      `json:"finalAmount"`
	Description    string     `json:"description"`
}

type AttachAddOnRequest struct {
	SubscriptionID xid.ID `json:"subscriptionId" validate:"required"`
	AddOnID        xid.ID `json:"addOnId"        validate:"required"`
	Quantity       int    `json:"quantity"       validate:"min=1"`
}

type BillingAddress struct {
	Line1      string `json:"line1"`
	Line2      string `json:"line2"`
	City       string `json:"city"`
	State      string `json:"state"`
	PostalCode string `json:"postalCode"`
	Country    string `json:"country"    validate:"len=2"` // ISO 3166-1 alpha-2
}

type BillingInterval string

type BillingMetric struct {
	ID        xid.ID       `json:"id"`
	AppID     xid.ID       `json:"appId"`
	Type      MetricType   `json:"type"`
	Period    MetricPeriod `json:"period"`
	Value     float64      `json:"value"`
	Currency  string       `json:"currency"`
	Date      time.Time    `json:"date"` // The date this metric is for
	CreatedAt time.Time    `json:"createdAt"`
}

type BillingPattern string

type CalculateTaxRequest struct {
	Amount         int64           `json:"amount"         validate:"required"`
	Currency       string          `json:"currency"       validate:"required,len=3"`
	BillingAddress *BillingAddress `json:"billingAddress"`
	OrganizationID *xid.ID         `json:"organizationId"`
	ProductType    string          `json:"productType"` // For product-specific tax rules
}

type CancelSubscriptionRequest struct {
	Immediate bool   `json:"immediate"` // If true, cancel immediately; otherwise at period end
	Reason    string `json:"reason"`    // Cancellation reason
}

type ChurnAnalysis struct {
	Period    MetricPeriod `json:"period"`
	StartDate time.Time    `json:"startDate"`
	EndDate   time.Time    `json:"endDate"`

	// Customer churn
	CustomersAtStart  int     `json:"customersAtStart"`
	CustomersAtEnd    int     `json:"customersAtEnd"`
	CustomersChurned  int     `json:"customersChurned"`
	CustomerChurnRate float64 `json:"customerChurnRate"` // Percentage

	// Revenue churn
	MRRAtStart          int64   `json:"mrrAtStart"`
	MRRAtEnd            int64   `json:"mrrAtEnd"`
	MRRChurned          int64   `json:"mrrChurned"`
	RevenueChurnRate    float64 `json:"revenueChurnRate"`    // Percentage
	NetRevenueRetention float64 `json:"netRevenueRetention"` // Percentage (can be >100%)

	// Breakdown by reason
	ChurnByReason map[string]int `json:"churnByReason"` // Reason -> count
	ChurnByPlan   map[string]int `json:"churnByPlan"`   // Plan slug -> count

	Currency string `json:"currency"`
}

type CohortAnalysis struct {
	CohortMonth    time.Time `json:"cohortMonth"` // The month customers signed up
	TotalCustomers int       `json:"totalCustomers"`
	Retention      []float64 `json:"retention"` // Retention rate for each subsequent month
	Revenue        []int64   `json:"revenue"`   // Revenue for each subsequent month
	Currency       string    `json:"currency"`
}

type CohortAnalysisResponse struct {
	Cohorts  []CohortAnalysis `json:"cohorts"`
	Currency string           `json:"currency"`
}

type Config struct {
	// General settings
	Enabled             bool `json:"enabled"`
	RequireSubscription bool `json:"requireSubscription"` // Require subscription to create org

	// Trial settings
	DefaultTrialDays  int      `json:"defaultTrialDays"`
	TrialAllowedPlans []string `json:"trialAllowedPlans"` // Plan slugs that allow trials

	// Grace period
	GracePeriodDays int `json:"gracePeriodDays"` // Days before suspending on failed payment

	// Seat management
	AutoSyncSeats bool `json:"autoSyncSeats"` // Auto-update quantity based on org members

	// Plan sync settings
	AutoSyncPlans bool `json:"autoSyncPlans"` // Auto-sync plans to payment provider on create/update

	// Provider configuration
	Provider     string       `json:"provider"` // stripe, paddle, etc.
	StripeConfig StripeConfig `json:"stripe"`

	// Webhook settings
	WebhookTolerance int `json:"webhookTolerance"` // Seconds tolerance for webhook timestamp

	// Metering settings
	UsageReportBatchSize int `json:"usageReportBatchSize"` // Batch size for usage reporting
	UsageReportInterval  int `json:"usageReportInterval"`  // Seconds between usage reports
}

type ConsumeFeatureRequest struct {
	OrganizationID xid.ID         `json:"organizationId"           validate:"required"`
	FeatureKey     string         `json:"featureKey"               validate:"required"`
	Quantity       int64          `json:"quantity"                 validate:"required,min=1"`
	IdempotencyKey string         `json:"idempotencyKey,omitempty"`
	Reason         string         `json:"reason,omitempty"`
	Metadata       map[string]any `json:"metadata,omitempty"`
}

type ConvertCurrencyRequest struct {
	Amount       int64  `json:"amount"       validate:"required"`
	FromCurrency string `json:"fromCurrency" validate:"required,len=3"`
	ToCurrency   string `json:"toCurrency"   validate:"required,len=3"`
}

type ConvertCurrencyResponse struct {
	OriginalAmount    int64     `json:"originalAmount"`
	OriginalCurrency  string    `json:"originalCurrency"`
	ConvertedAmount   int64     `json:"convertedAmount"`
	ConvertedCurrency string    `json:"convertedCurrency"`
	ExchangeRate      float64   `json:"exchangeRate"`
	ConvertedAt       time.Time `json:"convertedAt"`
}

type Coupon struct {
	ID          xid.ID         `json:"id"`
	AppID       xid.ID         `json:"appId"`
	Code        string         `json:"code"`        // Unique coupon code (e.g., "SUMMER2024")
	Name        string         `json:"name"`        // Display name
	Description string         `json:"description"` // Optional description
	Type        CouponType     `json:"type"`        // Type of discount
	Duration    CouponDuration `json:"duration"`    // How long it applies
	Status      CouponStatus   `json:"status"`

	// Discount values (depending on type)
	PercentOff float64 `json:"percentOff"` // Percentage off (0-100)
	AmountOff  int64   `json:"amountOff"`  // Fixed amount off (in smallest currency unit)
	Currency   string  `json:"currency"`   // Currency for fixed amount
	TrialDays  int     `json:"trialDays"`  // Additional trial days
	FreeMonths int     `json:"freeMonths"` // Number of free months

	// Duration settings
	DurationMonths int `json:"durationMonths"` // For repeating duration

	// Restrictions
	MaxRedemptions       int      `json:"maxRedemptions"`       // Max total redemptions (0 = unlimited)
	MaxRedemptionsPerOrg int      `json:"maxRedemptionsPerOrg"` // Max per organization
	MinPurchaseAmount    int64    `json:"minPurchaseAmount"`    // Minimum purchase amount
	ApplicablePlans      []string `json:"applicablePlans"`      // Plan slugs this applies to (empty = all)
	ApplicableAddOns     []string `json:"applicableAddOns"`     // Add-on slugs this applies to
	FirstPurchaseOnly    bool     `json:"firstPurchaseOnly"`    // Only for first purchase

	// Validity
	ValidFrom  time.Time  `json:"validFrom"`
	ValidUntil *time.Time `json:"validUntil"`

	// Usage tracking
	TimesRedeemed int `json:"timesRedeemed"` // Number of times redeemed

	// Provider integration
	ProviderCouponID string `json:"providerCouponId"` // Coupon ID in payment provider

	// Metadata
	Metadata  map[string]any `json:"metadata"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
}

type CouponDuration string

type CouponError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type CouponRedemption struct {
	ID             xid.ID `json:"id"`
	AppID          xid.ID `json:"appId"`
	CouponID       xid.ID `json:"couponId"`
	OrganizationID xid.ID `json:"organizationId"`
	SubscriptionID xid.ID `json:"subscriptionId"`

	// Applied discount
	DiscountType   CouponType `json:"discountType"`
	DiscountAmount int64      `json:"discountAmount"` // Actual amount discounted
	Currency       string     `json:"currency"`

	RedeemedAt time.Time  `json:"redeemedAt"`
	ExpiresAt  *time.Time `json:"expiresAt"` // When the discount stops applying
}

type CouponStatus string

type CouponType string

type CreateAddOnRequest struct {
	Name            string          `json:"name"            validate:"required,min=1,max=100"`
	Slug            string          `json:"slug"            validate:"required,min=1,max=50,alphanum"`
	Description     string          `json:"description"     validate:"max=1000"`
	BillingPattern  BillingPattern  `json:"billingPattern"  validate:"required"`
	BillingInterval BillingInterval `json:"billingInterval" validate:"required"`
	Price           int64           `json:"price"           validate:"min=0"`
	Currency        string          `json:"currency"        validate:"len=3"`
	Features        []PlanFeature   `json:"features"`
	PriceTiers      []PriceTier     `json:"priceTiers"`
	TierMode        TierMode        `json:"tierMode"`
	Metadata        map[string]any  `json:"metadata"`
	IsActive        bool            `json:"isActive"`
	IsPublic        bool            `json:"isPublic"`
	DisplayOrder    int             `json:"displayOrder"`
	RequiresPlanIDs []xid.ID        `json:"requiresPlanIds"`
	ExcludesPlanIDs []xid.ID        `json:"excludesPlanIds"`
	MaxQuantity     int             `json:"maxQuantity"`
}

type CreateAlertConfigRequest struct {
	OrganizationID   xid.ID         `json:"organizationId"   validate:"required"`
	AlertType        AlertType      `json:"alertType"        validate:"required"`
	ThresholdPercent float64        `json:"thresholdPercent"`
	MetricKey        string         `json:"metricKey"`
	DaysBeforeEnd    int            `json:"daysBeforeEnd"`
	Channels         []AlertChannel `json:"channels"         validate:"required,min=1"`
	Recipients       []string       `json:"recipients"`
	WebhookURL       string         `json:"webhookUrl"`
	SlackChannel     string         `json:"slackChannel"`
	MinInterval      int            `json:"minInterval"`
	MaxAlertsPerDay  int            `json:"maxAlertsPerDay"`
}

type CreateCouponRequest struct {
	Code                 string         `json:"code"                 validate:"required,min=3,max=50"`
	Name                 string         `json:"name"                 validate:"required"`
	Description          string         `json:"description"`
	Type                 CouponType     `json:"type"                 validate:"required"`
	Duration             CouponDuration `json:"duration"             validate:"required"`
	PercentOff           float64        `json:"percentOff"`
	AmountOff            int64          `json:"amountOff"`
	Currency             string         `json:"currency"`
	TrialDays            int            `json:"trialDays"`
	FreeMonths           int            `json:"freeMonths"`
	DurationMonths       int            `json:"durationMonths"`
	MaxRedemptions       int            `json:"maxRedemptions"`
	MaxRedemptionsPerOrg int            `json:"maxRedemptionsPerOrg"`
	MinPurchaseAmount    int64          `json:"minPurchaseAmount"`
	ApplicablePlans      []string       `json:"applicablePlans"`
	ApplicableAddOns     []string       `json:"applicableAddOns"`
	FirstPurchaseOnly    bool           `json:"firstPurchaseOnly"`
	ValidFrom            time.Time      `json:"validFrom"`
	ValidUntil           *time.Time     `json:"validUntil"`
	Metadata             map[string]any `json:"metadata"`
}

type CreateCustomerRequest struct {
	OrganizationID xid.ID          `json:"organizationId" validate:"required"`
	Email          string          `json:"email"          validate:"required,email"`
	Name           string          `json:"name"           validate:"required"`
	Phone          string          `json:"phone"`
	TaxID          string          `json:"taxId"`
	TaxExempt      bool            `json:"taxExempt"`
	BillingAddress *BillingAddress `json:"billingAddress"`
	Metadata       map[string]any  `json:"metadata"`
}

type CreateExchangeRateRequest struct {
	FromCurrency string    `json:"fromCurrency" validate:"required,len=3"`
	ToCurrency   string    `json:"toCurrency"   validate:"required,len=3"`
	Rate         float64   `json:"rate"         validate:"required,gt=0"`
	ValidFrom    time.Time `json:"validFrom"`
	Source       string    `json:"source"`
}

type CreateFeatureRequest struct {
	Key          string         `json:"key"                validate:"required,min=1,max=100"`
	Name         string         `json:"name"               validate:"required,min=1,max=100"`
	Description  string         `json:"description"        validate:"max=1000"`
	Type         FeatureType    `json:"type"               validate:"required"`
	Unit         string         `json:"unit"               validate:"max=50"`
	ResetPeriod  ResetPeriod    `json:"resetPeriod"`
	IsPublic     bool           `json:"isPublic"`
	DisplayOrder int            `json:"displayOrder"`
	Icon         string         `json:"icon"               validate:"max=100"`
	Metadata     map[string]any `json:"metadata,omitempty"`
	Tiers        []FeatureTier  `json:"tiers,omitempty"` // For tiered features
}

type CreatePlanRequest struct {
	Name            string          `json:"name"            validate:"required,min=1,max=100"`
	Slug            string          `json:"slug"            validate:"required,min=1,max=50,alphanum"`
	Description     string          `json:"description"     validate:"max=1000"`
	BillingPattern  BillingPattern  `json:"billingPattern"  validate:"required"`
	BillingInterval BillingInterval `json:"billingInterval" validate:"required"`
	BasePrice       int64           `json:"basePrice"       validate:"min=0"`
	Currency        string          `json:"currency"        validate:"len=3"`
	TrialDays       int             `json:"trialDays"       validate:"min=0,max=365"`
	Features        []PlanFeature   `json:"features"`
	PriceTiers      []PriceTier     `json:"priceTiers"`
	TierMode        TierMode        `json:"tierMode"`
	Metadata        map[string]any  `json:"metadata"`
	IsActive        bool            `json:"isActive"`
	IsPublic        bool            `json:"isPublic"`
	DisplayOrder    int             `json:"displayOrder"`
}

type CreatePromotionCodeRequest struct {
	CouponID       xid.ID     `json:"couponId"       validate:"required"`
	Code           string     `json:"code"           validate:"required,min=3,max=50"`
	MaxRedemptions int        `json:"maxRedemptions"`
	ValidFrom      time.Time  `json:"validFrom"`
	ValidUntil     *time.Time `json:"validUntil"`
	RestrictToOrgs []string   `json:"restrictToOrgs"`
	FirstTimeOnly  bool       `json:"firstTimeOnly"`
}

type CreateSubscriptionRequest struct {
	OrganizationID xid.ID         `json:"organizationId" validate:"required"`
	PlanID         xid.ID         `json:"planId"         validate:"required"`
	Quantity       int            `json:"quantity"       validate:"min=1"`
	StartTrial     bool           `json:"startTrial"`
	TrialDays      int            `json:"trialDays"      validate:"min=0,max=365"`
	Metadata       map[string]any `json:"metadata"`
}

type CreateTaxExemptionRequest struct {
	OrganizationID xid.ID     `json:"organizationId" validate:"required"`
	Type           string     `json:"type"           validate:"required"`
	Certificate    string     `json:"certificate"    validate:"required"`
	Country        string     `json:"country"        validate:"required,len=2"`
	State          string     `json:"state"`
	ExpiresAt      *time.Time `json:"expiresAt"`
}

type CreateTaxIDRequest struct {
	OrganizationID xid.ID    `json:"organizationId" validate:"required"`
	Type           TaxIDType `json:"type"           validate:"required"`
	Value          string    `json:"value"          validate:"required"`
	Country        string    `json:"country"        validate:"required,len=2"`
}

type CreateTaxRateRequest struct {
	Name        string      `json:"name"        validate:"required"`
	Description string      `json:"description"`
	Type        TaxType     `json:"type"        validate:"required"`
	Percentage  float64     `json:"percentage"  validate:"required,gte=0,lte=100"`
	Country     string      `json:"country"     validate:"required,len=2"`
	State       string      `json:"state"`
	City        string      `json:"city"`
	PostalCode  string      `json:"postalCode"`
	Behavior    TaxBehavior `json:"behavior"    validate:"required"`
	IsDefault   bool        `json:"isDefault"`
	ValidFrom   time.Time   `json:"validFrom"`
}

type CurrencyAmount struct {
	Amount       int64  `json:"amount"`       // Amount in smallest unit (cents, pence, etc.)
	Currency     string `json:"currency"`     // Currency code
	DisplayValue string `json:"displayValue"` // Formatted display value
}

type CurrentUsage struct {
	OrganizationID   xid.ID  `json:"organizationId"`
	OrganizationName string  `json:"organizationName"`
	FeatureID        xid.ID  `json:"featureId"`
	FeatureName      string  `json:"featureName"`
	FeatureType      string  `json:"featureType"`
	Unit             string  `json:"unit"`
	CurrentUsage     int64   `json:"currentUsage"`
	Limit            int64   `json:"limit"`
	PercentUsed      float64 `json:"percentUsed"`
}

type Customer struct {
	ID                 xid.ID          `json:"id"`
	OrganizationID     xid.ID          `json:"organizationId"`
	ProviderCustomerID string          `json:"providerCustomerId"` // Stripe Customer ID
	Email              string          `json:"email"`
	Name               string          `json:"name"`
	Phone              string          `json:"phone"`
	TaxID              string          `json:"taxId"` // VAT number, etc.
	TaxExempt          bool            `json:"taxExempt"`
	Currency           string          `json:"currency"`         // Preferred currency
	Balance            int64           `json:"balance"`          // Account balance in cents
	DefaultPaymentID   *xid.ID         `json:"defaultPaymentId"` // Default payment method
	BillingAddress     *BillingAddress `json:"billingAddress"`
	Metadata           map[string]any  `json:"metadata"`
	CreatedAt          time.Time       `json:"createdAt"`
	UpdatedAt          time.Time       `json:"updatedAt"`
}

type CustomerTaxID struct {
	ID             xid.ID     `json:"id"`
	AppID          xid.ID     `json:"appId"`
	OrganizationID xid.ID     `json:"organizationId"`
	Type           TaxIDType  `json:"type"`
	Value          string     `json:"value"`
	Country        string     `json:"country"`
	VerifiedAt     *time.Time `json:"verifiedAt"`
	IsValid        bool       `json:"isValid"`
	CreatedAt      time.Time  `json:"createdAt"`
	UpdatedAt      time.Time  `json:"updatedAt"`
}

type DashboardMetrics struct {
	// Current state
	TotalMRR              int64 `json:"totalMrr"`
	TotalARR              int64 `json:"totalArr"`
	ActiveSubscriptions   int   `json:"activeSubscriptions"`
	TrialingSubscriptions int   `json:"trialingSubscriptions"`

	// Changes
	MRRGrowth          float64 `json:"mrrGrowth"` // Percentage change
	SubscriptionGrowth float64 `json:"subscriptionGrowth"`

	// Health indicators
	ChurnRate           float64 `json:"churnRate"`
	TrialConversionRate float64 `json:"trialConversionRate"`
	NetRevenueRetention float64 `json:"netRevenueRetention"`

	// Revenue breakdown
	NewMRR       int64 `json:"newMrr"`
	ExpansionMRR int64 `json:"expansionMrr"`
	ChurnedMRR   int64 `json:"churnedMrr"`

	Currency string    `json:"currency"`
	AsOf     time.Time `json:"asOf"`
}

type EventType string

type ExchangeRate struct {
	ID           xid.ID     `json:"id"`
	AppID        xid.ID     `json:"appId"`
	FromCurrency string     `json:"fromCurrency"` // Source currency code
	ToCurrency   string     `json:"toCurrency"`   // Target currency code
	Rate         float64    `json:"rate"`         // Exchange rate (multiply by this to convert)
	ValidFrom    time.Time  `json:"validFrom"`    // When this rate becomes valid
	ValidUntil   *time.Time `json:"validUntil"`   // When this rate expires (nil = current)
	Source       string     `json:"source"`       // Source of the rate (manual, api, etc.)
	CreatedAt    time.Time  `json:"createdAt"`
	UpdatedAt    time.Time  `json:"updatedAt"`
}

type ExportMetricsRequest struct {
	MetricTypes []MetricType `json:"metricTypes"`
	Period      MetricPeriod `json:"period"`
	StartDate   time.Time    `json:"startDate"`
	EndDate     time.Time    `json:"endDate"`
	Format      string       `json:"format"` // csv, json, xlsx
}

type Feature struct {
	ID                xid.ID         `json:"id"`
	AppID             xid.ID         `json:"appId"`
	Key               string         `json:"key"`               // Unique per app
	Name              string         `json:"name"`              // Display name
	Description       string         `json:"description"`       // Feature description
	Type              FeatureType    `json:"type"`              // boolean, limit, unlimited, metered, tiered
	Unit              string         `json:"unit"`              // "seats", "GB", "API calls", etc.
	ResetPeriod       ResetPeriod    `json:"resetPeriod"`       // When usage resets
	IsPublic          bool           `json:"isPublic"`          // Show in pricing pages
	DisplayOrder      int            `json:"displayOrder"`      // Order in UI
	Icon              string         `json:"icon"`              // Icon identifier for UI
	ProviderFeatureID string         `json:"providerFeatureId"` // Provider sync ID (e.g., Stripe product feature ID)
	LastSyncedAt      *time.Time     `json:"lastSyncedAt"`      // Last provider sync time
	Metadata          map[string]any `json:"metadata"`
	Tiers             []FeatureTier  `json:"tiers,omitempty"` // For tiered features
	CreatedAt         time.Time      `json:"createdAt"`
	UpdatedAt         time.Time      `json:"updatedAt"`
}

type FeatureAccess struct {
	Feature      *Feature `json:"feature"`
	HasAccess    bool     `json:"hasAccess"`
	IsBlocked    bool     `json:"isBlocked"`
	Limit        int64    `json:"limit"` // -1 for unlimited, 0 for no access
	CurrentUsage int64    `json:"currentUsage"`
	Remaining    int64    `json:"remaining"`    // -1 for unlimited
	GrantedExtra int64    `json:"grantedExtra"` // Extra from grants
	PlanValue    string   `json:"planValue"`    // The raw value from plan
}

type FeatureGrant struct {
	ID             xid.ID           `json:"id"`
	OrganizationID xid.ID           `json:"organizationId"`
	FeatureID      xid.ID           `json:"featureId"`
	FeatureKey     string           `json:"featureKey"` // Denormalized for convenience
	GrantType      FeatureGrantType `json:"grantType"`  // addon, override, promotion, trial, manual
	Value          int64            `json:"value"`      // Additional quota
	ExpiresAt      *time.Time       `json:"expiresAt,omitempty"`
	SourceType     string           `json:"sourceType,omitempty"` // addon, coupon, promotion, etc.
	SourceID       *xid.ID          `json:"sourceId,omitempty"`   // AddOn ID, Promotion ID, etc.
	Reason         string           `json:"reason,omitempty"`
	IsActive       bool             `json:"isActive"`
	Metadata       map[string]any   `json:"metadata,omitempty"`
	CreatedAt      time.Time        `json:"createdAt"`
	UpdatedAt      time.Time        `json:"updatedAt"`
}

type FeatureGrantType string

type FeatureTier struct {
	ID        xid.ID `json:"id"`
	FeatureID xid.ID `json:"featureId"`
	TierOrder int    `json:"tierOrder"`
	UpTo      int64  `json:"upTo"`  // -1 for unlimited
	Value     string `json:"value"` // What's unlocked at this tier
	Label     string `json:"label"` // Display label for this tier
}

type FeatureType string

type FeatureUsageAction string

type FeatureUsageLog struct {
	ID             xid.ID         `json:"id"`
	OrganizationID xid.ID         `json:"organizationId"`
	FeatureID      xid.ID         `json:"featureId"`
	FeatureKey     string         `json:"featureKey"`
	Action         string         `json:"action"` // consume, grant, reset, adjust
	Quantity       int64          `json:"quantity"`
	PreviousUsage  int64          `json:"previousUsage"`
	NewUsage       int64          `json:"newUsage"`
	ActorID        *xid.ID        `json:"actorId,omitempty"`
	Reason         string         `json:"reason,omitempty"`
	IdempotencyKey string         `json:"idempotencyKey,omitempty"`
	Metadata       map[string]any `json:"metadata,omitempty"`
	CreatedAt      time.Time      `json:"createdAt"`
}

type FeatureUsageResponse struct {
	FeatureKey   string    `json:"featureKey"`
	FeatureName  string    `json:"featureName"`
	FeatureType  string    `json:"featureType"`
	CurrentUsage int64     `json:"currentUsage"`
	Limit        int64     `json:"limit"`     // -1 for unlimited
	Remaining    int64     `json:"remaining"` // -1 for unlimited
	PeriodStart  time.Time `json:"periodStart"`
	PeriodEnd    time.Time `json:"periodEnd"`
	GrantedExtra int64     `json:"grantedExtra"` // Extra quota from grants
}

type GetCohortAnalysisRequest struct {
	StartMonth time.Time `json:"startMonth"`
	NumMonths  int       `json:"numMonths"`
	Currency   string    `json:"currency"`
}

type GetMetricsRequest struct {
	MetricTypes []MetricType `json:"metricTypes"`
	Period      MetricPeriod `json:"period"`
	StartDate   time.Time    `json:"startDate"`
	EndDate     time.Time    `json:"endDate"`
	Currency    string       `json:"currency"`
	GroupBy     string       `json:"groupBy"` // plan, segment, etc.
}

type GetUsageSummaryRequest struct {
	SubscriptionID xid.ID    `json:"subscriptionId" validate:"required"`
	MetricKey      string    `json:"metricKey"      validate:"required"`
	PeriodStart    time.Time `json:"periodStart"    validate:"required"`
	PeriodEnd      time.Time `json:"periodEnd"      validate:"required"`
}

type GrantFeatureRequest struct {
	OrganizationID xid.ID           `json:"organizationId"       validate:"required"`
	FeatureKey     string           `json:"featureKey"           validate:"required"`
	GrantType      FeatureGrantType `json:"grantType"            validate:"required"`
	Value          int64            `json:"value"                validate:"required,min=1"`
	ExpiresAt      *time.Time       `json:"expiresAt,omitempty"`
	SourceType     string           `json:"sourceType,omitempty"`
	SourceID       *xid.ID          `json:"sourceId,omitempty"`
	Reason         string           `json:"reason,omitempty"`
	Metadata       map[string]any   `json:"metadata,omitempty"`
}

type GrowthPoint struct {
	Date        time.Time `json:"date"`
	NewSubs     int       `json:"newSubs"`
	ChurnedSubs int       `json:"churnedSubs"`
	ActiveSubs  int       `json:"activeSubs"`
	NetGrowth   int       `json:"netGrowth"`
}

type Invoice struct {
	ID                xid.ID         `json:"id"`
	SubscriptionID    xid.ID         `json:"subscriptionId"`    // Related subscription
	OrganizationID    xid.ID         `json:"organizationId"`    // Organization billed
	Number            string         `json:"number"`            // Invoice number (e.g., INV-2024-0001)
	Status            InvoiceStatus  `json:"status"`            // Current status
	Currency          string         `json:"currency"`          // ISO 4217 currency code
	Subtotal          int64          `json:"subtotal"`          // Amount before tax in cents
	Tax               int64          `json:"tax"`               // Tax amount in cents
	Total             int64          `json:"total"`             // Total amount in cents
	AmountPaid        int64          `json:"amountPaid"`        // Amount already paid in cents
	AmountDue         int64          `json:"amountDue"`         // Remaining amount due in cents
	Description       string         `json:"description"`       // Invoice description
	PeriodStart       time.Time      `json:"periodStart"`       // Billing period start
	PeriodEnd         time.Time      `json:"periodEnd"`         // Billing period end
	DueDate           time.Time      `json:"dueDate"`           // Payment due date
	PaidAt            *time.Time     `json:"paidAt"`            // When paid
	VoidedAt          *time.Time     `json:"voidedAt"`          // When voided
	ProviderInvoiceID string         `json:"providerInvoiceId"` // Stripe Invoice ID
	ProviderPDFURL    string         `json:"providerPdfUrl"`    // Stripe hosted PDF URL
	HostedInvoiceURL  string         `json:"hostedInvoiceUrl"`  // Stripe hosted invoice page
	Metadata          map[string]any `json:"metadata"`          // Custom metadata
	CreatedAt         time.Time      `json:"createdAt"`
	UpdatedAt         time.Time      `json:"updatedAt"`

	// Relations
	Items []InvoiceItem `json:"items,omitempty"`
}

type InvoiceItem struct {
	ID             xid.ID         `json:"id"`
	InvoiceID      xid.ID         `json:"invoiceId"`
	Description    string         `json:"description"`    // Line item description
	Quantity       int64          `json:"quantity"`       // Quantity
	UnitAmount     int64          `json:"unitAmount"`     // Unit price in cents
	Amount         int64          `json:"amount"`         // Total amount in cents
	PlanID         *xid.ID        `json:"planId"`         // Related plan if applicable
	AddOnID        *xid.ID        `json:"addOnId"`        // Related add-on if applicable
	PeriodStart    time.Time      `json:"periodStart"`    // Item period start
	PeriodEnd      time.Time      `json:"periodEnd"`      // Item period end
	Proration      bool           `json:"proration"`      // Is this a proration adjustment
	Metadata       map[string]any `json:"metadata"`       // Custom metadata
	ProviderItemID string         `json:"providerItemId"` // Stripe Invoice Item ID
	CreatedAt      time.Time      `json:"createdAt"`
}

type InvoiceMetrics struct {
	Period               MetricPeriod `json:"period"`
	TotalInvoiced        int64        `json:"totalInvoiced"`
	TotalCollected       int64        `json:"totalCollected"`
	TotalOutstanding     int64        `json:"totalOutstanding"`
	TotalOverdue         int64        `json:"totalOverdue"`
	CollectionRate       float64      `json:"collectionRate"`       // Percentage
	AverageTimeToPayment float64      `json:"averageTimeToPayment"` // In days
	Currency             string       `json:"currency"`
}

type InvoiceStatus string

type LinkFeatureRequest struct {
	FeatureID        xid.ID         `json:"featureId"                  validate:"required"`
	Value            string         `json:"value"`         // The limit/value for this plan
	IsBlocked        bool           `json:"isBlocked"`     // Explicitly block this feature
	IsHighlighted    bool           `json:"isHighlighted"` // Highlight in pricing UI
	OverrideSettings map[string]any `json:"overrideSettings,omitempty"`
}

type ListInvoicesFilter struct {
	OrganizationID *xid.ID       `json:"organizationId"`
	SubscriptionID *xid.ID       `json:"subscriptionId"`
	Status         InvoiceStatus `json:"status"`
	FromDate       *time.Time    `json:"fromDate"`
	ToDate         *time.Time    `json:"toDate"`
	Page           int           `json:"page"`
	PageSize       int           `json:"pageSize"`
}

type ListUsageRecordsFilter struct {
	SubscriptionID *xid.ID    `json:"subscriptionId"`
	OrganizationID *xid.ID    `json:"organizationId"`
	MetricKey      string     `json:"metricKey"`
	FromDate       *time.Time `json:"fromDate"`
	ToDate         *time.Time `json:"toDate"`
	Reported       *bool      `json:"reported"`
	Page           int        `json:"page"`
	PageSize       int        `json:"pageSize"`
}

type MRRBreakdown struct {
	Date            time.Time `json:"date"`
	Currency        string    `json:"currency"`
	TotalMRR        int64     `json:"totalMrr"`
	NewMRR          int64     `json:"newMrr"`          // From new customers
	ExpansionMRR    int64     `json:"expansionMrr"`    // From upgrades
	ContractionMRR  int64     `json:"contractionMrr"`  // From downgrades (negative)
	ChurnedMRR      int64     `json:"churnedMrr"`      // Lost from cancellations (negative)
	ReactivationMRR int64     `json:"reactivationMrr"` // From reactivated customers
	NetNewMRR       int64     `json:"netNewMrr"`       // Total change
}

type MetricPeriod string

type MetricType string

type MetricsResponse struct {
	Metrics    []BillingMetric   `json:"metrics"`
	MRRHistory []MRRBreakdown    `json:"mrrHistory,omitempty"`
	Churn      *ChurnAnalysis    `json:"churn,omitempty"`
	Dashboard  *DashboardMetrics `json:"dashboard,omitempty"`
	StartDate  time.Time         `json:"startDate"`
	EndDate    time.Time         `json:"endDate"`
	Currency   string            `json:"currency"`
}

type MultiCurrencyPrice struct {
	BaseCurrency string                    `json:"baseCurrency"`
	BaseAmount   int64                     `json:"baseAmount"`
	Prices       map[string]CurrencyAmount `json:"prices"` // Currency code -> amount
}

type OrgRevenue struct {
	OrgID    xid.ID `json:"orgId"`
	OrgName  string `json:"orgName"`
	MRR      int64  `json:"mrr"`
	ARR      int64  `json:"arr"`
	PlanID   xid.ID `json:"planId"`
	PlanName string `json:"planName"`
	Status   string `json:"status"`
}

type OrgUsageStats struct {
	OrgID       xid.ID      `json:"orgId"`
	OrgName     string      `json:"orgName"`
	FeatureID   xid.ID      `json:"featureId"`
	FeatureName string      `json:"featureName"`
	FeatureType FeatureType `json:"featureType"`
	Unit        string      `json:"unit"`
	Usage       int64       `json:"usage"`
	Limit       int64       `json:"limit"`
	PercentUsed float64     `json:"percentUsed"`
}

type OrganizationFeatureUsage struct {
	ID             xid.ID         `json:"id"`
	OrganizationID xid.ID         `json:"organizationId"`
	FeatureID      xid.ID         `json:"featureId"`
	FeatureKey     string         `json:"featureKey"` // Denormalized for convenience
	CurrentUsage   int64          `json:"currentUsage"`
	PeriodStart    time.Time      `json:"periodStart"`
	PeriodEnd      time.Time      `json:"periodEnd"`
	LastReset      time.Time      `json:"lastReset"`
	Metadata       map[string]any `json:"metadata,omitempty"`
}

type PauseSubscriptionRequest struct {
	ResumeAt *time.Time `json:"resumeAt"` // Optional date to auto-resume
	Reason   string     `json:"reason"`   // Pause reason
}

type PaymentMethod struct {
	ID                 xid.ID            `json:"id"`
	OrganizationID     xid.ID            `json:"organizationId"`
	Type               PaymentMethodType `json:"type"`               // card, bank_account, etc.
	IsDefault          bool              `json:"isDefault"`          // Is this the default payment method
	ProviderMethodID   string            `json:"providerMethodId"`   // Stripe PaymentMethod ID
	ProviderCustomerID string            `json:"providerCustomerId"` // Stripe Customer ID

	// Card-specific fields (when Type == PaymentMethodCard)
	CardBrand    string `json:"cardBrand"`    // visa, mastercard, etc.
	CardLast4    string `json:"cardLast4"`    // Last 4 digits
	CardExpMonth int    `json:"cardExpMonth"` // Expiration month
	CardExpYear  int    `json:"cardExpYear"`  // Expiration year
	CardFunding  string `json:"cardFunding"`  // credit, debit, prepaid

	// Bank account specific fields (when Type == PaymentMethodBankAccount)
	BankName          string `json:"bankName"`
	BankLast4         string `json:"bankLast4"`
	BankRoutingNumber string `json:"bankRoutingNumber"` // Masked
	BankAccountType   string `json:"bankAccountType"`   // checking, savings

	// Billing details
	BillingName         string `json:"billingName"`
	BillingEmail        string `json:"billingEmail"`
	BillingPhone        string `json:"billingPhone"`
	BillingAddressLine1 string `json:"billingAddressLine1"`
	BillingAddressLine2 string `json:"billingAddressLine2"`
	BillingCity         string `json:"billingCity"`
	BillingState        string `json:"billingState"`
	BillingPostalCode   string `json:"billingPostalCode"`
	BillingCountry      string `json:"billingCountry"`

	Metadata  map[string]any `json:"metadata"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
}

type PaymentMethodType string

type Plan struct {
	ID              xid.ID          `json:"id"`
	AppID           xid.ID          `json:"appId"`           // Scoped to app
	Name            string          `json:"name"`            // Display name
	Slug            string          `json:"slug"`            // URL-safe identifier
	Description     string          `json:"description"`     // Marketing description
	Archived        bool            `json:"archived"`        // Whether the plan is archived
	BillingPattern  BillingPattern  `json:"billingPattern"`  // How the plan is billed
	BillingInterval BillingInterval `json:"billingInterval"` // Billing frequency
	BasePrice       int64           `json:"basePrice"`       // Price in cents
	Currency        string          `json:"currency"`        // ISO 4217 currency code
	TrialDays       int             `json:"trialDays"`       // Number of trial days (0 for no trial)
	Features        []PlanFeature   `json:"features"`        // Feature flags and limits
	PriceTiers      []PriceTier     `json:"priceTiers"`      // For tiered/usage pricing
	TierMode        TierMode        `json:"tierMode"`        // How tiers are applied
	Metadata        map[string]any  `json:"metadata"`        // Custom metadata
	IsActive        bool            `json:"isActive"`        // Can be subscribed to
	IsPublic        bool            `json:"isPublic"`        // Visible in public pricing
	DisplayOrder    int             `json:"displayOrder"`    // Order in pricing pages
	ProviderPlanID  string          `json:"providerPlanId"`  // Stripe Product ID
	ProviderPriceID string          `json:"providerPriceId"` // Stripe Price ID
	CreatedAt       time.Time       `json:"createdAt"`
	UpdatedAt       time.Time       `json:"updatedAt"`
}

type PlanFeature struct {
	Key           string      `json:"key"`                     // Feature identifier (e.g., "max_members")
	Name          string      `json:"name"`                    // Display name
	Description   string      `json:"description"`             // Feature description
	Type          FeatureType `json:"type"`                    // boolean, limit, or unlimited
	Value         any         `json:"value"`                   // The feature value (true, 100, -1 for unlimited)
	Unit          string      `json:"unit,omitempty"`          // Unit of measurement (e.g., "seats", "GB", "API calls")
	IsHighlighted bool        `json:"isHighlighted,omitempty"` // Highlight in pricing comparison
}

type PlanFeatureLink struct {
	ID               xid.ID         `json:"id"`
	PlanID           xid.ID         `json:"planId"`
	FeatureID        xid.ID         `json:"featureId"`
	Value            string         `json:"value"`         // JSON: limit value, tier, boolean, etc.
	IsBlocked        bool           `json:"isBlocked"`     // Explicitly blocked for this plan
	IsHighlighted    bool           `json:"isHighlighted"` // Highlight in pricing comparison
	OverrideSettings map[string]any `json:"overrideSettings,omitempty"`
	Feature          *Feature       `json:"feature,omitempty"` // Loaded feature
}

type PriceTier struct {
	UpTo       int64 `json:"upTo"`       // Upper bound (-1 for infinite)
	UnitAmount int64 `json:"unitAmount"` // Price per unit in cents
	FlatAmount int64 `json:"flatAmount"` // Flat fee for this tier in cents
}

type PromotionCode struct {
	ID       xid.ID  `json:"id"`
	AppID    xid.ID  `json:"appId"`
	CouponID xid.ID  `json:"couponId"`
	Coupon   *Coupon `json:"coupon,omitempty"`
	Code     string  `json:"code"` // Unique promotion code
	IsActive bool    `json:"isActive"`

	// Restrictions (override coupon settings)
	MaxRedemptions int        `json:"maxRedemptions"` // Max for this specific code
	ValidFrom      time.Time  `json:"validFrom"`
	ValidUntil     *time.Time `json:"validUntil"`

	// Customer restrictions
	RestrictToOrgs []string `json:"restrictToOrgs"` // Org IDs that can use this
	FirstTimeOnly  bool     `json:"firstTimeOnly"`

	// Usage tracking
	TimesRedeemed int `json:"timesRedeemed"`

	// Provider integration
	ProviderPromoID string `json:"providerPromoId"`

	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type PublicFeature struct {
	Key          string `json:"key"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Type         string `json:"type"`
	Unit         string `json:"unit,omitempty"`
	Icon         string `json:"icon,omitempty"`
	DisplayOrder int    `json:"displayOrder"`
}

type PublicPlanFeature struct {
	Key           string `json:"key"`
	Name          string `json:"name"`
	Description   string `json:"description"`
	Type          string `json:"type"`
	Unit          string `json:"unit,omitempty"`
	Value         any    `json:"value"` // Parsed value (boolean, number, or tier info)
	IsHighlighted bool   `json:"isHighlighted"`
	IsBlocked     bool   `json:"isBlocked"`
	DisplayOrder  int    `json:"displayOrder"`
}

type RecordUsageRequest struct {
	SubscriptionID xid.ID         `json:"subscriptionId" validate:"required"`
	MetricKey      string         `json:"metricKey"      validate:"required,min=1,max=50"`
	Quantity       int64          `json:"quantity"       validate:"required,min=0"`
	Action         UsageAction    `json:"action"         validate:"required"`
	Timestamp      *time.Time     `json:"timestamp"` // Optional, defaults to now
	IdempotencyKey string         `json:"idempotencyKey" validate:"max=100"`
	Metadata       map[string]any `json:"metadata"`
}

type RedeemCouponRequest struct {
	Code           string `json:"code"           validate:"required"`
	OrganizationID xid.ID `json:"organizationId" validate:"required"`
	SubscriptionID xid.ID `json:"subscriptionId" validate:"required"`
}

type ResetPeriod string

type ResolveAlertRequest struct {
	AlertID    xid.ID `json:"alertId"    validate:"required"`
	Resolution string `json:"resolution"`
}

type RevenueByPlan struct {
	PlanID            xid.ID  `json:"planId"`
	PlanName          string  `json:"planName"`
	PlanSlug          string  `json:"planSlug"`
	ActiveSubscribers int     `json:"activeSubscribers"`
	MRR               int64   `json:"mrr"`
	ARR               int64   `json:"arr"`
	PercentOfTotal    float64 `json:"percentOfTotal"`
	Currency          string  `json:"currency"`
}

type RevenueBySegment struct {
	Segment     string  `json:"segment"`
	Subscribers int     `json:"subscribers"`
	MRR         int64   `json:"mrr"`
	ARPU        int64   `json:"arpu"`
	ChurnRate   float64 `json:"churnRate"`
	LTV         int64   `json:"ltv"`
	Currency    string  `json:"currency"`
}

type SetupIntentResult struct {
	ClientSecret   string `json:"clientSecret"`   // For client-side confirmation
	SetupIntentID  string `json:"setupIntentId"`  // Stripe SetupIntent ID
	PublishableKey string `json:"publishableKey"` // Stripe publishable key
}

type SnoozeAlertRequest struct {
	AlertID     xid.ID    `json:"alertId"     validate:"required"`
	SnoozeUntil time.Time `json:"snoozeUntil" validate:"required"`
}

type StripeConfig struct {
	SecretKey      string `json:"secretKey"`
	WebhookSecret  string `json:"webhookSecret"`
	PublishableKey string `json:"publishableKey"`
	APIVersion     string `json:"apiVersion"`     // Optional: specific API version
	ConnectAccount string `json:"connectAccount"` // Optional: for Stripe Connect
}

type Subscription struct {
	ID                 xid.ID             `json:"id"`
	OrganizationID     xid.ID             `json:"organizationId"`     // Links to Organization
	PlanID             xid.ID             `json:"planId"`             // Current plan
	Status             SubscriptionStatus `json:"status"`             // Current status
	Quantity           int                `json:"quantity"`           // For per-seat billing
	CurrentPeriodStart time.Time          `json:"currentPeriodStart"` // Start of current billing period
	CurrentPeriodEnd   time.Time          `json:"currentPeriodEnd"`   // End of current billing period
	TrialStart         *time.Time         `json:"trialStart"`         // Start of trial
	TrialEnd           *time.Time         `json:"trialEnd"`           // End of trial
	CancelAt           *time.Time         `json:"cancelAt"`           // Scheduled cancellation date
	CanceledAt         *time.Time         `json:"canceledAt"`         // When cancellation was requested
	EndedAt            *time.Time         `json:"endedAt"`            // When subscription actually ended
	PausedAt           *time.Time         `json:"pausedAt"`           // When subscription was paused
	ResumeAt           *time.Time         `json:"resumeAt"`           // Scheduled resume date
	ProviderSubID      string             `json:"providerSubId"`      // Stripe Subscription ID
	ProviderCustomerID string             `json:"providerCustomerId"` // Stripe Customer ID
	Metadata           map[string]any     `json:"metadata"`           // Custom metadata
	CreatedAt          time.Time          `json:"createdAt"`
	UpdatedAt          time.Time          `json:"updatedAt"`

	// Relations (populated when loaded)
	Plan   *Plan               `json:"plan,omitempty"`
	AddOns []SubscriptionAddOn `json:"addOns,omitempty"`
}

type SubscriptionAddOn struct {
	ID                xid.ID    `json:"id"`
	SubscriptionID    xid.ID    `json:"subscriptionId"`
	AddOnID           xid.ID    `json:"addOnId"`
	Quantity          int       `json:"quantity"`
	ProviderSubItemID string    `json:"providerSubItemId"` // Stripe Subscription Item ID
	CreatedAt         time.Time `json:"createdAt"`

	// Relations
	AddOn *AddOn `json:"addOn,omitempty"`
}

type SubscriptionMovement struct {
	ID             xid.ID `json:"id"`
	AppID          xid.ID `json:"appId"`
	SubscriptionID xid.ID `json:"subscriptionId"`
	OrganizationID xid.ID `json:"organizationId"`
	MovementType   string `json:"movementType"` // new, upgrade, downgrade, churn, reactivation

	// Revenue impact
	PreviousMRR int64  `json:"previousMrr"`
	NewMRR      int64  `json:"newMrr"`
	MRRChange   int64  `json:"mrrChange"`
	Currency    string `json:"currency"`

	// Plan details
	PreviousPlanID *xid.ID `json:"previousPlanId"`
	NewPlanID      *xid.ID `json:"newPlanId"`

	// Metadata
	Reason     string    `json:"reason"`
	Notes      string    `json:"notes"`
	OccurredAt time.Time `json:"occurredAt"`
	CreatedAt  time.Time `json:"createdAt"`
}

type SubscriptionStatus string

type SupportedCurrency struct {
	ID            xid.ID    `json:"id"`
	Code          string    `json:"code"`          // ISO 4217 code (USD, EUR, GBP, etc.)
	Name          string    `json:"name"`          // Display name
	Symbol        string    `json:"symbol"`        // Currency symbol ($, €, £)
	DecimalPlaces int       `json:"decimalPlaces"` // Number of decimal places (2 for most, 0 for JPY)
	IsDefault     bool      `json:"isDefault"`     // Is this the default currency
	IsActive      bool      `json:"isActive"`      // Is this currency currently active
	CreatedAt     time.Time `json:"createdAt"`
	UpdatedAt     time.Time `json:"updatedAt"`
}

type TaxBehavior string

type TaxBillingAddress = BillingAddress

type TaxCalculation struct {
	TaxRateID     xid.ID  `json:"taxRateId"`
	TaxRateName   string  `json:"taxRateName"`
	TaxType       TaxType `json:"taxType"`
	Percentage    float64 `json:"percentage"`
	TaxableAmount int64   `json:"taxableAmount"` // Amount before tax
	TaxAmount     int64   `json:"taxAmount"`     // Calculated tax amount
	TotalAmount   int64   `json:"totalAmount"`   // Amount after tax
	Currency      string  `json:"currency"`
	IsExempt      bool    `json:"isExempt"`
	ExemptionID   *xid.ID `json:"exemptionId"`
}

type TaxExemption struct {
	ID             xid.ID     `json:"id"`
	AppID          xid.ID     `json:"appId"`
	OrganizationID xid.ID     `json:"organizationId"`
	Type           string     `json:"type"`        // Exemption type (nonprofit, government, resale)
	Certificate    string     `json:"certificate"` // Exemption certificate number
	Country        string     `json:"country"`     // Country where exemption applies
	State          string     `json:"state"`       // State where exemption applies
	VerifiedAt     *time.Time `json:"verifiedAt"`  // When exemption was verified
	ExpiresAt      *time.Time `json:"expiresAt"`   // When exemption expires
	IsActive       bool       `json:"isActive"`
	CreatedAt      time.Time  `json:"createdAt"`
	UpdatedAt      time.Time  `json:"updatedAt"`
}

type TaxIDType string

type TaxRate struct {
	ID          xid.ID      `json:"id"`
	AppID       xid.ID      `json:"appId"`
	Name        string      `json:"name"`        // Display name (e.g., "US Sales Tax", "UK VAT")
	Description string      `json:"description"` // Optional description
	Type        TaxType     `json:"type"`        // Type of tax
	Percentage  float64     `json:"percentage"`  // Tax rate as percentage (e.g., 20.0 for 20%)
	Country     string      `json:"country"`     // ISO 3166-1 alpha-2 country code
	State       string      `json:"state"`       // State/province code (for US, CA)
	City        string      `json:"city"`        // City (for local taxes)
	PostalCode  string      `json:"postalCode"`  // Postal/ZIP code pattern
	Behavior    TaxBehavior `json:"behavior"`    // Exclusive or inclusive
	IsDefault   bool        `json:"isDefault"`   // Default rate for the region
	IsActive    bool        `json:"isActive"`    // Is this rate active

	// Provider integration
	ProviderTaxRateID string `json:"providerTaxRateId"` // Tax rate ID in payment provider

	// Timestamps
	ValidFrom  time.Time  `json:"validFrom"`  // When rate becomes valid
	ValidUntil *time.Time `json:"validUntil"` // When rate expires
	CreatedAt  time.Time  `json:"createdAt"`
	UpdatedAt  time.Time  `json:"updatedAt"`
}

type TaxSummary struct {
	Calculations []TaxCalculation `json:"calculations"`
	TotalTax     int64            `json:"totalTax"`
	Currency     string           `json:"currency"`
}

type TaxType string

type TierMode string

type TrialMetrics struct {
	Period             MetricPeriod `json:"period"`
	TrialsStarted      int          `json:"trialsStarted"`
	TrialsConverted    int          `json:"trialsConverted"`
	TrialsExpired      int          `json:"trialsExpired"`
	TrialsActive       int          `json:"trialsActive"`
	ConversionRate     float64      `json:"conversionRate"`
	AverageTrialLength float64      `json:"averageTrialLength"` // In days

	// Conversion by plan
	ConversionByPlan map[string]float64 `json:"conversionByPlan"` // Plan slug -> rate
}

type TriggerAlertRequest struct {
	OrganizationID xid.ID         `json:"organizationId" validate:"required"`
	Type           AlertType      `json:"type"           validate:"required"`
	Severity       AlertSeverity  `json:"severity"`
	Title          string         `json:"title"          validate:"required"`
	Message        string         `json:"message"        validate:"required"`
	Metadata       map[string]any `json:"metadata"`
}

type UpdateAddOnRequest struct {
	Name            *string        `json:"name,omitempty"            validate:"omitempty,min=1,max=100"`
	Description     *string        `json:"description,omitempty"     validate:"omitempty,max=1000"`
	Price           *int64         `json:"price,omitempty"           validate:"omitempty,min=0"`
	Features        []PlanFeature  `json:"features,omitempty"`
	PriceTiers      []PriceTier    `json:"priceTiers,omitempty"`
	TierMode        *TierMode      `json:"tierMode,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
	IsActive        *bool          `json:"isActive,omitempty"`
	IsPublic        *bool          `json:"isPublic,omitempty"`
	DisplayOrder    *int           `json:"displayOrder,omitempty"`
	RequiresPlanIDs []xid.ID       `json:"requiresPlanIds,omitempty"`
	ExcludesPlanIDs []xid.ID       `json:"excludesPlanIds,omitempty"`
	MaxQuantity     *int           `json:"maxQuantity,omitempty"`
}

type UpdateAlertConfigRequest struct {
	IsEnabled        *bool          `json:"isEnabled"`
	ThresholdPercent *float64       `json:"thresholdPercent"`
	DaysBeforeEnd    *int           `json:"daysBeforeEnd"`
	Channels         []AlertChannel `json:"channels"`
	Recipients       []string       `json:"recipients"`
	WebhookURL       *string        `json:"webhookUrl"`
	SlackChannel     *string        `json:"slackChannel"`
	MinInterval      *int           `json:"minInterval"`
	MaxAlertsPerDay  *int           `json:"maxAlertsPerDay"`
}

type UpdateCouponRequest struct {
	Name                 *string        `json:"name"`
	Description          *string        `json:"description"`
	MaxRedemptions       *int           `json:"maxRedemptions"`
	MaxRedemptionsPerOrg *int           `json:"maxRedemptionsPerOrg"`
	ApplicablePlans      []string       `json:"applicablePlans"`
	ApplicableAddOns     []string       `json:"applicableAddOns"`
	ValidUntil           *time.Time     `json:"validUntil"`
	Status               *CouponStatus  `json:"status"`
	Metadata             map[string]any `json:"metadata"`
}

type UpdateCustomerRequest struct {
	Email          *string         `json:"email,omitempty"          validate:"omitempty,email"`
	Name           *string         `json:"name,omitempty"`
	Phone          *string         `json:"phone,omitempty"`
	TaxID          *string         `json:"taxId,omitempty"`
	TaxExempt      *bool           `json:"taxExempt,omitempty"`
	BillingAddress *BillingAddress `json:"billingAddress,omitempty"`
	Metadata       map[string]any  `json:"metadata,omitempty"`
}

type UpdateExchangeRateRequest struct {
	Rate       *float64   `json:"rate"`
	ValidUntil *time.Time `json:"validUntil"`
}

type UpdateFeatureRequest struct {
	Name         *string        `json:"name,omitempty"         validate:"omitempty,min=1,max=100"`
	Description  *string        `json:"description,omitempty"  validate:"omitempty,max=1000"`
	Unit         *string        `json:"unit,omitempty"         validate:"omitempty,max=50"`
	ResetPeriod  *ResetPeriod   `json:"resetPeriod,omitempty"`
	IsPublic     *bool          `json:"isPublic,omitempty"`
	DisplayOrder *int           `json:"displayOrder,omitempty"`
	Icon         *string        `json:"icon,omitempty"         validate:"omitempty,max=100"`
	Metadata     map[string]any `json:"metadata,omitempty"`
	Tiers        []FeatureTier  `json:"tiers,omitempty"`
}

type UpdateLinkRequest struct {
	Value            *string        `json:"value,omitempty"`
	IsBlocked        *bool          `json:"isBlocked,omitempty"`
	IsHighlighted    *bool          `json:"isHighlighted,omitempty"`
	OverrideSettings map[string]any `json:"overrideSettings,omitempty"`
}

type UpdatePlanRequest struct {
	Name         *string        `json:"name,omitempty"         validate:"omitempty,min=1,max=100"`
	Description  *string        `json:"description,omitempty"  validate:"omitempty,max=1000"`
	BasePrice    *int64         `json:"basePrice,omitempty"    validate:"omitempty,min=0"`
	TrialDays    *int           `json:"trialDays,omitempty"    validate:"omitempty,min=0,max=365"`
	Features     []PlanFeature  `json:"features,omitempty"`
	PriceTiers   []PriceTier    `json:"priceTiers,omitempty"`
	TierMode     *TierMode      `json:"tierMode,omitempty"`
	Metadata     map[string]any `json:"metadata,omitempty"`
	IsActive     *bool          `json:"isActive,omitempty"`
	IsPublic     *bool          `json:"isPublic,omitempty"`
	DisplayOrder *int           `json:"displayOrder,omitempty"`
}

type UpdateSubscriptionRequest struct {
	PlanID   *xid.ID        `json:"planId,omitempty"`
	Quantity *int           `json:"quantity,omitempty" validate:"omitempty,min=1"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type UpdateTaxRateRequest struct {
	Name        *string      `json:"name"`
	Description *string      `json:"description"`
	Percentage  *float64     `json:"percentage"`
	Behavior    *TaxBehavior `json:"behavior"`
	IsDefault   *bool        `json:"isDefault"`
	IsActive    *bool        `json:"isActive"`
	ValidUntil  *time.Time   `json:"validUntil"`
}

type UsageAction string

type UsageLimit struct {
	MetricKey      string  `json:"metricKey"`
	CurrentUsage   int64   `json:"currentUsage"`
	Limit          int64   `json:"limit"`          // -1 for unlimited
	RemainingUsage int64   `json:"remainingUsage"` // -1 for unlimited
	IsExceeded     bool    `json:"isExceeded"`
	PercentUsed    float64 `json:"percentUsed"`
}

type UsageMetric struct {
	Key           string `json:"key"`           // Metric identifier
	Name          string `json:"name"`          // Display name
	Description   string `json:"description"`   // Description
	Unit          string `json:"unit"`          // Unit of measurement (e.g., "calls", "GB")
	AggregateType string `json:"aggregateType"` // "sum", "max", "last_during_period"
}

type UsageRecord struct {
	ID               xid.ID         `json:"id"`
	SubscriptionID   xid.ID         `json:"subscriptionId"`   // Related subscription
	OrganizationID   xid.ID         `json:"organizationId"`   // Organization for quick queries
	MetricKey        string         `json:"metricKey"`        // Usage metric identifier (e.g., "api_calls", "storage_gb")
	Quantity         int64          `json:"quantity"`         // Usage amount
	Action           UsageAction    `json:"action"`           // set, increment, decrement
	Timestamp        time.Time      `json:"timestamp"`        // When the usage occurred
	IdempotencyKey   string         `json:"idempotencyKey"`   // For deduplication
	Metadata         map[string]any `json:"metadata"`         // Additional context
	ProviderRecordID string         `json:"providerRecordId"` // Stripe Usage Record ID
	Reported         bool           `json:"reported"`         // Has been reported to provider
	ReportedAt       *time.Time     `json:"reportedAt"`       // When reported to provider
	CreatedAt        time.Time      `json:"createdAt"`
}

type UsageSnapshot struct {
	MetricKey    string    `json:"metricKey"`
	CurrentValue int64     `json:"currentValue"`
	Limit        int64     `json:"limit"`
	PercentUsed  float64   `json:"percentUsed"`
	Timestamp    time.Time `json:"timestamp"`
}

type UsageStats struct {
	TotalUsage   int64   `json:"totalUsage"`
	TotalOrgs    int     `json:"totalOrgs"`
	AverageUsage float64 `json:"averageUsage"`
}

type UsageSummary struct {
	MetricKey     string    `json:"metricKey"`
	TotalQuantity int64     `json:"totalQuantity"`
	PeriodStart   time.Time `json:"periodStart"`
	PeriodEnd     time.Time `json:"periodEnd"`
	RecordCount   int64     `json:"recordCount"`
	FirstRecordAt time.Time `json:"firstRecordAt"`
	LastRecordAt  time.Time `json:"lastRecordAt"`
}

type UsageTrend struct {
	Date   time.Time `json:"date"`
	Usage  int64     `json:"usage"`
	Action string    `json:"action"`
}

type VATValidationResult struct {
	Valid       bool   `json:"valid"`
	CountryCode string `json:"countryCode"`
	VATNumber   string `json:"vatNumber"`
	Name        string `json:"name"`
	Address     string `json:"address"`
	Message     string `json:"message"`
}

type ValidateCouponRequest struct {
	Code           string `json:"code"           validate:"required"`
	OrganizationID xid.ID `json:"organizationId" validate:"required"`
	PlanSlug       string `json:"planSlug"`
	AddOnSlug      string `json:"addOnSlug"`
	PurchaseAmount int64  `json:"purchaseAmount"`
}

type ValidateCouponResponse struct {
	Valid           bool     `json:"valid"`
	Coupon          *Coupon  `json:"coupon,omitempty"`
	DiscountAmount  int64    `json:"discountAmount"`
	DiscountPercent float64  `json:"discountPercent"`
	Message         string   `json:"message"`
	Errors          []string `json:"errors,omitempty"`
}