spree_api 5.6.1 → 6.0.0.beta1

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

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class StockLevelSerializer < V3::StockLevelSerializer
+          include Concerns::ExternalReferencesAttribute
+
+          typelize metadata: 'Record<string, unknown>',
+                   allocated_count: :number, available_count: :number,
+                   reserved_count: :number, incoming_count: :number, purchasable_count: :number,
+                   stock_location_name: [:string, nullable: true],
+                   product_id: [:string, nullable: true],
+                   variant_name: [:string, nullable: true], variant_sku: [:string, nullable: true],
+                   options_text: [:string, nullable: true],
+                   thumbnail_url: [:string, nullable: true]
+
+          # Reserved: units held by checkouts in progress. Incoming: units on
+          # their way on an open purchase order or a transfer in transit.
+          # Which shelf and which SKU, flat, the way a stock movement names
+          # them: enough for a list row without expanding the variant, whose
+          # own serializer computes availability per row.
+          attributes :metadata, :reserved_count, :incoming_count, :purchasable_count,
+                     :variant_name, :variant_sku,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :stock_location_name do |stock_level|
+            stock_level.stock_location&.name
+          end
+
+          attribute :product_id do |stock_level|
+            stock_level.product&.prefixed_id
+          end
+
+          attribute :options_text do |stock_level|
+            stock_level.variant&.options_text.presence
+          end
+
+          attribute :thumbnail_url do |stock_level|
+            image_url_for(stock_level.thumbnail)
+          end
+
+          # Units promised to placed orders but not yet dispatched. Raised by an
+          # `allocated` movement and retired by `released` or `shipped`, so an
+          # oversell reads as this exceeding count_on_hand.
+          attribute :allocated_count do |stock_level|
+            stock_level.allocated_count.to_i
+          end
+
+          # Physical stock minus allocated units (per stock_level).
+          attribute :available_count do |stock_level|
+            stock_level.available_count.to_i
+          end
+
+          one :stock_location,
+              resource: proc { Spree.api.admin_stock_location_serializer },
+              if: proc { expand?('stock_location') }
+
+          one :variant,
+              resource: proc { Spree.api.admin_variant_serializer },
+              if: proc { expand?('variant') }
+        end
+      end
+    end
+  end
+end

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

@@ -3,20 +3,36 @@ module Spree
     module V3
       module Admin
         class StockLocationSerializer < V3::StockLocationSerializer
-          typelize active: :boolean, default: :boolean, backorderable_default: :boolean,
-                   propagate_all_variants: :boolean, pickup_enabled: :boolean,
+          include Concerns::ExternalReferencesAttribute
+
+          typelize seller_id: [:string, nullable: true], seller_name: [:string, nullable: true],
+                   active: :boolean, default: :boolean, backorderable_default: :boolean,
+                   propagate_all_variants: :boolean, pickup_enabled: :boolean, returns_enabled: :boolean,
                    admin_name: [:string, nullable: true],
                    address2: [:string, nullable: true], state_name: [:string, nullable: true],
                    phone: [:string, nullable: true], company: [:string, nullable: true],
-                   kind: :string, pickup_stock_policy: :string,
+                   kind: [:string, enum: Spree::StockLocation::KINDS, enum_type_name: 'StockLocationKind'],
+                   pickup_stock_policy: [:string, enum: Spree::StockLocation::PICKUP_STOCK_POLICIES],
                    pickup_ready_in_minutes: [:number, nullable: true],
                    pickup_instructions: [:string, nullable: true]
 
           attributes :admin_name, :address2, :state_name, :phone, :company,
                      :active, :default, :backorderable_default, :propagate_all_variants,
-                     :kind, :pickup_enabled, :pickup_stock_policy,
+                     :kind, :pickup_enabled, :pickup_stock_policy, :returns_enabled,
                      :pickup_ready_in_minutes, :pickup_instructions,
                      created_at: :iso8601, updated_at: :iso8601
