refactor: disambiguate lines vs detailed lines

Author: turip

api/api.gen.go

@@ -5720,11 +5720,6 @@ export interface components {
        *     External calls always create valid lines, other line types are managed by the
        *     billing engine of OpenMeter. */
       readonly status: components['schemas']['InvoiceLineStatus']
-      /** @description Discounts detailes applied to this line.
-       *
-       *     New discounts can be added via the invoice's discounts API, to facilitate
-       *     discounts that are affecting multiple lines. */
-      readonly discounts?: components['schemas']['InvoiceLineDiscounts']
       /** @description The invoice this item belongs to. */
       invoice?: components['schemas']['InvoiceReference']
       /** @description The currency of this line. */
@@ -5781,13 +5776,25 @@ export interface components {
        * @default regular
        */
       readonly category?: components['schemas']['InvoiceDetailedLineCostCategory']
+      /** @description Discounts detailes applied to this line.
+       *
+       *     New discounts can be added via the invoice's discounts API, to facilitate
+       *     discounts that are affecting multiple lines. */
+      readonly discounts?: components['schemas']['InvoiceDetailedLineDiscounts']
     }
     /**
      * @description InvoiceDetailedLineCostCategory determines if the flat fee is a regular fee due to use due to a
      *     commitment.
      * @enum {string}
      */
     InvoiceDetailedLineCostCategory: 'regular' | 'commitment'
+    /** @description InvoiceLineDiscounts represents the discounts applied to the invoice line by type. */
+    InvoiceDetailedLineDiscounts: {
+      /** @description Amount based discounts applied to the line.
+       *
+       *     Amount based discounts are deduced from the total price of the line. */
+      amount?: components['schemas']['InvoiceLineAmountDiscount'][]
+    }
     /** @description InvoiceDetailedLineRateCard represents the rate card (intent) for a flat fee line. */
     InvoiceDetailedLineRateCard: {
       /**
@@ -6083,7 +6090,7 @@ export interface components {
      * @description Line status specifies the status of the line.
      * @enum {string}
      */
-    InvoiceLineStatus: 'valid' | 'detail' | 'split'
+    InvoiceLineStatus: 'valid' | 'detailed' | 'split'
     /** @description InvoiceLineSubscriptionReference contains the references to the subscription that this line is related to. */
     InvoiceLineSubscriptionReference: {
       /** @description The subscription. */
@@ -10940,6 +10947,8 @@ export type InvoiceAvailableActions =
 export type InvoiceDetailedLine = components['schemas']['InvoiceDetailedLine']
 export type InvoiceDetailedLineCostCategory =
   components['schemas']['InvoiceDetailedLineCostCategory']
+export type InvoiceDetailedLineDiscounts =
+  components['schemas']['InvoiceDetailedLineDiscounts']
 export type InvoiceDetailedLineRateCard =
   components['schemas']['InvoiceDetailedLineRateCard']
 export type InvoiceDocumentRef = components['schemas']['InvoiceDocumentRef']

api/client/go/client.gen.go

@@ -16814,15 +16814,6 @@ components:
             External calls always create valid lines, other line types are managed by the
             billing engine of OpenMeter.
           readOnly: true
-        discounts:
-          allOf:
-            - $ref: '#/components/schemas/InvoiceLineDiscounts'
-          description: |-
-            Discounts detailes applied to this line.
-
-            New discounts can be added via the invoice's discounts API, to facilitate
-            discounts that are affecting multiple lines.
-          readOnly: true
         invoice:
           allOf:
             - $ref: '#/components/schemas/InvoiceReference'
@@ -16902,6 +16893,15 @@ components:
           description: Category of the flat fee.
           default: regular
           readOnly: true
+        discounts:
+          allOf:
+            - $ref: '#/components/schemas/InvoiceDetailedLineDiscounts'
+          description: |-
+            Discounts detailes applied to this line.
+
+            New discounts can be added via the invoice's discounts API, to facilitate
+            discounts that are affecting multiple lines.
+          readOnly: true
       description: InvoiceDetailedLine represents a line item that is sold to the customer as a manually added fee.
     InvoiceDetailedLineCostCategory:
       type: string
@@ -16911,6 +16911,18 @@ components:
       description: |-
         InvoiceDetailedLineCostCategory determines if the flat fee is a regular fee due to use due to a
         commitment.
+    InvoiceDetailedLineDiscounts:
+      type: object
+      properties:
+        amount:
+          type: array
+          items:
+            $ref: '#/components/schemas/InvoiceLineAmountDiscount'
+          description: |-
+            Amount based discounts applied to the line.
+
+            Amount based discounts are deduced from the total price of the line.
+      description: InvoiceLineDiscounts represents the discounts applied to the invoice line by type.
     InvoiceDetailedLineRateCard:
       type: object
       required:
@@ -17351,7 +17363,7 @@ components:
       type: string
       enum:
         - valid
-        - detail
+        - detailed
         - split
       description: Line status specifies the status of the line.
     InvoiceLineSubscriptionReference:

api/client/javascript/src/client/schemas.ts

@@ -17174,15 +17174,6 @@ components:
             External calls always create valid lines, other line types are managed by the
             billing engine of OpenMeter.
           readOnly: true
-        discounts:
-          allOf:
-            - $ref: '#/components/schemas/InvoiceLineDiscounts'
-          description: |-
-            Discounts detailes applied to this line.
-
-            New discounts can be added via the invoice's discounts API, to facilitate
-            discounts that are affecting multiple lines.
-          readOnly: true
         invoice:
           allOf:
             - $ref: '#/components/schemas/InvoiceReference'
@@ -17262,6 +17253,15 @@ components:
           description: Category of the flat fee.
           default: regular
           readOnly: true
+        discounts:
+          allOf:
+            - $ref: '#/components/schemas/InvoiceDetailedLineDiscounts'
+          description: |-
+            Discounts detailes applied to this line.
+
+            New discounts can be added via the invoice's discounts API, to facilitate
+            discounts that are affecting multiple lines.
+          readOnly: true
       description: InvoiceDetailedLine represents a line item that is sold to the customer as a manually added fee.
     InvoiceDetailedLineCostCategory:
       type: string
@@ -17271,6 +17271,18 @@ components:
       description: |-
         InvoiceDetailedLineCostCategory determines if the flat fee is a regular fee due to use due to a
         commitment.
+    InvoiceDetailedLineDiscounts:
+      type: object
+      properties:
+        amount:
+          type: array
+          items:
+            $ref: '#/components/schemas/InvoiceLineAmountDiscount'
+          description: |-
+            Amount based discounts applied to the line.
+
+            Amount based discounts are deduced from the total price of the line.
+      description: InvoiceLineDiscounts represents the discounts applied to the invoice line by type.
     InvoiceDetailedLineRateCard:
       type: object
       required:
@@ -17902,7 +17914,7 @@ components:
       type: string
       enum:
         - valid
-        - detail
+        - detailed
         - split
       description: Line status specifies the status of the line.
     InvoiceLineSubscriptionReference:

api/openapi.cloud.yaml

@@ -463,6 +463,7 @@ enum InvoiceLineTypes {
 /**
  * Line status specifies the status of the line.
  */
+// TODO[v2]: Deprecate this type altogether
 @friendlyName("InvoiceLineStatus")
 enum InvoiceLineStatus {
   /**
@@ -474,7 +475,7 @@ enum InvoiceLineStatus {
    * The line is a detail line which is used to detail the individual
    * charges and discounts of a valid line.
    */
-  detail: "detail",
+  detailed: "detailed",
 
   /**
    * The line has been split into multiple valid lines due to progressive
@@ -762,7 +763,7 @@ model InvoiceDetailedLineRateCard {
  */
 @friendlyName("InvoiceDetailedLine")
 model InvoiceDetailedLine {
-  ...OmitProperties<InvoiceLineBase, "type">;
+  ...OmitProperties<InvoiceLineBase, "type" | "discounts">;
 
   /**
    * Type of the line.
@@ -804,6 +805,28 @@ model InvoiceDetailedLine {
    */
   @visibility(Lifecycle.Read)
   category?: InvoiceDetailedLineCostCategory = InvoiceDetailedLineCostCategory.regular;
+
+  /**
+   * Discounts detailes applied to this line.
+   *
+   * New discounts can be added via the invoice's discounts API, to facilitate
+   * discounts that are affecting multiple lines.
+   */
+  @visibility(Lifecycle.Read)
+  discounts?: InvoiceDetailedLineDiscounts;
+}
+
+/**
+ * InvoiceLineDiscounts represents the discounts applied to the invoice line by type.
+ */
+@friendlyName("InvoiceDetailedLineDiscounts")
+model InvoiceDetailedLineDiscounts {
+  /**
+   * Amount based discounts applied to the line.
+   *
+   * Amount based discounts are deduced from the total price of the line.
+   */
+  amount?: InvoiceLineAmountDiscount[];
 }
 
 /**

api/openapi.yaml

@@ -205,12 +205,12 @@ func (a App) createInvoice(ctx context.Context, invoice billing.Invoice) (*billi
 	// Add lines to the Stripe invoice
 	var stripeLineAdd []*stripe.InvoiceItemParams
 
-	leafLines := invoice.GetLeafLinesWithConsolidatedTaxBehavior()
+	leafLines := invoice.GetDetailedLinesWithConsolidatedTaxBehavior()
 
 	// Iterate over the leaf lines
 	for _, line := range leafLines {
 		// Add discounts for line if any
-		for _, discount := range line.Discounts.Amount {
+		for _, discount := range line.AmountDiscounts {
 			stripeLineAdd = append(stripeLineAdd, getDiscountStripeAddInvoiceItemParams(calculator, line, discount, stripeCustomerData.StripeCustomerID))
 		}
 
@@ -304,7 +304,7 @@ func (a App) updateInvoice(ctx context.Context, invoice billing.Invoice) (*billi
 		stripeLinesRemove []string
 	)
 
-	leafLines := invoice.GetLeafLinesWithConsolidatedTaxBehavior()
+	leafLines := invoice.GetDetailedLinesWithConsolidatedTaxBehavior()
 
 	// Helper to get a Stripe line item by ID
 	stripeLinesByID := make(map[string]*stripe.InvoiceLineItem)
@@ -319,7 +319,7 @@ func (a App) updateInvoice(ctx context.Context, invoice billing.Invoice) (*billi
 
 	// Iterate over the leaf lines
 	for _, line := range leafLines {
-		amountDiscountsById, err := line.Discounts.Amount.GetByID()
+		amountDiscountsById, err := line.AmountDiscounts.GetByID()
 		if err != nil {
 			return nil, fmt.Errorf("failed to get amount discounts by ID: %w", err)
 		}
@@ -452,7 +452,7 @@ func sortInvoiceLines[K StripeInvoiceLineOperationParams](stripeLineAdd []*K) {
 // getDiscountStripeUpdateInvoiceItemParams returns the Stripe line item for a discount
 func getDiscountStripeUpdateInvoiceItemParams(
 	calculator StripeCalculator,
-	line *billing.Line,
+	line billing.DetailedLine,
 	discount billing.AmountLineDiscountManaged,
 	stripeLine *stripe.InvoiceLineItem,
 ) *stripeclient.StripeInvoiceItemWithID {
@@ -463,7 +463,7 @@ func getDiscountStripeUpdateInvoiceItemParams(
 }
 
 // getDiscountStripeInvoiceItemParams returns the Stripe line item for a discount
-func getDiscountStripeInvoiceItemParams(calculator StripeCalculator, line *billing.Line, discount billing.AmountLineDiscountManaged) *stripe.InvoiceItemParams {
+func getDiscountStripeInvoiceItemParams(calculator StripeCalculator, line billing.DetailedLine, discount billing.AmountLineDiscountManaged) *stripe.InvoiceItemParams {
 	name := getDiscountLineName(line, discount)
 	period := getPeriod(line)
 
@@ -480,14 +480,14 @@ func getDiscountStripeInvoiceItemParams(calculator StripeCalculator, line *billi
 	return applyTaxSettingsToInvoiceItem(addParams, line)
 }
 
-func getDiscountStripeAddInvoiceItemParams(calculator StripeCalculator, line *billing.Line, discount billing.AmountLineDiscountManaged, stripeCustomerID string) *stripe.InvoiceItemParams {
+func getDiscountStripeAddInvoiceItemParams(calculator StripeCalculator, line billing.DetailedLine, discount billing.AmountLineDiscountManaged, stripeCustomerID string) *stripe.InvoiceItemParams {
 	params := getDiscountStripeInvoiceItemParams(calculator, line, discount)
 	// Customer is required for adds
 	params.Customer = stripe.String(stripeCustomerID)
 	return params
 }
 
-func applyTaxSettingsToInvoiceItem(add *stripe.InvoiceItemParams, line *billing.Line) *stripe.InvoiceItemParams {
+func applyTaxSettingsToInvoiceItem(add *stripe.InvoiceItemParams, line billing.DetailedLine) *stripe.InvoiceItemParams {
 	if line.TaxConfig != nil && !lo.IsEmpty(line.TaxConfig) {
 		if line.TaxConfig.Behavior != nil {
 			add.TaxBehavior = getStripeTaxBehavior(line.TaxConfig.Behavior)
@@ -504,7 +504,7 @@ func applyTaxSettingsToInvoiceItem(add *stripe.InvoiceItemParams, line *billing.
 // getStripeUpdateInvoiceItemParams returns the Stripe update line params
 func getStripeUpdateInvoiceItemParams(
 	calculator StripeCalculator,
-	line *billing.Line,
+	line billing.DetailedLine,
 	stripeLine *stripe.InvoiceLineItem,
 ) *stripeclient.StripeInvoiceItemWithID {
 	return &stripeclient.StripeInvoiceItemWithID{
@@ -514,7 +514,7 @@ func getStripeUpdateInvoiceItemParams(
 }
 
 // getStripeAddLinesLineParams returns the Stripe line item
-func getStripeInvoiceItemParams(line *billing.Line, calculator StripeCalculator) *stripe.InvoiceItemParams {
+func getStripeInvoiceItemParams(line billing.DetailedLine, calculator StripeCalculator) *stripe.InvoiceItemParams {
 	description := getLineName(line)
 	period := getPeriod(line)
 	amount := line.Totals.Amount
@@ -551,22 +551,22 @@ func getStripeInvoiceItemParams(line *billing.Line, calculator StripeCalculator)
 }
 
 // getStripeAddInvoiceItemParams returns the Stripe line item
-func getStripeAddInvoiceItemParams(line *billing.Line, calculator StripeCalculator, stripeCustomerID string) *stripe.InvoiceItemParams {
+func getStripeAddInvoiceItemParams(line billing.DetailedLine, calculator StripeCalculator, stripeCustomerID string) *stripe.InvoiceItemParams {
 	params := getStripeInvoiceItemParams(line, calculator)
 	params.Customer = stripe.String(stripeCustomerID)
 	return params
 }
 
 // getPeriod returns the period
-func getPeriod(line *billing.Line) *stripe.InvoiceItemPeriodParams {
+func getPeriod(line billing.DetailedLine) *stripe.InvoiceItemPeriodParams {
 	return &stripe.InvoiceItemPeriodParams{
 		Start: lo.ToPtr(line.Period.Start.Unix()),
 		End:   lo.ToPtr(line.Period.End.Unix()),
 	}
 }
 
 // getDiscountLineName returns the line name
-func getDiscountLineName(line *billing.Line, discount billing.AmountLineDiscountManaged) string {
+func getDiscountLineName(line billing.DetailedLine, discount billing.AmountLineDiscountManaged) string {
 	name := line.Name
 	if discount.Description != nil {
 		name = fmt.Sprintf("%s (%s)", name, *discount.Description)
@@ -576,7 +576,7 @@ func getDiscountLineName(line *billing.Line, discount billing.AmountLineDiscount
 }
 
 // getLineName returns the line name
-func getLineName(line *billing.Line) string {
+func getLineName(line billing.DetailedLine) string {
 	name := line.Name
 	if line.Description != nil {
 		name = fmt.Sprintf("%s (%s)", name, *line.Description)

api/spec/src/billing/invoices/invoice.tsp

@@ -80,9 +80,9 @@ func (a *adapter) UpsertInvoiceLines(ctx context.Context, inputIn billing.Upsert
 					SetNillableSplitLineGroupID(line.SplitLineGroupID).
 					SetNillableDeletedAt(line.DeletedAt).
 					SetInvoiceAt(line.InvoiceAt.In(time.UTC)).
-					SetStatus(line.Status).
+					SetStatus(billing.InvoiceLineStatusValid).
 					SetManagedBy(line.ManagedBy).
-					SetType(line.Type).
+					SetType(billing.InvoiceLineTypeUsageBased).
 					SetName(line.Name).
 					SetNillableDescription(line.Description).
 					SetCurrency(line.Currency).
@@ -288,9 +288,9 @@ func (a *adapter) UpsertInvoiceLines(ctx context.Context, inputIn billing.Upsert
 	})
 }
 
-func (a *adapter) upsertFeeLineConfig(ctx context.Context, in diff[*billing.Line]) error {
-	return upsertWithOptions(ctx, a.db, in, upsertInput[*billing.Line, *db.BillingInvoiceFlatFeeLineConfigCreate]{
-		Create: func(tx *db.Client, line *billing.Line) (*db.BillingInvoiceFlatFeeLineConfigCreate, error) {
+func (a *adapter) upsertFeeLineConfig(ctx context.Context, in diff[*billing.DetailedLine]) error {
+	return upsertWithOptions(ctx, a.db, in, upsertInput[*billing.DetailedLine, *db.BillingInvoiceFlatFeeLineConfigCreate]{
+		Create: func(tx *db.Client, line *billing.DetailedLine) (*db.BillingInvoiceFlatFeeLineConfigCreate, error) {
 			if line.FlatFee.ConfigID == "" {
 				line.FlatFee.ConfigID = ulid.Make().String()
 			}
@@ -302,10 +302,7 @@ func (a *adapter) upsertFeeLineConfig(ctx context.Context, in diff[*billing.Line
 				SetPaymentTerm(line.FlatFee.PaymentTerm).
 				SetID(line.FlatFee.ConfigID)
 
-			if line.Status == billing.InvoiceLineStatusDetailed {
-				// TODO[later]: Detailed lines must be a separate entity, so that we don't need these hacks (like line config or type specific sets)
-				create = create.SetNillableIndex(line.FlatFee.Index)
-			}
+			create = create.SetNillableIndex(line.FlatFee.Index)
 
 			return create, nil
 		},