spree-paypal_platform 5.0.1

data/app/presenters/spree/paypal_checkout/order_presenter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'paypal_server_sdk'
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Builds a PayPal Orders API create-order payload from a Spree order.
+    #
+    # The storefront owns the address: we send `purchase_units[].shipping`
+    # from `order.ship_address` and pin it with `SET_PROVIDED_ADDRESS` so
+    # PayPal does not re-collect it. The amount breakdown sends only
+    # `additional_tax_total` — sending full `tax_total` double-counts
+    # included VAT and trips PayPal `AMOUNT_MISMATCH`.
+    #
+    class OrderPresenter
+      PAYPAL_ITEM_NAME_MAX_LENGTH = 127
+
+      ##
+      # @param order [Spree::Order]
+      #
+      def initialize(order)
+        @order = order
+      end
+
+      attr_reader :order
+
+      ##
+      # @return [Hash] body ready for `client.orders.create_order`
+      #
+      def to_json(*_args)
+        {
+          'body' => PaypalServerSdk::OrderRequest.new(
+            intent: PaypalServerSdk::CheckoutPaymentIntent::CAPTURE,
+            purchase_units: [purchase_unit],
+            payment_source: payment_source
+          )
+        }
+      end
+
+      private
+
+      def purchase_unit
+        args = {
+          amount: amount_with_breakdown,
+          items: items
+        }
+        args[:shipping] = shipping_details if shipping_details
+
+        PaypalServerSdk::PurchaseUnitRequest.new(**args)
+      end
+
+      # NOTE: the breakdown only sends additional (non-included) tax — sending
+      # the full tax_total double-counts VAT on tax-inclusive markets and
+      # trips AMOUNT_MISMATCH. Do not change to order.tax_total.
+      def amount_with_breakdown
+        PaypalServerSdk::AmountWithBreakdown.new(
+          currency_code: order.currency.upcase,
+          value: order.total.to_s,
+          breakdown: PaypalServerSdk::AmountBreakdown.new(
+            item_total: paypal_money(order.item_total),
+            shipping: paypal_money(order.ship_total),
+            tax_total: paypal_money(order.additional_tax_total),
+            discount: paypal_money((order.promo_total || 0).abs)
+          )
+        )
+      end
+
+      def paypal_money(amount)
+        PaypalServerSdk::Money.new(
+          currency_code: order.currency.upcase,
+          value: amount.to_s
+        )
+      end
+
+      def items
+        order.line_items.map do |line_item|
+          PaypalServerSdk::Item.new(
+            name: line_item.name.to_s[0...PAYPAL_ITEM_NAME_MAX_LENGTH],
+            unit_amount: paypal_money(line_item.price),
+            quantity: line_item.quantity.to_s,
+            sku: line_item.sku,
+            category: line_item.variant.digital? ? PaypalServerSdk::ItemCategory::DIGITAL_GOODS : PaypalServerSdk::ItemCategory::PHYSICAL_GOODS
+          )
+        end
+      end
+
+      def shipping_details
+        address = order.ship_address
+        return nil if address.blank?
+
+        PaypalServerSdk::ShippingDetails.new(
+          name: PaypalServerSdk::ShippingName.new(full_name: address.full_name),
+          address: PaypalServerSdk::Address.new(
+            country_code: address.country&.iso,
+            address_line_1: address.address1,
+            address_line_2: address.address2.presence,
+            admin_area_2: address.city,
+            admin_area_1: region_code(address),
+            postal_code: address.zipcode
+          )
+        )
+      end
+
+      def region_code(address)
+        address.state&.abbr.presence || address.state_name.presence
+      end
+
+      def payment_source
+        PaypalServerSdk::PaymentSource.new(
+          paypal: PaypalServerSdk::PaypalWallet.new(
+            experience_context: PaypalServerSdk::PaypalWalletExperienceContext.new(
+              brand_name: order.store&.name,
+              shipping_preference: shipping_preference,
+              user_action: PaypalServerSdk::PaypalExperienceUserAction::PAY_NOW
+            )
+          )
+        )
+      end
+
+      def shipping_preference
+        if order.ship_address.present?
+          PaypalServerSdk::PaypalWalletContextShippingPreference::SET_PROVIDED_ADDRESS
+        else
+          PaypalServerSdk::PaypalWalletContextShippingPreference::NO_SHIPPING
+        end
+      end
+    end
+  end
+end