+
+          attribute :seller_id do |stock_location|
+            stock_location.seller&.prefixed_id
+          end
+
+          attribute :seller_name do |stock_location|
+            stock_location.seller&.name
+          end
+
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') }
         end
       end
     end

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

@@ -0,0 +1,116 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class StockMovementSerializer < V3::StockMovementSerializer
+          typelize order_id: [:string, nullable: true], fulfillment_id: [:string, nullable: true],
+                   return_id: [:string, nullable: true], exchange_id: [:string, nullable: true],
+                   stock_transfer_id: [:string, nullable: true],
+                   purchase_order_id: [:string, nullable: true],
+                   stock_receipt_id: [:string, nullable: true],
+                   order_number: [:string, nullable: true], return_number: [:string, nullable: true],
+                   exchange_number: [:string, nullable: true],
+                   stock_transfer_number: [:string, nullable: true],
+                   purchase_order_number: [:string, nullable: true],
+                   unit_cost: [:string, nullable: true],
+                   display_unit_cost: [:string, nullable: true],
+                   stock_location_id: [:string, nullable: true],
+                   stock_location_name: [:string, nullable: true],
+                   variant_id: [:string, nullable: true],
+                   variant_name: [:string, nullable: true],
+                   variant_sku: [:string, nullable: true]
+
+          # Which shelf, and which SKU. A movement names neither directly —
+          # both hang off its stock level, the (variant, warehouse) pair — but
+          # a history panel cannot be read without them: scoped to a variant
+          # the warehouse is what varies, scoped to a warehouse the SKU is,
+          # and scoped to one transfer both do.
+          attribute :stock_location_id do |movement|
+            movement.stock_level&.stock_location&.prefixed_id
+          end
+
+          attribute :stock_location_name do |movement|
+            movement.stock_level&.stock_location&.name
+          end
+
+          attribute :variant_id do |movement|
+            movement.stock_level&.variant&.prefixed_id
+          end
+
+          attribute :variant_name do |movement|
+            movement.stock_level&.variant&.product&.name
+          end
+
+          attribute :variant_sku do |movement|
+            movement.stock_level&.variant&.sku
+          end
+
+          # The cause. Exactly which keys are set follows from the kind — a
+          # dispatch carries its fulfillment and its order, a transfer carries
+          # the transfer, a correction carries none.
+          attribute :order_id do |movement|
+            Spree::Order.prefixed_id_for(movement.order_id)
+          end
+
+          attribute :fulfillment_id do |movement|
+            Spree::Fulfillment.prefixed_id_for(movement.fulfillment_id)
+          end
+
+          attribute :return_id do |movement|
+            Spree::Return.prefixed_id_for(movement.return_id)
+          end
+
+          attribute :exchange_id do |movement|
+            Spree::Exchange.prefixed_id_for(movement.exchange_id)
+          end
+
+          attribute :stock_transfer_id do |movement|
+            Spree::StockTransfer.prefixed_id_for(movement.stock_transfer_id)
+          end
+
+          attribute :stock_receipt_id do |movement|
+            movement.stock_receipt&.prefixed_id
+          end
+
+          attribute :purchase_order_id do |movement|
+            Spree::PurchaseOrder.prefixed_id_for(movement.purchase_order_id)
+          end
+
+          # The cause by the name a merchant knows it by — "T1001", "PO1003",
+          # "R123456789" — so a history row can point at its document without
+          # a second request to look the number up.
+          attribute :order_number do |movement|
+            movement.order&.number
+          end
+
+          attribute :return_number do |movement|
+            movement.return&.number
+          end
+
+          attribute :exchange_number do |movement|
+            movement.exchange&.number
+          end
+
+          attribute :stock_transfer_number do |movement|
+            movement.stock_transfer&.number
+          end
+
+          attribute :purchase_order_number do |movement|
+            movement.purchase_order&.number
+          end
+
+          # What the units cost, on the rows where that means something: a
+          # purchase. Null on a transfer or a return — moving stock the
+          # merchant already owns is not buying it.
+          attribute :unit_cost do |movement|
+            movement.unit_cost&.to_s
+          end
+
+          attribute :display_unit_cost do |movement|
+            movement.display_unit_cost&.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One line of a delivery: how many of a document's line arrived, how
+        # many were refused, and why.
+        class StockReceiptItemSerializer < V3::BaseSerializer
+          typelize quantity_accepted: :number,
+                   quantity_rejected: :number,
+                   rejection_reason: [:string, enum: Spree::StockReceiptItem::REJECTION_REASONS, nullable: true],
+                   notes: 'string | null',
+                   line_type: [:string, enum: %w[purchase_order_item stock_transfer_item]],
+                   line_id: 'string | null',
+                   product_id: 'string | null',
+                   variant_id: 'string | null',
+                   variant_name: 'string | null',
+                   variant_sku: 'string | null',
+                   thumbnail_url: 'string | null'
+
+          attributes :quantity_accepted, :quantity_rejected, :rejection_reason, :notes
+
+          # The document line this delivery counted against, as the client
+          # names it: `purchase_order_item` or `stock_transfer_item`.
+          attribute :line_type do |item|
+            item.line_type.demodulize.underscore
+          end
+
+          attribute :line_id do |item|
+            item.line&.prefixed_id
+          end
+
+          attribute :variant_id do |item|
+            item.variant&.prefixed_id
+          end
+
+          # The product the line's variant belongs to, so a delivery's line
+          # can link to the screen where that SKU's stock lives.
+          attribute :product_id do |item|
+            item.variant&.product&.prefixed_id
+          end
+
+          attribute :variant_name do |item|
+            item.variant&.product&.name
+          end
+
+          attribute :variant_sku do |item|
+            item.variant&.sku
+          end
+
+          attribute :thumbnail_url do |item|
+            image_url_for(item.line&.thumbnail)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One delivery against a purchase order or a transfer: what the dock
+        # counted in, under which packing slip, on which day.
+        class StockReceiptSerializer < V3::BaseSerializer
+          typelize number: :string,
+                   reference: 'string | null',
+                   notes: 'string | null',
+                   received_at: :string,
+                   receivable_type: [:string, enum: %w[purchase_order stock_transfer]],
+                   receivable_id: :string,
+                   received_by_id: 'string | null',
+                   items_count: :number,
+                   quantity_accepted_total: :number,
+                   quantity_rejected_total: :number,
+                   metadata: 'Record<string, unknown>'
+
+          attributes :number, :reference, :notes, :metadata,
+                     :quantity_accepted_total, :quantity_rejected_total,
+                     received_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          # The document this delivery was booked against, as the client
+          # names it: `purchase_order` or `stock_transfer`.
+          attribute :receivable_type do |receipt|
+            receipt.receivable_type.demodulize.underscore
+          end
+
+          attribute :receivable_id do |receipt|
+            receipt.receivable&.prefixed_id
+          end
+
+          attribute :received_by_id do |receipt|
+            receipt.received_by.try(:prefixed_id)
+          end
+
+          attribute :items_count do |receipt|
+            receipt.items.size
+          end
+
+          many :items,
+               resource: proc { Spree.api.admin_stock_receipt_item_serializer },
+               if: proc { expand?('items') }
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@ module Spree
     module V3
       module Admin
         class StockReservationSerializer < V3::StockReservationSerializer
