spree_api 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What the marketplace actually earned, sale by sale.
+        #
+        # Read-only, enforced by the routes: a commission line records
+        # something that already happened, frozen when the order was placed.
+        # Correcting one is not an edit but a reversal, which arrives with
+        # refunds in the next phase.
+        class CommissionLinesController < ResourceController
+          scoped_resource :commissions
+
+          protected
+
+          def model_class
+            Spree::CommissionLine
+          end
+
+          def serializer_class
+            Spree.api.admin_commission_line_serializer
+          end
+
+          # Reached through the store's own orders: the lines carry no store of
+          # their own, and the order is what ties them to one.
+          def scope
+            super.where(order_id: current_store.orders.select(:id))
+          end
+
+          # Every association the serializer reads, so a page of lines costs a
+          # fixed number of queries rather than one per row.
+          def collection_includes
+            [:seller, :commission_rate, :order, :line_item, :fulfillment]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # What the marketplace charges its sellers, as the operator configures it.
+        #
+        # Targeting rides the regular payload as `rules: [...]` rather than
+        # living at its own endpoint, so the whole editor saves in one
+        # round-trip — the same shape price lists use.
+        #
+        # Operator-only: `read_commissions`/`write_commissions` is closed to the
+        # seller audience, because a seller must never see, let alone set, what
+        # anyone is charged.
+        class CommissionRatesController < ResourceController
+          scoped_resource :commissions
+
+          # GET /api/v3/admin/commission_rates/rule_types
+          #
+          # Every registered rule kind with its configuration schema, so a
+          # client builds its editor from what the marketplace actually has
+          # rather than a list hardcoded to match core's.
+          def rule_types
+            authorize! :create, Spree::CommissionRule
+
+            data = Spree.commission_rules.map do |klass|
+              {
+                type: klass.api_type,
+                name: klass.human_name,
+                description: klass.description,
+                preference_schema: klass.serialized_preference_schema,
+                # Config a rule takes beyond its preferences — a catalog-scale
+                # reference list lives in its own table, not the blob, and an
+                # editor has to know to render a picker for it.
+                association_fields: association_fields_for(klass)
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          # A rule kind nobody registered is refused rather than skipped.
+          # `assign_typed_association` drops a row it cannot resolve, which
+          # would leave the rate with fewer rules than the client sent — and
+          # fewer rules means a rate that charges *more* sales, so a typo would
+          # silently widen what a marketplace bills.
+          def create
+            return if reject_unregistered_rules
+
+            super
+          end
+
+          def update
+            return if reject_unregistered_rules
+
+            super
+          end
+
+          protected
+
+          def model_class
+            Spree::CommissionRate
+          end
+
+          def serializer_class
+            Spree.api.admin_commission_rate_serializer
+          end
+
+          def scope
+            super.ordered
+          end
+
+          def collection_includes
+            [:commission_rules, :commission_rate_values]
+          end
+
+          # `rule_types` is read-only discovery — maps to the read scope and
+          # the :show ability rather than counting as a write.
+          def read_actions
+            super + %w[rule_types]
+          end
+
+          def permitted_params
+            attributes = normalize_params(
+              params.permit(
+                :name, :code, :enabled, :position, :kind, :value,
+                :tax_inclusive, :include_shipping, :commission_tax_rate,
+                metadata: {},
+                amounts: {},
+                # Nested one level deeper than +amounts+ — currency => floor and
+                # cap — so the whole subtree is permitted rather than its keys,
+                # which are currency codes and not knowable here.
+                bounds: {},
+                rules: [:id, :type, { preferences: {} }, *rule_association_attributes]
+              )
+            )
+
+            attributes[:rules] = resolved_rule_rows(attributes[:rules]) if attributes.key?(:rules)
+            attributes
+          end
+
+          private
+
+          # Resolves a rule's product list against this store before it reaches
+          # the model. Two things have to happen here and nowhere else: the ids
+          # arrive prefixed (only `preferences` are decoded on the way through
+          # TypedAssociations), and a product the caller cannot reach must not
+          # become part of a rule — a rate could otherwise be narrowed to
+          # another marketplace's catalog, and the serializer would read those
+          # products' ids straight back.
+          #
+          # Unreachable ids are dropped rather than refused, matching how
+          # delivery-method rules and price-list membership handle the same
+          # case: failing the whole save over one stale id would leave a
+          # merchant unable to clear it.
+          def resolved_rule_rows(rules)
+            Array(rules).map do |row|
+              row = row.to_h.with_indifferent_access
+              next row if row[:product_ids].blank?
+
+              row.merge(product_ids: accessible_product_ids(row[:product_ids]))
+            end
+          end
+
+          def accessible_product_ids(ids)
+            current_store.products.
+              accessible_by(current_ability, :show).
+              where(id: decode_prefixed_ids(ids)).
+              pluck(:id)
+          end
+
+          def reject_unregistered_rules
+            return false unless params.key?(:rules)
+
+            unknown = Array(params[:rules]).map { |rule| rule[:type].presence }.compact.reject do |type|
+              Spree.commission_rules.any? { |klass| klass.api_type == type }
+            end
+            return false if unknown.empty?
+
+            errors = ActiveModel::Errors.new(Spree::CommissionRate.new)
+            unknown.each do |type|
+              errors.add(:rules, :invalid_commission_rule_type, type: type,
+                         message: Spree.t('errors.messages.invalid_commission_rule_type', type: type))
+            end
+            render_validation_error(errors)
+
+            true
+          end
+
+          # Association-backed config every registered rule kind accepts, so
+          # the permit list stays generic. A rule naming catalog-scale records
+          # keeps them in its own table rather than its preferences.
+          def rule_association_attributes
+            Spree.commission_rules.flat_map do |klass|
+              klass.additional_permitted_attributes
+            end.uniq
+          end
+
+          def association_fields_for(klass)
+            case klass.api_type
+            when 'seller_rule' then ['seller_ids']
+            when 'category_rule' then ['category_ids']
+            else
+              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
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/addresses_controller.rb

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # A node's address book — an entry is an ordinary address the node
+          # owns, so the whole of it is reached through the node.
+          class AddressesController < BaseController
+            include Spree::Api::V3::CompanyAddressWrites
+
+            before_action :authorize_parent_access!
+
+            # POST /api/v3/admin/companies/:company_id/addresses
+            def create
+              result = Spree.address_create_service.call(
+                address_params: permitted_params,
+                owner: @parent,
+                **default_flags
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value), status: :created
+              else
+                render_errors(result.value.errors)
+              end
+            end
+
+            # PATCH /api/v3/admin/companies/:company_id/addresses/:id
+            def update
+              result = Spree.address_update_service.call(
+                address: @resource,
+                address_params: permitted_params,
+                **default_flags
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_errors(result.value.errors)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Address
+            end
+
+            def serializer_class
+              Spree.api.admin_address_serializer
+            end
+
+            def scope
+              @parent.addresses
+            end
+
+            def parent_association
+              :addresses
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/base_controller.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # Anything nested under a company. The parent is resolved through the
+          # store, so a company belonging to another tenant is a 404 rather than
+          # a readable record.
+          class BaseController < ResourceController
+            scoped_resource :customers
+
+            protected
+
+            def set_parent
+              @parent = current_store.companies.
+                        accessible_by(current_ability, parent_ability_action).
+                        find_by_prefix_id!(params[:company_id])
+              @company = @parent
+            end
+
+            def authorize_parent_access!
+              authorize_parent!(@parent)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/invitations_controller.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # The pending invitations into one node. Revocation is addressed
+          # directly by invitation id (CompanyInvitationsController).
+          class InvitationsController < BaseController
+            before_action :authorize_parent_access!
+
+            # DELETE /api/v3/admin/companies/:company_id/invitations/:id
+            #
+            # Revokes rather than erases: a spent token keeps refusing.
+            def destroy
+              if @resource.revoke!
+                head :no_content
+              else
+                render_error(
+                  code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                  message: Spree.t('company_invitations.not_pending'),
+                  status: :unprocessable_content
+                )
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::CompanyInvitation
+            end
+
+            def serializer_class
+              Spree.api.admin_company_invitation_serializer
+            end
+
+            # Pending only, and narrowed before pagination: a page of spent
+            # invitations would otherwise push live ones out of the first
+            # page and make the row count describe the wrong set. Spent and
+            # revoked rows are history, not a work list.
+            # The listing shows live invitations only, so spent rows cannot
+            # push pending ones off the first page. Addressing one by id still
+            # finds it, so revoking an already-spent invitation answers "not
+            # pending" rather than "no such invitation".
+            def scope
+              action_name == 'index' ? @parent.invitations.pending : @parent.invitations
+            end
+
+            def parent_association
+              :invitations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/memberships_controller.rb

@@ -0,0 +1,66 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # The people with standing over one node. Creation takes an email
+          # and does the right thing: a membership for an existing customer,
+          # an invitation otherwise — the same convergent behavior as the
+          # storefront endpoint.
+          class MembershipsController < BaseController
+            # Overriding `scope` bypasses the base class's `accessible_by`, so
+            # without this a role with no customer permission could still list
+            # who buys for a node — and memberships carry customer emails.
+            before_action :authorize_parent_access!
+
+            # POST /api/v3/admin/companies/:company_id/memberships
+            def create
+              result = Spree.company_add_member_service.call(
+                company: @parent,
+                email: params.require(:customer_email),
+                metadata: permitted_params[:metadata]
+              )
+
+              if result.success?
+                serializer = if result.value.is_a?(Spree::CompanyInvitation)
+                               Spree.api.admin_company_invitation_serializer
+                             else
+                               serializer_class
+                             end
+                render json: serializer.new(result.value, params: serializer_params).to_h, status: :created
+              else
+                render_validation_error(result.value.errors)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::CompanyMembership
+            end
+
+            def serializer_class
+              Spree.api.admin_company_membership_serializer
+            end
+
+            def scope
+              @parent.memberships
+            end
+
+            def parent_association
+              :memberships
+            end
+
+            def collection_includes
+              [:customer]
+            end
+
+            def permitted_params
+              params.permit(:customer_email, metadata: {})
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb

@@ -0,0 +1,137 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # A company's exemption evidence. Accepting one is a decision, so it
+          # runs through the verify workflow rather than a status write, and a
+          # verified certificate is revoked rather than deleted.
+          class TaxExemptionCertificatesController < BaseController
+            include ActiveStorage::SetCurrent
+
+            before_action :authorize_parent_access!
+            # Re-declaring the filter replaces the inherited options, so the
+            # standard actions have to be listed alongside the custom ones.
+            before_action :set_resource, only: [:show, :update, :destroy, :verify, :revoke, :download]
+
+            # A tampered signed id would otherwise surface as a 500.
+            rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature
+
+            # PATCH /api/v3/admin/companies/:company_id/tax_exemption_certificates/:id/verify
+            def verify
+              result = Spree.tax_exemption_certificate_verify_workflow.call(
+                certificate: @resource,
+                verified_by: try_spree_current_user
+              )
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_result_error(result)
+              end
+            end
+
+            # PATCH .../:id/revoke — withdrawing evidence that was accepted.
+            def revoke
+              if @resource.update(status: 'revoked')
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            # GET .../:id/download — streamed rather than redirected, so the
+            # document is never reachable without admin credentials.
+            def download
+
+              unless @resource.document.attached?
+                return render_error(
+                  code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                  message: 'Certificate has no attached document',
+                  status: :unprocessable_content
+                )
+              end
+
+              send_data(
+                @resource.document.download,
+                filename: @resource.document.filename.to_s,
+                type: @resource.document.content_type || 'application/octet-stream',
+                disposition: 'attachment'
+              )
+            end
+
+            protected
+
+            # Fetching the document is a read of the certificate, so it takes the
+            # read scope and the :show ability rather than being classed as a
+            # write because it isn't index or show. Without this a key holding
+            # read_customers is refused its own certificate.
+            READ_ACTIONS = %w[index show download].freeze
+
+            def read_actions
+              READ_ACTIONS
+            end
+
+            def action_kind
+              READ_ACTIONS.include?(action_name) ? 'read' : 'write'
+            end
+
+            def model_class
+              Spree::TaxExemptionCertificate
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_exemption_certificate_serializer
+            end
+
+            def scope
+              @parent.tax_exemption_certificates
+            end
+
+            def parent_association
+              :tax_exemption_certificates
+            end
+
+            def collection_includes
+              [{ document_attachment: :blob }]
+            end
+
+            # `document` is an ActiveStorage signed blob id from
+            # POST /api/v3/admin/direct_uploads.
+            def permitted_params
+              params.permit(:certificate_number, :reason_code, :issuing_authority,
+                            :issued_at, :expires_at, :country_code, :state_code, :document,
+                            metadata: {})
+            end
+
+            def build_resource
+              super.tap { |certificate| certificate.status ||= 'pending' }
+            end
+
+            # The custom actions are not permissions of their own: accepting or
+            # withdrawing is updating, fetching the document is reading.
+            def authorize_resource!(resource = @resource, action = action_name.to_sym)
+              mapped = case action
+                       when :verify, :revoke then :update
+                       when :download then :show
+                       else action
+                       end
+
+              authorize!(mapped, resource)
+            end
+
+            private
+
+            def render_invalid_signature
+              render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+                message: 'Invalid document signed id',
+                status: :unprocessable_content
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/companies/tax_identifiers_controller.rb

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Companies
+          # A business's own tax registration — the number that goes on its
+          # invoices, which outranks the buyer's own when the two differ.
+          #
+          # Mirrors the customer registrations endpoint, including manual
+          # re-validation: a registry answers only "valid now", so a number
+          # verified last year may have been deregistered since.
+          class TaxIdentifiersController < BaseController
+            include Spree::Api::V3::TaxIdentifierValidation
+
+            before_action :authorize_parent_access!
+            # Re-declaring the filter replaces the inherited options, so the
+            # standard actions have to be listed alongside the custom one.
+            before_action :set_resource, only: [:show, :update, :destroy, :validate]
+
+            protected
+
+            def model_class
+              Spree::TaxIdentifier
+            end
+
+            def serializer_class
+              Spree.api.admin_tax_identifier_serializer
+            end
+
+            def scope
+              @parent.tax_identifiers
+            end
+
+            def parent_association
+              :tax_identifiers
+            end
+
+            def permitted_params
+              params.permit(:kind, :value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Company nodes — tree-aware CRUD. A company is a customer record, so
+        # it answers to the customer scopes rather than earning one of its own.
+        #
+        # The tree is driven by Ransack: `?q[parent_id_null]=1` lists roots,
+        # `?q[parent_id_eq]=` a node's children. Deleting a node destroys its
+        # subtree. Re-parenting is an ordinary update — the model revalidates
+        # depth, cycle and store.
+        class CompaniesController < ResourceController
+          scoped_resource :customers
+
+          protected
+
+          def model_class
+            Spree::Company
+          end
+
+          def serializer_class
+            Spree.api.admin_company_serializer
+          end
+
+          def scope
+            super.for_store(current_store)
+          end
+
+          def collection_includes
+            [:children, :memberships, :external_references]
+          end
+
+          def permitted_params
+            permitted = params.permit(*model_additional_permitted_attributes,
+                                      :name, :kind, :parent_id, :po_number_required, metadata: {})
+            resolve_parent_param(permitted)
+          end
+
+          private
+
+          # The parent is an incidental lookup like any other: resolved through
+          # the store so another tenant's node 404s rather than becoming this
+          # node's parent.
+          def resolve_parent_param(permitted)
+            return permitted unless permitted.key?(:parent_id)
+
+            permitted[:parent_id] =
+              if permitted[:parent_id].present?
+                current_store.companies.find_by_prefix_id!(permitted[:parent_id]).id
+              else
+                nil
+              end
+            permitted
+          end
+        end
+      end
+    end
+  end
+end