spree_api 5.6.1 → 6.0.0.beta1

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

@@ -2,38 +2,101 @@ module Spree
   module Api
     module V3
       module Admin
-        # Inventory movement between stock locations, or vendor → location
-        # for receives. Pass `source_location_id` for transfers; omit it to
-        # record an external receive.
+        # Stock moving between two of the merchant's own warehouses.
+        #
+        # `create` persists a draft; nothing moves until the transfer is marked
+        # in transit. Receiving from a supplier is a
+        # {Spree::Api::V3::Admin::PurchaseOrdersController} order, not a
+        # transfer with a missing source.
+        #
+        # Every status change is its own member action rather than a PATCH that
+        # mass-assigns `status`, because each one is a workflow with its own
+        # arguments — receiving carries the quantities the warehouse counted,
+        # cancelling carries what happens to units already in flight.
         class StockTransfersController < ResourceController
-          scoped_resource :stock
+          include Spree::Api::V3::Admin::ReceivableActions
 
-          def create
-            authorize!(:create, model_class)
+          scoped_resource :stock
 
-            stock_locations = Spree::StockLocation.accessible_by(current_ability, :show)
-            destination = stock_locations.find_by_prefix_id!(params[:destination_location_id])
-            source = params[:source_location_id].present? ?
-              stock_locations.find_by_prefix_id!(params[:source_location_id]) : nil
+          # The base registers this for show/update/destroy; a second
+          # `before_action :set_resource` replaces that registration rather than
+          # adding to it, so those three are listed again here.
+          before_action :set_resource, only: [:show, :update, :destroy, :mark_ready, :mark_in_transit, :mark_draft, :close, :cancel]
 
-            variants_map = build_variants_map
-            if variants_map.empty?
+          # DELETE /api/v3/admin/stock_transfers/:id
+          #
+          # A draft is the only transfer a merchant may throw away: past that
+          # it describes a box that physically exists, which is cancelled
+          # rather than deleted.
+          #
+          # Really deleted, not stamped. Soft deletion exists for the upgrade
+          # task's converted receives, whose numbers have to stay findable; a
+          # draft nobody sent has nothing to preserve, and `destroy` would
+          # hard-delete its lines regardless (they are not paranoid), leaving a
+          # soft-deleted row that could never be restored intact.
+          def destroy
+            unless @resource.draft?
               return render_error(
-                code: 'invalid_variants',
-                message: Spree.t('stock_transfer.errors.must_have_variant'),
+                code: 'invalid_status',
+                message: Spree.t('stock_transfer.errors.only_draft_can_be_deleted'),
                 status: :unprocessable_content
               )
             end
 
-            @resource = source ?
-              Spree::StockTransfer.new(reference: params[:reference]).tap { |t| t.transfer(source, destination, variants_map) } :
-              Spree::StockTransfer.new(reference: params[:reference]).tap { |t| t.receive(destination, variants_map) }
+            authorize_resource!(@resource, :destroy)
+            @resource.really_destroy!
+            head :no_content
+          end
 
-            if @resource.persisted?
-              render json: serialize_resource(@resource), status: :created
-            else
-              render_validation_error(@resource.errors)
-            end
+          # PATCH /api/v3/admin/stock_transfers/:id/mark_ready
+          def mark_ready
+            result = Spree.stock_transfer_mark_ready_workflow.call(stock_transfer: @resource)
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/stock_transfers/:id/mark_in_transit
+          def mark_in_transit
+            result = Spree.stock_transfer_mark_in_transit_workflow.call(
+              stock_transfer: @resource,
+              force: params[:force].to_b
+            )
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/stock_transfers/:id/mark_draft
+          def mark_draft
+            result = Spree.stock_transfer_mark_draft_workflow.call(stock_transfer: @resource)
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/stock_transfers/:id/close
+          #
+          # Deliveries are recorded through the nested stock receipts; this is
+          # for units that left the source and are not going to turn up.
+          def close
+            result = Spree.stock_transfer_close_workflow.call(stock_transfer: @resource, reason: params[:reason])
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
+          end
+
+          # PATCH /api/v3/admin/stock_transfers/:id/cancel
+          def cancel
+            result = Spree.stock_transfer_cancel_workflow.call(
+              stock_transfer: @resource,
+              on_in_transit: params[:on_in_transit],
+              reason: params[:reason],
+              canceler: try_spree_current_user
+            )
+            return render_result_error(result) unless result.success?
+
+            render json: serialize_resource(result.value)
           end
 
           protected
