Flow.io < - > Spree adapter

All flowcommerce_spree code is located in the ./app and ./lib folders.

Installation

• Add the gem to main application's Gemfile:

  gem 'flowcommerce_spree', git: 'https://github.com/mejuri-inc/flowcommerce_spree'
  

• If the main application's Rails version is less than 4.2, add also to main application's Gemfile the activerecord -postgres-json gem (at least version 0.2.3):

  gem 'activerecord-postgres-json', '>= 0.2.3'
  

• Run bundle install.

• Define these additional ENV variables.

  • You will find FLOW_TOKEN, FLOW_ORGANIZATION and FLOW_BASE_COUNTRY in Flow console

  • To enable HTTP Basic authentication for securing the FlowcommerceSpree::WebhooksController, prepend username:password@ to the hostname in your webhook URL. By doing so, the credentials needed for authentication will be sent in the HTTP header. For example: https://username:password@www.mywebhookurl.com On the main app's backend side, the username and password values should be defined in the FLOW_IO_WEBHOOK_USER and FLOW_IO_WEBHOOK_PASSWORD environment variables

    FLOW_TOKEN='SUPERsecretTOKEN' # API_KEY
    FLOW_ORGANIZATION='spree-app-sandbox'
    FLOW_BASE_COUNTRY='usa'
    # The path to which the FlowcommerceSpree engine will be mounted (default, if this variable is missing, will be the 
    # '/flow' path)
    FLOW_MOUNT_PATH='/flow'
    # The following variables should be set for securing the FlowcommerceSpree::WebhooksControler
    FLOW_IO_WEBHOOK_USER
    FLOW_IO_WEBHOOK_PASSWORD
    

• To enable payments with the FlowCommerce engine, the payment method flow.io with Spree::Gateway::FlowIo should be added in the Spree Admin. This payment method is automatically registered in the gem in an after_initialize Rails engine callback:

    # lib/flowcommerce_spree/engine.rb
    config.after_initialize do |app|
      # init Flow payments as an option
      app.config.spree.payment_methods << Spree::Gateway::FlowIo
    end
  

• To see and optionally invoke the list of FlowCommerce tasks, run bundle exec rake flowcommerce_spree:list_tasks . Any task from the list could be invoked, typing at the Type the task number to be invoked: prompt the task number, or from a terminal prompt, in the main application's root folder, running bundle exec rake {task_name}

• Run the flowcommerce_spree:install:migrations task to copy the DB migrations' file into the main application's db/migrate folder.

• Run bundle exec rake db:migrate SCOPE=flowcommerce_spree from a terminal prompt. This will add an meta jsonb column to the Spree::CreditCard, Spree::Product, Spree::Variant, Spree::Order, Spree::Promotion models' DB tables, if there is not yet such a column defined.

• If the main application's Rails version is less than 4.2, add the JSON serializer for the meta column to the affected models' decorators (Spree::CreditCard, Spree::Product, Spree::Variant, Spree::Order, Spree::Promotion models):

  serialize :flow_data, ActiveRecord::Coders::JSON.new(symbolize_keys: true)

FlowcommerceSpree::Api module

This is a legacy module using the curl gem for making direct calls to flow.io API. It will be refactored out in future versions of the gem in favor of using the official flow.io API client from the flowcommerce gem.

FlowcommerceSpree::ExperienceService

Responsible for selecting current experience. You have to define available experiences in flow console.

FlowcommerceSpree::OrderSync

Maintain and synchronizes Spree::Order with Flow API.

FlowcommerceSpree::Session

Every shop user has a session. This class helps in creating and maintaining session with Flow.

Decorators

Decorators are used extensively across the gem to modify or add behaviour of several Spree classes and modules. To properly deal with the precedence in the Ruby ancestor chain, the class_eval, include and prepend methods are being used, depending on the level of modification.

Spree::Gateway::FlowIo

Adapter for Spree, that allows using Flow.io as payment gateway. Flow is PCI compliant payment processor.

Gem Maintenance

Preparing a release

Merge all the pull requests that should make it into the new release into the main branch, then checkout and pull the branch and run the github_changelog_generator, specifying the new version as a --future-release cli parameter:

git checkout main
git pull

github_changelog_generator -u mejuri-inc -p flowcommerce_spree --future-release v0.0.2

Then add the changes to git, commit and push the Preparing the new release commit directly into the main branch:

git add .
git commit -m 'Preparing the new v0.0.2 release'
git push

RubyGems credentials

Ensure you have the RubyGems credentials located in the ~/.gem/credentials file.

Adding a gem owner

gem owner flowcommerce_spree -a sebastian.deluca@mejuri.com

Building a new gem version

Adjust the new gem version number in the lib/flowcommerce_spree/version.rb file. It is used when building the gem by the following command:

gem build flowcommerce_spree.gemspec

Assuming the version was set to 0.0.1, a flowcommerce_spree-0.0.1.gem binary file will be generated at the root of the app (repo).

• The binary file shouldn't be added into the git tree, it will be pushed into the RubyGems and to the GitHub releases

Pushing a new gem release to RubyGems

gem push flowcommerce_spree-0.0.1.gem # don't forget to specify the correct version number

Crafting the new release on GitHub

On the Releases page push the Draft a new release button.

The new release editing page opens, on which the following actions could be taken:

• Choose the repo branch (default is main)
• Insert a tag version (usually, the tag should correspond to the gem's new version, v0.0.1, for example)
  • the tag will be created by GitHub on the last commit into the chosen branch
• Fill the release Title and Description
• Attach the binary file with the generated gem version
• If the release is not yet ready for production, mark the This is a pre-release checkbox
• Press either the Publish release, or the Save draft button if you want to publish it later
  • After publishing the release, the the binary gem file will be available on GitHub and could be removed locally