spree_klaviyo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca7abe5ed0437048bead7b0b1b074979d85cb5f247d752e4e5ebd638fadc95a6
+  data.tar.gz: 2989bed6e4a9ee6bb6745eb1630e74e5973bb361c51b772a0115ebdeedc6ac21
+SHA512:
+  metadata.gz: 7592104f62d2110332fe4a775f8d6e30445c8db480685225cbea112bd3e1f34df9c2259de0e8de114a95deb510aecd697e7f727424013ec6543e4c42320b655f
+  data.tar.gz: 66efd287a71046e3ef4c677ca20e77c6265b1ea6c3c2bf302a3b3ebfc90215259d48f34dd5add56a5c90de8612dc2268151728581e6b18cccda0c4b4d19166dd

data/LICENSE.md

@@ -0,0 +1,12 @@
+Copyright (c) 2025 Vendo Connect Inc.
+All rights reserved.
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).

data/README.md

@@ -0,0 +1,65 @@
+# Spree Klaviyo
+
+This is an official Klaviyo email marketing extension for [Spree Commerce](https://spreecommerce.org).
+
+## Installation
+
+1. Add this extension to your Gemfile with this line:
+
+    ```ruby
+    bundle add spree_klaviyo
+    ```
+
+2. Run the install generator
+
+    ```ruby
+    bundle exec rails g spree_klaviyo:install
+    ```
+
+3. Restart your server
+
+  If your server was running, restart it so that it can find the assets properly.
+
+## Setup guide
+
+[Please follow our setup guide](https://spreecommerce.org/docs/integrations/marketing/klaviyo) how to setup Klaviyo with Spree Commerce.
+
+## Developing
+
+1. Create a dummy app
+
+    ```bash
+    bundle update
+    bundle exec rake test_app
+    ```
+
+2. Add your new code
+3. Run tests
+
+    ```bash
+    bundle exec rspec
+    ```
+
+When testing your applications integration with this extension you may use it's factories.
+Simply add this require statement to your spec_helper:
+
+```ruby
+require 'spree_klaviyo/factories'
+```
+
+## Releasing a new version
+
+```shell
+bundle exec gem bump -p -t
+bundle exec gem release
+```
+
+For more options please see [gem-release README](https://github.com/svenfuchs/gem-release)
+
+## Contributing
+
+If you'd like to contribute, please take a look at the
+[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
+pull request.
+
+Copyright (c) 2025 [Vendo Connect Inc.](https://getvendo.com), released under the AGPL 3.0 license.

data/Rakefile

@@ -0,0 +1,21 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_klaviyo'
+  Rake::Task['extension:test_app'].invoke
+end

data/app/assets/config/spree_klaviyo_manifest.js

@@ -0,0 +1 @@
+//= link_tree ../images

data/app/clients/spree_klaviyo/klaviyo/client.rb

@@ -0,0 +1,77 @@
+module SpreeKlaviyo
+  module Klaviyo
+    class Client
+      class Result < ::Spree::ServiceModule::Result; end
+
+      def initialize(public_api_key:, private_api_key:)
+        @public_api_key = public_api_key
+        @private_api_key = private_api_key
+      end
+
+      def get_request(api_endpoint)
+        request = Net::HTTP::Get.new(url(api_endpoint))
+        request["accept"] = "application/json"
+        request["revision"] = SpreeKlaviyo::Config[:klaviyo_api_revision]
+        request["Authorization"] = "Klaviyo-API-Key #{private_api_key}"
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          Result.new(true, response.read_body)
+        else
+          Result.new(false, response.read_body)
+        end
+      end
+
+      def post_request(api_endpoint, body)
+        request = Net::HTTP::Post.new(url(api_endpoint))
+        request["accept"] = "application/json"
+        request["revision"] = SpreeKlaviyo::Config[:klaviyo_api_revision]
+        request["content-type"] = "application/json"
+        request["Authorization"] = "Klaviyo-API-Key #{private_api_key}"
+        request.body = body.to_json
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          Result.new(true, response.read_body)
+        else
+          Result.new(false, response.read_body)
+        end
+      end
+
+      def patch_request(api_endpoint, body)
+        request = Net::HTTP::Patch.new(url(api_endpoint))
+        request["accept"] = "application/json"
+        request["revision"] = SpreeKlaviyo::Config[:klaviyo_api_revision]
+        request["content-type"] = "application/json"
+        request["Authorization"] = "Klaviyo-API-Key #{private_api_key}"
+        request.body = body.to_json
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          Result.new(true, response.read_body)
+        else
+          Result.new(false, response.read_body)
+        end
+      end
+
+      private
+
+      attr_reader :public_api_key, :private_api_key
+
+      def url(endpoint = "")
+        @url ||= URI.join(SpreeKlaviyo::Config[:klaviyo_api_url], endpoint)
+      end
+
+      def http
+        @http ||= Net::HTTP.new(url.host, url.port).tap do |net_http_instance|
+          net_http_instance.use_ssl = true
+          net_http_instance.open_timeout = SpreeKlaviyo::Config[:klaviyo_api_open_timeout]
+          net_http_instance.read_timeout = SpreeKlaviyo::Config[:klaviyo_api_read_timeout]
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree_klaviyo/addresses_controller_decorator.rb

@@ -0,0 +1,18 @@
+module SpreeKlaviyo
+  module AddressesControllerDecorator
+    def self.prepended(base)
+      base.include ::Spree::IntegrationsHelper
+
+      base.after_action :create_or_update_klaviyo_profile, only: %i[create update]
+    end
+
+    def create_or_update_klaviyo_profile
+      return unless store_integration('klaviyo').present?
+      return unless @address.valid?
+
+      try_spree_current_user.create_or_update_klaviyo_profile(klaviyo_integration: store_integration('klaviyo'))
+    end
+  end
+end
+
+Spree::AddressesController.prepend(SpreeKlaviyo::AddressesControllerDecorator)

data/app/controllers/spree_klaviyo/profile_controller_decorator.rb

@@ -0,0 +1,18 @@
+module SpreeKlaviyo
+  module ProfileControllerDecorator
+    def self.prepended(base)
+      base.before_action :create_klaviyo_profile, only: :update
+    end
+
+    private
+
+    def create_klaviyo_profile
+      return unless store_integration('klaviyo').present?
+      return unless @user.valid?
+
+      @user.create_or_update_klaviyo_profile(klaviyo_integration: store_integration('klaviyo'))
+    end
+  end
+end
+
+Spree::Account::ProfileController.prepend(SpreeKlaviyo::ProfileControllerDecorator)

data/app/controllers/spree_klaviyo/user_registrations_controller_decorator.rb

@@ -0,0 +1,22 @@
+module SpreeKlaviyo
+  module UserRegistrationsControllerDecorator
+    def self.prepended(base)
+      base.include ::Spree::AnalyticsHelper
+      base.after_action :create_or_update_klaviyo_profile, only: :create, if: :try_spree_current_user
+    end
+
+    private
+
+    def create_or_update_klaviyo_profile
+      integration = store_integration('klaviyo')
+      return if integration.nil?
+
+      try_spree_current_user.create_or_update_klaviyo_profile(
+        klaviyo_integration: integration,
+        guest_id: visitor_id
+      )
+    end
+  end
+end
+
+Spree::UserRegistrationsController.prepend(SpreeKlaviyo::UserRegistrationsControllerDecorator) if defined?(Spree::UserRegistrationsController)

data/app/jobs/spree_klaviyo/base_job.rb

@@ -0,0 +1,5 @@
+module SpreeKlaviyo
+  class BaseJob < ApplicationJob
+    queue_as SpreeKlaviyo.queue
+  end
+end

data/app/jobs/spree_klaviyo/create_back_in_stock_subscription_job.rb

@@ -0,0 +1,10 @@
+module SpreeKlaviyo
+  class CreateBackInStockSubscriptionJob < BaseJob
+    def perform(klaviyo_integration_id, email, variant_id)
+      variant = ::Spree::Variant.find(variant_id)
+      klaviyo_integration = ::Spree::Integrations::Klaviyo.find(klaviyo_integration_id)
+
+      klaviyo_integration.create_back_in_stock_subscription(email: email, variant_id: variant.id)
+    end
+  end
+end

data/app/jobs/spree_klaviyo/create_event_job.rb

@@ -0,0 +1,10 @@
+module SpreeKlaviyo
+  class CreateEventJob < BaseJob
+    def perform(klaviyo_integration_id, event, resource_id, resource_type, email, guest_id = nil)
+      resource = resource_type.classify.constantize.find(resource_id)
+      klaviyo_integration = ::Spree::Integration.find(klaviyo_integration_id)
+
+      SpreeKlaviyo::CreateEvent.call(klaviyo_integration: klaviyo_integration, event: event, resource: resource, email: email, guest_id: guest_id)
+    end
+  end
+end

data/app/jobs/spree_klaviyo/create_or_update_profile_job.rb

@@ -0,0 +1,10 @@
+module SpreeKlaviyo
+  class CreateOrUpdateProfileJob < BaseJob
+    def perform(klaviyo_integration_id, user_id, guest_id)
+      user = ::Spree.user_class.find(user_id)
+      klaviyo_integration = ::Spree::Integrations::Klaviyo.find(klaviyo_integration_id)
+
+      SpreeKlaviyo::CreateOrUpdateProfile.call(klaviyo_integration: klaviyo_integration, user: user, guest_id: guest_id)
+    end
+  end
+end

data/app/jobs/spree_klaviyo/fetch_profile_job.rb

@@ -0,0 +1,15 @@
+module SpreeKlaviyo
+  class FetchProfileJob < BaseJob
+    NoProfileFoundError = Class.new(StandardError)
+
+    def perform(klaviyo_integration_id, user_id)
+      klaviyo_integration = ::Spree::Integrations::Klaviyo.find(klaviyo_integration_id)
+      user = ::Spree.user_class.find(user_id)
+
+      result = SpreeKlaviyo::FetchProfile.call(klaviyo_integration: klaviyo_integration, user: user)
+
+      # Due to race condition let's give Klaviyo some time to create profile
+      raise NoProfileFoundError if result.error == ::Spree::Integrations::Klaviyo::NO_PROFILE_FOUND
+    end
+  end
+end

data/app/jobs/spree_klaviyo/subscribe_job.rb

@@ -0,0 +1,10 @@
+module SpreeKlaviyo
+  class SubscribeJob < BaseJob
+    def perform(klaviyo_integration_id, email, user_id = nil)
+      user = ::Spree.user_class.find(user_id) if user_id.present?
+      klaviyo_integration = ::Spree::Integrations::Klaviyo.find(klaviyo_integration_id)
+
+      SpreeKlaviyo::Subscribe.call(klaviyo_integration: klaviyo_integration, email: email, user: user)
+    end
+  end
+end

data/app/jobs/spree_klaviyo/unsubscribe_job.rb

@@ -0,0 +1,10 @@
+module SpreeKlaviyo
+  class UnsubscribeJob < BaseJob
+    def perform(klaviyo_integration_id, email, user_id = nil)
+      user = ::Spree.user_class.find(user_id)
+      klaviyo_integration = ::Spree::Integrations::Klaviyo.find(klaviyo_integration_id)
+
+      SpreeKlaviyo::Unsubscribe.call(klaviyo_integration: klaviyo_integration, email: email, user: user)
+    end
+  end
+end

data/app/models/concerns/spree_klaviyo/user_methods.rb

@@ -0,0 +1,24 @@
+module SpreeKlaviyo
+  module UserMethods
+    extend ActiveSupport::Concern
+
+    included do
+      store_accessor :private_metadata, :klaviyo_id
+      store_accessor :private_metadata, :klaviyo_subscribed
+    end
+
+    def klaviyo_subscribed?
+      klaviyo_subscribed.to_b
+    end
+
+    def create_or_update_klaviyo_profile(klaviyo_integration:, guest_id: nil)
+      SpreeKlaviyo::CreateOrUpdateProfileJob.perform_later(klaviyo_integration.id, id, guest_id)
+    end
+
+    def fetch_klaviyo_profile(klaviyo_integration:)
+      return if klaviyo_id.present?
+
+      SpreeKlaviyo::FetchProfileJob.perform_later(klaviyo_integration.id, id)
+    end
+  end
+end

data/app/models/spree/integrations/klaviyo.rb

@@ -0,0 +1,122 @@
+module Spree
+  module Integrations
+    class Klaviyo < Spree::Integration
+      class Api::Error < StandardError; end
+
+      NO_PROFILE_FOUND = 'No profile found'.freeze
+
+      preference :klaviyo_public_api_key, :string
+      preference :klaviyo_private_api_key, :password
+      preference :default_newsletter_list_id, :string
+
+      validates :preferred_klaviyo_public_api_key, :preferred_klaviyo_private_api_key, :preferred_default_newsletter_list_id, presence: true
+
+      def self.integration_group
+        'marketing'
+      end
+
+      def self.icon_path
+        'integration_icons/klaviyo-logo.png'
+      end
+
+      def can_connect?
+        # There's no method for checking if credentials are valid, but we can figure it out basing on response,
+        # except Public API Key.
+        result = client.get_request("lists/#{preferred_default_newsletter_list_id}")
+
+        # 'Missing or invalid private key.' for invalid private key
+        # 'A list with id #{id} does not exist.' for invalid newsletter list id
+        @connection_error_message = JSON.parse(result.value)['errors'].first['detail'] if result.failure?
+
+        result.success?
+      end
+
+      def create_profile(user, guest_id = nil)
+        user_presenter = ::SpreeKlaviyo::UserPresenter.new(email: user.email, address: user&.bill_address, guest_id: guest_id)
+        result = client.post_request('profiles/', user_presenter.call)
+
+        handle_result(result)
+      end
+
+      def update_profile(user, guest_id = nil)
+        user_presenter = ::SpreeKlaviyo::UserPresenter.new(email: user.email, address: user&.bill_address, user: user, guest_id: guest_id)
+        result = client.patch_request("profiles/#{user.klaviyo_id}/", user_presenter.call)
+
+        handle_result(result)
+      end
+
+      def subscribe_user(email)
+        result = client.post_request(
+          'profile-subscription-bulk-create-jobs/',
+          ::SpreeKlaviyo::SubscribePresenter.new(email: email, list_id: preferred_default_newsletter_list_id).call
+        )
+
+        handle_result(result)
+      end
+
+      def unsubscribe_user(email)
+        payload = ::SpreeKlaviyo::SubscribePresenter.new(
+          email: email,
+          list_id: preferred_default_newsletter_list_id,
+          type: 'profile-subscription-bulk-delete-job',
+          subscribed: false
+        ).call
+
+        result = client.post_request(
+          'profile-subscription-bulk-delete-jobs/',
+          payload
+        )
+
+        handle_result(result)
+      end
+
+      def create_back_in_stock_subscription(email:, variant_id:)
+        body = ::SpreeKlaviyo::BackInStockSubscriptionPresenter.new(email: email, variant_id: variant_id).call
+        result = client.post_request('back-in-stock-subscriptions/', body)
+
+        handle_result(result)
+      end
+
+      def create_event(event:, resource:, email:, guest_id: nil)
+        result = client.post_request(
+          'events/',
+          ::SpreeKlaviyo::EventPresenter.new(
+            integration: self,
+            event: event,
+            resource: resource,
+            email: email,
+            guest_id: guest_id
+          ).call
+        )
+
+        handle_result(result)
+      end
+
+      def fetch_profile(email:)
+        result = client.get_request("profiles/?fields[profile]=email&filter=equals(email,'#{CGI.escapeURIComponent(email)}')")
+
+        return Spree::ServiceModule::Result.new(false, email, NO_PROFILE_FOUND) if result.success? && JSON.parse(result.value)['data'].empty?
+
+        handle_result(result)
+      end
+
+      private
+
+      def client
+        ::SpreeKlaviyo::Klaviyo::Client.new(
+          public_api_key: preferred_klaviyo_public_api_key,
+          private_api_key: preferred_klaviyo_private_api_key
+        )
+      end
+
+      def handle_result(result)
+        if result.success?
+          Spree::ServiceModule::Result.new(true, result.value)
+        else
+          Rails.error.report(Api::Error.new(result.value), context: { integration_id: id }, source: 'spree.klaviyo')
+          Spree::ServiceModule::Result.new(false, result.value)
+        end
+      end
+    end
+  end
+end

data/app/models/spree_klaviyo/analytics_event_handler.rb

@@ -0,0 +1,61 @@
+module SpreeKlaviyo
+  class AnalyticsEventHandler < ::Spree::BaseAnalyticsEventHandler
+    def client
+      @client ||= store.integrations.active.find_by(type: 'Spree::Integrations::Klaviyo')
+    end
+
+    def handle_event(event_name, properties)
+      return if client.blank?
+
+      email = user&.email.presence
+
+      record = case event_name
+               when 'product_viewed'
+                 properties[:product]
+               when 'product_list_viewed'
+                 properties[:taxon]
+               when 'product_searched'
+                 properties[:query]
+               when 'product_added', 'product_removed'
+                 email ||= properties[:line_item].order.email
+                 properties[:line_item].order
+               when 'payment_info_entered'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'coupon_entered', 'coupon_removed'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'coupon_applied'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'coupon_denied'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'checkout_started'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'checkout_email_entered'
+                 email = properties[:email]
+                 properties[:order]
+               when 'checkout_step_viewed', 'checkout_step_completed'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'order_completed'
+                 email ||= properties[:order].email
+                 properties[:order]
+               when 'subscribed_to_newsletter'
+                 email ||= properties[:email]
+                 SpreeKlaviyo::SubscribeJob.perform_later(client.id, email, user&.id)
+                 nil
+               when 'unsubscribed_from_newsletter'
+                 email ||= properties[:email]
+                 SpreeKlaviyo::UnsubscribeJob.perform_later(client.id, email, user&.id)
+                 nil
+               end
+
+      return if email&.strip&.blank? && identity_hash[:visitor_id].blank?
+
+      client.create_event(event: event_human_name(event_name), resource: record, email: email, guest_id: identity_hash[:visitor_id])
+    end
+  end
+end

data/app/models/spree_klaviyo/order_decorator.rb

@@ -0,0 +1,34 @@
+module SpreeKlaviyo
+  module OrderDecorator
+    def self.prepended(base)
+      base.state_machine.after_transition to: :complete, do: :subscribe_user_to_klaviyo_newsletter
+      base.state_machine.after_transition to: :canceled, do: :track_order_cancelled_event
+    end
+
+    def subscribe_user_to_klaviyo_newsletter
+      return unless accept_marketing?
+
+      return if user&.klaviyo_subscribed?
+
+      integration = store_integration('klaviyo')
+      return if integration.blank?
+
+      SpreeKlaviyo::SubscribeJob.perform_later(integration.id, email, user_id)
+    end
+
+    def track_order_cancelled_event
+      klaviyo_integration = store.integrations.active.find_by(type: 'Spree::Integrations::Klaviyo')
+      return if klaviyo_integration.nil?
+
+      klaviyo_integration.create_event(event: 'Order Cancelled', resource: self, email: email)
+    rescue StandardError => e
+      Rails.error.report(
+        e,
+        context: { event_name: 'order_cancelled', record: { order: self } },
+        source: 'spree.core'
+      )
+    end
+  end
+
+  ::Spree::Order.prepend(OrderDecorator)
+end

data/app/models/spree_klaviyo/shipment_handler_decorator.rb

@@ -0,0 +1,25 @@
+module SpreeKlaviyo
+  module ShipmentHandlerDecorator
+    def perform
+      super
+      track_package_shipped_event
+    end
+
+    def track_package_shipped_event
+      order = @shipment.order
+
+      klaviyo_integration = order.store.integrations.active.find_by(type: 'Spree::Integrations::Klaviyo')
+      return if klaviyo_integration.blank?
+
+      klaviyo_integration.create_event(event: 'Package Shipped', resource: @shipment, email: order.email)
+    rescue StandardError => e
+      Rails.error.report(
+        e,
+        context: { event_name: 'package_shipped', record: { order: order, shipment: @shipment } },
+        source: 'spree.core'
+      )
+    end
+  end
+
+  ::Spree::ShipmentHandler.prepend(ShipmentHandlerDecorator)
+end

data/app/models/spree_klaviyo/user_decorator.rb

@@ -0,0 +1,9 @@
+module SpreeKlaviyo
+  module UserDecorator
+    def self.prepended(base)
+      base.include ::SpreeKlaviyo::UserMethods
+    end
+  end
+end
+
+Spree.user_class.prepend(SpreeKlaviyo::UserDecorator) if Spree.user_class.present?

data/app/presenters/spree_klaviyo/address_presenter.rb

@@ -0,0 +1,27 @@
+module SpreeKlaviyo
+  class AddressPresenter
+    def initialize(address:)
+      @address = address
+    end
+
+    def call
+      return {} if @address.nil?
+
+      {
+        city: @address.city,
+        country: @address.country_name,
+        postalCode: @address.zipcode,
+        state: @address.state_text,
+        street: @address.street,
+        phone: @address.phone,
+        name: @address.full_name,
+        first_name: @address.first_name,
+        last_name: @address.last_name
+      }
+    end
+
+    private
+
+    attr_reader :address
+  end
+end