-          typelize stock_item_id: :string,
+          typelize stock_level_id: :string,
                    line_item_id: :string,
                    order_id: :string,
                    variant_id: [:string, nullable: true],
@@ -12,8 +12,8 @@ module Spree
                    expires_at: :string,
                    active: :boolean
 
-          attribute :stock_item_id do |reservation|
-            reservation.stock_item.prefixed_id
+          attribute :stock_level_id do |reservation|
+            reservation.stock_level.prefixed_id
           end
 
           attribute :line_item_id do |reservation|
@@ -25,11 +25,11 @@ module Spree
           end
 
           attribute :variant_id do |reservation|
-            reservation.stock_item&.variant&.prefixed_id
+            reservation.stock_level&.variant&.prefixed_id
           end
 
           attribute :stock_location_id do |reservation|
-            reservation.stock_item&.stock_location&.prefixed_id
+            reservation.stock_level&.stock_location&.prefixed_id
           end
 
           attributes :quantity, expires_at: :iso8601

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

@@ -0,0 +1,57 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One SKU on a stock transfer: how many left, how many arrived, and
+        # how many of those were refused.
+        class StockTransferItemSerializer < V3::BaseSerializer
+          typelize quantity_shipped: :number,
+                   quantity_received: :number,
+                   quantity_rejected: :number,
+                   quantity_over: :number,
+                   outstanding: :number,
+                   stock_transfer_id: 'string | null',
+                   thumbnail_url: 'string | null',
+                   product_id: 'string | null',
+                   variant_id: 'string | null',
+                   variant_name: 'string | null',
+                   variant_sku: 'string | null',
+                   options_text: 'string | null'
+
+          attributes :quantity_shipped, :quantity_received, :quantity_rejected, :quantity_over, :outstanding,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :stock_transfer_id do |item|
+            Spree::StockTransfer.prefixed_id_for(item.stock_transfer_id)
+          end
+
+          attribute :variant_id do |item|
+            item.variant&.prefixed_id
+          end
+
+          # The product the line's variant belongs to, so a line can link
+          # straight to the screen where that SKU's stock lives.
+          attribute :product_id do |item|
+            item.variant&.product&.prefixed_id
+          end
+
+          attribute :variant_name do |item|
+            item.variant&.product&.name
+          end
+
+          attribute :variant_sku do |item|
+            item.variant&.sku
+          end
+
+          attribute :options_text do |item|
+            item.variant&.options_text
+          end
+
+          attribute :thumbnail_url do |item|
+            image_url_for(item.thumbnail)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,26 +2,46 @@ module Spree
   module Api
     module V3
       module Admin
-        # Inventory movement between two stock locations (or external →
-        # location for receives). The originating location is `nil` for
-        # receives (vendor stock arriving) and present for transfers.
-        class StockTransferSerializer < V3::BaseSerializer
-          typelize number: :string,
-                   reference: [:string, nullable: true],
-                   source_location_id: [:string, nullable: true],
-                   destination_location_id: [:string, nullable: true],
+        # Stock moving between two of the merchant's own warehouses. The trip
+        # has a middle: `shipped_at` is when the units left the source,
+        # `received_at` when the destination finished counting them in.
+        class StockTransferSerializer < V3::StockTransferSerializer
+          typelize status: :string,
+                   notes: 'string | null',
+                   items_count: :number,
+                   quantity_shipped_total: :number,
+                   quantity_received_total: :number,
+                   quantity_rejected_total: :number,
+                   editable: :boolean,
+                   closed_short_at: 'string | null',
+                   close_reason: 'string | null',
+                   closed_short: :boolean,
+                   shipped_at: 'string | null',
+                   received_at: 'string | null',
+                   deleted_at: 'string | null',
                    metadata: 'Record<string, unknown>'
 
-          attributes :number, :reference, :metadata,
-                     created_at: :iso8601, updated_at: :iso8601
+          attributes :status, :notes, :metadata, :close_reason,
+                     :items_count, :quantity_received_total, :quantity_rejected_total,
+                     shipped_at: :iso8601, received_at: :iso8601, closed_short_at: :iso8601,
+                     deleted_at: :iso8601
 
-          attribute :source_location_id do |stock_transfer|
-            stock_transfer.source_location&.prefixed_id
-          end
+          attribute :closed_short, &:closed_short?
 
