dto

type AddSchedulePhaseRequest struct {
	Phase SubscriptionSchedulePhaseInput `json:"phase" validate:"required"`
}

type Address struct {
	Line1      string `json:"address_line1" validate:"omitempty,max=255"`
	Line2      string `json:"address_line2" validate:"omitempty,max=255"`
	City       string `json:"address_city" validate:"omitempty,max=100"`
	State      string `json:"address_state" validate:"omitempty,max=100"`
	PostalCode string `json:"address_postal_code" validate:"omitempty,max=20"`
	Country    string `json:"address_country" validate:"omitempty,len=2,iso3166_1_alpha2"`
}

type AggregatedEntitlement struct {
	IsEnabled        bool                `json:"is_enabled"`
	UsageLimit       *int64              `json:"usage_limit,omitempty"`
	IsSoftLimit      bool                `json:"is_soft_limit"`
	UsageResetPeriod types.BillingPeriod `json:"usage_reset_period,omitempty"`
	StaticValues     []string            `json:"static_values,omitempty"` // For static/SLA features
}

type AggregatedFeature struct {
	Feature     *FeatureResponse       `json:"feature"`
	Entitlement *AggregatedEntitlement `json:"entitlement"`
	Sources     []*EntitlementSource   `json:"sources"`
}

type AssignTenantRequest struct {
	UserID   string `json:"user_id" validate:"required,uuid"`
	TenantID string `json:"tenant_id" validate:"required,uuid"`
}

type AuthResponse struct {
	Token    string `json:"token"`
	UserID   string `json:"user_id"`
	TenantID string `json:"tenant_id"`
}

type BillingPeriodInfo struct {
	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time"`
	Period    string    `json:"period"` // e.g., "monthly", "yearly"
}

type BulkIngestEventRequest struct {
	Events []*IngestEventRequest `json:"events" validate:"required,min=1,max=1000"`
}

type CalculateROIRequest struct {
	// SubscriptionID is required to get subscription details
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// MeterID references the meter to track usage
	MeterID string `json:"meter_id,omitempty"`

	// PriceID references the price configuration
	PriceID string `json:"price_id,omitempty"`

	// Optional time range. If not provided, uses entire subscription period
	PeriodStart *time.Time `json:"period_start,omitempty"`
	PeriodEnd   *time.Time `json:"period_end,omitempty"`
}

type CostBreakdownItem struct {
	// MeterID identifies the usage meter
	MeterID string `json:"meter_id"`

	// MeterName is the display name of the meter
	MeterName string `json:"meter_name"`

	// Usage is the quantity consumed
	Usage decimal.Decimal `json:"usage"`

	// Cost is the calculated cost for this meter
	Cost decimal.Decimal `json:"cost"`
}

type CostBreakdownResponse struct {
	// TotalCost is the sum of all meter costs
	TotalCost decimal.Decimal `json:"total_cost"`

	// Items contains the breakdown by meter
	Items []CostBreakdownItem `json:"items"`
}

type CostBreakup struct {
	// EffectiveUnitCost is the per-unit cost based on the applicable tier
	EffectiveUnitCost decimal.Decimal
	// SelectedTierIndex is the index of the tier that was applied (-1 if no tiers)
	SelectedTierIndex int
	// TierUnitAmount is the unit amount of the selected tier
	TierUnitAmount decimal.Decimal
	// FinalCost is the total cost for the quantity
	FinalCost decimal.Decimal
}

type CostSheetResponse struct {
	ID        string       `json:"id"`
	MeterID   string       `json:"meter_id"`
	PriceID   string       `json:"price_id"`
	Status    types.Status `json:"status"`
	CreatedAt time.Time    `json:"created_at"`
	UpdatedAt time.Time    `json:"updated_at"`
}

type CreateAPIKeyRequest struct {
	Name        string           `json:"name" binding:"required" validate:"required"`
	Type        types.SecretType `json:"type" binding:"required" validate:"required"`
	Permissions []string         `json:"permissions"`
	ExpiresAt   *time.Time       `json:"expires_at,omitempty"`
}

type CreateAPIKeyResponse struct {
	Secret SecretResponse `json:"secret"`
	APIKey string         `json:"api_key,omitempty"`
}

type CreateCostSheetRequest struct {
	// MeterID references the meter to track usage
	MeterID string `json:"meter_id" validate:"required"`

	// PriceID references the price configuration
	PriceID string `json:"price_id" validate:"required"`
}

type CreateCreditGrantRequest struct {
	Name                   string                               `json:"name" binding:"required"`
	Scope                  types.CreditGrantScope               `json:"scope" binding:"required"`
	PlanID                 *string                              `json:"plan_id,omitempty"`
	SubscriptionID         *string                              `json:"subscription_id,omitempty"`
	Credits                decimal.Decimal                      `json:"credits" binding:"required"`
	Cadence                types.CreditGrantCadence             `json:"cadence" binding:"required"`
	Period                 *types.CreditGrantPeriod             `json:"period,omitempty"`
	PeriodCount            *int                                 `json:"period_count,omitempty"`
	ExpirationType         types.CreditGrantExpiryType          `json:"expiration_type,omitempty"`
	ExpirationDuration     *int                                 `json:"expiration_duration,omitempty"`
	ExpirationDurationUnit *types.CreditGrantExpiryDurationUnit `json:"expiration_duration_unit,omitempty"`
	Priority               *int                                 `json:"priority,omitempty"`
	Metadata               types.Metadata                       `json:"metadata,omitempty"`
}

type CreateCreditNoteLineItemRequest struct {
	// invoice_line_item_id is the unique identifier of the invoice line item being credited
	InvoiceLineItemID string `json:"invoice_line_item_id" validate:"required"`

	// display_name is an optional human-readable name for this credit note line item
	DisplayName string `json:"display_name" validate:"omitempty"`

	// amount is the monetary amount to be credited for this line item
	Amount decimal.Decimal `json:"amount" validate:"required"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata" validate:"omitempty"`
}

type CreateCreditNoteRequest struct {
	// credit_note_number is an optional human-readable identifier for the credit note
	CreditNoteNumber string `json:"credit_note_number" validate:"omitempty"`

	// invoice_id is the unique identifier of the invoice this credit note is applied to
	InvoiceID string `json:"invoice_id" validate:"required"`

	// memo is an optional free-text field for additional notes about the credit note
	Memo string `json:"memo" validate:"omitempty"`

	// reason specifies the reason for creating this credit note (duplicate, fraudulent, order_change, product_unsatisfactory)
	Reason types.CreditNoteReason `json:"reason" validate:"required"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata" validate:"omitempty"`

	// line_items contains the individual line items that make up this credit note (minimum 1 required)
	LineItems []CreateCreditNoteLineItemRequest `json:"line_items"`

	// idempotency_key is an optional key used to prevent duplicate credit note creation
	IdempotencyKey *string `json:"idempotency_key" validate:"omitempty"`

	// process_credit_note is a flag to process the credit note after creation
	ProcessCreditNote bool `json:"process_credit_note" validate:"omitempty" default:"true"`
}

type CreateCustomerRequest struct {
	ExternalID        string            `json:"external_id" validate:"required"`
	Name              string            `json:"name"`
	Email             string            `json:"email" validate:"omitempty,email"`
	AddressLine1      string            `json:"address_line1" validate:"omitempty,max=255"`
	AddressLine2      string            `json:"address_line2" validate:"omitempty,max=255"`
	AddressCity       string            `json:"address_city" validate:"omitempty,max=100"`
	AddressState      string            `json:"address_state" validate:"omitempty,max=100"`
	AddressPostalCode string            `json:"address_postal_code" validate:"omitempty,max=20"`
	AddressCountry    string            `json:"address_country" validate:"omitempty,len=2,iso3166_1_alpha2"`
	Metadata          map[string]string `json:"metadata,omitempty"`
}

type CreateEntitlementRequest struct {
	PlanID           string              `json:"plan_id,omitempty"`
	FeatureID        string              `json:"feature_id" binding:"required"`
	FeatureType      types.FeatureType   `json:"feature_type" binding:"required"`
	IsEnabled        bool                `json:"is_enabled"`
	UsageLimit       *int64              `json:"usage_limit"`
	UsageResetPeriod types.BillingPeriod `json:"usage_reset_period"`
	IsSoftLimit      bool                `json:"is_soft_limit"`
	StaticValue      string              `json:"static_value"`
}

type CreateEnvironmentRequest struct {
	Name string `json:"name" validate:"required"`
	Type string `json:"type" validate:"required"`
}