@@ -47,27 +110,60 @@ module Spree
           end
 
           def collection_includes
-            [:source_location, :destination_location]
+            [:source_location, :destination_location, line_includes]
           end
 
-          private
+          def create_workflow
+            Spree.stock_transfer_create_workflow
+          end
 
-          # Variants the merchant doesn't have access to are dropped silently;
-          # if the resulting map is empty the action surfaces a 422
-          # `invalid_variants` so callers can distinguish "nothing supplied"
-          # from "all variants were rejected." A single SELECT covers any
-          # number of variants instead of N round-trips.
-          def build_variants_map
-            entries = params.permit(variants: [:variant_id, :quantity]).fetch(:variants, [])
-            quantities_by_id = entries.each_with_object({}) do |entry, hash|
-              decoded = Spree::PrefixedId.decode_prefixed_id(entry[:variant_id])
-              hash[decoded.to_i] = entry[:quantity].to_i if decoded
-            end
+          def update_workflow
+            Spree.stock_transfer_update_workflow
+          end
+
+          def create_workflow_arguments
+            {
+              store: current_store,
+              source_location: stock_location_from(:source_location_id),
+              destination_location: stock_location_from(:destination_location_id),
+              items: items_from_params(:quantity_shipped) || [],
+              reference: params[:reference],
+              notes: params[:notes],
+              created_by: try_spree_current_user
+            }
+          end
+
+          def update_workflow_arguments
+            {
+              stock_transfer: @resource,
+              attributes: editable_attributes,
+              items: items_from_params(:quantity_shipped)
+            }
+          end
 
-            current_store.variants.accessible_by(current_ability, :update).where(id: quantities_by_id.keys).each_with_object({}) do |variant, acc|
-              quantity = quantities_by_id[variant.id]
-              acc[variant] = quantity if quantity&.positive?
+          # Only what mass assignment may safely carry. The two warehouses are
+          # resolved through the store instead, since an id the payload names
+          # has to be proved to belong here.
+          def resource_permitted_attributes
+            [:reference, :notes, { metadata: {} }]
+          end
+
+          # A transfer's status transitions are its own actions, so `update`
+          # only ever edits the document — and its two ends are objects the
+          # store handed us, never ids the payload asserted.
+          def editable_attributes
+            attributes = permitted_params.to_h.symbolize_keys
+            attributes[:source_location] = stock_location_from(:source_location_id) if params.key?(:source_location_id)
+            if params.key?(:destination_location_id)
+              attributes[:destination_location] = stock_location_from(:destination_location_id)
             end
+            attributes
+          end
+
+          # The listing and the detail page both read a transfer's totals off
+          # its lines.
+          def scope_includes
+            [line_includes]
           end
         end
       end

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

@@ -5,6 +5,15 @@ module Spree
         class StoreController < Admin::BaseController
           scoped_resource :settings
 
+          # Reading the current store is shell data — the dashboard needs the
+          # name, logo, timezone, currency and locales to render anything at
+          # all, so every signed-in staff member can read it regardless of
+          # their permissions. Secret keys still need `read_settings`: a
+          # scope-limited integration has no business reading operational
+          # settings (support/notification emails, routing) it wasn't granted.
+          # Writing always requires `write_settings`.
+          skip_scope_check! only: :show, jwt_only: true
+
           # GET /api/v3/admin/store
           def show
             authorize! :show, current_store
@@ -22,8 +31,38 @@ module Spree
             end
           end
 
