market_town-checkout 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 248333e5411064b778918baad5c255f009ebd07f
-  data.tar.gz: 708d710d4e7ec962a017c72cc9099cd3922461f7
+  metadata.gz: d56e8ab33f9b246e43a09187bafe27f4f1726337
+  data.tar.gz: f4365e815a8df693f3d0e0a146445b20310e2377
 SHA512:
-  metadata.gz: 1b6dcd7003da193d40b838a74ccbb170d40157a89c820736797f37520c39be678135619a9ebed271063723766060c3689d0680e361fad7b933f63ed03aad03ca
-  data.tar.gz: 14665062ba3b4d705110fe6b44823645ad97030856d0343fffb36c6b105aaef83b157f2d6ade5ff6d71c161d3c45fd5100a72fdd503613df53e92ab6adc10651
+  metadata.gz: 5b812c35b5a8e7942859866e7635f6eaefbf2d08107830352d2a2e63a434534ffde09a75c15bccf841b96a3cf317f8acc514dc51bbfdcbd173a7f34df157875b
+  data.tar.gz: 0103ea588a6c72642cd4ad491de1c7d09be48027b56b857cc93d12a7bf320b31d6879faf45caf897e24f45fae7d23e20f46f4d51ad2020cd25c9b87c8e53567f

data/lib/market_town/checkout.rb

@@ -32,6 +32,7 @@ module MarketTown
   #
   # ## Available steps
   #
+  #  - {CartStep} – Handles the initialisation of the checkout process
   #  - {AddressStep} – Handles the taking of billing and delivery addresses
   #  - {DeliveryStep} – Handles the choosing of delivery method
   #  - {CompleteStep} – Handles completion of order
@@ -56,6 +57,7 @@ require_relative './checkout/missing_dependency'
 require_relative './checkout/dependencies'
 require_relative './checkout/error'
 require_relative './checkout/steps/step'
+require_relative './checkout/steps/cart_step'
 require_relative './checkout/steps/address_step'
 require_relative './checkout/steps/delivery_step'
 require_relative './checkout/steps/complete_step'

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

@@ -1,5 +1,13 @@
 module MarketTown
   module Checkout
+    # Handles addresses by validating them and optionally storing them.
+    #
+    # Dependencies:
+    #  - fulfilments#can_fulfil_address?
+    #  - address_storage#store
+    #  - fulfilments#propose_shipments
+    #  - finish#address_step
+    #
     class AddressStep < Step
       class InvalidAddressError < Error; end
       class CannotFulfilAddressError < Error; end
@@ -14,20 +22,30 @@ module MarketTown
 
       protected
 
+      # @raise [InvalidAddressError]
+      #
       def validate_billing_address(state)
         validate_address(:billing, state[:billing_address])
       end
 
+      # Copies billing address into delivery address if requested
+      #
       def use_billing_address_as_delivery_address(state)
         if state[:use_billing_address] == true
           state.merge(delivery_address: state[:billing_address])
         end
       end
 
+      # @raise [InvalidAddressError]
+      #
       def validate_delivery_address(state)
         validate_address(:delivery, state[:delivery_address])
       end
 
+      # Tries to ensure delivery can be made to address
+      #
+      # @raise [CannotFulfilAddressError]
+      #
       def ensure_delivery(state)
         unless deps.fulfilments.can_fulfil_address?(state)
           raise CannotFulfilAddressError.new(state[:delivery_address])
@@ -36,18 +54,25 @@ module MarketTown
         add_dependency_missing_warning(state, :cannot_ensure_delivery)
       end
 
+      # Tries to store addresses
+      #
       def store_addresses(state)
         deps.address_storage.store(state)
       rescue MissingDependency
         add_dependency_missing_warning(state, :cannot_store_address)
       end
 
+      # Tries to proposes shipments to delivery address ready to be confirmed at
+      # delivery step.
+      #
       def propose_shipments(state)
         deps.fulfilments.propose_shipments(state)
       rescue MissingDependency
         add_dependency_missing_warning(state, :cannot_propose_shipments)
       end
 