type CreateFeatureRequest struct {
	Name         string              `json:"name" binding:"required"`
	Description  string              `json:"description"`
	LookupKey    string              `json:"lookup_key"`
	Type         types.FeatureType   `json:"type" binding:"required"`
	MeterID      string              `json:"meter_id,omitempty"`
	Meter        *CreateMeterRequest `json:"meter,omitempty"`
	Metadata     types.Metadata      `json:"metadata,omitempty"`
	UnitSingular string              `json:"unit_singular,omitempty"`
	UnitPlural   string              `json:"unit_plural,omitempty"`
}

type CreateIntegrationRequest struct {
	Name        string               `json:"name" binding:"required"`
	Provider    types.SecretProvider `json:"provider" binding:"required"`
	Credentials map[string]string    `json:"credentials" binding:"required"`
}

type CreateInvoiceLineItemRequest struct {
	// price_id is the optional unique identifier of the price associated with this line item
	PriceID *string `json:"price_id,omitempty"`

	// plan_id is the optional unique identifier of the plan associated with this line item
	PlanID *string `json:"plan_id,omitempty"`

	// plan_display_name is the optional human-readable name of the plan
	PlanDisplayName *string `json:"plan_display_name,omitempty"`

	// price_type indicates the type of pricing (fixed, usage, tiered, etc.)
	PriceType *string `json:"price_type,omitempty"`

	// meter_id is the optional unique identifier of the meter used for usage tracking
	MeterID *string `json:"meter_id,omitempty"`

	// meter_display_name is the optional human-readable name of the meter
	MeterDisplayName *string `json:"meter_display_name,omitempty"`

	// display_name is the optional human-readable name for this line item
	DisplayName *string `json:"display_name,omitempty"`

	// amount is the monetary amount for this line item
	Amount decimal.Decimal `json:"amount" validate:"required"`

	// quantity is the quantity of units for this line item
	Quantity decimal.Decimal `json:"quantity" validate:"required"`

	// period_start is the optional start date of the period this line item covers
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period this line item covers
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata,omitempty"`
}

type CreateInvoiceRequest struct {
	// invoice_number is an optional human-readable identifier for the invoice
	InvoiceNumber *string `json:"invoice_number,omitempty"`

	// customer_id is the unique identifier of the customer this invoice belongs to
	CustomerID string `json:"customer_id" validate:"required"`

	// subscription_id is the optional unique identifier of the subscription associated with this invoice
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// idempotency_key is an optional key used to prevent duplicate invoice creation
	IdempotencyKey *string `json:"idempotency_key"`

	// invoice_type indicates the type of invoice (subscription, one_time, etc.)
	InvoiceType types.InvoiceType `json:"invoice_type"`

	// currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice
	Currency string `json:"currency" validate:"required"`

	// amount_due is the total amount that needs to be paid for this invoice
	AmountDue decimal.Decimal `json:"amount_due" validate:"required"`

	// total is the total amount of the invoice including taxes and discounts
	Total decimal.Decimal `json:"total" validate:"required"`

	// subtotal is the amount before taxes and discounts are applied
	Subtotal decimal.Decimal `json:"subtotal" validate:"required"`

	// description is an optional text description of the invoice
	Description string `json:"description,omitempty"`

	// due_date is the date by which payment is expected
	DueDate *time.Time `json:"due_date,omitempty"`

	// billing_period is the period this invoice covers (e.g., "monthly", "yearly")
	BillingPeriod *string `json:"billing_period,omitempty"`

	// period_start is the start date of the billing period
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the end date of the billing period
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// billing_reason indicates why this invoice was created (subscription_cycle, manual, etc.)
	BillingReason types.InvoiceBillingReason `json:"billing_reason"`

	// invoice_status represents the current status of the invoice (draft, finalized, etc.)
	InvoiceStatus *types.InvoiceStatus `json:"invoice_status,omitempty"`

	// payment_status represents the payment status of the invoice (unpaid, paid, etc.)
	PaymentStatus *types.PaymentStatus `json:"payment_status,omitempty"`

	// amount_paid is the amount that has been paid towards this invoice
	AmountPaid *decimal.Decimal `json:"amount_paid,omitempty"`

	// line_items contains the individual items that make up this invoice
	LineItems []CreateInvoiceLineItemRequest `json:"line_items,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata,omitempty"`

	// environment_id is the unique identifier of the environment this invoice belongs to
	EnvironmentID string `json:"environment_id,omitempty"`

	// invoice_pdf_url is the URL where customers can download the PDF version of this invoice
	InvoicePDFURL *string `json:"invoice_pdf_url,omitempty"`
}

type CreateMeterRequest struct {
	Name        string            `json:"name" binding:"required" example:"API Usage Meter"`
	EventName   string            `json:"event_name" binding:"required" example:"api_request"`
	Aggregation meter.Aggregation `json:"aggregation" binding:"required"`
	Filters     []meter.Filter    `json:"filters"`
	ResetUsage  types.ResetUsage  `json:"reset_usage" binding:"required"`
}

type CreatePaymentRequest struct {
	IdempotencyKey    string                       `json:"idempotency_key,omitempty"`
	DestinationType   types.PaymentDestinationType `json:"destination_type" binding:"required"`
	DestinationID     string                       `json:"destination_id" binding:"required"`
	PaymentMethodType types.PaymentMethodType      `json:"payment_method_type" binding:"required"`
	PaymentMethodID   string                       `json:"payment_method_id"`
	Amount            decimal.Decimal              `json:"amount" binding:"required"`
	Currency          string                       `json:"currency" binding:"required"`
	Metadata          types.Metadata               `json:"metadata,omitempty"`
	ProcessPayment    bool                         `json:"process_payment" default:"true"`
}

type CreatePlanEntitlementRequest struct {
	*CreateEntitlementRequest
}

type CreatePlanPriceRequest struct {
	*CreatePriceRequest
}

type CreatePlanRequest struct {
	Name         string                         `json:"name" validate:"required"`
	LookupKey    string                         `json:"lookup_key"`
	Description  string                         `json:"description"`
	Prices       []CreatePlanPriceRequest       `json:"prices"`
	Entitlements []CreatePlanEntitlementRequest `json:"entitlements"`
	CreditGrants []CreateCreditGrantRequest     `json:"credit_grants"`
}

type CreatePlanResponse struct {
	*plan.Plan
}

type CreatePriceRequest struct {
	Amount             string                   `json:"amount"`
	Currency           string                   `json:"currency" validate:"required,len=3"`
	PlanID             string                   `json:"plan_id,omitempty"`
	Type               types.PriceType          `json:"type" validate:"required"`
	BillingPeriod      types.BillingPeriod      `json:"billing_period" validate:"required"`
	BillingPeriodCount int                      `json:"billing_period_count" validate:"required,min=1"`
	BillingModel       types.BillingModel       `json:"billing_model" validate:"required"`
	BillingCadence     types.BillingCadence     `json:"billing_cadence" validate:"required"`
	MeterID            string                   `json:"meter_id,omitempty"`
	FilterValues       map[string][]string      `json:"filter_values,omitempty"`
	LookupKey          string                   `json:"lookup_key,omitempty"`
	InvoiceCadence     types.InvoiceCadence     `json:"invoice_cadence" validate:"required"`
	TrialPeriod        int                      `json:"trial_period"`
	Description        string                   `json:"description,omitempty"`
	Metadata           map[string]string        `json:"metadata,omitempty"`
	TierMode           types.BillingTier        `json:"tier_mode,omitempty"`
	Tiers              []CreatePriceTier        `json:"tiers,omitempty"`
	TransformQuantity  *price.TransformQuantity `json:"transform_quantity,omitempty"`
}

type CreatePriceTier struct {
	UpTo       *uint64 `json:"up_to"`
	UnitAmount string  `json:"unit_amount" validate:"required"`
	FlatAmount *string `json:"flat_amount" validate:"omitempty"`
}

type CreateSubscriptionInvoiceRequest struct {
	// subscription_id is the unique identifier of the subscription to create an invoice for
	SubscriptionID string `json:"subscription_id" binding:"required"`

	// period_start is the start date of the billing period for this invoice
	PeriodStart time.Time `json:"period_start" binding:"required"`

	// period_end is the end date of the billing period for this invoice
	PeriodEnd time.Time `json:"period_end" binding:"required"`

	// is_preview indicates whether this is a preview invoice (not saved to database)
	IsPreview bool `json:"is_preview"`

	// reference_point defines the point in time used for calculating usage and charges
	ReferencePoint types.InvoiceReferencePoint `json:"reference_point"`
}

type CreateSubscriptionRequest struct {

	// customer_id is the flexprice customer id
	// and it is prioritized over external_customer_id in case both are provided.
	CustomerID string `json:"customer_id"`
	// external_customer_id is the customer id in your DB
	// and must be same as what you provided as external_id while creating the customer in flexprice.
	ExternalCustomerID string               `json:"external_customer_id"`
	PlanID             string               `json:"plan_id" validate:"required"`
	Currency           string               `json:"currency" validate:"required,len=3"`
	LookupKey          string               `json:"lookup_key"`
	StartDate          time.Time            `json:"start_date" validate:"required"`
	EndDate            *time.Time           `json:"end_date,omitempty"`
	TrialStart         *time.Time           `json:"trial_start,omitempty"`
	TrialEnd           *time.Time           `json:"trial_end,omitempty"`
	BillingCadence     types.BillingCadence `json:"billing_cadence" validate:"required"`
	BillingPeriod      types.BillingPeriod  `json:"billing_period" validate:"required"`
	BillingPeriodCount int                  `json:"billing_period_count" validate:"required,min=1"`
	Metadata           map[string]string    `json:"metadata,omitempty"`
	// BillingCycle is the cycle of the billing anchor.
	// This is used to determine the billing date for the subscription (i.e set the billing anchor)
	// If not set, the default value is anniversary. Possible values are anniversary and calendar.
	// Anniversary billing means the billing anchor will be the start date of the subscription.
	// Calendar billing means the billing anchor will be the appropriate date based on the billing period.
	// For example, if the billing period is month and the start date is 2025-04-15 then in case of
	// calendar billing the billing anchor will be 2025-05-01 vs 2025-04-15 for anniversary billing.
	BillingCycle types.BillingCycle `json:"billing_cycle"`
	// Credit grants to be applied when subscription is created
	CreditGrants []CreateCreditGrantRequest `json:"credit_grants,omitempty"`
	// CommitmentAmount is the minimum amount a customer commits to paying for a billing period
	CommitmentAmount *decimal.Decimal `json:"commitment_amount,omitempty"`
	// OverageFactor is a multiplier applied to usage beyond the commitment amount
	OverageFactor *decimal.Decimal `json:"overage_factor,omitempty"`
	// Phases represents an optional timeline of subscription phases
	Phases []SubscriptionSchedulePhaseInput `json:"phases,omitempty" validate:"omitempty,dive"`
}

type CreateSubscriptionScheduleRequest struct {
	SubscriptionID string                           `json:"subscription_id" validate:"required"`
	EndBehavior    types.ScheduleEndBehavior        `json:"end_behavior"`
	Phases         []SubscriptionSchedulePhaseInput `json:"phases" validate:"required,min=1,dive"`
}

type CreateTaskRequest struct {
	TaskType   types.TaskType         `json:"task_type" binding:"required"`
	EntityType types.EntityType       `json:"entity_type" binding:"required"`
	FileURL    string                 `json:"file_url" binding:"required"`
	FileName   *string                `json:"file_name,omitempty"`
	FileType   types.FileType         `json:"file_type" binding:"required"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
}

type CreateTenantRequest struct {
	Name           string                `json:"name" validate:"required"`
	BillingDetails *TenantBillingDetails `json:"billing_details,omitempty"`
	ID             string                `json:"-"`
}

type CreateWalletRequest struct {
	CustomerID string `json:"customer_id,omitempty"`

	// external_customer_id is the customer id in the external system
	ExternalCustomerID  string                 `json:"external_customer_id,omitempty"`
	Name                string                 `json:"name,omitempty"`
	Currency            string                 `json:"currency" binding:"required"`
	Description         string                 `json:"description,omitempty"`
	Metadata            types.Metadata         `json:"metadata,omitempty"`
	AutoTopupTrigger    types.AutoTopupTrigger `json:"auto_topup_trigger,omitempty"`
	AutoTopupMinBalance decimal.Decimal        `json:"auto_topup_min_balance,omitempty"`
	AutoTopupAmount     decimal.Decimal        `json:"auto_topup_amount,omitempty"`
	WalletType          types.WalletType       `json:"wallet_type"`
	Config              *types.WalletConfig    `json:"config,omitempty"`
	// amount in the currency =  number of credits * conversion_rate
	// ex if conversion_rate is 1, then 1 USD = 1 credit
	// ex if conversion_rate is 2, then 1 USD = 0.5 credits
	// ex if conversion_rate is 0.5, then 1 USD = 2 credits
	ConversionRate decimal.Decimal `json:"conversion_rate" default:"1"`
	// initial_credits_to_load is the number of credits to load to the wallet
	// if not provided, the wallet will be created with 0 balance
	// NOTE: this is not the amount in the currency, but the number of credits
	InitialCreditsToLoad decimal.Decimal `json:"initial_credits_to_load,omitempty" default:"0"`
	// initial_credits_to_load_expiry_date YYYYMMDD format in UTC timezone (optional to set nil means no expiry)
	// for ex 20250101 means the credits will expire on 2025-01-01 00:00:00 UTC
	// hence they will be available for use until 2024-12-31 23:59:59 UTC
	InitialCreditsToLoadExpiryDate *int `json:"initial_credits_to_load_expiry_date,omitempty"`

	// initial_credits_expiry_date_utc is the expiry date in UTC timezone (optional to set nil means no expiry)
	// ex 2025-01-01 00:00:00 UTC
	InitialCreditsExpiryDateUTC *time.Time `json:"initial_credits_expiry_date_utc,omitempty"`
}

type CreditGrantResponse struct {
	*creditgrant.CreditGrant
}

type CreditNoteResponse struct {
	*creditnote.CreditNote

	// invoice contains the associated invoice information if requested
	Invoice *InvoiceResponse `json:"invoice,omitempty"`

	// subscription contains the associated subscription information if applicable
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// customer contains the customer information associated with this credit note
	Customer *customer.Customer `json:"customer,omitempty"`
}

type CustomerEntitlementsResponse struct {
	CustomerID string               `json:"customer_id"`
	Features   []*AggregatedFeature `json:"features"`
}

type CustomerInvoiceSummary struct {
	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id"`

	// currency is the three-letter ISO currency code for this summary
	Currency string `json:"currency"`

	// total_revenue_amount is the total revenue generated from this customer in this currency
	TotalRevenueAmount decimal.Decimal `json:"total_revenue_amount"`

	// total_unpaid_amount is the total amount of unpaid invoices in this currency
	TotalUnpaidAmount decimal.Decimal `json:"total_unpaid_amount"`

	// total_overdue_amount is the total amount of overdue invoices in this currency
	TotalOverdueAmount decimal.Decimal `json:"total_overdue_amount"`

	// total_invoice_count is the total number of invoices for this customer in this currency
	TotalInvoiceCount int `json:"total_invoice_count"`

	// unpaid_invoice_count is the number of unpaid invoices for this customer in this currency
	UnpaidInvoiceCount int `json:"unpaid_invoice_count"`

	// overdue_invoice_count is the number of overdue invoices for this customer in this currency
	OverdueInvoiceCount int `json:"overdue_invoice_count"`

	// unpaid_usage_charges is the total amount of unpaid usage-based charges in this currency
	UnpaidUsageCharges decimal.Decimal `json:"unpaid_usage_charges"`

	// unpaid_fixed_charges is the total amount of unpaid fixed charges in this currency
	UnpaidFixedCharges decimal.Decimal `json:"unpaid_fixed_charges"`
}

type CustomerMultiCurrencyInvoiceSummary struct {
	// customer_id is the unique identifier of the customer
	CustomerID string `json:"customer_id"`

	// default_currency is the primary currency for this customer
	DefaultCurrency string `json:"default_currency"`

	// summaries contains the invoice summaries for each currency
	Summaries []*CustomerInvoiceSummary `json:"summaries"`
}

type CustomerResponse struct {
	*customer.Customer
}

type CustomerUsageSummaryResponse struct {
	CustomerID string                    `json:"customer_id"`
	Features   []*FeatureUsageSummary    `json:"features"`
	Period     *BillingPeriodInfo        `json:"period"`
	Pagination *types.PaginationResponse `json:"pagination,omitempty"`
}

type EntitlementResponse struct {
	*entitlement.Entitlement
	Feature *FeatureResponse `json:"feature,omitempty"`
	Plan    *PlanResponse    `json:"plan,omitempty"`
}

type EntitlementSource struct {
	SubscriptionID string `json:"subscription_id"`
	PlanID         string `json:"plan_id"`
	Quantity       int64  `json:"quantity"`
	PlanName       string `json:"plan_name"`
	EntitlementID  string `json:"entitlement_id"`
	IsEnabled      bool   `json:"is_enabled"`
	UsageLimit     *int64 `json:"usage_limit,omitempty"`
	StaticValue    string `json:"static_value,omitempty"`
}

type EnvironmentResponse struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Type      string `json:"type"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

type Event struct {
	ID                 string                 `json:"id"`
	ExternalCustomerID string                 `json:"external_customer_id"`
	CustomerID         string                 `json:"customer_id"`
	EventName          string                 `json:"event_name"`
	Timestamp          time.Time              `json:"timestamp"`
	Properties         map[string]interface{} `json:"properties"`
	Source             string                 `json:"source"`
	EnvironmentID      string                 `json:"environment_id"`
}

type ExpiredCreditsResponse struct {
	Items   []*ExpiredCreditsResponseItem `json:"items"`
	Total   int                           `json:"total"`
	Success int                           `json:"success"`
	Failed  int                           `json:"failed"`
}

type ExpiredCreditsResponseItem struct {
	TenantID string `json:"tenant_id"`
	Count    int    `json:"count"`
}

type FeatureResponse struct {
	*feature.Feature
	Meter *MeterResponse `json:"meter,omitempty"`
}

type FeatureUsageSummary struct {
	Feature      *FeatureResponse     `json:"feature"`
	TotalLimit   *int64               `json:"total_limit"`
	CurrentUsage decimal.Decimal      `json:"current_usage"`
	UsagePercent decimal.Decimal      `json:"usage_percent"`
	IsEnabled    bool                 `json:"is_enabled"`
	IsSoftLimit  bool                 `json:"is_soft_limit"`
	Sources      []*EntitlementSource `json:"sources"`
}

type GetCostBreakdownRequest struct {
	// SubscriptionID to get the time period from if StartTime and EndTime are not provided
	SubscriptionID string `json:"subscription_id" validate:"required"`

	// Optional time range. If not provided, uses subscription period
	StartTime *time.Time `json:"start_time,omitempty"`
	EndTime   *time.Time `json:"end_time,omitempty"`
}

type GetCustomerEntitlementsRequest struct {
	FeatureIDs      []string `json:"feature_ids,omitempty" form:"feature_ids"`
	SubscriptionIDs []string `json:"subscription_ids,omitempty" form:"subscription_ids"`
}

type GetCustomerUsageSummaryRequest struct {
	FeatureIDs      []string `json:"feature_ids,omitempty" form:"feature_ids"`
	SubscriptionIDs []string `json:"subscription_ids,omitempty" form:"subscription_ids"`
}

type GetCustomerWalletsRequest struct {
	ID                     string `form:"id"`
	LookupKey              string `form:"lookup_key"`
	IncludeRealTimeBalance bool   `form:"include_real_time_balance" default:"false"`
}

type GetEventsRequest struct {
	// Customer ID in your system that was sent with the event
	ExternalCustomerID string `json:"external_customer_id"`
	// Event name / Unique identifier for the event in your system
	EventName string `json:"event_name"`
	// Event ID is the idempotency key for the event
	EventID string `json:"event_id"`
	// Start time of the events to be fetched in ISO 8601 format
	// Defaults to last 7 days from now if not provided
	StartTime time.Time `json:"start_time" example:"2024-11-09T00:00:00Z"`
	// End time of the events to be fetched in ISO 8601 format
	// Defaults to now if not provided
	EndTime time.Time `json:"end_time" example:"2024-12-09T00:00:00Z"`
	// First key to iterate over the events
	IterFirstKey string `json:"iter_first_key"`
	// Last key to iterate over the events
	IterLastKey string `json:"iter_last_key"`
	// Property filters to filter the events by the keys in `properties` field of the event
	PropertyFilters map[string][]string `json:"property_filters,omitempty"`
	// Page size to fetch the events and is set to 50 by default
	PageSize int `json:"page_size"`
	// Offset to fetch the events and is set to 0 by default
	Offset int `json:"offset"`
	// Source to filter the events by the source
	Source string `json:"source"`
	// Sort by the field. Allowed values (case sensitive): timestamp, event_name (default: timestamp)
	Sort *string `json:"sort,omitempty" form:"sort" example:"timestamp"`
	// Order by condition. Allowed values (case sensitive): asc, desc (default: desc)
	Order *string `json:"order,omitempty" form:"order" example:"desc"`
	// Count of total number of events
	CountTotal bool `json:"-"`
}

type GetEventsResponse struct {
	Events       []Event `json:"events"`
	HasMore      bool    `json:"has_more"`
	IterFirstKey string  `json:"iter_first_key,omitempty"`
	IterLastKey  string  `json:"iter_last_key,omitempty"`
	TotalCount   uint64  `json:"total_count,omitempty"`
	Offset       int     `json:"offset,omitempty"`
}

type GetPreviewInvoiceRequest struct {
	// subscription_id is the unique identifier of the subscription to preview invoice for
	SubscriptionID string `json:"subscription_id" binding:"required"`

	// period_start is the optional start date of the period to preview
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period to preview
	PeriodEnd *time.Time `json:"period_end,omitempty"`
}

type GetUsageAnalyticsRequest struct {
	ExternalCustomerID string           `json:"external_customer_id" binding:"required"`
	FeatureIDs         []string         `json:"feature_ids,omitempty"`
	Sources            []string         `json:"sources,omitempty"`
	StartTime          time.Time        `json:"start_time,omitempty"`
	EndTime            time.Time        `json:"end_time,omitempty"`
	GroupBy            []string         `json:"group_by,omitempty"` // allowed values: "source", "feature_id"
	WindowSize         types.WindowSize `json:"window_size,omitempty"`
	// Property filters to filter the events by the keys in `properties` field of the event
	PropertyFilters map[string][]string `json:"property_filters,omitempty"`
}

type GetUsageAnalyticsResponse struct {
	TotalCost decimal.Decimal     `json:"total_cost"`
	Currency  string              `json:"currency"`
	Items     []UsageAnalyticItem `json:"items"`
}

type GetUsageByMeterRequest struct {
	MeterID            string              `form:"meter_id" json:"meter_id" binding:"required" example:"123"`
	Meter              *meter.Meter        `form:"-" json:"-"` // caller can set this in case already fetched from db to avoid extra db call
	ExternalCustomerID string              `form:"external_customer_id" json:"external_customer_id" example:"user_5"`
	CustomerID         string              `form:"customer_id" json:"customer_id" example:"customer456"`
	StartTime          time.Time           `form:"start_time" json:"start_time" example:"2024-11-09T00:00:00Z"`
	EndTime            time.Time           `form:"end_time" json:"end_time" example:"2024-12-09T00:00:00Z"`
	WindowSize         types.WindowSize    `form:"window_size" json:"window_size"`
	Filters            map[string][]string `form:"filters,omitempty" json:"filters,omitempty"`
	PriceID            string              `form:"-" json:"-"` // this is just for internal use to store the price id
}

type GetUsageBySubscriptionRequest struct {
	SubscriptionID string    `json:"subscription_id" binding:"required" example:"123"`
	StartTime      time.Time `json:"start_time" example:"2024-03-13T00:00:00Z"`
	EndTime        time.Time `json:"end_time" example:"2024-03-20T00:00:00Z"`
	LifetimeUsage  bool      `json:"lifetime_usage" example:"false"`
}

type GetUsageBySubscriptionResponse struct {
	Amount             float64                              `json:"amount"`
	Currency           string                               `json:"currency"`
	DisplayAmount      string                               `json:"display_amount"`
	StartTime          time.Time                            `json:"start_time"`
	EndTime            time.Time                            `json:"end_time"`
	Charges            []*SubscriptionUsageByMetersResponse `json:"charges"`
	CommitmentAmount   float64                              `json:"commitment_amount,omitempty"`
	OverageFactor      float64                              `json:"overage_factor,omitempty"`
	CommitmentUtilized float64                              `json:"commitment_utilized,omitempty"` // Amount of commitment used
	OverageAmount      float64                              `json:"overage_amount,omitempty"`      // Amount charged at overage rate
	HasOverage         bool                                 `json:"has_overage"`                   // Whether any usage exceeded commitment
}

type GetUsageRequest struct {
	ExternalCustomerID string                `form:"external_customer_id" json:"external_customer_id" example:"customer456"`
	CustomerID         string                `form:"customer_id" json:"customer_id" example:"customer456"`
	EventName          string                `form:"event_name" json:"event_name" binding:"required" required:"true" example:"api_request"`
	PropertyName       string                `form:"property_name" json:"property_name" example:"request_size"` // will be empty/ignored in case of COUNT
	AggregationType    types.AggregationType `form:"aggregation_type" json:"aggregation_type" binding:"required"`
	StartTime          time.Time             `form:"start_time" json:"start_time" example:"2024-03-13T00:00:00Z"`
	EndTime            time.Time             `form:"end_time" json:"end_time" example:"2024-03-20T00:00:00Z"`
	WindowSize         types.WindowSize      `form:"window_size" json:"window_size"`
	Filters            map[string][]string   `form:"filters,omitempty" json:"filters,omitempty"`
	PriceID            string                `form:"-" json:"-"` // this is just for internal use to store the price id
	MeterID            string                `form:"-" json:"-"` // this is just for internal use to store the meter id
	Multiplier         *decimal.Decimal      `form:"multiplier" json:"multiplier,omitempty"`
}

type GetUsageResponse struct {
	Results   []UsageResult         `json:"results,omitempty"`
	Value     float64               `json:"value,omitempty"`
	EventName string                `json:"event_name"`
	Type      types.AggregationType `json:"type"`
}

type IngestEventRequest struct {
	EventName          string                 `json:"event_name" validate:"required" binding:"required" example:"api_request" csv:"event_name"`
	EventID            string                 `json:"event_id" example:"event123" csv:"event_id"`
	CustomerID         string                 `json:"customer_id" example:"customer456" csv:"customer_id"`
	ExternalCustomerID string                 `json:"external_customer_id" validate:"required" binding:"required" example:"customer456" csv:"external_customer_id"`
	Timestamp          time.Time              `json:"timestamp" example:"2024-03-20T15:04:05Z" csv:"-"` // Handled separately due to parsing
	TimestampStr       string                 `json:"-" csv:"timestamp"`                                // Used for CSV parsing
	Source             string                 `json:"source" example:"api" csv:"source"`
	Properties         map[string]interface{} `json:"properties" swaggertype:"object,string,number" example:"{\"request_size\":100,\"response_status\":200}" csv:"-"` // Handled separately for dynamic columns
}

type InvoiceLineItemResponse struct {
	// id is the unique identifier for this line item
	ID string `json:"id"`

	// invoice_id is the unique identifier of the invoice this line item belongs to
	InvoiceID string `json:"invoice_id"`

	// customer_id is the unique identifier of the customer associated with this line item
	CustomerID string `json:"customer_id"`

	// subscription_id is the optional unique identifier of the subscription associated with this line item
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// price_id is the optional unique identifier of the price associated with this line item
	PriceID *string `json:"price_id"`

	// plan_id is the optional unique identifier of the plan associated with this line item
	PlanID *string `json:"plan_id,omitempty"`

	// plan_display_name is the optional human-readable name of the plan
	PlanDisplayName *string `json:"plan_display_name,omitempty"`

	// price_type indicates the type of pricing (fixed, usage, tiered, etc.)
	PriceType *string `json:"price_type,omitempty"`

	// meter_id is the optional unique identifier of the meter used for usage tracking
	MeterID *string `json:"meter_id,omitempty"`

	// meter_display_name is the optional human-readable name of the meter
	MeterDisplayName *string `json:"meter_display_name,omitempty"`

	// display_name is the optional human-readable name for this line item
	DisplayName *string `json:"display_name,omitempty"`

	// amount is the monetary amount for this line item
	Amount decimal.Decimal `json:"amount"`

	// quantity is the quantity of units for this line item
	Quantity decimal.Decimal `json:"quantity"`

	// currency is the three-letter ISO currency code for this line item
	Currency string `json:"currency"`

	// period_start is the optional start date of the period this line item covers
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the optional end date of the period this line item covers
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information about this line item
	Metadata types.Metadata `json:"metadata,omitempty"`

	// tenant_id is the unique identifier of the tenant this line item belongs to
	TenantID string `json:"tenant_id"`

	// status represents the current status of this line item
	Status string `json:"status"`

	// created_at is the timestamp when this line item was created
	CreatedAt time.Time `json:"created_at"`

	// updated_at is the timestamp when this line item was last updated
	UpdatedAt time.Time `json:"updated_at"`

	// created_by is the identifier of the user who created this line item
	CreatedBy string `json:"created_by,omitempty"`

	// updated_by is the identifier of the user who last updated this line item
	UpdatedBy string `json:"updated_by,omitempty"`
}

type InvoiceResponse struct {
	// id is the unique identifier for this invoice
	ID string `json:"id"`

	// customer_id is the unique identifier of the customer this invoice belongs to
	CustomerID string `json:"customer_id"`

	// subscription_id is the optional unique identifier of the subscription associated with this invoice
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// invoice_type indicates the type of invoice (subscription, one_time, etc.)
	InvoiceType types.InvoiceType `json:"invoice_type"`

	// invoice_status represents the current status of the invoice (draft, finalized, etc.)
	InvoiceStatus types.InvoiceStatus `json:"invoice_status"`

	// payment_status represents the payment status of the invoice (unpaid, paid, etc.)
	PaymentStatus types.PaymentStatus `json:"payment_status"`

	// currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice
	Currency string `json:"currency"`

	// amount_due is the total amount that needs to be paid for this invoice
	AmountDue decimal.Decimal `json:"amount_due"`

	// total is the total amount of the invoice including taxes and discounts
	Total decimal.Decimal `json:"total"`

	// subtotal is the amount before taxes and discounts are applied
	Subtotal decimal.Decimal `json:"subtotal"`

	// amount_paid is the amount that has been paid towards this invoice
	AmountPaid decimal.Decimal `json:"amount_paid"`

	// amount_remaining is the amount still outstanding on this invoice
	AmountRemaining decimal.Decimal `json:"amount_remaining"`

	// invoice_number is the optional human-readable identifier for the invoice
	InvoiceNumber *string `json:"invoice_number,omitempty"`

	// idempotency_key is the optional key used to prevent duplicate invoice creation
	IdempotencyKey *string `json:"idempotency_key,omitempty"`

	// billing_sequence is the optional sequence number for billing cycles
	BillingSequence *int `json:"billing_sequence,omitempty"`

	// description is the optional text description of the invoice
	Description string `json:"description,omitempty"`

	// due_date is the date by which payment is expected
	DueDate *time.Time `json:"due_date,omitempty"`

	// billing_period is the period this invoice covers (e.g., "monthly", "yearly")
	BillingPeriod *string `json:"billing_period,omitempty"`

	// period_start is the start date of the billing period
	PeriodStart *time.Time `json:"period_start,omitempty"`

	// period_end is the end date of the billing period
	PeriodEnd *time.Time `json:"period_end,omitempty"`

	// paid_at is the timestamp when this invoice was paid
	PaidAt *time.Time `json:"paid_at,omitempty"`

	// voided_at is the timestamp when this invoice was voided
	VoidedAt *time.Time `json:"voided_at,omitempty"`

	// finalized_at is the timestamp when this invoice was finalized
	FinalizedAt *time.Time `json:"finalized_at,omitempty"`

	// invoice_pdf_url is the optional URL to the PDF version of this invoice
	InvoicePDFURL *string `json:"invoice_pdf_url,omitempty"`

	// billing_reason indicates why this invoice was created (subscription_cycle, manual, etc.)
	BillingReason string `json:"billing_reason,omitempty"`

	// line_items contains the individual items that make up this invoice
	LineItems []*InvoiceLineItemResponse `json:"line_items,omitempty"`

	// metadata contains additional custom key-value pairs for storing extra information
	Metadata types.Metadata `json:"metadata,omitempty"`

	// version is the version number of this invoice
	Version int `json:"version"`

	// tenant_id is the unique identifier of the tenant this invoice belongs to
	TenantID string `json:"tenant_id"`

	// status represents the current status of this invoice
	Status string `json:"status"`

	// created_at is the timestamp when this invoice was created
	CreatedAt time.Time `json:"created_at"`

	// updated_at is the timestamp when this invoice was last updated
	UpdatedAt time.Time `json:"updated_at"`

	// created_by is the identifier of the user who created this invoice
	CreatedBy string `json:"created_by,omitempty"`

	// updated_by is the identifier of the user who last updated this invoice
	UpdatedBy string `json:"updated_by,omitempty"`

	// subscription contains the associated subscription information if requested
	Subscription *SubscriptionResponse `json:"subscription,omitempty"`

	// customer contains the customer information associated with this invoice
	Customer *CustomerResponse `json:"customer,omitempty"`
}

type LinkedIntegrationsResponse struct {
	Providers []string `json:"providers"`
}

type ListCostSheetsResponse struct {
	Items []CostSheetResponse `json:"items"`
	Total int                 `json:"total"`
}

type ListCreditGrantsResponse = types.ListResponse[*CreditGrantResponse]

type ListCreditNotesResponse = types.ListResponse[*CreditNoteResponse]

type ListCustomersResponse = types.ListResponse[*CustomerResponse]

type ListEntitlementsResponse = types.ListResponse[*EntitlementResponse]

type ListEnvironmentsResponse struct {
	Environments []EnvironmentResponse `json:"environments"`
	Total        int                   `json:"total"`
	Offset       int                   `json:"offset"`
	Limit        int                   `json:"limit"`
}

type ListFeaturesResponse = types.ListResponse[*FeatureResponse]

type ListInvoicesResponse = types.ListResponse[*InvoiceResponse]

type ListMetersResponse = types.ListResponse[*MeterResponse]

type ListPaymentsResponse struct {
	Items      []*PaymentResponse       `json:"items"`
	Pagination types.PaginationResponse `json:"pagination"`
}

type ListPlansResponse = types.ListResponse[*PlanResponse]

type ListPricesResponse = types.ListResponse[*PriceResponse]

type ListSecretsResponse = types.ListResponse[*SecretResponse]

type ListSubscriptionPausesResponse struct {
	Items []*SubscriptionPauseResponse `json:"items"`
	Total int                          `json:"total"`
}

type ListSubscriptionsResponse = types.ListResponse[*SubscriptionResponse]

type ListTasksResponse struct {
	Items      []*TaskResponse          `json:"items"`
	Pagination types.PaginationResponse `json:"pagination"`
}

type ListWalletTransactionsResponse = types.ListResponse[*WalletTransactionResponse]

type LoginRequest struct {
	Email    string `json:"email" binding:"required,email" validate:"email"`
	Password string `json:"password" binding:"required" validate:"min=8"`
	Token    string `json:"token" binding:"omitempty" validate:"omitempty"`
}

type MeterResponse struct {
	ID          string            `json:"id" example:"550e8400-e29b-41d4-a716-446655440000"`
	Name        string            `json:"name" example:"API Usage Meter"`
	TenantID    string            `json:"tenant_id" example:"tenant123"`
	EventName   string            `json:"event_name" example:"api_request"`
	Aggregation meter.Aggregation `json:"aggregation"`
	Filters     []meter.Filter    `json:"filters"`
	ResetUsage  types.ResetUsage  `json:"reset_usage"`
	CreatedAt   time.Time         `json:"created_at" example:"2024-03-20T15:04:05Z"`
	UpdatedAt   time.Time         `json:"updated_at" example:"2024-03-20T15:04:05Z"`
	Status      string            `json:"status" example:"published"`
}

type OnboardingEventsRequest struct {
	CustomerID     string `json:"customer_id" validate:"omitempty" example:"cus_01HKG8QWERTY123"`
	FeatureID      string `json:"feature_id" validate:"omitempty" example:"feat_01HKG8QWERTY123"`
	SubscriptionID string `json:"subscription_id" validate:"omitempty" example:"sub_01HKG8QWERTY123"`
	Duration       int    `json:"duration" validate:"omitempty,min=1,max=600" default:"60" example:"60"`
}

type OnboardingEventsResponse struct {
	Message        string    `json:"message"`
	StartedAt      time.Time `json:"started_at"`
	Duration       int       `json:"duration"`
	Count          int       `json:"count"`
	CustomerID     string    `json:"customer_id"`
	FeatureID      string    `json:"feature_id,omitempty"`
	SubscriptionID string    `json:"subscription_id,omitempty"`
}

type PauseSubscriptionRequest struct {
	PauseMode  types.PauseMode   `json:"pause_mode" validate:"required"`
	PauseStart *time.Time        `json:"pause_start,omitempty" validate:"omitempty"`
	PauseEnd   *time.Time        `json:"pause_end,omitempty" validate:"omitempty,gtfield=PauseStart"`
	PauseDays  *int              `json:"pause_days,omitempty" validate:"omitempty,gt=0"`
	Reason     string            `json:"reason,omitempty" validate:"omitempty,max=255"`
	DryRun     bool              `json:"dry_run,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

type PauseSubscriptionResponse struct {
	Subscription  *SubscriptionResponse       `json:"subscription,omitempty"`
	Pause         *SubscriptionPauseResponse  `json:"pause,omitempty"`
	BillingImpact *types.BillingImpactDetails `json:"billing_impact"`
	DryRun        bool                        `json:"dry_run"`
}

type PaymentAttemptResponse struct {
	ID            string         `json:"id"`
	PaymentID     string         `json:"payment_id"`
	AttemptNumber int            `json:"attempt_number"`
	ErrorMessage  *string        `json:"error_message,omitempty"`
	Metadata      types.Metadata `json:"metadata,omitempty"`
	TenantID      string         `json:"tenant_id"`
	CreatedAt     time.Time      `json:"created_at"`
	UpdatedAt     time.Time      `json:"updated_at"`
	CreatedBy     string         `json:"created_by"`
	UpdatedBy     string         `json:"updated_by"`
}

type PaymentResponse struct {
	ID                string                       `json:"id"`
	IdempotencyKey    string                       `json:"idempotency_key"`
	DestinationType   types.PaymentDestinationType `json:"destination_type"`
	DestinationID     string                       `json:"destination_id"`
	PaymentMethodType types.PaymentMethodType      `json:"payment_method_type"`
	PaymentMethodID   string                       `json:"payment_method_id"`
	Amount            decimal.Decimal              `json:"amount"`
	Currency          string                       `json:"currency"`
	PaymentStatus     types.PaymentStatus          `json:"payment_status"`
	TrackAttempts     bool                         `json:"track_attempts"`
	Metadata          types.Metadata               `json:"metadata,omitempty"`
	SucceededAt       *time.Time                   `json:"succeeded_at,omitempty"`
	FailedAt          *time.Time                   `json:"failed_at,omitempty"`
	RefundedAt        *time.Time                   `json:"refunded_at,omitempty"`
	ErrorMessage      *string                      `json:"error_message,omitempty"`
	Attempts          []*PaymentAttemptResponse    `json:"attempts,omitempty"`
	InvoiceNumber     *string                      `json:"invoice_number,omitempty"`
	TenantID          string                       `json:"tenant_id"`
	CreatedAt         time.Time                    `json:"created_at"`
	UpdatedAt         time.Time                    `json:"updated_at"`
	CreatedBy         string                       `json:"created_by"`
	UpdatedBy         string                       `json:"updated_by"`
}

type PlanResponse struct {
	*plan.Plan
	Prices       []*PriceResponse       `json:"prices,omitempty"`
	Entitlements []*EntitlementResponse `json:"entitlements,omitempty"`
	CreditGrants []*CreditGrantResponse `json:"credit_grants,omitempty"`
}

type PriceResponse struct {
	*price.Price
	Meter *MeterResponse `json:"meter,omitempty"`
}

type ProcessScheduledCreditGrantApplicationsResponse struct {
	SuccessApplicationsCount int `json:"success_applications_count"`
	FailedApplicationsCount  int `json:"failed_applications_count"`
	TotalApplicationsCount   int `json:"total_applications_count"`
}

type ROIResponse struct {
	// Cost and Revenue
	Cost    decimal.Decimal `json:"cost"`
	Revenue decimal.Decimal `json:"revenue"`

	// Net Revenue (Revenue - Cost)
	NetRevenue decimal.Decimal `json:"net_revenue"`

	// Markup (Revenue - Cost / Cost)
	Markup           decimal.Decimal `json:"markup"`
	MarkupPercentage decimal.Decimal `json:"markup_percentage"`

	// Net Margin (ROI)
	NetMargin           decimal.Decimal `json:"net_margin"`
	NetMarginPercentage decimal.Decimal `json:"net_margin_percentage"`

	// Cost breakdown by meter
	CostBreakdown []CostBreakdownItem `json:"cost_breakdown"`
}

type ResumeSubscriptionRequest struct {
	ResumeMode types.ResumeMode  `json:"resume_mode" validate:"required"`
	DryRun     bool              `json:"dry_run,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

type ResumeSubscriptionResponse struct {
	// Only included if not a dry run
	Subscription *SubscriptionResponse      `json:"subscription,omitempty"`
	Pause        *SubscriptionPauseResponse `json:"pause,omitempty"`

	// Billing impact details
	BillingImpact *types.BillingImpactDetails `json:"billing_impact"`

	// Whether this was a dry run
	DryRun bool `json:"dry_run"`
}

type SecretResponse struct {
	ID          string               `json:"id"`
	Name        string               `json:"name"`
	Type        types.SecretType     `json:"type"`
	Provider    types.SecretProvider `json:"provider"`
	DisplayID   string               `json:"display_id"`
	Permissions []string             `json:"permissions"`
	ExpiresAt   *time.Time           `json:"expires_at,omitempty"`
	LastUsedAt  *time.Time           `json:"last_used_at,omitempty"`
	Status      types.Status         `json:"status"`
	CreatedAt   time.Time            `json:"created_at"`
	UpdatedAt   time.Time            `json:"updated_at"`
}

type SignUpRequest struct {
	Email      string `json:"email" binding:"required,email" validate:"email"`
	Password   string `json:"password" binding:"omitempty,min=8" validate:"omitempty,min=8"`
	TenantName string `json:"tenant_name" binding:"omitempty" validate:"omitempty"`
	Token      string `json:"token" binding:"omitempty" validate:"omitempty"`
}

type SubscriptionLineItemRequest struct {
	PriceID     string            `json:"price_id" validate:"required"`
	Quantity    decimal.Decimal   `json:"quantity" validate:"required"`
	DisplayName string            `json:"display_name,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type SubscriptionLineItemResponse struct {
	*subscription.SubscriptionLineItem
}