data/app/services/spree/paypal_checkout/capture_order.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Captures a legacy {Order} via the PayPal Orders API and completes
+    # the Spree checkout.
+    #
+    class CaptureOrder
+      ##
+      # @param paypal_order [Spree::PaypalCheckout::Order]
+      #
+      def initialize(paypal_order:)
+        @paypal_order = paypal_order
+        @order = paypal_order.order
+        @gateway = paypal_order.gateway
+        @amount = paypal_order.amount
+      end
+
+      attr_reader :paypal_order, :order, :gateway, :amount
+
+      ##
+      # @return [Spree::PaypalCheckout::Order]
+      #
+      def call
+        return paypal_order if order.completed? || order.canceled?
+
+        gateway_response = gateway.capture(
+          (amount.to_d * 100).to_i,
+          paypal_order.paypal_id,
+          { order_id: order.number }
+        )
+
+        order.with_lock do
+          paypal_order.update!(data: gateway_response.params)
+          paypal_order.create_payment!
+          Spree::Dependencies.checkout_complete_service.constantize.call(order: order)
+        end
+
+        paypal_order
+      end
+    end
+  end
+end

data/app/services/spree/paypal_checkout/create_payment.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Creates the Spree::Payment for a captured legacy PayPal order.
+    #
+    class CreatePayment
+      ##
+      # @param paypal_order [Spree::PaypalCheckout::Order]
+      # @param order [Spree::Order, NilClass]
+      # @param gateway [Spree::PaypalCheckout::Gateway, NilClass]
+      # @param amount [Numeric, NilClass]
+      #
+      def initialize(paypal_order:, order: nil, gateway: nil, amount: nil)
+        @paypal_order = paypal_order
+        @order = order || paypal_order.order
+        @gateway = gateway || paypal_order.gateway
+        @amount = amount || paypal_order.amount
+      end
+
+      ##
+      # @return [Spree::Payment]
+      #
+      def call
+        source = CreateSource.new(
+          paypal_payment_source: paypal_order.payment_source,
+          gateway: gateway,
+          order: order
+        ).call
+
+        payment = order.payments.find_or_initialize_by(
+          payment_method_id: gateway.id,
+          response_code: paypal_order.paypal_payment_id,
+          amount: amount
+        )
+
+        payment.source = source if source.present?
+        payment.state = 'completed'
+        payment.save!
+        payment
+      end
+
+      private
+
+      attr_reader :order, :gateway, :paypal_order, :amount
+    end
+  end
+end

