spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/spree/api/v3/admin/reporting_controller.rb

@@ -0,0 +1,95 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The semantic reporting surface (docs/plans/6.0-analytics-semantic-layer.md):
+        # one query endpoint compiled against the Spree.reporting registry, plus
+        # registry introspection for pickers and agent tool schemas.
+        class ReportingController < Admin::BaseController
+          include ReportingAuthorization
+
+          scoped_resource :reports
+
+          rescue_from Spree::Reporting::UnknownMember, Spree::Reporting::InvalidQuery, with: :render_invalid_query
+
+          QUERY_KEYS = %w[metrics dimensions filters metric_filters time_range compare sort limit currency].freeze
+
+          # POST /api/v3/admin/reporting/query
+          def query
+            reporting_query = Spree::Reporting::Query.new(store: current_store, params: query_params)
+            authorize_reporting_members!(reporting_query)
+            return if performed?
+
+            result = reporting_query.execute
+
+            render json: ReportingResultSerializer.new(
+              result,
+              store: current_store,
+              params: serializer_params
+            ).to_h
+          end
+
+          # GET /api/v3/admin/reporting/schema
+          #
+          # Filtered to what this caller may reference: pickers never offer,
+          # and agents never propose, a member that would be refused.
+          def schema
+            render json: Spree::Reporting::Schema.new(
+              store: current_store,
+              allowed: ->(member) { member_allowed?(member) }
+            ).to_h
+          end
+
+          private
+
+          def action_kind
+            'read'
+          end
+
+          # The contract owns shape validation (registry allowlist, loud
+          # rejection of unknown members) — nothing here is mass-assigned to a
+          # model, so strong-params filtering would only duplicate it.
+          def query_params
+            params.to_unsafe_h.slice(*QUERY_KEYS)
+          end
+
+          # Both credential types are authorized per referenced member:
+          # JWT admins via CanCanCan (`required_subjects`), secret keys via
+          # their scopes (`required_key_scopes` on top of the `read_reports`
+          # endpoint gate) — a key without `read_products` cannot query the
+          # product dimension any more than a limited staff role can.
+          def authorize_reporting_members!(reporting_query)
+            if current_api_key.present?
+              missing = reporting_query.required_key_scopes.reject { |scope| current_api_key.has_scope?(scope) }
+              return if missing.empty?
+
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied],
+                message: "API key lacks scope: #{missing.join(', ')}",
+                status: :forbidden,
+                details: { required_scopes: missing }
+              )
+            else
+              authorize!(:read, :reports)
+              forbidden = reporting_query.unreadable_subjects(current_ability).first
+              raise CanCan::AccessDenied.new(nil, :read, forbidden) if forbidden
+            end
+          end
+
+          # An unknown member carries what it was and what was valid instead.
+          # Passing those through as `details` lets a client correct the query
+          # without parsing the sentence — the same list the schema endpoint
+          # would have given it.
+          def render_invalid_query(error)
+            details = if error.is_a?(Spree::Reporting::UnknownMember)
+                        { kind: error.kind, name: error.name.to_s, valid: error.valid.map(&:to_s) }
+                      end
+
+            render_error(code: 'invalid_reporting_query', message: error.message,
+                         status: :unprocessable_content, details: details)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/resource_controller.rb

@@ -6,8 +6,17 @@ module Spree
         # inheritance branches (V3::BaseController vs V3::ResourceController);
         # any concern added here MUST also be added to Admin::BaseController.
         class ResourceController < Spree::Api::V3::ResourceController
+          include Spree::Api::V3::Admin::StoreContext
           include Spree::Api::V3::AdminAuthentication
           include Spree::Api::V3::ScopedAuthorization
