spree_api 5.4.3 → 5.5.0.rc1

data/app/serializers/spree/api/v3/admin/category_serializer.rb

@@ -5,10 +5,11 @@ module Spree
         # Admin API Category Serializer
         # Full category data including admin-only fields
         class CategorySerializer < V3::CategorySerializer
-          typelize lft: :number, rgt: :number
+          typelize pretty_name: :string, lft: :number, rgt: :number, sort_order: :string,
+                   metadata: 'Record<string, unknown>'
 
-          # Nested set columns for tree operations
-          attributes :lft, :rgt, created_at: :iso8601, updated_at: :iso8601
+          # Admin-only attributes
+          attributes :metadata, :pretty_name, :lft, :rgt, created_at: :iso8601, updated_at: :iso8601
 
           # Override inherited associations to use admin serializers
           one :parent,

data/app/serializers/spree/api/v3/admin/channel_serializer.rb

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ChannelSerializer < V3::ChannelSerializer
+          typelize store_id: :string,
+                   preferred_order_routing_strategy: [:string, nullable: true]
+
+          attributes :preferred_order_routing_strategy,
+                     created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/country_serializer.rb

@@ -7,7 +7,7 @@ module Spree
 
           many :states,
                resource: Spree.api.admin_state_serializer,
-               if: proc { expand?(:states) }
+               if: proc { params[:expand]&.include?('states') }
         end
       end
     end

data/app/serializers/spree/api/v3/admin/coupon_code_serializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Coupon codes belong to multi-code promotions. Read-only here:
+        # codes are generated server-side based on the promotion's
+        # `code_prefix` + `number_of_codes`.
+        class CouponCodeSerializer < BaseSerializer
+          typelize code: :string,
+                   state: [:string, nullable: true],
+                   promotion_id: :string,
+                   order_id: [:string, nullable: true]
+
+          attributes :code, :state,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :promotion_id do |coupon|
+            coupon.promotion&.prefixed_id
+          end
+
+          attribute :order_id do |coupon|
+            coupon.order&.prefixed_id
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/credit_card_serializer.rb

@@ -4,7 +4,8 @@ module Spree
       module Admin
         class CreditCardSerializer < V3::CreditCardSerializer
           typelize customer_id: [:string, nullable: true],
-                   payment_method_id: [:string, nullable: true]
+                   payment_method_id: [:string, nullable: true],
+                   metadata: 'Record<string, unknown>'
 
           attribute :customer_id do |credit_card|
             credit_card.user&.prefixed_id
@@ -14,7 +15,8 @@ module Spree
             credit_card.payment_method&.prefixed_id
           end
 
-          attributes created_at: :iso8601, updated_at: :iso8601
+          attributes :metadata,
+                     created_at: :iso8601, updated_at: :iso8601
         end
       end
     end

data/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API Custom Field Definition Serializer
+        # Schema-side metadata for custom fields (per resource type).
+        class CustomFieldDefinitionSerializer < BaseSerializer
+          typelize namespace: :string,
+                   key: :string,
+                   label: :string,
+                   field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
+                   resource_type: :string,
+                   storefront_visible: :boolean
+
+          attributes :namespace, :key, :label, :field_type, :resource_type, :storefront_visible,
+                     created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/custom_field_serializer.rb

@@ -5,12 +5,17 @@ module Spree
         # Admin API Custom Field Serializer
         # Full custom field data including admin-only fields
         class CustomFieldSerializer < V3::CustomFieldSerializer
-          typelize storefront_visible: :boolean
+          typelize storefront_visible: :boolean,
+                   custom_field_definition_id: :string
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
-          attribute :storefront_visible do |metafield|
-            metafield.display_on.in?(%w[both front_end])
+          attribute :storefront_visible do |custom_field|
+            custom_field.metafield_definition.available_on_front_end?
+          end
+
+          attribute :custom_field_definition_id do |custom_field|
+            custom_field.metafield_definition.prefixed_id
           end
         end
       end

data/app/serializers/spree/api/v3/admin/customer_group_serializer.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Serializes Spree::CustomerGroup for the admin pickers
+        # (e.g. promotion rule, customer-group filters). Surfaces only
+        # what the admin UI needs to display + select rows.
+        class CustomerGroupSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   description: 'string | null',
+                   customers_count: :number
+
+          attributes :name, :description, :customers_count,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          # Members are paginated separately via `/customers?customer_group_id_in=…`
+          # because a group can hold tens of thousands of users — embedding the
+          # whole list on every group fetch would explode the index payload.
+          # Pass `expand=customers` when you need them inline (single-record reads only).
+          many :customers,
+               resource: Spree.api.admin_customer_serializer,
+               if: proc { expand?('customers') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/customer_serializer.rb

@@ -8,10 +8,19 @@ module Spree
           typelize login: [:string, nullable: true],
                    last_sign_in_at: [:string, nullable: true], current_sign_in_at: [:string, nullable: true],
                    sign_in_count: :number, failed_attempts: :number,
-                   last_sign_in_ip: [:string, nullable: true], current_sign_in_ip: [:string, nullable: true]
+                   last_sign_in_ip: [:string, nullable: true], current_sign_in_ip: [:string, nullable: true],
+                   tags: [:string, multi: true],
+                   internal_note_html: [:string, nullable: true],
+                   metadata: 'Record<string, unknown>',
+                   orders_count: :number,
+                   total_spent: :string,
+                   display_total_spent: :string,
+                   last_order_completed_at: [:string, nullable: true],
+                   default_billing_address_id: [:string, nullable: true],
+                   default_shipping_address_id: [:string, nullable: true]
 
           # Admin-only attributes
-          attributes :login,
+          attributes :login, :metadata,
                      last_sign_in_at: :iso8601, current_sign_in_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
@@ -31,6 +40,45 @@ module Spree
             user.current_sign_in_ip
           end
 
+          attribute :tags do |user|
+            user.tag_list.to_a
+          end
+
+          attribute :internal_note_html do |user|
+            user.respond_to?(:internal_note) ? user.internal_note&.body&.to_s.presence : nil
+          end
+
+          attribute :default_billing_address_id do |user|
+            user.bill_address&.prefixed_id
+          end
+
+          attribute :default_shipping_address_id do |user|
+            user.ship_address&.prefixed_id
+          end
+
+          # Order aggregates: prefer attributes precomputed on the scope (see
+          # CustomersController#scope) to avoid N+1 on list endpoints. Fall
+          # back to per-user queries when not preloaded (e.g. show endpoint
+          # for a freshly loaded record).
+          attribute :orders_count do |user|
+            user.attributes['orders_count']&.to_i || user.orders.complete.count
+          end
+
+          attribute :total_spent do |user|
+            (user.attributes['total_spent'] || user.orders.complete.sum(:total)).to_s
+          end
+
+          attribute :display_total_spent do |user|
+            amount = user.attributes['total_spent'] || user.orders.complete.sum(:total)
+            currency = Spree::Current.currency || Spree::Current.store&.default_currency || Spree::Config[:currency]
+            Spree::Money.new(amount, currency: currency).to_s
+          end
+
+          attribute :last_order_completed_at do |user|
+            value = user.attributes.key?('last_order_completed_at') ? user.attributes['last_order_completed_at'] : user.orders.complete.maximum(:completed_at)
+            value.respond_to?(:iso8601) ? value.iso8601 : value
+          end
+
           # Override inherited associations to use admin serializers
           many :addresses, resource: Spree.api.admin_address_serializer, if: proc { expand?('addresses') }
           one :bill_address, key: :default_billing_address, resource: Spree.api.admin_address_serializer, if: proc { expand?('default_billing_address') }
@@ -39,6 +87,14 @@ module Spree
           many :orders,
                resource: Spree.api.admin_order_serializer,
                if: proc { expand?('orders') }
+
+          many :store_credits,
+               resource: Spree.api.admin_store_credit_serializer,
+               if: proc { expand?('store_credits') }
+
+          many :customer_groups,
+               resource: Spree.api.admin_customer_group_serializer,
+               if: proc { expand?('customer_groups') }
         end
       end
     end

data/app/serializers/spree/api/v3/admin/dashboard_analytics_serializer.rb

@@ -0,0 +1,143 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class DashboardAnalyticsSerializer
+          attr_reader :store, :currency, :time_range, :params
+
+          def initialize(store:, currency:, time_range:, params: {})
+            @store = store
+            @currency = currency
+            @time_range = time_range
+            @params = params
+          end
+
+          def to_h
+            {
+              currency: currency,
+              date_from: time_range.first.iso8601,
+              date_to: time_range.last.iso8601,
+              summary: summary,
+              chart_data: chart_data,
+              top_products: top_products
+            }
+          end
+
+          private
+
+          def orders
+            @orders ||= store.orders.complete.where(currency: currency, completed_at: time_range)
+          end
+
+          def prev_orders
+            @prev_orders ||= store.orders.complete.where(currency: currency, completed_at: previous_time_range)
+          end
+
+          def previous_time_range
+            duration = time_range.last - time_range.first
+            (time_range.first - duration)..(time_range.last - duration)
+          end
+
+          # ---- Summary ----
+
+          def summary
+            sales = sales_total
+            count = orders_count
+            avg = count > 0 ? (sales / count).round(2) : 0.0
+
+            prev_sales = prev_orders.sum(:total).to_f
+            prev_count = prev_orders.count
+            prev_avg = prev_count > 0 ? (prev_sales / prev_count).round(2) : 0.0
+
+            {
+              sales_total: sales.round(2),
+              display_sales_total: money(sales),
+              sales_growth: growth_rate(sales, prev_sales),
+              orders_count: count,
+              orders_growth: growth_rate(count, prev_count),
+              avg_order_value: avg,
+              display_avg_order_value: money(avg),
+              avg_order_value_growth: growth_rate(avg, prev_avg)
+            }
+          end
+
+          def sales_total
+            @sales_total ||= orders.sum(:total).to_f
+          end
+
+          def orders_count
+            @orders_count ||= orders.count
+          end
+
+          # ---- Chart data ----
+
+          def chart_data
+            daily = orders
+              .select("DATE(completed_at) AS day, SUM(total) AS day_total, COUNT(*) AS day_count")
+              .group("DATE(completed_at)")
+              .order("day")
+              .index_by { |r| r.day.to_s }
+
+            (time_range.first.to_date..time_range.last.to_date).map do |date|
+              key = date.to_s
+              row = daily[key]
+              total = row&.day_total.to_f
+              count = row&.day_count.to_i || 0
+              {
+                date: key,
+                sales: total.round(2),
+                orders: count,
+                avg_order_value: count > 0 ? (total / count).round(2) : 0.0
+              }
+            end
+          end
+
+          # ---- Top products ----
+
+          def top_products
+            rows = Spree::LineItem
+              .joins(:variant)
+              .where(order: orders)
+              .group('spree_variants.product_id')
+              .order(Arel.sql('SUM(spree_line_items.quantity * spree_line_items.price) DESC'))
+              .limit(5)
+              .pluck(Arel.sql('spree_variants.product_id, SUM(spree_line_items.quantity), SUM(spree_line_items.quantity * spree_line_items.price)'))
+
+            product_ids = rows.map(&:first).compact
+            return [] if product_ids.empty?
+
+            products = store.products.with_deleted.includes(:primary_media).where(id: product_ids)
+            product_serializer = Spree.api.admin_product_serializer
+
+            rows.filter_map do |product_id, quantity, amount|
+              product = products.find { |p| p.id == product_id }
+              next unless product
+
+              serialized = product_serializer.new(product, params: params).to_h
+              {
+                id: serialized['id'],
+                name: serialized['name'],
+                slug: serialized['slug'],
+                image_url: serialized['thumbnail_url'],
+                price: serialized.dig('price', 'display_amount'),
+                quantity: quantity.to_i,
+                total: money(amount)
+              }
+            end
+          end
+
+          # ---- Helpers ----
+
+          def money(amount)
+            Spree::Money.new(amount, currency: currency).to_s
+          end
+
+          def growth_rate(current, previous)
+            return 0.0 if previous.zero?
+            (((current - previous) / previous.to_f) * 100).round(1)
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/export_serializer.rb

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::Export}.
+        #
+        # `download_url` is the path to our own download endpoint, not a
+        # pre-signed ActiveStorage URL — the controller streams bytes inline
+        # so the JWT auth flow runs on every download and works through the
+        # SPA's `/api/*`-only dev proxy.
+        class ExportSerializer < V3::ExportSerializer
+          typelize done: :boolean,
+                   download_url: [:string, nullable: true],
+                   filename: [:string, nullable: true],
+                   byte_size: [:number, nullable: true]
+
+          attribute(:done) { |export| export.done? }
+
+          # Safe-nav on `blob` — `attachment.attached?` can stay true while a
+          # background job purges the underlying blob (e.g. retention sweeps).
+          attribute :filename do |export|
+            export.attachment.blob&.filename&.to_s if export.done?
+          end
+
+          attribute :byte_size do |export|
+            export.attachment.blob&.byte_size if export.done?
+          end
+
+          attribute :download_url do |export|
+            next nil unless export.done?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_admin_export_path(
+              id: export.prefixed_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb

@@ -3,19 +3,15 @@ module Spree
     module V3
       module Admin
         class FulfillmentSerializer < V3::FulfillmentSerializer
-          typelize metadata: 'Record<string, unknown> | null',
+          typelize metadata: 'Record<string, unknown>',
                    order_id: [:string, nullable: true],
                    stock_location_id: [:string, nullable: true],
                    adjustment_total: :string,
                    pre_tax_amount: :string
 
-          attributes :adjustment_total, :pre_tax_amount,
+          attributes :metadata, :adjustment_total, :pre_tax_amount,
                      created_at: :iso8601, updated_at: :iso8601
 
-          attribute :metadata do |shipment|
-            shipment.metadata.presence
-          end
-
           attribute :order_id do |shipment|
             shipment.order&.prefixed_id
           end

data/app/serializers/spree/api/v3/admin/{asset_serializer.rb → gift_card_batch_serializer.rb}

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       module Admin
-        class AssetSerializer < V3::AssetSerializer
+        class GiftCardBatchSerializer < V3::GiftCardBatchSerializer
         end
       end
     end

data/app/serializers/spree/api/v3/admin/gift_card_serializer.rb

@@ -2,14 +2,49 @@ module Spree
   module Api
     module V3
       module Admin
+        # Admin serializer extends the store-facing one with operational
+        # context the admin UI needs: who the card was issued to (customer),
+        # who issued it (admin), and the orders that consumed it.
         class GiftCardSerializer < V3::GiftCardSerializer
-          typelize metadata: 'Record<string, unknown> | null'
+          typelize customer_id: [:string, nullable: true],
+                   created_by_id: [:string, nullable: true]
 
-          attribute :metadata do |gift_card|
-            gift_card.metadata.presence
+          attributes created_at: :iso8601, updated_at: :iso8601
+
+          attribute :customer_id do |gift_card|
+            gift_card.user&.prefixed_id
           end
 
-          attributes created_at: :iso8601, updated_at: :iso8601
+          attribute :created_by_id do |gift_card|
+            gift_card.created_by&.prefixed_id
+          end
+
+          # Customer the card was issued to. Gated behind `expand?` to keep
+          # the list payload thin — the SPA's list view passes
+          # `expand=customer,created_by` to populate the row chips.
+          one :user,
+              key: :customer,
+              resource: Spree.api.admin_customer_serializer,
+              if: proc { expand?('customer') }
+
+          # Admin who issued the card.
+          one :created_by,
+              resource: Spree.api.admin_admin_user_serializer,
+              if: proc { expand?('created_by') }
+
+          # Batch the card was issued as part of (bulk-issue flow). The
+          # `Spree::GiftCard#batch` association is keyed off
+          # `gift_card_batch_id`; we rename the JSON field to match that
+          # column for read/write symmetry.
+          one :batch,
+              key: :gift_card_batch,
+              resource: Spree.api.admin_gift_card_batch_serializer,
+              if: proc { expand?('gift_card_batch') }
+
+          # Orders that consumed the card. Detail-only — pass `expand=orders`.
+          many :orders,
+               resource: Spree.api.admin_order_serializer,
+               if: proc { expand?('orders') }
         end
       end
     end

data/app/serializers/spree/api/v3/admin/invitation_serializer.rb

@@ -0,0 +1,64 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::Invitation}. Used on the staff
+        # settings page to list pending invitations and to surface the result
+        # of `POST /admin/invitations`. Inviter and invitee are flattened to
+        # email-only — the full polymorphic identities aren't useful to the UI.
+        class InvitationSerializer < V3::BaseSerializer
+          typelize email: :string,
+                   status: :string,
+                   role_id: :string,
+                   role_name: :string,
+                   inviter_email: :string,
+                   expires_at: :string,
+                   acceptance_url: :string,
+                   invitee_exists: :boolean,
+                   store: '{ id: string; name: string }'
+
+          attributes :email, :status,
+                     created_at: :iso8601, updated_at: :iso8601, expires_at: :iso8601
+
+          # `role`, `inviter` are `validates ... presence: true` on the model,
+          # so they're guaranteed non-null for any persisted invitation.
+          attribute :role_id do |invitation|
+            invitation.role.prefixed_id
+          end
+
+          attribute :role_name do |invitation|
+            invitation.role.name
+          end
+
+          attribute :inviter_email do |invitation|
+            invitation.inviter.email
+          end
+
+          # Absolute URL when `Spree::Config[:admin_url]` is set, otherwise
+          # the path so the SPA can prepend `window.location.origin`.
+          attribute :acceptance_url do |invitation|
+            if Spree::Config[:admin_url].present?
+              Rails.application.routes.url_helpers.admin_invitation_acceptance_url(invitation)
+            else
+              "/accept-invitation/#{invitation.prefixed_id}?token=#{invitation.token}"
+            end
+          end
+
+          # Drives the SPA's sign-in vs sign-up branch on the acceptance page.
+          # Looked up by email so an admin who's already on another store sees
+          # the password prompt, not a fresh account form.
+          attribute :invitee_exists do |invitation|
+            Spree.admin_user_class.exists?(email: invitation.email)
+          end
+
+          # Minimal store identity for the unauthenticated acceptance page's
+          # title ("Join <store>"). Full Store would over-expose internals to
+          # a public landing page; this is the smallest shape that renders.
+          attribute :store do |invitation|
+            { id: invitation.store.prefixed_id, name: invitation.store.name }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/line_item_serializer.rb

@@ -5,16 +5,12 @@ module Spree
         # Admin API Line Item Serializer
         # Extends the store serializer with metadata visibility
         class LineItemSerializer < V3::LineItemSerializer
-          typelize metadata: 'Record<string, unknown> | null',
+          typelize metadata: 'Record<string, unknown>',
                    cost_price: [:string, nullable: true],
-                   tax_category_id: [:string, nullable: true],
-                   order_id: [:string, nullable: true]
+                   tax_category_id: [:string, nullable: true]
 
-          attributes created_at: :iso8601, updated_at: :iso8601
-
-          attribute :metadata do |line_item|
-            line_item.metadata.presence
-          end
+          attributes :metadata,
+                     created_at: :iso8601, updated_at: :iso8601
 
           attribute :cost_price do |line_item|
             line_item.cost_price&.to_s
@@ -24,18 +20,10 @@ module Spree
             line_item.tax_category&.prefixed_id
           end
 
-          attribute :order_id do |line_item|
-            line_item.order&.prefixed_id
-          end
-
           # Override inherited associations to use admin serializers
           many :option_values, resource: Spree.api.admin_option_value_serializer
           many :digital_links, resource: Spree.api.admin_digital_link_serializer
 
-          one :order,
-              resource: Spree.api.admin_order_serializer,
-              if: proc { expand?('order') }
-
           one :variant,
               resource: Spree.api.admin_variant_serializer,
               if: proc { expand?('variant') }

data/app/serializers/spree/api/v3/admin/media_serializer.rb

@@ -3,7 +3,9 @@ module Spree
     module V3
       module Admin
         class MediaSerializer < V3::MediaSerializer
-          typelize viewable_type: :string, viewable_id: :string
+          typelize viewable_type: :string, viewable_id: :string,
+                   metadata: 'Record<string, unknown>',
+                   download_url: [:string, nullable: true]
 
           attributes created_at: :iso8601, updated_at: :iso8601
 
@@ -11,7 +13,27 @@ module Spree
             asset.viewable&.prefixed_id
           end
 
-          attributes :viewable_type
+          # Forces Content-Disposition: attachment so admins downloading from
+          # cloud storage (S3) get a save-as instead of an inline view. Mirrors
+          # the host resolution from the `:cdn_image` direct route since
+          # rails_blob_url itself doesn't fall back to Spree.cdn_host or the
+          # current store's domain.
+          attribute :download_url do |asset|
+            next nil unless asset.attachment&.attached?
+
+            host = Spree.cdn_host.presence ||
+                   Rails.application.routes.default_url_options[:host] ||
+                   Spree::Store.current&.url_or_custom_domain
+            helpers = Rails.application.routes.url_helpers
+
+            if host.present?
+              helpers.rails_blob_url(asset.attachment.blob, disposition: 'attachment', host: host)
+            else
+              helpers.rails_blob_path(asset.attachment.blob, disposition: 'attachment')
+            end
+          end
+
+          attributes :metadata, :viewable_type
         end
       end
     end