spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,156 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The media library: every file in the store, whether or not it has been
+        # placed on a product yet.
+        #
+        # Subclasses the product-scoped media controller for its create
+        # branches, but drops the parent: a row created here has no viewable,
+        # which is what makes uploading before deciding where a file goes
+        # possible. Putting a file ON a product is the nested controller's job —
+        # POST that product's media with this row's id as `source_media_id`.
+        #
+        # `source_media_id` works here too, and means "copy this file into the
+        # library again" — an unplaced row sharing the original's blob.
+        class MediaLibraryController < MediaController
+          # The library reaches across products, categories and collections, so
+          # it is not a product endpoint. The nested gallery routes keep
+          # `products` — those are one product's own media, reached through a
+          # product the caller can already see.
+          scoped_resource :media
+          # Restates the base class's member actions with `usage` added — a
+          # second `before_action :set_resource` would replace that filter
+          # rather than extend it, leaving show/update/destroy without a record.
+          before_action :set_resource, only: %i[show update destroy usage]
+
+          # Deleting from the library means deleting the file. A file still in
+          # use needs the caller to say so — `detach=true`, which the dashboard
+          # sends after a confirmation showing the places — and then the file
+          # is removed from all of them in one pass. Without it the delete is
+          # refused with the usage list, so an API client can't take a file out
+          # from under a catalog by accident. Removing a file from one
+          # product's gallery is the nested endpoint's destroy, which stays
+          # unguarded: that is removing a placement, not the file.
+          def destroy
+            references = Spree::Media::Usage.call(media: @resource).value
+            return super if references.empty?
+
+            unless detach_requested?
+              return render_error(
+                code: ERROR_CODES[:resource_invalid],
+                message: Spree.t(
+                  'api.errors.media_in_use',
+                  places: references.filter_map(&:name).uniq.first(5).to_sentence
+                ),
+                status: :unprocessable_content,
+                details: { usage: references.map { |reference| reference_payload(reference) } }
+              )
+            end
+
+            result = Spree::Media::Destroy.call(media: @resource)
+            return head :no_content if result.success?
+
+            # A rolled-back delete carries no validation errors, so
+            # render_service_error would produce an empty message.
+            render_error(
+              code: ERROR_CODES[:processing_error],
+              message: Spree.t('api.errors.media_not_deleted'),
+              status: :unprocessable_content
+            )
+          end
+
+          # Where this file is in use — other products it has been placed on,
+          # plain image fields sharing it, and descriptions embedding it. What
+          # the dashboard shows before a merchant deletes something.
+          def usage
+            references = Spree::Media::Usage.call(media: @resource).value
+
+            render json: { data: references.map { |reference| reference_payload(reference) } }
+          end
+
+          protected
+
+          def detach_requested?
+            ActiveModel::Type::Boolean.new.cast(params[:detach])
+          end
+
+          def reference_payload(reference)
+            {
+              kind: reference.kind,
+              name: reference.name,
+              owner_type: reference.owner_type,
+              owner_id: reference.owner_id,
+              field: reference.field
+            }
+          end
+
+          # Reading where a file is used is reading the file, for the key gate
+          # and for CanCanCan alike. The latter needs saying twice: `read_actions`
+          # settles the required API-key scope, while this maps the action onto
+          # an ability a role actually grants — CanCanCan's `:read` alias covers
+          # only index and show, so a staffer with read access would otherwise
+          # be refused.
+          def read_actions
+            super + %w[usage]
+          end
+
+          # The library authorizes the media record itself; the product-nested
+          # controller authorizes its product instead, so this restores the
+          # per-record check its no-op skips. `usage` maps to `:show` because
+          # CanCanCan's `:read` alias covers only index and show.
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            authorize!(action == :usage ? :show : action, resource || Spree::Media)
+          end
+
+          # No parent to resolve. The library is the store's own collection, so
+          # tenancy comes from the store_id on the rows themselves rather than
+          # from a product two hops away.
+          def set_parent
+            @parent = nil
+          end
+
+          # The listing shows one row per file; member actions resolve any row.
+          #
+          # Reuse shares a blob across rows, so a picture placed on three
+          # products is three rows of the same image — the library shows files,
+          # and `usage` says where each one appears. But a row the grouping
+          # hides is still a real record a client may hold the id of, so
+          # narrowing every lookup would 404 it on show or destroy.
+          # The library has no parent, so this is the one media endpoint where
+          # the admin base's `accessible_by` would apply — a role's
+          # record-level rules must still filter it. `super` is skipped
+          # deliberately: the parent controller's scope reads @product, which
+          # a library request does not have.
+          def scope
+            media = current_store.media
+                                 .accessible_by(current_ability, ability_action_for_request)
+                                 .order(created_at: :desc)
+            listing? ? media.distinct_by_file : media
+          end
+
+          def listing?
+            action_name == 'index'
+          end
+
+          # A library row is born unplaced. `viewable` stays nil until someone
+          # copies the file onto a product.
+          def build_resource
+            current_store.media.build(media_attributes)
+          end
+
+          # There is no product to fetch into, so the URL import job — which
+          # takes a viewable — has nothing to target. A merchant importing by
+          # URL does it from the product they are filling.
+          def create_from_url
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:resource_invalid],
+              message: Spree.t('api.errors.media_url_import_requires_product'),
+              status: :unprocessable_content
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -21,6 +21,7 @@ module Spree
 
           def permitted_params
             params.permit(
+              *model_additional_permitted_attributes,
               :name, :label, :position, :filterable, :kind,
               option_values: [
                 :id, :name, :label, :position, :color_code, :image

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

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

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The multi-order transaction container — what a customer bought in one
+        # checkout when it was fulfilled by more than one seller.
+        #
+        # Read-only, enforced by the routes: a group records a checkout that
+        # already happened, and everything an operator can act on lives on the
+        # orders inside it or on the payment it holds.
+        class OrderGroupsController < ResourceController
+          scoped_resource :orders
+
+          protected
+
+          def model_class
+            Spree::OrderGroup
+          end
+
+          def serializer_class
+            Spree.api.admin_order_group_serializer
+          end
+
+          def scope
+            super.where(store_id: current_store.id)
+          end
+
+          # Everything both serializers touch. The group's figures are summed
+          # from its children and its payments are rendered in full, so a page
+          # of groups that did not preload them would issue a query per row for
+          # each.
+          def collection_includes
+            [
+              :customer, :ship_address, :bill_address,
+              { payments: %i[payment_method source] },
+              { orders: %i[market gift_card] }
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -30,7 +30,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:type, :active, :position, preferences: {})
+            params.permit(*model_additional_permitted_attributes, :type, :active, :position, preferences: {})
           end
 
           # `types` is read-only discovery — maps to the read scope + :show ability.

data/app/controllers/spree/api/v3/admin/orders/claims_controller.rb

@@ -0,0 +1,56 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Claims on a completed order.
+          class ClaimsController < BaseController
+            include Spree::Api::V3::Orders::ClaimActions
+
+            # Claims are a subject of the `orders` catalog resource, so
+            # `read_orders`/`write_orders` gate these endpoints. `:claims`
+            # would name a key no catalog knows.
+            scoped_resource :orders
+
+            before_action :set_resource, only: [:show, :update, :approve, :resolve, :deny, :cancel]
+
+            # PATCH /api/v3/admin/orders/:order_id/claims/:id
+            #
+            # Editable fields only — status moves through the member actions.
+            def update
+              if @resource.update(permitted_params)
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_claim_serializer
+            end
+
+            def collection_includes
+              [:reason, { claim_line_items: [:variant, :replacement_variant] }]
+            end
+
+            def permitted_params
+              params.permit(:memo, :reason_id, metadata: {})
+            end
+
+            private
+
+            # The whole store's catalogue: an operator may promise anything
+            # the store sells as a replacement.
+            def replacement_variant_for(variant_id)
+              return nil if variant_id.blank?
+
+              current_store.variants.find_by_prefix_id!(variant_id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/orders/deliveries_controller.rb

@@ -0,0 +1,66 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # The consignments of one fulfillment, under
+          # /orders/:order_id/fulfillments/:fulfillment_id/deliveries.
+          #
+          # CRUD lives in the shared concern; what is here is the store-wide
+          # scope and the one action only an operator has. The
+          # fulfillment-level mark_delivered stays beside it for parcels that
+          # have no delivery row at all.
+          class DeliveriesController < BaseController
+            include Spree::Api::V3::Orders::DeliveryActions
+
+            before_action :set_resource, only: [:show, :update, :destroy, :mark_delivered]
+
+            # PATCH .../deliveries/:id/mark_delivered — staff saying this one
+            # consignment arrived; the fulfillment follows once every
+            # consignment has.
+            def mark_delivered
+              with_order_lock do
+                result = Spree.delivery_update_tracking_workflow.call(
+                  delivery: @resource,
+                  tracking_status: 'delivered',
+                  delivered_at: mark_delivered_params[:delivered_at],
+                  notify_customer: notify_customer?(mark_delivered_params[:notify_customer])
+                )
+
+                if result.success?
+                  render json: serialize_resource(result.value)
+                else
+                  render_result_error(result)
+                end
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_delivery_serializer
+            end
+
+            # The consignments hang off the fulfillment, not the order, so
+            # the parent is narrowed one step past the base's.
+            def set_parent
+              super
+              @parent = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+            end
+
+            private
+
+            def mark_delivered_params
+              @mark_delivered_params ||= params.permit(:delivered_at, :notify_customer)
+            end
+
+            # Only an explicit false suppresses the email.
+            def notify_customer?(value)
+              !ActiveModel::Type::Boolean.new.cast(value).equal?(false)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/orders/discount_codes_controller.rb

@@ -0,0 +1,86 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Applies/removes a discount code on a draft order — the admin
+          # counterpart of the storefront cart endpoint, with the same pending
+          # semantics: a real-but-not-yet-eligible code is kept and activates
+          # on the first recalculation where the order qualifies. Completed
+          # orders are frozen; their discounts change only through manual rows
+          # (see DiscountsController).
+          class DiscountCodesController < BaseController
+            skip_before_action :set_resource, raise: false
+
+            # POST /api/v3/admin/orders/:order_id/discount_codes
+            def create
+              with_order_lock do
+                return render_completed_order_error if @parent.completed?
+
+                @parent.coupon_code = permitted_params[:code]
+
+                coupon_handler.apply
+
+                if coupon_handler.successful? || pending_eligibility?
+                  @parent.save!(validate: false) if @parent.changed?
+                  render json: serialize_resource(@parent.reload), status: :created
+                else
+                  @parent.update_column(:coupon_code, nil) if @parent.read_attribute(:coupon_code).present?
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/discount_codes/:id
+            # :id is the discount code string.
+            def destroy
+              with_order_lock do
+                return render_completed_order_error if @parent.completed?
+
+                coupon_handler.remove(params[:id])
+
+                if coupon_handler.successful?
+                  render json: serialize_resource(@parent.reload)
+                else
+                  render_errors(coupon_handler.error)
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Order
+            end
+
+            def serializer_class
+              Spree.api.admin_order_serializer
+            end
+
+            private
+
+            def coupon_handler
+              @coupon_handler ||= Spree.coupon_handler.new(@parent, enable_gift_cards: false)
+            end
+
+            def pending_eligibility?
+              coupon_handler.status_code == :coupon_code_not_eligible
+            end
+
+            def render_completed_order_error
+              render_error(
+                code: ERROR_CODES[:discount_not_editable],
+                message: Spree.t('errors.messages.coupon_code_frozen_after_completion'),
+                status: :unprocessable_content
+              )
+            end
+
+            def permitted_params
+              params.permit(:code)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/orders/discounts_controller.rb

@@ -0,0 +1,99 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Typed Spree::Discount rows on an order. Manual rows have full CRUD;
+          # promotion-sourced rows are read-only (recalculation owns them) and
+          # respond 422 to update/destroy. Mutations re-sum the order totals —
+          # this is the sanctioned post-placement discount path and works on
+          # completed orders.
+          class DiscountsController < BaseController
+            scoped_resource :orders
+
+            # POST /api/v3/admin/orders/:order_id/discounts
+            def create
+              with_order_lock do
+                line_item = @parent.line_items.find_by_prefix_id!(params[:line_item_id]) if params[:line_item_id].present?
+
+                result = Spree.order_discount_create_service.call(
+                  order: @parent,
+                  label: params[:label],
+                  value: params[:value].presence || params[:amount],
+                  value_type: params[:value_type].presence || 'flat',
+                  line_item: line_item
+                )
+
+                if result.success?
+                  render json: { data: serialize_collection(result.value) }, status: :created
+                else
+                  render_error(code: ERROR_CODES[:validation_error], message: result.error.to_s, status: :unprocessable_entity)
+                end
+              end
+            end
+
+            # PATCH /api/v3/admin/orders/:order_id/discounts/:id
+            def update
+              with_order_lock do
+                result = Spree.order_discount_update_service.call(order: @parent, discount: @resource, attributes: permitted_params)
+
+                if result.success?
+                  render json: serialize_resource(@resource)
+                elsif result.error.value == :promotion_discount_not_editable
+                  render_promotion_row_error
+                else
+                  render_validation_error(@resource.errors)
+                end
+              end
+            end
+
+            # DELETE /api/v3/admin/orders/:order_id/discounts/:id
+            def destroy
+              with_order_lock do
+                result = Spree.order_discount_destroy_service.call(order: @parent, discount: @resource)
+
+                if result.success?
+                  head :no_content
+                else
+                  render_promotion_row_error
+                end
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Discount
+            end
+
+            def serializer_class
+              Spree.api.admin_discount_serializer
+            end
+
+            def scope
+              @parent.discounts
+            end
+
+            def permitted_params
+              params.permit(:label, :amount)
+            end
+
+            def collection_includes
+              [:promotion, :line_item, :fulfillment]
+            end
+
+            private
+
+            def render_promotion_row_error
+              render_error(
+                code: ERROR_CODES[:discount_not_editable],
+                message: Spree.t('errors.messages.promotion_discount_not_editable'),
+                status: :unprocessable_entity
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/orders/exchanges_controller.rb

@@ -0,0 +1,62 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module Orders
+          # Exchanges on a completed order. Each status change is its own
+          # member action, because each carries different arguments.
+          class ExchangesController < BaseController
+            include Spree::Api::V3::Orders::ExchangeActions
+
+            # Exchanges are a subject of the `orders` catalog resource, so
+            # `read_orders`/`write_orders` gate these endpoints. `:exchanges`
+            # would name a key no catalog knows.
+            scoped_resource :orders
+
+            before_action :set_resource, only: [:show, :update, :approve, :receive, :fulfill, :cancel]
+
+            # PATCH /api/v3/admin/orders/:order_id/exchanges/:id
+            #
+            # Editable fields only — status moves through the member actions.
+            def update
+              if @resource.update(permitted_params)
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_exchange_serializer
+            end
+
+            def collection_includes
+              [:reason, :stock_location, { exchange_line_items: [:original_variant, :new_variant] }]
+            end
+
+            def permitted_params
+              params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+            end
+
+            private
+
+            # The whole store's catalogue, and any warehouse the caller may
+            # see: an operator exchanges into anything the store sells.
+            def replacement_variant_for(variant_id)
+              current_store.variants.find_by_prefix_id!(variant_id)
+            end
+
+            def stock_location_for_create
+              return nil if create_params[:stock_location_id].blank?
+
+              current_store.stock_locations.accessible_by(current_ability, :show).
+                find_by_prefix_id!(create_params[:stock_location_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end