+          # External-identity addressing for every admin resource whose model
+          # opts in via Spree::HasExternalReferences — the concern's guards
+          # no-op for everything else. Sitting here rather than per controller
+          # means a newly synced resource cannot ship the half-supported state
+          # (readable references, unaddressable member paths) by forgetting an
+          # include.
+          include Spree::Api::V3::Admin::Concerns::ExternalReferences
+          include Spree::Api::V3::Admin::ValidationDetails
 
           protected
 
@@ -15,19 +24,27 @@ module Spree
             authenticate_admin!
           end
 
-          # Render error from ServiceModule::Result, extracting ActiveModel::Errors
-          # from the ResultError wrapper to get proper validation_error responses.
-          def render_result_error(result)
-            error = result.error
-            errors = error.respond_to?(:value) ? error.value : error
+          # CanCanCan lives on the admin branch only. The shared base leaves
+          # these as no-ops because the Store API authorizes by ownership
+          # scoping; back-office callers are authorized per record and per
+          # collection by their role's catalog keys.
+          def scope
+            base_scope = super
+            return base_scope if @parent.present?
 
-            if errors.is_a?(ActiveModel::Errors)
-              render_validation_error(errors)
-            else
-              render_service_error(error)
-            end
+            base_scope.accessible_by(current_ability, ability_action_for_request)
+          end
+
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            authorize!(action, resource)
           end
 
+          def authorize_parent!(parent)
+            authorize!(parent_ability_action, parent)
+          end
+
+          # Render error from ServiceModule::Result, extracting ActiveModel::Errors
+          # from the ResultError wrapper to get proper validation_error responses.
           def decode_ids(ids, klass)
             Array(ids).map do |id|
               Spree::PrefixedId.prefixed_id?(id) ? klass.find_by_param!(id).id : id

data/app/controllers/spree/api/v3/admin/return_reasons_controller.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ReturnReasonsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::ReturnReason
+          end
+
+          def serializer_class
+            Spree.api.admin_return_reason_serializer
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :name, :active)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/returns_controller.rb

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cross-order listing of returns — "what is awaiting receipt across
+        # the whole store". Read-only by route: opening a return needs an
+        # order, so creation and the status transitions stay on the nested
+        # Orders::ReturnsController.
+        class ReturnsController < ResourceController
+          # Post-sale records are order data: a key that may read orders may
+          # read these, and nothing here writes.
+          scoped_resource :orders
+
+          protected
+
+          def model_class
+            Spree::Return
+          end
+
+          def serializer_class
+            Spree.api.admin_return_serializer
+          end
+
+          def collection_includes
+            [:order, :reason, :stock_location, { return_line_items: :variant }]
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/roles_controller.rb

@@ -2,12 +2,32 @@ module Spree
   module Api
     module V3
       module Admin
-        # Read-only list of roles available for staff role pickers (invite +
-        # edit forms). Roles are global, not per-store; CRUD is handled
-        # outside the SPA today and may grow into a richer permissions UI
-        # later. The controller ignores `current_store` for that reason.
+        # Staff roles and their catalog permissions (docs/plans/6.0-admin-rbac.md).
+        # A role belongs to what it governs, so this surface reads and writes
+        # the current store's own roles; one owned by another resource — a
+        # marketplace seller's — belongs to that panel. Protection of the admin
+        # role and host-locked rows lives on the model (`mutable` guards,
+        # `can_be_deleted?`).
         class RolesController < ResourceController
-          scoped_resource :settings
+          include Spree::Api::V3::Admin::RoleGrantGuard
+
+          scoped_resource :staff
+
+          # POST /api/v3/admin/roles
+          # A caller may only grant permissions they effectively hold — the
+          # same anti-amplification rule as role grants and API-key minting.
+          def create
+            return if reject_unauthorized_permission_grant!(requested_permissions)
+
+            super
+          end
+
+          # PATCH /api/v3/admin/roles/:id
+          def update
+            return if params.key?(:permissions) && reject_unauthorized_permission_grant!(requested_permissions)
+
+            super
+          end
 
           protected
 
