loyalty_lab_sdk 0.0.0

data/CHANGELOG.rdoc

@@ -0,0 +1,10 @@
+= Loyalty Lab SDK
+
+== Version 0.0.0
+* Initial release
+* Supports all LoyaltyAPI calls
+* Supports lazy authentication
+* Supports environment variable authentication
+* Helpers for creating shoppers
+* Supports retries on timeout errors
+* Supports re-authentication when authentication token expires

data/LICENSE.txt

@@ -0,0 +1,9 @@
+Copyright (c) 2012 RevPAR Collective, Inc.
+
+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.
+
+THIS SOFTWARE IS IN NO WAY AFFILIATED WITH THE LOYALTY LAB ORGANIZATION.

data/README.rdoc

@@ -0,0 +1,45 @@
+= Loyalty Lab SDK
+
+A ruby library for accessing the Loyalty Lab API documented here: http://api.loyaltylab.com/loyaltyapi/help/index.html
+
+This library attempts to be as transparent as possible by making all method calls, parameters, and objects identical to those documented at the above URL. Capitalization goes against typical ruby conventions, and is instead as documented by Loyalty Lab.
+
+NOTE: This software is in no way affiliated with the Loyalty Lab organization.
+
+== Synopsis
+
+ LoyaltyLabSDK.config(:username => 'foo', :password => 'bar')
+
+ api = LoyaltyLabSDK::LoyaltyAPI.new
+ shopper = api.GetShopper 'shopperId' => 1234
+ shopper_id = shopper['ShopperId']
+ point_balance = api.AdjustShopperPoints 'shopperId' => shopper_id,
+  'pointChange' => 1000,
+  'pointType' => 'Base',
+  'description' => 'Surprise bonus'
+
+ new_retailer_shopper_id = 1234
+ new_shopper = api.build_default_shopper(new_retailer_shopper_id)
+ new_shopper['EmailAddress'] = 'test@gmail.com'
+ new_shopper['FirstName'] = 'Joe'
+ new_shopper['LastName'] = 'Schmoe'
+ new_card = api.build_default_card(new_retailer_shopper_id)
+ api.CreateShopperWithCard 'shopper' => new_shopper, 'card' => new_card
+
+== Authentication
+
+By default, a new LoyaltyAPI instance will authenticate itself against the API (using #authenticate!) and store the authentication token when it is constructed. Authentication may be skipped by setting the :lazy_authentication option to true when calling the constructor. In this case, authentication will occur when the first API call is made (or it may be done explicitly).
+
+According to Loyalty Lab, the authentication token will expire after 20 minutes of inactivity. By default, LoyaltyAPI has an option :allow_reauthenticate that defaults to true (may be overridden). If it's true, then when you receive an AuthenticationError while making an API call on an already-authenticated LoyaltyAPI instance, it will try once to re-authenticate automatically. This behavior could be overridden by the client by setting :allow_reauthenticate to false and then either ignoring the error, pro-actively calling #authenticate!, or catching AuthenticationError exceptions and re-authenticating then.
+
+== Timeouts
+
+By default, all requests will timeout (for opening connections and making requests) after 15 seconds. This may be overridden by setting the :open_timeout and :read_timeout options when calling LoyaltyLabSDK.config.
+
+== Environment Variables
+
+For convenience in a command-line environment, configuration of username and password may be skipped by setting the LOYALTY_LAB_SDK_USERNAME and LOYALTY_LAB_SDK_PASSWORD environment variables.
+
+== Rails
+
+If running in a rails environment, this configuration will automatically use the global Rails.logger instance. This behavior may be overridden by passing in a :logger option to LoyaltyLabSDK.config.

data/lib/loyalty_lab_sdk/config.rb

@@ -0,0 +1,62 @@
+require 'logger'
+
+module LoyaltyLabSDK
+
+  DEFAULT_TIMEOUT = 15
+  DEFAULT_RETRIES = 2
+
+  # Globally configures and retrieves configuration for the Loyalty Lab SDK.
+  #
+  # == Environment Variables
+  #
+  # For convenience in a command-line environment, configuration may be skipped
+  # by setting the LOYALTY_LAB_SDK_USERNAME and LOYALTY_LAB_SDK_PASSWORD
+  # environment variables, which are self-explanatory.
+  #
+  # == Rails
+  #
+  # If running in a rails environment, this configuration will automatically use
+  # the global Rails.logger instance. This behavior may be overridden by passing
+  # in a :logger option.
+  #
+  # @param [Hash] options
+  # @option options [String] :username (nil) Loyalty Lab account username
+  # @option options [String] :password (nil) Loyalty Lab account password
+  # @option options [Logger] :logger (Rails.logger) Logger to use
+  # @option options [Numeric] :open_timeout (LoyaltyLabSDK::DEFAULT_TIMEOUT)
+  #   Number of seconds to wait for the connection to open
+  #   (see Net::HTTP#open_timeout)
+  # @option options [Numeric] :read_timeout (LoyaltyLabSDK::DEFAULT_TIMEOUT)
+  #   Number of seconds to wait for one block to be read
+  #   (see Net::HTTP#read_timeout)
+  # @option options [Integer] :connection_error_retries
+  #   (LoyaltyLabSDK::DEFAULT_RETRIES) Number of retries that will be attempted
+  #   if a connection error (timeout) occurs
+  def self.config(options = nil)
+    @config ||= {
+      :username => ENV['LOYALTY_LAB_SDK_USERNAME'],
+      :password => ENV['LOYALTY_LAB_SDK_PASSWORD'],
+      :logger => default_logger,
+      :open_timeout => DEFAULT_TIMEOUT,
+      :read_timeout => DEFAULT_TIMEOUT,
+      :connection_error_retries => DEFAULT_RETRIES,
+    }
+    
+    @config.merge!(options) if options
+
+    @config
+  end
+
+  private
+
+  def self.default_logger
+    if defined?(::Rails)
+      ::Rails.logger
+    else
+      logger = ::Logger.new(STDERR)
+      logger.level = ::Logger::INFO
+      logger
+    end
+  end
+
+end

data/lib/loyalty_lab_sdk/exceptions.rb

@@ -0,0 +1,18 @@
+module LoyaltyLabSDK
+
+  # An abstract super-class of all other LoyaltyLabApi Error classes
+  class Error < StandardError; end
+  
+  # Indicates an error establishing a connection to the API, or a timeout that occurs while
+  # making an API call. Is relatively common and transient- worth retrying in important cases.
+  class ConnectionError < Error; end
+  
+  # Indicates an error authenticating with the provided credentials.
+  class AuthenticationError < Error; end
+  
+  # Indicates any other API error (generally should be non-transient and not worth retrying). The
+  # error code and string will be present in this error's message if one was provided in the
+  # response.
+  class UnknownError < Error; end
+
+end

data/lib/loyalty_lab_sdk/loyalty_api.rb

@@ -0,0 +1,329 @@
+require 'date'
+require 'loyalty_lab_sdk/exceptions'
+require 'active_support/inflector'
+require 'savon'
+
+module LoyaltyLabSDK
+class LoyaltyAPI
+
+  ENDPOINT = 'https://api.loyaltylab.com/loyaltyapi/loyaltyapi.asmx'
+  NAMESPACE = 'http://www.loyaltylab.com/loyaltyapi/'
+
+  # Constructs an object-oriented API to loyalty lab.
+  #
+  # In addition to the options specified below, any of the options documented
+  # in LoyaltyLabSDK#config may be overridden.
+  #
+  # It will establish a connection, authenticate the username/password, and store
+  # the authentication data upon construction unless the lazy_authentication
+  # parameter is set. This authentication token times out after 20 minutes
+  # (double-check Loyalty Lab's documentation), so a client wishing to use this
+  # object should accommodate that, and re-call #authenticate! if necessary.
+  #
+  # @param [Hash] options
+  # @option options [boolean] :lazy_authentication (false) Delays authentication
+  #   until either the first call is made or it is done explicitly.
+  # @option options [boolean] :allow_reauthenticate (true) If true, will
+  #   attempt to re-authenticate the client once automatically if an
+  #   AuthenticationError is thrown (on any call).
+  def initialize(options = {})
+    self.config = {
+      :lazy_authentication => false,
+      :allow_reauthenticate => true,
+    }.merge!(LoyaltyLabSDK.config).merge!(options)
+
+    Savon.configure do |c|
+      c.logger = config[:logger]
+      c.raise_errors = false
+    end
+
+    initialize_client
+
+    @authenticated = false
+
+    unless config[:lazy_authentication]
+      authenticate!
+    end
+  end
+
+  # Authenticates the client.
+  #
+  # This method is called by the constructor unless lazy_authentication is
+  # on, so this will not typically need to be invoked directly.
+  #
+  # An object that hasn't been called in 20 minutes will have its
+  # authentication headers expired by Loyalty Lab, requiring this method to
+  # be invoked again on long-lived objects.
+  def authenticate!
+    response = self.AuthenticateUser(
+      { :username => config[:username], :password => config[:password] },
+      :is_authenticate => true,
+      :allow_reauthenticate => false)
+
+    auth_data = {
+      :retailer_guid => response['RetailerGuid'],
+      :authenticated => response['Authenticated'],
+      :token => response['Token'],
+      :ics_user_id => response['ICSUserID']
+    }
+
+    if !auth_data[:authenticated]
+      raise AuthenticationError, 'authentication failed'
+    end
+
+    self.retailer_guid = auth_data[:retailer_guid]
+
+    self.auth_header = {
+      "wsdl:AuthenticationResult" => {
+        "wsdl:RetailerGuid" => auth_data[:retailer_guid],
+        "wsdl:Authenticated" => auth_data[:authenticated],
+        "wsdl:Token" => auth_data[:token],
+        "wsdl:ICSUserID" => auth_data[:ics_user_id],
+      }
+    }
+
+    @authenticated = true
+  end
+
+  # Implements most API calls. The API method should be passed as defined in Loyalty
+  # Lab's API documentation here: http://api.loyaltylab.com/loyaltyapi/help/index.html
+  #
+  # Each of the parameters should be passed in a hash as documented.
+  #
+  # Responses will be in the documented format (a "string" return value with respond
+  # with a string, etc...), or if it's an object (such as a Shopper object), the
+  # result will be a hash with string keys for object
+  #
+  # == Examples:
+  #
+  # === Retrieve a shopper
+  #  shopper = api.GetShopperByEmail 'email' => 'test@gmail.com'
+  #
+  # === Adjust shopper point balance
+  #  point_balance = api.AdjustShopperPoints 'shopperId' => shopper['ShopperId'],
+  #   'pointChange' => 1000,
+  #   'pointType' => 'Base',
+  #   'description' => 'Bonus'
+  #
+  # === Create a shopper with card
+  #  new_shopper = api.build_default_shopper(1234)
+  #  new_shopper['EmailAddress'] = 'test2@gmail.com'
+  #  new_shopper['FirstName'] = 'Joe'
+  #  new_shopper['LastName'] = 'Schmoe'
+  #  new_card = api.build_default_card(1234)
+  #  api.CreateShopperWithCard 'shopper' => new_shopper, 'card' => new_card
+  def method_missing(method_name, *args)
+    call_api_method(method_name, *args)
+  end
+
+  # Initializes and returns a shopper object with default fields set for use with a
+  # CreateShopper call.
+  #
+  # This object should be updated with all relevant fields (ie. email address, first
+  # name, phone number, etc) before being saved.
+  def build_default_shopper(retailer_shopper_id)
+    now = DateTime.now
+
+    {
+      'ShopperId' => 0,
+      'RetailerGUID' => retailer_guid,
+      'EmailAddress' => '',
+      'EmailFrequency' => 1,
+      'EmailFrequencyUnit' => 'D',
+      'EmailFormat' => 'HTML',
+      'Password' => ' ',
+      'Status' => 'A',
+      'LastName' => '',
+      'MiddleInitial' => '',
+      'FirstName' => '',
+      'Address1' => '',
+      'City' => '',
+      'State' => '',
+      'Zip' => '',
+      'PhoneNumber' => '',
+      'ProfileCreateDateTime' => now,
+      'ProfileUpdateDateTime' => now,
+      'CreateDateTime' => now,
+      'PasswordLastChanged' => now,
+      'Origin' => 'W',
+      'RetailerShopperId' => retailer_shopper_id.to_s,
+      'FileImportId' => 0,
+      'BulkEmail' => 1,
+      'LoyaltyMember' => true,
+      'PersonStatus' => 'P',
+      'RetailerRegistered' => false,
+      'MailOptIn' => false,
+      'PhoneOptIn' => false,
+      'RetailerShopperCreationDate' => now,
+      'LoyaltyLabCreateDateTime' => now,
+      'StatusUpdateDateTime' => now
+    }
+  end
+
+  # Initializes and returns a card object with default fields set for use with a
+  # CreateShopper call.
+  #
+  # This object should be updated with all relevant fields before being saved (if
+  # necessary).
+  def build_default_card(retailer_shopper_id)
+    now = DateTime.now
+
+    {
+      'RegisteredCardId' => 0,
+      'ShopperId' => 0,
+      'CommonName' => 'loyalty member id',
+      'AlternateCardIdentifier' => retailer_shopper_id.to_s,
+      'CardType' => 'L',
+      'ExpirationMonth' => 12,
+      'ExpirationYear' => 3010,
+      'LastFour' => ' ',
+      'CardHolderName' => ' ',
+      'Status' => 'A',
+      'CreateDateTime' => now,
+      'IsPreferred' => ' ',
+      'FileImportId' => 0
+    }
+  end
+
+  private
+
+  ERROR_HANDLERS = {
+    '100' => AuthenticationError
+  }
+
+  SHOPPER_FIELD_MAPPINGS = {
+    :retailer_guid => 'RetailerGUID'
+  }
+
+  FIELD_MAPPING = {
+    'AuthenticateUser' => {
+      :ics_user_id => 'ICSUserID'
+    },
+    'GetShopperByID' => SHOPPER_FIELD_MAPPINGS,
+    'GetShopperByEmail' => SHOPPER_FIELD_MAPPINGS,
+    'GetShopperByRetailerID' => SHOPPER_FIELD_MAPPINGS
+  }
+
+  attr_accessor :config, :client, :retailer_guid, :auth_header
+
+  def initialize_client
+    self.client = ::Savon::Client.new do
+      wsdl.endpoint = ENDPOINT
+      wsdl.namespace = NAMESPACE
+      http.open_timeout = config[:open_timeout]
+      http.read_timeout = config[:read_timeout]
+    end
+  end
+
+  def call_api_method(method_name, request_body = nil, options = {})
+    options = {
+      :is_authenticate => false,
+      :connection_error_retries => config[:connection_error_retries],
+      :allow_reauthenticate => config[:allow_reauthenticate],
+    }.merge(options)
+
+    if !@authenticated && !options[:is_authenticate]
+      authenticate!
+    end
+
+    method_name = method_name.to_s
+
+    request_body ||= {}
+
+    prepared_request_body = prepare_request(request_body)
+
+    begin
+      response = client.request "wsdl:#{method_name}" do |soap, wsdl, http, wsse|
+        http.headers["SOAPAction"] = "http://www.loyaltylab.com/loyaltyapi/#{method_name}"
+        soap.header = auth_header unless options[:is_authenticate]
+        soap.body = prepared_request_body
+      end
+    rescue Exception => e
+      config[:logger].debug "communication exception during request: #{e.message}"
+      if options[:connection_error_retries] > 0
+        config[:logger].debug "#{options[:connection_error_retries]} retry attempt(s) remaining; retrying..."
+        options[:connection_error_retries] -= 1
+        return call_api_method(method_name, request_body, options)
+      else
+        config[:logger].debug 'no retry attempts remaining'
+        raise ConnectionError, e.message
+      end
+    end
+
+    begin
+      check_response_for_errors(response)
+    rescue AuthenticationError => e
+      if options[:allow_reauthenticate]
+        authenticate!
+        options[:allow_reauthenticate] = false
+        return call_api_method(method_name, request_body, options)
+      else
+        raise e
+      end
+    end
+
+    modified_method_name = method_name.underscore
+
+    response = response.to_hash["#{modified_method_name}_response".to_sym]
+    response = response["#{modified_method_name}_result".to_sym] unless response.nil?
+
+    normalize_response method_name, response
+  end
+
+  # Returns a request hash with proper namespacing prefixes and transformations applied
+  # to the given request hash.
+  def prepare_request(request_hash = {}, nested_object = false)
+    result = {}
+    request_hash.each do |key, value|
+      # handle nested objects in the request (like a shopper)
+      value = prepare_request(value, true) if value.instance_of?(Hash)
+
+      # add the wsdl: prefix to the key
+      result["wsdl:#{key}"] = value
+    end
+    result
+  end
+
+  # Takes a raw response and checks it for errors, throwing proper exceptions if
+  # present.
+  def check_response_for_errors(response)
+    # take no action if there are no errors
+    return unless response.soap_fault? || response.http_error?
+
+    response_hash = response.to_hash
+    if response_hash[:fault] && response_hash[:fault][:detail]
+      # we can parse the response, so check the specific error code
+      error_code = response_hash[:fault][:detail][:code]
+
+      # if we can recognize the specific code, dispatch the proper exception
+      if ERROR_HANDLERS.has_key? error_code
+        raise ERROR_HANDLERS[error_code], response_hash[:fault][:faultstring]
+      end
+
+      # otherwise return a well-defined error string with the code and error message
+      raise UnknownError, "#{response_hash[:fault][:detail][:code]} #{response_hash[:fault][:detail][:description]}: #{response_hash[:fault][:faultstring]}"
+    end
+
+    # we can't parse the error, so just pass back the entire response body
+    raise UnknownError, response.to_s
+  end
+
+  def normalize_response(method_name, response, mapping = FIELD_MAPPING[method_name])
+    if response.instance_of?(Hash)
+      mapping ||= {}
+      response.inject({}) do |hash, (key, value)|
+        new_key = mapping[key] || key.to_s.camelize
+        hash[new_key] = normalize_response(nil, value, nil) # TODO: implement nested mappings
+        hash
+      end
+    elsif response.instance_of?(Array)
+      response.collect do |value|
+        normalize_response(nil, value, nil) # TODO: implement nested mappings
+      end
+    else
+      response
+    end
+  end
+
+end
+end

data/lib/loyalty_lab_sdk/version.rb

@@ -0,0 +1,3 @@
+module LoyaltyLabSDK
+  VERSION = '0.0.0'
+end

data/lib/loyalty_lab_sdk.rb

@@ -0,0 +1,24 @@
+require 'httpi'
+require 'net/http'
+
+# prevents debug log messages that clutter output
+HTTPI.log = false
+
+# prevents warning
+class Net::HTTP
+  alias_method :old_initialize, :initialize
+  def initialize(*args)
+    old_initialize(*args)
+    @ssl_context = OpenSSL::SSL::SSLContext.new
+    @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  end
+end
+
+require 'loyalty_lab_sdk/config'
+require 'loyalty_lab_sdk/exceptions'
+
+module LoyaltyLabSDK
+
+  autoload :LoyaltyAPI, 'loyalty_lab_sdk/loyalty_api'
+
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: loyalty_lab_sdk
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- David Dawson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-09 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70125150677680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70125150677680
+- !ruby/object:Gem::Dependency
+  name: httpi
+  requirement: &70125150676260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70125150676260
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: &70125150674620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70125150674620
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: &70125150673640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70125150673640
+- !ruby/object:Gem::Dependency
+  name: guid
+  requirement: &70125150672220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: *70125150672220
+description: Full documentation of the API is at http://api.loyaltylab.com/loyaltyapi/help/index.html.
+email: david@stashrewards.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+- CHANGELOG.rdoc
+- LICENSE.txt
+files:
+- lib/loyalty_lab_sdk/config.rb
+- lib/loyalty_lab_sdk/exceptions.rb
+- lib/loyalty_lab_sdk/loyalty_api.rb
+- lib/loyalty_lab_sdk/version.rb
+- lib/loyalty_lab_sdk.rb
+- README.rdoc
+- CHANGELOG.rdoc
+- LICENSE.txt
+homepage: http://www.stashrewards.com
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3780691586861817189
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Library for accessing the Loyalty Lab API.
+test_files: []