spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/spree/api/v3/seller/orders/labels_controller.rb

@@ -0,0 +1,55 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # Labels on a parcel the seller ships themselves.
+          #
+          # Recording, printing and deleting are shared with the operator's
+          # branch through the concern. Buying and refunding are not: they
+          # need the operator's carrier account, so a seller uploads a label
+          # bought elsewhere and prints it back.
+          #
+          # Rooted at the order fetched through `current_seller_orders`, so a
+          # fulfillment on somebody else's order reads as missing.
+          class LabelsController < BaseController
+            include Spree::Api::V3::Orders::ShippingLabelActions
+
+            before_action :set_resource, only: [:show, :download, :destroy]
+
+            # POST .../labels
+            #
+            # Records an uploaded label; a request without a file is refused,
+            # since purchase is the operator's.
+            def create
+              authorize!(:create, Spree::ShippingLabel)
+
+              if label_params[:file].blank?
+                return render_error(
+                  code: ERROR_CODES[:validation_error],
+                  message: Spree.t('shipping_labels.errors.file_required'),
+                  status: :unprocessable_content
+                )
+              end
+
+              record_uploaded_label
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_shipping_label_serializer
+            end
+
+            # The labels and consignments hang off the fulfillment, not the
+            # order, so the parent is narrowed one step past the base's.
+            def set_parent
+              super
+              @parent = @order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders/notes_controller.rb

@@ -0,0 +1,82 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # The notes on one of this seller's orders: the instructions the
+          # buyer left, and the seller's own working note.
+          #
+          # A marketplace basket splits into one order per seller, so the
+          # internal note on this row is the seller's alone — never the
+          # operator's note about the whole sale.
+          #
+          # Singular, because an order has one set of notes: reading and
+          # writing them is a resource rather than a verb on the order.
+          class NotesController < BaseController
+            # The notes are columns on the order, not a nested collection, so
+            # there is no member record to fetch.
+            skip_before_action :set_resource, raise: false
+
+            # GET /api/v3/seller/orders/:order_id/notes
+            def show
+              render json: serialize_resource(@order)
+            end
+
+            # PATCH /api/v3/seller/orders/:order_id/notes
+            #
+            # Send only the note that changes: an absent key leaves the other
+            # alone, while an empty string clears it.
+            def update
+              attributes = notes_params
+              return render_validation_error(missing_notes_errors) if attributes.empty?
+
+              if @order.update(attributes)
+                render json: serialize_resource(@order.reload)
+              else
+                render_validation_error(@order.errors)
+              end
+            end
+
+            protected
+
+            def model_class
+              Spree::Order
+            end
+
+            # The whole order, so a client refreshing a note gets the same
+            # shape it renders the page from.
+            def serializer_class
+              Spree.api.seller_order_serializer
+            end
+
+            def read_actions
+              %w[show]
+            end
+
+            private
+
+            # The rich-text note is written through `internal_note`, which the
+            # model sanitizes — the `_html` reader is its round-trip partner,
+            # never a write.
+            def notes_params
+              permitted = params.permit(:customer_note, :internal_note)
+
+              {}.tap do |attributes|
+                attributes[:customer_note] = permitted[:customer_note] if params.key?(:customer_note)
+                attributes[:internal_note] = permitted[:internal_note] if params.key?(:internal_note)
+              end
+            end
+
+            # A request naming neither note has asked for nothing; saying so
+            # beats a 200 that changed nothing.
+            def missing_notes_errors
+              ActiveModel::Errors.new(@order).tap do |errors|
+                errors.add(:base, :blank, message: 'customer_note or internal_note is required')
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders/returns_controller.rb

@@ -0,0 +1,44 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        module Orders
+          # Goods coming back on one of this seller's orders.
+          #
+          # Every status move reuses the operator's workflow, shared through
+          # the concern, so restocking, the tax credit, the refund and the
+          # ledger reversal all happen exactly as they do when the marketplace
+          # handles the return itself. What is here is what makes it the
+          # seller's: the order comes from `current_seller_orders`, so a
+          # return on somebody else's order reads as missing rather than
+          # denied, and the goods go back onto the seller's own shelf.
+          class ReturnsController < BaseController
+            include Spree::Api::V3::Orders::ReturnActions
+
+            before_action :set_resource, only: [:show, :approve, :receive, :refund, :cancel]
+
+            protected
+
+            def serializer_class
+              Spree.api.seller_return_serializer
+            end
+
+            def collection_includes
+              [:reason, :stock_location, { return_line_items: [:variant, :line_item] }]
+            end
+
+            private
+
+            # The seller's own shelves: returned goods go back into the stock
+            # the seller sells from, never a marketplace warehouse.
+            def stock_location_for_create
+              return nil if create_params[:stock_location_id].blank?
+
+              current_seller.stock_locations.find_by_prefix_id!(create_params[:stock_location_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/orders_controller.rb

@@ -0,0 +1,199 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # The orders placed with this seller.
+        #
+        # On a marketplace a basket spanning several sellers is split into one
+        # order each, so a seller's orders are their own rows — not a filtered
+        # view of somebody else's. The anchor roots `scope` in
+        # `current_seller.orders`, so an id belonging to another seller reads
+        # as missing rather than denied. Drafts are not this seller's either —
+        # neither an in-flight checkout nor the operator's working document —
+        # and are unreachable from every endpoint on this branch.
+        #
+        # Read, cancel, and correct an address. Fulfilling is the
+        # fulfillments endpoint under the order, and everything that settles
+        # money with the customer — approving, resuming, refunds, payments —
+        # stays with the operator, who owns that relationship.
+        class OrdersController < Seller::ResourceController
+          include Spree::Api::V3::OrderLock
+
+          scoped_resource :orders
+
+          before_action :set_resource, only: [:show, :cancel, :address]
+
+          # PATCH /api/v3/seller/orders/:id/cancel
+          #
+          # A seller withdrawing from an order they cannot fulfil, naming a
+          # reason from the marketplace's own list.
+          #
+          # `refund_payments` hands back what the buyer paid for these goods.
+          # A seller is merchant of record for their own child order, so the
+          # party who owes that money back is the party who took it — and on a
+          # split checkout the workflow settles through this order's own
+          # payment splits, capped at each share, so a seller can never reach
+          # a sibling's money.
+          #
+          # Deliberately takes no `refund_amount`: withdrawing from the whole
+          # order returns what that order was paid, and a seller choosing a
+          # partial figure is a return, which has its own endpoint and its own
+          # bound.
+          def cancel
+            with_order_lock do
+              result = Spree.order_cancel_workflow.call(
+                order: @resource,
+                canceler: try_spree_current_user,
+                reason: cancel_reason,
+                note: params[:cancel_note].presence,
+                refund_payments: params[:refund_payments].to_b,
+                notify_customer: params[:notify_customer].to_b
+              )
+
+              if result.success?
+                render json: serialize_resource(@resource.reload)
+              else
+                render_service_error(@resource.errors.presence || result.error)
+              end
+            end
+          end
+
+          # PATCH /api/v3/seller/orders/:id/address
+          #
+          # Corrects where the goods go or who the invoice names. The seller is
+          # merchant of record for their own child order, so a delivery address
+          # the buyer got wrong is theirs to fix.
+          #
+          # Its own action rather than a general PATCH: an order's terms are
+          # the marketplace's, and a write that took whatever the serializer
+          # permits would quietly grow into one a seller could reprice with.
+          def address
+            # Checked before the lock: an empty payload needs no serialization,
+            # and returning out of a locked block is worth avoiding.
+            return render_validation_error(missing_address_errors) if sent_addresses.blank?
+
+            # The merge reads the address it is about to replace, so it runs
+            # under the order's lock: two corrections landing together would
+            # each lay their fields over the same snapshot, and the later one
+            # would undo the earlier one's lines.
+            with_order_lock do
+              if @resource.update(address_params)
+                render json: serialize_resource(@resource.reload)
+              else
+                render_validation_error(@resource.errors)
+              end
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::Order
+          end
+
+          def serializer_class
+            Spree.api.seller_order_serializer
+          end
+
+          def read_actions
+            %w[index show]
+          end
+
+          # The same exclusion the nested endpoints get from
+          # `current_seller_orders`, applied over the inherited scope so its
+          # includes and preloading survive.
+          def scope
+            super.not_drafts
+          end
+
+          def collection_includes
+            [:line_items, :customer, :channel]
+          end
+
+          private
+
+          # Either address, as a correction rather than a replacement: the
+          # sent fields are laid over what the order already holds, so a
+          # request naming one line does not blank out the country and
+          # postcode beside it. The nested writer builds a fresh address row
+          # either way, which is what keeps a shared customer address book
+          # entry from being rewritten by an order-level fix.
+          def sent_addresses
+            @sent_addresses ||= params.permit(
+              shipping_address: address_permitted_keys,
+              billing_address: address_permitted_keys
+            ).slice(:shipping_address, :billing_address).reject { |_key, value| value.blank? }
+          end
+
+          def address_params
+            permitted = sent_addresses
+
+            {}.tap do |attributes|
+              if permitted[:shipping_address].present?
+                attributes[:ship_address_attributes] =
+                  merged_address(@resource.ship_address, permitted[:shipping_address])
+              end
+
+              if permitted[:billing_address].present?
+                attributes[:bill_address_attributes] =
+                  merged_address(@resource.bill_address, permitted[:billing_address])
+              end
+            end
+          end
+
+          def merged_address(address, sent)
+            current = address ? address.attributes.slice(*address_attribute_names) : {}
+            current.merge(sent.to_h)
+          end
+
+          # The permitted keys that are real columns; the rest are the writer
+          # aliases a client may send, which have no value to carry over.
+          def address_attribute_names
+            @address_attribute_names ||=
+              address_permitted_keys.map(&:to_s) & Spree::Address.column_names
+          end
+
+          def address_permitted_keys
+            [
+              :firstname, :lastname, :first_name, :last_name,
+              :address1, :address2, :city,
+              :country_code, :state_code,
+              :zipcode, :postal_code, :phone, :alternative_phone,
+              :state_name, :company, :label
+            ]
+          end
+
+          # A request naming neither address has asked for nothing; saying so
+          # beats a 200 that changed nothing.
+          def missing_address_errors
+            ActiveModel::Errors.new(@resource).tap do |errors|
+              errors.add(:base, :blank, message: 'shipping_address or billing_address is required')
+            end
+          end
+
+          # The reason a seller picked, resolved through the store's own list so
+          # a reason belonging to another store reads as missing. Optional —
+          # the workflow accepts a cancellation with none.
+          def cancel_reason
+            id = params[:cancel_reason_id].presence
+            return if id.nil?
+
+            current_store.order_cancellation_reasons.find_by_prefix_id!(id)
+          end
+
+          def set_resource
+            @resource = find_resource
+            @order = @resource # OrderLock reads this
+            authorize_resource!(@resource)
+          end
+
+          # Cancelling and correcting an address are both changes to the
+          # order, so they need the write key rather than a key of their own.
+          def authorize_resource!(resource = @resource, action = action_name.to_sym)
+            authorize!(%i[cancel address].include?(action) ? :update : action, resource)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/package_types_controller.rb

@@ -0,0 +1,100 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # What this seller packs their goods into: the boxes their parcels
+        # ship in, the cartons their products are packed into, the pallets a
+        # wholesale order leaves on (docs/plans/6.0-seller-package-types.md).
+        #
+        # The listing also carries the marketplace's own packaging, so a
+        # seller can pack into the operator's standard cartons rather than
+        # re-measuring them. Those rows are read-only: `find_resource` roots
+        # writes in the seller's own packaging, so a marketplace row's id is a
+        # 404 on every action but `show`.
+        #
+        # Marking a row default makes it the box this seller's parcels are
+        # quoted with — one default per owner, so it never displaces the
+        # marketplace's.
+        class PackageTypesController < Seller::ResourceController
+          scoped_resource :package_types
+
+          protected
+
+          def model_class
+            Spree::PackageType
+          end
+
+          def serializer_class
+            Spree.api.seller_package_type_serializer
+          end
+
+          # Reading shows the seller's own packaging plus the marketplace's —
+          # the same set their variants may reference, so a carton picker can
+          # ask "what can I pack into" rather than only "what have I
+          # measured".
+          #
+          # `owner=mine` narrows it to the seller's own rows. The packaging
+          # settings page asks for that, because a list mixing both owners
+          # reads as "packaging is configured" while the seller has recorded
+          # nothing — the shipping-box requirement then looks broken rather
+          # than outstanding. Not a Ransack predicate: `available_to_seller`
+          # composes with `.or()`, so a filter on `seller_id` widens back out
+          # to the whole condition instead of narrowing it.
+          def scope
+            rows = current_store.package_types
+            rows = params[:owner] == 'mine' ? rows.for_seller(current_seller) : rows.available_to_seller(current_seller)
+            rows.preload_associations_lazily
+          end
+
+          # Writes root in the seller's own rows, so the marketplace's
+          # packaging cannot be edited or deleted through this branch.
+          def resource_scope
+            current_seller.package_types
+          end
+
+          def find_resource
+            action_name == 'show' ? super : resource_scope.find_by_prefix_id!(params[:id])
+          end
+
+          # No DISTINCT, so the owner ordering below is legal on PostgreSQL:
+          # it rejects an ORDER BY expression that is not in the select list
+          # of a SELECT DISTINCT, and `available_to_seller` makes the query
+          # distinct through `.or()`. Nothing here needs it — one table, no
+          # joins, so no row can appear twice.
+          def collection_distinct?
+            false
+          end
+
+          # The seller's own rows before the marketplace's, then by name.
+          #
+          # This list holds two owners' packaging, so it has roughly twice as
+          # much to fit under the 100-row page limit as the operator's does.
+          # Ordering here rather than in the client is what makes the limit
+          # cut the shared rows instead of the seller's own measurements —
+          # the page is taken before anything client-side can reorder it.
+          # Ransack cannot express it: it drops the direction on `seller_id`,
+          # and NULLs sort first ascending.
+          #
+          # Skipped when the caller asked for its own order.
+          def apply_collection_sort(collection)
+            return collection if params[:sort].present?
+
+            collection.order(
+              Arel.sql('CASE WHEN seller_id IS NULL THEN 1 ELSE 0 END'),
+              Spree::PackageType.arel_table[:name].asc
+            )
+          end
+
+          # The same set the operator's controller permits — a seller measures
+          # their own packaging, so every field on the shared form is theirs
+          # to set. `seller_id` is deliberately absent: ownership comes from
+          # the authenticated seller, never the payload.
+          def resource_permitted_attributes
+            [:name, :kind, :length, :width, :height, :dimensions_unit,
+             :weight, :max_weight, :weight_unit, :default, { metadata: {} }]
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/password_resets_controller.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Password reset for the marketplace seller panel.
+        #
+        # Parallel to the admin controller rather than a subclass of it, per
+        # Decision 10: what differs is the audience it issues and the panel the
+        # emailed link opens, and both are the point. A seller resetting their
+        # password must end up with a seller session on the seller panel, never
+        # an admin one on the dashboard.
+        class PasswordResetsController < Spree::Api::V3::BaseController
+          include Spree::Api::V3::Seller::AuthCookies
+          include Spree::Api::V3::JwtAuthentication
+
+          # No `skip_scope_check!`: this extends the plain v3 base, which has
+          # no authentication or scope gate to lift. The emailed token is the
+          # only credential, exactly as on the admin twin.
+          rate_limit to: Spree::Api::Config[:rate_limit_password_reset],
+                     within: Spree::Api::Config[:rate_limit_window].seconds,
+                     store: Rails.cache,
+                     with: RATE_LIMIT_RESPONSE
+
+          # POST /api/v3/seller/auth/password_resets
+          def create
+            user = Spree.admin_user_class.find_by(email: params[:email])
+
+            # Staff share this user class, so a match is not enough: a store
+            # admin who runs no seller has no panel to be sent to, and mailing
+            # them a seller reset link would be an invitation to a session they
+            # cannot hold.
+            if user&.seller_member?
+              user.publish_event('seller_user.password_reset_requested', event_payload(user))
+            end
+
+            # Always 202, whether or not anything matched — this endpoint must
+            # not become a way to discover which addresses exist.
+            render json: { message: Spree.t(:password_reset_requested, scope: :api) }, status: :accepted
+          end
+
+          # PATCH /api/v3/seller/auth/password_resets/:id
+          def update
+            user = Spree.admin_user_class.find_by_password_reset_token(params[:id])
+
+            # Membership is re-checked here rather than trusted from the token:
+            # it can be revoked between the email being sent and the link being
+            # opened, and signing in is what the success path does.
+            return render_token_invalid unless user&.seller_member?
+
+            unless user.update(password: params[:password], password_confirmation: params[:password_confirmation])
+              return render_errors(user.errors)
+            end
+
+            user.publish_event('seller_user.password_reset')
+
+            # A reset must kill every existing session — a stolen refresh token
+            # must not survive the victim resetting their password. Revoked
+            # across every audience, since the password is what they all rest
+            # on. Then mint the fresh one for this browser.
+            Spree::RefreshToken.revoke_all_for(user)
+            set_refresh_cookie(
+              Spree::RefreshToken.create_for(
+                user,
+                audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER,
+                request_env: request_env_for_token
+              )
+            )
+
+            render json: auth_response(user)
+          end
+
+          private
+
+          # A token that no longer belongs to a seller is reported exactly as an
+          # expired or forged one: the caller is unauthenticated either way, and
+          # distinguishing them would leak that the address is a real account.
+          def render_token_invalid
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:password_reset_token_invalid],
+              message: Spree.t(:password_reset_token_invalid, scope: :api),
+              status: :unprocessable_content
+            )
+          end
+
+          # The store is carried on the event so the mailer can resolve the
+          # right panel origin and locale without a request to read them from.
+          def event_payload(user)
+            store = seller_store(user)
+            payload = {
+              reset_token: user.generate_token_for(:password_reset),
+              email: user.email,
+              store_id: store&.prefixed_id
+            }
+            redirect_url = validated_redirect_url(store)
+            payload[:redirect_url] = redirect_url if redirect_url.present?
+            payload
+          end
+
+          # Which store's panel to send them to.
+          #
+          # Derived from the seller, never from `current_store`: this endpoint
+          # is unauthenticated, so the request carries no seller header and
+          # `current_store` is simply the default store — which on a
+          # multi-store install is the wrong marketplace entirely. The seller
+          # branch's rule is that the store follows the seller.
+          def seller_store(user)
+            user.sellers.first&.store
+          end
+
+          # Honoured only when it points somewhere the seller's own store has
+          # vouched for. An unvalidated value would let anyone with the reset
+          # form turn this endpoint into a token-exfiltration channel, and
+          # judging it against the default store's allowlist would let one
+          # marketplace's origins approve a link mailed to another's seller.
+          # Dropping it leaves the mailer to resolve the panel origin itself.
+          def validated_redirect_url(store)
+            url = params[:redirect_url].presence
+            return unless url && store
+            return unless store.allowed_origins.exists? && store.allowed_origin?(url)
+
+            url
+          end
+
+          # Same shape as the login response, so the panel can sign them
+          # straight in rather than bouncing them to a login form.
+          def auth_response(user)
+            {
+              token: generate_jwt(user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER),
+              user: Spree.api.seller_team_member_serializer.new(
+                user, params: { store: seller_store(user) }
+              ).to_h,
+              sellers: serialized_sellers(user)
+            }
+          end
+
+          # The panel needs these to choose an X-Spree-Seller-Id before it can
+          # make any other request.
+          def serialized_sellers(user)
+            user.sellers.map { |seller| { id: seller.prefixed_id, name: seller.name, status: seller.status } }
+          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/seller/payouts_controller.rb

@@ -0,0 +1,47 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # Settlements to this seller — what has been sent, and what is owed.
+        #
+        # Read-only: a payout is created by the sweep and confirmed by the
+        # provider or the operator, never by the seller.
+        class PayoutsController < Seller::ResourceController
+          scoped_resource :seller_earnings
+
+          protected
+
+          def model_class
+            Spree::SellerPayout
+          end
+
+          def serializer_class
+            Spree.api.seller_payout_serializer
+          end
+
+          def scope
+            super.order(created_at: :desc)
+          end
+
+          # See TransfersController: the model class is the operator's subject.
+          def authorize_resource!(_resource = @resource, action = action_name.to_sym)
+            authorize!(action, :seller_earnings)
+          end
+
+          # One grouped count for the page rather than a query per settlement
+          # (the sweep claims transfers with `update_all`, so no counter column
+          # could stay right). A single payout read asks for its own.
+          def serializer_params
+            return super unless action_name == 'index'
+
+            super.merge(transfer_counts: transfer_counts)
+          end
+
+          def transfer_counts
+            @transfer_counts ||= Spree::SellerTransfer.where(payout_id: collection.map(&:id)).group(:payout_id).count
+          end
+        end
+      end
+    end
+  end
+end