market_town-checkout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ccf737f8e5d5e1b99350ca5c2e7c69595813de52
+  data.tar.gz: b61d9955fd58a7de3ec72fe50720e49c6c8a659a
+SHA512:
+  metadata.gz: 5e3c575fbca0a8c72411e092cda3edd013249b7700e083171f52ee64c724c7cad18d775c0eef7cd598ee96b156c3584982af1618de128417412520471d1fc7b1
+  data.tar.gz: f0b50505161df4ee7d1333d36a178698283601b9b16e1749baec106049ee9f31606eead57107ec44591855c0e49e8d63a9ba976555f9b766423dd608303d58aa

data/README.md

@@ -0,0 +1,138 @@
+# Market Town: Checkout
+
+Checkout business logic for your ruby e-commerce. This gem is framework
+independent but provides integration with Spree and Webhooks.
+
+You can introduce MarketTown::Checkout as an interface between your application
+and your e-commerce backend. Using the power of dependency injection you can
+provide implementation specific logic for applying promotions, saving addresses,
+taking payments, etc. in your e-commerce store.
+
+If you've ever wanted to gradually replace Spree with your own system, or split
+Spree out into a number of different services then you're in the right place.
+
+## Mission
+
+ - Handle common use cases of checkout step behaviour
+ - Provide a Spree dependency container for writing your own checkout
+   controllers that speak to Spree objects underneath
+ - Provide a Webhook dependency container that will forward calls onto a HTTPS
+   interface of your choice
+
+## Implementing a checkout
+
+This library provides logic for common steps in a checkout. You can use these
+steps in your checkout controllers. This example will be in Ruby on Rails but it
+could be any ruby framework or library, even Rack.
+
+### Dependency container
+
+First of all let's create a dependency container for an imaginary e-commerce
+framework.
+
+``` ruby
+class AppContainer < MarketTown::Checkout::Dependencies
+  class Fulfilments
+    def can_fulfil_address?(delivery_address)
+      Ecom::DistributionService.new.check_address(delivery_address)
+    end
+
+    def propose_shipments(state)
+      state[:order].shipments << Ecom::Shipments.new.propose(state[:delivery_address])
+    end
+  end
+
+  class AddressStorage
+    def store(state)
+      case state[:address_type]
+      when :delivery
+        state[:user].shipment_addresses << state[:delivery_address]
+      when :billing
+        state[:user].billing_addresses << state[:billing_address]
+      end
+    end
+  end
+
+  class Finish
+    def address_step(state)
+      state[:order].update!(step: :delivery)
+    end
+  end
+
+  def fulfilments
+    Fulfilments.new
+  end
+
+  def address_storage
+    AddressStorage.new
+  end
+
+  def finish
+    Finish.new
+  end
+end
+```
+
+Inside this container we wrote some simple adapters to our e-commerce framework.
+You can of course keep these adapters in another file, we've kept them here to
+keep the example simple. The container exposes the adapters via methods that
+are used by MarketTown::Checkout steps.
+
+### Generic step controller
+
+Now we can implement our base step controller:
+
+``` ruby
+class StepController < ApplicationController
+  def edit
+    @order = Ecom::Order.find_by(user: current_user)
+  end
+
+  def update
+    @order = Ecom::Order.find_by(user: current_user)
+    process_step
+    redirect_to checkout_path(@order)
+  rescue MarketTown::Checkout::Error => e
+    flash.now[:errors] = [e.error]
+    render :edit
+  rescue ActiveRecord::RecordInvalid
+    render :edit
+  end
+
+  private
+
+  def process_step
+    MarketTown::Checkout.process_step(step: step_name,
+                                      dependencies: AppContainer.new,
+                                      state: step_state)
+  end
+
+  def step_state
+    { user: current_user,
+      order: @order }
+  end
+end
+```
+
+### Address step controller
+
+And now let's create our address checkout step:
+
+``` ruby
+class AddressStepController < StepController
+  private
+
+  def step_name
+    :address
+  end
+
+  def step_state
+    address_params = %i(name address_1 locality postal_code country save)
+
+    super.merge(params.require(:order).permit(billing_address: address_params,
+                                              delivery_address: address_params))
+  end
+end
+```
+
+You could create a controller for each step in the same way.

data/lib/market_town/checkout/dependencies.rb