type SubscriptionPauseResponse struct {
	*subscription.SubscriptionPause
}

type SubscriptionResponse struct {
	*subscription.Subscription
	Plan     *PlanResponse     `json:"plan"`
	Customer *CustomerResponse `json:"customer"`
	// Schedule is included when the subscription has a schedule
	Schedule *SubscriptionScheduleResponse `json:"schedule,omitempty"`
}

type SubscriptionSchedulePhaseInput struct {
	BillingCycle     types.BillingCycle            `json:"billing_cycle"`
	StartDate        time.Time                     `json:"start_date" validate:"required"`
	EndDate          *time.Time                    `json:"end_date,omitempty"`
	LineItems        []SubscriptionLineItemRequest `json:"line_items"`
	CreditGrants     []CreateCreditGrantRequest    `json:"credit_grants"`
	CommitmentAmount decimal.Decimal               `json:"commitment_amount"`
	OverageFactor    decimal.Decimal               `json:"overage_factor"`
	Metadata         map[string]string             `json:"metadata,omitempty"`
}

type SubscriptionSchedulePhaseResponse struct {
	ID               string                         `json:"id"`
	ScheduleID       string                         `json:"schedule_id"`
	PhaseIndex       int                            `json:"phase_index"`
	StartDate        time.Time                      `json:"start_date"`
	EndDate          *time.Time                     `json:"end_date,omitempty"`
	CommitmentAmount *decimal.Decimal               `json:"commitment_amount"`
	OverageFactor    *decimal.Decimal               `json:"overage_factor"`
	CreditGrants     []CreditGrantResponse          `json:"credit_grants,omitempty"`
	LineItems        []SubscriptionLineItemResponse `json:"line_items,omitempty"`
	CreatedAt        time.Time                      `json:"created_at"`
	UpdatedAt        time.Time                      `json:"updated_at"`
}

type SubscriptionScheduleResponse struct {
	ID                string                               `json:"id"`
	SubscriptionID    string                               `json:"subscription_id"`
	ScheduleStatus    types.SubscriptionScheduleStatus     `json:"status"`
	CurrentPhaseIndex int                                  `json:"current_phase_index"`
	EndBehavior       types.ScheduleEndBehavior            `json:"end_behavior"`
	StartDate         time.Time                            `json:"start_date"`
	Phases            []*SubscriptionSchedulePhaseResponse `json:"phases,omitempty"`
	CreatedAt         time.Time                            `json:"created_at"`
	UpdatedAt         time.Time                            `json:"updated_at"`
}

type SubscriptionUpdatePeriodResponse struct {
	TotalSuccess int                                     `json:"total_success"`
	TotalFailed  int                                     `json:"total_failed"`
	Items        []*SubscriptionUpdatePeriodResponseItem `json:"items"`
	StartAt      time.Time                               `json:"start_at"`
}

type SubscriptionUpdatePeriodResponseItem struct {
	SubscriptionID string    `json:"subscription_id"`
	PeriodStart    time.Time `json:"period_start"`
	PeriodEnd      time.Time `json:"period_end"`
	Success        bool      `json:"success"`
	Error          string    `json:"error"`
}

type SubscriptionUsageByMetersResponse struct {
	Amount           float64            `json:"amount"`
	Currency         string             `json:"currency"`
	DisplayAmount    string             `json:"display_amount"`
	Quantity         float64            `json:"quantity"`
	FilterValues     price.JSONBFilters `json:"filter_values"`
	MeterID          string             `json:"meter_id"`
	MeterDisplayName string             `json:"meter_display_name"`
	Price            *price.Price       `json:"price"`
	IsOverage        bool               `json:"is_overage"`               // Whether this charge is at overage rate
	OverageFactor    float64            `json:"overage_factor,omitempty"` // Factor applied to this charge if in overage
}

type SuccessResponse struct {
	Message string `json:"message"`
}

