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 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"`

	// 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"`

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

	Pauses []*SubscriptionPause `json:"pauses,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"`
	PlanID           string               `db:"plan_id" json:"plan_id,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"`
	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
}