invoice

type BillingSequence struct {
	ID             string
	TenantID       string
	SubscriptionID string
	LastSequence   int
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

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

	// customer_id is the ID of the customer who will receive this invoice
	CustomerID string `json:"customer_id"`

	// subscription_id is the ID of the subscription this invoice is associated with (only present for subscription-based invoices)
	SubscriptionID *string `json:"subscription_id,omitempty"`

	// invoice_type indicates the type of invoice - whether this is a subscription invoice, one-time charge, or other billing type
	InvoiceType types.InvoiceType `json:"invoice_type"`

	// invoice_status represents the current status of the invoice - values include draft, open, paid, void, etc.
	InvoiceStatus types.InvoiceStatus `json:"invoice_status"`

	// payment_status indicates whether the invoice has been paid, is pending, or failed
	PaymentStatus types.PaymentStatus `json:"payment_status"`

	// currency is the three-letter ISO currency code (e.g., USD, EUR, GBP) that applies to all monetary amounts on this 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"`

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

	// subtotal is the sum of all line items before any taxes, discounts, or additional fees
	Subtotal decimal.Decimal `json:"subtotal"`

	// total is the final amount including taxes, fees, and discounts
	Total decimal.Decimal `json:"total"`

	// total_discount is the sum of all coupon discounts applied to the invoice
	TotalDiscount decimal.Decimal `json:"total_discount"`

	// amount_remaining is the outstanding amount still owed on this invoice (calculated as amount_due minus amount_paid)
	AmountRemaining decimal.Decimal `json:"amount_remaining"`

	// invoice_number is the human-readable invoice number displayed to customers (e.g., INV-2024-001)
	InvoiceNumber *string `json:"invoice_number"`

	// idempotency_key is a unique key used to prevent duplicate invoice creation when retrying API calls
	IdempotencyKey *string `json:"idempotency_key"`

	// billing_sequence is the sequential number indicating the billing cycle for subscription invoices
	BillingSequence *int `json:"billing_sequence"`

	// description is an optional description or notes about this invoice
	Description string `json:"description,omitempty"`

	// due_date is the date when payment for this invoice is due
	DueDate *time.Time `json:"due_date,omitempty"`

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

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

	// billing_period describes the billing period this invoice covers (e.g., "January 2024", "Q1 2024")
	BillingPeriod *string `json:"billing_period,omitempty"`

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

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

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

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

	// billing_reason indicates why this invoice was generated (e.g., "subscription_billing", "manual_charge")
	BillingReason string `json:"billing_reason,omitempty"`

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

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

	// coupon_applications contains the coupon applications that were applied to this invoice
	CouponApplications []*coupon_application.CouponApplication `json:"coupon_applications,omitempty"`

	// version is the version number for tracking changes to this invoice
	Version int `json:"version"`

	// environment_id is the ID of the environment this invoice belongs to (for multi-environment setups)
	EnvironmentID string `json:"environment_id"`

	// adjustment_amount is the total sum of credit notes of type "adjustment".
	// These are non-cash reductions applied to the invoice (e.g. goodwill credit, billing correction).
	AdjustmentAmount decimal.Decimal `json:"adjustment_amount"`

	// refunded_amount is the total sum of credit notes of type "refund".
	// These are actual refunds issued to the customer.
	RefundedAmount decimal.Decimal `json:"refunded_amount"`

	// total_tax is the sum of all taxes combined at the invoice level.
	TotalTax decimal.Decimal `json:"total_tax"`

	// common fields including tenant information, creation/update timestamps, and status
	types.BaseModel
}

type InvoiceLineItem struct {
	ID               string           `json:"id"`
	InvoiceID        string           `json:"invoice_id"`
	CustomerID       string           `json:"customer_id"`
	SubscriptionID   *string          `json:"subscription_id,omitempty"`
	EntityID         *string          `json:"entity_id,omitempty"`
	EntityType       *string          `json:"entity_type,omitempty"`
	PlanDisplayName  *string          `json:"plan_display_name,omitempty"`
	PriceID          *string          `json:"price_id,omitempty"`
	PriceType        *string          `json:"price_type,omitempty"`
	MeterID          *string          `json:"meter_id,omitempty"`
	MeterDisplayName *string          `json:"meter_display_name,omitempty"`
	PriceUnitID      *string          `json:"price_unit_id,omitempty"`
	PriceUnit        *string          `json:"price_unit,omitempty"`
	PriceUnitAmount  *decimal.Decimal `json:"price_unit_amount,omitempty"`
	DisplayName      *string          `json:"display_name,omitempty"`
	Amount           decimal.Decimal  `json:"amount"`
	Quantity         decimal.Decimal  `json:"quantity"`
	Currency         string           `json:"currency"`
	PeriodStart      *time.Time       `json:"period_start,omitempty"`
	PeriodEnd        *time.Time       `json:"period_end,omitempty"`
	Metadata         types.Metadata   `json:"metadata,omitempty"`
	EnvironmentID    string           `json:"environment_id"`
	types.BaseModel
}

type InvoiceSequence struct {
	ID        string
	TenantID  string
	YearMonth string
	LastValue int64
	CreatedAt time.Time
	UpdatedAt time.Time
}

type Repository interface {
	// Core invoice operations
	Create(ctx context.Context, inv *Invoice) error
	Get(ctx context.Context, id string) (*Invoice, error)
	Update(ctx context.Context, inv *Invoice) error
	Delete(ctx context.Context, id string) error
	List(ctx context.Context, filter *types.InvoiceFilter) ([]*Invoice, error)
	Count(ctx context.Context, filter *types.InvoiceFilter) (int, error)

	// Edge-specific operations
	AddLineItems(ctx context.Context, invoiceID string, items []*InvoiceLineItem) error
	RemoveLineItems(ctx context.Context, invoiceID string, itemIDs []string) error

	// Bulk operations with edges
	CreateWithLineItems(ctx context.Context, inv *Invoice) error

	// Idempotency operations
	GetByIdempotencyKey(ctx context.Context, key string) (*Invoice, error)

	// Period validation
	ExistsForPeriod(ctx context.Context, subscriptionID string, periodStart, periodEnd time.Time) (bool, error)

	// GetNextInvoiceNumber generates and returns the next invoice number for a tenant
	// Format: INV-YYYYMM-XXXXX
	GetNextInvoiceNumber(ctx context.Context) (string, error)

	// GetNextBillingSequence returns the next billing sequence number for a subscription
	GetNextBillingSequence(ctx context.Context, subscriptionID string) (int, error)
}