Add admin_metadata to attributes for admins

Introduce the `admin_metadata` attribute to support dynamic metadata handling for admins.
It enables configuration of metadata via API preferences, and ensures that metadata fields
are properly permitted for admin users through new helper methods.

**Implementation:**
- Added `admin_metadata` to resources for admins.
- Integrated `metadata_permit_parameters` and `metadata_api_parameters preference` in API configuration.
- Implemented `permitted_<resource>_attributes` and `<method_name>_attributes` methods for dynamic metadata permissions.
- Added `extract_metadata` in `line_items_controller` to handle metadata fields.

Author: JustShah

api/app/controllers/spree/api/base_controller.rb

@@ -18,6 +18,9 @@ class BaseController < ActionController::Base
       class_attribute :admin_line_item_attributes
       self.admin_line_item_attributes = [:price, :variant_id, :sku]
 
+      class_attribute :admin_metadata_attributes
+      self.admin_metadata_attributes = [{ admin_metadata: {} }]
+
       attr_accessor :current_api_user
 
       before_action :load_user
@@ -35,15 +38,29 @@ class BaseController < ActionController::Base
 
       private
 
+      Spree::Api::Config.metadata_permit_parameters.each do |resource|
+        define_method("permitted_#{resource.to_s.underscore}_attributes") do
+          if can?(:admin, "Spree::#{resource}".constantize)
+            super() + admin_metadata_attributes
+          else
+            super()
+          end
+        end
+      end
+
       # users should be able to set price when importing orders via api
       def permitted_line_item_attributes
         if can?(:admin, Spree::LineItem)
-          super + admin_line_item_attributes
+          super + admin_line_item_attributes + admin_metadata_attributes
         else
           super
         end
       end
 
+      def permitted_user_attributes
+        can?(:admin, Spree.user_class) ? super + admin_metadata_attributes : super
+      end
+
       def load_user
         @current_api_user ||= Spree.user_class.find_by(spree_api_key: api_key.to_s)
       end

api/app/controllers/spree/api/line_items_controller.rb

@@ -15,8 +15,10 @@ def create
           @line_item = @order.contents.add(
             variant,
             params[:line_item][:quantity] || 1,
-            options: line_item_params[:options].to_h
+            options: line_item_params[:options].to_h,
+            **extract_metadata
           )
+
           respond_with(@line_item, status: 201, default_template: :show)
         rescue ActiveRecord::RecordInvalid => error
           invalid_resource!(error.record)
@@ -56,10 +58,21 @@ def line_items_attributes
         { line_items_attributes: {
             id: params[:id],
             quantity: params[:line_item][:quantity],
-            options: line_item_params[:options] || {}
+            options: line_item_params[:options] || {},
+            **extract_metadata
         } }
       end
 
+      def extract_metadata
+        metadata = { customer_metadata: line_item_params[:customer_metadata] }
+
+        if @current_user_roles&.include?("admin")
+          metadata[:admin_metadata] = line_item_params[:admin_metadata]
+        end
+
+        metadata
+      end
+
       def line_item_params
         params.require(:line_item).permit(permitted_line_item_attributes)
       end

api/app/helpers/spree/api/api_helpers.rb

@@ -43,6 +43,16 @@ module ApiHelpers
         end
       end
 
+      Spree::Api::Config.metadata_api_parameters.each do |method_name, resource|
+        define_method("#{method_name}_attributes") do
+          authorized_attributes(resource, "#{method_name}_attributes")
+        end
+      end
+
+      def authorized_attributes(resource, config_attribute)
+        can?(:admin, resource) ? Spree::Api::Config.public_send(config_attribute) + [:admin_metadata] : Spree::Api::Config.public_send(config_attribute)
+      end
+
       def required_fields_for(model)
         required_fields = model._validators.select do |_field, validations|
           validations.any? { |validation| validation.is_a?(ActiveModel::Validations::PresenceValidator) }

api/lib/spree/api_configuration.rb

@@ -41,6 +41,28 @@ class ApiConfiguration < Preferences::Configuration
 
     preference :line_item_attributes, :array, default: [:id, :quantity, :price, :variant_id, :customer_metadata]
 
