solidus_mailchimp_sync 1.0.0.beta01

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 438a05bdc2da376a935c47c5e49a40c7fb051c29
+  data.tar.gz: fb84400208fe9076147845ebac7f07b976c48f6f
+SHA512:
+  metadata.gz: 19cd7dd3771b03e505a7bee345a4e266d873e05c92db6ab859a32f2314ae7bd628cf0c019ccc16612e062b40f2d51f053d6321a024b0503e97ec45f769f73184
+  data.tar.gz: 8a677341ef4873597f3006a69cd92c24b96ba42e4320cbe431a4edf004ce26c4b4fec7ba15584a427648d0caaea9860cf6a8a3d769e48ba28470035567e6154a

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2016 Friends of the Web
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name Spree nor the names of its contributors may be used to
+      endorse or promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,103 @@
+[![Build Status](https://travis-ci.org/friendsoftheweb/solidus_mailchimp_sync.svg?branch=master)](https://travis-ci.org/friendsoftheweb/solidus_mailchimp_sync)
+
+SolidusMailchimpSync
+====================
+
+**WIP**
+
+Synchronizes Solidus data with [Mailchimp E-Commerce API](http://developer.mailchimp.com/documentation/mailchimp/guides/getting-started-with-ecommerce/). (Mailchimp API 3.0)
+
+This plugin does not do every kind of integration with Mailchimp that might be possible, it just focuses
+on synchronizing data from Solidus to Mailchimp, by adding ActiveRecord lifecycle
+hooks to Solidus models.
+
+* Solidus `User` to Mailchimp `Customer`. (All customers currently added as status `transactional` in Mailchimp)
+* Solidus `Product`, `Variant` (and images) to Mailchimp `Product` and `Variant`.
+* Solidus `Order` (and their `LineItem`s), to Mailchimp `Cart` and `Order` (and their `Line`s).
+
+Not all possible attributes that can be sync'd may yet be synced. It does
+not yet sync Order payment/cancel/return/shipment state. It does not yet sync Customer
+`orders_count`/`total_spent`. Some Mailchimp E-Commerce features may require these, others
+are still usable.
+
+Right now this plugin will connect everything in Solidus to a single Mailchimp `Store`, it does
+not support multiple Mailchimp Stores.
+
+We do not (yet?) support Mailchimp E-Commerce Link Tracking.
+
+Actual sync'ing is done in background jobs using ActiveJob, configure your
+ActiveJob adapter. All jobs are idempotent.
+
+Installation
+------------
+
+Add solidus_mailchimp_sync to your Gemfile:
+
+```ruby
+gem 'solidus_mailchimp_sync'
+```
+
+Bundle your dependencies and run the installation generator:
+
+```shell
+bundle
+bundle exec rails g solidus_mailchimp_sync:install
+```
+
+Your app will need to set `default_url_options[:host]` so urls can be
+sent to mailchimp in background. :
+
+     config.action_mailer.default_url_options = { host: 'mystore.example.org' }
+
+Review the generated `./config/initializers/solidus_mailchimp_sync.rb` for required
+and optional config, including mailchimp api keys.
+
+You will need to have a Mailchimp List already created. You will need to create
+a Mailchimp `Store` object belonging to that list, that we'll use for synchronization.
+Not sure if that can be created through anything but API. You can create one by:
+
+    bundle exec rake solidus_mailchimp_sync:create_mailchimp_store LIST_ID=list-id-from-mailchimp
+
+Then add the storeID for created store to your configuration.
+
+Before going live, you will probably want to bulk-add all your existing data --
+if existing products aren't added, orders won't be able to be synced. This
+could take a while:
+
+    RAILS_ENV=production rake solidus_mailchimp_sync:bulk_sync
+
+Known issues/To do
+-------
+
+* If a user changes their email addresses, their old orders may be no longer associated with
+  them in mailchimp, they will wind up with two mailchimp customer records. (Mailchimp
+  docs suggest you can change an existing Customer's id itself, but it didn't seem to work.
+  can't change an existing Customer's email address)
+* Debounce: This may send a LOT of updates to mailchimp, when you're editing something.
+  In checkout process there are sometimes multiple syncs for order, not sure why.
+  Have an idea for an implementation debounce feature that could debounce/coalesce mailchimp
+  syncs in the general case.
+
+Testing
+-------
+
+First bundle your dependencies, then run `rake`. `rake` will default to building the dummy app if it does not exist, then it will run specs, and [Rubocop](https://github.com/bbatsov/rubocop) static code analysis. The dummy app can be regenerated by using `rake test_app`.
+
+```shell
+bundle
+bundle exec rake
+```
+
+Some tests use VCR to record live transactions with mailchimp. To run these tests while
+recording new cassettes, you will need to set ENV `MAILCHIMP_API_KEY` and `MAILCHIMP_STORE_ID`.
+**Note** these should be a test/dummy mailchimp account, as data will be edited by tests.
+
+When testing your applications integration with this extension you may use it's factories.
+(No factories at present)
+Simply add this require statement to your spec_helper:
+
+```ruby
+require 'solidus_mailchimp_sync/factories'
+```
+
+Copyright (c) 2016 Friends of the Web LLC, released under the New BSD License

data/Rakefile

@@ -0,0 +1,31 @@
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'spree/testing_support/extension_rake'
+  require 'rubocop/rake_task'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  RuboCop::RakeTask.new
+
+  #task default: %i(first_run rubocop spec)
+  task default: %i(first_run spec)
+rescue LoadError
+  # no rspec available
+end
+
+task :first_run do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'solidus_mailchimp_sync'
+  Rake::Task['extension:test_app'].invoke
+end

data/app/assets/javascripts/spree/backend/solidus_mailchimp_sync.js

@@ -0,0 +1,2 @@
+// Placeholder manifest file.
+// the installer will append this file to the app vendored assets here: vendor/assets/javascripts/spree/backend/all.js'

data/app/assets/javascripts/spree/frontend/solidus_mailchimp_sync.js

@@ -0,0 +1,2 @@
+// Placeholder manifest file.
+// the installer will append this file to the app vendored assets here: vendor/assets/javascripts/spree/frontend/all.js'

data/app/assets/stylesheets/spree/backend/solidus_mailchimp_sync.css

@@ -0,0 +1,4 @@
+/*
+Placeholder manifest file.
+the installer will append this file to the app vendored assets here: 'vendor/assets/stylesheets/spree/backend/all.css'
+*/

data/app/assets/stylesheets/spree/frontend/solidus_mailchimp_sync.css

@@ -0,0 +1,4 @@
+/*
+Placeholder manifest file.
+the installer will append this file to the app vendored assets here: 'vendor/assets/stylesheets/spree/frontend/all.css'
+*/

data/app/jobs/solidus_mailchimp_sync/sync_job.rb

@@ -0,0 +1,15 @@
+module SolidusMailchimpSync
+  class SyncJob < ActiveJob::Base
+    class_attribute :use_queue_name
+    use_queue_name = :default
+
+    queue_as do
+      self.use_queue_name
+    end
+
+    def perform(synchronizer_class_name, model)
+      synchronizer = synchronizer_class_name.constantize.new(model)
+      synchronizer.sync
+    end
+  end
+end

data/app/models/solidus_mailchimp_sync/error.rb

@@ -0,0 +1,32 @@
+module SolidusMailchimpSync
+  class Error < StandardError
+    attr_reader :type, :title, :status, :detail, :instance,
+                :request_method, :request_url, :request_body,
+                :response_body, :response_hash
+
+    def initialize( type:nil, title:nil, status: nil, detail: nil, instance: nil,
+                    request_method:nil, request_url: nil, request_body: nil,
+                    response_body: nil, response_hash: nil)
+
+      @type = type
+      @title = title
+      @status = status
+      @detail = detail
+      @instance = instance
+
+      @request_method = request_method.to_s.upcase
+      @request_url = request_url
+      @request_body = request_body
+
+      @response_body = response_body
+      @response_hash = response_hash
+
+      super(constructed_message)
+    end
+
+    def constructed_message
+      errors = response_hash.try { |h| h["errors"] }.to_s.presence
+      [status, title, detail, errors].compact.join(': ')
+    end
+  end
+end

data/app/models/solidus_mailchimp_sync/mailchimp.rb

@@ -0,0 +1,69 @@
+require 'json'
+require 'http'
+require 'solidus_mailchimp_sync'
+
+module SolidusMailchimpSync
+  class Mailchimp
+    AUTH_USER = "ignored"
+
+    # If Mailchimp errors, will normally raise a SolidusMailchimpSync::Error, but
+    # set `return_errors: true` to return the Error as return value instead.
+    def self.request(method, path, body: nil, return_errors: false)
+      return unless SolidusMailchimpSync.enabled
+
+      if SolidusMailchimpSync.api_key.blank?
+        raise ArgumentError, "Missing required configuration `SolidusMailchimpSync.api_key`"
+      end
+
+      url = url(path)
+      args = [method.to_sym, url]
+      args << { json: body } if body
+      response = HTTP.basic_auth(user: AUTH_USER, pass: SolidusMailchimpSync.api_key).
+                      request(*args)
+
+      response_hash = response.body.present? ? JSON.parse(response.body.to_s) : { status: response.code }
+
+      unless (200..299).cover?(response.code)
+        return Error.new(
+          request_method: method,
+          request_url: url,
+          request_body: body,
+
+          type: response_hash["type"],
+          title: response_hash["title"],
+          status: response_hash["status"] || response.code,
+          detail: response_hash["detail"],
+          instance: response_hash["instance"],
+
+          response_hash: response_hash
+        ).tap { |error| raise error unless return_errors }
+      end
+
+      response_hash
+    rescue JSON::ParserError => e
+      return Error.new(request_method: method, request_url: url, request_body: body,
+                      status: response.status, detail: "JSON::ParserError #{e}",
+                      response_body: response.body.to_s).tap { |error| raise error unless return_errors }
+    end
+
+    # Assumes an ECommerce request to our store, prefixes path argument with
+    # `/ecommerce/store/#{SolidusMailchimpSync.store_id}/`
+    def self.ecommerce_request(method, path, body: nil, store_id: SolidusMailchimpSync.store_id, return_errors: false)
+      if store_id.blank?
+        raise ArgumentError, "Missing required configuration `SolidusMailchimpSync.store_id`"
+      end
+
+      path = "/ecommerce/stores/#{store_id}/" + path.sub(%r{\A/}, '')
+      request(method, path, body: body, return_errors: return_errors)
+    end
+
+    def self.base_url
+      "https://#{SolidusMailchimpSync.data_center}.api.mailchimp.com/3.0/"
+    end
+
+    def self.url(path)
+      base_url + path.sub(%r{\A/}, '')
+    end
+
+  end
+end

data/app/serializers/solidus_mailchimp_sync/customer_serializer.rb

@@ -0,0 +1,34 @@
+require 'json'
+
+module SolidusMailchimpSync
+  # ONLY includes email address. Everyone has their own user class,
+  # use a custom serializer to serialize other stuff. To change where
+  # email address is stored in user record, be sure to set
+  # SolidusMailchimpSync::UserSynchronizer.email_address_attribute
+  class CustomerSerializer
+    attr_reader :user
+
+    def initialize(user)
+      @user = user
+      unless user.persisted?
+        raise ArgumentError, "Can't serialize a non-saved user: #{user}"
+      end
+    end
+
+    def as_json
+      # Note mailchimp does not let us change email address, it won't be updated on
+      # subsequent pushes. So our mailchimp id includes the email address,
+      # and new mailchimp Customer will be created if email address changes.
+      {
+        'id' => UserSynchronizer.customer_id(user),
+        'email_address' => user.send(UserSynchronizer.email_address_attribute),
+        'opt_in_status' => false
+      }
+    end
+
+    def to_json
+      JSON.dump(as_json)
+    end
+
+  end
+end

data/app/serializers/solidus_mailchimp_sync/line_item_serializer.rb

@@ -0,0 +1,26 @@
+require 'json'
+
+module SolidusMailchimpSync
+  # Line item for Cart or Order, mailchimp serializes the same
+  class LineItemSerializer
+    attr_reader :line_item
+
+    def initialize(line_item)
+      @line_item = line_item
+    end
+
+    def as_json
+      {
+        id: line_item.id.to_s,
+        product_id: line_item.product.id.to_s,
+        product_variant_id: line_item.variant.id.to_s,
+        quantity: line_item.quantity,
+        price: line_item.price.to_f
+      }
+    end
+
+    def to_json
+      JSON.dump(as_json)
+    end
+  end
+end

data/app/serializers/solidus_mailchimp_sync/order_serializer.rb

@@ -0,0 +1,70 @@
+require 'json'
+
+module SolidusMailchimpSync
+  # Serializes to Mailchimp Cart or Order, depending on state.
+  class OrderSerializer
+    attr_reader :order
+
+    def initialize(order)
+      @order = order
+      unless order.persisted?
+        raise ArgumentError, "Can't serialize a non-saved order: #{order}"
+      end
+    end
+
+    def as_json
+      hash = {
+        id: order.id.to_s,
+        customer: {
+          id: UserSynchronizer.customer_id(order.user)
+        },
+        currency_code: order.currency,
+        order_total: order.total.to_f,
+        tax_total: order.tax_total.to_f,
+        lines: line_items
+      }
+
+
+      # Mailchimp does not take URLs for orders, just carts
+      unless order_complete?
+        url = cart_url
+        hash["checkout_url"] = url if url
+      end
+
+      hash["shipping_total"] = shipping_total if shipping_total
+
+      hash
+    end
+
+    # Override in custom serializer for custom front-end url
+    def cart_url
+      # Mailchimp does not take URLs for orders, just carts
+      unless order_complete?
+        if Rails.application.routes.default_url_options[:host] && Spree::Core::Engine.routes.url_helpers.respond_to?(:cart_url)
+          Spree::Core::Engine.routes.url_helpers.cart_url(host: Rails.application.routes.default_url_options[:host])
+        end
+      end
+    end
+
+    def order_complete?
+      # Yes, somehow solidus can sometimes, temporarily, in our after commit hook
+      # have state==complete set, but not completed_at
+      order.completed? || order.state == "complete"
+    end
+
+    def shipping_total
+      # Mailchimp only wants shipping total for Orders, not Carts.
+      order.shipment_total if order_complete?
+    end
+
+    def to_json
+      JSON.dump(as_json)
+    end
+
+    def line_items
+      order.line_items.collect do |line_item|
+        ::SolidusMailchimpSync::OrderSynchronizer.line_item_serializer_class_name.constantize.new(line_item).as_json
+      end
+    end
+  end
+end