type TaskResponse struct {
	ID                string                 `json:"id"`
	TaskType          types.TaskType         `json:"task_type"`
	EntityType        types.EntityType       `json:"entity_type"`
	FileURL           string                 `json:"file_url"`
	FileName          *string                `json:"file_name,omitempty"`
	FileType          types.FileType         `json:"file_type"`
	TaskStatus        types.TaskStatus       `json:"task_status"`
	TotalRecords      *int                   `json:"total_records,omitempty"`
	ProcessedRecords  int                    `json:"processed_records"`
	SuccessfulRecords int                    `json:"successful_records"`
	FailedRecords     int                    `json:"failed_records"`
	ErrorSummary      *string                `json:"error_summary,omitempty"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
	StartedAt         *time.Time             `json:"started_at,omitempty"`
	CompletedAt       *time.Time             `json:"completed_at,omitempty"`
	FailedAt          *time.Time             `json:"failed_at,omitempty"`
	TenantID          string                 `json:"tenant_id"`
	Status            string                 `json:"status"`
	CreatedAt         time.Time              `json:"created_at"`
	UpdatedAt         time.Time              `json:"updated_at"`
	CreatedBy         string                 `json:"created_by,omitempty"`
	UpdatedBy         string                 `json:"updated_by,omitempty"`
}

type TenantBillingDetails struct {
	Email     string  `json:"email,omitempty"`
	HelpEmail string  `json:"help_email,omitempty"`
	Phone     string  `json:"phone,omitempty"`
	Address   Address `json:"address,omitempty"`
}

type TenantBillingUsage struct {
	Usage         *CustomerUsageSummaryResponse `json:"usage"`
	Subscriptions []*SubscriptionResponse       `json:"subscriptions"`
}

type TenantResponse struct {
	ID             string                `json:"id"`
	Name           string                `json:"name"`
	BillingDetails *TenantBillingDetails `json:"billing_details,omitempty"`
	Status         string                `json:"status"`
	CreatedAt      string                `json:"created_at"`
	UpdatedAt      string                `json:"updated_at"`
}

type TopUpWalletRequest struct {
	// credits_to_add is the number of credits to add to the wallet
	CreditsToAdd decimal.Decimal `json:"credits_to_add"`
	// amount is the amount in the currency of the wallet to be added
	// NOTE: this is not the number of credits to add, but the amount in the currency
	// amount = credits_to_add * conversion_rate
	// if both amount and credits_to_add are provided, amount will be ignored
	// ex if the wallet has a conversion_rate of 2 then adding an amount of
	// 10 USD in the wallet wil add 5 credits in the wallet
	Amount            decimal.Decimal         `json:"amount"`
	TransactionReason types.TransactionReason `json:"transaction_reason,omitempty" binding:"required"`
	// expiry_date YYYYMMDD format in UTC timezone (optional to set nil means no expiry)
	// for ex 20250101 means the credits will expire on 2025-01-01 00:00:00 UTC
	// hence they will be available for use until 2024-12-31 23:59:59 UTC
	ExpiryDate *int `json:"-"`
	// expiry_date_utc is the expiry date in UTC timezone
	// ex 2025-01-01 00:00:00 UTC
	ExpiryDateUTC *time.Time `json:"expiry_date_utc,omitempty"`
	// priority is the priority of the transaction
	// lower number means higher priority
	// default is nil which means no priority at all
	Priority *int `json:"priority,omitempty"`
	// idempotency_key is a unique key for the transaction
	IdempotencyKey *string `json:"idempotency_key" binding:"required"`
	// description to add any specific details about the transaction
	Description string `json:"description,omitempty"`
	// metadata is a map of key-value pairs to store any additional information about the transaction
	Metadata types.Metadata `json:"metadata,omitempty"`
}

type UpdateCostSheetRequest struct {
	// ID of the costsheet to update
	ID string `json:"id" validate:"required"`

	// Status updates the costsheet's status (optional)
	Status string `json:"status,omitempty"`
}

type UpdateCreditGrantRequest struct {
	Name     *string         `json:"name,omitempty"`
	Metadata *types.Metadata `json:"metadata,omitempty"`
}

type UpdateCustomerRequest struct {
	ExternalID        *string           `json:"external_id"`
	Name              *string           `json:"name"`
	Email             *string           `json:"email" validate:"omitempty,email"`
	AddressLine1      *string           `json:"address_line1" validate:"omitempty,max=255"`
	AddressLine2      *string           `json:"address_line2" validate:"omitempty,max=255"`
	AddressCity       *string           `json:"address_city" validate:"omitempty,max=100"`
	AddressState      *string           `json:"address_state" validate:"omitempty,max=100"`
	AddressPostalCode *string           `json:"address_postal_code" validate:"omitempty,max=20"`
	AddressCountry    *string           `json:"address_country" validate:"omitempty,len=2,iso3166_1_alpha2"`
	Metadata          map[string]string `json:"metadata,omitempty"`
}

type UpdateEntitlementRequest struct {
	IsEnabled        *bool               `json:"is_enabled"`
	UsageLimit       *int64              `json:"usage_limit"`
	UsageResetPeriod types.BillingPeriod `json:"usage_reset_period"`
	IsSoftLimit      *bool               `json:"is_soft_limit"`
	StaticValue      string              `json:"static_value"`
}

type UpdateEnvironmentRequest struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type UpdateFeatureRequest struct {
	Name         *string         `json:"name,omitempty"`
	Description  *string         `json:"description,omitempty"`
	Metadata     *types.Metadata `json:"metadata,omitempty"`
	UnitSingular *string         `json:"unit_singular,omitempty"`
	UnitPlural   *string         `json:"unit_plural,omitempty"`
	Filters      *[]meter.Filter `json:"filters,omitempty"`
}

type UpdateInvoicePaymentRequest struct {
	// payment_status is the new payment status to set for the invoice (paid, unpaid, etc.)
	PaymentStatus types.PaymentStatus `json:"payment_status" validate:"required"`
}

type UpdateMeterRequest struct {
	Filters []meter.Filter `json:"filters"`
}

type UpdatePaymentRequest struct {
	PaymentStatus *string         `json:"payment_status,omitempty"`
	Metadata      *types.Metadata `json:"metadata,omitempty"`
}

type UpdatePaymentStatusRequest struct {
	// payment_status is the new payment status to set for the invoice (paid, unpaid, etc.)
	PaymentStatus types.PaymentStatus `json:"payment_status" binding:"required"`

	// amount is the optional payment amount to record
	Amount *decimal.Decimal `json:"amount,omitempty"`
}

type UpdatePlanCreditGrantRequest struct {
	// The ID of the credit grant to update (present if the credit grant is being updated)
	ID string `json:"id,omitempty"`
	// The credit grant request to update existing credit grant or create new credit grant
	*CreateCreditGrantRequest
}

type UpdatePlanEntitlementRequest struct {
	// The ID of the entitlement to update (present if the entitlement is being updated)
	ID string `json:"id,omitempty"`
	// The entitlement request to update existing entitlement or create new entitlement
	*CreatePlanEntitlementRequest
}

type UpdatePlanPriceRequest struct {
	// The ID of the price to update (present if the price is being updated)
	ID string `json:"id,omitempty"`
	// The price request to update existing price or create new price
	*CreatePriceRequest
}

type UpdatePlanRequest struct {
	Name         *string                        `json:"name,omitempty"`
	LookupKey    *string                        `json:"lookup_key,omitempty"`
	Description  *string                        `json:"description,omitempty"`
	Prices       []UpdatePlanPriceRequest       `json:"prices,omitempty"`
	Entitlements []UpdatePlanEntitlementRequest `json:"entitlements,omitempty"`
	CreditGrants []UpdatePlanCreditGrantRequest `json:"credit_grants,omitempty"`
}

type UpdatePriceRequest struct {
	LookupKey   string            `json:"lookup_key"`
	Description string            `json:"description"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type UpdateSubscriptionRequest struct {
	Status            types.SubscriptionStatus `json:"status"`
	CancelAt          *time.Time               `json:"cancel_at,omitempty"`
	CancelAtPeriodEnd bool                     `json:"cancel_at_period_end,omitempty"`
}

type UpdateSubscriptionScheduleRequest struct {
	Status      types.SubscriptionScheduleStatus `json:"status,omitempty"`
	EndBehavior types.ScheduleEndBehavior        `json:"end_behavior,omitempty"`
}

type UpdateTaskStatusRequest struct {
	TaskStatus types.TaskStatus `json:"task_status" binding:"required"`
}

type UpdateTenantRequest struct {
	Name           string                `json:"name,omitempty"`
	BillingDetails *TenantBillingDetails `json:"billing_details,omitempty"`
	Metadata       *types.Metadata       `json:"metadata,omitempty"`
}

type UpdateWalletRequest struct {
	Name                *string                 `json:"name,omitempty"`
	Description         *string                 `json:"description,omitempty"`
	Metadata            *types.Metadata         `json:"metadata,omitempty"`
	AutoTopupTrigger    *types.AutoTopupTrigger `json:"auto_topup_trigger,omitempty"`
	AutoTopupMinBalance *decimal.Decimal        `json:"auto_topup_min_balance,omitempty"`
	AutoTopupAmount     *decimal.Decimal        `json:"auto_topup_amount,omitempty"`
	Config              *types.WalletConfig     `json:"config,omitempty"`
}

type UsageAnalyticItem struct {
	FeatureID       string                `json:"feature_id"`
	FeatureName     string                `json:"name,omitempty"`
	EventName       string                `json:"event_name,omitempty"`
	Source          string                `json:"source,omitempty"`
	Unit            string                `json:"unit,omitempty"`
	UnitPlural      string                `json:"unit_plural,omitempty"`
	AggregationType types.AggregationType `json:"aggregation_type,omitempty"`
	TotalUsage      decimal.Decimal       `json:"total_usage"`
	TotalCost       decimal.Decimal       `json:"total_cost"`
	Currency        string                `json:"currency,omitempty"`
	EventCount      uint64                `json:"event_count"` // Number of events that contributed to this aggregation
	Points          []UsageAnalyticPoint  `json:"points,omitempty"`
}

type UsageAnalyticPoint struct {
	Timestamp  time.Time       `json:"timestamp"`
	Usage      decimal.Decimal `json:"usage"`
	Cost       decimal.Decimal `json:"cost"`
	EventCount uint64          `json:"event_count"` // Number of events in this time window
}

type UsageResult struct {
	WindowSize time.Time `json:"window_size"`
	Value      float64   `json:"value"`
}

type UserResponse struct {
	ID     string          `json:"id"`
	Email  string          `json:"email"`
	Tenant *TenantResponse `json:"tenant"`
}

type WalletBalanceResponse struct {
	*wallet.Wallet
	RealTimeBalance       *decimal.Decimal `json:"real_time_balance,omitempty"`
	RealTimeCreditBalance *decimal.Decimal `json:"real_time_credit_balance,omitempty"`
	BalanceUpdatedAt      *time.Time       `json:"balance_updated_at,omitempty"`
	UnpaidInvoiceAmount   *decimal.Decimal `json:"unpaid_invoice_amount,omitempty"`
	CurrentPeriodUsage    *decimal.Decimal `json:"current_period_usage,omitempty"`
}

type WalletResponse struct {
	ID                  string                 `json:"id"`
	CustomerID          string                 `json:"customer_id"`
	Name                string                 `json:"name,omitempty"`
	Currency            string                 `json:"currency"`
	Description         string                 `json:"description,omitempty"`
	Balance             decimal.Decimal        `json:"balance"`
	CreditBalance       decimal.Decimal        `json:"credit_balance"`
	WalletStatus        types.WalletStatus     `json:"wallet_status"`
	Metadata            types.Metadata         `json:"metadata,omitempty"`
	AutoTopupTrigger    types.AutoTopupTrigger `json:"auto_topup_trigger"`
	AutoTopupMinBalance decimal.Decimal        `json:"auto_topup_min_balance"`
	AutoTopupAmount     decimal.Decimal        `json:"auto_topup_amount"`
	WalletType          types.WalletType       `json:"wallet_type"`
	Config              types.WalletConfig     `json:"config,omitempty"`
	ConversionRate      decimal.Decimal        `json:"conversion_rate"`
	CreatedAt           time.Time              `json:"created_at"`
	UpdatedAt           time.Time              `json:"updated_at"`
}

type WalletTransactionResponse struct {
	ID                  string                      `json:"id"`
	WalletID            string                      `json:"wallet_id"`
	Type                string                      `json:"type"`
	Amount              decimal.Decimal             `json:"amount"`
	CreditAmount        decimal.Decimal             `json:"credit_amount"`
	CreditBalanceBefore decimal.Decimal             `json:"credit_balance_before"`
	CreditBalanceAfter  decimal.Decimal             `json:"credit_balance_after"`
	TransactionStatus   types.TransactionStatus     `json:"transaction_status"`
	ExpiryDate          *time.Time                  `json:"expiry_date,omitempty"`
	Priority            *int                        `json:"priority,omitempty"`
	CreditsAvailable    decimal.Decimal             `json:"credits_available,omitempty"`
	TransactionReason   types.TransactionReason     `json:"transaction_reason,omitempty"`
	ReferenceType       types.WalletTxReferenceType `json:"reference_type,omitempty"`
	ReferenceID         string                      `json:"reference_id,omitempty"`
	Description         string                      `json:"description,omitempty"`
	Metadata            types.Metadata              `json:"metadata,omitempty"`
	CreatedAt           time.Time                   `json:"created_at"`
	UpdatedAt           time.Time                   `json:"updated_at"`
}