spree_api 5.6.1 → 6.0.0.beta2

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

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

@@ -22,7 +22,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:prefix, :codes_count, :amount, :expires_at, :currency)
+            params.permit(*model_additional_permitted_attributes, :prefix, :codes_count, :amount, :expires_at, :currency)
           end
         end
       end

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

@@ -9,7 +9,7 @@ module Spree
         # `store` and `created_by` are auto-stamped by `build_resource` in
         # `Spree::Api::V3::ResourceController`, so create requests only need
         # to include user-facing attributes (amount, currency, expires_at,
-        # optional code, optional user_id).
+        # optional code, optional customer_id).
         class GiftCardsController < ResourceController
           scoped_resource :gift_cards
 
@@ -24,7 +24,8 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:code, :amount, :expires_at, :user_id, :currency)
+            params.permit(*model_additional_permitted_attributes, :code, :amount, :expires_at,
+                          :customer_id, :currency)
           end
         end
       end

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

@@ -26,10 +26,15 @@ module Spree
           def create
             @resource = build_resource
             authorize_resource!(@resource, :create)
+            # After authorization: a 404 for an unknown list must not tell a
+            # caller without import rights whether the id exists.
+            assign_price_list(@resource)
 
             if @resource.save
               begin
-                @resource.start_mapping!
+                result = Spree.import_start_mapping_workflow.call(import: @resource)
+
+                return render_service_error(result.error) unless result.success?
               rescue ::CSV::MalformedCSVError, EncodingError => e
                 @resource.update_columns(status: 'failed', processing_errors: e.message, updated_at: Time.current)
                 return render_error(
@@ -72,7 +77,10 @@ module Spree
             apply_mappings!(@resource)
 
             if @resource.mapping_done?
-              @resource.complete_mapping!
+              result = Spree.import_complete_mapping_workflow.call(import: @resource)
+
+              return render_service_error(result.error) unless result.success?
+
               render json: serialize_resource(@resource)
             else
               missing = @resource.required_fields - @resource.mappings.mapped.pluck(:schema_field)
@@ -96,7 +104,11 @@ module Spree
             @resource = find_resource
             authorize_resource!(@resource, :update)
 
-            if @resource.retry_failed_rows
+            return if refuse_seller_owned!
+
+            result = Spree.import_retry_failed_rows_workflow.call(import: @resource)
+
+            if result.success?
               render json: serialize_resource(@resource)
             else
               render_error(
@@ -136,7 +148,7 @@ module Spree
 
           # GET /api/v3/admin/imports/template?type=Spree::Imports::Products
           #
-          # CSV header row for the type's schema (including the metafield
+          # CSV header row for the type's schema (including the custom_field
           # columns available for the model) — the "Download template" link
           # in the admin dashboard.
           def template
@@ -181,6 +193,19 @@ module Spree
             redirect_to url, allow_other_host: true, status: :found
           end
 
+          # DELETE /api/v3/admin/imports/:id
+          #
+          # An operator deletes their own imports. A seller's is theirs to
+          # remove — see `refuse_seller_owned!`.
+          def destroy
+            @resource = find_resource
+            authorize_resource!(@resource, :destroy)
+
+            return if refuse_seller_owned!
+
+            super
+          end
+
           protected
 
           def model_class
@@ -224,8 +249,8 @@ module Spree
 
           def build_resource
             klass = resolve_import_type(permitted_params[:type]) || Spree::Import
-            attrs = permitted_params.except(:type).merge(
-              owner: current_store,
+            attrs = permitted_params.except(:type, :price_list_id).merge(
+              store: current_store,
               user: acting_admin_user
             )
             # The done email links back to results_url — allowed origins only.
@@ -234,7 +259,21 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:type, :attachment, :preferred_delimiter, :results_url)
+            params.permit(*model_additional_permitted_attributes, :type, :attachment, :preferred_delimiter, :results_url, :price_list_id)
+          end
+
+          # A price-list import writes into one list, named by its prefixed id.
+          # Resolved through the current store, so another store's list is a
+          # 404 rather than a write into it; a type without a list ignores the
+          # parameter. `permitted_params` does not normalize, so the raw
+          # prefixed id is what arrives here.
+          def assign_price_list(import)
+            return unless import.respond_to?(:price_list=)
+
+            prefixed_id = permitted_params[:price_list_id]
+            return if prefixed_id.blank?
+
+            import.price_list = current_store.price_lists.find_by_prefix_id!(prefixed_id)
           end
 
           # Returns the registered Import subclass matching `name`, or nil.
@@ -251,11 +290,35 @@ module Spree
             return nil if name.blank?
 
             name = name.to_s
-            Spree::Import.available_types.find { |type| type.api_type == name || type.to_s == name }
+            Spree::Import.available_types.find { |type| type.api_type == name }
           end
 
           private
 
+          # Refuses a write against an import one of this store's sellers ran,
+          # rendering 422 and answering true so the caller returns.
+          #
+          # An operator can see every import in their marketplace — that is the
+          # point of the store-scoped list, and it is what makes a seller's
+          # failed rows debuggable. Acting on one is different: a retry re-runs
+          # writes into the seller's own catalog, and nothing on the import
+          # would record that the operator, rather than the seller, caused
+          # them. So reads span the store and writes stay with whoever owns the
+          # row.
+          #
+          # @return [Boolean]
+          def refuse_seller_owned!
+            return false if @resource.seller_id.blank?
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+              message: Spree.t(:cannot_modify_seller_import, scope: 'api',
+                               default: "This import belongs to a seller. It can be viewed here, but only the seller can retry or delete it."),
+              status: :unprocessable_content
+            )
+            true
+          end
+
           # Imports require a user: row processors resolve records through
           # `import.current_ability`. JWT requests use the signed-in admin;
           # API-key requests attribute to the key's creator when that is an

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

@@ -0,0 +1,67 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Credential records for provider gems (delivery rates, tax, ...) —
+        # one per (store, type). The types endpoint is the dashboard's
+        # gallery source; activation is verified by the model
+        # (verify-before-activate), so a failed connection surfaces as a
+        # plain 422 on `active`.
+        class IntegrationsController < ResourceController
+          include Spree::Api::V3::Admin::SubclassedResource
+
+          scoped_resource :integrations
+
+          subclassed_via -> { Spree::Integration.registered_classes },
+                         unknown_type_error: 'unknown_integration_type'
+
+          # GET /api/v3/admin/integrations/types
+          # Pure registry discovery — which integrations are installed and how
+          # they're configured. Deliberately carries no per-store connected
+          # state: clients cache this long-lived and read live connection
+          # state from the integrations list instead.
+          def types
+            authorize! :create, model_class
+
+            render json: { data: Spree::Integration.discovery_entries }
+          end
+
+          # POST /api/v3/admin/integrations/:id/test
+          # Live connection check; nothing is persisted.
+          def test
+            @resource = find_resource
+            authorize_resource!(@resource, :update)
+
+            connected = @resource.can_connect?
+            render json: { connected: connected, error_message: connected ? nil : @resource.connection_error_message }
+          end
+
+          protected
+
+          def model_class
+            Spree::Integration
+          end
+
+          def serializer_class
+            Spree.api.admin_integration_serializer
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :type, :active, preferences: {})
+          end
+
+          # `types` is read-only discovery — maps to the read scope.
+          def read_actions
+            super + %w[types]
+          end
+
+          private
+
+          def build_subclassed_resource(klass, attrs)
+            current_store.integrations.build(attrs.merge(type: klass.sti_name))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Spree
                      within: Spree::Api::Config[:rate_limit_window].seconds,
                      store: Rails.cache,
                      only: [:lookup, :accept],
