refactor: simplify invoicing api

api/spec/src/billing/invoices.tsp

@@ -563,23 +563,13 @@ model InvoiceSimulationInput {
 }
 
 /**
- * InvoiceSimulationInput represents a line item that can be input to the simulation endpoint.
+ * InvoiceSimulationLine represents a usage-based line item that can be input to the simulation endpoint.
  */
 @friendlyName("InvoiceSimulationLine")
-@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
-union InvoiceSimulationLine {
-  usage_based: InvoiceSimulationUsageBasedLine,
-  flat_fee: InvoiceSimulationFlatFeeLine,
-}
-
-/**
- * InvoiceSimulationUsageBasedLine represents a usage-based line item that can be input to the simulation endpoint.
- */
-@friendlyName("InvoiceSimulationUsageBasedLine")
-model InvoiceSimulationUsageBasedLine {
+model InvoiceSimulationLine {
   ...TypeSpec.Rest.Resource.ResourceCreateModel<OmitProperties<
-    Invoice.InvoiceUsageBasedLine,
-    "invoice" | "currency"
+    Invoice.InvoiceLine,
+    "invoice" | "currency" | "children"
   >>;
 
   /**
@@ -603,25 +593,6 @@ model InvoiceSimulationUsageBasedLine {
   id?: ULID;
 }
 
-/**
- * InvoiceSimulationFlatFeeLine represents a flat fee line item that can be input to the simulation endpoint.
- */
-@friendlyName("InvoiceSimulationFlatFeeLine")
-model InvoiceSimulationFlatFeeLine {
-  ...TypeSpec.Rest.Resource.ResourceCreateModel<OmitProperties<
-    Invoice.InvoiceFlatFeeLine,
-    "invoice" | "currency"
-  >>;
-
-  /**
-   * ID of the line. If not specified it will be auto-generated.
-   *
-   * When discounts are specified, this must be provided, so that the discount can reference it.
-   */
-  @visibility(Lifecycle.Create)
-  id?: ULID;
-}
-
 /**
  * InvoiceReplaceUpdate represents the update model for an invoice.
  */

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

@@ -13,7 +13,7 @@ namespace OpenMeter.Billing.Invoice;
  */
 @friendlyName("InvoiceDocumentRefType")
 enum InvoiceDocumentRefType {
-  creditNoteOriginalInvoice: "credit_node_original_invoice",
+  creditNoteOriginalInvoice: "credit_note_original_invoice",
 }
 
 /**

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

@@ -420,54 +420,15 @@ enum InvoiceType {
 }
 
 /**
- * BillingInvoiceLine represents a line item that is sold to the customer based on a specific (unit) price.
- */
-@friendlyName("InvoiceLine")
-@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
-union InvoiceLine {
-  usage_based: InvoiceUsageBasedLine,
-  flat_fee: InvoiceFlatFeeLine,
-}
-
-/**
- * InvoiceLineReplaceUpdate represents the update model for an invoice line.
- */
-@friendlyName("InvoiceLineReplaceUpdate")
-@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
-union InvoiceLineReplaceUpdate {
-  usage_based: InvoiceUsageBasedLineReplaceUpdate,
-  flat_fee: InvoiceFlatFeeLineReplaceUpdate,
-}
-
-/**
- * InvoiceUpdateUsageBasedLineReplaceUpdate represents the update model for an UBP invoice line.
- *
- * This type makes ID optional to allow for creating new lines as part of the update.
- */
-@friendlyName("InvoiceUsageBasedLineReplaceUpdate")
-model InvoiceUsageBasedLineReplaceUpdate {
-  ...TypeSpec.Rest.Resource.ResourceReplaceModel<OmitProperties<
-    InvoiceUsageBasedLine,
-    "id"
-  >>;
-
-  /**
-   * The ID of the line.
-   */
-  @visibility(Lifecycle.Update)
-  id?: ULID;
-}
-
-/**
- * InvoiceFlatFeeLineReplaceUpdate represents the update model for a flat fee invoice line.
+ * InvoiceLineReplaceUpdate represents the update model for an UBP invoice line.
  *
  * This type makes ID optional to allow for creating new lines as part of the update.
  */
-@friendlyName("InvoiceFlatFeeLineReplaceUpdate")
-model InvoiceFlatFeeLineReplaceUpdate {
+@friendlyName("InvoiceLineReplaceUpdate")
+model InvoiceLineReplaceUpdate {
   ...TypeSpec.Rest.Resource.ResourceReplaceModel<OmitProperties<
-    InvoiceFlatFeeLine,
-    "id"
+    InvoiceLine,
+    "id" | "children"
   >>;
 
   /**
@@ -478,42 +439,21 @@ model InvoiceFlatFeeLineReplaceUpdate {
 }
 
 /**
- * InvoiceLineCreate represents the create model for an invoice line.
+ * InvoicePendingLineCreate represents the create model for an invoice line that is sold to the customer based on usage.
  */
 @friendlyName("InvoicePendingLineCreate")
-@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
-union InvoicePendingLineCreate {
-  usage_based: InvoiceUsageBasedPendingLineCreate,
-  flat_fee: InvoiceFlatFeePendingLineCreate,
-}
-
-/**
- * InvoiceUsageBasedLineCreateWithCustomer represents the create model for an invoice line that is sold to the customer based on usage.
- */
-@friendlyName("InvoiceUsageBasedPendingLineCreate")
-model InvoiceUsageBasedPendingLineCreate {
-  // Note: invoice is omitted as the line is assigned a new or existing gathering invoice
-  ...TypeSpec.Rest.Resource.ResourceCreateModel<OmitProperties<
-    InvoiceUsageBasedLine,
-    "invoice" | "currency"
-  >>;
-}
-
-/**
- * InvoiceFlatFeePendingLineCreate represents the create model for an invoice line that is sold to the customer as a manually added fee.
- */
-@friendlyName("InvoiceFlatFeePendingLineCreate")
-model InvoiceFlatFeePendingLineCreate {
+model InvoicePendingLineCreate {
   // Note: invoice is omitted as the line is assigned a new or existing gathering invoice
   ...TypeSpec.Rest.Resource.ResourceCreateModel<OmitProperties<
-    InvoiceFlatFeeLine,
-    "invoice" | "currency"
+    InvoiceLine,
+    "invoice" | "currency" | "children"
   >>;
 }
 
 /**
  * LineTypes represents the different types of lines that can be used in an invoice.
  */
+#deprecated "We are moving to a coherent invoice line structure"
 @friendlyName("InvoiceLineTypes")
 enum InvoiceLineTypes {
   flatFee: "flat_fee",
@@ -594,7 +534,8 @@ model InvoiceLineBase {
    *
    * A line's type cannot be changed after creation.
    */
-  @visibility(Lifecycle.Read, Lifecycle.Create)
+  #deprecated "We are moving to a coherent invoice line structure"
+  @visibility(Lifecycle.Read)
   type: InvoiceLineTypes;
 
   /**
@@ -646,12 +587,6 @@ model InvoiceLineBase {
   @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
   taxConfig?: OpenMeter.ProductCatalog.TaxConfig;
 
-  /**
-   * The lines detailing the item or service sold.
-   */
-  @visibility(Lifecycle.Read)
-  children?: InvoiceLine[];
-
   /**
    * Totals for this line.
    */
@@ -723,19 +658,22 @@ model InvoiceUsageBasedRateCard {
 
 /**
  * InvoiceUsageBasedLine represents a line item that is sold to the customer based on usage. */
-@friendlyName("InvoiceUsageBasedLine")
-model InvoiceUsageBasedLine {
+@friendlyName("InvoiceLine")
+model InvoiceLine {
   ...OmitProperties<InvoiceLineBase, "type">;
 
   /**
    * Type of the line.
    */
+  #deprecated "Invoice always has usage-based line children"
+  @visibility(Lifecycle.Read)
   type: InvoiceLineTypes.usageBased;
 
   /**
    * Price of the usage-based item being sold.
    */
   #deprecated "Use rateCard.price instead"
+  @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
   price?: OpenMeter.ProductCatalog.RateCardUsageBasedPrice;
 
   /**
@@ -745,6 +683,12 @@ model InvoiceUsageBasedLine {
   @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
   featureKey?: Key;
 
+  /**
+   * The lines detailing the item or service sold.
+   */
+  @visibility(Lifecycle.Read)
+  children?: InvoiceDetailedLine[];
+
   /**
    * The rate card that is used for this line.
    *
@@ -788,11 +732,11 @@ model InvoiceUsageBasedLine {
 }
 
 /**
- * InvoiceFlatFeeRateCard represents the rate card (intent) for a flat fee line.
+ * InvoiceDetailedLineRateCard represents the rate card (intent) for a flat fee line.
  */
-@friendlyName("InvoiceFlatFeeRateCard")
-model InvoiceFlatFeeRateCard {
-  // TODO: Once the deprecation is done, let's make price required
+@friendlyName("InvoiceDetailedLineRateCard")
+model InvoiceDetailedLineRateCard {
+  // TODO[v2]: Once the deprecation is done, let's make price required
   ...PickProperties<
     OpenMeter.ProductCatalog.RateCardFlatFee,
     "taxConfig" | "price"
@@ -814,15 +758,17 @@ model InvoiceFlatFeeRateCard {
 }
 
 /**
- * InvoiceFlatFeeLine represents a line item that is sold to the customer as a manually added fee.
+ * InvoiceDetailedLine represents a line item that is sold to the customer as a manually added fee.
  */
-@friendlyName("InvoiceFlatFeeLine")
-model InvoiceFlatFeeLine {
+@friendlyName("InvoiceDetailedLine")
+model InvoiceDetailedLine {
   ...OmitProperties<InvoiceLineBase, "type">;
 
   /**
    * Type of the line.
    */
+  #deprecated "Invoice line's children are always detailed lines"
+  @visibility(Lifecycle.Read)
   type: InvoiceLineTypes.flatFee;
 
   /**
@@ -849,23 +795,23 @@ model InvoiceFlatFeeLine {
   /**
    * The rate card that is used for this line.
    */
-  // TODO: Once the deprecation is done, let's make rateCard required
+  // TODO[v2]: Once the deprecation is done, let's make rateCard required
   @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
-  rateCard?: InvoiceFlatFeeRateCard;
+  rateCard?: InvoiceDetailedLineRateCard;
 
   /**
    * Category of the flat fee.
    */
-  @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
-  category?: InvoiceFlatFeeCategory = InvoiceFlatFeeCategory.regular;
+  @visibility(Lifecycle.Read)
+  category?: InvoiceDetailedLineCostCategory = InvoiceDetailedLineCostCategory.regular;
 }
 
 /**
- * InvoiceFlatFeeCategory determines if the flat fee is a regular fee due to use due to a
+ * InvoiceDetailedLineCostCategory determines if the flat fee is a regular fee due to use due to a
  * commitment.
  */
-@friendlyName("InvoiceFlatFeeCategory")
-union InvoiceFlatFeeCategory {
+@friendlyName("InvoiceDetailedLineCostCategory")
+union InvoiceDetailedLineCostCategory {
   /**
    * The fee is a regular fee due to usage.
    */