spree_cm_commissioner 2.13.5 → 2.13.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9473bef71175dc42b69c1959ac56827e1ca0ef2b6c13205ed2c83793e678a21f
-  data.tar.gz: 314a9fbe0dbc6fe925f435b3eaeef9d737689f81fb7d95e631bbcf10a2e3e8bf
+  metadata.gz: c83a53b69842100120ae6f6edea538c4a7335fc9859e52765f4be45ad2506b0c
+  data.tar.gz: 61cd2bea3a4a011a385ad636c6f3330bc44e04085eb39ea22c64c96f86c59978
 SHA512:
-  metadata.gz: fa509b4c09684a80915bca9927228aa41de193821593d00f84da4cd1bb2f2b0d5034146d9c52e4dec654ad57092ac87273771be63841b66546cb1a1b63e0077d
-  data.tar.gz: f04d83d04ce10ebb051931a0bde85c690e279ac08d18e90b3be9e2f14721992c9e04096ef1eab051e1dde8b81ba6ea6aef356ca77422ac27ecb05aebf7f2e5c8
+  metadata.gz: 18012dec394174123a5fefcb459c369aab56bf075cabb068e695ab42eac92c1f487468047d6201bee6dc2f1f8730147260ec7d4b4dbfa1b4c0f5c98c31720508
+  data.tar.gz: 5dae3a462226fe008f4c17d43231d315d45e24a415fd07fe8c564f61694821ba70e037b311f8f653766df763a009e00b2ccf0d8f7bbbaf712e858a50b0cbdf43

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.13.5)
+    spree_cm_commissioner (2.13.7)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/controllers/spree/admin/base_controller_decorator.rb

@@ -1,6 +1,10 @@
 module Spree
   module Admin
     module BaseControllerDecorator
+      def self.prepended(base)
+        base.before_action :set_prepaid_current_actor
+      end
+
       # even db in read only mode, authorizor still need to run Warden callbacks which will write to db
       # this include update tracked fields such as sign_in_count, last_sign_in_at, etc.
       def authorize!(*args)
@@ -40,6 +44,16 @@ module Spree
 
         redirect_back fallback_location: admin_root_path
       end
+
+      private
+
+      # See SpreeCmCommissioner::Current#actor -- lets StoreCreditEventDecorator's after_create
+      # mirror attribute an admin-triggered authorize/capture/void/credit event (refunds, voids)
+      # to whoever is signed in, without threading current_user through Spree core's own
+      # Payment/Refund/StoreCredit call chain.
+      def set_prepaid_current_actor
+        SpreeCmCommissioner::Current.actor = try_spree_current_user
+      end
     end
   end
 end

data/app/controllers/spree/admin/customer_notifications_controller.rb

@@ -2,7 +2,22 @@ module Spree
   module Admin
     class CustomerNotificationsController < Spree::Admin::ResourceController
       def index
-        @notifications = SpreeCmCommissioner::CustomerNotification.all
+        @search = model_class.ransack(params[:q])
+        @search.sorts = 'created_at desc' if @search.sorts.empty?
+        @notifications = @search.result.page(params[:page]).per(params[:per_page] || 25)
+      end
+
+      # POST /admin/customer_notifications/:id/clone
+      def clone
+        result = SpreeCmCommissioner::CustomerNotifications::Clone.call(customer_notification: @object)
+
+        if result.success?
+          flash[:success] = Spree.t(:customer_notification_cloned)
+          redirect_to edit_admin_customer_notification_url(result.value)
+        else
+          flash[:error] = Spree.t(:customer_notification_not_cloned, error: result.error.to_s)
+          redirect_to admin_customer_notifications_url
+        end
       end
 
       def model_class

data/app/controllers/spree/admin/prepaid_transactions_controller.rb