data/app/services/spree/paypal_checkout/create_source.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Builds a {PaymentSources} record from a PayPal Orders `payment_source`.
+    #
+    # PayPal returns one of `paypal`, `apple_pay`, or `card` (Card Fields).
+    # Unknown keys raise so a new wallet is not silently dropped.
+    #
+    class CreateSource
+      ##
+      # @param paypal_payment_source [Hash]
+      # @param gateway [Spree::PaypalCheckout::Gateway]
+      # @param order [Spree::Order, NilClass]
+      # @param user [Spree::User, NilClass]
+      #
+      def initialize(paypal_payment_source:, gateway:, order: nil, user: nil)
+        @paypal_payment_source = paypal_payment_source.with_indifferent_access
+        @gateway = gateway
+        @user = user || order&.user
+        @order = order
+      end
+
+      ##
+      # @return [Spree::PaymentSource]
+      # @raise [ArgumentError] when the payload has no known wallet key
+      #
+      def call
+        if paypal_payment_source[:paypal].present?
+          create_paypal_source
+        elsif paypal_payment_source[:apple_pay].present?
+          create_apple_pay_source
+        elsif paypal_payment_source[:card].present?
+          create_card_source
+        else
+          raise ArgumentError, "Unsupported PayPal payment source: #{paypal_payment_source.keys.join(', ')}"
+        end
+      end
+
+      private
+
+      attr_reader :gateway, :user, :paypal_payment_source, :order
+
+      def create_paypal_source
+        wallet = paypal_payment_source[:paypal]
+        source = PaymentSources::Paypal.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: wallet[:account_id]
+        )
+        source.update!(
+          user: user,
+          email: wallet[:email_address],
+          name: full_name(wallet[:name]),
+          account_id: wallet[:account_id],
+          account_status: wallet[:account_status]
+        )
+        source
+      end
+
+      def create_apple_pay_source
+        wallet = paypal_payment_source[:apple_pay]
+        card = wallet[:card] || {}
+        profile_id = wallet[:id].presence ||
+                     wallet[:token].presence ||
+                     ['applepay', card[:brand], card[:last_digits]].compact.join('-')
+
+        source = PaymentSources::ApplePay.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: profile_id
+        )
+        source.update!(
+          user: user,
+          name: full_name(wallet[:name]).presence || wallet[:name],
+          email: wallet[:email_address],
+          card_brand: card[:brand],
+          last_digits: card[:last_digits],
+          card_type: card[:type]
+        )
+        source
+      end
+
+      def create_card_source
+        card = paypal_payment_source[:card]
+        profile_id = card[:id].presence || ['card', card[:brand], card[:last_digits]].compact.join('-')
+
+        source = PaymentSources::Card.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: profile_id
+        )
+        source.update!(
+          user: user,
+          name: card[:name],
+          card_brand: card[:brand],
+          last_digits: card[:last_digits],
+          card_type: card[:type]
+        )
+        source
+      end
+
+      def full_name(name)
+        return name if name.is_a?(String)
+        return '' if name.blank?
+
+        "#{name[:given_name]} #{name[:surname]}".strip
+      end
+    end
+  end
+end

data/app/views/spree/admin/payment_methods/configuration_guides/_spree_paypal_checkout.html.erb

@@ -0,0 +1,16 @@
+<div class="alert alert-info">
+  <p class="mb-0">
+    To find your <strong>Client ID</strong> and <strong>Client Secret</strong>, go to the
+    <%= external_link_to 'PayPal Developer Dashboard', 'https://developer.paypal.com/dashboard/', class: 'alert-link' %>.
+    For more information, see the <%= external_link_to 'PayPal REST API documentation', 'https://developer.paypal.com/api/rest/', class: 'alert-link' %>.
+  </p>
+</div>
+
+<div class="alert alert-info mt-3">
+  <p class="mb-0">
+    <strong>Apple Pay</strong> is a funding source of this same PayPal method, not a second payment method.
+    Register every storefront domain that will show the Apple Pay button in the
+    <%= external_link_to 'PayPal Apple Pay domain registration', 'https://developer.paypal.com/docs/checkout/apm/apple-pay/', class: 'alert-link' %>
+    dashboard, then set <em>Apple pay domain</em> below. The button only renders in Safari over HTTPS.
+  </p>
+</div>

data/app/views/spree/admin/payment_methods/descriptions/_spree_paypal_checkout.html.erb

@@ -0,0 +1,10 @@
+<p class="mb-1">
+  PayPal Checkout: wallet, Pay Later, Apple Pay, and Card Fields on one payment method.
+</p>
+
+<div class="d-flex align-items-center">
+  <%= payment_method_icon_tag 'paypal', class: 'm-1' %>
+  <%= payment_method_icon_tag 'visa', class: 'm-1' %>
+  <%= payment_method_icon_tag 'master', class: 'm-1' %>
+  <%= payment_method_icon_tag 'apple_pay', class: 'm-1' %>
+</div>

