spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ClaimReasonsController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::ClaimReason
+          end
+
+          def serializer_class
+            Spree.api.admin_claim_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/claims_controller.rb

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cross-order listing of claims — "what is awaiting resolution across
+        # the whole store". Read-only by route: opening a claim needs an
+        # order, so creation and the status transitions stay on the nested
+        # Orders::ClaimsController.
+        class ClaimsController < 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::Claim
+          end
+
+          def serializer_class
+            Spree.api.admin_claim_serializer
+          end
+
+          def collection_includes
+            [:order, :reason, { claim_line_items: :variant }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Discovery for `Spree::CollectionRule` STI subclasses, so the dashboard
+        # can offer every registered rule kind — including ones a plugin adds to
+        # `config.spree.collection_rules` — without hard-coding the list.
+        #
+        # Read-only by design: rules are written through the owning collection's
+        # `rules` sync setter (PATCH /collections/:id), not as a nested resource.
+        class CollectionRulesController < ResourceController
+          # Rule kinds are part of the collections surface — a key that can read
+          # collections can discover the rules it may configure on them.
+          scoped_resource :collections
+
+          def types
+            authorize! :read, model_class
+
+            render json: { data: model_class.subclasses_with_preference_schema }
+          end
+
+          protected
+
+          def model_class
+            Spree::CollectionRule
+          end
+
+          def serializer_class
+            Spree.api.admin_collection_rule_serializer
+          end
+
+          # `types` is read-only discovery — maps to the read scope + :show ability.
+          def read_actions
+            super + %w[types]
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/collections/products_controller.rb

@@ -0,0 +1,101 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Collections
+          # The products curated under a collection — the uniform nested
+          # membership surface (see Spree::Api::V3::Admin::ProductMembership),
+          # plus per-member reposition: listing is ordered by the
+          # ProductCollection position so the merchant's manual ordering
+          # round-trips. Automatic (rule-based) membership is materialized by
+          # the rules, not managed here.
+          class ProductsController < ResourceController
+            include Spree::Api::V3::Admin::ProductMembership
+
+            scoped_resource :products
+
+            before_action :ensure_manual_collection, only: [:create, :destroy, :reposition]
+            before_action :set_product, only: [:reposition]
+
+            # PATCH /api/v3/admin/collections/:collection_id/products/:id/reposition
+            # Body: { new_position: 0 } — 0-based index among the collection's products.
+            # @product is already constrained to the collection's scope, so a
+            # ProductCollection always exists.
+            def reposition
+              position = integer_param(:new_position)
+              return render_invalid_position if position.nil?
+
+              product_collection_for(@product).insert_at(position + 1)
+              # insert_at shifts sibling positions, so refresh every product in the
+              # collection (manual sort reads position from the search index).
+              @parent_collection.products.find_each(&:enqueue_search_index)
+              head :no_content
+            end
+
+            protected
+
+            # The collection's products, ordered by membership position.
+            def scope
+              product_scope.
+                joins(:product_collections).
+                where(Spree::ProductCollection.table_name => { collection_id: @parent_collection.id }).
+                order(Spree::ProductCollection.table_name => { position: :asc })
+            end
+
+            # A product is curated at most once per collection (unique
+            # [collection_id, product_id]), so the join can't duplicate rows —
+            # DISTINCT is unnecessary and breaks Postgres ordering by position.
+            def collection_distinct?
+              false
+            end
+
+            def add_member_products(products)
+              Spree::Collections::AddProducts.call(collections: [@parent_collection], products: products)
+            end
+
+            def remove_member_products(products)
+              Spree::Collections::RemoveProducts.call(collections: [@parent_collection], products: products)
+            end
+
+            # Loads the parent collection (runs before the base set_resource).
+            # Any collection resolves — listing (index) an automatic collection's
+            # rule-materialized membership is valid. Manual-only curation is enforced
+            # separately by +ensure_manual_collection+ on the write actions.
+            def set_parent
+              @parent_collection = Spree::Collection.
+                            accessible_by(current_ability, parent_ability_action).
+                            for_store(current_store).
+                            find_by_prefix_id!(params[:collection_id])
+              authorize_parent!(@parent_collection)
+            end
+
+            private
+
+            # Manual curation (add/remove/reposition) is invalid on automatic
+            # collections: their membership is materialized from rules by
+            # RegenerateProducts, so a manual change would be wiped on the next
+            # regeneration. Listing (index) the materialized membership is fine.
+            def ensure_manual_collection
+              return if @parent_collection.manual?
+
+              render_error(
+                code: ERROR_CODES[:validation_error],
+                message: Spree.t('api.errors.automatic_collection_curation',
+                                 default: "Products of an automatic collection are managed by its rules and can't be curated manually"),
+                status: :unprocessable_content
+              )
+            end
+
+            def set_product
+              @product = scope.find_by_prefix_id!(params[:id])
+            end
+
+            def product_collection_for(product)
+              Spree::ProductCollection.find_by(collection_id: @parent_collection.id, product_id: product.id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin CRUD for collections — the flat, merchandising half of today's
+        # dual-purpose Taxon. Both manual and automatic (rule-based) collections
+        # live here. Reordering is a plain +position+ update (acts_as_list
+        # reorders siblings on save), matching the SPA ResourceTable reorder
+        # convention, so there is no dedicated reposition action.
+        class CollectionsController < ResourceController
+          scoped_resource :collections
+
+          protected
+
+          def model_class
+            Spree::Collection
+          end
+
+          def serializer_class
+            Spree.api.admin_collection_serializer
+          end
+
+          # The serializer always renders the rule set — eager load it.
+          # Eager-loaded unconditionally (as PromotionsController does for its
+          # own rules): the write path reads the association through the `rules=`
+          # sync setter regardless of what the response expands.
+          def scope_includes
+            [:rules]
+          end
+
+          def scope
+            super.ordered
+          end
+
+          # Flat params. +rules+ is applied by the model's sync setter
+          # (Spree::Collection#rules=): the full desired rule set, prefixed
+          # +crule_+ ids update, missing ids build, omitted rules are removed —
+          # so normalize_params is deliberately NOT called (that would rewrite
+          # +rules+ to +rules_attributes+ and route past the setter).
+          def permitted_params
+            params.permit(
+              :name, :description, :permalink, :position,
+              :meta_title, :meta_description, :meta_keywords,
+              :image, :square_image,
+              :automatic, :rules_match_policy, :sort_order,
+              rules: [:id, :type, :value, :match_policy],
+              # Inline custom field values keyed by definition id (see
+              # CategoriesController#permitted_params for the value shapes).
+              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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