@@ -19,8 +39,32 @@ module Spree
             Spree.api.admin_role_serializer
           end
 
+          # The store's own roles. A role belonging to another resource — a
+          # marketplace seller's — is managed from that panel and never appears
+          # in the staff role picker.
           def scope
-            Spree::Role.accessible_by(current_ability, :show)
+            current_store.roles.accessible_by(current_ability, :show)
+          end
+
+          def collection_includes
+            [:role_users]
+          end
+
+          # Roles created here belong to the store being administered. The base
+          # builder stamps `store`, which a role does not have — its owner is
+          # polymorphic — so it would leave the resource unset.
+          def build_resource
+            current_store.roles.build(permitted_params)
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :name, :description, permissions: [])
+          end
+
+          private
+
+          def requested_permissions
+            Array(params[:permissions]).map(&:to_s).reject(&:blank?)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/seller_payouts_controller.rb

@@ -0,0 +1,83 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Settlements to sellers — what has been sent, and what is still owed.
+        #
+        # A payout is created by the sweep on the seller's own schedule rather
+        # than by a caller, so there is no create or update here. The one thing
+        # an operator does to a payout is say it landed, which is what the
+        # built-in provider expects: it records the settlement and waits to be
+        # told the bank transfer went out.
+        class SellerPayoutsController < ResourceController
+          scoped_resource :payouts
+
+          # PATCH /api/v3/admin/seller_payouts/:id/complete
+          #
+          # What the built-in provider waits for: the operator saying the bank
+          # transfer went out, with the reference it went out under.
+          #
+          # Authorized as an update, like every other custom member action —
+          # naming the action itself would only pass while the ability grants
+          # `manage`, and a host narrowing that would get a 403 the scope gate
+          # had already allowed.
+          def complete
+            @resource = find_resource
+            authorize! :update, @resource
+
+            result = Spree.seller_payout_complete_workflow.call(
+              seller_payout: @resource,
+              reference: params[:reference].to_s.presence
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value)
+            else
+              render_result_error(result)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::SellerPayout
+          end
+
+          def serializer_class
+            Spree.api.admin_seller_payout_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          # Deliberately without `transfers`: the serializer wants their number,
+          # not the rows, and a monthly settlement can hold hundreds.
+          def collection_includes
+            [:seller]
+          end
+
+          # One grouped count for the page, handed to the serializer — asking
+          # each row for its own would be a query per settlement, and a
+          # counter column cannot work here because the sweep claims transfers
+          # with `update_all`, which no callback sees.
+          #
+          # Only for the listing. Every action shares this method, and building
+          # the count needs `collection` — so a member action would run a whole
+          # paginated index query to serialize its one record, then read that
+          # record's count out of a page it may not even be on. The serializer
+          # asks a single payout for its own count, which is one query.
+          def serializer_params
+            return super unless action_name == 'index'
+
+            super.merge(transfer_counts: transfer_counts)
+          end
+
+          def transfer_counts
+            @transfer_counts ||= Spree::SellerTransfer.where(payout_id: collection.map(&:id)).group(:payout_id).count
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/seller_requirement_submissions_controller.rb

