subscription

type LineItemRepository interface {
	// Core operations
	Create(ctx context.Context, item *SubscriptionLineItem) error
	Get(ctx context.Context, id string) (*SubscriptionLineItem, error)
	Update(ctx context.Context, item *SubscriptionLineItem) error
	Delete(ctx context.Context, id string) error

	// Bulk operations
	CreateBulk(ctx context.Context, items []*SubscriptionLineItem) error

	// Query operations
	ListBySubscription(ctx context.Context, subscriptionID string) ([]*SubscriptionLineItem, error)
	ListByCustomer(ctx context.Context, customerID string) ([]*SubscriptionLineItem, error)

	// Filter based operations
	List(ctx context.Context, filter *types.SubscriptionLineItemFilter) ([]*SubscriptionLineItem, error)
	Count(ctx context.Context, filter *types.SubscriptionLineItemFilter) (int, error)

	// Future extensibility
	GetByPriceID(ctx context.Context, priceID string) ([]*SubscriptionLineItem, error)
	GetByPlanID(ctx context.Context, planID string) ([]*SubscriptionLineItem, error)
}

type Repository interface {
	Create(ctx context.Context, subscription *Subscription) error
	Get(ctx context.Context, id string) (*Subscription, error)
	Update(ctx context.Context, subscription *Subscription) error
	Delete(ctx context.Context, id string) error
	List(ctx context.Context, filter *types.SubscriptionFilter) ([]*Subscription, error)
	Count(ctx context.Context, filter *types.SubscriptionFilter) (int, error)
	ListAll(ctx context.Context, filter *types.SubscriptionFilter) ([]*Subscription, error)
	ListAllTenant(ctx context.Context, filter *types.SubscriptionFilter) ([]*Subscription, error)
	ListByCustomerID(ctx context.Context, customerID string) ([]*Subscription, error)
	ListByIDs(ctx context.Context, subscriptionIDs []string) ([]*Subscription, error)
	CreateWithLineItems(ctx context.Context, subscription *Subscription, items []*SubscriptionLineItem) error
	GetWithLineItems(ctx context.Context, id string) (*Subscription, []*SubscriptionLineItem, error)

	// Pause-related methods
	CreatePause(ctx context.Context, pause *SubscriptionPause) error
	GetPause(ctx context.Context, id string) (*SubscriptionPause, error)
	UpdatePause(ctx context.Context, pause *SubscriptionPause) error
	ListPauses(ctx context.Context, subscriptionID string) ([]*SubscriptionPause, error)
	GetWithPauses(ctx context.Context, id string) (*Subscription, []*SubscriptionPause, error)
}

type SchedulePhase 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"`
	LineItems        []types.SchedulePhaseLineItem    `json:"line_items,omitempty"`
	CreditGrants     []types.SchedulePhaseCreditGrant `json:"credit_grants,omitempty"`
	Metadata         types.Metadata                   `json:"metadata,omitempty"`
	EnvironmentID    string                           `json:"environment_id"`
	types.BaseModel
}

