feat: charges example handlers for flat fee/credit purchase

openmeter/billing/charges/chargecreditpurchase.go

@@ -1,6 +1,7 @@
 package charges
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -374,3 +375,44 @@ func (s CreditPurchaseState) Validate() error {
 
 	return errors.Join(errs...)
 }
+
+// CreditPurchaseHandler is the interface for handling credit purchase charges.
+// It is used to handle the different types of credit purchase charges (promotional, external, invoice).
+//
+// Promotional credit purchases are handled by the OnPromotionalCreditPurchase method only.
+//
+// Cost basis > 0 credit purchases are handled by the OnCreditPurchase method, which is the initial call.
+// Happy path:
+// - OnCreditPurchase is called
+// - OnCreditPurchasePaymentAuthorized is called
+// - OnCreditPurchasePaymentSettled is called
+//
+// Failed payment can occur either after the OnCreditPurchase or after the OnCreditPurchasePaymentAuthorized call.
+
+type CreditPurchaseHandler interface {
+	// Promotional credit handler methods (cost basis == 0)
+	// ----------------------------------------------------
+
+	// OnPromotionalCreditPurchase is called when a promotional credit purchase is created (e.g. costbasis is 0)
+	// For promotional credit purchases we don't call any of the payment handler methods.
+	OnPromotionalCreditPurchase(ctx context.Context, charge CreditPurchaseCharge) ([]CreditRealizationCreateInput, error)
+
+	// Credit purchase handler methods (cost basis > 0)
+	// ------------------------------------------------
+
+	// OnCreditPurchase is called when a credit purchase is initiated that is going to be settled by
+	// a payment (either external or a standard invoice)
+	// Initial call
+	OnCreditPurchase(ctx context.Context, charge CreditPurchaseCharge) ([]CreditRealizationCreateInput, error)
+
+	// OnCreditPurchasePaymentAuthorized is called when a credit purchase payment is authorized for a credit
+	// purchase.
+	OnCreditPurchasePaymentAuthorized(ctx context.Context, charge CreditPurchaseCharge) (LedgerTransactionGroupReference, error)
+
+	// OnCreditPurchasePaymentSettled is called when a credit purchase payment is settled for a credit
+	// purchase.
+	OnCreditPurchasePaymentSettled(ctx context.Context, charge CreditPurchaseCharge) (LedgerTransactionGroupReference, error)
+
+	// OnCreditPurchasePaymentUncollectible is called when a credit purchase payment is uncollectible
+	OnCreditPurchasePaymentUncollectible(ctx context.Context, charge CreditPurchaseCharge) (LedgerTransactionGroupReference, error)
+}

openmeter/billing/charges/chargeflatfee.go

@@ -1,6 +1,7 @@
 package charges
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"slices"
@@ -107,3 +108,26 @@ func (s FlatFeeState) Validate() error {
 
 	return errors.Join(errs...)
 }
+
+type OnFlatFeeAssignedToInvoiceInput struct {
+	Charge            FlatFeeCharge         `json:"charge"`
+	PreTaxTotalAmount alpacadecimal.Decimal `json:"totalAmount"`
+}
+
+type FlatFeeHandler interface {
+	// OnFlatFeeAssignedToInvoice is called when a flat fee is being assigned to an invoice
+	OnFlatFeeAssignedToInvoice(ctx context.Context, input OnFlatFeeAssignedToInvoiceInput) ([]CreditRealizationCreateInput, error)
+
+	// OnFlatFeeLineDeleted is called when a flat fee line is deleted before the invoice has been issued, should revert
+	// the credit realizations that were created.
+	OnFlatFeeLineDeleted(ctx context.Context, charge FlatFeeCharge) ([]ReversedCreditRealization, error)
+
+	// OnFlatFeePaymentAuthorized is called when a flat fee payment is authorized
+	OnFlatFeePaymentAuthorized(ctx context.Context, charge FlatFeeCharge) (LedgerTransactionGroupReference, error)
+
+	// OnFlatFeePaymentSettled is called when a flat fee payment is settled
+	OnFlatFeePaymentSettled(ctx context.Context, charge FlatFeeCharge) (LedgerTransactionGroupReference, error)
+
+	// OnFlatFeePaymentUncollectible is called when a flat fee payment is uncollectible
+	OnFlatFeePaymentUncollectible(ctx context.Context, charge FlatFeeCharge) (LedgerTransactionGroupReference, error)
+}