@@ -0,0 +1,139 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The operator's review queue: what sellers have submitted about the
+        # marketplace's requirements, and the decisions on them.
+        #
+        # Each decision is its own member action because each is a workflow
+        # carrying its own arguments — a rejection carries the reason the
+        # seller needs in order to fix it — and because a status moved by
+        # PATCH would skip the mail and the extension hooks.
+        class SellerRequirementSubmissionsController < ResourceController
+          scoped_resource :sellers
+
+          before_action :set_resource, only: [:show, :accept, :reject, :download]
+
+          # POST /api/v3/admin/sellers/:seller_id/requirement_submissions
+          #
+          # The operator excusing one seller from something the marketplace
+          # asks of everyone. Creating anything else here would be the
+          # operator submitting on the seller's behalf, which is what the
+          # seller's own branch is for.
+          def create
+            authorize! :create, Spree::SellerRequirementSubmission
+
+            result = Spree.seller_requirement_submission_waive_workflow.call(
+              seller: seller,
+              requirement: requirement_from_params,
+              reviewed_by: try_spree_current_user,
+              review_note: params[:review_note]
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value), status: :created
+            else
+              render_result_error(result)
+            end
+          end
+
+          # PATCH /api/v3/admin/sellers/:seller_id/requirement_submissions/:id/accept
+          def accept
+            run_workflow(Spree.seller_requirement_submission_accept_workflow)
+          end
+
+          # PATCH /api/v3/admin/sellers/:seller_id/requirement_submissions/:id/reject
+          def reject
+            run_workflow(Spree.seller_requirement_submission_reject_workflow)
+          end
+
+          # GET /api/v3/admin/sellers/:seller_id/requirement_submissions/:id/download
+          #
+          # Served through the API rather than as a storage link: these are
+          # business registrations and identity documents, so each read is
+          # authorized instead of being open to anyone holding a URL.
+          def download
+            unless @resource.file.attached?
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Submission has no attached file',
+                status: :unprocessable_content
+              )
+            end
+
+            send_data(
+              @resource.file.download,
+              filename: @resource.file.filename.to_s,
+              type: @resource.file.content_type,
+              disposition: 'attachment'
+            )
+          end
+
+          protected
+
+          def model_class
+            Spree::SellerRequirementSubmission
+          end
+
+          def serializer_class
+            Spree.api.admin_seller_requirement_submission_serializer
+          end
+
+          # The parent is set and authorized by the base controller, and the
+          # scope hangs off it — so a submission belonging to another
+          # marketplace is a 404 rather than a document.
+          def parent_association
+            :requirement_submissions
+          end
+
+          # The serializer reads each row's file and its seller, so both are
+          # loaded with the page rather than per row.
+          def collection_includes
+            [:requirement, :reviewed_by, :seller, { file_attachment: :blob }]
+          end
+
+          def read_actions
+            super + %w[download]
+          end
+
+          # Scope-fetched through the store, then filtered by what this role may
+          # do with it: reading a seller is not licence to decide its
+          # submissions, which `authorize_parent!` enforces per action.
+          def set_parent
+            @parent = current_store.sellers.
+                      accessible_by(current_ability, parent_ability_action).
+                      find_by_prefix_id!(params[:seller_id])
+            authorize_parent!(@parent)
+          end
+
+          private
+
+          def seller
+            @parent
+          end
+
+          # Through the store's own requirements: an id from elsewhere is a
+          # 404 here rather than a waiver written against another
+          # marketplace's checklist.
+          def requirement_from_params
+            current_store.seller_requirements.find_by_prefix_id!(params[:requirement_id])
+          end
+
+          def run_workflow(workflow)
+            result = workflow.call(
+              submission: @resource,
+              reviewed_by: try_spree_current_user,
+              review_note: params[:review_note]
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value)
+            else
+              render_result_error(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/seller_requirements_controller.rb

@@ -0,0 +1,115 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What this marketplace asks of a seller before it will let them
+        # trade (docs/plans/6.0-seller-onboarding-requirements.md).
+        #
+        # Under `write_sellers` rather than `settings`: who decides admission
+        # is who admits, and a key that can approve sellers is the same key
+        # that should be able to change what approval requires.
+        class SellerRequirementsController < ResourceController
+          include Spree::Api::V3::Admin::SubclassedResource
+
+          scoped_resource :sellers
+
+          subclassed_via -> { Spree.seller_requirements },
+                         unknown_type_error: 'unknown_seller_requirement_type'
+
+          # GET /api/v3/admin/seller_requirements/types
+          #
+          # The kinds an operator can add, with the shape of each one's
+          # configuration form. A marketplace's own kinds appear here the
+          # moment they are registered, which is what keeps the picker from
+          # being a hardcoded list in the dashboard.
+          def types
+            # `:read`, matching its place in `read_actions`: this lists the
+            # kinds a marketplace has registered and nothing about any store,
+            # so a staffer who can see the checklist can see what it is made
+            # of. Asking for `:create` here 403s exactly those people.
+            authorize! :read, model_class
+
+            data = Spree.seller_requirements.map do |klass|
+              {
+                type: klass.api_type,
+                name: klass.human_name,
+                description: klass.human_description,
+                allow_multiple: klass.allow_multiple?,
+                accepts_submissions: klass.accepts_submissions?,
+                reviewed_by_operator: klass.reviewed_by_operator?,
+                # Whether the store already has one, and whether it may add
+                # another — the uniqueness rule is the model's, so the picker
+                # reads the answer rather than reimplementing it.
+                configured: configured_types.include?(klass.to_s),
+                addable: klass.allow_multiple? || configured_types.exclude?(klass.to_s),
+                # What a seller may upload, for kinds that collect a file.
+                # Told to the operator, never asked of them — the answer is
+                # the same for every marketplace.
+                accepted_content_types: klass.accepted_content_types,
+                # Config a kind takes beyond its preferences — a reference
+                # list gets its own picker, not a text box.
+                association_fields: association_fields_for(klass),
+                preference_schema: klass.serialized_preference_schema
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          protected
+
+          def model_class
+            Spree::SellerRequirement
+          end
+
+          def serializer_class
+            Spree.api.admin_seller_requirement_serializer
+          end
+
+          def scope
+            super.ordered
+          end
+
+          # `type` is stripped before assignment by the subclassed-resource
+          # flow, so a saved row's kind can never change — which matters
+          # because its submissions answered the old one.
+          def permitted_params
+            params.permit(:type, :name, :description, :position, :active, :required,
+                          preferences: {}, metadata: {})
+          end
+
+          # `types` is read-only discovery — maps to the read scope.
+          def read_actions
+            super + %w[types]
+          end
+
+          private
+
+          # `additional_permitted_attributes` entries are either bare symbols
+          # or `{ custom_field_definition_ids: [] }` hashes; both reduce to
+          # field names an editor can render a picker for.
+          def association_fields_for(klass)
+            return [] unless klass.respond_to?(:additional_permitted_attributes)
+
+            klass.additional_permitted_attributes.flat_map do |attribute|
+              attribute.is_a?(Hash) ? attribute.keys : attribute
+            end.map(&:to_s)
+          end
+
+          def build_subclassed_resource(klass, attrs)
+            current_store.seller_requirements.build(attrs.merge(type: klass.sti_name))
+          end
+
+          # `pluck` queries whether or not the association is already loaded,
+          # so a warm `current_store` cannot leave this answering with a kind
+          # the store no longer has. `reorder(nil)` because the association
+          # orders by position, and PostgreSQL refuses SELECT DISTINCT with an
+          # ORDER BY on a column it does not select.
+          def configured_types
+            @configured_types ||= current_store.seller_requirements.reorder(nil).distinct.pluck(:type)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/seller_transfers_controller.rb

@@ -0,0 +1,36 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What each seller has earned, order by order.
+        #
+        # Read-only, enforced by the routes: a transfer records money that
+        # moved. Correcting one is a reversal — another row, written by the
+        # refund that caused it — rather than an edit.
+        class SellerTransfersController < ResourceController
+          scoped_resource :payouts
+
+          protected
+
+          def model_class
+            Spree::SellerTransfer
+          end
+
+          def serializer_class
+            Spree.api.admin_seller_transfer_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          # Every association the serializer reads, so a page of rows costs a
+          # fixed number of queries rather than one per row.
+          def collection_includes
+            [:seller, :order, :payout, :reversed_from, :refund]
+          end
+        end
+      end
+    end
+  end
+end