flatfee

type Adapter interface {
	ChargeAdapter
	ChargeDetailedLineAdapter
	ChargeCreditAllocationAdapter
	ChargeRunAdapter
	ChargeInvoicedUsageAdapter
	ChargePaymentAdapter

	entutils.TxCreator
}

type AdvanceChargeInput struct {
	ChargeID meta.ChargeID
}

type Charge struct {
	ChargeBase

	Realizations Realizations `json:"realizations"`
}

type ChargeAdapter interface {
	CreateCharges(ctx context.Context, charges CreateChargesInput) ([]Charge, error)

	UpdateCharge(ctx context.Context, charge ChargeBase) (ChargeBase, error)
	CreateChargeOverride(ctx context.Context, charge ChargeBase, override IntentMutableFields) (ChargeBase, error)
	DeleteChargeOverride(ctx context.Context, charge ChargeBase) (ChargeBase, error)
	UpdateSubscriptionItemID(ctx context.Context, charge Charge, newSubscriptionItemID string) (Charge, error)
	DeleteCharge(ctx context.Context, charge Charge) error
	GetByIDs(ctx context.Context, ids GetByIDsInput) ([]Charge, error)
	GetByID(ctx context.Context, id GetByIDInput) (Charge, error)
}

type ChargeBase struct {
	meta.ManagedResource

	Intent OverridableIntent `json:"intent"`
	Status Status            `json:"status"`

	State State `json:"state"`
}

type ChargeCreditAllocationAdapter interface {
	CreateCreditAllocations(ctx context.Context, runID RealizationRunID, creditAllocations creditrealization.CreateInputs) (creditrealization.Realizations, error)
}

type ChargeDetailedLineAdapter interface {
	UpsertDetailedLines(ctx context.Context, runID RealizationRunID, lines DetailedLines) error
	FetchCurrentRunDetailedLines(ctx context.Context, charge Charge) (Charge, error)
}

type ChargeInvoicedUsageAdapter interface {
	CreateInvoicedUsage(ctx context.Context, input CreateInvoicedUsageInput) (invoicedusage.AccruedUsage, error)
}

type ChargePaymentAdapter interface {
	CreatePayment(ctx context.Context, runID RealizationRunID, paymentSettlement payment.InvoicedCreate) (payment.Invoiced, error)
	UpdatePayment(ctx context.Context, paymentSettlement payment.Invoiced) (payment.Invoiced, error)
}

type ChargeRunAdapter interface {
	CreateCurrentRun(ctx context.Context, input CreateCurrentRunInput) (RealizationRunBase, error)
	UpdateRealizationRun(ctx context.Context, input UpdateRealizationRunInput) (RealizationRunBase, error)
	DetachCurrentRun(ctx context.Context, chargeID meta.ChargeID) error
}

type ChargeWithGatheringLine struct {
	Charge                Charge
	GatheringLineToCreate *billing.GatheringLine
}

type CorrectCreditAllocationsInput struct {
	Charge   Charge    `json:"charge"`
	BookedAt time.Time `json:"bookedAt"`

	Corrections                  creditrealization.CorrectionRequest   `json:"corrections"`
	LineageSegmentsByRealization lineage.ActiveSegmentsByRealizationID `json:"-"`
}

type CreateChargesInput struct {
	Namespace string
	Intents   []IntentWithInitialStatus
}

type CreateCurrentRunInput struct {
	Charge                    ChargeBase
	ServicePeriod             timeutil.ClosedPeriod
	AmountAfterProration      alpacadecimal.Decimal
	NoFiatTransactionRequired bool
	Immutable                 bool
	LineID                    *string
	InvoiceID                 *string
}

type CreateInput struct {
	Namespace     string
	Intents       []Intent
	FeatureMeters feature.FeatureMeters
}

type CreateInvoicedUsageInput struct {
	RunID         RealizationRunID
	LineID        string
	InvoiceID     string
	InvoicedUsage invoicedusage.AccruedUsage
}

type DetailedLine = stddetailedline.Base

type DetailedLines []DetailedLine

