spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,231 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # First-run setup (docs/plans/6.0-store-context-and-first-run-setup.md):
+        # a one-time, token-guarded flow that creates the first admin user and
+        # adopts the seeded store. Mounted under `/api/v3/admin/auth/...` so
+        # the issued refresh-token cookie's path matches `/auth/refresh` —
+        # same shape as invitation acceptance. Dead permanently once any
+        # admin user exists.
+        class SetupController < BaseController
+          include Spree::Api::V3::Admin::AuthCookies
+
+          skip_scope_check!
+          skip_before_action :authenticate_admin!, only: [:show, :countries, :create]
+
+          rate_limit to: Spree::Api::Config[:rate_limit_login],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     only: [:show, :countries, :create],
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
+
+          # GET /api/v3/admin/auth/setup
+          # Leaks a single boolean that is self-evident on a fresh install —
+          # the login page uses it to offer the setup screen.
+          def show
+            render json: { setup_required: setup_required? }
+          end
+
+          # GET /api/v3/admin/auth/setup/countries
+          # The setup screen runs before any credential exists, so it cannot
+          # use the authenticated countries endpoint. Currency and locales are
+          # derived here rather than in the client, so the market the setup
+          # builds and the currency the merchant was shown cannot disagree.
+          def countries
+            return render_setup_unavailable unless setup_required?
+
+            render json: { countries: Spree::Country.all.map { |country| country_payload(country) } }
+          end
+
+          # POST /api/v3/admin/auth/setup
+          # Body: { setup_token, email, password, password_confirmation?,
+          #         first_name?, last_name?, store_name, country_code,
+          #         locale?, currency? }
+          # Currency defaults to the country's own; an unknown code is refused
+          # rather than ignored, since the token is spent in the same request.
+          def create
+            return render_setup_unavailable unless setup_token_usable?
+            return render_missing_country if country.nil?
+            return render_unknown_currency if unknown_currency?
+
+            user = nil
+            store = Spree::Store.default
+
+            # The token is one-time, so the guard above must not be a bare
+            # check-then-act: two requests carrying the same token can both
+            # pass it and each create an admin. Re-checking under a row lock
+            # on the store serializes them — the loser sees a spent token.
+            store.with_lock do
+              return render_setup_unavailable unless setup_token_usable?(store.reload)
+
+              user = Spree.admin_user_class.create!(admin_user_params)
+              adopt_default_store(user, store)
+            end
+
+            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
+
+          def setup_required?
+            Spree.admin_user_class.present? && Spree.admin_user_class.count.zero?
+          end
+
+          # The token lives on the default store (has_secure_token) and only
+          # authorizes setup while no admin user exists.
+          def setup_token_usable?(store = Spree::Store.default)
+            return false unless setup_required?
+
+            provided = params[:setup_token].to_s
+            stored = store&.setup_token
+
+            provided.present? && stored.present? &&
+              ActiveSupport::SecurityUtils.secure_compare(stored, provided)
+          end
+
+          # Resolved before the token is spent: setup is one-shot, so a store
+          # provisioned for the wrong country would leave no in-band way to
+          # correct it.
+          def country
+            @country ||= Spree::Country.by_iso(params[:country_code]) if params[:country_code].present?
+          end
+
+          def render_missing_country
+            message = if params[:country_code].present?
+                        "Unknown country #{params[:country_code]}"
+                      else
+                        "Country can't be blank"
+                      end
+
+            render_error(
+              code: ERROR_CODES[:validation_error],
+              message: message,
+              status: :unprocessable_content,
+              details: { country_code: [message] }
+            )
+          end
+
+          # Blank means "use the country's own currency"; a code that resolves
+          # to nothing is a typo worth refusing before the token is spent.
+          def unknown_currency?
+            params[:currency].present? && ::Money::Currency.find(params[:currency].to_s.strip).nil?
+          end
+
+          def render_unknown_currency
+            message = "Unknown currency #{params[:currency]}"
+
+            render_error(
+              code: ERROR_CODES[:validation_error],
+              message: message,
+              status: :unprocessable_content,
+              details: { currency: [message] }
+            )
+          end
+
+          def country_payload(country)
+            {
+              code: country.iso,
+              name: country.name,
+              currency: country.default_currency,
+              locales: offerable_locales(country)
+            }
+          end
+
+          # A country's official languages, minus any Spree has no translations
+          # for — Switzerland speaks Romansh and Spree does not, so offering it
+          # would point a storefront at a language with nothing behind it.
+          # English closes the gap for countries whose languages all fall
+          # through, and is always offered alongside.
+          #
+          # Installs without spree_i18n only have English, and filtering
+          # against that would leave every country English-only. There the
+          # unfiltered list is the better answer: the merchant's own language
+          # is still the right default for their storefront, whether or not
+          # this install carries a translation bundle for it.
+          def offerable_locales(country)
+            return country.official_locales if translated_locales.size <= 1
+
+            (country.official_locales & translated_locales).presence || ['en']
+          end
+
+          def translated_locales
+            @translated_locales ||= Spree.available_locales.map { |locale| locale.to_s.split('-').first }.uniq
+          end
+
+          # Token mismatch, spent token, and already-set-up all render the
+          # same 404 so the endpoint leaks nothing about which it was.
+          def render_setup_unavailable
+            render_error(
+              code: ERROR_CODES[:record_not_found],
+              message: 'Setup is not available',
+              status: :not_found
+            )
+          end
+
+          def admin_user_params
+            params.permit(:email, :password, :password_confirmation, :first_name, :last_name)
+          end
+
+          # The seed already created the default store (every downstream seed
+          # depends on it existing) — setup claims and renames it rather than
+          # creating a second one, and spends the token.
+          #
+          # The country-shaped defaults (market, warehouse, delivery zones,
+          # pickup) are built here rather than seeded, because the seed ran
+          # before anyone had said where the shop sells from.
+          def adopt_default_store(user, store)
+            store.update!(store_params.merge(setup_token: nil))
+            store.add_user(user)
+
+            Spree::Stores::ProvisionDefaults.call(
+              store: store,
+              country: country,
+              locale: params[:locale].presence,
+              currency: params[:currency].presence
+            )
+          end
+
+          # `store_name` is optional: an API client may claim the installation
+          # without renaming the seeded store (the dashboard's form requires
+          # it, but the endpoint is the documented surface).
+          def store_params
+            params[:store_name].present? ? { name: params[:store_name] } : {}
+          end
+
+          def auth_response(user)
+            {
+              token: generate_jwt(user, audience: JWT_AUDIENCE_ADMIN),
+              user: Spree.api.admin_admin_user_serializer.new(user, params: serializer_params).to_h
+            }
+          end
+
+          def serializer_params
+            {
+              store: Spree::Store.default,
+              locale: current_locale,
+              currency: current_currency,
+              user: nil,
+              includes: []
+            }
+          end
+
+          def request_env_for_token
+            {
+              ip_address: request.remote_ip,
+              user_agent: request.user_agent&.truncate(255)
+            }
+          end
+
+          def jwt_expiration
+            Spree::Api::Config[:admin_jwt_expiration]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,172 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Stock levels are auto-created when a variant lands at a stock
+        # location, so there's deliberately no `create` route — use the
+        # variants / stock-locations endpoints for that flow.
+        class StockLevelsController < ResourceController
+          scoped_resource :stock
+
+          before_action :require_stock_levels!, only: [:bulk_upsert]
+
+          def bulk_upsert
+            authorize! :update, Spree::StockLevel
+
+            raw_rows = Array(params[:stock_levels]).map do |row|
+              row = row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h
+              row.with_indifferent_access
+            end
+            rows = decode_stock_rows(raw_rows)
+
+            invalid = rows.each_with_index.filter_map do |row, index|
+              missing = %i[variant_id stock_location_id].reject { |key| row[key].present? }
+              missing << :count_on_hand if row[:count_on_hand].blank? && row[:adjustment].blank?
+              { index: index, missing: missing } if missing.any?
+            end
+
+            if invalid.any?
+              return render_error(
+                code: 'invalid_stock_levels',
+                message: 'Each row must name a variant and stock location in this store, ' \
+                         'and either a count_on_hand or an adjustment.',
+                status: :unprocessable_content,
+                details: { rows: invalid }
+              )
+            end
+
+            result = Spree.stock_level_bulk_upsert_service.call(rows: rows)
+            render json: result.value
+          end
+
+          # PATCH /api/v3/admin/stock_levels/:id
+          #
+          # A count edit is a correction written as an `adjusted` movement
+          # rather than straight onto the column, which is what puts it in the
+          # stock history beside every other change — see
+          # {Spree::StockLevels::Correct}. The rest of the payload updates
+          # normally.
+          #
+          # Both halves share one transaction: a refused correction — a
+          # non-integer count, or a count and an adjustment together — must
+          # not leave the backorder flag or the metadata from the same request
+          # committed behind a 422.
+          def update
+            attributes = permitted_params.to_h
+            correction = attributes.extract!('count_on_hand', 'adjustment', 'reason')
+            result = nil
+
+            model_class.transaction do
+              @resource.update!(attributes) if attributes.any?
+
+              result = Spree.stock_level_correct_service.call(
+                stock_level: @resource,
+                count_on_hand: correction['count_on_hand'],
+                adjustment: correction['adjustment'],
+                reason: correction['reason']
+              )
+              raise ActiveRecord::Rollback if result.failure?
+            end
+
+            if result.failure?
+              @resource.reload
+              return render_validation_error(result.error.to_s)
+            end
+
+            render json: serialize_resource(result.value)
+          rescue ActiveRecord::RecordInvalid => e
+            render_errors(e.record.errors)
+          end
+
+          protected
+
+          def model_class
+            Spree::StockLevel
+          end
+
+          def serializer_class
+            Spree.api.admin_stock_level_serializer
+          end
+
+          # What the flat row attributes read, so a page of levels is a fixed
+          # number of queries however long it is.
+          def collection_includes
+            [:stock_location, { variant: [:primary_media, { option_values: :option_type }, { product: :primary_media }] }]
+          end
+
+          # `StockLevel.for_store` already applies its own `distinct`, and
+          # `id`-asc gives a stable order across edits (variant.position
+          # alone isn't unique — see git blame for the row-jumping bug).
+          def apply_collection_sort(collection)
+            collection.order(Spree::StockLevel.arel_table[:id].asc)
+          end
+
+          # Stock levels are auto-created against a (variant, stock_location)
+          # pair and never re-pointed, so update only touches the count and
+          # backorder flag — not the variant or location FKs.
+          #
+          # `reason` labels the correction in the stock history. It stays
+          # optional so an audit requirement never turns an existing endpoint
+          # into a 422; omitting it falls back to a translated default.
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :count_on_hand, :adjustment, :backorderable, :reason,
+                          metadata: {})
+          end
+
+          private
+
+          def require_stock_levels!
+            return if params.key?(:stock_levels)
+
+            render_error(
+              code: 'missing_stock_levels',
+              message: 'stock_levels is required (send an empty array to no-op).',
+              status: :unprocessable_content
+            )
+          end
+
+          # Every id is resolved through the current store's own scopes, so a
+          # variant or location belonging to another store is simply not found
+          # rather than quietly written to. Rows name records by Spree's own
+          # ids alone — this endpoint upserts stock levels, nothing more; a
+          # connector resolves its keys through the member paths first.
+          #
+          # Resolved as a batch: decoding a prefixed id is pure Ruby, so a
+          # thousand-row feed costs two SELECTs here, not two per row — and a
+          # feed repeats its stock location on nearly every row.
+          def decode_stock_rows(raw_rows)
+            variant_ids = resolve_ids(store_variants, Spree::Variant, raw_rows.map { |row| row[:variant_id] })
+            location_ids = resolve_ids(store_stock_locations, Spree::StockLocation, raw_rows.map { |row| row[:stock_location_id] })
+
+            raw_rows.map do |row|
+              {
+                variant_id: variant_ids[row[:variant_id]],
+                stock_location_id: location_ids[row[:stock_location_id]],
+                count_on_hand: row[:count_on_hand],
+                adjustment: row[:adjustment],
+                backorderable: row[:backorderable]
+              }.compact
+            end
+          end
+
+          # @return [Hash{String=>Integer}] prefixed id => id, for the ids the
+          #   scope can actually see; unknown or foreign ids resolve to nothing
+          def resolve_ids(scope, model, prefixed_ids)
+            decoded = prefixed_ids.uniq.index_with { |value| model.decode_own_prefixed_id(value) }
+            found = scope.where(id: decoded.values.compact).pluck(:id).to_set
+
+            decoded.transform_values { |id| id if id && found.include?(id) }
+          end
+
+          def store_variants
+            current_store.variants.accessible_by(current_ability, :update)
+          end
+
+          def store_stock_locations
+            current_store.stock_locations.accessible_by(current_ability, :update)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -27,11 +27,12 @@ module Spree
 
           def permitted_params
             params.permit(
+              *model_additional_permitted_attributes,
               :name, :admin_name, :active, :default,
               :kind, :propagate_all_variants, :backorderable_default,
               :address1, :address2, :city, :zipcode, :phone, :company,
-              :country_iso, :state_abbr, :state_name,
-              :pickup_enabled, :pickup_stock_policy,
+              :country_code, :state_code, :state_name,
+              :pickup_enabled, :pickup_stock_policy, :returns_enabled,
               :pickup_ready_in_minutes, :pickup_instructions
             )
           end

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

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Read-only. A movement is a fact about stock that already happened,
+        # so it is written by the stock verbs on Spree::StockLocation and
+        # never edited — reversing one means writing its counterpart.
+        class StockMovementsController < ResourceController
+          scoped_resource :stock
+
+          protected
+
+          def model_class
+            Spree::StockMovement
+          end
+
+          def serializer_class
+            Spree.api.admin_stock_movement_serializer
+          end
+
+          # Every row names its shelf, its SKU and its cause by number, so all
+          # of them come along rather than costing a query each.
+          def collection_includes
+            [{ stock_level: [:stock_location, { variant: :product }] },
+             :order, :return, :exchange, :stock_transfer, :purchase_order]
+          end
+
+          # Newest first: a stock history is read from the most recent change
+          # backwards.
+          def apply_collection_sort(collection)
+            collection.recent
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ module Spree
           end
 
           def collection_includes
-            [{ stock_item: [:variant, :stock_location], line_item: [], order: [] }]
+            [{ stock_level: [:variant, :stock_location], line_item: [], order: [] }]
           end
         end
       end

data/app/controllers/spree/api/v3/admin/stock_transfers/stock_receipts_controller.rb

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module StockTransfers
+          # The deliveries the destination warehouse counted in against one
+          # transfer. Recording one lands the accepted units on its shelf.
+          class StockReceiptsController < ResourceController
+            include Spree::Api::V3::Admin::StockReceiptActions
+
+            scoped_resource :stock
+
+            protected
+
+            def set_parent
+              @parent = current_store.stock_transfers.find_by_prefix_id!(params[:stock_transfer_id])
+            end
+
+            def create_workflow
+              Spree.stock_transfer_receive_workflow
+            end
+
+            def receivable_keyword
+              :stock_transfer
+            end
+          end
+        end
+      end
+    end
+  end
+end