refactor: billing detailed lines

Author: turip

go.sum

@@ -2000,6 +2000,8 @@ github.com/oklog/ulid v1.3.1 h1:EGfNDEx6MqHz8B3uNV6QAib1UR2Lm97sHi3ocA6ESJ4=
 github.com/oklog/ulid v1.3.1/go.mod h1:CirwcVhetQ6Lv90oh/F+FBtV6XMibvdAFo93nm5qn4U=
 github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
 github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
+github.com/olekukonko/tablewriter v0.0.5 h1:P2Ga83D34wi1o9J6Wh1mRuqd4mF/x/lgBS7N7AbDhec=
+github.com/olekukonko/tablewriter v0.0.5/go.mod h1:hPp6KlRPjbx+hW8ykQs1w3UBbZlj6HuIJcUGPhkA7kY=
 github.com/oliveagle/jsonpath v0.0.0-20180606110733-2e52cf6e6852 h1:Yl0tPBa8QPjGmesFh1D0rDy+q1Twx6FyU7VWHi8wZbI=
 github.com/oliveagle/jsonpath v0.0.0-20180606110733-2e52cf6e6852/go.mod h1:eqOVx5Vwu4gd2mmMZvVZsgIqNSaW3xxRThUJ0k/TPk4=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=

openmeter/billing/app.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
+	"github.com/samber/lo"
 	"github.com/samber/mo"
 
 	"github.com/openmeterio/openmeter/openmeter/app"
@@ -222,23 +224,42 @@ func (r UpsertInvoiceResult) MergeIntoInvoice(invoice *Invoice) error {
 		invoice.ExternalIDs.Invoicing = externalID
 	}
 