+    # Spree::Api::Config.metadata_api_parameters contains the models
+    # to which the admin_metadata attribute is added
+    preference :metadata_api_parameters, :array, default: [
+      [:order, 'Spree::Order'],
+      [:customer_return, 'Spree::CustomerReturn'],
+      [:payment, 'Spree::Payment'],
+      [:return_authorization, 'Spree::ReturnAuthorization'],
+      [:shipment, 'Spree::Shipment'],
+      [:user, 'Spree.user_class'],
+      [:line_item, 'Spree::LineItem']
+    ]
+
+    # Spree::Api::Config.metadata_permit_parameters contains the models
+    # to which the admin_metadata attribute is permitted
+    preference :metadata_permit_parameters, :array, default: [
+      :Order,
+      :CustomerReturn,
+      :Payment,
+      :ReturnAuthorization,
+      :Shipment
+    ]
+
     preference :option_type_attributes, :array, default: [:id, :name, :presentation, :position]
 
     preference :payment_attributes, :array, default: [

api/spec/requests/spree/api/customer_returns_spec.rb

@@ -59,6 +59,14 @@ module Spree::Api
         expect(json_response).to have_attributes(attributes)
       end
 
+      it "can view admin_metadata" do
+        customer_return = FactoryBot.create(:customer_return)
+
+        get spree.api_order_customer_return_path(customer_return.order, customer_return.id)
+
+        expect(json_response).to have_key('admin_metadata')
+      end
+
       it "can get a list of customer returns" do
         FactoryBot.create(:customer_return, shipped_order: order)
         FactoryBot.create(:customer_return, shipped_order: order)
@@ -97,7 +105,7 @@ module Spree::Api
       it "can learn how to create a new customer return" do
         get spree.new_api_order_customer_return_path(order)
 
-        expect(json_response["attributes"]).to eq(["id", "number", "stock_location_id", "created_at", "updated_at"])
+        expect(json_response["attributes"]).to eq(["id", "number", "stock_location_id", "created_at", "updated_at", "customer_metadata", "admin_metadata"])
       end
 
       it "can update a customer return" do
@@ -112,6 +120,23 @@ module Spree::Api
         expect(json_response["stock_location_id"]).to eq final_stock_location.id
       end
 
+      it "can update a customer return admin_metadata" do
+        initial_stock_location = FactoryBot.create(:stock_location)
+        final_stock_location = FactoryBot.create(:stock_location)
+        customer_return = FactoryBot.create(:customer_return, stock_location: initial_stock_location)
+
+        put spree.api_order_customer_return_path(customer_return.order, customer_return.id),
+        params: {
+          order_id: customer_return.order.number,
+          customer_return: { stock_location_id: final_stock_location.id, admin_metadata: { 'order_number' => 'PN345678' } }
+        }
+
+        expect(response.status).to eq(200)
+        expect(json_response).to have_attributes(attributes)
+        expect(json_response["stock_location_id"]).to eq final_stock_location.id
+        expect(json_response["admin_metadata"]).to eq({ 'order_number' => 'PN345678' })
+      end
+
       context "when creating new return items" do
         it "can create a new customer return" do
           stock_location = FactoryBot.create(:stock_location)

api/spec/requests/spree/api/line_items_spec.rb

@@ -228,6 +228,34 @@ module Spree::Api
       end
     end
 
+    context "as an admin" do
+      sign_in_as_admin!
+
+      it "can see admin_metadata" do
+        post spree.api_order_line_items_path(order),
+        params: {
+          line_item: { variant_id: product.master.to_param, quantity: 1 },
+          order_token: order.guest_token
+        }
+
+        expect(response.status).to eq(201)
+        expect(json_response).to have_key('admin_metadata')
+      end
+
+      it "allows creating line item with customer metadata and admin metadata" do
+        post spree.api_order_line_items_path(order),
+        params: {
+          line_item: { variant_id: product.master.to_param,
+                       quantity: 1,
+                       customer_metadata: { "Company" => "Sample Company" },
+                       admin_metadata: { "discount" => "not_applicable" } }
+        }
+
+        expect(json_response['customer_metadata']).to eq({ "Company" => "Sample Company" })
+        expect(json_response['admin_metadata']).to eq({ "discount" => "not_applicable" })
+      end
+    end
+
     context "as just another user" do
       before do
         user = create(:user)

api/spec/requests/spree/api/orders_spec.rb

@@ -987,6 +987,32 @@ module Spree::Api
           expect(json_response['error']).to eq(I18n.t(:could_not_transition, scope: "spree.api", resource: 'order'))
           expect(response.status).to eq(422)
         end
+
+        it "can update a order admin_metadata" do
+          put spree.api_order_path(order), params: { order: { admin_metadata: { 'order_number' => 'PN345678' } } }
+
+          expect(response.status).to eq(200)
+
+          expect(json_response["admin_metadata"]).to eq({ 'order_number' => 'PN345678' })
+        end
+
+        it "can update customer metadata if the order is complete" do
+          order = create(:order)
+          order.completed_at = Time.current
+          order.state = 'complete'
+          order.save!
+
+          put spree.api_order_path(order), params: { order: { customer_metadata: { 'Note' => 'Do not ring the bell' }, admin_metadata: { 'order_number' => 'PN345678' } } }
+
+          expect(json_response['customer_metadata']).to eq({ 'Note' => 'Do not ring the bell' })
+          expect(json_response["admin_metadata"]).to eq({ 'order_number' => 'PN345678' })
+        end
+
+        it "can view admin_metadata" do
+          get spree.api_order_path(order)
+
+          expect(json_response).to have_key('admin_metadata')
+        end
       end
 
       context "can cancel an order" do

api/spec/requests/spree/api/payments_spec.rb

@@ -187,6 +187,26 @@ module Spree::Api
               expect(response.status).to eq(403)
               expect(json_response["error"]).to eq("This payment cannot be updated because it is completed.")
             end
+
+            it "can update a payment admin_metadata" do
+              payment.update(state: 'pending')
+
+              put spree.api_order_payment_path(order, payment),
+              params: {
+                payment: {
+                  amount: 2.01,
+                  admin_metadata: { 'order_number' => 'PN345678' }
+                }
+              }
+
+              expect(response.status).to eq(200)
+              expect(json_response["admin_metadata"]).to eq({ 'order_number' => 'PN345678' })
+            end
+
+            it "can view admin_metadata" do
+              get spree.api_order_payments_path(order)
+              expect(json_response["payments"].first).to have_key('admin_metadata')
+            end
           end
         end
 

api/spec/requests/spree/api/return_authorizations_spec.rb

@@ -121,7 +121,7 @@ module Spree::Api
 
       it "can learn how to create a new return authorization" do
         get spree.new_api_order_return_authorization_path(order)
-        expect(json_response["attributes"]).to eq(["id", "number", "state", "order_id", "memo", "created_at", "updated_at"])
+        expect(json_response["attributes"]).to eq(["id", "number", "state", "order_id", "memo", "created_at", "updated_at", "customer_metadata", "admin_metadata"])
         required_attributes = json_response["required_attributes"]
         expect(required_attributes).to include("order")
       end
@@ -151,6 +151,31 @@ module Spree::Api
         expect { return_authorization.reload }.to raise_error(ActiveRecord::RecordNotFound)
       end
 
+      it "can view admin_metadata" do
+        FactoryBot.create(:return_authorization, order:)
+
+        return_authorization = order.return_authorizations.first
+
+        get spree.api_order_return_authorization_path(order, return_authorization.id)
+
+        expect(response.status).to eq(200)
+        expect(json_response).to have_attributes(attributes)
+        expect(json_response).to have_key('admin_metadata')
+      end
+
+      it "can update a return authorization on the order and metadata" do
+        FactoryBot.create(:return_authorization, order:)
+
+        return_authorization = order.return_authorizations.first
+
+        put spree.api_order_return_authorization_path(order, return_authorization.id), params: { return_authorization: { memo: "ABC", admin_metadata: { 'return_type' => 'warranty claim' }, customer_metadata: { 'return_reason' => 'product not working' } } }
+
+        expect(response.status).to eq(200)
+        expect(json_response).to have_attributes(attributes)
+        expect(json_response["admin_metadata"]).to eq({ 'return_type' => 'warranty claim' })
+        expect(json_response["customer_metadata"]).to eq({ 'return_reason' => 'product not working' })
+      end
+
       it_behaves_like "a return authorization creator"
     end
 

api/spec/requests/spree/api/shipments_spec.rb

@@ -92,6 +92,23 @@ module Spree::Api
         expect(json_response['stock_location_name']).to eq(stock_location.name)
       end
 
+      it "can update a shipment and it's metadata" do
+        params = {
+          shipment: {
+            stock_location_id: stock_location.to_param,
+            admin_metadata: { 'delivery_type' => 'express' },
+            customer_metadata: { 'timing' => 'standard' }
+          }
+        }
+
+        put(spree.api_shipment_path(shipment), params:)
+
+        expect(response.status).to eq(200)
+        expect(json_response['stock_location_name']).to eq(stock_location.name)
+        expect(json_response["admin_metadata"]).to eq({ 'delivery_type' => 'express' })
+        expect(json_response["customer_metadata"]).to eq({ 'timing' => 'standard' })
+      end
+
       it "can make a shipment ready" do
         allow_any_instance_of(Spree::Order).to receive_messages(paid?: true, complete?: true)
         put spree.ready_api_shipment_path(shipment)