type Subscription struct {
	// ID is the unique identifier for the subscription
	ID string `db:"id" json:"id"`

	// LookupKey is the key used to lookup the subscription in our system
	LookupKey string `db:"lookup_key" json:"lookup_key,omitempty"`

	// CustomerID is the identifier for the customer in our system
	CustomerID string `db:"customer_id" json:"customer_id"`

	// PlanID is the identifier for the plan in our system
	PlanID string `db:"plan_id" json:"plan_id"`

	SubscriptionStatus types.SubscriptionStatus `db:"subscription_status" json:"subscription_status"`

	// Currency is the currency of the subscription in lowercase 3 digit ISO codes
	Currency string `db:"currency" json:"currency"`

	// BillingAnchor is the reference point that aligns future billing cycle dates.
	// It sets the day of week for week intervals, the day of month for month and year intervals,
	// and the month of year for year intervals. The timestamp is in UTC format.
	BillingAnchor time.Time `db:"billing_anchor" json:"billing_anchor"`

	// 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 `db:"billing_cycle" json:"billing_cycle"`

	// StartDate is the start date of the subscription
	StartDate time.Time `db:"start_date" json:"start_date"`

	// EndDate is the end date of the subscription
	EndDate *time.Time `db:"end_date" json:"end_date,omitempty"`

	// CurrentPeriodStart is the end of the current period that the subscription has been invoiced for.
	// At the end of this period, a new invoice will be created.
	CurrentPeriodStart time.Time `db:"current_period_start" json:"current_period_start"`

	// CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for.
	// At the end of this period, a new invoice will be created.
	CurrentPeriodEnd time.Time `db:"current_period_end" json:"current_period_end"`

	// CanceledAt is the date the subscription was canceled
	CancelledAt *time.Time `db:"cancelled_at" json:"cancelled_at,omitempty"`

	// CancelAt is the date the subscription will be canceled
	CancelAt *time.Time `db:"cancel_at" json:"cancel_at"`

	// CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period
	CancelAtPeriodEnd bool `db:"cancel_at_period_end" json:"cancel_at_period_end"`

	// TrialStart is the start date of the trial period
	TrialStart *time.Time `db:"trial_start" json:"trial_start"`

	// TrialEnd is the end date of the trial period
	TrialEnd *time.Time `db:"trial_end" json:"trial_end"`

	BillingCadence types.BillingCadence `db:"billing_cadence" json:"billing_cadence"`

	BillingPeriod types.BillingPeriod `db:"billing_period" json:"billing_period"`

	// BillingPeriodCount is the total number units of the billing period.
	BillingPeriodCount int `db:"billing_period_count" json:"billing_period_count"`

	// Version is used for optimistic locking
	Version int `db:"version" json:"version"`

	Metadata types.Metadata `db:"metadata" json:"metadata,omitempty"`

	// EnvironmentID is the environment identifier for the subscription
	EnvironmentID string `db:"environment_id" json:"environment_id"`

	PauseStatus types.PauseStatus `db:"pause_status" json:"pause_status"`

	// ActivePauseID references the current active pause configuration
	// This will be null if no pause is active or scheduled
	ActivePauseID *string `db:"active_pause_id" json:"active_pause_id,omitempty"`

	// CommitmentAmount is the minimum amount a customer commits to paying for a billing period
	CommitmentAmount *decimal.Decimal `db:"commitment_amount" json:"commitment_amount,omitempty"`

	// OverageFactor is a multiplier applied to usage beyond the commitment amount
	OverageFactor *decimal.Decimal `db:"overage_factor" json:"overage_factor,omitempty"`

	LineItems []*SubscriptionLineItem `json:"line_items,omitempty"`

	Pauses []*SubscriptionPause `json:"pauses,omitempty"`

	CouponAssociations []*coupon_association.CouponAssociation `json:"coupon_associations,omitempty"`

	types.BaseModel
}

type SubscriptionLineItem struct {
	ID               string                                `db:"id" json:"id"`
	SubscriptionID   string                                `db:"subscription_id" json:"subscription_id"`
	CustomerID       string                                `db:"customer_id" json:"customer_id"`
	EntityID         string                                `db:"entity_id" json:"entity_id,omitempty"`
	EntityType       types.SubscriptionLineItemEntitiyType `db:"entity_type" json:"entity_type,omitempty"`
	PlanDisplayName  string                                `db:"plan_display_name" json:"plan_display_name,omitempty"`
	PriceID          string                                `db:"price_id" json:"price_id"`
	PriceType        types.PriceType                       `db:"price_type" json:"price_type,omitempty"`
	MeterID          string                                `db:"meter_id" json:"meter_id,omitempty"`
	MeterDisplayName string                                `db:"meter_display_name" json:"meter_display_name,omitempty"`
	PriceUnitID      string                                `db:"price_unit_id" json:"price_unit_id"`
	PriceUnit        string                                `db:"price_unit" json:"price_unit"`
	DisplayName      string                                `db:"display_name" json:"display_name,omitempty"`
	Quantity         decimal.Decimal                       `db:"quantity" json:"quantity"`
	Currency         string                                `db:"currency" json:"currency"`
	BillingPeriod    types.BillingPeriod                   `db:"billing_period" json:"billing_period"`
	InvoiceCadence   types.InvoiceCadence                  `db:"invoice_cadence" json:"invoice_cadence"`
	TrialPeriod      int                                   `db:"trial_period" json:"trial_period"`
	StartDate        time.Time                             `db:"start_date" json:"start_date,omitempty"`
	EndDate          time.Time                             `db:"end_date" json:"end_date,omitempty"`
	Metadata         map[string]string                     `db:"metadata" json:"metadata,omitempty"`
	EnvironmentID    string                                `db:"environment_id" json:"environment_id"`
	types.BaseModel
}

type SubscriptionPause struct {
	// ID is the unique identifier for the subscription pause
	ID string `db:"id" json:"id"`

	// SubscriptionID is the identifier for the subscription
	SubscriptionID string `db:"subscription_id" json:"subscription_id"`

	PauseStatus types.PauseStatus `db:"pause_status" json:"pause_status"`
	PauseMode   types.PauseMode   `db:"pause_mode" json:"pause_mode"`
	ResumeMode  types.ResumeMode  `db:"resume_mode" json:"resume_mode,omitempty"`

	// PauseStart is when the pause actually started
	PauseStart time.Time `db:"pause_start" json:"pause_start"`

	// PauseEnd is when the pause will end (null for indefinite)
	PauseEnd *time.Time `db:"pause_end" json:"pause_end,omitempty"`

	// ResumedAt is when the pause was actually ended (if manually resumed)
	ResumedAt *time.Time `db:"resumed_at" json:"resumed_at,omitempty"`

	// OriginalPeriodStart is the start of the billing period when the pause was created
	OriginalPeriodStart time.Time `db:"original_period_start" json:"original_period_start"`

	// OriginalPeriodEnd is the end of the billing period when the pause was created
	OriginalPeriodEnd time.Time `db:"original_period_end" json:"original_period_end"`

	// Reason is the reason for pausing
	Reason string `db:"reason" json:"reason,omitempty"`

	Metadata types.Metadata `db:"metadata" json:"metadata,omitempty"`

	// EnvironmentID is the environment identifier for the pause
	EnvironmentID string `db:"environment_id" json:"environment_id"`

	types.BaseModel
}

type SubscriptionSchedule struct {
	ID                string                           `json:"id"`
	SubscriptionID    string                           `json:"subscription_id"`
	ScheduleStatus    types.SubscriptionScheduleStatus `json:"schedule_status"`
	CurrentPhaseIndex int                              `json:"current_phase_index"`
	EndBehavior       types.ScheduleEndBehavior        `json:"end_behavior"`
	StartDate         time.Time                        `json:"start_date"`
	Metadata          types.Metadata                   `json:"metadata"`
	Phases            []*SchedulePhase                 `json:"phases,omitempty"`
	EnvironmentID     string                           `json:"environment_id"`
	types.BaseModel
}

type SubscriptionScheduleRepository interface {
	// Create creates a new subscription schedule
	Create(ctx context.Context, schedule *SubscriptionSchedule) error

	// Get retrieves a subscription schedule by ID
	Get(ctx context.Context, id string) (*SubscriptionSchedule, error)

	// GetBySubscriptionID gets a schedule for a subscription if it exists
	GetBySubscriptionID(ctx context.Context, subscriptionID string) (*SubscriptionSchedule, error)

	// Update updates a subscription schedule
	Update(ctx context.Context, schedule *SubscriptionSchedule) error

	// Delete deletes a subscription schedule
	Delete(ctx context.Context, id string) error

	// ListPhases lists all phases for a subscription schedule
	ListPhases(ctx context.Context, scheduleID string) ([]*SchedulePhase, error)

	// CreatePhase creates a new subscription schedule phase
	CreatePhase(ctx context.Context, phase *SchedulePhase) error

	// GetPhase gets a subscription schedule phase by ID
	GetPhase(ctx context.Context, id string) (*SchedulePhase, error)

	// UpdatePhase updates a subscription schedule phase
	UpdatePhase(ctx context.Context, phase *SchedulePhase) error

	// DeletePhase deletes a subscription schedule phase
	DeletePhase(ctx context.Context, id string) error

	// CreateWithPhases creates a schedule with all its phases in one transaction
	CreateWithPhases(ctx context.Context, schedule *SubscriptionSchedule, phases []*SchedulePhase) error
}