+          # GET /api/v3/admin/store/data_sources
+          #
+          # The pricing and inventory engines this store can choose between,
+          # with whether each is usable — a provider whose integration is not
+          # connected is listed but not selectable, so the dashboard can say
+          # why rather than hiding it.
+          def data_sources
+            authorize! :show, current_store
+
+            render json: {
+              data: {
+                pricing_providers: describe(Spree.pricing_providers),
+                inventory_providers: describe(Spree.inventory_providers),
+                failure_policies: Spree::ProviderFailurePolicy::VALUES
+              }
+            }
+          end
+
           private
 
+          def describe(provider_classes)
+            provider_classes.map do |provider_class|
+              {
+                key: provider_class.key,
+                name: provider_class.provider_name,
+                integration_class: provider_class.integration_class,
+                integration_type: provider_class.integration_class.presence&.safe_constantize&.api_type,
+                available: provider_class.available_for_store?(current_store)
+              }
+            end
+          end
+
           def serialize_store
             serializer_class.new(current_store, params: serializer_params).to_h
           end
@@ -42,7 +81,33 @@ module Spree
               :preferred_storefront_access,
               :preferred_storefront_url,
               :preferred_guest_checkout,
+              :preferred_company_field_enabled,
+              :preferred_address_requires_company,
+              :preferred_address_requires_phone,
+              :preferred_capture_method,
+              # @deprecated Superseded by preferred_capture_method; the model
+              #   maps them onto it. Removed in 6.1.
+              :preferred_auto_capture,
+              :preferred_auto_capture_on_dispatch,
+              :preferred_track_inventory_levels,
+              :preferred_stock_reservations_enabled,
+              :preferred_low_stock_threshold,
+              :preferred_tax_using_ship_address,
+              :preferred_track_price_history,
+              :preferred_show_products_without_price,
+              :preferred_disable_sku_validation,
               :preferred_order_routing_strategy,
+              :preferred_pricing_provider,
+              :preferred_inventory_provider,
+              :preferred_pricing_provider_failure_policy,
+              :preferred_inventory_provider_failure_policy,
+              :preferred_payout_provider,
+              :preferred_default_payouts_schedule_interval,
+              :preferred_default_minimum_payout_amount,
+              :preferred_document_number_format,
+              :preferred_order_number_prefix,
+              :preferred_order_number_suffix,
+              :preferred_order_number_sequence_start,
               :mail_from_address,
               :customer_support_email,
               :new_order_notifications_email,

data/app/controllers/spree/api/v3/admin/store_credits/events_controller.rb

@@ -0,0 +1,47 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module StoreCredits
+          # A store credit's ledger: how its balance got to where it is.
+          # Read-only — events are written by the credit itself as it is
+          # allocated, authorized, captured, voided and credited back.
+          class EventsController < ResourceController
+            scoped_resource :store_credits
+
+            protected
+
+            def model_class
+              Spree::StoreCreditEvent
+            end
+
+            def serializer_class
+              Spree.api.admin_store_credit_event_serializer
+            end
+
+            def parent_association
+              :store_credit_events
+            end
+
+            # A ledger reads newest first unless the caller asks otherwise.
+            def apply_collection_sort(collection)
+              return super if sort_param.present?
+
+              collection.reverse_chronological
+            end
+
+            # The parent credit is resolved through the store's own credits,
+            # so a credit belonging to another store 404s rather than leaking
+            # its ledger.
+            def set_parent
+              @parent = current_store.store_credits.
+                        accessible_by(current_ability, parent_ability_action).
+                        find_by_prefix_id!(params[:store_credit_id])
+              authorize_parent!(@parent)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Cross-customer view of what the store owes in prepaid balances.
+        #
+        # Read-only by design: a credit always belongs to one customer, and
+        # issuing, editing and deleting one stays nested under that customer
+        # (`Customers::StoreCreditsController`). This list is for seeing,
+        # filtering and auditing across all of them.
+        class StoreCreditsController < ResourceController
+          scoped_resource :store_credits
+
+          protected
+
+          def model_class
+            Spree::StoreCredit
+          end
+
+          def serializer_class
+            Spree.api.admin_store_credit_serializer
+          end
+
+          # Not `:originator`: the serializer encodes its id from the columns
+          # rather than loading the record, so preloading a polymorphic
+          # association would fire one query per originator kind on the page
+          # and discard every row it returned.
+          def collection_includes
+            [:customer, :created_by]
+          end
+
+          # Pagination metadata plus the outstanding balance, one row per
+          # currency, summed over the same filtered scope the page came from —
+          # so a customer filter answers "this customer's balance" and no
+          # filter answers "the store's liability".
+          def collection_meta(_collection)
+            super.merge(totals: currency_totals)
+          end
+
+          private
+
+          # @return [Array<Hash>] one entry per currency present in the
+          #   filtered scope, ordered by currency.
+          def currency_totals
+            base = scope
+            table = Spree::StoreCredit.arel_table
+            # Summed over the matching ids rather than over the joined rows: a
+            # filter reaching through a `has_many` would match a credit once per
+            # joined row and count its amount that many times, overstating what
+            # the store owes.
+            # Without the sort key: the subquery only supplies ids, so carrying
+            # the page's ORDER BY (and any join it needs) buys nothing.
+            filtered = base.ransack(ransack_params.except('s')).result.select(:id)
+            rows = base.where(id: filtered).
+                   reorder(nil).
+                   order(:currency).
+                   group(:currency).
+                   pluck(
+                     :currency,
+                     table[:amount].sum,
+                     table[:amount_used].sum,
+                     table[:amount_authorized].sum
+                   )
+
+            rows.map do |currency, amount, used, authorized|
+              # `SUM` answers an Integer on a whole-number total, and these
+              # totals render beside rows that serialize decimal strings — so
+              # "50" must not appear against their "50.0".
+              figures = {
+                amount: amount.to_d,
+                amount_used: used.to_d,
+                amount_authorized: authorized.to_d
+              }
+              figures[:amount_remaining] =
+                figures[:amount] - figures[:amount_used] - figures[:amount_authorized]
+
+              displays = figures.transform_keys { |name| :"display_#{name}" }.
+                         transform_values { |value| Spree::Money.new(value, currency: currency).to_s }
+
+              { currency: currency }.merge(figures.transform_values(&:to_s)).merge(displays)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The merchant's supplier address book. Buying goods in is its own
+        # permission resource: `write_stock` moves the stock you have, and must
+        # not also mean "may place orders with suppliers".
+        class SuppliersController < ResourceController
+          scoped_resource :purchasing
+
+          protected
+
+          def model_class
+            Spree::Supplier
+          end
+
+          def serializer_class
+            Spree.api.admin_supplier_serializer
+          end
+
+          def resource_permitted_attributes
+            [:name, :contact_name, :email, :phone, :notes,
+             :address1, :address2, :city, :state_name, :state_code,
+             :country_code, :postal_code, { metadata: {} }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -19,7 +19,7 @@ module Spree
             {
               'Spree::Product' => 'read_products',
               'Spree::Order' => 'read_orders',
-              Spree.user_class.to_s => 'read_customers'
+              Spree.customer_class.to_s => 'read_customers'
             }
           end
 
@@ -99,7 +99,7 @@ module Spree
           # Sourced from `Spree.taggable_types` (registered in
           # `Spree::Core::Engine`'s after_initialize block). Apps extend the
           # list in an initializer without overriding this controller:
-          #   Spree.taggable_types << 'MyApp::Vendor'
+          #   Spree.taggable_types << 'MyApp::Seller'
           def allowed_taggable_types
             Spree.taggable_types
           end

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

@@ -14,6 +14,10 @@ module Spree
           def serializer_class
             Spree.api.admin_tax_category_serializer
           end
+
+          def resource_permitted_attributes
+            [:name, :tax_code, :description, :is_default]
+          end
         end
       end
     end

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

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Which tax engines this installation can point a market at, and what
+        # each of them cannot do. Discovery rather than CRUD: providers are
+        # classes registered in code, not rows — so there is no serializer, and
+        # each class describes itself (`to_api_hash`), the same shape
+        # `/promotion_rules/types` and `/collection_rules/types` use.
+        #
+        # The capability list is the point — a merchant selling into US states
+        # needs to be told at configuration time that the built-in engine has no
+        # local-tax data, rather than discovering it from a tax bill.
+        class TaxProvidersController < BaseController
+          scoped_resource :settings
+
+          # GET /api/v3/admin/tax_providers
+          def index
+            render json: { data: Spree.tax_providers.map { |provider| provider.to_api_hash(current_store) } }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Tax rates are the whole configuration of the internal tax provider, so
+        # these endpoints are how the default engine is set up and inspected.
+        class TaxRatesController < ResourceController
+          scoped_resource :settings
+
+          protected
+
+          def model_class
+            Spree::TaxRate
+          end
+
+          def serializer_class
+            Spree.api.admin_tax_rate_serializer
+          end
+
+          def collection_includes
+            [:tax_category]
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :name, :amount, :amount_percentage, :included_in_price,
+                          :show_rate_in_label, :tax_category_id,
+                          :country_code, :state_code, metadata: {})
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TrackingCarriersController < ResourceController
+          scoped_resource :fulfillments
+
+          # GET /api/v3/admin/tracking_carriers
+          #
+          # The registered carriers a tracking number can be pinned to
+          # (Spree.tracking_carriers), so the carrier picker renders from the
+          # registry — extensions and host apps that add carriers appear
+          # without any client change.
+          def index
+            authorize! :update, Spree::Fulfillment
+
+            data = Spree.tracking_carriers.map do |slug, carrier|
+              { id: slug, name: carrier[:name] }
+            end
+
+            render json: { data: data.sort_by { |carrier| carrier[:name] } }
+          end
+
+          protected
+
+          def model_class
+            Spree::Fulfillment
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,18 +9,12 @@ module Spree
         class TranslatableResourcesController < Admin::BaseController
           scoped_resource :settings
 