@@ -0,0 +1,105 @@
+module MarketTown
+  module Checkout
+    # A dependency container for injecting custom behaviour into {Checkout} and
+    # subsequently {Step}.
+    #
+    # The purpose of {Checkout} is to provide the logic for orchestrating the
+    # checkout process. The actual implementation needs to be injected at
+    # runtime via {Dependencies} or an object like it.
+    #
+    # ## Using {Dependencies}
+    #
+    # Since {Dependencies} extends the ruby Hash object you can treat it as
+    # such. We provide {#method_missing} to provide a way of accessing keys
+    # of the hash with methods.
+    #
+    # First let's create a dependency for sending notifications.
+    #
+    # ``` ruby
+    # class Notifications
+    #   def notify(notification, data)
+    #     puts :notification, JSON.dump(data)
+    #   end
+    # end
+    # ```
+    #
+    # Now we can create our container and use it:
+    #
+    # ``` ruby
+    # container = MarketTown::Checkout::Dependencies.new(notifications: Notifications.new)
+    #
+    # container.notifications.notify(:order_complete, { order_id: 1 })
+    # ```
+    #
+    # You don't actually need to use the container yourself though. The point
+    # of the container is to inject behaviour into a checkout step. You would
+    # usually use it like so:
+    #
+    # ``` ruby
+    # container = MarketTown::Checkout::Dependencies.new(notifications: Notifications.new)
+    #
+    # MarketTown::Checkout.process_step(step: :complete,
+    #                                   dependencies: container,
+    #                                   state: { order: order })
+    # ```
+    #
+    # ## Extending {Dependencies}
+    #
+    # You can extend {Dependencies} instead of passing a Hash into it's
+    # constructor:
+    #
+    # ``` ruby
+    # class AppContainer < MarketTown::Checkout::Dependencies
+    #   def notifications
+    #     Notifications.new
+    #   end
+    # end
+    # ```
+    #
+    # You can define an application wide container like this or you could
+    # setup different containers for each step in your checkout.
+    #
+    # ## Using your own container
+    #
+    # As long as you provide an object that provides the dependencies
+    # each step needs you do not actually need to extend {Dependencies} at all.
+    #
+    # ``` ruby
+    # class AppContainer
+    #   def notifications
+    #     Notifications.new
+    #   end
+    # end
+    # ```
+    #
+    class Dependencies < Hash
+      def initialize(deps = {})
+        merge!(deps.delete_if { |k, v| v.nil? })
+      end
+
+      # Used to fetch a dependency
+      #
+      # @example
+      #   container.complete_step.delivery(state)
+      #
+      # @raise [MissingDependency] when dependency is not defined
+      #
+      def method_missing(method)
+        fetch(method)
+      rescue KeyError
+        raise MissingDependency.new(method)
+      end
+
+      # Uses built-in ruby Logger if not provided
+      #
+      # @return [Logger or similar]
+      #
+      def logger
+        super
+      rescue MissingDependency
+        require 'logger'
+        Logger.new(STDOUT)
+      end
+    end
+  end
+end

data/lib/market_town/checkout/error.rb

@@ -0,0 +1,15 @@
+module MarketTown
+  module Checkout
+    class Error < RuntimeError
+      def error
+        self.class.name.sub('MarketTown::Checkout::', '')
+                       .split('::')
+                       .join('_')
+                       .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                       .gsub(/([a-z])([A-Z])/, '\1_\2')
+                       .downcase
+                       .to_sym
+      end
+    end
+  end
+end

data/lib/market_town/checkout/missing_dependency.rb

@@ -0,0 +1,22 @@
+module MarketTown
+  module Checkout
+    # When you request a dependency that is not defined in {Dependencies} then
+    # a {MissingDependency} exception will be raised. This is used to provide
+    # useful warnings in development in {Step}'s.
+    #
+    # ``` ruby
+    # container = MarketTown::Checkout::Dependencies.new
+    #
+    # begin
+    #   container.fulfilments.propose_shipments(state)
+    # rescue MissingDependency
+    #   puts 'Did not propose shipments'
+    # end
+    # ```
+    #
+    # See {AddressStep#ensure_delivery} and {DeliveryStep#validate_shipments}
+    # for real world examples.
+    #
+    class MissingDependency < RuntimeError; end
+  end
+end

data/lib/market_town/checkout/models/address.rb