@@ -0,0 +1,69 @@
+module Spree
+  module Admin
+    # Two read-only views over the prepaid ledger:
+    # - #index: platform-wide filterable browse (GET /admin/store_credit/transactions).
+    # - #show: a single ledger row's full detail (GET /admin/store_credit/transactions/:id),
+    #   reached from both #index's row links and the per-user store_credits Transactions tab.
+    #   Not nested under a user/store_credit -- PrepaidTransaction has a global id, and one
+    #   detail page reached from two different listings is simpler than two near-identical ones.
+    #   Currency, balance, admin, and reason/freeze metadata live here rather than cluttering
+    #   either listing table.
+    class PrepaidTransactionsController < Spree::Admin::BaseController
+      TRANSACTIONS_PER_PAGE = 25
+
+      before_action :load_transaction, only: :show
+
+      # GET /admin/store_credit/transactions -- the admin/store_credit dashboard's own
+      # platform-wide ledger browse (see Spree::Admin::StoreCreditAdminController's other tabs and
+      # store_credit_admin/_tabs.html.erb), but its own route/controller rather than a #show?
+      # tab=transactions query param, so filters/pagination live in a real URL.
+      def index
+        @current_tab = 'transactions'
+        @tenants = SpreeCmCommissioner::Tenant.order(:name)
+        @current_tenant_id = params[:tenant_id].presence&.to_i
+        @store = Spree::Store.default
+        build_transactions_search
+      end
+
+      def show; end
+
+      private
+
+      def load_transaction
+        @transaction = SpreeCmCommissioner::PrepaidTransaction.find(params[:id])
+        @user = @transaction.user
+        @store_credit = @transaction.store_credit
+        @reversed = SpreeCmCommissioner::PrepaidTransaction
+                    .exists?(user: @user, transaction_type: 'reverse_top_up', idempotency_key: "admin_reverse:#{@transaction.id}")
+        @return_to = safe_return_to
+      end
+
+      # So the back link on the detail page returns to the exact filtered/paginated Transactions
+      # tab state the admin came from, not a bare reset to page 1 -- only same-admin-namespace
+      # paths are honored, since this is attacker-controllable input (an admin could be tricked
+      # into following a crafted link) and open-redirecting out of /admin would be a phishing vector.
+      def safe_return_to
+        candidate = params[:return_to]
+        candidate if candidate.present? && candidate.start_with?('/admin/')
+      end
+
+      # Individual ledger row search/browse -- scoped to whichever tenant the dashboard's own
+      # tenant selector has picked (tenant_id: nil => platform-issued, same convention as
+      # StoreCreditOverviewQuery), further filtered via Ransack (q[user_email_cont],
+      # q[currency_eq], q[transaction_type_eq], q[created_at_gteq]/[created_at_lteq], ...).
+      def build_transactions_search
+        params[:q] = {} if params[:q].blank?
+        @transactions_search = SpreeCmCommissioner::PrepaidTransaction.where(tenant_id: @current_tenant_id).ransack(params[:q])
+        @transactions = @transactions_search.result
+                                            .includes(:user, :order, :tenant, :admin, :store_credit)
+                                            .order(created_at: :desc)
+                                            .page(params[:page])
+                                            .per(TRANSACTIONS_PER_PAGE)
+      end
+
+      def model_class
+        SpreeCmCommissioner::PrepaidTransaction
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/private_sales_controller.rb

@@ -14,6 +14,7 @@ module Spree
       # partial reads these ivars — without this a rejected save is a 500 instead of a form.
       before_action :load_stock_rows, only: %i[edit update]
       before_action :load_assignable_roles, only: %i[new create edit update]
+      before_action :load_offline_product_ids, only: %i[new create edit update]
 
       # GET /admin/private_sales
       def index
@@ -45,6 +46,11 @@ module Spree
         @assignable_roles = Spree::Role.non_vendor.order(:name)
       end
 
+      # The product search only returns `name`, so the form labels offline products from this list.
+      def load_offline_product_ids
+        @offline_product_ids = Spree::Product.where(offline: true).pluck(:id)
+      end
+
       def location_after_save
         edit_admin_private_sale_path(@private_sale)
       end

data/app/controllers/spree/admin/product_commissions_controller.rb

@@ -42,7 +42,8 @@ module Spree
 
       def commission_for(product)
         commission_rate = product.commission_rate || product.vendor&.commission_rate || 0
-        product.price * commission_rate / 100
+        # A product can have no price in the store currency yet (e.g. a freshly created ticket).
+        (product.price || 0) * commission_rate / 100
       end
 
       # override

data/app/controllers/spree/admin/reschedule_policies_controller.rb

@@ -0,0 +1,148 @@
+module Spree
+  module Admin
+    # Platform-admin management of reschedule policies, built like the Payment
+    # Methods page: a scoped tab bar (Store / Vendors / Tenants) over the shared
+    # ReschedulePolicy table.
+    #
+    # - Store tab (default): platform policies (vendor_id nil). Full CRUD.
+    # - Vendors tab: every vendor policy, read-only.
+    # - Tenants tab: vendor policies whose vendor belongs to a tenant, read-only.
+    #
+    # Create/Update delegate to the existing ReschedulePolicies services (with
+    # vendor: nil), which own calculator building, typed rules, and the
+    # one-default-per-scope rule.
+    class ReschedulePoliciesController < BaseController
+      # Only these tabs switch the page into read-only vendor/tenant mode; any
+      # other value falls back to the store tab, in the controller and the view
+      # alike (see `current_tab`).
+      TABS = %w[vendors tenants].freeze
+
+      before_action :load_policy, only: %i[edit update destroy set_default]
+
+      helper_method :current_tab
+
+      def index
+        authorize! :manage, SpreeCmCommissioner::ReschedulePolicy
+
+        @search = collection.ransack(params[:q])
+        @reschedule_policies = @search.result
+                                      .order(default: :desc, name: :asc)
+                                      .page(params[:page])
+                                      .per(params[:per_page] || 20)
+      end
+
+      def new
+        authorize! :manage, SpreeCmCommissioner::ReschedulePolicy
+        @reschedule_policy = SpreeCmCommissioner::ReschedulePolicy.new(status: :active)
+        # Seed a calculator so the fee fields render; the form/services can swap it.
+        @reschedule_policy.calculator_type = 'Spree::Calculator::FlatRate'
+      end
+
+      def create
+        authorize! :manage, SpreeCmCommissioner::ReschedulePolicy
+
+        result = SpreeCmCommissioner::ReschedulePolicies::Create.call(vendor: nil, options: policy_params)
+        if result.success?
+          flash[:success] = Spree.t(:successfully_created, resource: reschedule_policy_name)
+          redirect_to admin_reschedule_policies_path
+        else
+          @reschedule_policy = result.value || SpreeCmCommissioner::ReschedulePolicy.new
+          flash.now[:error] = result.error&.value
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def update
+        result = SpreeCmCommissioner::ReschedulePolicies::Update.call(policy: @reschedule_policy, options: policy_params)
+        if result.success?
+          flash[:success] = Spree.t(:successfully_updated, resource: reschedule_policy_name)
+          redirect_to admin_reschedule_policies_path
+        else
+          flash.now[:error] = result.error&.value
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        if @reschedule_policy.active?
+          # The reschedule flow resolves the store policy from the *active*
+          # store policies, so deleting this one would reject every reschedule.
+          flash[:error] = Spree.t('admin.reschedule_policies.cannot_delete_active')
+        elsif @reschedule_policy.destroy
+          flash[:success] = Spree.t(:successfully_removed, resource: reschedule_policy_name)
+        else
+          flash[:error] = @reschedule_policy.errors.full_messages.to_sentence
+        end
+
+        redirect_to admin_reschedule_policies_path
+      end
+
+      # Promote this store policy to the active default; the Update service
+      # demotes the current default in the same scope first.
+      def set_default
+        result = SpreeCmCommissioner::ReschedulePolicies::Update.call(
+          policy: @reschedule_policy, options: { default: true, status: :active }
+        )
+        flash[:success] = Spree.t(:successfully_updated, resource: reschedule_policy_name) if result.success?
+        flash[:error] = result.error&.value if result.failure?
+        redirect_to admin_reschedule_policies_path
+      end
+
+      private
+
+      # nil for the store tab (including unknown/blank `tab` values), otherwise
+      # the recognised tab name.
+      def current_tab
+        params[:tab] if TABS.include?(params[:tab])
+      end
+
+      # All statuses are shown (draft/inactive included) so the admin can manage
+      # them, so the raw vendor_id/tenant_id filters are used, not the
+      # active-only `store_policies` / `vendor_policies` scopes.
+      def collection
+        base = SpreeCmCommissioner::ReschedulePolicy
+        case current_tab
+        when 'vendors'
+          base.where.not(vendor_id: nil).includes(:vendor)
+        when 'tenants'
+          base.where.not(vendor_id: nil).where.not(tenant_id: nil).includes(vendor: :tenant)
+        else
+          base.where(vendor_id: nil)
+        end
+      end
+
+      def load_policy
+        authorize! :manage, SpreeCmCommissioner::ReschedulePolicy
+        # Edits apply to store policies only; vendor/tenant policies are read-only here.
+        @reschedule_policy = SpreeCmCommissioner::ReschedulePolicy.where(vendor_id: nil).find(params[:id])
+      end
+
+      # Store policies only carry a fee calculator; the typed reschedule rules
+      # (cutoff, max-per-booking, vendor approval, ...) belong to vendor policies
+      # and are managed elsewhere, so they are not collected here.
+      def policy_params
+        params.require(:spree_cm_commissioner_reschedule_policy).permit(
+          :name,
+          :description,
+          :status,
+          :default,
+          :calculator_type,
+          calculator_attributes: calculator_attribute_keys
+        )
+      end
+
+      # Only the preferences of the selected (whitelisted) calculator subclass
+      # are permitted, so preferences never land on the wrong calculator type.
+      def calculator_attribute_keys
+        type = params.dig(:spree_cm_commissioner_reschedule_policy, :calculator_type)
+        return [] unless %w[Spree::Calculator::FlatRate Spree::Calculator::PercentOnLineItem].include?(type)
+
+        type.constantize.new.defined_preferences.map { |preference| "preferred_#{preference}" }
+      end
+
+      def reschedule_policy_name
+        SpreeCmCommissioner::ReschedulePolicy.model_name.human
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/reschedule_requests_controller.rb

@@ -0,0 +1,82 @@
+module Spree
+  module Admin
+    class RescheduleRequestsController < Spree::Admin::ResourceController
+      helper Spree::Admin::RescheduleRequestsHelper
+
+      def index
+        @search = model_class.includes(:order, :user, :vendor, :vendor_policy).ransack(params[:q])
+        @reschedule_requests = @search.result
+                                      .order(created_at: :desc)
+                                      .page(params[:page])
+                                      .per(params[:per_page] || Spree::Backend::Config[:admin_orders_per_page])
+      end
+
+      def show
+        @reschedule_request = load_request
+      end
+
+      def state_changes
+        @reschedule_request = model_class.find(params[:id])
+        @state_changes = @reschedule_request.state_changes.includes(:user).order(created_at: :desc)
+      end
+
+      def approve
+        run_service(
+          SpreeCmCommissioner::RescheduleRequests::Vendors::Approve,
+          approved_by: try_spree_current_user,
+          success_key: 'approved'
+        )
+      end
+
+      def reject
+        run_service(
+          SpreeCmCommissioner::RescheduleRequests::Vendors::Reject,
+          rejected_by: try_spree_current_user,
+          success_key: 'rejected'
+        )
+      end
+
+      def cancel
+        run_service(
+          SpreeCmCommissioner::RescheduleRequests::Cancel,
+          cancelled_by: try_spree_current_user,
+          reason: params[:cancellation_reason].presence,
+          success_key: 'cancelled'
+        )
+      end
+
+      private
+
+      # Each service takes the acting admin so audit rows record who acted
+      # rather than the request's customer.
+      def run_service(service, success_key:, **)
+        @reschedule_request = model_class.find(params[:id])
+
+        result = service.call(reschedule_request: @reschedule_request, **)
+        if result.success?
+          flash[:success] = t("spree.admin.reschedule_requests.#{success_key}")
+        else
+          flash[:error] = result.error&.value
+        end
+
+        redirect_to admin_reschedule_request_path(@reschedule_request)
+      end
+
+      def load_request
+        model_class.includes(
+          :order, :user, :vendor, :tenant, :vendor_policy, :store_policy,
+          previous_request_snapshots: %i[variant line_item],
+          new_request_snapshots: %i[variant line_item]
+        ).find(params[:id])
+      end
+
+      def model_class
+        SpreeCmCommissioner::RescheduleRequest
+      end
+
+      def object_name
+        'spree_cm_commissioner_reschedule_request'
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/store_credit_admin_controller.rb

@@ -0,0 +1,122 @@
+module Spree
+  module Admin
+    class StoreCreditAdminController < Spree::Admin::BaseController
+      TABS = %w[overview frozen_store_credits settings].freeze
+
+      def show
+        @current_tab = TABS.include?(params[:tab]) ? params[:tab] : 'overview'
+        @tenants = SpreeCmCommissioner::Tenant.order(:name)
+        @current_tenant_id = params[:tenant_id].presence&.to_i
+        store_credit_overview = SpreeCmCommissioner::StoreCreditOverviewQuery.new(issuer_tenant_id: @current_tenant_id)
+        @summary = store_credit_overview.call
+        @frozen_store_credits = store_credit_overview.frozen_store_credits
+        @config = SpreeCmCommissioner::Configuration.new
+        @store = Spree::Store.default
+      end
+
+      # Covers every prepaid_* Configuration preference editable from the Settings tab -- the
+      # currency rate table (keyed by Spree::Store.default#supported_currency_codes -- edit the
+      # currency list itself on the store's own admin settings page, not here) and the
+      # fraud/velocity limits (Configuration's comment on prepaid_max_topups_per_hour and
+      # friends). One form/action since nothing here is ever meaningfully saved independently.
+      SETTINGS_KEYS = %i[
+        prepaid_currency_rates prepaid_topup_min_amount prepaid_topup_max_amount
+        prepaid_max_topups_per_hour prepaid_max_topup_count_daily prepaid_daily_topup_limit
+        prepaid_max_balance
+      ].freeze
+
+      def update_settings
+        config = SpreeCmCommissioner::Configuration.new
+        new_values = {
+          prepaid_currency_rates: permitted_currency_rates(config),
+          prepaid_topup_min_amount: params[:prepaid_topup_min_amount].to_d,
+          prepaid_topup_max_amount: params[:prepaid_topup_max_amount].to_d,
+          prepaid_max_topups_per_hour: params[:prepaid_max_topups_per_hour].to_i,
+          prepaid_max_topup_count_daily: params[:prepaid_max_topup_count_daily].to_i,
+          prepaid_daily_topup_limit: params[:prepaid_daily_topup_limit].to_d,
+          prepaid_max_balance: params[:prepaid_max_balance].to_d
+        }
+
+        error = invalid_settings_reason(new_values)
+        if error
+          flash[:error] = error
+          return redirect_to admin_store_credit_path(tab: 'settings')
+        end
+
+        old_values = SETTINGS_KEYS.index_with { |key| config[key] }
+        SETTINGS_KEYS.each { |key| config[key] = new_values[key] }
+
+        log_settings_change(old_values, new_values)
+
+        flash[:success] = I18n.t('spree_cm_commissioner.store_credit_admin.settings_updated')
+        redirect_to admin_store_credit_path(tab: 'settings')
+      end
+
+      def run_reconciliation
+        report = SpreeCmCommissioner::PrepaidReconciliationService.run_daily
+
+        if report.drift_count.zero?
+          flash[:success] = I18n.t('spree_cm_commissioner.store_credit_admin.reconciliation_success', checked_count: report.checked_count)
+        else
+          flash[:error] = I18n.t(
+            'spree_cm_commissioner.store_credit_admin.reconciliation_drift',
+            checked_count: report.checked_count, drift_count: report.drift_count
+          )
+        end
+
+        redirect_back fallback_location: admin_store_credit_path
+      end
+
+      private
+
+      # Keyed by the store's current supported-currencies list, so a dropped currency's rate
+      # doesn't linger and a new one gets an explicit (fallback 1.0) entry.
+      def permitted_currency_rates(config)
+        currency_codes = Spree::Store.default.supported_currency_codes
+        submitted = params[:prepaid_currency_rates]
+        submitted = submitted.is_a?(ActionController::Parameters) ? submitted.permit(*currency_codes) : {}
+
+        currency_codes.index_with do |currency|
+          submitted[currency].presence&.to_f || config.prepaid_currency_rates[currency] || 1.0
+        end
+      end
+
+      # These preferences are the only fraud/velocity ceiling enforced on store credit money-in
+      # (Prepaid::CheckTopUpLimits, Prepaid::TopUp) -- a negative value would be silently treated
+      # as "no limit" by comparisons like `amount > limit`, and a non-positive currency rate would
+      # corrupt every cross-currency conversion built on it.
+      def invalid_settings_reason(values)
+        %i[
+          prepaid_topup_min_amount prepaid_topup_max_amount prepaid_max_topups_per_hour
+          prepaid_max_topup_count_daily prepaid_daily_topup_limit prepaid_max_balance
+        ].each do |key|
+          return "#{key} can't be negative" if values[key].negative?
+        end
+
+        if values[:prepaid_topup_min_amount] > values[:prepaid_topup_max_amount] && values[:prepaid_topup_max_amount].positive?
+          return 'prepaid_topup_min_amount cannot exceed prepaid_topup_max_amount'
+        end
+
+        values[:prepaid_currency_rates].each do |currency, rate|
+          return "currency rate for #{currency} must be positive" unless rate.positive?
+        end
+
+        nil
+      end
+
+      # No dedicated audit-log model for Configuration preferences (they're key/value, not an
+      # ActiveRecord row PaperTrail can version) -- structured log line is the same pattern
+      # #run_reconciliation already uses ("-- see logs") for admin-triggered store credit actions.
+      def log_settings_change(old_values, new_values)
+        changed = SETTINGS_KEYS.each_with_object({}) do |key, diff|
+          diff[key] = { from: old_values[key], to: new_values[key] } if old_values[key] != new_values[key]
+        end
+        return if changed.empty?
+
+        Rails.logger.info(
+          "[store_credit_settings_change] admin_id=#{try_spree_current_user&.id} changes=#{changed}"
+        )
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/ticket_transfer_rules_controller.rb

@@ -1,6 +1,8 @@
 module Spree
   module Admin
     class TicketTransferRulesController < Spree::Admin::ResourceController
+      before_action :load_offline_product_ids, only: %i[new edit create update]
+
       def index
         @search = model_class.ransack(params[:q])
         @ticket_transfer_rules = @search.result
@@ -11,6 +13,11 @@ module Spree
 
       private
 
+      # The scope-target search only returns `name`, so the form labels offline products from this list.
+      def load_offline_product_ids
+        @offline_product_ids = Spree::Product.where(offline: true).pluck(:id)
+      end
+
       def model_class
         SpreeCmCommissioner::TicketTransferRule
       end

data/app/controllers/spree/api/v2/platform/store_credits_controller_decorator.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V2
+      module Platform
+        # Platform::ResourceController#authorize_spree_user only runs CanCan checks when the
+        # request carries a user OAuth token (`spree_current_user.present?`); a bare app
+        # (client_credentials) token skips it entirely by design, and the base permitted-params
+        # list falls back to every column on the model (`json_api_permitted_attributes`). That
+        # would let any app token holding the generic `:admin` doorkeeper scope rewrite
+        # `amount`/`amount_used`/`user_id`/`issuer_tenant_id` etc. directly -- bypassing the
+        # prepaid ledger (cm_prepaid_transactions) and the AdminCredit/ReverseTopUp/Freeze
+        # services that exist to keep it consistent, with no record of who changed what.
+        #
+        # Nothing in this monorepo (docs, internal services, cm-market-app/client) calls this
+        # endpoint -- it's just Spree's default auto-generated CRUD from `resources :store_credits`
+        # in spree_api's routes, not something built for a known consumer. Rather than maintain a
+        # safe-fields allowlist forever (every future Spree::StoreCredit column is a fresh chance
+        # to leak through it), the endpoint is disabled outright: every action 404s, same as an
+        # unrouted path would. The route itself still exists (routes.rb lives in gems/spree_api,
+        # which this repo's decorator-only rule forbids editing directly), so this is done from
+        # our own extension gem instead.
+        module StoreCreditsControllerDecorator
+          def self.prepended(base)
+            # prepend_before_action, not before_action -- runs ahead of the base controller's own
+            # doorkeeper_authorize!/authorize_spree_user checks, so this 404s unconditionally
+            # (same as an unrouted path would) rather than only after an auth check passes.
+            base.prepend_before_action { head :not_found }
+          end
+        end
+      end
+    end
+  end
+end
+
+Spree::Api::V2::Platform::StoreCreditsController.prepend Spree::Api::V2::Platform::StoreCreditsControllerDecorator

data/app/controllers/spree/api/v2/storefront/account/prepaid_balances_controller.rb

@@ -0,0 +1,52 @@
+module Spree
+  module Api
+    module V2
+      module Storefront
+        module Account
+          # Endpoint: GET /api/v2/storefront/account/prepaid_balances
+          # Single endpoint for both "my one balance" and "all my balances" -- an optional
+          # ?currency= filters down to one (still an array, just 0-or-1 items), omitted returns
+          # every currency the platform has issued the user. Replaces the old separate
+          # GET account/prepaid (show) + GET account/prepaid_balances (index) pair: #show
+          # couldn't express "no currency given" without an :id segment, and this app's other
+          # index/show split forced the response shape (object vs array) to vary by param, which
+          # is worse than one endpoint with one fixed (array) shape and an optional filter.
+          class PrepaidBalancesController < Spree::Api::V2::ResourceController
+            before_action :require_spree_current_user
+
+            def index
+              if params[:currency].present?
+                currency = params[:currency].to_s.upcase
+                unless Spree::Store.default.supported_currency_codes.include?(currency)
+                  return render_error_payload("unsupported currency: #{currency}")
+                end
+              end
+
+              render_serialized_payload { collection_serializer.new(presented_collection(currency)).serializable_hash }
+            end
+
+            private
+
+            # Platform-issued prepaid credit only (Spree::StoreCredit#platform_prepaid scope) --
+            # storefront is the platform namespace; tenant-issued wallet credit isn't
+            # spendable/visible here. Preferred currency sorted first (matches PrepaidConfig's
+            # supported_currencies order) rather than left in arbitrary DB order -- the client
+            # shouldn't have to inspect is_preferred on every item just to know which one to
+            # show first.
+            def presented_collection(currency)
+              preferred_currency = Spree::Store.default.default_currency
+              credits = spree_current_user.store_credits.platform_prepaid(currency).to_a
+              credits.sort_by! { |credit| credit.currency == preferred_currency ? 0 : 1 }
+
+              credits.map { |credit| SpreeCmCommissioner::PrepaidBalancePresenter.new(credit, preferred_currency) }
+            end
+
+            def collection_serializer
+              Spree::V2::Storefront::PrepaidBalanceSerializer
+            end
+          end
+        end
+      end
+    end
+  end
+end