Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Open source integrations (#12618)

Łukasz Adamczykba785ed661ba
diff --git a/admin/app/controllers/concerns/spree/admin/preferences_concern.rb b/admin/app/controllers/concerns/spree/admin/preferences_concern.rb
new file mode 100644
index 0000000000..f953888d70
--- /dev/null
+++ b/admin/app/controllers/concerns/spree/admin/preferences_concern.rb
@@ -0,0 +1,22 @@
+module Spree
+ module Admin
+ module PreferencesConcern
+ extend ActiveSupport::Concern
+
+ private
+
+ def clear_empty_password_preferences(param_name)
+ if params[param_name].present?
+ password_preferences = @object.preferences_of_type(:password)
+ password_preferences.each do |preference|
+ preference_key = "preferred_#{preference}"
+
+ if params.dig(param_name, preference_key).blank? && @object.preferences[preference].present?
+ params[param_name].delete(preference_key)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/admin/app/controllers/spree/admin/base_controller.rb b/admin/app/controllers/spree/admin/base_controller.rb
index 5e73025ab2..37714b6660 100644
--- a/admin/app/controllers/spree/admin/base_controller.rb
+++ b/admin/app/controllers/spree/admin/base_controller.rb
@@ -8,6 +8,7 @@ module Spree
helper 'spree/locale'
helper 'spree/currency'
helper 'spree/addresses'
+ helper 'spree/integrations'
before_action :authorize_admin
diff --git a/admin/app/controllers/spree/admin/integrations_controller.rb b/admin/app/controllers/spree/admin/integrations_controller.rb
new file mode 100644
index 0000000000..0e59e0c2b2
--- /dev/null
+++ b/admin/app/controllers/spree/admin/integrations_controller.rb
@@ -0,0 +1,54 @@
+module Spree
+ module Admin
+ class IntegrationsController < ResourceController
+ include Spree::Admin::PreferencesConcern
+
+ prepend_before_action :require_integration_type, only: %i[new create]
+ prepend_before_action :prevent_from_creating_more_integrations, only: %i[new create]
+
+ before_action -> { clear_empty_password_preferences(:integration) }, only: :update
+
+ before_action :check_if_can_connect, only: %i[create update]
+
+ private
+
+ def allowed_integration_types
+ @allowed_integration_types ||= Rails.application.config.spree.integrations.map { |klass| [klass.to_s, klass] }.to_h
+ end
+
+ def require_integration_type
+ redirect_to spree.admin_integrations_path unless params.dig(:integration, :type).present?
+ end
+
+ def prevent_from_creating_more_integrations
+ type = params.dig(:integration, :type)
+
+ if allowed_integration_types.key?(type) && allowed_integration_types[type].for_store(current_store).exists?
+ redirect_to spree.admin_integrations_path
+ end
+ end
+
+ def build_resource
+ return unless params[:integration].present?
+
+ type = params[:integration].delete(:type)
+
+ if allowed_integration_types.key?(type)
+ @object = allowed_integration_types[type].new
+ else
+ flash[:error] = Spree.t('admin.integrations.invalid_integration_type')
+ redirect_to spree.admin_integrations_path
+ end
+ end
+
+ def check_if_can_connect
+ @integration.attributes = permitted_resource_params
+
+ unless @integration.can_connect?
+ @integration.errors.add(:base, :unable_to_connect, error_message: @integration.connection_error_message)
+ render action == :create ? :new : :edit, status: :unprocessable_entity
+ end
+ end
+ end
+ end
+end
diff --git a/admin/app/controllers/spree/admin/payment_methods_controller.rb b/admin/app/controllers/spree/admin/payment_methods_controller.rb
index cf7fe2d383..4b1a302428 100644
--- a/admin/app/controllers/spree/admin/payment_methods_controller.rb
+++ b/admin/app/controllers/spree/admin/payment_methods_controller.rb
@@ -1,8 +1,10 @@
module Spree
module Admin
class PaymentMethodsController < ResourceController
+ include Spree::Admin::PreferencesConcern
+
prepend_before_action :require_payment_type, only: [:new, :create]
- before_action :clear_empty_password_preferences, only: :update
+ before_action -> { clear_empty_password_preferences(:payment_method) }, only: :update
private
@@ -27,19 +29,6 @@ module Spree
def require_payment_type
redirect_to spree.admin_payment_methods_path unless params.dig(:payment_method, :type).present?
end
-
- def clear_empty_password_preferences
- if params[:payment_method].present?
- password_preferences = @object.preferences_of_type(:password)
- password_preferences.each do |preference|
- preference_key = "preferred_#{preference}"
-
- if params.dig(:payment_method, preference_key).blank? && @object.preferences[preference].present?
- params[:payment_method].delete(preference_key)
- end
- end
- end
- end
end
end
end
diff --git a/admin/app/helpers/spree/admin/base_helper.rb b/admin/app/helpers/spree/admin/base_helper.rb
index 7e62421db8..d4ef00907d 100644
--- a/admin/app/helpers/spree/admin/base_helper.rb
+++ b/admin/app/helpers/spree/admin/base_helper.rb
@@ -199,37 +199,40 @@ module Spree
# renders all the preference fields for an object
# @param object [Spree::TaxRate, Spree::Calculator, Spree::PaymentMethod, Spree::ShippingMethod, Spree::Store] the object to render the preference fields for
# @param form [ActionView::Helpers::FormBuilder] the form builder
+ # @param i18n_scope [String] the i18n scope for the preference fields
# @return [String] the preference fields
- def preference_fields(object, form)
+ def preference_fields(object, form, i18n_scope: '')
return unless object.respond_to?(:preferences)
- fields = object.preferences.keys.map do |key|
- if object.has_preference?(key)
- case key
- when :currency
- content_tag(:div, form.label("preferred_#{key}", Spree.t(key)) +
- form.currency_select("preferred_#{key}", current_store.supported_currencies.split(','), {}, { class: 'custom-select', disabled: current_store.supported_currencies.split(',').count == 1 }),
- class: 'form-group', id: [object.class.to_s.parameterize, 'preference', key].join('-'))
- else
- if object.preference_type(key).to_sym == :boolean
- content_tag(:div, class: 'form-group custom-control custom-checkbox') do
- preference_field_for(form, "preferred_#{key}", type: object.preference_type(key)) +
- form.label(
- "preferred_#{key}",
- Spree.t(key),
- class: 'custom-control-label',
- id: [object.class.to_s.parameterize, 'preference', key].join('-')
- )
- end
- else
- content_tag(:div, form.label("preferred_#{key}", Spree.t(key)) +
- preference_field_for(form, "preferred_#{key}", type: object.preference_type(key)),
- class: 'form-group', id: [object.class.to_s.parameterize, 'preference', key].join('-'))
- end
+ fields = object.preferences.keys.map { |key| preference_field(object, form, key, i18n_scope: i18n_scope) }
+ safe_join(fields)
+ end
+
+ def preference_field(object, form, key, i18n_scope: '')
+ return unless object.has_preference?(key)
+
+ case key
+ when :currency
+ content_tag(:div, form.label("preferred_#{key}", Spree.t(key, scope: i18n_scope)) +
+ form.currency_select("preferred_#{key}", current_store.supported_currencies.split(','), {}, { class: 'custom-select', disabled: current_store.supported_currencies.split(',').count == 1 }),
+ class: 'form-group', id: [object.class.to_s.parameterize, 'preference', key].join('-'))
+ else
+ if object.preference_type(key).to_sym == :boolean
+ content_tag(:div, class: 'form-group custom-control custom-checkbox') do
+ preference_field_for(form, "preferred_#{key}", type: object.preference_type(key)) +
+ form.label(
+ "preferred_#{key}",
+ Spree.t(key, scope: i18n_scope),
+ class: 'custom-control-label',
+ id: [object.class.to_s.parameterize, 'preference', key].join('-')
+ )
end
+ else
+ content_tag(:div, form.label("preferred_#{key}", Spree.t(key, scope: i18n_scope)) +
+ preference_field_for(form, "preferred_#{key}", type: object.preference_type(key)),
+ class: 'form-group', id: [object.class.to_s.parameterize, 'preference', key].join('-'))
end
end
- safe_join(fields)
end
def spree_dom_id(record)
diff --git a/admin/app/views/spree/admin/integrations/_integration.html.erb b/admin/app/views/spree/admin/integrations/_integration.html.erb
new file mode 100644
index 0000000000..b719f8bc63
--- /dev/null
+++ b/admin/app/views/spree/admin/integrations/_integration.html.erb
@@ -0,0 +1,36 @@
+<% integration_name = integration_class.integration_name %>
+<% integration = store_integration(integration_class.integration_key) %>
+
+<% integration_description ||= Spree.t("admin.integrations.#{integration_class.integration_key}.description") %>
+
+<div id="integration-<%= integration_class.integration_key %>" class="col mb-4 d-flex align-items-stretch">
+ <div class="card w-full">
+ <div class="card-header border-bottom d-flex align-items-center justify-content-between h-auto pr-3 <% if integration.present? %>bg-success<% end %>">
+ <div style="height: 36px" class="d-flex align-items-center">
+ <%= image_tag integration_class.icon_path, alt: integration_name, height: 36 if integration_class.icon_path.present? %>
+ </div>
+
+ <% if integration.present? %>
+ <span class="badge badge-success small">
+ <%= icon('check', class: 'mr-1') %>
+ <%= Spree.t(:active) %>
+ </span>
+ <% end %>
+ </div>
+
+ <div class="card-body">
+ <p><%= integration_description %></p>
+ </div>
+
+ <div class="card-footer d-flex <% if integration.present? %>align-items-baseline justify-content-between<% else %>flex-column<% end %>">
+ <% if integration.present? %>
+ <%= link_to spree.edit_admin_integration_path(integration), class: 'card-link btn btn-sm btn-light' do %>
+ <%= icon 'settings' %>
+ <%= Spree.t(:settings) %>
+ <% end if can?(:update, integration) %>
+ <% else %>
+ <%= link_to_with_icon 'plus', "#{Spree.t('actions.connect')} #{integration_class.integration_name}", spree.new_admin_integration_path(integration: { type: integration_class.name }), class: 'btn btn-primary' if can?(:create, Spree::Integration) %>
+ <% end %>
+ </div>
+ </div>
+</div>
diff --git a/admin/app/views/spree/admin/integrations/edit.html.erb b/admin/app/views/spree/admin/integrations/edit.html.erb
new file mode 100644
index 0000000000..683b47e462
--- /dev/null
+++ b/admin/app/views/spree/admin/integrations/edit.html.erb
@@ -0,0 +1,11 @@
+<% content_for :page_title do %>
+ <%= page_header_back_button spree.admin_integrations_path %>
+ <%= @integration.name %> <%= Spree.t(:settings) %>
+<% end %>
+
+<%= render partial: 'spree/admin/shared/error_messages', locals: { target: @integration } %>
+
+<%= form_for @integration, as: :integration, url: spree.admin_integration_path(@integration) do |form| %>
+ <%= render "spree/admin/integrations/forms/#{@integration.key}", form: form %>
+ <%= render 'spree/admin/shared/edit_resource_links', f: form %>
+<% end %>
diff --git a/admin/app/views/spree/admin/integrations/index.html.erb b/admin/app/views/spree/admin/integrations/index.html.erb
new file mode 100644
index 0000000000..37749bd42b
--- /dev/null
+++ b/admin/app/views/spree/admin/integrations/index.html.erb
@@ -0,0 +1,23 @@
+<%= content_for(:page_title) do %>
+ <%= Spree.t(:integrations) %>
+<% end %>
+
+<%= content_for(:page_alerts) do %>
+ <div class="alert alert-info">
+ <%= Spree.t('admin.integrations.page_subtitle') %>
+ </div>
+<% end %>
+
+<div class="container px-lg-0 mt-2">
+ <% grouped_available_store_integrations.each do |group, integrations| %>
+ <% if group.present? %>
+ <div class="my-2 text-muted font-weight-light text-uppercase"><%= Spree.t(group) %></div>
+ <% end %>
+
+ <div class="row row-cols-1 row-cols-md-2 row-cols-lg-3 mb-4">
+ <% integrations.each do |integration| %>
+ <%= render 'spree/admin/integrations/integration', integration_class: integration %>
+ <% end %>
+ </div>
+ <% end %>
+</div>
diff --git a/admin/app/views/spree/admin/integrations/new.html.erb b/admin/app/views/spree/admin/integrations/new.html.erb
new file mode 100644
index 0000000000..eb9eecd31e
--- /dev/null
+++ b/admin/app/views/spree/admin/integrations/new.html.erb
@@ -0,0 +1,14 @@
+<% content_for :page_title do %>
+ <%= page_header_back_button spree.admin_integrations_path %>
+ <%= Spree.t('actions.connect') %> <%= @integration.name %>
+<% end %>
+
+<%= render partial: 'spree/admin/shared/error_messages', locals: { target: @integration } %>
+
+<%= form_for @integration, as: :integration, url: spree.admin_integrations_path do |form| %>
+ <%= form.hidden_field :type %>
+ <%= form.hidden_field :active, value: true %>
+
+ <%= render "spree/admin/integrations/forms/#{@integration.key}", form: form %>
+ <%= render 'spree/admin/shared/new_resource_links' %>
+<% end %>
diff --git a/admin/config/locales/en.yml b/admin/config/locales/en.yml
index 53c8680036..fd96085dcf 100644
--- a/admin/config/locales/en.yml
+++ b/admin/config/locales/en.yml
@@ -75,6 +75,9 @@ en:
export_only_filtered_records: Export only filtered records, matching the search criteria
filters: Filters
getting_started: Getting started
+ integrations:
+ invalid_integration_type: This integration is not allowed
+ page_subtitle: Connect your store to third-party services to enhance customer experience.
manage_currencies: Manage Currencies
manage_properties: Manage Properties
manage_stock_locations: Manage Stock Locations
diff --git a/admin/config/routes.rb b/admin/config/routes.rb
index 51f5c0ab0d..f761d11adc 100644
--- a/admin/config/routes.rb
+++ b/admin/config/routes.rb
@@ -165,6 +165,9 @@ Spree::Core::Engine.add_routes do
end
resources :custom_domains, except: :show
+ # integrations
+ resources :integrations
+
# storefront / page builder
resource :storefront, only: [:edit, :update], controller: :storefront
resources :themes, except: [:new, :show] do
diff --git a/core/app/helpers/spree/integrations_helper.rb b/core/app/helpers/spree/integrations_helper.rb
new file mode 100644
index 0000000000..7214290d61
--- /dev/null
+++ b/core/app/helpers/spree/integrations_helper.rb
@@ -0,0 +1,15 @@
+module Spree
+ module IntegrationsHelper
+ def store_integrations
+ @store_integrations ||= current_store.integrations.active.to_a
+ end
+
+ def store_integration(name)
+ store_integrations.find { |integration| integration.type.to_s.demodulize.underscore == name }
+ end
+
+ def grouped_available_store_integrations
+ Rails.application.config.spree.integrations.group_by(&:integration_group).sort_by { |group, _| group }
+ end
+ end
+end
diff --git a/core/app/models/spree/integration.rb b/core/app/models/spree/integration.rb
new file mode 100644
index 0000000000..5f8034203c
--- /dev/null
+++ b/core/app/models/spree/integration.rb
@@ -0,0 +1,63 @@
+module Spree
+ class Integration < Spree.base_class
+ include Spree::SingleStoreResource
+
+ #
+ # Associations
+ #
+ belongs_to :store, class_name: 'Spree::Store', touch: true
+
+ #
+ # Validations
+ #
+ validates :type, presence: true
+ validates :store, presence: true, uniqueness: { scope: :type }
+
+ #
+ # Scopes
+ #
+ scope :active, -> { where(active: true) }
+
+ # This attribute is used to temporarily store connection-related error messages
+ # that can be displayed to users when testing or validating integration connections.
+ # It is not persisted to the database and is reset on each new connection attempt.
+ # @param message [String, nil] The error message to be stored
+ # @return [String, nil] The current error message
+ attr_accessor :connection_error_message
+
+ # Associates the integration to a group.
+ # The name here will be used as Spree.t key to display the group name.
+ # Leave blank to leave the integration ungrouped.
+ def self.integration_group
+ nil
+ end
+
+ def self.icon_path
+ nil
+ end
+
+ def self.integration_name
+ name.demodulize.titleize.strip
+ end
+
+ def self.integration_key
+ name.demodulize.underscore
+ end
+
+ def name
+ self.class.integration_name
+ end
+
+ def key
+ self.class.integration_key
+ end
+
+ # Checks if the integration can establish a connection.
+ # This is a base implementation that always returns true.
+ # Subclasses should override this method to implement their own connection validation logic.
+ # @return [Boolean] true if the integration can connect, false otherwise
+ def can_connect?
+ true
+ end
+ end
+end
diff --git a/core/config/locales/en.yml b/core/config/locales/en.yml
index 2b53dc55fc..64316118db 100644
--- a/core/config/locales/en.yml
+++ b/core/config/locales/en.yml
@@ -334,6 +334,9 @@ en:
spree/export:
one: Export
other: Exports
+ spree/integration:
+ one: Integration
+ other: Integrations
spree/inventory_unit:
one: Inventory Unit
other: Inventory Units
diff --git a/core/db/migrate/20250407085228_create_spree_integrations.rb b/core/db/migrate/20250407085228_create_spree_integrations.rb
new file mode 100644
index 0000000000..018ba1f250
--- /dev/null
+++ b/core/db/migrate/20250407085228_create_spree_integrations.rb
@@ -0,0 +1,12 @@
+class CreateSpreeIntegrations < ActiveRecord::Migration[7.2]
+ def change
+ create_table :spree_integrations, if_not_exists: true do |t|
+ t.references :store, null: false, index: true
+ t.string :type, null: false, index: true
+ t.text :preferences
+ t.boolean :active, default: false, null: false, index: true
+
+ t.timestamps
+ end
+ end
+end
diff --git a/core/lib/spree/core/engine.rb b/core/lib/spree/core/engine.rb
index 474e02be6c..74a524b3c8 100644
--- a/core/lib/spree/core/engine.rb
+++ b/core/lib/spree/core/engine.rb
@@ -22,7 +22,8 @@ module Spree
:page_blocks,
:reports,
:analytics_events,
- :analytics_event_handlers)
+ :analytics_event_handlers,
+ :integrations)
SpreeCalculators = Struct.new(:shipping_methods, :tax_rates, :promotion_actions_create_adjustments, :promotion_actions_create_item_adjustments)
PromoEnvironment = Struct.new(:rules, :actions)
isolate_namespace Spree
@@ -267,6 +268,8 @@ module Spree
gift_card_issued: 'Gift Card Issued'
}
Rails.application.config.spree.analytics_event_handlers = []
+
+ Rails.application.config.spree.integrations = []
end
initializer 'spree.promo.register.promotions.actions' do |app|
diff --git a/core/lib/spree/testing_support/factories/integration_factory.rb b/core/lib/spree/testing_support/factories/integration_factory.rb
new file mode 100644
index 0000000000..9cb60bcc3a
--- /dev/null
+++ b/core/lib/spree/testing_support/factories/integration_factory.rb
@@ -0,0 +1,7 @@
+FactoryBot.define do
+ factory :integration, class: Spree::Integration do
+ type { 'Spree::Integration' }
+ store { Spree::Store.default }
+ active { true }
+ end
+end
diff --git a/core/spec/models/spree/integration_spec.rb b/core/spec/models/spree/integration_spec.rb
new file mode 100644
index 0000000000..243ef4c9ec
--- /dev/null
+++ b/core/spec/models/spree/integration_spec.rb
@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+# We have no concrete integrations yet so this is just to check that the base model is valid
+RSpec.describe Spree::Integration, type: :model do
+ subject(:integration) { build(:integration) }
+
+ it { is_expected.to be_valid }
+end
diff --git a/storefront/app/controllers/spree/store_controller.rb b/storefront/app/controllers/spree/store_controller.rb
index a3e2d32d68..832c4a4688 100644
--- a/storefront/app/controllers/spree/store_controller.rb
+++ b/storefront/app/controllers/spree/store_controller.rb
@@ -8,6 +8,7 @@ module Spree
include Spree::PasswordProtected
include Spree::WishlistHelper
include Spree::AnalyticsHelper
+ include Spree::IntegrationsHelper
layout :choose_layout
@@ -17,6 +18,7 @@ module Spree
helper 'spree/currency'
helper 'spree/addresses'
helper 'spree/wishlist'
+ helper 'spree/integrations'
helper_method :title
helper_method :title=