spree_emails 6.0.0.beta4 → 6.0.0.rc1

data/app/serializers/spree/emails/fulfillment_group_serializer.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Emails
+    # One real parcel of a purchase: what it carries, who sold it and what it
+    # cost to deliver.
+    class FulfillmentGroupSerializer
+      include Alba::Resource
+
+      attributes :name
+
+      attribute :display_cost do |group|
+        group.display_cost.to_s
+      end
+
+      attribute :seller_names do |group|
+        group.sellers.map(&:name)
+      end
+
+      many :manifest, key: :items, source: proc { manifest.select(&:line_item) },
+                     resource: Spree::Emails::ParcelItemSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/fulfillment_serializer.rb

@@ -0,0 +1,19 @@
+module Spree
+  module Emails
+    class FulfillmentSerializer < Spree::Api::V3::FulfillmentSerializer
+      typelize delivery_method_name: [:string, nullable: true]
+
+      attribute :delivery_method_name do |fulfillment|
+        fulfillment.delivery_method&.name
+      end
+
+      many :deliveries, resource: Spree::Emails::DeliverySerializer
+      one :delivery_method, resource: Spree::Emails::DeliveryMethodSerializer
+      one :stock_location, resource: Spree::Emails::StockLocationSerializer
+      many :delivery_rates, resource: Spree::Emails::DeliveryRateSerializer
+
+      many :manifest, key: :manifest_items, source: proc { manifest.select(&:line_item) },
+                     resource: Spree::Emails::ParcelItemSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/gift_card_serializer.rb

@@ -0,0 +1,6 @@
+module Spree
+  module Emails
+    class GiftCardSerializer < Spree::Api::V3::GiftCardSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/line_item_serializer.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Emails
+    class LineItemSerializer < Spree::Api::V3::LineItemSerializer
+      include Spree::Emails::PurchasedItemAttributes
+
+      many :option_values, resource: Spree::Emails::OptionValueSerializer
+
+      typelize sku: [:string, nullable: true], display_amount: :string,
+               url: [:string, nullable: true], image_url: [:string, nullable: true]
+
+      attributes :sku
+
+      # Price times quantity, before discounts — what the line cost.
+      attribute :display_amount do |line_item|
+        line_item.display_amount.to_s
+      end
+
+      # The full-size image; emails show the thumbnail in `image_url`.
+      attributes :thumbnail_url, if: proc { false }
+    end
+  end
+end

data/app/serializers/spree/emails/market_serializer.rb

@@ -0,0 +1,6 @@
+module Spree
+  module Emails
+    class MarketSerializer < Spree::Api::V3::MarketSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/option_value_serializer.rb

@@ -0,0 +1,6 @@
+module Spree
+  module Emails
+    class OptionValueSerializer < Spree::Api::V3::OptionValueSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/order_group_serializer.rb

@@ -0,0 +1,60 @@
+module Spree
+  module Emails
+    # A purchase that divided into several orders, as its confirmation reads
+    # it: every item, the parcels it ships in, and one set of totals.
+    class OrderGroupSerializer < Spree::Api::V3::OrderGroupSerializer
+      include Spree::Emails::PurchaseSummaryAttributes
+
+      typelize po_number: [:string, nullable: true], order_count: :number,
+               delivery_total: :string, display_delivery_total: :string,
+               additional_tax_total: :string, display_additional_tax_total: :string,
+               gift_card_total: :string, display_gift_card_total: :string
+
+      attributes :po_number
+
+      attribute :order_count do |group|
+        group.orders.size
+      end
+
+      attribute :display_delivery_total do |group|
+        group.display_delivery_total.to_s
+      end
+
+      attribute :delivery_total do |group|
+        group.delivery_total.to_s
+      end
+
+      attribute :additional_tax_total do |group|
+        group.additional_tax_total.to_s
+      end
+
+      attribute :display_additional_tax_total do |group|
+        group.display_additional_tax_total.to_s
+      end
+
+      attribute :gift_card_total do |group|
+        group.gift_card_total.to_s
+      end
+
+      attribute :display_gift_card_total do |group|
+        group.display_gift_card_total.to_s
+      end
+
+      # Every child order in full is what the webhook payload carries; the
+      # email reads the purchase-wide fields above instead.
+      many :orders, resource: proc { Spree.api.order_serializer }, if: proc { false }
+
+      many :fulfillment_groups, resource: Spree::Emails::FulfillmentGroupSerializer
+
+      # What no parcel carries — a download, an emailed gift card.
+      many :unfulfilled_items,
+           source: proc { unfulfilled_line_items },
+           resource: Spree::Emails::LineItemSerializer
+
+      # One delivery row for the whole purchase; the parcels break it down.
+      many :delivery_lines,
+           source: proc { delivery_total.zero? ? [] : [Spree::Emails::AmountLine.new(amount: delivery_total, currency: currency)] },
+           resource: Spree::Emails::AmountLineSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/order_serializer.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Emails
+    # An order as its emails read it: the Store API order plus what only an
+    # email shows — who to greet, the summary rows and line thumbnails.
+    class OrderSerializer < Spree::Api::V3::OrderSerializer
+      include Spree::Emails::PurchaseSummaryAttributes
+
+      many :order_promotions, key: :discounts, resource: Spree::Emails::AppliedPromotionSerializer
+      many :fees, resource: Spree::Emails::FeeSerializer
+      many :fulfillments, resource: Spree::Emails::FulfillmentSerializer
+      many :payments, resource: Spree::Emails::PaymentSerializer
+      one :gift_card, resource: Spree::Emails::GiftCardSerializer
+      one :market, resource: Spree::Emails::MarketSerializer
+
+      # One row per delivery rate, at its cost before discounts, so the rows
+      # add up to the total once a free-delivery promotion is listed.
+      many :delivery_lines,
+           source: proc {
+             Spree::Emails::AmountLine.group(fulfillments, currency: currency, amount: :cost, keep_zero: true,
+                                                           label: ->(fulfillment) { fulfillment.selected_delivery_rate&.name })
+           },
+           resource: Spree::Emails::AmountLineSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/parcel_item_serializer.rb

