feat(credit_notes): Expose credit notes in API

app/controllers/api/v1/credit_notes_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class CreditNotesController < Api::BaseController
+      def show
+        credit_note = current_organization.credit_notes.find_by(id: params[:id])
+        return not_found_error(resource: 'credit_note') unless credit_note
+
+        render(
+          json: ::V1::CreditNoteSerializer.new(
+            credit_note,
+            root_name: 'credit_note',
+            includes: %i[items],
+          ),
+        )
+      end
+
+      def index
+        credit_notes = current_organization.credit_notes
+
+        if params[:external_customer_id]
+          credit_notes = credit_notes.joins(:customer).where(customers: { external_id: params[:external_customer_id] })
+        end
+
+        credit_notes = credit_notes.order(created_at: :desc)
+          .page(params[:page])
+          .per(params[:per_page] || PER_PAGE)
+
+        render(
+          json: ::CollectionSerializer.new(
+            credit_notes,
+            ::V1::CreditNoteSerializer,
+            collection_name: 'credit_notes',
+            meta: pagination_metadata(credit_notes),
+          ),
+        )
+      end
+    end
+  end
+end

app/models/customer.rb

@@ -13,6 +13,7 @@ class Customer < ApplicationRecord
   has_many :invoices
   has_many :applied_coupons
   has_many :coupons, through: :applied_coupons
+  has_many :credit_notes
   has_many :applied_add_ons
   has_many :add_ons, through: :applied_add_ons
   has_many :wallets

app/serializers/v1/credit_note_item_serializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module V1
+  class CreditNoteItemSerializer < ModelSerializer
+    def serialize
+      {
+        lago_id: model.id,
+        amount_cents: model.amount_cents,
+        amount_currency: model.amount_currency,
+        fee: fee,
+      }
+    end
+
+    private
+
+    def fee
+      ::V1::FeeSerializer.new(
+        model.fee,
+      ).serialize
+    end
+  end
+end

app/serializers/v1/credit_note_serializer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module V1
+  class CreditNoteSerializer < ModelSerializer
+    def serialize
+      payload = {
+        lago_id: model.id,
+        sequential_id: model.sequential_id,
+        number: model.number,
+        lago_invoice_id: model.invoice_id,
+        invoice_number: model.invoice.number,
+        status: model.status,
+        reason: model.reason,
+        amount_cents: model.amount_cents,
+        amount_currency: model.amount_currency,
+        remaining_amount_cents: model.remaining_amount_cents,
+        remaining_amount_currency: model.remaining_amount_currency,
+        created_at: model.created_at.iso8601,
+        updated_at: model.updated_at.iso8601,
+        file_url: nil, # TODO: Expose credit note document in API
+      }
+
+      payload = payload.merge(items) if include?(:items)
+
+      payload
+    end
+
+    private
+
+    def items
+      ::CollectionSerializer.new(
+        model.items.order(created_at: :asc),
+        ::V1::CreditNoteItemSerializer,
+        collection_name: 'items',
+      ).serialize
+    end
+  end
+end

app/serializers/v1/fee_serializer.rb

