feat(metadata): Services, GraphQL and API layers (#4663)

## Roadmap Task

- [SPEC: Metadata on credit
notes](https://www.notion.so/getlago/Spec-Metadata-on-credit-notes-2afef63110d2805cbbfceb3dfe754940)
- [BE: Metadata on credit
notes](https://www.notion.so/getlago/BE-Metadata-on-credit-notes-2b0ef63110d280d49217d215b566d688)
- [Canny
request](https://getlago.canny.io/feature-requests/p/add-metadata-to-more-objects)

  ## Context

This PR adds Services, GraphQL and REST API support for credit note
metadata. These are parts 2-4 of the feature

  ## Description

  ### Read operations

  - **GET /v1/credit_notes/:id** — returns metadata in the response
- **GET /v1/credit_notes** — includes metadata with eager loading (also
fixes an existing N+1 query)

  ### Write operations via credit note endpoints

  - **POST /v1/credit_notes** — accepts a `metadata` hash on creation
  - **PUT /v1/credit_notes/:id** — supports metadata merge and replace

  ### Dedicated metadata endpoints

  | Method | Endpoint | Description |
  |--------|----------|-------------|
  | POST | `/v1/credit_notes/:id/metadata` | Replaces all metadata |
| PATCH | `/v1/credit_notes/:id/metadata` | Merges new keys into
existing metadata |
  | DELETE | `/v1/credit_notes/:id/metadata` | Removes all metadata |
| DELETE | `/v1/credit_notes/:id/metadata/:key` | Removes a single key |

---------

Co-authored-by: Julien Bourdeau <julien@julienbourdeau.com>

Author: nepalez

app/controllers/api/v1/credit_notes/base_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module CreditNotes
+      class BaseController < Api::BaseController
+        before_action :find_credit_note
+
+        private
+
+        attr_reader :credit_note
+
+        def find_credit_note
+          @credit_note = current_organization.credit_notes.finalized.find_by!(id: params[:credit_note_id])
+        rescue ActiveRecord::RecordNotFound
+          not_found_error(resource: "credit_note")
+        end
+
+        def resource_name
+          "credit_note"
+        end
+      end
+    end
+  end
+end

app/controllers/api/v1/credit_notes/metadata_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module CreditNotes
+      class MetadataController < BaseController
+        def create
+          result = ::CreditNotes::UpdateService.call(credit_note:, metadata:)
+
+          if result.success?
+            render_metadata
+          else
+            render_error_response(result)
+          end
+        end
+
+        def update
+          result = ::CreditNotes::UpdateService.call(credit_note:, partial_metadata: true, metadata:)
+
+          if result.success?
+            render_metadata
+          else
+            render_error_response(result)
+          end
+        end
+
+        def destroy
+          result = ::CreditNotes::UpdateService.call(credit_note:, metadata: nil)
+
+          if result.success?
+            render_metadata
+          else
+            render_error_response(result)
+          end
+        end
+
+        def destroy_key
+          return not_found_error(resource: "metadata") unless credit_note.metadata
+
+          result = Metadata::DeleteItemKeyService.call(item: credit_note.metadata, key: params[:key])
+
+          if result.success?
+            render_metadata
+          else
+            render_error_response(result)
+          end
+        end
+
+        private
+
+        def metadata
+          params.fetch(:metadata, {}).permit!.to_h
+        end
+
+        def render_metadata
+          render(json: {metadata: credit_note.reload.metadata&.value})
+        end
+      end
+    end
+  end
+end

app/controllers/api/v1/credit_notes_controller.rb

@@ -5,7 +5,7 @@ module V1
     class CreditNotesController < Api::BaseController
       include CreditNoteIndex
       def create
-        result = CreditNotes::CreateService.call(
+        result = ::CreditNotes::CreateService.call(
           invoice: current_organization.invoices.visible.find_by(id: input_params[:invoice_id]),
           **input_params
         )
@@ -40,12 +40,12 @@ def update
         credit_note = current_organization.credit_notes.find_by(id: params[:id])
         return not_found_error(resource: "credit_note") unless credit_note
 
-        result = CreditNotes::UpdateService.new(credit_note:, **update_params).call
+        result = ::CreditNotes::UpdateService.new(credit_note:, partial_metadata: true, **update_params).call
 
         if result.success?
           render(
             json: ::V1::CreditNoteSerializer.new(
-              credit_note,
+              result.credit_note,
               root_name: "credit_note",
               includes: %i[items applied_taxes]
             )
@@ -68,7 +68,7 @@ def download_pdf
           )
         end
 
-        CreditNotes::GeneratePdfJob.perform_later(credit_note)
+        ::CreditNotes::GeneratePdfJob.perform_later(credit_note)
 
         head(:ok)
       end
@@ -86,7 +86,7 @@ def download_xml
           )
         end
 
-        CreditNotes::GenerateXmlJob.perform_later(credit_note)
+        ::CreditNotes::GenerateXmlJob.perform_later(credit_note)
 
         head(:ok)
       end
@@ -95,7 +95,7 @@ def void
         credit_note = current_organization.credit_notes.find_by(id: params[:id])
         return not_found_error(resource: "credit_note") unless credit_note
 
-        result = CreditNotes::VoidService.new(credit_note:).call
+        result = ::CreditNotes::VoidService.new(credit_note:).call
 
         if result.success?
           render(
@@ -118,7 +118,7 @@ def index
       end
 
       def estimate
-        result = CreditNotes::EstimateService.call(
+        result = ::CreditNotes::EstimateService.call(
           invoice: current_organization.invoices.visible.find_by(id: estimate_params[:invoice_id]),
           items: estimate_params[:items]
         )
@@ -145,6 +145,7 @@ def input_params
             :description,
             :credit_amount_cents,
             :refund_amount_cents,
+            metadata: {},
             items: [
               :fee_id,
               :amount_cents
@@ -153,7 +154,7 @@ def input_params
       end
 
       def update_params
-        params.require(:credit_note).permit(:refund_status)
+        params.require(:credit_note).permit(:refund_status, metadata: {})
       end
 
       def estimate_params

app/controllers/concerns/credit_note_index.rb

@@ -34,7 +34,15 @@ def credit_note_index(external_customer_id:)
     if result.success?
       render(
         json: ::CollectionSerializer.new(
-          result.credit_notes.includes(:items, :applied_taxes, :invoice),
+          result.credit_notes.includes(
+            :items,
+            :applied_taxes,
+            :file_attachment,
+            :xml_file_attachment,
+            :error_details,
+            :metadata,
+            invoice: :billing_entity
+          ),
           ::V1::CreditNoteSerializer,
           collection_name: "credit_notes",
           meta: pagination_metadata(result.credit_notes),

app/graphql/mutations/credit_notes/create.rb

@@ -19,6 +19,7 @@ class Create < BaseMutation
       argument :refund_amount_cents, GraphQL::Types::BigInt, required: false
 
       argument :items, [Types::CreditNoteItems::Input], required: true
+      argument :metadata, [Types::Metadata::Input], required: false, **Types::Metadata::Input::ARGUMENT_OPTIONS
 
       type Types::CreditNotes::Object
 

app/graphql/mutations/credit_notes/update.rb

@@ -10,15 +10,15 @@ class Update < BaseMutation
       graphql_name "UpdateCreditNote"
       description "Updates an existing Credit Note"
 
-      argument :id, ID, required: true
-      argument :refund_status, Types::CreditNotes::RefundStatusTypeEnum, required: true
+      input_object_class Types::CreditNotes::UpdateCreditNoteInput
 
       type Types::CreditNotes::Object
 
       def resolve(**args)
         result = ::CreditNotes::UpdateService.new(
           credit_note: context[:current_user].credit_notes.find_by(id: args[:id]),
-          refund_status: args[:refund_status]
+          refund_status: args[:refund_status],
+          metadata: args[:metadata]
         ).call
 
         result.success? ? result.credit_note : result_error(result)

app/graphql/resolvers/credit_notes_resolver.rb

@@ -30,32 +30,21 @@ class CreditNotesResolver < Resolvers::BaseResolver
 
     type Types::CreditNotes::Object.collection_type, null: false
 
-    def resolve(args)
-      result = CreditNotesQuery.call(
+    FILTER_KEYS = %i[
+      amount_from amount_to billing_entity_ids credit_status currency customer_external_id
+      customer_id invoice_number issuing_date_from issuing_date_to reason refund_status self_billed
+    ].freeze
+
+    def resolve(**args)
+      includes = [:customer, :items]
+
+      CreditNotesQuery.call(
         organization: current_organization,
         search_term: args[:search_term],
-        filters: {
-          amount_from: args[:amount_from],
-          amount_to: args[:amount_to],
-          billing_entity_ids: args[:billing_entity_ids],
-          credit_status: args[:credit_status],
-          currency: args[:currency],
-          customer_external_id: args[:customer_external_id],
-          customer_id: args[:customer_id],
-          invoice_number: args[:invoice_number],
-          issuing_date_from: args[:issuing_date_from],
-          issuing_date_to: args[:issuing_date_to],
-          reason: args[:reason],
-          refund_status: args[:refund_status],
-          self_billed: args[:self_billed]
-        },
-        pagination: {
-          page: args[:page],
-          limit: args[:limit]
-        }
-      )
-
-      result.credit_notes
+        includes:,
+        filters: args.slice(*FILTER_KEYS),
+        pagination: args.slice(:page, :limit)
+      ).credit_notes
     end
   end
 end

app/graphql/types/credit_notes/object.rb

@@ -51,9 +51,14 @@ class Object < Types::BaseObject
       field :error_details, [Types::ErrorDetails::Object], null: true
       field :external_integration_id, String, null: true
       field :integration_syncable, GraphQL::Types::Boolean, null: false
+      field :metadata, [Types::Metadata::Object], null: true
       field :tax_provider_id, String, null: true
       field :tax_provider_syncable, GraphQL::Types::Boolean, null: false
 
+      def metadata
+        object.metadata&.value&.map { |key, value| {key:, value:} }
+      end
+
       def applied_taxes
         object.applied_taxes.order(tax_rate: :desc)
       end

app/graphql/types/credit_notes/update_credit_note_input.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Types
+  module CreditNotes
+    class UpdateCreditNoteInput < BaseInputObject
+      description "Update Credit Note input arguments"
+
+      argument :id, ID, required: true
+      argument :metadata, [Types::Metadata::Input], required: false, **Types::Metadata::Input::ARGUMENT_OPTIONS
+      argument :refund_status, Types::CreditNotes::RefundStatusTypeEnum, required: false
+    end
+  end
+end

app/graphql/types/metadata/input.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Types
+  module Metadata
+    class Input < Types::BaseInputObject
+      graphql_name "MetadataInput"
+      description "Input for metadata key-value pair"
+
+      argument :key, String, required: true
+      argument :value, String, required: :nullable
+
+      ARGUMENT_OPTIONS = {
+        prepare: ->(value, _ctx) { value&.reduce({}) { |h, item| h.merge(item[:key] => item[:value]) } },
+        validates: {::Validators::UniqueByFieldValidator => {field_name: :key}}
+      }.freeze
+    end
+  end
+end