feat(customers): group credit notes by entity (#5565)

## Context

The customer detail page is replacing its single "Total amount
available" credit-notes summary card with a per-(currency × billing
entity) breakdown table, mirroring the Invoice balances treatment that's
landing alongside it. Today the `customer.creditNotesBalances` GraphQL
field only groups by currency, so customers transacting across multiple
billing entities cannot see their balances split by entity, and there's
no per-bucket count of credit notes for the row subtitle.

## Description

`CustomerCreditNotesBalance` now exposes two new non-null fields
(`billingEntityId: ID!` and `creditsAvailableCount: Int!`) in addition
to the existing `currency` and `amountCents`. The
`customer.creditNotesBalances` resolver groups finalized credit notes by
both currency and billing entity (joining `invoices`) and emits one row
per `(currency, billingEntity)` pair, returning the sum of
`balance_amount_cents` and the count of finalized credit notes with
`credit_amount_cents > 0`.

The previous `balance_amount_cents > 0` filter is removed so buckets
with fully-consumed credits still flow through: this is required so the
consumer can render the "credit notes issued & credited" subtitle even
when the available balance is zero. The consumer applies visibility
client-side via `amountCents > 0 OR creditsAvailableCount > 0`.

Old vs new response shape for the same customer (one billing entity,
single currency, and one cross-entity case):

| Customer | Before | After |
| --- | --- | --- |
| Single-entity, single-currency | `[{ currency: "EUR", amountCents:
1500 }]` | `[{ currency: "EUR", billingEntityId: "...", amountCents:
1500, creditsAvailableCount: 3 }]` |
| Cross-currency, cross-entity (3 buckets) | 1 row per currency only | 1
row per `(currency, billingEntity)` pair |
| Fully-consumed bucket | omitted | included with `amountCents: 0` and
`creditsAvailableCount > 0` |

Implementation notes:
- Uses PostgreSQL's `COUNT(*) FILTER (WHERE ...)` rather than
`COUNT(CASE WHEN ...)`. Lago is PG-only; the FILTER form is equivalent
and more idiomatic.
- Raw SQL aggregates are wrapped in `Arel.sql(...)` to satisfy Rails 8's
`disable_joins`-style protection against unsafe `pluck` inputs.
- `joins(:invoice)` is safe: `credit_notes.invoice_id` is `NOT NULL`
with a FK, and `invoices.billing_entity_id` is `NOT NULL` at the DB
level, so no rows are dropped and the new `ID!` typing is sound.
- `schema.graphql` and `schema.json` are regenerated.

## How to try locally

1. Check out the branch and rebuild the API container if needed.
2. Seed or open a customer with credit notes across multiple currencies
and billing entities (a quick `rails console` script that creates a
couple of `:billing_entity`, a couple of `:invoice`, and several
`:credit_note` records works).
3. Run the GraphQL query against the customer:
   ```graphql
   query($id: ID!) {
     customer(id: $id) {
       creditNotesBalances {
         currency
         billingEntityId
         amountCents
         creditsAvailableCount
       }
     }
   }
   ```
Confirm: one row per `(currency, billingEntityId)` pair, amounts sum
correctly per bucket, and counts only include credit notes with
`credit_amount_cents > 0`.
4. Verify a single-entity, single-currency customer still returns
exactly one row (no regression).
5. `bundle exec rspec spec/graphql/types/customers/object_spec.rb
spec/graphql/lago_api_schema_spec.rb` to confirm the new behavior specs
and the schema-dump cross-check both pass.

Author: aquinofb

app/graphql/types/customers/credit_notes_balance.rb

@@ -6,6 +6,8 @@ class CreditNotesBalance < Types::BaseObject
       graphql_name "CustomerCreditNotesBalance"
 
       field :amount_cents, GraphQL::Types::BigInt, null: false
+      field :billing_entity_id, ID, null: false
+      field :credits_available_count, Integer, null: false
       field :currency, Types::CurrencyEnum, null: false
     end
   end

app/graphql/types/customers/object.rb

@@ -85,7 +85,7 @@ class Object < Types::BaseObject
       field :credit_notes_balances,
         [Types::Customers::CreditNotesBalance],
         null: false,
-        description: "Credit notes credits balance available per customer per currency"
+        description: "Credit notes balances broken down by (currency, billing entity)"
       field :credit_notes_credits_available_count,
         Integer,
         null: false,
@@ -166,12 +166,16 @@ def credit_notes_balance_amount_cents
       end
 
       def credit_notes_balances
-        object.credit_notes
-          .finalized
-          .where("credit_notes.balance_amount_cents > 0")
-          .group("credit_notes.total_amount_currency")
-          .sum("credit_notes.balance_amount_cents")
-          .map { |currency, amount_cents| {currency:, amount_cents:} }
+        object.credit_notes.finalized.joins(:invoice)
+          .group("credit_notes.total_amount_currency", "invoices.billing_entity_id")
+          .pluck(
+            "credit_notes.total_amount_currency",
+            "invoices.billing_entity_id",
+            Arel.sql("SUM(credit_notes.balance_amount_cents)"),
+            Arel.sql("COUNT(*) FILTER (WHERE credit_notes.credit_amount_cents > 0)")
+          ).map { |currency, billing_entity_id, amount_cents, credits_available_count|
+            {currency:, billing_entity_id:, amount_cents:, credits_available_count:}
+          }
       end
 
       def billing_configuration

schema.graphql

@@ -90,4 +90,137 @@
 
     expect(subject).to have_field(:error_details).of_type("[ErrorDetail!]")
   end