-                     with: RATE_LIMIT_RESPONSE
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
 
           # GET /api/v3/admin/auth/invitations/:id/lookup?token=:token
           def lookup
@@ -32,13 +32,13 @@ module Spree
             return if performed?
 
             @invitation.invitee = user
-            @invitation.accept!
+            result = Spree.invitation_accept_workflow.call(invitation: @invitation)
 
-            refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+            return render_service_error(result.error) unless result.success?
+
+            refresh_token = Spree::RefreshToken.create_for(user, audience: JWT_AUDIENCE_ADMIN, request_env: request_env_for_token)
             set_refresh_cookie(refresh_token)
             render json: auth_response(user)
-          rescue ActiveRecord::RecordInvalid => e
-            render_validation_error(e.record.errors)
           end
 
           private

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

@@ -9,7 +9,9 @@ module Spree
         class InvitationsController < ResourceController
           include Spree::Api::V3::Admin::RoleGrantGuard
 
-          scoped_resource :settings
+          # Staff management is the escalation path — its own scope pair,
+          # grantable separately from store configuration (6.0-admin-rbac.md).
+          scoped_resource :staff
 
           # POST /api/v3/admin/invitations
           # Guards against inviting a new staff member straight into the admin
@@ -67,6 +69,8 @@ module Spree
           end
 
           # `email` and `role_id` are flat — `role_id` accepts a prefixed ID.
+          # No extension union: an invitation carries only the role grant, which is
+          # the authorization surface itself, not extensible resource data.
           def permitted_params
             attrs = params.permit(:email, :role_id)
             if attrs[:role_id].present? && Spree::PrefixedId.prefixed_id?(attrs[:role_id])

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

@@ -6,7 +6,9 @@ module Spree
         # current store (its supported_locales_list), so the dashboard's locale
         # switcher enumerates locales instead of hardcoding them.
         class LocalesController < Admin::BaseController
-          scoped_resource :settings
+          # Reference data the dashboard shell needs regardless of the caller's
+          # grant — exempt from the key gate like `/tags` and `/countries`.
+          skip_scope_check!
 
           # GET /api/v3/admin/locales
           def index