spree_api 5.6.0 → 6.0.0.beta1

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

@@ -6,111 +6,161 @@ module Spree
           scoped_resource :products
 
           def create
-            if permitted_params[:url].present?
+            # An external video has no file, so it takes the plain create path
+            # even though a URL is present — `url` means "fetch this image from
+            # here" and only applies to image rows.
+            if permitted_params[:source_media_id].present?
+              create_from_library
+            elsif permitted_params[:url].present? && !external_video_request?
               create_from_url
             elsif permitted_params[:signed_id].present?
               create_from_signed_id
             else
-              @resource = build_resource
-              authorize_resource!(@resource, :create)
-
-              if @resource.save
-                render json: serialize_resource(@resource), status: :created
-              else
-                render_validation_error(@resource.errors)
-              end
+              authorize_and_create(build_resource)
             end
           end
 
           protected
 
+          # `url` and `signed_id` say how to *fetch* the bytes; neither is an
+          # attribute on the row. A re-synced asset already has its file, so
+          # the replay only carries them as leftovers from the create shape.
+          def normalize_upsert_params!
+            params.delete(:url)
+            params.delete(:signed_id)
+          end
+
           def model_class
-            Spree::Asset
+            Spree::Media
           end
 
           def serializer_class
             Spree.api.admin_media_serializer
           end
 
+          # A product's gallery is part of the product: authorizing the product
+          # here is the whole check, and the per-record hook stays a no-op so a
+          # media key is never required to manage a product's own pictures.
+          # The media keys govern the library.
+          def authorize_resource!(resource = @resource, action = action_name.to_sym); end
+
           def set_parent
             @product = current_store.products.find_by_prefix_id!(params[:product_id])
             authorize!(:update, @product)
 
             @parent = if params[:variant_id].present?
-                        @product.variants_including_master.find_by_prefix_id!(params[:variant_id])
+                        @product.variants.find_by_prefix_id!(params[:variant_id])
                       else
                         @product
                       end
           end
 
           # Variants store assets via the polymorphic `images` association; products own
-          # their gallery via `media`. Both resolve to `Spree::Asset` rows with different
+          # their gallery via `media`. Both resolve to `Spree::Media` rows with different
           # `viewable_type` values.
           def parent_association
             params[:variant_id].present? ? :images : :media
           end
 
           # For product-scoped listings we surface BOTH product-level assets and any
-          # legacy master-pinned assets, so existing data keeps showing up while
-          # merchants migrate. New uploads land on `Spree::Product` (see #set_parent).
+          # legacy assets still pinned to the default variant, so existing data keeps
+          # showing up while merchants migrate. New uploads land on `Spree::Product`
+          # (see #set_parent).
           def scope
             return super if params[:variant_id].present?
 
-            Spree::Asset.where(
+            Spree::Media.where(
               viewable_type: 'Spree::Product', viewable_id: @product.id
             ).or(
-              Spree::Asset.where(
-                viewable_type: 'Spree::Variant', viewable_id: @product.master&.id
+              Spree::Media.where(
+                viewable_type: 'Spree::Variant', viewable_id: @product.default_variant&.id
               )
             ).order(:position)
           end
 
-          ALLOWED_MEDIA_TYPES = -> { [Spree::Asset, *Spree::Asset.descendants].map(&:name).to_set.freeze }
-
           def build_resource
-            media_type = permitted_params[:type] || 'Spree::Image'
-
-            unless ALLOWED_MEDIA_TYPES.call.include?(media_type)
-              raise ArgumentError, "Invalid media type: #{media_type}"
-            end
-
-            media = @parent.send(parent_association).build(permitted_params.except(:type, :url, :signed_id))
-            media.type = media_type
+            @parent.send(parent_association).build(media_attributes)
+          end
 
-            media
+          # Everything the client sent minus the transport keys — a direct file,
+          # the URL to fetch one from, and the library row to copy are ways of
+          # getting at a file, not attributes of the row. Leaving `attachment`
+          # in let a request carrying it alongside `source_media_id` overwrite
+          # the shared blob with an upload, defeating the reuse.
+          def media_attributes
+            permitted_params.except(:attachment, :url, :signed_id, :source_media_id)
           end
 
+          # The media file, a URL to fetch one from, and the library row to copy
+          # are transport, not attributes — everything a client can set lives on
+          # the model.
           def permitted_params
-            params.permit(:type, :alt, :position, :attachment, :url, :signed_id, variant_ids: [])
+            params.permit(
+              *model_additional_permitted_attributes,
+              *Spree::Media::WRITABLE_ATTRIBUTES,
+              :attachment, :url, :signed_id, :source_media_id,
+              variant_ids: []
+            )
           end
 
-          def create_from_url
-            authorize!(:create, Spree::Asset)
+          def external_video_request?
+            permitted_params[:media_type] == 'external_video'
+          end
 
+          def create_from_url
             url = permitted_params[:url]
             position = permitted_params[:position]
 
+            # The job runs later, so the identities the connector sent ride
+            # along and are written on the media once it exists. All of them:
+            # a DAM and a PIM may both name the same asset.
+            references = external_reference_params.map { |entry| entry.transform_keys(&:to_s) }
+            references = references.presence
+
             Spree::Images::SaveFromUrlJob.perform_later(
               @parent.id,
               @parent.class.name,
               url,
-              nil,
+              references,
               position
             )
 
             head :accepted
           end
 
+          # Places a file already in the library onto this product or variant.
+          # The copy shares the source's blob, so nothing is uploaded and no
+          # rendition is regenerated; it gets its own alt, position and variant
+          # links from there on.
+          #
+          # The source is fetched through the store's own library, so a media id
+          # belonging to another store reads as a 404 rather than copying a
+          # file across the tenancy boundary.
+          def create_from_library
+            source = current_store.media.find_by_prefix_id!(permitted_params[:source_media_id])
+
+            @resource = source.duplicate_for(@parent)
+            # Anything the client sent alongside the source wins over what was
+            # copied, so a merchant can place a file and correct its alt text
+            # for the new context in one request.
+            @resource.assign_attributes(media_attributes)
+
+            authorize_and_create(@resource)
+          end
+
           def create_from_signed_id
             @resource = build_resource
             @resource.attachment.attach(permitted_params[:signed_id])
-            authorize_resource!(@resource, :create)
 
-            if @resource.save
-              render json: serialize_resource(@resource), status: :created
-            else
-              render_validation_error(@resource.errors)
-            end
+            authorize_and_create(@resource)
+          end
+
+          # The common tail of every create branch. Wraps the base class's
+          # save_and_render with the per-record authorization the branches
+          # share, since each builds its record a different way.
+          def authorize_and_create(media)
+            authorize_resource!(media, :create)
+            save_and_render(media, status: :created)
           end
         end
       end

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