@@ -4,6 +4,7 @@ module V1
   class FeeSerializer < ModelSerializer
     def serialize
       {
+        lago_id: model.id,
         item: {
           type: model.fee_type,
           code: model.item_code,

config/routes.rb

@@ -24,6 +24,7 @@
       resources :add_ons, param: :code
       resources :billable_metrics, param: :code
       resources :coupons, param: :code
+      resources :credit_notes, only: %i[show index]
       resources :events, only: %i[create show]
       resources :applied_coupons, only: %i[create]
       resources :applied_add_ons, only: %i[create]

spec/controllers/api/v1/credit_notes_controller_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe Api::V1::CreditNotesController, type: :request do
+  let(:invoice) { create(:invoice) }
+  let(:organization) { invoice.organization }
+  let(:customer) { invoice.customer }
+  let(:credit_note) { create(:credit_note, invoice: invoice, customer: customer) }
+  let(:credit_note_items) { create_list(:credit_note_item, 2, credit_note: credit_note) }
+
+  describe 'GET /credit_notes/:id' do
+    before { credit_note_items }
+
+    it 'returns a credit note' do
+      get_with_token(organization, "/api/v1/credit_notes/#{credit_note.id}")
+
+      aggregate_failures do
+        expect(response).to have_http_status(:success)
+        expect(json[:credit_note][:lago_id]).to eq(credit_note.id)
+        expect(json[:credit_note][:sequential_id]).to eq(credit_note.sequential_id)
+        expect(json[:credit_note][:number]).to eq(credit_note.number)
+        expect(json[:credit_note][:lago_invoice_id]).to eq(invoice.id)
+        expect(json[:credit_note][:invoice_number]).to eq(invoice.number)
+        expect(json[:credit_note][:status]).to eq(credit_note.status)
+        expect(json[:credit_note][:reason]).to eq(credit_note.reason)
+        expect(json[:credit_note][:amount_cents]).to eq(credit_note.amount_cents)
+        expect(json[:credit_note][:amount_currency]).to eq(credit_note.amount_currency)
+        expect(json[:credit_note][:remaining_amount_cents]).to eq(credit_note.remaining_amount_cents)
+        expect(json[:credit_note][:remaining_amount_currency]).to eq(credit_note.remaining_amount_currency)
+        expect(json[:credit_note][:created_at]).to eq(credit_note.created_at.iso8601)
+        expect(json[:credit_note][:updated_at]).to eq(credit_note.updated_at.iso8601)
+
+        expect(json[:credit_note][:items].count).to eq(2)
+
+        json_item = json[:credit_note][:items].first
+        item = credit_note_items.first
+        expect(json_item[:lago_id]).to eq(item.id)
+        expect(json_item[:amount_cents]).to eq(item.amount_cents)
+        expect(json_item[:amount_currency]).to eq(item.amount_currency)
+        expect(json_item[:fee][:lago_id]).to eq(item.fee.id)
+        expect(json_item[:fee][:amount_cents]).to eq(item.fee.amount_cents)
+        expect(json_item[:fee][:amount_currency]).to eq(item.fee.amount_currency)
+        expect(json_item[:fee][:item][:type]).to eq(item.fee.fee_type)
+        expect(json_item[:fee][:item][:code]).to eq(item.fee.item_code)
+        expect(json_item[:fee][:item][:name]).to eq(item.fee.item_name)
+      end
+    end
+
+    context 'when credit note does not exists' do
+      it 'returns not found' do
+        get_with_token(organization, '/api/v1/credit_notes/foo')
+
+        expect(response).to have_http_status(:not_found)
+      end
+    end
+
+    context 'when credit note belongs to another organization' do
+      let(:wrong_credit_note) { create(:credit_note) }
+
+      it 'returns not found' do
+        get_with_token(organization, "/api/v1/credit_notes/#{wrong_credit_note.id}")
+      end
+    end
+  end
+
+  describe 'GET /credits_notes' do
+    let(:second_customer) { create(:customer, organization: organization) }
+    let(:second_invoice) { create(:invoice, customer: second_customer) }
+    let(:second_credit_note) { create(:credit_note, invoice: second_invoice, customer: second_invoice.customer) }
+
+    before do
+      credit_note
+      second_credit_note
+    end
+
+    it 'returns a list of credit_notes' do
+      get_with_token(organization, '/api/v1/credit_notes')
+
+      aggregate_failures do
+        expect(response).to have_http_status(:success)
+        expect(json[:credit_notes].count).to eq(2)
+        expect(json[:credit_notes].first[:lago_id]).to eq(second_credit_note.id)
+        expect(json[:credit_notes].last[:lago_id]).to eq(credit_note.id)
+      end
+    end
+
+    context 'with pagination' do
+      it 'returns the metadata' do
+        get_with_token(organization, '/api/v1/credit_notes?page=1&per_page=1')
+
+        aggregate_failures do
+          expect(response).to have_http_status(:success)
+          expect(json[:credit_notes].count).to eq(1)
+
+          expect(json[:meta][:current_page]).to eq(1)
+          expect(json[:meta][:next_page]).to eq(2)
+          expect(json[:meta][:prev_page]).to eq(nil)
+          expect(json[:meta][:total_pages]).to eq(2)
+          expect(json[:meta][:total_count]).to eq(2)
+        end
+      end
+    end
+
+    context 'with external_customer_id filter' do
+      it 'returns credit notes of the customer' do
+        get_with_token(organization, "/api/v1/credit_notes?external_customer_id=#{customer.external_id}")
+
+        aggregate_failures do
+          expect(response).to have_http_status(:success)
+
+          expect(json[:credit_notes].count).to eq(1)
+          expect(json[:credit_notes].first[:lago_id]).to eq(credit_note.id)
+        end
+      end
+    end
+  end
+end

spec/factories/billable_metric_factory.rb

@@ -5,7 +5,7 @@
     organization
     name { 'Some metric' }
     description { 'some description' }
-    code { Faker::Name.first_name }
+    code { Faker::Alphanumeric.alphanumeric(number: 10) }
     aggregation_type { 'count_agg' }
     properties { {} }
   end

spec/factories/credit_note_items.rb

@@ -4,5 +4,7 @@
   factory :credit_note_item do
     credit_note
     fee
+    amount_cents { 100 }
+    amount_currency { 'EUR' }
   end
 end

spec/factories/plan_factory.rb

@@ -4,7 +4,7 @@
   factory :plan do
     organization
     name { Faker::TvShows::SiliconValley.app }
-    code { Faker::Name.first_name }
+    code { Faker::Alphanumeric.alphanumeric(number: 10) }
     interval { 'monthly' }
     pay_in_advance { false }
     amount_cents { 100 }