@@ -0,0 +1,77 @@
+require 'active_model'
+require 'countries/iso3166'
+
+module MarketTown
+  module Checkout
+    # An Address model for validating addresses. This class is for internal
+    # use only. You should validate addresses yourself before passing them
+    # into {MarketTown::Checkout}.
+    #
+    # @api private
+    #
+    class Address
+      # Validates an address, throws {InvalidError} if invalid
+      #
+      # @param [Hash] address_attrs
+      # @option address_attrs [String] :name
+      # @option address_attrs [String] :company
+      # @option address_attrs [String] :address_1
+      # @option address_attrs [String] :address_2
+      # @option address_attrs [String] :address_3
+      # @option address_attrs [String] :locality
+      # @option address_attrs [String] :region
+      # @option address_attrs [String] :postal_code
+      # @option address_attrs [String] :country must be valid ISO3166 alpha 2
+      #
+      # @raise [InvalidError] if address invalid
+      #
+      def self.validate!(address_attrs)
+        address = new(address_attrs)
+
+        if address.invalid?
+          raise InvalidError.new(address: address_attrs,
+                                 errors: address.errors.messages)
+        end
+      end
+
+      include ActiveModel::Model
+
+      attr_accessor :name,
+                    :company,
+                    :address_1,
+                    :address_2,
+                    :address_3,
+                    :locality,
+                    :region,
+                    :postal_code,
+                    :country,
+                    :save
+
+      validates :name, presence: true
+      validates :address_1, presence: true
+      validates :locality, presence: true
+      validates :postal_code, presence: true
+      validates :country, presence: true
+
+      validate :country_is_iso3166
+
+      private
+
+      def country_is_iso3166
+        if ISO3166::Country.find_country_by_alpha2(country).nil?
+          errors.add(:country, 'Country was not valid ISO3166 alpha 2')
+        end
+      end
+
+      # Thrown when {Address} invalid
+      #
+      class InvalidError < RuntimeError
+        attr_reader :data
+
+        def initialize(data)
+          @data = data
+        end
+      end
+    end
+  end
+end

data/lib/market_town/checkout/steps/address_step.rb

@@ -0,0 +1,64 @@
+module MarketTown
+  module Checkout
+    class AddressStep < Step
+      class InvalidAddressError < Error; end
+      class CannotFulfilAddressError < Error; end
+
+      steps :validate_billing_address,
+            :use_billing_address_as_delivery_address,
+            :validate_delivery_address,
+            :ensure_delivery,
+            :store_addresses,
+            :propose_shipments,
+            :finish_address_step
+
+      protected
+
+      def validate_billing_address(state)
+        validate_address(:billing, state[:billing_address])
+      end
+
+      def use_billing_address_as_delivery_address(state)
+        if state[:use_billing_address] == true
+          state.merge(delivery_address: state[:billing_address])
+        end
+      end
+
+      def validate_delivery_address(state)
+        validate_address(:delivery, state[:delivery_address])
+      end
+
+      def ensure_delivery(state)
+        unless deps.fulfilments.can_fulfil_address?(state)
+          raise CannotFulfilAddressError.new(state[:delivery_address])
+        end
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_ensure_delivery)
+      end
+
+      def store_addresses(state)
+        deps.address_storage.store(state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_store_address)
+      end
+
+      def propose_shipments(state)
+        deps.fulfilments.propose_shipments(state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_propose_shipments)
+      end
+
+      def finish_address_step(state)
+        deps.finish.address_step(state)
+      end
+
+      private
+
+      def validate_address(type, address)
+        Address.validate!(address)
+      rescue Address::InvalidError => e
+        raise InvalidAddressError.new({ type: type }.merge(e.data))
+      end
+    end
+  end
+end

data/lib/market_town/checkout/steps/cart_step.rb

@@ -0,0 +1,24 @@
+module MarketTown
+  module Checkout
+    class CartStep < Step
+      steps :ensure_line_items,
+            :load_default_addresses,
+            :finish_cart_step
+
+      protected
+
+      def ensure_line_items(state)
+      end
+
+      def load_default_addresses(state)
+        deps.address_storage.load_default(state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_load_default_addresses)
+      end
+
+      def finish_cart_step(state)
+        deps.finish.cart_step(state)
+      end
+    end
+  end
+end

data/lib/market_town/checkout/steps/complete_step.rb

@@ -0,0 +1,36 @@
+module MarketTown
+  module Checkout
+    class CompleteStep < Step
+      class AlreadyCompleteError < Error; end
+
+      steps :ensure_incomplete,
+            :fulfil_order,
+            :send_order_complete_notice,
+            :finish_complete_step
+
+      protected
+
+      def ensure_incomplete(state)
+        if deps.finish.complete_step_finished?(state)
+          raise AlreadyCompleteError.new(state)
+        end
+      end
+
+      def fulfil_order(state)
+        deps.fulfilments.fulfil(state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_fulfil_order)
+      end
+
+      def send_order_complete_notice(state)
+        deps.notifications.notify(:order_complete, state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_send_order_complete_notice)
+      end
+
+      def finish_complete_step(state)
+        deps.finish.complete_step(state)
+      end
+    end
+  end
+end

data/lib/market_town/checkout/steps/delivery_step.rb