-          attribute :destination_location_id do |stock_transfer|
-            stock_transfer.destination_location&.prefixed_id
-          end
+          # Named for the merchant's own vocabulary — a transfer ships, a
+          # purchase order orders — over the concern's neutral
+          # `quantity_expected`.
+          attribute :quantity_shipped_total, &:quantity_expected_total
+
+          attribute :editable, &:editable?
+
+          many :items,
+               resource: proc { Spree.api.admin_stock_transfer_item_serializer },
+               if: proc { expand?('items') }
+
+          many :stock_receipts,
+               resource: proc { Spree.api.admin_stock_receipt_serializer },
+               if: proc { expand?('stock_receipts') }
 
           one :source_location,
               resource: proc { Spree.api.admin_stock_location_serializer },

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

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # One line of a store credit's ledger: how the balance moved and what
+        # moved it. Read-only — events are written by the credit itself.
+        class StoreCreditEventSerializer < V3::StoreCreditEventSerializer
+          typelize originator_type: [:string, nullable: true],
+                   originator_id: [:string, nullable: true],
+                   store_credit_id: :string
+
+          attributes updated_at: :iso8601
+
+          attribute :store_credit_id do |event|
+            event.store_credit&.prefixed_id
+          end
+
+          attribute :originator_type do |event|
+            Spree::Base.polymorphic_api_type(event.originator_type)
+          end
+
+          # From the columns, like the credit's own originator: a type read from
+          # the column beside an id read from the association would name an
+          # originator the client has no id to link to.
+          attribute :originator_id do |event|
+            Spree::Base.polymorphic_prefixed_id(event.originator_type, event.originator_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,29 +5,64 @@ module Spree
         class StoreCreditSerializer < V3::StoreCreditSerializer
           typelize customer_id: [:string, nullable: true],
                    created_by_id: [:string, nullable: true],
-                   category_id: [:string, nullable: true],
-                   category_name: [:string, nullable: true],
                    memo: [:string, nullable: true],
+                   amount_authorized: :string,
+                   display_amount_authorized: :string,
+                   outstanding: :boolean,
+                   originator_type: [:string, nullable: true],
+                   originator_id: [:string, nullable: true],
                    metadata: 'Record<string, unknown>'
 
           attributes :memo, :metadata,
                      created_at: :iso8601, updated_at: :iso8601
 
+          attribute :amount_authorized do |store_credit|
+            store_credit.amount_authorized.to_s
+          end
+
+          # Answers the same question as the `outstanding` filter, so the row
+          # and the filter cannot disagree.
+          attribute :outstanding do |store_credit|
+            store_credit.outstanding?
+          end
+
+          attribute :display_amount_authorized do |store_credit|
+            store_credit.display_amount_authorized.to_s
+          end
+
           attribute :customer_id do |store_credit|
-            store_credit.user&.prefixed_id
+            store_credit.customer&.prefixed_id
           end
 
           attribute :created_by_id do |store_credit|
             store_credit.created_by&.prefixed_id
           end
 
-          attribute :category_id do |store_credit|
-            store_credit.category&.prefixed_id
+          # Why the credit exists: the return, exchange, claim or gift card
+          # that issued it, or null when an admin issued it by hand. The type
+          # is the polymorphic shorthand (`return`, `gift_card`), never a Ruby
+          # class name.
+          #
+          # Both read the columns rather than the association: returns, claims
+          # and exchanges are paranoid, so loading the record answers nil once
+          # it is soft-deleted — which would leave a type naming an originator
+          # beside a null id, and a client rendering "Return" for something it
+          # cannot link to.
+          attribute :originator_type do |store_credit|
+            Spree::Base.polymorphic_api_type(store_credit.originator_type)
           end
 
-          attribute :category_name do |store_credit|
-            store_credit.category_name
+          attribute :originator_id do |store_credit|
+            Spree::Base.polymorphic_prefixed_id(store_credit.originator_type, store_credit.originator_id)
           end
+
+          one :customer,
+              resource: proc { Spree.api.admin_customer_serializer },
+              if: proc { expand?('customer') }
+
+          one :created_by,
+              resource: proc { Spree.api.admin_admin_user_serializer },
+              if: proc { expand?('created_by') }
         end
       end
     end