usagebased

type Adapter interface {
	RealizationRunAdapter
	RealizationRunCreditAllocationAdapter
	RealizationRunInvoiceUsageAdapter
	RealizationRunPaymentAdapter
	ChargeAdapter
	ChargeCostBasisAdapter

	entutils.TxCreator
}

type AdvanceChargeInput struct {
	ChargeID         meta.ChargeID
	CustomerOverride billing.CustomerOverrideWithDetails
	FeatureMeters    feature.FeatureMeters
}

type BillingMeteredQuantity struct {
	// PreLinePeriod is the cumulative quantity already represented by earlier
	// billed runs.
	PreLinePeriod alpacadecimal.Decimal
	// LinePeriod is the quantity represented by the current standard invoice
	// line.
	LinePeriod alpacadecimal.Decimal
}

type Charge struct {
	ChargeBase

	Realizations RealizationRuns `json:"realizations"`
	Expands      Expands         `json:"expands"`
}

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, input GetByIDsInput) ([]Charge, error)
	GetByID(ctx context.Context, input GetByIDInput) (Charge, error)
}

type ChargeBase struct {
	meta.ManagedResource

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

	State State `json:"state"`
}

type ChargeCostBasisAdapter interface {
	SetResolvedCostBasis(ctx context.Context, input costbasis.SetResolvedCostBasisInput) (costbasis.CostBasis, error)
}

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

type Charges []Charge

type CreateChargesInput struct {
	Namespace string
	Intents   []CreateIntent
}

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

type CreateIntent struct {
	Intent      OverridableIntent
	Annotations models.Annotations `json:"annotations"`

	FeatureID         string
	RatingEngine      RatingEngine
	ResolvedCostBasis *costbasis.State
}

type CreateRealizationRunInput struct {
	FeatureID                 string                `json:"featureId"`
	Type                      RealizationRunType    `json:"type"`
	StoredAtLT                time.Time             `json:"storedAtLT"`
	ServicePeriodTo           time.Time             `json:"servicePeriodTo"`
	LineID                    *string               `json:"lineId,omitempty"`
	InvoiceID                 *string               `json:"invoiceId,omitempty"`
	MeteredQuantity           alpacadecimal.Decimal `json:"meteredQuantity"`
	Totals                    totals.Totals         `json:"totals"`
	NoFiatTransactionRequired bool                  `json:"noFiatTransactionRequired"`
}

type CreditsOnlyUsageAccruedCorrectionInput struct {
	Charge   Charge         `json:"charge"`
	Run      RealizationRun `json:"run"`
	BookedAt time.Time      `json:"bookedAt"`

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

type CreditsOnlyUsageAccruedInput struct {
	Charge           Charge                `json:"charge"`
	Run              RealizationRun        `json:"run"`
	BookedAt         time.Time             `json:"bookedAt"`
	AmountToAllocate alpacadecimal.Decimal `json:"amountToAllocate"`
}

type DetailedLine struct {
	stddetailedline.Base

	PricerReferenceID string  `json:"pricerReferenceID"`
	CorrectsRunID     *string `json:"correctsRunID,omitempty"`
}

type DetailedLines []DetailedLine

type Expands struct {
	RealtimeUsage *totals.Totals `json:"realtimeUsage,omitempty"`
}

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

type GetByIDsInput struct {
	Namespace string
	IDs       []string
	Expands   meta.Expands
}

type GetCurrentTotalsInput struct {
	ChargeID meta.ChargeID
}

type GetCurrentTotalsResult struct {
	Charge    Charge
	DueTotals totals.Totals
}

type Handler interface {
	// OnInvoiceUsageAccrued is called when invoice-settled usage-based usage is sent to the customer.
	OnInvoiceUsageAccrued(ctx context.Context, input OnInvoiceUsageAccruedInput) (ledgertransaction.GroupReference, error)

	// OnPaymentAuthorized is called when an invoice-backed usage-based run receives payment authorization.
	OnPaymentAuthorized(ctx context.Context, input OnPaymentAuthorizedInput) (ledgertransaction.GroupReference, error)

	// OnPaymentSettled is called when an invoice-backed usage-based run payment is settled.
	OnPaymentSettled(ctx context.Context, input OnPaymentSettledInput) (ledgertransaction.GroupReference, error)

	// OnCustomCurrencyOverageAccrued is called when uncovered custom-currency usage is accrued in fiat.
	// This must be modeled as a credit purchase flow from the ledger point of view.
	OnCustomCurrencyOverageAccrued(ctx context.Context, input OnCustomCurrencyOverageAccruedInput) (OnCustomCurrencyOverageAccruedResult, error)

	// OnCreditsOnlyUsageAccrued is called when a credit-only usage-based charge needs to be allocated as credits fully.
	OnCreditsOnlyUsageAccrued(ctx context.Context, input CreditsOnlyUsageAccruedInput) (creditrealization.CreateAllocationInputs, error)

	// OnCreditsOnlyUsageAccruedCorrection is called when a credit-only usage-based charge needs to be corrected.
	OnCreditsOnlyUsageAccruedCorrection(ctx context.Context, input CreditsOnlyUsageAccruedCorrectionInput) (creditrealization.CreateCorrectionInputs, error)
}

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

type IntentMutableFields struct {
	meta.IntentMutableFields

	// IntentDeletedAt marks the usage-based 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"`

	Price productcatalog.Price `json:"price"`

	Discounts billing.Discounts `json:"discounts"`

	// UnitConfig is the optional unit conversion snapshotted from the effective
	// rate card. Like Price it is a mutable rating input (set on create and
	// update) so re-rates read the config in effect for the charge.
	UnitConfig *productcatalog.UnitConfig `json:"unitConfig,omitempty"`
}

type OnCustomCurrencyOverageAccruedInput struct {
	Charge Charge         `json:"charge"`
	Run    RealizationRun `json:"run"`
}

type OnCustomCurrencyOverageAccruedResult struct {
	TransactionGroup ledgertransaction.GroupReference `json:"transactionGroup"`
	TotalFiatAmount  alpacadecimal.Decimal            `json:"totalFiatAmount"`
}

type OnInvoiceUsageAccruedInput struct {
	Charge        Charge                `json:"charge"`
	Run           RealizationRun        `json:"run"`
	ServicePeriod timeutil.ClosedPeriod `json:"servicePeriod"`
	BookedAt      time.Time             `json:"bookedAt"`
	Amount        alpacadecimal.Decimal `json:"amount"`
}

type OnPaymentAuthorizedInput = PaymentEventInput

type OnPaymentSettledInput = PaymentEventInput

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

type PaymentEventInput struct {
	Charge     Charge                `json:"charge"`
	Run        RealizationRun        `json:"run"`
	EventAt    time.Time             `json:"eventAt"`
	FiatAmount alpacadecimal.Decimal `json:"fiatAmount"`
}

type RateableIntent struct {
	Intent

	ServicePeriod  timeutil.ClosedPeriod
	MeterValue     alpacadecimal.Decimal
	CreditsApplied billing.CreditsApplied
}

type RatingEngine string

type RealizationRun struct {
	RealizationRunBase

	// Realizations
	CreditsAllocated creditrealization.Realizations `json:"creditsAllocated"`
	InvoiceUsage     *invoicedusage.AccruedUsage    `json:"invoicedUsage"`
	Payment          *payment.Invoiced              `json:"payment"`
	// DetailedLines excludes taxes. Credit-then-invoice runs include credit
	// allocations, while credits-only runs retain their gross rated details.
	DetailedLines mo.Option[DetailedLines] `json:"detailedLines,omitzero"`
}

type RealizationRunAdapter interface {
	CreateRealizationRun(ctx context.Context, chargeID meta.ChargeID, input CreateRealizationRunInput) (RealizationRunBase, error)
	UpdateRealizationRun(ctx context.Context, input UpdateRealizationRunInput) (RealizationRunBase, error)
	UpsertRunDetailedLines(ctx context.Context, input UpsertRunDetailedLinesInput) error
	FetchDetailedLines(ctx context.Context, charge Charge) (Charge, error)
}

type RealizationRunBase struct {
	ID RealizationRunID
	models.ManagedModel

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

	Type        RealizationRunType `json:"type"`
	InitialType RealizationRunType `json:"initialType"`
	StoredAtLT  time.Time          `json:"storedAtLT"`
	// ServicePeriodTo is the end of the service period for the realization run.
	ServicePeriodTo time.Time `json:"servicePeriodTo"`
	// MeteredQuantity is the metered quantity for time IN [intent.servicePeriod.from, servicePeriodTo) capped by stored_at < StoredAtLT.
	MeteredQuantity alpacadecimal.Decimal `json:"meteredQuantity"`
	// Totals includes credit allocations and excludes taxes.
	Totals                    totals.Totals `json:"totals"`
	NoFiatTransactionRequired bool          `json:"noFiatTransactionRequired"`
	// DetailedLinesIncludeCreditAllocations describes if credit allocation is applied to the detailed lines.
	// Credits-only: always false
	// Credit-then-invoice:
	// - true, for all runs (even when 0 credits were allocated)
	// - legacy runs have false, as previously we didn't store credit allocations on detailed lines
	DetailedLinesIncludeCreditAllocations bool `json:"detailedLinesIncludeCreditAllocations"`
}

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

type RealizationRunID models.NamespacedID

type RealizationRunInvoiceUsageAdapter interface {
	CreateRunInvoicedUsage(ctx context.Context, runID RealizationRunID, invoicedUsage invoicedusage.AccruedUsage) (invoicedusage.AccruedUsage, error)
}

type RealizationRunPaymentAdapter interface {
	CreateRunPayment(ctx context.Context, runID RealizationRunID, in payment.InvoicedCreate) (payment.Invoiced, error)
	UpdateRunPayment(ctx context.Context, in payment.Invoiced) (payment.Invoiced, error)
}

type RealizationRunType string

type RealizationRuns []RealizationRun

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

type State struct {
	CurrentRealizationRunID *string          `json:"currentRealizationRunId"`
	AdvanceAfter            *time.Time       `json:"advanceAfter"`
	FeatureID               string           `json:"featureId"`
	RatingEngine            RatingEngine     `json:"ratingEngine"`
	CostBasisID             *string          `json:"-"`
	ResolvedCostBasis       *costbasis.State `json:"resolvedCostBasis,omitempty"`
}

type Status string

type UnimplementedHandler struct{}

type UpdateRealizationRunInput struct {
	ID RealizationRunID

	Type                      mo.Option[RealizationRunType]    `json:"type"`
	StoredAtLT                mo.Option[time.Time]             `json:"storedAtLT"`
	DeletedAt                 mo.Option[*time.Time]            `json:"deletedAt,omitempty"`
	LineID                    mo.Option[*string]               `json:"lineId,omitempty"`
	MeteredQuantity           mo.Option[alpacadecimal.Decimal] `json:"meteredQuantity"`
	Totals                    mo.Option[totals.Totals]         `json:"totals"`
	NoFiatTransactionRequired mo.Option[bool]                  `json:"noFiatTransactionRequired"`
}

type UpsertRunDetailedLinesInput struct {
	ChargeID meta.ChargeID
	RunID    RealizationRunID

	DetailedLines                         DetailedLines
	DetailedLinesIncludeCreditAllocations bool
}

type UsageBasedService interface {
	// Create returns one result for each input intent, preserving input order.
	// Pending gathering-line creation relies on this to pair charge targets with
	// their source intents.
	Create(ctx context.Context, input CreateInput) ([]ChargeWithGatheringLine, error)
	// GetByIDs loads usage-based charges. Request realization expansions when
	// callers need run, detailed-line, or credit-allocation state.
	GetByIDs(ctx context.Context, input GetByIDsInput) ([]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 usage-based charge. Realization runs store
	// cumulative usage snapshots; billing-line quantities are mapped separately.
	AdvanceCharge(ctx context.Context, input AdvanceChargeInput) (*Charge, error)
	// TriggerPatch applies an explicit base/override target patch and then
	// reconciles invoice artifacts from the effective usage-based intent.
	TriggerPatch(ctx context.Context, charge meta.ChargeID, patch meta.Patch) (meta.TriggerPatchResult[Charge], error)
	// GetCurrentTotals calculates the current customer-facing totals from the
	// effective intent and non-voided realization history.
	GetCurrentTotals(ctx context.Context, input GetCurrentTotalsInput) (GetCurrentTotalsResult, error)
}