+
+  describe "credit_notes_balances grouping" do
+    let(:required_permission) { "customers:view" }
+    let(:membership) { create(:membership) }
+    let(:organization) { membership.organization }
+    let(:customer) { create(:customer, organization:) }
+    let(:billing_entity_a) { create(:billing_entity, organization:) }
+    let(:billing_entity_b) { create(:billing_entity, organization:) }
+
+    let(:query) do
+      <<~GQL
+        query($customerId: ID!) {
+          customer(id: $customerId) {
+            creditNotesBalances {
+              currency
+              billingEntityId
+              amountCents
+              creditsAvailableCount
+            }
+          }
+        }
+      GQL
+    end
+
+    def execute
+      execute_graphql(
+        current_user: membership.user,
+        current_organization: organization,
+        permissions: required_permission,
+        query:,
+        variables: {customerId: customer.id}
+      ).dig("data", "customer", "creditNotesBalances")
+    end
+
+    context "with a single (currency, billing entity) bucket" do
+      before do
+        invoice = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        create(:credit_note, customer:, organization:, invoice:,
+          total_amount_currency: "EUR", balance_amount_cents: 100, credit_amount_cents: 100)
+        create(:credit_note, customer:, organization:, invoice:,
+          total_amount_currency: "EUR", balance_amount_cents: 50, credit_amount_cents: 50)
+      end
+
+      it "returns one row aggregating both credit notes" do
+        expect(execute).to match_array([
+          {
+            "currency" => "EUR",
+            "billingEntityId" => billing_entity_a.id,
+            "amountCents" => "150",
+            "creditsAvailableCount" => 2
+          }
+        ])
+      end
+    end
+
+    context "with multiple currencies under one billing entity" do
+      before do
+        invoice_eur = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        invoice_usd = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        create(:credit_note, customer:, organization:, invoice: invoice_eur,
+          total_amount_currency: "EUR", balance_amount_cents: 100, credit_amount_cents: 100)
+        create(:credit_note, customer:, organization:, invoice: invoice_usd,
+          total_amount_currency: "USD", balance_amount_cents: 200, credit_amount_cents: 200)
+      end
+
+      it "returns one row per currency for the same billing entity" do
+        expect(execute).to match_array([
+          {"currency" => "EUR", "billingEntityId" => billing_entity_a.id, "amountCents" => "100", "creditsAvailableCount" => 1},
+          {"currency" => "USD", "billingEntityId" => billing_entity_a.id, "amountCents" => "200", "creditsAvailableCount" => 1}
+        ])
+      end
+    end
+
+    context "with multiple billing entities under one currency" do
+      before do
+        invoice_a = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        invoice_b = create(:invoice, customer:, organization:, billing_entity: billing_entity_b)
+        create(:credit_note, customer:, organization:, invoice: invoice_a,
+          total_amount_currency: "EUR", balance_amount_cents: 100, credit_amount_cents: 100)
+        create(:credit_note, customer:, organization:, invoice: invoice_b,
+          total_amount_currency: "EUR", balance_amount_cents: 400, credit_amount_cents: 400)
+      end
+
+      it "returns one row per billing entity for the same currency" do
+        expect(execute).to match_array([
+          {"currency" => "EUR", "billingEntityId" => billing_entity_a.id, "amountCents" => "100", "creditsAvailableCount" => 1},
+          {"currency" => "EUR", "billingEntityId" => billing_entity_b.id, "amountCents" => "400", "creditsAvailableCount" => 1}
+        ])
+      end
+    end
+
+    context "with multiple currencies and billing entities combined" do
+      before do
+        invoice_eur_a = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        invoice_usd_a = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        invoice_eur_b = create(:invoice, customer:, organization:, billing_entity: billing_entity_b)
+        create(:credit_note, customer:, organization:, invoice: invoice_eur_a,
+          total_amount_currency: "EUR", balance_amount_cents: 100, credit_amount_cents: 100)
+        create(:credit_note, customer:, organization:, invoice: invoice_usd_a,
+          total_amount_currency: "USD", balance_amount_cents: 200, credit_amount_cents: 200)
+        create(:credit_note, customer:, organization:, invoice: invoice_eur_b,
+          total_amount_currency: "EUR", balance_amount_cents: 400, credit_amount_cents: 400)
+      end
+
+      it "returns one row per (currency, billing entity) pair" do
+        expect(execute).to match_array([
+          {"currency" => "EUR", "billingEntityId" => billing_entity_a.id, "amountCents" => "100", "creditsAvailableCount" => 1},
+          {"currency" => "USD", "billingEntityId" => billing_entity_a.id, "amountCents" => "200", "creditsAvailableCount" => 1},
+          {"currency" => "EUR", "billingEntityId" => billing_entity_b.id, "amountCents" => "400", "creditsAvailableCount" => 1}
+        ])
+      end
+    end
+
+    context "with a fully-consumed credit (zero balance, positive credit amount)" do
+      before do
+        invoice = create(:invoice, customer:, organization:, billing_entity: billing_entity_a)
+        create(:credit_note, customer:, organization:, invoice:,
+          total_amount_currency: "EUR", balance_amount_cents: 0, credit_amount_cents: 500)
+      end
+
+      it "still returns the bucket so the FE can render the 'credited' subtitle" do
+        expect(execute).to match_array([
+          {"currency" => "EUR", "billingEntityId" => billing_entity_a.id, "amountCents" => "0", "creditsAvailableCount" => 1}
+        ])
+      end
+    end
+
+    context "when the customer has no finalized credit notes" do
+      it "returns an empty array" do
+        expect(execute).to eq([])
+      end
+    end
+  end
 end