data/app/views/spree/admin/payments/source_forms/_spree_paypal_checkout.html.erb

@@ -0,0 +1,7 @@
+<% if previous_cards.any? %>
+  <%= render 'spree/admin/payments/source_forms/previous_cards', previous_cards: previous_cards, f: f %>
+<% else %>
+  <span class="text-gray-600">
+    <%= Spree.t(:no_payment_sources_available, default: 'No saved PayPal accounts available.') %>
+  </span>
+<% end %>

data/app/views/spree/payment_sources/_paypal_checkout.html.erb

@@ -0,0 +1,17 @@
+<p class="mb-0">
+  <%= source.try(:display_payment_info) || source.class.try(:display_name) %>
+</p>
+<% if source.respond_to?(:email) && source.email.present? %>
+  <p class="mb-0">
+    <%= source.email %>
+  </p>
+<% end %>
+<% if source.respond_to?(:account_status) && source.account_status.present? %>
+  <p class="mb-0">
+    <% if source.account_status == 'VERIFIED' %>
+      <code class="text-success"><%= source.account_status %></code>
+    <% else %>
+      <code class="text-danger"><%= source.account_status %></code>
+    <% end %>
+  </p>
+<% end %>

data/config/initializers/spree.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Must be after_initialize: spree_core assigns (does not append to)
+# config.spree.payment_methods in its own after_initialize, and a
+# file-scope registration here would be silently clobbered.
+Rails.application.config.after_initialize do
+  Rails.application.config.spree.payment_methods << Spree::PaypalCheckout::Gateway
+end

data/db/migrate/20250528095719_create_spree_paypal_checkout_orders.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateSpreePaypalCheckoutOrders < ActiveRecord::Migration[7.2]
+  def change
+    create_table :spree_paypal_checkout_orders do |t|
+      t.references :order, null: false
+      t.references :payment_method, null: false
+      t.string :paypal_id, null: false
+      t.decimal :amount, null: false, precision: 10, scale: 2
+
+      if t.respond_to? :jsonb
+        t.jsonb :data
+      else
+        t.json :data
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_paypal_checkout_orders, [:order_id, :paypal_id], unique: true
+  end
+end

data/db/migrate/20260817120000_rewrite_spree_paypal_checkout_sti_types.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class RewriteSpreePaypalCheckoutStiTypes < ActiveRecord::Migration[7.2]
+  # Hosts coming from the official / forked `spree_paypal_checkout` gem store
+  # `SpreePaypalCheckout::Gateway` (and `…::PaymentSources::Paypal`) in STI
+  # type columns. The new gem aliases those constants, so checkout keeps
+  # working before this migration runs; rewriting the strings makes the
+  # alias optional for the next deploy.
+  LEGACY_TO_CURRENT = {
+    'SpreePaypalCheckout::Gateway' => 'Spree::PaypalCheckout::Gateway',
+    'SpreePaypalCheckout::PaymentSources::Paypal' => 'Spree::PaypalCheckout::PaymentSources::Paypal',
+    'SpreePaypalCheckout::Order' => 'Spree::PaypalCheckout::Order'
+  }.freeze
+
+  def up
+    rewrite_column(:spree_payment_methods, :type)
+    rewrite_column(:spree_payment_sources, :type) if column_exists?(:spree_payment_sources, :type)
+  end
+
+  def down
+    rewrite_column(:spree_payment_methods, :type, LEGACY_TO_CURRENT.invert)
+    rewrite_column(:spree_payment_sources, :type, LEGACY_TO_CURRENT.invert) if column_exists?(:spree_payment_sources, :type)
+  end
+
+  private
+
+  def rewrite_column(table, column, mapping = LEGACY_TO_CURRENT)
+    mapping.each do |from, to|
+      reversible_update = "UPDATE #{table} SET #{column} = #{quote(to)} WHERE #{column} = #{quote(from)}"
+      execute reversible_update
+    end
+  end
+end