openmeter/billing/charges/credits.go

@@ -0,0 +1,119 @@
+package charges
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/alpacahq/alpacadecimal"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/timeutil"
+)
+
+type CreditRealizationCreateInput struct {
+	Annotations   models.Annotations    `json:"annotations"`
+	ServicePeriod timeutil.ClosedPeriod `json:"servicePeriod"`
+
+	// TODO: let's add ledger transaction id(s) here
+
+	Amount alpacadecimal.Decimal `json:"amount"`
+}
+
+func (i CreditRealizationCreateInput) Validate() error {
+	var errs []error
+
+	if err := i.ServicePeriod.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("service period: %w", err))
+	}
+
+	if i.Amount.IsNegative() {
+		errs = append(errs, fmt.Errorf("amount must be positive"))
+	}
+
+	return errors.Join(errs...)
+}
+
+type CreditRealization struct {
+	models.NamespacedID
+	models.ManagedModel
+	CreditRealizationCreateInput
+
+	// AllocatedToStandardInvoiceRealizationID is the standard invoice realization ID that the credit was allocated to.
+	// If nil, the credit is not allocated to any invoice line (e.g. line is still in gathering,
+	// credit_only mode without invoicing, etc.)
+	AllocatedToStandardInvoiceRealizationID *string `json:"allocatedToStandardInvoiceRealizationID"`
+}
+
+func (r CreditRealization) Validate() error {
+	var errs []error
+
+	if err := r.CreditRealizationCreateInput.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("credit realization input: %w", err))
+	}
+
+	if r.AllocatedToStandardInvoiceRealizationID != nil && *r.AllocatedToStandardInvoiceRealizationID == "" {
+		errs = append(errs, fmt.Errorf("allocated to standard invoice realization ID must be set"))
+	}
+
+	return errors.Join(errs...)
+}
+
+type CreditRealizations []CreditRealization
+
+func (r CreditRealizations) Validate() error {
+	var errs []error
+
+	for idx, realization := range r {
+		if err := realization.Validate(); err != nil {
+			errs = append(errs, fmt.Errorf("credit realization[%d]: %w", idx, err))
+		}
+	}
+
+	return errors.Join(errs...)
+}
+
+func (r CreditRealizations) RealizedUnsettledAmount() alpacadecimal.Decimal {
+	sum := alpacadecimal.Zero
+	for _, realization := range r {
+		sum = sum.Add(realization.Amount)
+	}
+	return sum
+}
+
+func (r CreditRealizations) LastRealizedPeriod() *timeutil.ClosedPeriod {
+	// TODO: we might want to filter for period realizations only
+	if len(r) == 0 {
+		return nil
+	}
+
+	lastRealizedPeriod := r[0].ServicePeriod
+	for _, realization := range r {
+		if realization.ServicePeriod.To.After(lastRealizedPeriod.To) {
+			lastRealizedPeriod = realization.ServicePeriod
+		}
+	}
+
+	return &lastRealizedPeriod
+}
+
+type ReversedCreditRealization struct {
+	RealizationID models.NamespacedID `json:"realizationID"`
+
+	TransactionGroupReferences []LedgerTransactionGroupReference `json:"transactionGroupReference"`
+}
+
+func (r ReversedCreditRealization) Validate() error {
+	var errs []error
+
+	if err := r.RealizationID.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("realization ID: %w", err))
+	}
+
+	for idx, transactionGroupReference := range r.TransactionGroupReferences {
+		if err := transactionGroupReference.Validate(); err != nil {
+			errs = append(errs, fmt.Errorf("transaction group reference[%d]: %w", idx, err))
+		}
+	}
+
+	return errors.Join(errs...)
+}

openmeter/billing/charges/ledger.go

@@ -0,0 +1,24 @@
+package charges
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+// LedgerTransactionGroupReference is a reference to a ledger transaction group.
+// It is used to track payment settlement transactions.
+type LedgerTransactionGroupReference struct {
+	TransactionGroupID models.NamespacedID `json:"transactionGroupID"`
+}
+
+func (r LedgerTransactionGroupReference) Validate() error {
+	var errs []error
+
+	if err := r.TransactionGroupID.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("transaction group ID: %w", err))
+	}
+
+	return errors.Join(errs...)
+}