+      # Finishes address step
+      #
       def finish_address_step(state)
         deps.finish.address_step(state)
       end

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

@@ -1,5 +1,14 @@
 module MarketTown
   module Checkout
+    # The place where a checkout process begins. This step represents the
+    # finalisation of a cart before the checkout process.
+    #
+    # Dependencies:
+    #  - order#has_line_items?
+    #  - address_storage#load_default
+    #  - promotions#apply_cart_promotions
+    #  - finish#cart_step
+    #
     class CartStep < Step
       class NoLineItemsError < Error; end
 
@@ -9,18 +18,29 @@ module MarketTown
 
       protected
 
+      # @raise [NoLineItemsError] when no line items on order
+      #
       def ensure_line_items(state)
         unless deps.order.has_line_items?(state)
           raise NoLineItemsError.new(state)
         end
       end
 
+      # Tries to load default addresses
+      #
       def load_default_addresses(state)
         deps.address_storage.load_default(state)
       rescue MissingDependency
         add_dependency_missing_warning(state, :cannot_load_default_addresses)
       end
 
+      # Tries to apply cart promotions
+      #
+      def apply_cart_promotions(state)
+      end
+
+      # Finishes cart step
+      #
       def finish_cart_step(state)
         deps.finish.cart_step(state)
       end

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

@@ -1,5 +1,15 @@
 module MarketTown
   module Checkout
+    # Handles completion of checkout. All payments and options should have
+    # already been completed by this point. The purpose of this step is to
+    # request the fulfilment of the order and notify the customer.
+    #
+    # Dependencies:
+    #  - finish#complete_step_finished?
+    #  - fulfilments#fulfil
+    #  - notifications#notify
+    #  - finish#complete_step
+    #
     class CompleteStep < Step
       class AlreadyCompleteError < Error; end
 
@@ -10,24 +20,32 @@ module MarketTown
 
       protected
 
+      # @raise [AlreadyCompleteError]
+      #
       def ensure_incomplete(state)
         if deps.finish.complete_step_finished?(state)
           raise AlreadyCompleteError.new(state)
         end
       end
 
+      # Tries to fulfil order
+      #
       def fulfil_order(state)
         deps.fulfilments.fulfil(state)
       rescue MissingDependency
         add_dependency_missing_warning(state, :cannot_fulfil_order)
       end
 
+      # Tries to send notifications about order complete
+      #
       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
 
+      # Finishes complete step
+      #
       def finish_complete_step(state)
         deps.finish.complete_step(state)
       end

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

@@ -1,5 +1,12 @@
 module MarketTown
   module Checkout
+    # Handles delivery method and application of delivery promotions.
+    #
+    # Dependencies:
+    #  - fulfilments#can_fulfil_shipments?
+    #  - promotions#apply_delivery_promotions
+    #  - finish#delivery_step
+    #
     class DeliveryStep < Step
       class InvalidDeliveryAddressError < Error; end
       class CannotFulfilShipmentsError < Error; end
@@ -11,12 +18,18 @@ module MarketTown
 
       protected
 
+      # @raise [InvalidDeliveryAddressError]
+      #
       def validate_delivery_address(state)
         Address.validate!(state[:delivery_address])
       rescue Address::InvalidError => e
         raise InvalidDeliveryAddressError.new(e.data)
       end
 
+      # Tries to validate shipments
+      #
+      # @raise [CannotFulfilShipmentsError]
+      #
       def validate_shipments(state)
         unless deps.fulfilments.can_fulfil_shipments?(state)
           raise CannotFulfilShipmentsError.new(state[:shipments])
@@ -25,12 +38,16 @@ module MarketTown
         add_dependency_missing_warning(state, :cannot_validate_shipments)
       end
 
+      # Tries to apply delivery promotions
+      #
       def apply_delivery_promotions(state)
         deps.promotions.apply_delivery_promotions(state)
       rescue MissingDependency
         add_dependency_missing_warning(state, :cannot_apply_delivery_promotions)
       end
 
+      # Finish delivery step
+      #
       def finish_delivery_step(state)
         deps.finish.delivery_step(state)
       end

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

@@ -1,6 +1,92 @@
 module MarketTown
   module Checkout
+    # Extended by all steps provided by {MarketTown::Checkout}.
+    #
+    # ## Creating your own {Step}
+    #
+    # If you wish to create your own step then you can extend {Step} or you can
+    # create a class that looks like step.
+    #
+    # ### Extending {Step}
+    #
+    # ``` ruby
+    # class MyStep < MarketTown::Checkout::Step
+    #   steps :a_step,
+    #         :a_second_step
+    #
+    #   protected
+    #
+    #   def a_step(state)
+    #   end
+    #
+    #   def a_second_step(state)
+    #   end
+    # end
+    # ```
+    #
+    # ### Duck typing {Step}
+    #
+    # ``` ruby
+    # class MyCustomStep
+    #   def initialize(dependencies)
+    #   end
+    #
+    #   def process(state)
+    #   end
+    # end
+    # ```
+    #
+    # ## Extending an existing step
+    #
+    # You may want to alter the behaviour of a {Step}. You can do this quite
+    # easily by extending the class.
+    #
+    # In the example below we'll replace the behaviour of {AddressStep} to
+    # allow the use of delivery address as billing address instead of the
+    # default behaviour that does the opposite.
+    #
+    # ``` ruby
+    # class MyAddressStep < MarketTown::Checkout::AddressStep
+    #   # Here we override the step order as defined in AddressStep. We
+    #   # also replace #use_billing_address_as_delivery_address with
+    #   # #use_delivery_address_as_billing_address.
+    #   #
+    #   steps :validate_delivery_address,
+    #         :use_delivery_address_as_billing_address,
+    #         :validate_billing_address,
+    #         :ensure_delivery,
+    #         :store_addresses,
+    #         :propose_shipments,
+    #         :finish_address_step
+    #
+    #   protected
+    #
+    #   def use_delivery_address_as_billing_address(state)
+    #     if state[:use_delivery_address] == true
+    #       state.merge(billing_address: state[:delivery_address])
+    #     end
+    #   end
+    # end
+    # ```
+    #
+    #
     class Step
+      # Set steps for a subclass of {Step}.
+      #
+      # @example
+      #   class MyStep < MarketTown::Checkout::Step
+      #     steps :a_step,
+      #           :a_second_step
+      #
+      #     protected
+      #
+      #     def a_step(state)
+      #     end
+      #
+      #     def a_second_step(state)
+      #     end
+      #   end
+      #
       def self.steps(*steps)
         if steps.empty?
           @steps
@@ -11,11 +97,17 @@ module MarketTown
 
       attr_reader :meta, :deps
 
+      # Setup step meta object.
+      #
+      # @param [Dependencies]
+      #
       def initialize(dependencies = Dependencies.new)
         @meta = { name: name_from_class }
         @deps = dependencies
       end
 
+      # Process each sub-step that makes up step.
+      #
       def process(state)
         self.class.steps.reduce(state) do |state, step|
           send(step, state) || state
@@ -33,7 +125,7 @@ module MarketTown
       end
 
       def add_dependency_missing_warning(state, warning)
-        deps.logger.warn("MissingDependency so #{warning.to_s.split('_').join(' ')}")
+        deps.logger.warn("MissingDependency so #{warning.to_s.gsub('_', ' ')}")
         state.merge(warnings: state.fetch(:warnings, []).push(warning))
       end
     end

data/lib/market_town/checkout/version.rb

@@ -1,5 +1,5 @@
 module MarketTown
   module Checkout
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: market_town-checkout
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Luke Morton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-23 00:00:00.000000000 Z
+date: 2016-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel