four_tell 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0a2b99d95056ec90012bd1edbe1d3b19f98b2e5c
+  data.tar.gz: c50dc87fe437127f094cc8a6cda4197ce3d3851c
+SHA512:
+  metadata.gz: 4ddd82c4cc00e2481f32cf37e855bbc83f6736b8d0021350c21e08245e53d2284682a34682bc022012a043d00f46078500d74a3e2707e2977a79d6fd6e51adb1
+  data.tar.gz: c1d2715dc0d74ce75851e19153d39cc014ae0a437e5b8545decac6cd036a0825c8c99e270ef4ea920cdff72656e70279a3fc83ef682b02a616f00a6a6041eab2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,8 @@
+cache:
+  bundler: true
+git:
+  depth: 1
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in four_tell.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jon-Michael Deldin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# FourTell
+[![Build Status](https://travis-ci.org/TheClymb/four_tell.png?branch=master)](https://travis-ci.org/TheClymb/four_tell)
+[![Code Climate](https://codeclimate.com/github/TheClymb/four_tell.png)](https://codeclimate.com/github/TheClymb/four_tell)
+
+Ruby API bindings for the [4-Tell](http://www.4-tell.com/)
+personalization service.
+
+## Installation
+
+FourTell supports Ruby 2.0+. Add this line to your application's
+Gemfile:
+
+    gem 'four_tell'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install four_tell
+
+## Usage
+
+See the
+[documentation](http://rubydoc.info/github/TheClymb/four_tell/frames)
+for more details.
+
+```ruby
+require 'four_tell'
+ft = FourTell.new('username', 'password', 'your_four_tell_client_alias')
+
+# see FourTell::Request for more details
+req = ft.build_request
+req.customer_id = 1
+
+# fetch a list of recommended product IDs
+ft.recommendations(req)
+```
+
+## Contributing
+
+1. [Fork it](http://github.com/TheClymb/four_tell/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Author
+
+Built at [The Clymb](http://www.theclymb.com) by
+
+- [Jon-Michael Deldin](https://github.com/jmdeldin)
+- [Chris Kuttruff](https://github.com/ckuttruff)
+- [Max Justus Spransy](https://github.com/maxjustus)
+
+PS: [We're hiring!](http://www.theclymb.com/careers)

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'spec'
+  t.test_files = FileList['spec/*_spec.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/four_tell.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'four_tell'
+
+Gem::Specification.new do |spec|
+  spec.name          = "four_tell"
+  spec.version       = FourTell::VERSION
+  spec.authors       = ["Jon-Michael Deldin"]
+  spec.email         = ["dev@jmdeldin.com"]
+  spec.summary       = "Ruby bindings to the 4-Tell API."
+  spec.homepage      = "https://github.com/TheClymb/four_tell"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "excon", "> 0.27"
+  spec.add_dependency 'net-http-persistent', '~> 2.9.4'
+end

data/lib/four_tell.rb

@@ -0,0 +1,39 @@
+require 'net/https'
+require 'net/http/persistent'
+require 'four_tell/request'
+require 'json'
+
+class FourTell
+  VERSION = "1.0.0"
+
+  # @param [String] api_user
+  # @param [String] api_password
+  # @param [String] client_alias
+  def initialize(api_user, api_password, client_alias)
+    @api_user     = api_user
+    @api_password = api_password
+    @client_alias = client_alias
+  end
+
+  # Retrieve a list of recommended product IDs for a given request.
+  #
+  # @param [FourTell::Request] request
+  # @param [Fixnum] timeout Seconds to wait before timing out the request
+  # @raise [Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET]
+  # @return [Array]
+  def recommendations(request, timeout: 3)
+    url = URI(request.url)
+    response = Timeout::timeout(timeout) {
+      http = Net::HTTP::Persistent.new 'fourtell'
+      req = Net::HTTP::Get.new(url.request_uri)
+      req.basic_auth(@api_user, @api_password)
+      http.request(url, req)
+    }
+    (response && response.code == '200') ? JSON.parse(response.body) : []
+  end
+
+  # @return [FourTell::Request]
+  def build_request
+    FourTell::Request.new(@client_alias)
+  end
+end

data/lib/four_tell/request.rb

@@ -0,0 +1,141 @@
+require 'set'
+
+class FourTell
+  class Request
+    # @param [String] client_alias Your 4-Tell account name
+    def initialize(client_alias)
+      @client_alias = client_alias
+      @format       = 'json'
+      @num_results  = 20
+      @result_type  = :cross_sell
+    end
+
+    # *REQUIRED*: The customer_id sent to 4-Tell. This should correspond to the
+    # customer ID sent via data exports.
+    #
+    # @param [Fixnum]
+    attr_writer :customer_id
+
+    # The result type to return
+    #
+    # - cross-sell: recommending something based on a customer's likes
+    # - personal: based upon purchase history
+    # - similar: just bought a shirt, here's another
+    #
+    # @param [Symbol]
+    attr_writer :result_type
+
+    # The number of desired results between 1-20 (20 is the max limit in the
+    # 4-Tell API)
+    #
+    # @param [Fixnum]
+    attr_writer :num_results
+
+    # The product ID of the primary item on the page
+    #
+    # @param [Fixnum]
+    attr_writer :product_id
+
+    # Ordered list of most recently visited to least recently visited product
+    # IDs. Only 5 unique product IDs will be included.
+    #
+    # @param [Array]
+    attr_writer :click_stream_product_ids
+
+    # List of product IDs in the customer's cart
+    #
+    # @param [Array]
+    attr_writer :cart_product_ids
+
+    # Help 4-Tell provide the right kind of recommendations for the page
+    #
+    # Can be one of:
+    #  - Hm
+    #  - Pdp1
+    #  - Pdp2
+    #  - Cat
+    #  - Srch
+    #  - Cart
+    #  - Chkout
+    #  - Bought
+    #  - Admin
+    #  - Other
+    #
+    # @param [Symbol]
+    attr_writer :page_type
+
+    # Parameters for the 4-Tell call. Empty parameters are omitted.
+    #
+    # @return [Hash]
+    def params
+      {}.tap { |h|
+        h['clientAlias']    = client_alias
+        h['format']         = format
+        h['customerID']     = customer_id
+        h['numResults']     = num_results
+        h['resultType']     = result_type
+        h['productIDs']     = product_id
+        h['clickStreamIDs'] = click_stream_product_ids
+        h['cartIDs']        = cart_product_ids
+        h['pageType']       = page_type
+      }.reduce({}) do |h, (k, v)|
+        h[k] = v if v
+        h
+      end
+    end
+
+    def url
+      u = URI('https://live.4-tell.net/Boost2.0/rest/GetRecIDs/array')
+      u.query = URI.encode_www_form(params)
+      u.to_s
+    end
+
+    private
+
+    RESULT_TYPES = {cross_sell: 0, personal: 1, similar: 2}
+    PAGE_TYPES = Set.new(%i(Hm Pdp1 Pdp2 Cat Srch Cart Chkout Bought Admin Other))
+
+    attr_reader :client_alias, :format, :product_id
+
+    def customer_id
+      @customer_id or raise(ArgumentError, 'customer_id is required')
+    end
+
+    def result_type
+      RESULT_TYPES.fetch(@result_type)
+    end
+
+    def num_results
+      n = Integer(@num_results)
+
+      if n <= 0 || n > 20
+        raise(ArgumentError, 'num_results must be between 1-20')
+      else
+        n
+      end
+    end
+
+    def click_stream_product_ids
+      unless empty_array?(@click_stream_product_ids)
+        @click_stream_product_ids.uniq.take(5).join(',')
+      end
+    end
+
+    def cart_product_ids
+      @cart_product_ids.uniq.join(',') unless empty_array?(@cart_product_ids)
+    end
+
+    def page_type
+      return nil unless @page_type
+
+      if @page_type && !PAGE_TYPES.include?(@page_type)
+        raise(ArgumentError, "#{@page_type} is an invalid page_type")
+      end
+      @page_type.to_s
+    end
+
+    def empty_array?(ary)
+      ary.nil? || ary.empty?
+    end
+  end
+end

data/spec/four_tell_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+require 'webmock/minitest'
+
+describe FourTell do
+  let(:ft) { FourTell.new('username', 'password', 'client_alias') }
+
+  describe '#recommendations' do
+    it 'hits 4Tell' do
+      ids = (1..20).to_a.join(',')
+      base_url = "live.4-tell.net/Boost2.0/rest/GetRecIDs/array?clientAlias=client_alias&customerID=1&format=json&numResults=20&resultType=0"
+
+      stub_request(:get, "https://username:password@#{base_url}").
+        to_return(:status => 200, :body => "[#{ids}]")
+
+      req = MiniTest::Mock.new
+      req.expect :url, "https://#{base_url}"
+      ft.recommendations(req)
+
+      assert_requested(:get, "https://username:password@#{base_url}")
+    end
+  end
+end

data/spec/request_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+
+describe FourTell::Request do
+  let(:req) {
+    FourTell::Request.new('the_client_alias').tap { |r| r.customer_id = 1 }
+  }
+
+  def fetch_param(key)
+    req.params.fetch(key.to_s)
+  end
+
+  describe '#client_alias' do
+    specify do
+      fetch_param(:clientAlias).must_equal 'the_client_alias'
+    end
+  end
+
+  describe '#num_results' do
+    it 'can be set' do
+      req.num_results = 3
+      fetch_param(:numResults).must_equal 3
+    end
+
+    it 'defaults to 20' do
+      fetch_param(:numResults).must_equal 20
+    end
+
+    let(:err_msg) { 'num_results must be between 1-20' }
+    it 'cannot be <= 0' do
+      err = assert_raises(ArgumentError) { req.num_results = 0; req.params }
+      assert_equal err_msg, err.message
+    end
+    it 'cannot be > 20' do
+      err = assert_raises(ArgumentError) { req.num_results = 21; req.params }
+      assert_equal err_msg, err.message
+    end
+  end
+
+  describe '#format' do
+    it 'is JSON' do
+      fetch_param(:format).must_equal 'json'
+    end
+  end
+
+  describe '#customer_id' do
+    it 'is included' do
+      req.customer_id = 100
+      fetch_param(:customerID).must_equal 100
+    end
+
+    it 'is required' do
+      r = FourTell::Request.new('the_client_alias')
+      err = assert_raises(ArgumentError) { r.params }
+      assert_equal 'customer_id is required', err.message
+    end
+  end
+
+  describe '#result_type' do
+    it 'defaults to cross-sell' do
+      fetch_param(:resultType).must_equal 0
+    end
+
+    it 'converts cross-sell' do
+      req.result_type = :cross_sell
+      fetch_param(:resultType).must_equal 0
+    end
+
+    it 'converts personal' do
+      req.result_type = :personal
+      fetch_param(:resultType).must_equal 1
+    end
+
+    it 'converts similar' do
+      req.result_type = :similar
+      fetch_param(:resultType).must_equal 2
+    end
+
+    it 'throws an error if given an unknown symbol' do
+      req.result_type = :magic
+      assert_raises(KeyError) { req.params }
+    end
+  end
+
+  describe '#product_id' do
+    it 'is included' do
+      req.product_id = 314159
+      fetch_param(:productIDs).must_equal 314159
+    end
+  end
+
+  describe '#click_stream_product_ids' do
+    it 'sets these to clickStreamIDs' do
+      req.click_stream_product_ids = [3, 1, 4]
+      fetch_param(:clickStreamIDs).must_equal '3,1,4'
+    end
+
+    it 'dedupes and limits to 5' do
+      req.click_stream_product_ids = [3, 1, 4, 1, 5, 9, 2]
+      fetch_param(:clickStreamIDs).must_equal '3,1,4,5,9'
+    end
+  end
+
+  describe '#cart_product_ids' do
+    it 'dedupes' do
+      req.cart_product_ids = [3, 1, 4, 1, 5, 9, 2]
+      fetch_param(:cartIDs).must_equal '3,1,4,5,9,2'
+    end
+  end
+
+  describe '#page_type' do
+    it 'validates' do
+      %i(Hm Pdp1 Pdp2 Cat Srch Cart Chkout Bought Admin Other).each do |t|
+        req.page_type = t
+        fetch_param(:pageType).must_equal t.to_s
+      end
+    end
+
+    it 'can be nil' do
+      req.page_type = nil
+      req.params['pageType'].must_be_nil
+    end
+
+    it 'raises an error on invalid page_types' do
+      req.page_type = 'SECRET HIDEOUT'
+      err = assert_raises(ArgumentError) { fetch_param(:pageType) }
+      assert_equal 'SECRET HIDEOUT is an invalid page_type', err.message
+    end
+  end
+
+  describe '#url' do
+    let(:base_url) {
+      'https://live.4-tell.net/Boost2.0/rest/GetRecIDs/array?clientAlias=the_client_alias&format=json'
+    }
+
+    it 'omits empty parameters' do
+      req.product_id = 2
+      u = base_url + '&customerID=1&numResults=20&resultType=0&productIDs=2'
+      req.url.must_equal u
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'minitest/autorun'
+require 'minitest/pride'
+require 'four_tell'

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: four_tell
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jon-Michael Deldin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !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: webmock
+  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: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.27'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.27'
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.9.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.9.4
+description: 
+email:
+- dev@jmdeldin.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- four_tell.gemspec
+- lib/four_tell.rb
+- lib/four_tell/request.rb
+- spec/four_tell_spec.rb
+- spec/request_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/TheClymb/four_tell
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Ruby bindings to the 4-Tell API.
+test_files:
+- spec/four_tell_spec.rb
+- spec/request_spec.rb
+- spec/spec_helper.rb
+has_rdoc: