usagebased

type Adapter interface {
	RealizationRunAdapter
	RealizationRunCreditAllocationAdapter
	RealizationRunInvoiceUsageAdapter
	RealizationRunPaymentAdapter
	ChargeAdapter
	SubscriptionReferenceAdapter
	ChargeCostBasisAdapter

	entutils.TxCreator
}

type AdvanceChargeInput struct {
	ChargeID meta.ChargeID
	// CustomerOverride is an authoritative optional resolution hint. None lets
	// the service resolve the current customer override; Some uses only the
	// supplied snapshot.
	CustomerOverride mo.Option[billing.CustomerOverrideWithDetails]
	// FeatureMeters is an authoritative optional resolution hint. None lets the
	// service resolve the required feature meter; Some resolves exclusively from
	// the supplied collection and returns an error when the feature is absent.
	FeatureMeters mo.Option[billingfeaturemeter.FeatureMeters]
}

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

	BookedAt time.Time `json:"bookedAt"`

	// AmountToAllocate is denominated in the settlement fiat currency.
	AmountToAllocate alpacadecimal.Decimal `json:"amountToAllocate"`
}

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 CreateChargesAdapterInput) ([]Charge, error)
	UpdateCharge(ctx context.Context, charge ChargeBase) (ChargeBase, error)
	UpdateChargeValidationIssues(ctx context.Context, input UpdateChargeValidationIssuesInput) 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"`
	ValidationIssues billing.ValidationIssues `json:"validationIssues,omitempty"`

	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 CorrectFiatOverageCreditAllocationsInput struct {
	Charge   Charge         `json:"charge"`
	Run      RealizationRun `json:"run"`
	BookedAt time.Time      `json:"bookedAt"`

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

type CreateChargesAdapterInput struct {
	Namespace string
	Intents   []CreateIntentAdapterInput
}

type CreateCreditRealizationsInput struct {
	RunID              RealizationRunID
	CreditRealizations creditrealization.CreateInputs
}

type CreateInput struct {
	Namespace string
	Intents   CreateIntents
}

type CreateIntent struct {
	Intent
	Options meta.CreateOptions
}

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

	FeatureID         string
	RatingEngine      RatingEngine
	ResolvedCostBasis *costbasis.State
	ValidationIssues  billing.ValidationIssues
}

type CreateIntents []CreateIntent

type CreateRealizationRunAdapterInput struct {
	CreateRealizationRunInput

	PriorRunID *RealizationRunID
}

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 {
	chargedetailedline.Base

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

type DetailedLines []DetailedLine

type Expands struct {
	RealtimeUsage *totals.Totals `json:"realtimeUsage,omitempty"`
	// RealtimeQuantity is the cumulative metered quantity behind
	// RealtimeUsage, captured by the same live read; set only under the
	// realtime usage expand.
	RealtimeQuantity *alpacadecimal.Decimal `json:"realtimeQuantity,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
	// MeteredQuantity is the cumulative live metered quantity the due totals
	// were rated from.
	MeteredQuantity alpacadecimal.Decimal
}

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 prepares the gross custom-currency overage
	// during invoice line finalization, before settlement-fiat credit allocation.
	OnCustomCurrencyOverageAccrued(ctx context.Context, input OnCustomCurrencyOverageAccruedInput) (OnCustomCurrencyOverageAccruedResult, error)

	// OnCustomCurrencyOverageAccruedCorrection reverses the prepared gross
	// overage before its realization run is deleted. The implementation must
	// participate in the caller's transaction; billing can invoke it again only
	// after that transaction rolls back.
	OnCustomCurrencyOverageAccruedCorrection(ctx context.Context, input OnCustomCurrencyOverageAccruedCorrectionInput) 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)

	// OnAllocateFiatOverageCredits allocates settlement-fiat credits against an
	// already-prepared custom-currency overage.
	OnAllocateFiatOverageCredits(ctx context.Context, input AllocateFiatOverageCreditsInput) (creditrealization.CreateAllocationInputs, error)

	// OnCorrectFiatOverageCreditAllocations corrects settlement-fiat allocations for a custom-currency overage.
	OnCorrectFiatOverageCreditAllocations(ctx context.Context, input CorrectFiatOverageCreditAllocationsInput) (creditrealization.CreateCorrectionInputs, error)
}

type Intent struct {
	meta.Intent
	IntentMutableFields `json:"intentMutableFields"`
	SettlementMode      productcatalog.SettlementMode `json:"settlementMode"`
	FeatureKey          string                        `json:"featureKey"`
	FeatureID           string                        `json:"featureId"`
	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 NewPatchSetOverrideInput = meta.NewPatchSetOverrideInput[IntentMutableFields]

type OnCustomCurrencyOverageAccruedCorrectionInput = OnCustomCurrencyOverageAccruedInput

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

type OnCustomCurrencyOverageAccruedResult struct {
	TransactionGroup ledgertransaction.GroupReference `json:"transactionGroup"`
	// TotalFiatAmount is the authoritative rounded gross amount persisted for
	// invoice projection and later settlement-credit allocation.
	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 PatchSetOverride = meta.PatchSetOverride[IntentMutableFields]

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"`
	FiatOverageCreditRealizations creditrealization.Realizations `json:"fiatOverageCreditRealizations"`
	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 CreateRealizationRunAdapterInput) (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"`
	// PriorRunID identifies the preceding non-voided realization run. It is nil
	// for the first run.
	PriorRunID *RealizationRunID `json:"priorRunId,omitempty"`
	// 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"`
	// Immutable means the backing invoice crossed the external issuance boundary.
	Immutable bool `json:"immutable"`
	// FiatOverageCreditAllocationCompleted distinguishes a successful
	// zero-allocation result from pending allocation.
	FiatOverageCreditAllocationCompleted bool `json:"fiatOverageCreditAllocationCompleted"`
	// 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 {
	CreateChargeCurrencyCreditRealizations(ctx context.Context, input CreateCreditRealizationsInput) (creditrealization.Realizations, error)
	CreateFiatOverageCreditRealizations(ctx context.Context, input CreateCreditRealizationsInput) (creditrealization.Realizations, error)
}

type RealizationRunID models.NamespacedID

type RealizationRunInvoiceUsageAdapter interface {
	CreateRunInvoicedUsage(ctx context.Context, runID RealizationRunID, invoicedUsage invoicedusage.AccruedUsage) (invoicedusage.AccruedUsage, error)
	DeleteRunInvoicedUsage(ctx context.Context, id models.NamespacedID) 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 SubscriptionReferenceAdapter interface {
	UpdateSubscriptionReference(ctx context.Context, input meta.UpdateSubscriptionReferenceInput) error
}

type UnimplementedHandler struct{}

type UpdateChargeValidationIssuesInput struct {
	ChargeID         meta.ChargeID
	ValidationIssues billing.ValidationIssues
}

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"`
	Immutable                            mo.Option[bool]                  `json:"immutable"`
	FiatOverageCreditAllocationCompleted mo.Option[bool]                  `json:"fiatOverageCreditAllocationCompleted"`
}

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 charge until invoice patches are emitted or its
	// lifecycle becomes stable. Callers must apply returned invoice patches
	// before resuming when CanAdvance is true.
	AdvanceCharge(ctx context.Context, input AdvanceChargeInput) (meta.TriggerPatchResult[Charge], error)
	// TriggerPatch applies an explicit base/override target patch and advances
	// until invoice patches are emitted or the lifecycle becomes stable. Callers
	// that apply returned invoice patches must resume with AdvanceCharge.
	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)
}