@@ -0,0 +1,39 @@
+module MarketTown
+  module Checkout
+    class DeliveryStep < Step
+      class InvalidDeliveryAddressError < Error; end
+      class CannotFulfilShipmentsError < Error; end
+
+      steps :validate_delivery_address,
+            :validate_shipments,
+            :apply_delivery_promotions,
+            :finish_delivery_step
+
+      protected
+
+      def validate_delivery_address(state)
+        Address.validate!(state[:delivery_address])
+      rescue Address::InvalidError => e
+        raise InvalidDeliveryAddressError.new(e.data)
+      end
+
+      def validate_shipments(state)
+        unless deps.fulfilments.can_fulfil_shipments?(state)
+          raise CannotFulfilShipmentsError.new(state[:shipments])
+        end
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_validate_shipments)
+      end
+
+      def apply_delivery_promotions(state)
+        deps.promotions.apply_delivery_promotions(state)
+      rescue MissingDependency
+        add_dependency_missing_warning(state, :cannot_apply_delivery_promotions)
+      end
+
+      def finish_delivery_step(state)
+        deps.finish.delivery_step(state)
+      end
+    end
+  end
+end

data/lib/market_town/checkout/steps/step.rb

@@ -0,0 +1,41 @@
+module MarketTown
+  module Checkout
+    class Step
+      def self.steps(*steps)
+        if steps.empty?
+          @steps
+        else
+          @steps = steps
+        end
+      end
+
+      attr_reader :meta, :deps
+
+      def initialize(dependencies = Dependencies.new)
+        @meta = { name: name_from_class }
+        @deps = dependencies
+      end
+
+      def process(state)
+        self.class.steps.reduce(state) do |state, step|
+          send(step, state) || state
+        end
+      end
+
+      private
+
+      def name_from_class
+        self.class.name.split('::').last.sub('Step', '').downcase.to_sym
+      end
+
+      def [](meta_key)
+        meta.fetch(meta_key)
+      end
+
+      def add_dependency_missing_warning(state, warning)
+        deps.logger.warn("MissingDependency so #{warning.to_s.split('_').join(' ')}")
+        state.merge(warnings: state.fetch(:warnings, []).push(warning))
+      end
+    end
+  end
+end

data/lib/market_town/checkout/version.rb

@@ -0,0 +1,5 @@
+module MarketTown
+  module Checkout
+    VERSION = '0.1.0'
+  end
+end

data/lib/market_town/checkout.rb

@@ -0,0 +1,55 @@
+# MarketTown is a collection of gems for providing e-commerce functionality to
+# ruby apps.
+#
+# Maintained by Luke Morton. MIT Licensed.
+#
+module MarketTown
+  # {Checkout} provides a simple interface to perform a single step in a
+  # checkout process.
+  #
+  # ## Processing a step
+  #
+  # If we wanted to process the delivery step of an order we would do something
+  # like this:
+  #
+  # ``` ruby
+  # order = Order.find(1)
+  #
+  # delivery_address = { name: 'Luke Morton',
+  #                      address_1: '21 Cool St',
+  #                      locality: 'London',
+  #                      postal_code: 'N1 1PQ',
+  #                      country: 'GB' }
+  #
+  # MarketTown::Checkout.process_step(step: :delivery,
+  #                                   dependencies: AppContainer.new,
+  #                                   state: { order: order,
+  #                                            delivery_address: delivery_address,
+  #                                            delivery_method: :next_day })
+  # ```
+  #
+  # To find out more about `AppContainer` please see {Dependencies}.
+  #
+  module Checkout
+    extend self
+
+    # @param [Hash] options
+    # @option options [Symbol] :step One of `:address`, `:delivery`, `:complete`
+    # @option options [Dependencies] :dependencies
+    # @option options [Hash] :state A step dependant Hash
+    #
+    def process_step(options)
+      step = const_get(options.fetch(:step).to_s.capitalize << 'Step')
+      step.new(options.fetch(:dependencies)).process(options.fetch(:state))
+    end
+  end
+end
+
+require_relative './checkout/models/address'
+require_relative './checkout/missing_dependency'
+require_relative './checkout/dependencies'
+require_relative './checkout/error'
+require_relative './checkout/steps/step'
+require_relative './checkout/steps/address_step'
+require_relative './checkout/steps/delivery_step'
+require_relative './checkout/steps/complete_step'

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: market_town-checkout
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Luke Morton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: countries
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: lukemorton.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/market_town/checkout.rb
+- lib/market_town/checkout/dependencies.rb
+- lib/market_town/checkout/error.rb
+- lib/market_town/checkout/missing_dependency.rb
+- lib/market_town/checkout/models/address.rb
+- lib/market_town/checkout/steps/address_step.rb
+- lib/market_town/checkout/steps/cart_step.rb
+- lib/market_town/checkout/steps/complete_step.rb
+- lib/market_town/checkout/steps/delivery_step.rb
+- lib/market_town/checkout/steps/step.rb
+- lib/market_town/checkout/version.rb
+homepage: https://github.com/lukemorton/market_town
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Business logic for e-commerce checkouts
+test_files: []
+has_rdoc: