feat(presentation_group_keys): Update serializers to include presentation breakdowns (#5411)

This commit updates the serializers of usage, fee and invoices to
include the breakdowns.

We're including all presentation breakdowns associated to fees in
invoice, in order to do that, this commit
introduces a presentation builder, this class is responsible to group
the breakdowns based on `presentation_by`.
We avoid displaying the same `presentation_by` twice and instead we're
grouping and sum them together.

Serializers are being updated:
- Charge ( Usage / Projected )
- Fee
- Invoice

Author: tiagolupepic

app/controllers/api/v1/fees_controller.rb

@@ -50,7 +50,8 @@ def index
                 :fixed_charge_add_on,
                 :invoice,
                 :invoiceable,
-                :true_up_fee
+                :true_up_fee,
+                :presentation_breakdowns
               ),
               ::V1::FeeSerializer,
               collection_name: "fees",

app/queries/past_usage_query.rb

@@ -46,7 +46,7 @@ def query
   end
 
   def fees_query(invoice)
-    query = invoice.fees.joins(:subscription).where(subscription: {external_id: filters.external_subscription_id}).charge.includes(:charge_filter)
+    query = invoice.fees.joins(:subscription).where(subscription: {external_id: filters.external_subscription_id}).charge.includes(:charge_filter, :presentation_breakdowns)
     return query unless filters.billable_metric_code
 
     query.joins(:charge).where(charges: {billable_metric_id: billable_metric.id})

app/serializers/v1/customers/charge_usage_serializer.rb

@@ -13,7 +13,8 @@ def serialize
             charge: charge_data(fee),
             billable_metric: billable_metric_data(fee),
             filters: filters(fees),
-            grouped_usage: grouped_usage(fees)
+            grouped_usage: grouped_usage(fees),
+            presentation_breakdowns: PresentationBreakdownBuilder.call(fees, filter: PresentationBreakdownBuilder::UNGROUPED)
           }
         end
       end
@@ -110,7 +111,8 @@ def build_grouped_usage_data(grouped_fees)
         {
           **usage_data.except(:amount_currency),
           grouped_by: grouped_fees.first.grouped_by,
-          filters: filters(grouped_fees)
+          filters: filters(grouped_fees),
+          presentation_breakdowns: PresentationBreakdownBuilder.call(grouped_fees, filter: PresentationBreakdownBuilder::GROUPED)
         }
       end
     end

app/serializers/v1/customers/presentation_breakdown_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module V1
+  module Customers
+    class PresentationBreakdownBuilder
+      ALL = :all
+      UNGROUPED = :ungrouped
+      GROUPED = :grouped
+
+      def self.call(fees, filter:)
+        new(fees, filter:).call
+      end
+
+      def initialize(fees, filter:)
+        @fees = fees
+        @filter = filter
+      end
+
+      def call
+        Array(fees).flat_map do |fee|
+          next [] if filter == UNGROUPED && fee.grouped_by.present?
+          next [] if filter == GROUPED && fee.grouped_by.blank?
+
+          fee.presentation_breakdowns.map do |breakdown|
+            ::V1::PresentationBreakdownSerializer.new(breakdown).serialize
+          end
+        end
+      end
+
+      private
+
+      attr_reader :fees, :filter
+    end
+  end
+end

app/serializers/v1/customers/projected_charge_usage_serializer.rb

@@ -15,7 +15,8 @@ def serialize
             charge: charge_data(fee),
             billable_metric: billable_metric_data(fee),
             filters: cached_filters(fees),
-            grouped_usage: cached_grouped_usage(fees)
+            grouped_usage: cached_grouped_usage(fees),
+            presentation_breakdowns: PresentationBreakdownBuilder.call(fees, filter: PresentationBreakdownBuilder::UNGROUPED)
           }
         end
       end
@@ -32,7 +33,7 @@ def calculate_usage_data(fees)
 
       def current_usage_data(fees)
         totals = fees.each_with_object({
-          units: BigDecimal("0"),
+          units: BigDecimal(0),
           events_count: 0,
           amount_cents: 0
         }) do |fee, acc|
@@ -208,7 +209,8 @@ def build_grouped_usage_data(grouped_fees)
         {
           **usage_data.except(:amount_currency),
           grouped_by: grouped_fees.first.grouped_by,
-          filters: filters(grouped_fees)
+          filters: filters(grouped_fees),
+          presentation_breakdowns: PresentationBreakdownBuilder.call(grouped_fees, filter: PresentationBreakdownBuilder::GROUPED)
         }
       end
 

app/serializers/v1/fee_serializer.rb

@@ -56,7 +56,8 @@ def serialize
         refunded_at: model.refunded_at&.iso8601,
         amount_details: model.amount_details,
         self_billed: model.invoice&.self_billed || false,
-        pricing_unit_details:
+        pricing_unit_details:,
+        presentation_breakdowns: model.presentation_breakdowns.map { |breakdown| PresentationBreakdownSerializer.new(breakdown).serialize }
       }
 
       payload.merge!(model.date_boundaries) if model.charge? || model.subscription? || model.add_on? || model.fixed_charge?

app/serializers/v1/invoice_serializer.rb

@@ -93,6 +93,7 @@ def fees
             :customer,
             :charge,
             :billable_metric,
+            :presentation_breakdowns,
             {charge_filter: {values: :billable_metric_filter}}
           ]
         ),

app/serializers/v1/presentation_breakdown_serializer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module V1
+  class PresentationBreakdownSerializer < ModelSerializer
+    def serialize
+      {
+        presentation_by: model.presentation_by,
+        units: model.units.to_s
+      }
+    end
+  end
+end

spec/scenarios/current_usage/by_charge_model/dynamic_spec.rb

@@ -123,8 +123,8 @@
 
             expect(json[:customer_usage][:charges_usage][0][:grouped_usage]).to match_array(
               [
-                {amount_cents: 902, events_count: 1, total_aggregated_units: "10.0", units: "10.0", grouped_by: {group_key: "value 2"}, filters: [], pricing_unit_details: nil},
-                {amount_cents: 10, events_count: 1, total_aggregated_units: "10.0", units: "10.0", grouped_by: {group_key: "value 1"}, filters: [], pricing_unit_details: nil}
+                {amount_cents: 902, events_count: 1, total_aggregated_units: "10.0", units: "10.0", grouped_by: {group_key: "value 2"}, filters: [], pricing_unit_details: nil, presentation_breakdowns: []},
+                {amount_cents: 10, events_count: 1, total_aggregated_units: "10.0", units: "10.0", grouped_by: {group_key: "value 1"}, filters: [], pricing_unit_details: nil, presentation_breakdowns: []}
               ]
             )
           end

spec/serializers/v1/customers/charge_usage_serializer_spec.rb

@@ -19,6 +19,7 @@
   let(:ratio) { days_passed.to_f / charges_duration }
 
   let(:pricing_unit_usage) { nil }
+  let(:presentation_breakdowns) { [] }
 
   let(:usage) do
     [
@@ -44,7 +45,8 @@
         aggregation_type: billable_metric.aggregation_type,
         grouped_by: {"card_type" => "visa"},
         charge_filter: nil,
-        pricing_unit_usage:
+        pricing_unit_usage:,
+        presentation_breakdowns:
       )
     ]
   end
@@ -73,6 +75,7 @@
         "aggregation_type" => billable_metric.aggregation_type
       },
       "filters" => [],
+      "presentation_breakdowns" => [],
       "grouped_usage" => [
         {
           "amount_cents" => 100,
@@ -81,12 +84,165 @@
           "units" => "10.0",
           "total_aggregated_units" => "10.0",
           "grouped_by" => {"card_type" => "visa"},
-          "filters" => []
+          "filters" => [],
+          "presentation_breakdowns" => []
         }
       ]
     )
   end
 