@@ -0,0 +1,36 @@
+module Spree
+  module Emails
+    # One line as it travels in one parcel. A line packed from two warehouses
+    # rides in two parcels, so the quantity and amount are the parcel's share
+    # rather than the whole line's.
+    class ParcelItemSerializer < Spree::Emails::BaseSerializer
+      include Spree::Emails::PurchasedItemAttributes
+
+      attribute :id do |item|
+        item.line_item.prefixed_id
+      end
+
+      attribute :name do |item|
+        item.line_item.name
+      end
+
+      attributes :quantity
+
+      attribute :sku do |item|
+        item.line_item.sku
+      end
+
+      attribute :options_text do |item|
+        item.line_item.options_text
+      end
+
+      attribute :display_price do |item|
+        item.line_item.display_price.to_s
+      end
+
+      attribute :display_amount do |item|
+        Spree::Money.new(item.line_item.price * item.quantity, currency: item.line_item.currency).to_s
+      end
+    end
+  end
+end

data/app/serializers/spree/emails/payment_method_serializer.rb

@@ -0,0 +1,6 @@
+module Spree
+  module Emails
+    class PaymentMethodSerializer < Spree::Api::V3::PaymentMethodSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/payment_serializer.rb

@@ -0,0 +1,9 @@
+module Spree
+  module Emails
+    class PaymentSerializer < Spree::Api::V3::PaymentSerializer
+      typelize source: ['Record<string, unknown>', nullable: true]
+
+      one :payment_method, resource: Spree::Emails::PaymentMethodSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/purchase_summary_attributes.rb

@@ -0,0 +1,41 @@
+module Spree
+  module Emails
+    # What an email shows for a whole purchase — who to greet, the items and
+    # the summary rows — for both an order and a multi-seller purchase. The
+    # `spree/shared/purchase_totals` partial reads these names from either.
+    module PurchaseSummaryAttributes
+      extend ActiveSupport::Concern
+
+      included do
+        typelize customer_name: :string, display_total_minus_store_credits: :string
+
+        attribute :customer_name do |purchase|
+          purchase.name.presence || I18n.t('spree.customer')
+        end
+
+        attribute :display_total_minus_store_credits do |purchase|
+          purchase.display_total_minus_store_credits.to_s
+        end
+
+        many :line_items, key: :items, resource: Spree::Emails::LineItemSerializer
+        one :billing_address, resource: Spree::Emails::AddressSerializer
+        one :shipping_address, resource: Spree::Emails::AddressSerializer
+
+        many :promotion_discounts,
+             source: proc { Spree::Emails::AmountLine.group(discounts.promotion, currency: currency) },
+             resource: Spree::Emails::AmountLineSerializer
+
+        many :manual_discounts,
+             source: proc { Spree::Emails::AmountLine.group(discounts.manual, currency: currency) },
+             resource: Spree::Emails::AmountLineSerializer
+
+        # A multi-seller checkout apportions an order-level fee into one row
+        # per child, all under one label; summed back, it is the one charge the
+        # customer saw.
+        many :fee_lines,
+             source: proc { Spree::Emails::AmountLine.group(fees, currency: currency) },
+             resource: Spree::Emails::AmountLineSerializer
+      end
+    end
+  end
+end

