traction 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3773e88b2b90c95b451b5f8dee4cbb77464f6679
+  data.tar.gz: d6a69298660e16aa1399e094ccc2d70e60848a36
+SHA512:
+  metadata.gz: 995d56fccd80c6a9ba7e8161e516a3c0c3893f6b3a7887ad948f7e23d0f285d95c52da4c865deaf700fcd3f4cb049f64a9b6b405ce6e112397f222f570b68c93
+  data.tar.gz: 14e1d4f06de278bd2872d7626488c6f0deda647c2013b0f0546f3b2114af364386d8ece2617c32f5fe496780f0c29053ea2360c5b4f9899523289b9a8b2470a7

data/.gitignore

@@ -0,0 +1,33 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+*.swp
+*.swo
+*.swn

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/Gemfile

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

data/README.md

@@ -0,0 +1,77 @@
+# Traction
+
+A Ruby wrapper of the <a href="https://tractiondigital.com/" target="_blank">Traction Digital</a> API. The wrapper contains only methods for endpoints for which previous access has been established. The addition of new methods when an API is created is encouraged.
+
+Traction Digital <a href="https://int.tractionplatform.com/traction/help/int/webframe.html?Dynamic_API.html" target="_blank">API Documentation</a> requires an account and login. The documentation may be limited and/or out of date. Refer to the API Information associated with a particular function available in a specific campaign where possible for up to date information.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'traction'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself using Rubygems:
+
+    $ gem install traction
+
+## Usage
+
+Configure Traction with your API password and an object containing keys that become namespaces and paths associated with a "web connection" available to you in your Traction account. These paths are found in "API Information" in the Traction Account Dashboard, for a function within a given campaign.
+
+The available methods in traction depend on the functions created in the traction dashboard for a given campaign. To confirm a method is available, ensure that a traction function exists with the method detailed in the API Information tab.
+
+Using Rails, configuration can occur in an initializer:
+
+```ruby
+# config/initializers/traction.rb
+
+Traction.configure("<your_api_password>", {competition:  "<web_connection_path>",
+                                           registration: "<web_connection_path>",
+                                           triggered:    "<web_connection_path>"}
+```
+
+Or, it could happen anywhere in your Ruby app before method call, either on app load or in a before hook will work fine.
+
+Once you have completed configuration, use the gem methods to make api calls using the appropriate namespace you have created, associated with the traction function where that API is available:
+
+```ruby
+Traction.registration.get_customer_by("EMAIL", "example@email.com", ["EMAIL", "MOBILE", "FIRSTNAME", "LASTNAME"]
+#=>
+#{
+#  data: {
+#    customer: {
+#      email: "example@email.com",
+#      mobile: "0412345678",
+#      firstname: "Jane",
+#      lastname: "Doe"
+#    }
+#  },
+#  success: true
+#}
+ 
+```
+
+For the full list of available methods, refer to the <a href="http://www.rubydoc.info/gems/traction" target="_blank">documentation</a>.
+
+## To Do
+- provide some abstracted methods for removing subscriptions and groups etc
+- add remaining methods when access is gained to new function in Traction Dashboard
+
+## Contributing
+
+Contributions are fully encouraged as the Traction API documentation does not reveal all available methods and new methods are available only when a function is available in the Traction Account dashboard. Simple wrappers and abstractions are welcome.
+
+Particularly, given that traction functions exist for which no method has been made available yet, it is highly encouraged to add a method to this gem (using consistent style) if a user gains access to a function not yet wrapped by this gem.
+
+1. Fork it ( https://github.com/hardhatdigital/traction/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 a new Pull Request
+6. Party

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "traction"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/traction/version.rb

@@ -0,0 +1,4 @@
+module Traction
+  VERSION = "0.1.0"
+  DATE    = "2016-02-19"
+end

data/lib/traction/web_connection.rb

@@ -0,0 +1,328 @@
+require "json"
+require "net/http"
+
+module Traction
+
+  # Creates a new WebConnection object to contain wrapped API methods associated with a particular
+  # WebConnection, or Function, in Traction API terminology.
+  #
+  # Method examples use the hypothetical namespaces from the configuration example.
+  class WebConnection
+    DOMAIN = "int.api.tractionplatform.com"
+
+    def initialize(path, password)
+      @path = path
+      @password = password
+    end
+
+    # Registration method for retrieving attributes for a customer, searching against a given field.
+    #
+    # @param field      [String] The field to search against.
+    # @param value      [String] The value to search for.
+    # @param attributes [Array]  The retrieved customer fields on a successful result.
+    #
+    # @example
+    #           Traction.registration.get_customer_by("EMAIL", "example@email.com", ["EMAIL", "MOBILE", "FIRSTNAME", "LASTNAME"]
+    #           #=>
+    #           #{
+    #           #  data: {
+    #           #    customer: {
+    #           #      email: "example@email.com",
+    #           #      mobile: "0412345678",
+    #           #      firstname: "John",
+    #           #      lastname: "Doe"
+    #           #    }
+    #           #  },
+    #           #  success: true
+    #           #}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 1010,
+    #           #    description: "Customer not found",
+    #           #    cause: [{
+    #           #      "field": "customer.EMAIL"
+    #           #    }]
+    #           #  }
+    #           #}
+    def get_customer_by(field, value, attributes=[])
+      body = {customerLookup: {field => value},
+              customerAttributes: attributes}
+
+      get_response_for(body)
+    end
+
+    # Registration method for adding a customer to the campaign customer list.
+    #
+    # @param details       [Hash] The customer details to add.
+    # @param optional_data [Hash] Optional. Data available in triggered emails to the customer.
+    #
+    # @example
+    #           Traction.registration.add_customer("EMAIL" => "example@email.com", "MOBILE" => "0412345678", "FIRSTNAME" => "John", "LASTNAME" => "Doe")
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 1000,
+    #           #    description: "Invalid Parameter Data",
+    #           #    cause: [{
+    #           #      field: "customer.EMAIL",
+    #           #      message: "invalid email address"
+    #           #    }]
+    #           #  },
+    #           #  success: false
+    #           #}
+    def add_customer(details, optional_data={})
+      body = {customer: details,
+              transData: optional_data}
+
+      get_response_for(body)
+    end
+
+    # Registration method for adding a customer to the campaign customer list, and associating the customer
+    # with (or dissociating a customer from) groups and/or subscriptions.
+    #
+    # @param details       [Hash] The customer details to add.
+    # @param groups        [Hash] Optional. Groups to associate or dissociate with; true associates, false dissociates.
+    # @param subscriptions [Hash] Optional. Subscriptions to associate or dissociate with; "SUBSCRIBE" associates, "UNSUBSCRIBE" dissociates.
+    #
+    # @example
+    #           Traction.registration.add_customer_with_group_and_subscription({"EMAIL" => "example@email.com", "MOBILE" => "0412345678", "FIRSTNAME" => "John", "LASTNAME" => "Doe"}, {"12345" => true, "12346" => true, "23456" => false}, {"9876543210" => "SUBSCRIBE", "9876543211" => "SUBSCRIBE", "9876543212" => "UNSUBSCRIBE"})
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 1150,
+    #           #    description: "Invalid Group ID, please confirm group exists",
+    #           #    cause: "Group Id [12345] should be pre-existing"
+    #           #  },
+    #           #  success: false
+    #           #}
+    def add_customer_with_group_and_subscription(details, groups={}, subscriptions={})
+      body = {customer: details,
+              groups: groups,
+              subscriptions: subscriptions}
+
+      get_response_for(body)
+    end
+
+    # Registration method for adding a customer directly to an associated email list, selected on creation
+    # of the function in traction.
+    #
+    # @param details       [Hash] The customer details to add.
+    # @param optional_data [Hash] Optional. Data available in triggered emails to the customer.
+    #
+    # @example
+    #           Traction.registration.add_customer("EMAIL" => "example@email.com", "MOBILE" => "0412345678", "FIRSTNAME" => "John", "LASTNAME" => "Doe")
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 1000,
+    #           #    description: "Invalid Parameter Data",
+    #           #    cause: [{
+    #           #      field: "customer.EMAIL",
+    #           #      message: "invalid email address"
+    #           #    }]
+    #           #  },
+    #           #  success: false
+    #           #}
+    def web_registration(details, optional_data={})
+      body = {customer: details,
+              transData: optional_data}
+
+      get_response_for(body)
+    end
+
+    # Competition method for validating a potential entry to a competition.
+    #
+    # @param field      [String] The relevant customer field to validate with.
+    # @param value      [String] The value associated with the field.
+    # @param entry_code [String] The entry code to validate.
+    #
+    # @example
+    #           Traction.competition.validate_entry("EMAIL", "example@email.com", "ABC123")
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 2040,
+    #           #    description: "Entry Code Used",
+    #           #    cause: [{
+    #           #      field: "entryCode",
+    #           #      message: "[ABC123]  has already been used"
+    #           #    }]
+    #           #  },
+    #           #  success: false
+    #           #}
+    def validate_entry(field, value, entry_code)
+      body = {mode: "VALIDATE",
+              customer: {field => value},
+              entryCode: entry_code}
+       
+      get_response_for(body)
+    end
+
+    # Competition method for adding an entrant to (or removing an entrant from) a competition.
+    #
+    # @param details       [Hash]    The customer details to add.
+    # @param entry_code    [String]  The entry code for the entrant.
+    # @param subscribe     [Boolean] Optional. Subscribe (true) or unsubscribe (false) from the competition. Defaults to true.
+    # @param optional_data [Hash]    Optional. Data available in triggered emails to the customer.
+    #
+    # @example
+    #           Traction.competition.add_competition_entrant({"EMAIL" => "example@email.com", "MOBILE" => "0412345678", "FIRSTNAME" => "Jane", "LASTNAME" => "Doe"}, "XYZ123")
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 2040,
+    #           #    description: "Entry Code Used",
+    #           #    cause: [{
+    #           #      field: "entryCode",
+    #           #      message: "[XYZ123]  has already been used"
+    #           #    }]
+    #           #  },
+    #           #  success: false
+    #           #}
+    def add_competition_entrant(details, entry_code, subscribe=true, optional_data={})
+      body = {customer: details,
+              entryCode: entry_code,
+              subscribe: subscribe,
+              transData: optional_data}
+       
+      get_response_for(body)
+    end
+
+    # Competition method for drawing the competition winner/s.
+    #
+    # @param venues_ids [Array] Optional. List of venues for which the winner is drawn from. Defaults to all venues.
+    #
+    # @example
+    #           Traction.competition.draw
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 2140,
+    #           #    description: "Draw already done",
+    #           #    cause: null
+    #           #  },
+    #           #  success: false
+    #           #}
+    def draw_competition(venue_ids=[])
+      body = {mode: "DRAW"}
+      body[:venueIdList] = venue_ids if venue_ids.any?
+
+      get_response_for(body)
+    end
+
+    # Competition method for providing redemption code to a winner.
+    #
+    # @param field           [String] The field to search against.
+    # @param value           [String] The value to search for.
+    # @param venues_id       [String] Id of venue for which redemption code and customer apply.
+    # @param redemption_code [String] The redemption code for the winner.
+    # @param optional_data   [Hash]   Optional. Data available in triggered emails to the customer.
+    #
+    # @example
+    #           Traction.competition.redeem_winner("EMAIL", "example@email.com", "XYZ", "ABC123") 
+    #           #=>
+    #           #{
+    #           #  data: {
+    #           #    numWinners: 8,
+    #           #    numWinnersNoRedemptionCode: 2
+    #           #  },
+    #           #  success: true
+    #           #}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 2120,
+    #           #    description: "Claim code invalid",
+    #           #    cause: null
+    #           #  },
+    #           #  success: false
+    #           #}
+    def redeem_winner(field, value, venue_id, redemption_code, optional_data={})
+      body = {mode: "REDEEM",
+              customer: {field => value},
+              venueId: venue_id,
+              redemptionCode: redemption_code,
+              transData: optional_data}
+
+      get_response_for(body)
+    end
+
+    # Triggered Message method for sending a triggered email to a subscriber. The content of the email
+    # can be personalised with optional data, but should already exist in traction.
+    #
+    # @param email         [String] The email to search against.
+    # @param optional_data [Hash]   Optional. Data available in triggered emails to the customer.
+    #
+    # @example
+    #           Traction.triggered.send_triggered_email("example@email.com")
+    #           #=> {data: {}, success: true}
+    #           # OR
+    #           #=>
+    #           #{
+    #           #  error: {
+    #           #    code: 1000,
+    #           #    description: "Invalid Parameter Data",
+    #           #    cause: [{
+    #           #      field: "customer.Email",
+    #           #      message: "Invalid Email Address"
+    #           #    }]
+    #           #  },
+    #           #  success: false
+    #           #}
+    def send_triggered_email(email, optional_data={})
+      body = {customer: {EMAIL: email},
+              transData: optional_data}
+
+      get_response_for(body)
+    end
+
+   private
+
+    def get_response_for(body)
+      handle_response(
+        make_request(body))
+    end
+
+    def make_request(body)
+      uri = make_uri()
+
+      Net::HTTP.post_form(uri, {data: body.to_json, password: @password})
+    end
+
+    def handle_response(response)
+      case response.code
+      when "200"
+        JSON.parse(response.body)
+      when "401"
+        { success: false, error: { code: 401, description: "Unauthorised Access", cause: "The API call was not authorised. Check your URL and password details." } }
+      when "404"
+        { success: false, error: { code: 404, description: "Invalid URL", cause: "The URL was incorrect. Check your URL and password details." } }
+      when "503"
+        { success: false, error: { code: 503, description: "API Unavailable", cause: "The API is currently unavailable for upgrade or maintenance." } }
+      when "500"
+        { success: false, error: { code: 500, description: "Other", cause: "Unrecoverable or unknown error - API server may be down" } }
+      else
+        { success: false, error: { code: 000, description: "Unknown", cause: "Unknown error, possibly internal to gem." } }
+      end
+    end
+
+    def make_uri
+      URI.parse("https://#{DOMAIN}/#{@path}")
+    end
+  end
+end

data/lib/traction.rb

@@ -0,0 +1,31 @@
+require "traction/web_connection"
+
+# The Traction module houses methods to interact with the Traction API.
+module Traction
+
+  # Configure Traction with your API password and an object containing keys that become namespaces
+  # and paths associated with a "web connection" available to you in your Traction account.
+  # These paths are found in "API Information" in the Traction Account Dashboard, for a function
+  # within a given campaign.
+  #
+  # An ArgumentError is raised if you attempt to create a web connection name using a reserved word.
+  #
+  # The below example generates the namespaces Traction.competition and Traction.registration for
+  # functions available in the traction dashboard. The methods available to these namespaces will
+  # depend on the functions that were created in the traction dashboard.
+  #
+  # @param password             [String] Your API password. You might want to keep this a secret.
+  # @param web_connection_paths [Hash]   The namespaces and paths for each "function" eg. "/wkf/81h2ehc781hjd"
+  #
+  # @example
+  #           Traction.configure("<your_api_password>", {competition:  "<web_connection_path>",
+  #                                                      registration: "<web_connection_path>",
+  #                                                      triggered:    "<web_connection_path>"}
+  def self.configure(password, web_connection_paths={})
+    web_connection_paths.each do |name, path|
+      raise ArgumentError, "!ERROR: Unable to define a web_connection_paths path with name: #{name} as this is a reserved name." if self.class.respond_to?(name)
+      self.class.send(:define_method, name, -> { WebConnection.new(path, password) })
+    end
+  end
+
+end

data/traction.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'traction/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "traction"
+  spec.version       = Traction::VERSION
+  spec.date          = Traction::DATE
+
+  spec.summary       = ""
+  spec.description   = ""
+
+  spec.authors       = [""]
+  spec.email         = [""]
+  spec.homepage      = ""
+
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: traction
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ''
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: ''
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/traction.rb
+- lib/traction/version.rb
+- lib/traction/web_connection.rb
+- traction.gemspec
+homepage: ''
+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.4.6
+signing_key: 
+specification_version: 4
+summary: ''
+test_files: []
+has_rdoc: