spree_api 5.6.1 → 6.0.0.beta1

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

@@ -18,11 +18,11 @@ module Spree
         end
 
         attribute :description do |category|
-          category.description&.to_plain_text.to_s
+          Spree::RichTextHelper.to_plain_text(category.description)
         end
 
         attribute :description_html do |category|
-          category.description&.body&.to_s.to_s
+          category.description_html
         end
 
         attribute :image_url do |category|
@@ -60,7 +60,7 @@ module Spree
              resource: proc { Spree.api.category_serializer },
              if: proc { expand?('ancestors') }
 
-        many :public_metafields,
+        many :storefront_custom_fields,
              key: :custom_fields,
              resource: proc { Spree.api.custom_field_serializer },
              if: proc { expand?('custom_fields') }

data/app/serializers/spree/api/v3/claim_line_item_serializer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class ClaimLineItemSerializer < BaseSerializer
+        typelize quantity: :number,
+                 send_replacement: :boolean,
+                 refund_amount: :string,
+                 display_refund_amount: :string,
+                 paid_amount: :string,
+                 description: [:string, nullable: true],
+                 variant_id: [:string, nullable: true],
+                 replacement_variant_id: [:string, nullable: true],
+                 line_item_id: [:string, nullable: true]
+
+        attributes :quantity, :send_replacement, :description
+
+        attribute :refund_amount do |line|
+          line.refund_amount.to_s
+        end
+
+        # What the customer actually paid for these units — the ceiling the
+        # resolve workflow enforces, and what the dashboard offers when the
+        # claim carries no explicit amount.
+        attribute :paid_amount do |line|
+          line.paid_amount.to_s
+        end
+
+        attribute :display_refund_amount do |line|
+          line.display_refund_amount.to_s
+        end
+
+        attribute :variant_id do |line|
+          line.variant&.prefixed_id
+        end
+
+        attribute :replacement_variant_id do |line|
+          line.replacement_variant&.prefixed_id
+        end
+
+        attribute :line_item_id do |line|
+          line.line_item&.prefixed_id
+        end
+
+        one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/claim_reason_serializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # What went wrong with a delivery. Embedded in claims so a customer sees
+      # the reason's name rather than only its id; the vocabulary itself has
+      # no Store API controller of its own.
+      #
+      # Parallel to ReturnReasonSerializer rather than sharing a base class:
+      # Typelizer emits one TS type per serializer, so a shared parent would
+      # publish an abstract `Reason` type that no endpoint returns.
+      class ClaimReasonSerializer < BaseSerializer
+        typelize name: :string, active: :boolean
+
+        attributes :name, :active
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/claim_serializer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Customer-facing view of a claim.
+      class ClaimSerializer < BaseSerializer
+        typelize number: :string,
+                 status: [:string, enum: Spree::Claim.statuses, enum_type_name: 'ClaimStatus'],
+                 resolution: [:string, nullable: true],
+                 order_id: [:string, nullable: true],
+                 reason_id: [:string, nullable: true],
+                 refund_total: :string,
+                 display_refund_total: :string,
+                 approved_at: [:string, nullable: true],
+                 resolved_at: [:string, nullable: true],
+                 denied_at: [:string, nullable: true],
+                 canceled_at: [:string, nullable: true]
+
+        attributes :number, :status, :resolution
+
+        attribute :order_id do |claim|
+          claim.order&.prefixed_id
+        end
+
+        attribute :reason_id do |claim|
+          claim.reason&.prefixed_id
+        end
+
+        attribute :refund_total do |claim|
+          claim.refund_total.to_s
+        end
+
+        attribute :display_refund_total do |claim|
+          claim.display_refund_total.to_s
+        end
+
+        attribute :approved_at do |claim|
+          claim.approved_at&.iso8601
+        end
+
+        attribute :resolved_at do |claim|
+          claim.resolved_at&.iso8601
+        end
+
+        attribute :denied_at do |claim|
+          claim.denied_at&.iso8601
+        end
+
+        attribute :canceled_at do |claim|
+          claim.canceled_at&.iso8601
+        end
+
+        one :reason, resource: proc { Spree.api.claim_reason_serializer }, if: proc { expand?('reason') }
+
+        many :claim_line_items,
+             resource: proc { Spree.api.claim_line_item_serializer },
+             if: proc { expand?('claim_line_items') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/collection_serializer.rb

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      # Store (customer-facing) collection serializer. Deliberately omits the
+      # merchandising config — automatic / rules_match_policy / rules — which is
+      # back-office state exposed only by the Admin serializer.
+      class CollectionSerializer < BaseSerializer
+        typelize name: :string, permalink: :string, position: :number,
+                 sort_order: :string,
+                 meta_title: [:string, nullable: true], meta_description: [:string, nullable: true], meta_keywords: [:string, nullable: true],
+                 description: :string, description_html: :string,
+                 image_url: [:string, nullable: true], square_image_url: [:string, nullable: true],
+                 products_count: :number
+
+        attributes :name, :permalink, :position, :sort_order,
+                   :meta_title, :meta_description, :meta_keywords, :products_count
+
+        attribute :description do |collection|
+          Spree::RichTextHelper.to_plain_text(collection.description)
+        end
+
+        attribute :description_html do |collection|
+          collection.description_html
+        end
+
+        attribute :image_url do |collection|
+          image_url_for(collection.image)
+        end
+
+        attribute :square_image_url do |collection|
+          image_url_for(collection.square_image)
+        end
+
+        many :storefront_custom_fields,
+             key: :custom_fields,
+             resource: proc { Spree.api.custom_field_serializer },
+             if: proc { expand?('custom_fields') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/company_invitation_serializer.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Api
+    module V3
+      # A pending (or spent) invitation into a company node. The token is
+      # deliberately absent — it travels only in the invite email.
+      class CompanyInvitationSerializer < BaseSerializer
+        typelize email: :string, company_id: :string, status: [:string, enum: %w[pending accepted revoked expired]],
+                 expires_at: [:string, nullable: true]
+
+        attributes :email, expires_at: :iso8601
+
+        attribute :company_id do |invitation|
+          invitation.company.prefixed_id
+        end
+
+        # Derived, not a column: expiry is a date fact, acceptance and
+        # revocation are stamps.
+        attribute :status do |invitation|
+          if invitation.accepted? then 'accepted'
+          elsif invitation.revoked? then 'revoked'
+          elsif invitation.expired? then 'expired'
+          else 'pending'
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/company_membership_serializer.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Api
+    module V3
+      # A person with standing over a company node, as the storefront
+      # self-service surface lists them. Within a company OSS trusts every
+      # member, so members see each other.
+      class CompanyMembershipSerializer < BaseSerializer
+        typelize company_id: :string, customer_id: :string,
+                 email: [:string, nullable: true]
+
+        # Both associations are required, so these are never null and the
+        # types above say so.
+        attribute :company_id do |membership|
+          membership.company.prefixed_id
+        end
+
+        attribute :customer_id do |membership|
+          membership.customer.prefixed_id
+        end
+
+        # Lists members by who they are without a customer request per row.
+        attribute :email do |membership|
+          membership.customer.email
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/company_serializer.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Api
+    module V3
+      # The company node as members and event subscribers see it: the
+      # storefront self-service surface renders it directly, lifecycle events
+      # use it as their payload, and the admin serializer extends it so
+      # back-office fields stay in one place.
+      class CompanySerializer < BaseSerializer
+        typelize name: :string,
+                 kind: [:string, enum: Spree::Company::KINDS], parent_id: [:string, nullable: true],
+                 po_number_required: :boolean,
+                 ancestors: 'Array<{id: string, name: string, kind: string}>'
+
+        # `po_number_required` is buyer-facing by design: the checkout marks
+        # the PO field required from it.
+        attributes :name, :kind, :po_number_required
+
+        attribute :parent_id do |company|
+          company.parent&.prefixed_id
+        end
+
+        # The path above this node, root first — lets a client render
+        # "Acme / EMEA / Berlin" without a request per level. Bounded by the
+        # tree's depth cap.
+        attribute :ancestors do |company|
+          company.ancestors.reverse.map do |node|
+            { 'id' => node.prefixed_id, 'name' => node.name, 'kind' => node.kind }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,8 +6,8 @@ module Spree
       class CustomFieldSerializer < BaseSerializer
         typelize key: :string,
                  label: :string,
-                 type: [:string, deprecated: 'Use `field_type` instead. The legacy `type` field returns the Ruby STI class name (e.g. `Spree::Metafields::ShortText`) and will be removed in a future minor.'],
-                 field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
+                 type: [:string, deprecated: 'Use `field_type` instead. The legacy `type` field returns the Ruby STI class name (e.g. `Spree::CustomFields::ShortText`) and will be removed in a future minor.'],
+                 field_type: Spree::CustomField::FIELD_TYPE_TOKENS,
                  value: :any
 
         attributes :label, :type, :field_type

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

@@ -9,10 +9,18 @@ module Spree
                  phone: [:string, nullable: true], accepts_email_marketing: :boolean,
                  available_store_credit_total: :string, display_available_store_credit_total: :string,
                  default_billing_address: { nullable: true }, default_shipping_address: { nullable: true },
-                 newsletter_subscriber: { nullable: true }
+                 newsletter_subscriber: { nullable: true },
+                 email_marketing_consent_updated_at: [:string, nullable: true]
 
         attributes :email, :first_name, :last_name, :phone, :accepts_email_marketing
 
+        # When the opt-in last moved. Customer-facing because a person asking
+        # "when did I agree to this?" is exercising a right, not reading
+        # operational data.
+        attribute :email_marketing_consent_updated_at do |user|
+          user.email_marketing_consent_updated_at&.iso8601
+        end
+
         attribute :full_name do |user|
           user.full_name.presence || user.email
         end

data/app/serializers/spree/api/v3/data_request_event_serializer.rb

@@ -0,0 +1,30 @@
+module Spree
+  module Api
+    module V3
+      # The event shape for `data_request.*`.
+      #
+      # Deliberately not the store serializer: that one carries `download_url`,
+      # a working unauthenticated link to a person's entire personal-data
+      # export. An event goes to every subscribed endpoint and is persisted in
+      # the delivery log, so a subscriber would receive the credential and a
+      # copy would sit in a queryable admin-readable column for the life of the
+      # log. Subscribers get the fact that a request finished; fetching the
+      # file stays an authenticated act by the person it belongs to.
+      class DataRequestEventSerializer < BaseSerializer
+        typelize number: :string, kind: [:string, enum: Spree::DataRequest::KINDS], status: [:string, enum: Spree::DataRequest.statuses, enum_type_name: 'DataRequestStatus'],
+                 requested_at: [:string, nullable: true],
+                 completed_at: [:string, nullable: true]
+
+        attributes :number, :kind, :status
+
+        attribute :requested_at do |data_request|
+          data_request.requested_at&.iso8601
+        end
+
+        attribute :completed_at do |data_request|
+          data_request.completed_at&.iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/data_request_serializer.rb

@@ -0,0 +1,40 @@
+module Spree
+  module Api
+    module V3
+      # Store API Data Request Serializer
+      # A customer's own GDPR access or erasure request.
+      class DataRequestSerializer < BaseSerializer
+        typelize number: :string, kind: [:string, enum: Spree::DataRequest::KINDS], status: [:string, enum: Spree::DataRequest.statuses, enum_type_name: 'DataRequestStatus'],
+                 requested_at: [:string, nullable: true],
+                 completed_at: [:string, nullable: true],
+                 expires_at: [:string, nullable: true],
+                 download_url: [:string, nullable: true]
+
+        attributes :number, :kind, :status
+
+        attribute :requested_at do |data_request|
+          data_request.requested_at&.iso8601
+        end
+
+        attribute :completed_at do |data_request|
+          data_request.completed_at&.iso8601
+        end
+
+        attribute :expires_at do |data_request|
+          data_request.expires_at&.iso8601
+        end
+
+        # Present only while the file is still there — a link the storefront
+        # can render without having to reason about expiry itself.
+        attribute :download_url do |data_request, params|
+          next nil unless data_request.downloadable?
+
+          host = (params&.dig(:store) || data_request.store)&.formatted_url
+          next nil if host.blank?
+
+          Spree::Api::DataRequestUrls.download_url(data_request, host)
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/delivery_method_serializer.rb

@@ -2,9 +2,19 @@ module Spree
   module Api
     module V3
       class DeliveryMethodSerializer < BaseSerializer
-        typelize name: :string, code: [:string, nullable: true]
+        typelize name: :string, code: [:string, nullable: true],
+                 digital: :boolean, pickup: :boolean, pickup_point: :boolean,
+                 estimated_transit_business_days_min: [:number, nullable: true],
+                 estimated_transit_business_days_max: [:number, nullable: true]
 
-        attributes :name, :code
+        attributes :name, :code,
+                   :estimated_transit_business_days_min, :estimated_transit_business_days_max
+
+        # Derived from the fulfillment provider class — the storefront needs
+        # the delivery kind to render the right checkout affordances.
+        attribute :digital, &:digital?
+        attribute :pickup, &:pickup?
+        attribute :pickup_point, &:pickup_point?
       end
     end
   end

data/app/serializers/spree/api/v3/delivery_rate_serializer.rb

@@ -7,38 +7,55 @@ module Spree
                  total: :string, display_total: :string,
                  additional_tax_total: :string, display_additional_tax_total: :string,
                  included_tax_total: :string, display_included_tax_total: :string,
-                 tax_total: :string, display_tax_total: :string
-
-        attribute :delivery_method_id do |shipping_rate|
-          shipping_rate.shipping_method&.prefixed_id
+                 tax_total: :string, display_tax_total: :string,
+                 carrier: [:string, nullable: true],
+                 service_level: [:string, nullable: true],
+                 estimated_delivery_date: [:string, nullable: true],
+                 unpriced: :boolean,
+                 freight_summary: [:FreightSummary, nullable: true]
+
+        attribute :delivery_method_id do |deliver_rate|
+          deliver_rate.delivery_method&.prefixed_id
         end
 
+        # Carrier, service level and delivery date come from the rate provider
+        # and are what the customer chooses between; nil on calculator-priced
+        # methods. Provider metadata stays admin-only.
         attributes :name, :selected,
                    :cost, :total,
                    :additional_tax_total, :included_tax_total,
-                   :tax_total
-
-        attribute :display_cost do |shipping_rate|
-          shipping_rate.display_cost.to_s
+                   :tax_total,
+                   :carrier, :service_level, :estimated_delivery_date,
+                   :unpriced
+
+        # What the shipment looks like to a freight forwarder — cartons,
+        # pallets, cubic meters, gross weight. Present only on freight rates;
+        # it is what a buyer sees in place of a price they cannot be quoted
+        # yet, and stays readable on the placed order because the provider
+        # froze it here when it quoted.
+        one :freight_summary, resource: proc { Spree.api.freight_summary_serializer }
+
+        attribute :display_cost do |deliver_rate|
+          deliver_rate.display_cost.to_s
         end
 
-        attribute :display_total do |shipping_rate|
-          shipping_rate.display_total.to_s
+        attribute :display_total do |deliver_rate|
+          deliver_rate.display_total.to_s
         end
 
-        attribute :display_additional_tax_total do |shipping_rate|
-          shipping_rate.display_additional_tax_total.to_s
+        attribute :display_additional_tax_total do |deliver_rate|
+          deliver_rate.display_additional_tax_total.to_s
         end
 
-        attribute :display_included_tax_total do |shipping_rate|
-          shipping_rate.display_included_tax_total.to_s
+        attribute :display_included_tax_total do |deliver_rate|
+          deliver_rate.display_included_tax_total.to_s
         end
 
-        attribute :display_tax_total do |shipping_rate|
-          shipping_rate.display_tax_total.to_s
+        attribute :display_tax_total do |deliver_rate|
+          deliver_rate.display_tax_total.to_s
         end
 
-        one :shipping_method, key: :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
+        one :delivery_method, resource: proc { Spree.api.delivery_method_serializer }
       end
     end
   end

data/app/serializers/spree/api/v3/delivery_serializer.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      # One consignment's carrier journey — the customer's "where is my
+      # parcel" answer, so it sits on the public serializer beside the
+      # fulfillment's tracking summary.
+      class DeliverySerializer < BaseSerializer
+        typelize tracking_number: :string,
+                 tracking_url: [:string, nullable: true],
+                 carrier: [:string, nullable: true],
+                 carrier_name: [:string, nullable: true],
+                 service: [:string, nullable: true],
+                 status: [:string, enum: Spree::Delivery::STATUSES],
+                 estimated_delivery_at: [:string, nullable: true],
+                 delivered_at: [:string, nullable: true]
+
+        attributes :tracking_number, :carrier, :carrier_name, :service, :status
+
+        # The best link for this consignment: the one stored on the row, or
+        # the one derived from its carrier and number.
+        attribute :tracking_url do |delivery|
+          delivery.resolved_tracking_url
+        end
+
+        attributes estimated_delivery_at: :iso8601, delivered_at: :iso8601
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/delivery_zone_member_serializer.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      class DeliveryZoneMemberSerializer < BaseSerializer
+        typelize member_type: [:string, enum: Spree::DeliveryZoneMember::MEMBER_TYPES], country_code: [:string, nullable: true],
+                 country_name: [:string, nullable: true],
+                 state_code: [:string, nullable: true], state_name: [:string, nullable: true],
+                 postal_code_prefix: [:string, nullable: true],
+                 postal_code_from: [:string, nullable: true],
+                 postal_code_to: [:string, nullable: true]
+
+        attributes :member_type, :country_code, :state_code,
+                   :postal_code_prefix, :postal_code_from, :postal_code_to
+
+        # Admin zone summaries list countries by name; without this every
+        # client would have to carry its own ISO-to-name table.
+        attribute :country_name do |record|
+          record.country&.name
+        end
+
+        # The subdivision's name is reference data rather than something the
+        # member stores, so it is looked up from its country and code.
+        attribute :state_name do |record|
+          Spree::IsoData.subdivision_name(record.country_code, record.state_code) if record.state_code.present?
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/delivery_zone_serializer.rb

@@ -0,0 +1,13 @@
+module Spree
+  module Api
+    module V3
+      class DeliveryZoneSerializer < BaseSerializer
+        typelize name: :string, description: [:string, nullable: true]
+
+        attributes :name, :description
+
+        many :members, resource: proc { Spree.api.delivery_zone_member_serializer }, if: proc { expand?('members') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/digital_asset_serializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class DigitalAssetSerializer < BaseSerializer
+        typelize variant_id: [:string, nullable: true],
+                 filename: [:string, nullable: true],
+                 content_type: [:string, nullable: true]
+
+        attribute :variant_id do |digital_asset|
+          digital_asset.variant&.prefixed_id
+        end
+
+        attribute :filename do |digital_asset|
+          digital_asset.filename&.to_s
+        end
+
+        attributes :content_type
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/digital_link_serializer.rb

@@ -3,13 +3,17 @@ module Spree
     module V3
       class DigitalLinkSerializer < BaseSerializer
         typelize access_counter: :number, filename: :string, content_type: :string,
-                 download_url: :string,
+                 download_url: :string, expires_at: [:string, nullable: true],
                  authorizable: :boolean, expired: :boolean, access_limit_exceeded: :boolean
 
         attributes :access_counter, :filename, :content_type
 
         attribute :download_url do |digital_link|
-          Spree::Core::Engine.routes.url_helpers.api_v3_store_digital_download_path(token: digital_link.token)
+          Spree::Api::DigitalLinkUrls.download_path(digital_link)
+        end
+
+        attribute :expires_at do |digital_link|
+          digital_link.expires_at&.iso8601
         end
 
         attribute :authorizable do |digital_link|

data/app/serializers/spree/api/v3/discount_serializer.rb

@@ -1,20 +1,34 @@
 module Spree
   module Api
     module V3
-      # Unified discount serializer for applied promotions on Cart and Order.
-      # Replaces CartPromotionSerializer and OrderPromotionSerializer.
+      # A typed Spree::Discount money row (promotion-sourced or manual) on a
+      # line item or fulfillment. The embedded `discounts` key on Cart/Order
+      # stays the applied-promotion summary — see AppliedPromotionSerializer.
       class DiscountSerializer < BaseSerializer
-        typelize name: :string, description: [:string, nullable: true], code: [:string, nullable: true],
-                 amount: [:string, nullable: true], display_amount: [:string, nullable: true], promotion_id: :string
+        typelize label: :string, kind: [:string, enum: Spree::Discount::KINDS], code: [:string, nullable: true],
+                 value: [:string, nullable: true], value_type: [:string, nullable: true],
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true],
+                 promotion_id: [:string, nullable: true], line_item_id: [:string, nullable: true],
+                 fulfillment_id: [:string, nullable: true]
+
+        attributes :label, :kind, :code, :value_type
+
+        attribute :value do |record|
+          record.value&.to_s
+        end
 
         attribute :promotion_id do |record|
           record.promotion&.prefixed_id
         end
 
-        attributes :name, :description, :code
+        attribute :line_item_id do |record|
+          record.line_item&.prefixed_id
+        end
+
+        attribute :fulfillment_id do |record|
+          record.fulfillment&.prefixed_id
+        end
 
-        # Nulled for gated (prices_hidden) guests so an applied discount can't
-        # leak the amount the cart/order totals already withhold.
         money_attributes :amount, :display_amount
       end
     end