data/db/migrate/20260817130000_add_unique_index_on_paypal_checkout_order_paypal_id.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddUniqueIndexOnPaypalCheckoutOrderPaypalId < ActiveRecord::Migration[7.2]
+  def change
+    add_index :spree_paypal_checkout_orders, :paypal_id, unique: true
+  end
+end

data/lib/generators/spree/paypal_checkout/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    module Generators
+      ##
+      # Copies this gem's migrations into the host app and optionally runs them.
+      #
+      class InstallGenerator < Rails::Generators::Base
+        desc 'Copies Spree::PaypalCheckout migrations into the host application and runs them.'
+
+        class_option :auto_run_migrations,
+                     type: :boolean,
+                     default: false,
+                     desc: 'Run the copied migrations immediately instead of asking'
+
+        def copy_migrations
+          rake 'spree_paypal_checkout:install:migrations'
+        end
+
+        def run_migrations
+          if run_migrations?
+            rake 'db:migrate'
+          else
+            say_status :skip, 'db:migrate — remember to run it before using the gem', :yellow
+          end
+        end
+
+        private
+
+        def run_migrations?
+          return true if options[:auto_run_migrations]
+
+          ask('Run the migrations now? [Yn]').to_s.strip.casecmp('n') != 0
+        end
+      end
+    end
+  end
+end

data/lib/spree/paypal_checkout/engine.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Rails engine for the PayPal Checkout payment method.
+    #
+    class Engine < ::Rails::Engine
+      require 'spree/core'
+      isolate_namespace Spree
+
+      # Decorators reopen existing constants, so Zeitwerk must not autoload them.
+      initializer 'spree_paypal_checkout.ignore_decorators_from_zeitwerk', before: :setup_main_autoloader do
+        Rails.autoloaders.main.ignore(
+          File.join(File.dirname(__FILE__), '../../../app/**/*_decorator*.rb')
+        )
+      end
+
+      # engine_name generates route-helper prefixes and must be a valid Ruby
+      # identifier, so it cannot contain a dash.
+      engine_name 'spree_paypal_checkout'
+
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      ##
+      # Loads the gem's decorators. Called on every reload in development.
+      #
+      # @return [void]
+      #
+      def self.activate
+        Dir.glob(File.join(File.dirname(__FILE__), '../../../app/**/*_decorator*.rb')).each do |c|
+          Rails.configuration.cache_classes ? require(c) : load(c)
+        end
+      end
+
+      config.to_prepare(&method(:activate).to_proc)
+    end
+  end
+end