+  context "when contains presentation breakdowns" do
+    let(:presentation_breakdowns) do
+      [
+        build(:presentation_breakdown, presentation_by: {"card_type" => "visa"}, units: "8"),
+        build(:presentation_breakdown, presentation_by: {"card_type" => "mastercard"}, units: "1"),
+        build(:presentation_breakdown, presentation_by: {"country" => "pt"}, units: "3")
+      ]
+    end
+
+    it "serializes the breakdowns" do
+      expect(result["charges"].first["presentation_breakdowns"]).to eq([])
+      expect(result["charges"].first["grouped_usage"].first["presentation_breakdowns"]).to match_array(
+        [
+          {"presentation_by" => {"card_type" => "visa"}, "units" => "8.0"},
+          {"presentation_by" => {"card_type" => "mastercard"}, "units" => "1.0"},
+          {"presentation_by" => {"country" => "pt"}, "units" => "3.0"}
+        ]
+      )
+    end
+  end
+
+  context "when usage contains two objects, one with grouped_by and other without grouped_by" do
+    let(:other_charge) { create(:standard_charge, plan: charge.plan) }
+    let(:other_billable_metric) { other_charge.billable_metric }
+    let(:empty_group_presentation_breakdowns) { [] }
+    let(:visa_group_presentation_breakdowns) { [] }
+
+    let(:usage) do
+      [
+        OpenStruct.new(
+          charge_id: charge.id,
+          subscription:,
+          billable_metric: billable_metric,
+          charge: charge,
+          units: "2",
+          total_aggregated_units: "2",
+          events_count: 2,
+          amount_cents: 20,
+          amount_currency: "EUR",
+          properties: {
+            "from_datetime" => from_datetime.to_s,
+            "to_datetime" => to_datetime.to_s,
+            "charges_duration" => charges_duration
+          },
+          invoice_display_name: charge.invoice_display_name,
+          lago_id: billable_metric.id,
+          name: billable_metric.name,
+          code: billable_metric.code,
+          aggregation_type: billable_metric.aggregation_type,
+          grouped_by: {},
+          charge_filter: nil,
+          pricing_unit_usage: pricing_unit_usage,
+          presentation_breakdowns: empty_group_presentation_breakdowns
+        ),
+        OpenStruct.new(
+          charge_id: other_charge.id,
+          subscription:,
+          billable_metric: other_billable_metric,
+          charge: other_charge,
+          units: "8",
+          total_aggregated_units: "8",
+          events_count: 10,
+          amount_cents: 80,
+          amount_currency: "EUR",
+          properties: {
+            "from_datetime" => from_datetime.to_s,
+            "to_datetime" => to_datetime.to_s,
+            "charges_duration" => charges_duration
+          },
+          invoice_display_name: other_charge.invoice_display_name,
+          lago_id: other_billable_metric.id,
+          name: other_billable_metric.name,
+          code: other_billable_metric.code,
+          aggregation_type: other_billable_metric.aggregation_type,
+          grouped_by: {"card_type" => "visa"},
+          charge_filter: nil,
+          pricing_unit_usage: pricing_unit_usage,
+          presentation_breakdowns: visa_group_presentation_breakdowns
+        )
+      ]
+    end
+
+    it "serializes grouped usage including empty group" do
+      expect(result["charges"].length).to eq(2)
+
+      empty_group_charge = result["charges"].find { |c| c.dig("charge", "lago_id") == charge.id }
+      visa_group_charge = result["charges"].find { |c| c.dig("charge", "lago_id") == other_charge.id }
+
+      expect(empty_group_charge).to include(
+        "units" => "2.0",
+        "total_aggregated_units" => "2.0",
+        "events_count" => 2,
+        "amount_cents" => 20,
+        "grouped_usage" => [],
+        "presentation_breakdowns" => []
+      )
+
+      expect(visa_group_charge).to include(
+        "units" => "8.0",
+        "total_aggregated_units" => "8.0",
+        "events_count" => 10,
+        "amount_cents" => 80,
+        "grouped_usage" => [
+          {
+            "amount_cents" => 80,
+            "pricing_unit_details" => nil,
+            "events_count" => 10,
+            "units" => "8.0",
+            "total_aggregated_units" => "8.0",
+            "grouped_by" => {"card_type" => "visa"},
+            "filters" => [],
+            "presentation_breakdowns" => []
+          }
+        ]
+      )
+    end
+
+    context "when contains presentation breakdowns" do
+      let(:empty_group_presentation_breakdowns) do
+        [
+          build(:presentation_breakdown, presentation_by: {"card_type" => "visa"}, units: "8"),
+          build(:presentation_breakdown, presentation_by: {"country" => "pt"}, units: "3")
+        ]
+      end
+      let(:visa_group_presentation_breakdowns) do
+        [
+          build(:presentation_breakdown, presentation_by: {"card_type" => "mastercard"}, units: "1")
+        ]
+      end
+
+      it "serializes breakdowns for ungrouped and grouped usage" do
+        empty_group_charge = result["charges"].find { |c| c.dig("charge", "lago_id") == charge.id }
+        visa_group_charge = result["charges"].find { |c| c.dig("charge", "lago_id") == other_charge.id }
+
+        expect(empty_group_charge["grouped_usage"]).to eq([])
+        expect(empty_group_charge["presentation_breakdowns"]).to match_array(
+          [
+            {"presentation_by" => {"card_type" => "visa"}, "units" => "8.0"},
+            {"presentation_by" => {"country" => "pt"}, "units" => "3.0"}
+          ]
+        )
+
+        expect(visa_group_charge["presentation_breakdowns"]).to eq([])
+        expect(visa_group_charge["grouped_usage"].first["presentation_breakdowns"]).to match_array(
+          [
+            {"presentation_by" => {"card_type" => "mastercard"}, "units" => "1.0"}
+          ]
+        )
+      end
+    end
+  end
+
   context "when charge configured to use pricing units" do
     let(:pricing_unit_usage) do
       PricingUnitUsage.new(amount_cents: 200, conversion_rate: 0.5, short_name: "CR")
@@ -116,6 +272,7 @@
           "aggregation_type" => billable_metric.aggregation_type
         },
         "filters" => [],
+        "presentation_breakdowns" => [],
         "grouped_usage" => [
           {
             "amount_cents" => 100,
@@ -128,7 +285,8 @@
             "units" => "10.0",
             "total_aggregated_units" => "10.0",
             "grouped_by" => {"card_type" => "visa"},
-            "filters" => []
+            "filters" => [],
+            "presentation_breakdowns" => []
           }
         ]
       )
@@ -157,7 +315,8 @@
           grouped_by: {"card_type" => "visa"},
           charge_filter:,
           charge_filter_id: charge_filter.id,
-          pricing_unit_usage:
+          pricing_unit_usage:,
+          presentation_breakdowns:
         )
       end
     end