-          # Public resource types with a dedicated nested read route
-          # (`…/:id/translations`). Other registered types are writable via the
-          # batch endpoint and readable inline (e.g. option values are returned
-          # as children of an option type), so the dashboard must not GET a
-          # standalone matrix for them. Keep in sync with the `:translatable`
-          # route concern mounts in `spree/api/config/routes.rb`.
-          READABLE_RESOURCE_TYPES = %w[product category option_type].freeze
-
           # GET /api/v3/admin/translatable_resources
           def index
+            readable = readable_resource_types
+
             data = Spree::Translations.registry.map do |entry|
-              entry.merge('readable' => READABLE_RESOURCE_TYPES.include?(entry['resource_type']))
+              entry.merge('readable' => readable.include?(entry['resource_type']))
             end
 
             render json: { data: data }
@@ -28,6 +22,40 @@ module Spree
 
           private
 
+          # Public resource types with a dedicated nested read route
+          # (`…/:id/translations`). Other registered types are writable via the
+          # batch endpoint and readable inline (e.g. option values are returned
+          # as children of an option type), so the dashboard must not GET a
+          # standalone matrix for them.
+          #
+          # Derived from the routes rather than restated as a constant: the
+          # `:translatable` concern is mounted per resource, and a hand-kept
+          # list silently drifts the moment one is added (it had, for
+          # collections and policies).
+          #
+          # @return [Set<String>]
+          # Walked once and held on the class: the route set is immutable after
+          # boot, and in development the reloader replaces the class itself, so
+          # a route change is picked up without a cache to invalidate.
+          def readable_resource_types
+            self.class.readable_resource_types
+          end
+
+          def self.readable_resource_types
+            @readable_resource_types ||=
+              Spree::Core::Engine.routes.routes.each_with_object(Set.new) do |route, types|
+                next unless route.defaults[:controller] == 'spree/api/v3/admin/translations'
+                next unless route.defaults[:action] == 'index'
+
+                # ".../admin/<segment>/:<segment>_id/translations" — the parent
+                # segment is what the registry token has to match.
+                segment = route.path.spec.to_s[%r{/([^/]+)/:\w+_id/translations}, 1]
+                next if segment.blank?
+
+                types << segment.singularize
+              end
+          end
+
           def action_kind
             'read'
           end