+	if !invoice.Lines.IsPresent() {
+		return errors.New("invoice has no expanded lines")
+	}
+
 	var outErr error
 
 	// Let's merge the line IDs
 	if len(r.GetLineExternalIDs()) > 0 {
-		flattenedLines := invoice.FlattenLinesByID()
+		lineIDToExternalID := r.GetLineExternalIDs()
+		dicountIDToExternalID := r.GetLineDiscountExternalIDs()
 
-		// Merge the line IDs
-		for lineID, externalID := range r.GetLineExternalIDs() {
-			if line, ok := flattenedLines[lineID]; ok {
+		lines := invoice.Lines.OrEmpty()
+
+		for _, line := range lines {
+			if externalID, ok := lineIDToExternalID[line.ID]; ok {
 				line.ExternalIDs.Invoicing = externalID
-			} else {
-				outErr = errors.Join(outErr, fmt.Errorf("line not found in invoice: %s", lineID))
+				delete(lineIDToExternalID, line.ID)
+			}
+
+			for idx, detailedLine := range line.DetailedLines {
+				if externalID, ok := lineIDToExternalID[detailedLine.ID]; ok {
+					line.DetailedLines[idx].InvoicingAppExternalID = &externalID
+					delete(lineIDToExternalID, detailedLine.ID)
+				}
 			}
 		}
 
+		if len(lineIDToExternalID) > 0 {
+			outErr = errors.Join(outErr, fmt.Errorf("some lines were not found in the invoice: ids=[%s]", strings.Join(lo.Keys(lineIDToExternalID), ", ")))
+		}
+
+		if len(dicountIDToExternalID) > 0 {
+			outErr = errors.Join(outErr, fmt.Errorf("some line discounts were not found in the invoice: ids=[%s]", strings.Join(lo.Keys(dicountIDToExternalID), ", ")))
+		}
+
 		// Let's merge the line discount IDs
-		dicountIDToExternalID := r.GetLineDiscountExternalIDs()
 
 		for _, line := range flattenedLines {
 			for idx, discount := range line.Discounts.Amount {

openmeter/billing/invoice.go

@@ -4,7 +4,6 @@ import (
 	"errors"
 	"fmt"
 	"slices"
-	"sort"
 	"strings"
 	"time"
 
@@ -404,45 +403,22 @@ func (i Invoice) RemoveMetaForCompare() Invoice {
 	return invoice
 }
 
-func (i *Invoice) FlattenLinesByID() map[string]*Line {
-	out := make(map[string]*Line, len(i.Lines.OrEmpty()))
+func (i *Invoice) DetailedLinesByID() map[string]DetailedLine {
+	out := make(map[string]DetailedLine, len(i.Lines.OrEmpty()))
 
 	for _, line := range i.Lines.OrEmpty() {
-		out[line.ID] = line
-
-		for _, child := range line.Children.OrEmpty() {
+		for _, child := range line.DetailedLines {
 			out[child.ID] = child
 		}
 	}
 
 	return out
 }
 
-// getLeafLines returns the leaf lines
-func (i *Invoice) getLeafLines() []*Line {
-	var leafLines []*Line
-
-	for _, line := range i.FlattenLinesByID() {
-		// Skip non leaf nodes
-		if line.Type != InvoiceLineTypeFee {
-			continue
-		}
-
-		leafLines = append(leafLines, line)
-	}
-
-	return leafLines
-}
-
-// GetLeafLinesWithConsolidatedTaxBehavior returns the leaf lines with the tax behavior set to the invoice's tax behavior
+// GetDetailedLinesWithConsolidatedTaxBehavior returns the detailed lines with the tax behavior set to the invoice's tax behavior
 // unless the line already has a tax behavior set.
-func (i *Invoice) GetLeafLinesWithConsolidatedTaxBehavior() []*Line {
-	leafLines := i.getLeafLines()
-	if i.Workflow.Config.Invoicing.DefaultTaxConfig == nil {
-		return leafLines
-	}
-
-	return lo.Map(leafLines, func(line *Line, _ int) *Line {
+func (i *Invoice) GetDetailedLinesWithConsolidatedTaxBehavior() []DetailedLine {
+	return lo.Map(lo.Values(i.DetailedLinesByID()), func(line DetailedLine, _ int) DetailedLine {
 		line.TaxConfig = productcatalog.MergeTaxConfigs(i.Workflow.Config.Invoicing.DefaultTaxConfig, line.TaxConfig)
 		return line
 	})
@@ -468,59 +444,9 @@ func (i Invoice) RemoveCircularReferences() Invoice {
 	return clone
 }
 
+// TODO: Do we need this at all?
 func (i *Invoice) SortLines() {
-	if !i.Lines.IsPresent() {
-		return
-	}
-
-	lines := i.Lines.OrEmpty()
-
-	sortLines(lines)
-
-	i.Lines = NewLineChildren(lines)
-}
-
-func sortLines(lines []*Line) {
-	sort.Slice(lines, func(a, b int) bool {
-		lineA := lines[a]
-		lineB := lines[b]
-
-		// If both lines are flat fee lines, we sort them by index if possible
-		if lineA.Type == InvoiceLineTypeFee && lineB.Type == InvoiceLineTypeFee {
-			if lineA.FlatFee.Index != nil && lineB.FlatFee.Index != nil {
-				return *lineA.FlatFee.Index < *lineB.FlatFee.Index
-			}
-
-			if lineA.FlatFee.Index != nil {
-				return true
-			}
-
-			if lineB.FlatFee.Index != nil {
-				return false
-			}
-		}
-
-		if nameOrder := strings.Compare(lineA.Name, lineB.Name); nameOrder != 0 {
-			return nameOrder < 0
-		}
-
-		if !lineA.Period.Start.Equal(lineB.Period.Start) {
-			return lineA.Period.Start.Before(lineB.Period.Start)
-		}
-
-		return strings.Compare(lineA.ID, lineB.ID) < 0
-	})
-
-	for idx, line := range lines {
-		if line.Type == InvoiceLineTypeUsageBased && line.Children.IsPresent() {
-			children := line.Children.OrEmpty()
-			sortLines(children)
-
-			line.Children = NewLineChildren(children)
-		}
-
-		lines[idx] = line
-	}
+	i.Lines = i.Lines.Sorted()
 }
 
 type InvoiceExternalIDs struct {

openmeter/billing/invoice_test.go

@@ -4,12 +4,13 @@ import (
 	"testing"
 	"time"
 
+	"github.com/openmeterio/openmeter/pkg/models"
 	"github.com/samber/lo"
 	"github.com/stretchr/testify/require"
 )
 
 func TestSortLines(t *testing.T) {
-	lines := []*Line{
+	input := NewLineChildren([]*Line{
 		{
 			LineBase: LineBase{
 				Type: InvoiceLineTypeUsageBased,
@@ -19,28 +20,22 @@ func TestSortLines(t *testing.T) {
 				},
 				Description: lo.ToPtr("index=1"),
 			},
-			Children: NewLineChildren([]*Line{
+			DetailedLines: DetailedLines{
 				{
-					LineBase: LineBase{
+					ManagedResource: models.NewManagedResource(models.ManagedResourceInput{
 						ID:          "child-2",
-						Type:        InvoiceLineTypeFee,
 						Description: lo.ToPtr("index=1.1"),
-					},
-					FlatFee: &FlatFeeLine{
-						Index: lo.ToPtr(1),
-					},
+					}),
+					Index: lo.ToPtr(1),
 				},
 				{
-					LineBase: LineBase{
+					ManagedResource: models.NewManagedResource(models.ManagedResourceInput{
 						ID:          "child-1",
-						Type:        InvoiceLineTypeFee,
 						Description: lo.ToPtr("index=1.0"),
-					},
-					FlatFee: &FlatFeeLine{
-						Index: lo.ToPtr(0),
-					},
+					}),
+					Index: lo.ToPtr(0),
 				},
-			}),
+			},
 		},
 		{
 			LineBase: LineBase{
@@ -51,15 +46,14 @@ func TestSortLines(t *testing.T) {
 				},
 				Description: lo.ToPtr("index=0"),
 			},
-			Children: NewLineChildren(nil),
 		},
-	}
+	})
 
-	sortLines(lines)
+	lines := input.Sorted().OrEmpty()
 
 	require.Equal(t, *lines[0].Description, "index=0")
 	require.Equal(t, *lines[1].Description, "index=1")
-	children := lines[1].Children.OrEmpty()
+	children := lines[1].DetailedLines
 	require.Equal(t, *children[0].Description, "index=1.0")
 	require.Equal(t, *children[1].Description, "index=1.1")
 }

openmeter/billing/invoicedetailedline.go

@@ -0,0 +1,131 @@
+package billing
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/currencyx"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/samber/lo"
+)
+
+type DetailedLineCategory string
+
+const (
+	// DetailedLineCategoryRegular is a regular flat fee, that is based on the usage or a subscription.
+	DetailedLineCategoryRegular DetailedLineCategory = "regular"
+	// DetailedLineCategoryCommitment is a flat fee that is based on a commitment such as min spend.
+	DetailedLineCategoryCommitment DetailedLineCategory = "commitment"
+)
+
+func (DetailedLineCategory) Values() []string {
+	return []string{
+		string(DetailedLineCategoryRegular),
+		string(DetailedLineCategoryCommitment),
+	}
+}
+
+var _ models.Validator = (*DetailedLineCategory)(nil)
+
+func (c DetailedLineCategory) Validate() error {
+	if !slices.Contains(DetailedLineCategory("").Values(), string(c)) {
+		return fmt.Errorf("invalid category %s", c)
+	}
+	return nil
+}
+
+type DetailedLine struct {
+	models.Annotations
+	models.ManagedResource
+
+	// Relationships
+	InvoiceID    string `json:"invoiceID"`
+	ParentLineID string `json:"parentLineID"`
+
+	// Line details
+	Category               DetailedLineCategory           `json:"category"`
+	ChildUniqueReferenceID *string                        `json:"childUniqueReferenceID,omitempty"`
+	Currency               currencyx.Code                 `json:"currency"`
+	Index                  *int                           `json:"index,omitempty"`
+	PaymentTerm            productcatalog.PaymentTermType `json:"paymentTerm"`
+	PerUnitAmount          alpacadecimal.Decimal          `json:"perUnitAmount"`
+	Quantity               alpacadecimal.Decimal          `json:"quantity"`
+	ServicePeriod          Period                         `json:"servicePeriod"`
+
+	// Apps
+	TaxConfig              *productcatalog.TaxConfig `json:"taxConfig,omitempty"`
+	InvoicingAppExternalID *string                   `json:"invoicingAppExternalID,omitempty"`
+
+	// Discounts
+	AmountDiscounts AmountLineDiscountsManaged `json:"discounts,omitempty"`
+}
+
+var _ models.Validator = (*DetailedLine)(nil)
+
+func (l DetailedLine) Validate() error {
+	errs := []error{}
+
+	if l.InvoiceID == "" {
+		errs = append(errs, errors.New("invoiceID is required"))
+	}
+
+	if l.ParentLineID == "" {
+		errs = append(errs, errors.New("parentLineID is required"))
+	}
+
+	if err := l.Category.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("category: %w", err))
+	}
+
+	if l.PerUnitAmount.IsNegative() {
+		errs = append(errs, errors.New("price should be positive or zero"))
+	}
+
+	if l.Quantity.IsNegative() {
+		errs = append(errs, errors.New("quantity should be positive or zero"))
+	}
+
+	if err := l.PaymentTerm.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("payment term: %w", err))
+	}
+
+	if err := l.ServicePeriod.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("service period: %w", err))
+	}
+
+	if err := l.Currency.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("currency: %w", err))
+	}
+
+	if err := l.AmountDiscounts.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("amount discounts: %w", err))
+	}
+
+	return errors.Join(errs...)
+}
+
+// TODO: Is this even needed?
+func (l DetailedLine) Clone() DetailedLine {
+	if l.TaxConfig != nil {
+		taxConfig := *l.TaxConfig
+		l.TaxConfig = &taxConfig
+	}
+
+	return l
+}
+
+func (l DetailedLine) Equal(other *DetailedLine) bool {
+	return reflect.DeepEqual(l, *other)
+}
+
+type DetailedLines []DetailedLine
+
+func (l DetailedLines) Map(fn func(DetailedLine) DetailedLine) DetailedLines {
+	return lo.Map(l, func(item DetailedLine, _ int) DetailedLine {
+		return fn(item)
+	})
+}