data/app/serializers/spree/emails/purchased_item_attributes.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Emails
+    # What an email shows for a purchased line besides its Store API fields: a
+    # link to the product on the storefront and a thumbnail. Shared by the line
+    # item and parcel item serializers.
+    module PurchasedItemAttributes
+      extend ActiveSupport::Concern
+      include Spree::ImagesHelper
+
+      included do
+        attribute :url do |item|
+          product = purchased_line_item(item).product
+          "#{params[:storefront_url]}/products/#{product.slug}" if product
+        end
+
+        attribute :image_url do |item|
+          spree_image_url(purchased_line_item(item).thumbnail, variant: :small)
+        end
+      end
+
+      private
+
+      def purchased_line_item(item)
+        item.is_a?(Spree::LineItem) ? item : item.line_item
+      end
+    end
+  end
+end

data/app/serializers/spree/emails/return_serializer.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Emails
+    class ReturnSerializer < Spree::Api::V3::ReturnSerializer
+      typelize display_refunded_total: :string
+
+      # What was actually paid back — not the Store API's refund_total, which
+      # is the figure the return was expected to refund.
+      attribute :display_refunded_total do |return_record|
+        return_record.display_refunded_total.to_s
+      end
+
+      many :returned_items,
+           source: proc { return_line_items.filter_map(&:line_item).uniq },
+           resource: Spree::Emails::LineItemSerializer
+    end
+  end
+end

data/app/serializers/spree/emails/stock_location_serializer.rb

@@ -0,0 +1,6 @@
+module Spree
+  module Emails
+    class StockLocationSerializer < Spree::Api::V3::StockLocationSerializer
+    end
+  end
+end

data/app/services/spree/emails/samples/base.rb

@@ -0,0 +1,79 @@
+module Spree
+  module Emails
+    module Samples
+      # Builds what an email's template receives, for previewing a template
+      # and checking it before it is published: from the store's most recent
+      # matching record, or one the merchant picks. Values that would carry a
+      # token (reset, invitation, download links) are always placeholders.
+      class Base
+        # @return [String, nil] the kind of record the merchant can pick
+        #   ("order", "order_group", "fulfillment", "return"), or nil when the
+        #   email needs none
+        def self.record_type
+          nil
+        end
+
+        # @return [Array<String>] the permission keys a caller needs to see this
+        #   sample, since it shows a real record's data
+        def self.required_permissions
+          record_type ? %w[read_orders] : []
+        end
+
+        attr_reader :store, :record_id
+
+        # @param store [Spree::Store]
+        # @param record_id [String, nil] a prefixed id of the record to preview with
+        def initialize(store:, record_id: nil)
+          @store = store
+          @record_id = record_id.presence
+        end
+
+        # @return [Hash] the template's variables, before `store` and `locale` are added
+        def variables
+          raise NotImplementedError
+        end
+
+        # @param limit [Integer]
+        # @return [Array<Spree::EmailTemplates::SampleRecord>] the store's latest
+        #   records the email can be previewed with; empty when it needs none
+        def recent_records(limit: 5)
+          return [] unless self.class.record_type
+
+          records.limit(limit).map do |record|
+            Spree::EmailTemplates::SampleRecord.new(
+              id: record.prefixed_id, label: record.try(:number).presence || record.prefixed_id, created_at: record.created_at
+            )
+          end
+        end
+
+        # @return [String] the currency the email's amounts are in
+        def currency
+          (self.class.record_type && record.try(:currency)).presence || store.default_currency
+        end
+
+        protected
+
+        def record
+          @record ||= if record_id
+                        records.find_by_prefix_id!(record_id)
+                      else
+                        records.first || raise(Spree::EmailTemplates::NoSampleRecord, I18n.t('spree.email_templates.no_sample_record', record: self.class.record_type.to_s.humanize.downcase))
+                      end
+        end
+
+        # Every lookup goes through the store, so another store's record never answers.
+        def records
+          raise NotImplementedError
+        end
+
+        def data(object, serializer)
+          Spree::Emails::TemplateData.call(object, serializer, store: store, currency: currency)
+        end
+
+        def placeholder_url(path)
+          "#{store.storefront_url.to_s.chomp('/')}/#{path}?token=preview"
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/company_invitation.rb

@@ -0,0 +1,19 @@
+module Spree
+  module Emails
+    module Samples
+      class CompanyInvitation < Base
+        def self.required_permissions
+          %w[read_customers]
+        end
+
+        def variables
+          {
+            company: data(store.companies.order(created_at: :desc).first || Spree::Company.new(name: 'Acme Corporation', store: store),
+                          Spree.api.company_serializer),
+            accept_url: placeholder_url('account/company-invitation')
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/data_export.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Emails
+    module Samples
+      class DataExport < Base
+        def variables
+          { download_url: placeholder_url('account/data-export'), expires_at: 7.days.from_now.iso8601 }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/downloads.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Emails
+    module Samples
+      # The files-ready email. Lists the order's own downloads when it has any,
+      # always with placeholder links.
+      class Downloads < Order
+        def variables
+          {
+            order: data(record, Spree::Emails::OrderSerializer),
+            downloads: downloads,
+            resend: false
+          }
+        end
+
+        private
+
+        def downloads
+          links = record.digital_links.includes(digital_asset: { attachment_attachment: :blob }).to_a
+          return [{ filename: 'guide.pdf', url: placeholder_url('downloads'), expires_at: nil }] if links.empty?
+
+          links.map do |link|
+            { filename: link.filename.to_s, url: placeholder_url('downloads'), expires_at: link.expires_at&.iso8601 }
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/fulfillment.rb

@@ -0,0 +1,33 @@
+module Spree
+  module Emails
+    module Samples
+      class Fulfillment < Base
+        def self.required_permissions
+          %w[read_orders read_fulfillments]
+        end
+
+        def self.record_type
+          'fulfillment'
+        end
+
+        def variables
+          {
+            fulfillment: data(record, Spree::Emails::FulfillmentSerializer),
+            order: data(record.order, Spree::Emails::OrderSerializer),
+            resend: false
+          }
+        end
+
+        def currency
+          record.order.currency
+        end
+
+        protected
+
+        def records
+          store.fulfillments.order(created_at: :desc)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/newsletter_confirmation.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Emails
+    module Samples
+      class NewsletterConfirmation < Base
+        def variables
+          { confirmation_url: placeholder_url('newsletter/confirm') }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/order.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Emails
+    module Samples
+      # Order confirmation and cancellation.
+      class Order < Base
+        def self.record_type
+          'order'
+        end
+
+        def variables
+          { order: data(record, Spree::Emails::OrderSerializer), resend: false }
+        end
+
+        protected
+
+        def records
+          store.orders.complete.order(completed_at: :desc)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/order_group.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Emails
+    module Samples
+      # The confirmation of a purchase that divided into several orders.
+      class OrderGroup < Base
+        def self.record_type
+          'order_group'
+        end
+
+        def variables
+          { order_group: data(record, Spree::Emails::OrderGroupSerializer), resend: false }
+        end
+
+        protected
+
+        def records
+          store.order_groups.order(created_at: :desc)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/password_reset.rb

@@ -0,0 +1,15 @@
+module Spree
+  module Emails
+    module Samples
+      class PasswordReset < Base
+        def variables
+          {
+            customer: data(Spree.customer_class.new(first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com'),
+                           Spree.api.customer_serializer),
+            reset_url: placeholder_url('account/reset-password')
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/payment_link.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Emails
+    module Samples
+      class PaymentLink < Order
+        def variables
+          { order: data(record, Spree::Emails::OrderSerializer), payment_url: placeholder_url('checkout/payment') }
+        end
+
+        protected
+
+        def records
+          store.orders.order(created_at: :desc)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/emails/samples/return.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Emails
+    module Samples
+      class Return < Base
+        def self.record_type
+          'return'
+        end
+
+        def variables
+          {
+            return: data(record, Spree::Emails::ReturnSerializer),
+            order: data(record.order, Spree::Emails::OrderSerializer),
+            resend: false
+          }
+        end
+
+        def currency
+          record.order.currency
+        end
+
+        protected
+
+        def records
+          store.returns.order(created_at: :desc)
+        end
+      end
+    end
+  end
+end

data/app/subscribers/spree/order_email_subscriber.rb

@@ -20,7 +20,7 @@ module Spree
 
     def send_customer_confirmation(order, event)
       return if order.confirmation_delivered?
-      return if event.payload['notify_customer'] == false
+      return if event.metadata['notify_customer'] == false
       return unless order.store.prefers_send_consumer_transactional_emails?
 
       OrderMailer.confirm_email(order.id).deliver_later
@@ -46,7 +46,7 @@ module Spree
     def send_cancel_email(event)
       order = find_order(event)
       return unless order
-      return if event.payload['notify_customer'] == false
+      return if event.metadata['notify_customer'] == false
 
       store = order.store
       return unless store.prefers_send_consumer_transactional_emails?

data/app/subscribers/spree/order_group_email_subscriber.rb

@@ -27,7 +27,7 @@ module Spree
     # about the sale.
     def send_customer_confirmation(order_group, event)
       return if order_group.confirmation_delivered?
-      return if event.payload['notify_customer'] == false
+      return if event.metadata['notify_customer'] == false
       return unless order_group.store.prefers_send_consumer_transactional_emails?
 
       OrderGroupMailer.confirm_email(order_group.id).deliver_later

data/app/subscribers/spree/return_email_subscriber.rb

@@ -10,6 +10,8 @@ module Spree
 
       store = return_record.store
       return unless store.prefers_send_consumer_transactional_emails?
+      # A return owed nothing closes without a refund, so there is none to announce.
+      return if return_record.refunded_total.zero?
 
       ReturnMailer.refunded_email(return_record.id).deliver_later
     end