type FlatFeeService interface {
	// Create returns one result for each input intent, preserving input order.
	// Invoice-line create flows rely on this to merge charge target state back
	// onto the matching billing-preallocated line identity.
	Create(ctx context.Context, input CreateInput) ([]ChargeWithGatheringLine, error)
	// GetByIDs loads flat-fee charges. Request realization expansions when the
	// caller needs invoice-line, credit-allocation, or payment lifecycle state.
	GetByIDs(ctx context.Context, input GetByIDsInput) ([]Charge, error)
	// GetByID loads one flat-fee charge. Effective behavior may come from an
	// override layer, while subscription sync should compare the base intent.
	GetByID(ctx context.Context, input GetByIDInput) (Charge, error)
	// UpdateSubscriptionItemID repairs subscription ownership metadata on the
	// base intent; it must not rewrite an active customer-facing override layer.
	UpdateSubscriptionItemID(ctx context.Context, charge Charge, newSubscriptionItemID string) (Charge, error)
	// AdvanceCharge drives one charge through its lifecycle. Invoice-backed
	// changes are emitted as invoice patches for the billing boundary to consume.
	AdvanceCharge(ctx context.Context, input AdvanceChargeInput) (*Charge, error)
	// TriggerPatch applies an explicit base/override target patch and then
	// reconciles invoice artifacts from the effective flat-fee intent.
	TriggerPatch(ctx context.Context, charge meta.ChargeID, patch meta.Patch) (meta.TriggerPatchResult[Charge], error)
}

type GetByIDInput struct {
	ChargeID meta.ChargeID
	Expands  meta.Expands
}

type GetByIDsInput struct {
	Namespace string
	IDs       []string

	Expands meta.Expands
}

type GetByMetasInput struct {
	Namespace string
	Expands   meta.Expands
	Charges   meta.Charges
}

type Handler interface {
	// OnAllocateCredits is called when a flat fee allocates credits.
	OnAllocateCredits(ctx context.Context, input OnAllocateCreditsInput) (creditrealization.CreateAllocationInputs, error)

	// OnFlatFeeStandardInvoiceUsageAccrued is called when the remaining usage is sent to the customer on a standard invoice.
	OnInvoiceUsageAccrued(ctx context.Context, input OnInvoiceUsageAccruedInput) (ledgertransaction.GroupReference, error)

	// OnCorrectCreditAllocations is called when a credit allocation needs to be corrected.
	OnCorrectCreditAllocations(ctx context.Context, input CorrectCreditAllocationsInput) (creditrealization.CreateCorrectionInputs, error)

	// OnFlatFeePaymentAuthorized is called when a flat fee payment is authorized.
	OnPaymentAuthorized(ctx context.Context, input OnPaymentAuthorizedInput) (ledgertransaction.GroupReference, error)

	// OnFlatFeePaymentSettled is called when a flat fee payment is settled.
	OnPaymentSettled(ctx context.Context, input OnPaymentSettledInput) (ledgertransaction.GroupReference, error)

	// OnFlatFeePaymentUncollectible is called when a flat fee payment is uncollectible
	OnPaymentUncollectible(ctx context.Context, charge Charge) (ledgertransaction.GroupReference, error)
}

type Intent struct {
	meta.Intent
	IntentMutableFields `json:"intentMutableFields"`
	SettlementMode      productcatalog.SettlementMode `json:"settlementMode"`
	FeatureKey          *string                       `json:"featureKey,omitempty"`
}

type IntentMutableFields struct {
	meta.IntentMutableFields

	// IntentDeletedAt marks the flat-fee base/original intent as deleted.
	// Adapters derive the effective charge DeletedAt from this value when no intent override is present.
	IntentDeletedAt *time.Time `json:"intentDeletedAt,omitempty"`

	InvoiceAt           time.Time                      `json:"invoiceAt"`
	PaymentTerm         productcatalog.PaymentTermType `json:"paymentTerm"`
	PercentageDiscounts *billing.PercentageDiscount    `json:"percentageDiscounts"`

	ProRating             productcatalog.ProRatingConfig `json:"proRating"`
	AmountBeforeProration alpacadecimal.Decimal          `json:"amountBeforeProration"`
}