data/lib/spree/paypal_checkout/factories.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :paypal_checkout_gateway, class: 'Spree::PaypalCheckout::Gateway' do
+    name { 'PayPal Checkout' }
+    association :store, factory: :store
+    preferences do
+      {
+        client_id: ENV.fetch('PAYPAL_CLIENT_ID', 'client_id_test'),
+        client_secret: ENV.fetch('PAYPAL_CLIENT_SECRET', 'client_secret_test'),
+        test_mode: true,
+        enable_apple_pay: true
+      }
+    end
+  end
+
+  factory :paypal_checkout_payment_source, class: 'Spree::PaypalCheckout::PaymentSources::Paypal' do
+    association :payment_method, factory: :paypal_checkout_gateway
+    gateway_payment_profile_id { 'PAY-CUSTOMER-ID' }
+  end
+
+  factory :paypal_checkout_apple_pay_source, class: 'Spree::PaypalCheckout::PaymentSources::ApplePay' do
+    association :payment_method, factory: :paypal_checkout_gateway
+    gateway_payment_profile_id { 'APPLEPAY-TOKEN-1' }
+    card_brand { 'VISA' }
+    last_digits { '4242' }
+  end
+
+  factory :paypal_checkout_payment_session, class: 'Spree::PaymentSessions::PaypalCheckout' do
+    association :order, factory: :order
+    association :payment_method, factory: :paypal_checkout_gateway
+    amount { order.total }
+    currency { order.currency }
+    status { 'pending' }
+    external_id { "PAYPAL-ORDER-#{SecureRandom.hex(8).upcase}" }
+    external_data do
+      JSON.parse(File.read(Spree::PaypalCheckout::Engine.root.join('spec/fixtures/paypal_order.json')))
+    end
+
+    factory :completed_paypal_checkout_payment_session do
+      status { 'completed' }
+      external_data do
+        JSON.parse(File.read(Spree::PaypalCheckout::Engine.root.join('spec/fixtures/captured_paypal_order.json')))
+      end
+    end
+  end
+
+  factory :paypal_checkout_order, class: 'Spree::PaypalCheckout::Order' do
+    paypal_id { 'PAY-ORDER-ID' }
+    order { create(:order) }
+    payment_method { create(:paypal_checkout_gateway) }
+    amount { order.total }
+    data { JSON.parse(File.read(Spree::PaypalCheckout::Engine.root.join('spec/fixtures/paypal_order.json'))) }
+
+    factory :captured_paypal_checkout_order do
+      data { JSON.parse(File.read(Spree::PaypalCheckout::Engine.root.join('spec/fixtures/captured_paypal_order.json'))) }
+    end
+  end
+end

data/lib/spree/paypal_checkout/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    # Major version tracks Spree's major version: 5.x supports Spree 5.x.
+    VERSION = '5.0.1'
+  end
+end

data/lib/spree/paypal_checkout.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'spree_core'
+require 'paypal_server_sdk'
+require 'spree/paypal_checkout/version'
+require 'spree/paypal_checkout/engine'
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Table prefix for models nested under this module.
+    #
+    # Must live on the module, not on {Base}. ActiveRecord walks
+    # `module_parents` for `table_name_prefix` and finds `Spree` first
+    # (`"spree_"`) unless this closer parent defines it.
+    #
+    # @return [String]
+    #
+    def self.table_name_prefix
+      'spree_paypal_checkout_'
+    end
+
+    ##
+    # STI type names that count as this gem's gateway.
+    #
+    # Includes the historical `SpreePaypalCheckout::Gateway` string from the
+    # official / forked gem so existing payment-method rows keep matching
+    # after a host switches gems, even before the type-rewrite migration
+    # runs.
+    #
+    # @return [Array<String>]
+    #
+    def self.gateway_type_names
+      (
+        [Gateway.name, 'SpreePaypalCheckout::Gateway'] + Gateway.descendants.map(&:name)
+      ).uniq
+    end
+  end
+end
+
+# Historical top-level namespace from `spree_paypal_checkout`. Existing
+# `spree_payment_methods.type` / `spree_payment_sources.type` rows store
+# `SpreePaypalCheckout::…`; this alias lets those strings constantize
+# onto the new classes.
+SpreePaypalCheckout = Spree::PaypalCheckout

data/lib/spree-paypal_checkout.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its *name*, so `gem "spree-paypal_checkout"`
+# in a host Gemfile issues `require "spree-paypal_checkout"`. The real entry
+# point is `spree/paypal_checkout` (matching the Spree::PaypalCheckout
+# namespace), so this shim keeps the default `Bundler.require` working.
+require 'spree/paypal_checkout'

data/lib/spree-paypal_platform.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its *name*, so `gem "spree-paypal_platform"`
+# in a host Gemfile issues `require "spree-paypal_platform"`. The real entry
+# point is `spree/paypal_checkout` (matching the Spree::PaypalCheckout
+# namespace), so this shim keeps the default `Bundler.require` working.
+require 'spree/paypal_checkout'