spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,243 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DeliveryMethodsController < ResourceController
+          scoped_resource :delivery_methods
+
+          # GET /api/v3/admin/delivery_methods/calculators
+          # Registered delivery calculator classes with their preference
+          # schemas, so admin UIs can render configuration forms.
+          def calculators
+            authorize! :create, model_class
+
+            data = Spree::DeliveryMethod.calculators.map do |calculator_class|
+              {
+                type: calculator_class.api_type,
+                name: calculator_class.description,
+                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          # GET /api/v3/admin/delivery_methods/fulfillment_providers
+          # Registered FulfillmentProvider strategies with their class
+          # predicates, so admin UIs render capability hints from the
+          # registry, not JS constants.
+          def fulfillment_providers
+            authorize! :create, model_class
+
+            data = Spree.fulfillment_providers.map do |provider_class|
+              {
+                type: provider_class.to_s,
+                name: provider_class.provider_name,
+                integration_class: provider_class.integration_class,
+                integration_type: integration_api_type(provider_class),
+                available: provider_class.available_for_store?(current_store),
+                digital: provider_class.digital?,
+                pickup: provider_class.pickup?,
+                pickup_point: provider_class.pickup_point?,
+                requires_address: provider_class.new.requires_address?
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          # GET /api/v3/admin/delivery_methods/rate_providers
+          # Registered DeliveryRateProvider strategies. Providers whose
+          # integration isn't connected come back with `available: false` so
+          # the dashboard can offer connecting it inline — DeliveryMethod
+          # still rejects an unavailable provider on save. `service_catalog`
+          # feeds the carrier-services picker (empty = free-form).
+          def rate_providers
+            authorize! :create, model_class
+
+            data = Spree.delivery_rate_providers.map do |provider_class|
+              integration = provider_class.integration_class.presence &&
+                current_store.integrations.active.find_by(type: provider_class.integration_class)
+              catalog = provider_class.service_catalog(integration)
+
+              {
+                type: provider_class.to_s,
+                name: provider_class.provider_name,
+                integration_class: provider_class.integration_class,
+                integration_type: integration_api_type(provider_class),
+                available: provider_class.available_for_store?(current_store),
+                requires_address: provider_class.requires_address?,
+                uses_calculator: provider_class.uses_calculator?,
+                service_catalog: catalog.services,
+                # Present when the provider could not list services (e.g. a
+                # credential tier without access) — the picker shows it
+                # instead of an empty list.
+                service_catalog_error: catalog.error_message
+              }
+            end
+
+            render json: { data: data, default: Spree::DeliveryMethod::DEFAULT_RATE_PROVIDER }
+          end
+
+          def create
+            @resource = model_class.new(assignable_params)
+            authorize_resource!(@resource, :create)
+            assign_calculator(@resource)
+
+            if @resource.errors.empty? && @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            @resource.assign_attributes(assignable_params)
+            assign_calculator(@resource)
+
+            if @resource.errors.empty? && @resource.save
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          protected
+
+          # Wire shorthand of the provider's integration (`easy_post`), so the
+          # dashboard can tie a provider to the integration it needs without
+          # translating Ruby class names client-side.
+          def integration_api_type(provider_class)
+            klass = provider_class.integration_class.presence&.safe_constantize
+            klass&.api_type
+          end
+
+          def model_class
+            Spree::DeliveryMethod
+          end
+
+          def serializer_class
+            Spree.api.admin_delivery_method_serializer
+          end
+
+          # A single POST/PATCH can ship eligibility rules and carrier service
+          # rows alongside the basics; `DeliveryMethod#rules=` / `#services=`
+          # reconcile to the desired set, so the dashboard saves the whole
+          # sheet in one round-trip.
+          def permitted_params
+            params.permit(
+              *model_additional_permitted_attributes,
+              :name, :admin_name, :code, :fulfillment_provider,
+              :pickup_point_provider, :rate_provider, :storefront_visible, :tracking_url,
+              :available_to_sellers,
+              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
+              :tax_category_id, :calculator_type, :markup_flat, :markup_percent,
+              :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id,
+              stock_location_ids: [], calculator_preferences: {},
+              rules: rule_attributes,
+              services: [:id, :carrier, :service, :label, :markup_flat, :markup_percent, :position]
+            )
+          end
+
+          def rule_attributes
+            [:id, :type, :active, { preferences: {} }, *subclassed_rule_attributes]
+          end
+
+          # Association-backed rule config declares itself on the rule class
+          # (e.g. `[product_ids: []]`), so plugin-defined rules need no change
+          # here.
+          def subclassed_rule_attributes
+            Spree.delivery_method_rules.flat_map do |klass|
+              klass.respond_to?(:additional_permitted_attributes) ? klass.additional_permitted_attributes : []
+            end.uniq
+          end
+
+          def collection_includes
+            [:calculator, :tax_category, :delivery_zone, :delivery_profile, :delivery_method_rules, :seller]
+          end
+
+          private
+
+          # Resolves prefixed-ID params to records; calculator handled separately.
+          def assignable_params
+            attributes = permitted_params.except(:tax_category_id, :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id, :stock_location_ids, :calculator_type, :calculator_preferences)
+            if params.key?(:tax_category_id)
+              attributes[:tax_category] = params[:tax_category_id].present? ? Spree::TaxCategory.accessible_by(current_ability, :show).find_by_prefix_id!(params[:tax_category_id]) : nil
+            end
+            if params.key?(:delivery_profile_id)
+              attributes[:delivery_profile] = current_store.delivery_profiles.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_profile_id])
+            end
+            if params.key?(:delivery_origin_group_id) && params[:delivery_origin_group_id].present?
+              attributes[:delivery_origin_group] = current_store.delivery_origin_groups.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_origin_group_id])
+            end
+            if params.key?(:delivery_zone_id)
+              attributes[:delivery_zone] = params[:delivery_zone_id].present? ? current_store.delivery_zones.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_zone_id]) : nil
+            end
+            if params.key?(:stock_location_ids)
+              attributes[:pickup_locations] = Array(params[:stock_location_ids]).map { |id| current_store.stock_locations.accessible_by(current_ability, :show).find_by_prefix_id!(id) }
+            end
+            attributes[:rules] = resolved_rule_rows if params.key?(:rules)
+            attributes
+          end
+
+          # `DeliveryMethod#rules=` decodes prefixed ids but applies no store
+          # or ability scoping, so resolve association-backed config here — a
+          # product the caller cannot reach 404s rather than silently linking.
+          def resolved_rule_rows
+            Array(permitted_params[:rules]).map do |row|
+              row = row.to_h
+              row['product_ids'].blank? ? row : row.merge('product_ids' => accessible_product_ids(row['product_ids']))
+            end
+          end
+
+          # Keeps only the products this caller can reach in this store, and
+          # plucks ids rather than hydrating rows to read them back. Ids that
+          # resolve to nothing — another store's, or a product deleted while
+          # the sheet was open — are dropped: they cannot become an exclusion,
+          # and failing the whole save over one would leave the merchant stuck
+          # with no way to clear it. Mirrors how price lists filter membership.
+          def accessible_product_ids(ids)
+            current_store.products.
+              accessible_by(current_ability, :show).
+              where(id: decode_prefixed_ids(ids)).
+              pluck(:id)
+          end
+
+          def assign_calculator(delivery_method)
+            calculator_type = permitted_params[:calculator_type]
+            preferences = permitted_params[:calculator_preferences]
+
+            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
+              selected_calculator_class = Spree::DeliveryMethod.calculators.find do |klass|
+                klass.api_type == calculator_type
+              end
+              unless selected_calculator_class
+                delivery_method.errors.add(:calculator_type, :invalid)
+                return
+              end
+
+              delivery_method.calculator = selected_calculator_class.new
+            end
+
+            return if preferences.blank?
+
+            # A payload may carry preferences without naming a calculator —
+            # editing the amount on a method that already has one, or creating
+            # with the default. The model only builds the default calculator
+            # at validation, so without this the preferences land on nothing
+            # and the amount the merchant typed is silently replaced by a free
+            # rate.
+            delivery_method.ensure_calculator
+            return if delivery_method.calculator.nil?
+
+            preferences.each do |key, value|
+              next unless delivery_method.calculator.has_preference?(key)
+
+              delivery_method.calculator.set_preference(key, value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/delivery_profiles/origin_groups_controller.rb

@@ -0,0 +1,80 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module DeliveryProfiles
+          # Origin groups of one delivery profile. `stock_location_ids`
+          # replaces the group's full membership; empty means every store
+          # location. Deleting a group cascades to its zones and methods;
+          # only the profile's last group refuses to go.
+          class OriginGroupsController < ResourceController
+            scoped_resource :settings
+
+            def create
+              @resource = scope.new(assignable_params)
+              authorize_resource!(@resource, :create)
+
+              if @resource.save
+                render json: serialize_resource(@resource), status: :created
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            def update
+              @resource.assign_attributes(assignable_params)
+
+              if @resource.save
+                render json: serialize_resource(@resource)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::DeliveryOriginGroup
+            end
+
+            def serializer_class
+              Spree.api.admin_delivery_origin_group_serializer
+            end
+
+            def scope
+              parent_profile.delivery_origin_groups.ordered
+            end
+
+            def permitted_params
+              params.permit(*model_additional_permitted_attributes, :name, :position, stock_location_ids: [])
+            end
+
+            def collection_includes
+              [:stock_locations]
+            end
+
+            private
+
+            def parent_profile
+              @parent_profile ||= current_store.delivery_profiles.
+                accessible_by(current_ability, :show).
+                find_by_prefix_id!(params[:delivery_profile_id])
+            end
+
+            def assignable_params
+              attributes = permitted_params.except(:stock_location_ids)
+
+              if params.key?(:stock_location_ids)
+                attributes[:stock_locations] = Array(params[:stock_location_ids]).map do |id|
+                  current_store.stock_locations.accessible_by(current_ability, :show).find_by_prefix_id!(id)
+                end
+              end
+
+              attributes
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Fulfillment profiles — the grouping that decides how a set of
+        # products ships (origins, zones, methods). Stock-location membership
+        # is managed atomically through the profile: `stock_location_ids`
+        # replaces the full set; an empty array means every store location.
+        class DeliveryProfilesController < ResourceController
+          scoped_resource :settings
+
+          # GET /api/v3/admin/delivery_profiles/kinds
+          # Registered profile kinds, so admin UIs offer extension-added
+          # kinds without hardcoding the built-ins.
+          def kinds
+            authorize! :create, model_class
+
+            data = Spree.delivery_profile_types.map do |profile_class|
+              {
+                type: profile_class.to_s,
+                kind: profile_class.api_type
+              }
+            end
+
+            render json: { data: data }
+          end
+
+          def create
+            @resource = model_class.new(assignable_params)
+            authorize_resource!(@resource, :create)
+
+            if @resource.save
+              apply_default_group_locations(@resource)
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            @resource.assign_attributes(assignable_params)
+
+            if @resource.save
+              apply_default_group_locations(@resource)
+              render json: serialize_resource(@resource)
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::DeliveryProfile
+          end
+
+          def serializer_class
+            Spree.api.admin_delivery_profile_serializer
+          end
+
+          def scope
+            super.order_default
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :name, :default, :position, :kind, stock_location_ids: [])
+          end
+
+          def collection_includes
+            [delivery_origin_groups: :stock_locations]
+          end
+
+          private
+
+          def assignable_params
+            attributes = permitted_params.except(:kind, :stock_location_ids)
+
+            if @resource.nil?
+              attributes[:type] = params.key?(:kind) ? resolve_kind(params[:kind]).to_s : Spree::DeliveryProfiles::Shipping.to_s
+            end
+
+            attributes
+          end
+
+          # The profile-level shorthand writes the default origin group's
+          # membership — one call keeps working for single-group stores;
+          # multi-group stores manage members through the nested endpoint.
+          def apply_default_group_locations(profile)
+            return unless params.key?(:stock_location_ids)
+
+            locations = Array(params[:stock_location_ids]).map do |id|
+              current_store.stock_locations.accessible_by(current_ability, :show).find_by_prefix_id!(id)
+            end
+            profile.default_origin_group&.stock_locations = locations
+          end
+
+          # The wire kind (`shipping`, `digital`) resolves against the
+          # registry; an unknown kind is a client error, not a constantize.
+          def resolve_kind(kind)
+            Spree.delivery_profile_types.find { |klass| klass.api_type == kind.to_s } ||
+              raise(ActiveRecord::RecordNotFound)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Delivery zones with typed members (country / state / postal_code).
+        # Members are managed atomically through the zone: `members` in the
+        # payload replaces the full member set.
+        class DeliveryZonesController < ResourceController
+          scoped_resource :settings
+
+          def create
+            @resource = model_class.new(zone_params)
+            authorize_resource!(@resource, :create)
+
+            build_members(@resource) if params.key?(:members)
+
+            if @resource.save
+              render json: serialize_resource(@resource), status: :created
+            else
+              render_validation_error(@resource.errors)
+            end
+          end
+
+          def update
+            @resource.assign_attributes(zone_params)
+
+            model_class.transaction do
+              if params.key?(:members)
+                @resource.members.destroy_all
+                build_members(@resource)
+              end
+
+              if @resource.save
+                render json: serialize_resource(@resource)
+              else
+                render_validation_error(@resource.errors)
+                raise ActiveRecord::Rollback
+              end
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::DeliveryZone
+          end
+
+          def serializer_class
+            Spree.api.admin_delivery_zone_serializer
+          end
+
+          def permitted_params
+            params.permit(
+              *model_additional_permitted_attributes,
+              :name, :description, :delivery_profile_id, :delivery_origin_group_id,
+              members: [:member_type, :country_code, :state_code, :postal_code_prefix, :postal_code_from, :postal_code_to]
+            )
+          end
+
+          def collection_includes
+            [:members]
+          end
+
+          private
+
+          # A zone always lives inside a profile; absent an explicit one it
+          # joins the store default.
+          def zone_params
+            attributes = permitted_params.except(:members, :delivery_profile_id, :delivery_origin_group_id)
+            if params.key?(:delivery_profile_id) && params[:delivery_profile_id].present?
+              attributes[:delivery_profile] = current_store.delivery_profiles.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_profile_id])
+            end
+            if params.key?(:delivery_origin_group_id) && params[:delivery_origin_group_id].present?
+              attributes[:delivery_origin_group] = current_store.delivery_origin_groups.accessible_by(current_ability, :show).find_by_prefix_id!(params[:delivery_origin_group_id])
+            end
+            attributes
+          end
+
+          # Members are stored as codes. A subdivision may be given by code or
+          # by name, and a state member without a country has its country
+          # inferred — a code alone is ambiguous ("CA" is California and
+          # several other places), so an inference matching more than one
+          # country is rejected rather than guessed at.
+          def build_members(zone)
+            Array(permitted_params[:members]).each do |member|
+              attributes = member.to_h.symbolize_keys
+              country_code = attributes[:country_code].presence&.to_s&.upcase
+              state_value = attributes[:state_code].presence
+
+              if state_value.present?
+                country_code ||= infer_country_code_for_state(state_value)
+                attributes[:state_code] = Spree::IsoData.subdivision_code(country_code, state_value) if country_code
+              end
+
+              attributes[:country_code] = country_code
+              zone.members.build(attributes)
+            end
+          end
+
+          # Returns nil when the code is ambiguous, which leaves the member
+          # without a country for its presence validation to reject — better
+          # than silently picking one of several matching countries.
+          #
+          # @return [String, nil] the only country whose subdivisions match, if exactly one does
+          def infer_country_code_for_state(state_value)
+            matches = Spree::IsoData.countries.map(&:alpha2).select do |iso|
+              Spree::IsoData.subdivision_code(iso, state_value).present?
+            end
+
+            matches.one? ? matches.first : nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DigitalLinksController < ResourceController
+          scoped_resource :orders
+
+          before_action :set_resource, only: [:reset]
+
+          # PATCH /api/v3/admin/digital_links/:id/reset
+          #
+          # Gives the customer their download allowance back and restarts the
+          # expiry clock — the remedy when a download failed or a file was
+          # replaced after they had used up their attempts.
+          def reset
+            @resource.reset!
+
+            render json: serialize_resource(@resource)
+          end
+
+          protected
+
+          def model_class
+            Spree::DigitalLink
+          end
+
+          def serializer_class
+            Spree.api.admin_digital_link_serializer
+          end
+
+          # `digital_links` reaches links through line items, so the query
+          # carries a DISTINCT and inherits an ORDER BY on the line items'
+          # table. PostgreSQL rejects DISTINCT combined with an ORDER BY column
+          # outside the select list, so reorder by the links' own table —
+          # SQLite tolerates the inherited order, so this only surfaces on a
+          # real deployment.
+          def scope
+            current_store.digital_links.reorder("#{Spree::DigitalLink.table_name}.created_at": :desc)
+          end
+
+          def scope_includes
+            [:line_item, digital_asset: { attachment_attachment: :blob }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,8 @@ module Spree
     module V3
       module Admin
         class DirectUploadsController < Admin::BaseController
+          include Spree::Api::V3::DirectUploads
+
           # Direct uploads is a write-adjacent presigning helper: callers exchange
           # blob metadata for an upload URL, then reference the resulting
           # signed_id when creating/updating a resource (product media, customer
@@ -16,8 +18,12 @@ module Spree
           skip_before_action :authenticate_user
 
           # POST /api/v3/admin/direct_uploads
+          #
+          # Overrides the shared concern's create to select the storage service:
+          # digital assets must land on private storage up front, since attaching
+          # a signed id never moves a blob between services.
           def create
-            blob = ActiveStorage::Blob.create_before_direct_upload!(**blob_params)
+            blob = ActiveStorage::Blob.create_before_direct_upload!(service_name: storage_service_name, **blob_params)
 
             render json: {
               direct_upload: {
@@ -30,8 +36,16 @@ module Spree
 
           private
 
-          def blob_params
-            params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
+          # Attaching a signed id never moves the blob between services, so a
+          # file destined for a private attachment has to be uploaded to the
+          # private service up front. `private: true` asks for that; everything
+          # else keeps landing on the public service as before.
+          def storage_service_name
+            if params[:private].to_b
+              Spree.private_storage_service_name
+            else
+              Spree.public_storage_service_name
+            end
           end
         end
       end

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cross-order listing of exchanges — "what is awaiting fulfillment
+        # across the whole store". Read-only by route: opening an exchange
+        # needs an order, so creation and the status transitions stay on the
+        # nested Orders::ExchangesController.
+        class ExchangesController < 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::Exchange
+          end
+
+          def serializer_class
+            Spree.api.admin_exchange_serializer
+          end
+
+          def collection_includes
+            [:order, :reason, :stock_location, { exchange_line_items: [:original_variant, :new_variant] }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -98,7 +98,7 @@ module Spree
           # is intentionally dropped — only CSV is supported and Rails' request
           # format would otherwise overwrite the model's enum.
           def permitted_params
-            attrs = params.permit(:type, :record_selection, :results_url)
+            attrs = params.permit(*model_additional_permitted_attributes, :type, :record_selection, :results_url)
             raw = params[:search_params]
             attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
             attrs
@@ -118,7 +118,7 @@ module Spree
             return nil if name.blank?
 
             name = name.to_s
-            Spree::Export.available_types.find { |type| type.api_type == name || type.to_s == name }
+            Spree::Export.available_types.find { |type| type.api_type == name }
           end
 
           private