type IntentWithInitialStatus struct {
	Intent Intent

	FeatureID                 *string
	InitialStatus             Status
	InitialAdvanceAfter       *time.Time
	AmountAfterProration      alpacadecimal.Decimal
	NoFiatTransactionRequired bool
}

type OnAllocateCreditsInput struct {
	Charge        Charge                `json:"charge"`
	ServicePeriod timeutil.ClosedPeriod `json:"servicePeriod"`
	BookedAt      time.Time             `json:"bookedAt"`
	// PreTaxAmountToAllocate is the pre-tax amount to allocate from credits.
	// The input charge's settlement mode governs whether this may create a negative balance.
	PreTaxAmountToAllocate alpacadecimal.Decimal `json:"preTaxAmountToAllocate"`
}

type OnInvoiceUsageAccruedInput struct {
	Charge        Charge                `json:"charge"`
	ServicePeriod timeutil.ClosedPeriod `json:"servicePeriod"`
	BookedAt      time.Time             `json:"bookedAt"`
	Totals        totals.Totals         `json:"totals"`
}

type OnPaymentAuthorizedInput = PaymentEventInput

type OnPaymentSettledInput = PaymentEventInput

type OverridableIntent struct {
	// contains filtered or unexported fields
}

type PaymentEventInput struct {
	Charge  Charge                `json:"charge"`
	EventAt time.Time             `json:"eventAt"`
	Amount  alpacadecimal.Decimal `json:"amount"`
}

type ProRatingModeAdapterEnum string

type RealizationRun struct {
	RealizationRunBase

	CreditRealizations creditrealization.Realizations `json:"creditRealizations"`
	AccruedUsage       *invoicedusage.AccruedUsage    `json:"accruedUsage"`
	Payment            *payment.Invoiced              `json:"payment"`
	DetailedLines      mo.Option[DetailedLines]       `json:"detailedLines,omitzero"`
}

type RealizationRunBase struct {
	ID RealizationRunID `json:"id"`
	models.ManagedModel

	LineID    *string `json:"lineId,omitempty"`
	InvoiceID *string `json:"invoiceId,omitempty"`

	Type        RealizationRunType `json:"type"`
	InitialType RealizationRunType `json:"initialType"`

	ServicePeriod             timeutil.ClosedPeriod `json:"servicePeriod"`
	AmountAfterProration      alpacadecimal.Decimal `json:"amountAfterProration"`
	Totals                    totals.Totals         `json:"totals"`
	NoFiatTransactionRequired bool                  `json:"noFiatTransactionRequired"`
	// Immutable means the backing invoice line can no longer be updated in place.
	// When true, deleting this run requires issuing a credit note instead of mutating the invoice line.
	Immutable bool `json:"immutable"`
}

type RealizationRunID models.NamespacedID

type RealizationRunType string

type RealizationRuns []RealizationRun

type Realizations struct {
	CurrentRun *RealizationRun `json:"currentRun,omitempty"`
	PriorRuns  RealizationRuns `json:"priorRuns,omitempty"`
}

type Service interface {
	FlatFeeService
	GetLineEngine() billing.LineEngine
}

type State struct {
	AdvanceAfter         *time.Time            `json:"advanceAfter,omitempty"`
	FeatureID            *string               `json:"featureId,omitempty"`
	AmountAfterProration alpacadecimal.Decimal `json:"amountAfterProration"`
}

type Status string

type UpdateRealizationRunInput struct {
	ID RealizationRunID

	Type                      mo.Option[RealizationRunType]    `json:"type"`
	DeletedAt                 mo.Option[*time.Time]            `json:"deletedAt,omitempty"`
	LineID                    mo.Option[*string]               `json:"lineId,omitempty"`
	InvoiceID                 mo.Option[*string]               `json:"invoiceId,omitempty"`
	ServicePeriod             mo.Option[timeutil.ClosedPeriod] `json:"servicePeriod"`
	AmountAfterProration      mo.Option[alpacadecimal.Decimal] `json:"amountAfterProration"`
	Totals                    mo.Option[totals.Totals]         `json:"totals"`
	NoFiatTransactionRequired mo.Option[bool]                  `json:"noFiatTransactionRequired"`
	Immutable                 mo.Option[bool]                  `json:"immutable"`
}