zanox_publisher 0.1.0

data/lib/zanox_publisher/base.rb

@@ -0,0 +1,69 @@
+module ZanoxPublisher
+  # Base class for resources with pagination
+  class Base
+    @@default_per_page = 10
+    @@maximum_per_page = 50
+
+    class << self
+      # Getter for the maximum per page
+      #
+      # @return [Integer]
+      def maximum_per_page
+        @@maximum_per_page
+      end
+
+      # Set the number of items to request per page.
+      #
+      # @param number [Integer] The number of items per page (default = 10; maximum = 50)
+      #
+      # @return [Integer]
+      #
+      # @example
+      #         ZanoxPublisher::AdSpace.per_page = 20     #=> 20
+      #         first_page = ZanoxPublisher::AdSpace.page #=> [Array<AdSpace>]
+      def per_page=(number)
+        if number.to_i < 0
+          @per_page = 0
+        elsif number.to_i > @@maximum_per_page
+          @per_page = @@maximum_per_page
+        else
+          @per_page = number.to_i
+        end
+
+        @per_page
+      end
+
+      # Returns the number of items to request per page.
+      # The default of 10 is returned if per_page is not set.
+      #
+      # @return [Integer]
+      def per_page
+        @per_page ||= @@default_per_page
+      end
+
+      # Internally set total item count.
+      #
+      # @param number [Integer] The total items from the API response
+      #
+      # @return [Integer]
+      def total=(number)
+        @total = number
+      end
+
+      # Returns the total number of items or nil in case no page was requested
+      #
+      # @return [Integer, nil]
+      #
+      # @example
+      #         data = []
+      #         number = 0
+      #         do
+      #           data << ZanoxPublisher::AdSpace.page(number)
+      #           number += 1
+      #         end while data.size < ZanoxPublisher::AdSpace.total
+      def total
+        @total
+      end
+    end
+  end
+end

data/lib/zanox_publisher/category.rb

@@ -0,0 +1,57 @@
+module ZanoxPublisher
+  # General category class
+  #
+  # Legacy name category is for program and admedium
+  #
+  # NOTE: Later create enumerable class Categories to allow .include? on result from API
+  #
+  # @param [Integer] id     The identifer of the category
+  # @param [String]  name   The name of the category
+  class Category
+    class << self
+      # Fetch all categories from Zanox API Response
+      #
+      # @param data [Array] the value of the 'categories' element
+      #
+      # @return [Array<Category>, nil]
+      def fetch(data = nil)
+        # To support API of picking categories of hash with [] notation
+        return nil if data.nil?
+        categories = data.first
+        # In case the array is empty first will return a nil
+        return nil if categories.nil?
+        categories = categories['category']
+        # In case the second level is missing the hash [] notation will nil
+        return nil if categories.nil?
+        # In case just one category is in the list it must be converted back to an array
+        categories = [categories] if categories.is_a? Hash
+
+        # We got the array of category hash's
+        retval = []
+
+        categories.each do |category|
+          retval << self.new(category)
+        end
+
+        retval
+      end
+    end
+    attr_reader :id, :name
+
+    def initialize(data = {})
+      @id   = data.fetch('@id').to_i
+      @name = data.fetch('$', nil)
+    end
+
+    def to_s
+      @name
+    end
+
+    # Returns the category ID as integer representation
+    #
+    # @return [Integer]
+    def to_i
+      @id
+    end
+  end
+end

data/lib/zanox_publisher/connection.rb

@@ -0,0 +1,291 @@
+require 'httparty'
+require 'base64'
+require 'openssl'
+
+module ZanoxPublisher
+  # Represents a Zanox Product API error. Contains specific data about the error.
+  class ZanoxError < StandardError
+    attr_reader :data
+
+    def initialize(data)
+      @data   = data
+
+      # should contain Code, Message, and Reason
+      code    = data['code'].to_s
+      message = data['message'].to_s
+      reason  = data['reason'].to_s
+      super "The Zanox Product API responded with the following error message: #{message} Error reason: #{reason} [code: #{code}]"
+    end
+  end
+
+  # Raised for HTTP response codes of 400...500
+  class ClientError < StandardError; end
+  # Raised for HTTP response codes of 500...600
+  class ServerError < StandardError; end
+  # Raised for HTTP response code of 400
+  class BadRequest < ZanoxError; end
+  # Raised when authentication information is missing
+  class AuthenticationError < StandardError; end
+  # Raised when authentication fails with HTTP response code of 403
+  class Unauthorized < ZanoxError; end
+  # Raised for HTTP response code of 404
+  class NotFound < ClientError; end
+
+  # Raw connection to the Zanox API
+  #
+  # @attr [String] relative_path    The default relative path used for a request
+  class Connection
+    include HTTParty
+
+    API_URI     = 'https://api.zanox.com'
+    DATA_FORMAT = 'json'
+    API_VERSION = '2011-03-01'
+
+    base_uri "#{API_URI}/#{DATA_FORMAT}/#{API_VERSION}"
+
+    USER_AGENT_STRING = "ZanoxPublisher/#{VERSION} (ruby #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}; #{RUBY_PLATFORM})"
+
+    attr_accessor :relative_path
+
+    # Initializes a new connection instance of ZanoxPublisher.
+    # It requires authentication information to access the Publisher API.
+    # The relative path is used as the default for HTTP method calls.
+    #
+    # The connect ID and secret key can be passed as parameters,
+    # else the ZanoxPublisher::authenticate information is taken.
+    #
+    # @param relative_path [String] The default relative path of the resource
+    # @param connect_id [String] The connect ID of your account for authentication
+    # @param secret_key [String] The secret key of your account for authentication
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new("/profiles", "<your_client_id>", "<your_client_secret>") #=> #<Connection ...>
+    #           connection.get #=> #<HTTParty::Response ...>
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.get('/profiles') #=> #<Hash::Response ...>
+    #
+    def initialize(relative_path = '', connect_id = ZanoxPublisher.connect_id, secret_key = ZanoxPublisher.secret_key)
+      @connect_id, @secret_key = connect_id, secret_key
+      @relative_path = relative_path
+      @connection = self.class
+    end
+
+    # Sends a GET request for a public resource - auth with connect ID
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.get('/path') #=> #<Hash::Response ...>
+    def get(relative_path = @relative_path, params = {})
+      handle_response connection.get(relative_path, public_auth(params))
+    end
+
+    # Sends a POST request for a public resource - auth with connect ID
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.post('/path') #=> #<Hash::Response ...>
+    def post(relative_path = @relative_path, params = {})
+      handle_response connection.post(relative_path, public_auth(params))
+    end
+
+    # Sends a PUT request for a public resource - auth with connect ID
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.put('/path') #=> #<Hash::Response ...>
+    def put(relative_path = @relative_path, params = {})
+      handle_response connection.put(relative_path, public_auth(params))
+    end
+
+    # Sends a DELETE request for a public resource - auth with connect ID
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.delete('/path') #=> #<Hash::Response ...>
+    def delete(relative_path = @relative_path, params = {})
+      handle_response connection.delete(relative_path, public_auth(params))
+    end
+
+    # Sends a GET request for a private resource - auth with signature
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.signature_get('/path') #=> #<Hash::Response ...>
+    def signature_get(relative_path = @relative_path, params = {})
+      handle_response connection.get(relative_path, private_auth('GET', relative_path, params))
+    end
+
+    # Sends a POST request for a private resource - auth with signature
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.signature_post('/path') #=> #<Hash::Response ...>
+    def signature_post(relative_path = @relative_path, params = {})
+      handle_response connection.post(relative_path, private_auth('POST', relative_path, params))
+    end
+
+    # Sends a PUT request for a private resource - auth with signature
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.signature_put('/path') #=> #<Hash::Response ...>
+    def signature_put(relative_path = @relative_path, params = {})
+      handle_response connection.put(relative_path, private_auth('PUT', relative_path, params))
+    end
+
+    # Sends a DELETE request for a private resource - auth with signature
+    #
+    # For more information on authentication see {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest}
+    #
+    # @param relative_path [String] The relative path of the API resource
+    # @param params [Hash] The HTTParty params argument
+    #
+    # @return [Hash]
+    #
+    # @example
+    #           connection = ZanoxPublisher::Connection.new #=> #<Connection ...>
+    #           connection.signature_delete('/path') #=> #<Hash::Response ...>
+    def signature_delete(relative_path = @relative_path, params = {})
+      handle_response connection.delete(relative_path, private_auth('DELETE', relative_path, params))
+    end
+
+    private
+
+    attr_reader :connection
+
+    # Internal routine to handle the HTTParty::Response
+    def handle_response(response) # :nodoc:
+      case response.code
+      when 400
+        #IN CASE WE WANT MORE PRECISE ERROR NAMES
+        #data = response.parsed_response
+        #case data['code']
+        #when 230
+        #  raise ParameterDataInvalid.new data
+        #else
+        #  raise BadRequest.new data
+        #end
+        raise BadRequest.new(response.parsed_response)
+      when 403
+        raise Unauthorized.new(response.parsed_response)
+      when 404
+        raise NotFound.new
+      when 400...500
+        raise ClientError.new
+      when 500...600
+        raise ServerError.new
+      else
+        response.parsed_response
+      end
+    end
+
+    # Authentication header for public resources of the Zanox API
+    # Public resources - auth with connection ID.
+    #
+    # For details access the guide found {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest here}.
+    def public_auth(params)
+      raise AuthenticationError, 'Please provide your connect ID.' if @connect_id.nil?
+
+      auth = { 'Authorization' => "ZXWS #{@connect_id}" }
+
+      if params.has_key? :headers
+        params[:headers].merge(auth)
+      else
+        params[:headers] = auth
+      end
+
+      params
+    end
+
+    # Authentication header for private resources of the Zanox API
+    # Private resources - auth with signature.
+    #
+    # For details access the guide found {https://developer.zanox.com/web/guest/authentication/zanox-oauth/oauth-rest here}.
+    # Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) );
+    # StringToSign = HTTP-Verb + URI + timestamp + nonce
+    # HTTP Verb - GET, POST, PUT or DELETE;
+    # URI - exclude return format and API version date, include path parameters http://api.zanox.com/json/2011-03-01 -> /reports/sales/date/2013-07-20
+    # Timestamp - in GMT, format "EEE, dd MMM yyyy HH:mm:ss";
+    # Nonce - unique random string, generated at the time of request, valid once, 20 or more characters
+    def private_auth(verb, relative_path, params)
+      raise AuthenticationError, 'Please provide your connect ID.' if @connect_id.nil?
+      raise AuthenticationError, 'Please provide your secret key.' if @secret_key.nil?
+
+      # API Method: GET Sales for the date 2013-07-20
+      # 1. Generate nonce and timestamp
+      timestamp = Time.new.gmtime.strftime('%a, %e %b %Y %T GMT').to_s
+      # %e is with 0 padding so 06 for day 6 else use %d
+      #timestamp = Time.new.gmtime.strftime('%a, %d %b %Y %T GMT').to_s
+      nonce = OpenSSL::Digest::MD5.hexdigest((Time.new.usec + rand()).to_s)
+      # 2. Concatinate HTTP Verb, URI, timestamp and nonce to create StringToSign
+      string_to_sign = "#{verb}#{relative_path}#{timestamp}#{nonce}"
+      # 3. Hash the StringToSign using the secret key as HMAC parameter
+      signature = Base64.encode64("#{OpenSSL::HMAC.digest('sha1', @secret_key, string_to_sign)}").chomp
+      # 4. Add information to request headers
+      auth = {
+        'Authorization' => "ZXWS #{@connect_id}:#{signature}",
+        'Date' => timestamp,
+        'nonce' => nonce
+      }
+
+      if params.has_key? :headers
+        params[:headers].merge(auth)
+      else
+        params[:headers] = auth
+      end
+
+      params
+    end
+  end
+end

data/lib/zanox_publisher/exclusive_incentive.rb

@@ -0,0 +1,135 @@
+module ZanoxPublisher
+  # Exclusive incentives - Get coupons and other incentives
+  #
+  # The Zanox API cannot retrieve both exclusive and non-exclusive incentives, so each has its own class.
+  class ExclusiveIncentive < IncentiveBase
+    RESOURCE_PATH = '/incentives/exclusive'
+
+    # Set the exclusive attribute
+    @@exclusive = true
+
+    class << self
+      # Retrieves all incentive's dependent on search parameters.
+      #
+      # This is equivalent to the Zanox API method SearchExclusiveIncentives.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-incentives-exclusive}.
+      #
+      # Authentication: Requires signature.
+      #
+      # This can require multiple requests, as internally every page is pulled.
+      # The ZanoxPublisher::AdMedium.page function can be used to better control the requests made.
+      #
+      # @param program [Program, Integer] limits results to a particular program ID.
+      # @param adspace [AdSpace, Integer] limits results to incentives that have tracking links associated with this AdSpace.
+      # @param incentive_type [String] limits results to one of the following incentive types (API equivalent is incentiveType).
+      # @param incentiveType [String] limits results to one of the following incentive types (API name).
+      # @param region [String] limits results to a region.
+      #
+      # @return [Array<ExclusiveIncentive>]
+      def all(options = {})
+        retval = []
+        current_page = 0
+        options.merge!({ per_page: maximum_per_page })
+
+        begin
+          retval       += self.page(current_page, options)
+          current_page += 1
+        end while ExclusiveIncentive.total > retval.size
+
+        retval
+      end
+
+      # Retrieves a list of exclusive incentiveItems dependent on search parameter.
+      #
+      # This is equivalent to the Zanox API method SearchExclusiveIncentives.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-incentives-exclusive}.
+      #
+      # Authentication: Requires signature.
+      #
+      # @param page [Integer] the page position.
+      # @param per_page [Integer] number of items in the result set (API equivalent is items).
+      # @param items [Integer] number of items in the result set (API name).
+      # @param program [Program, Integer] limits results to a particular program ID.
+      # @param adspace [AdSpace, Integer] limits results to incentives that have tracking links associated with this AdSpace.
+      # @param incentive_type [String] limits results to one of the following incentive types (API equivalent is incentiveType).
+      # @param incentiveType [String] limits results to one of the following incentive types (API name).
+      # @param region [String] limits results to a region.
+      #
+      # @return [Array<ExclusiveIncentive>]
+      def page(page = 0, options = {})
+        params = { query: { page: page } }
+
+        per_page = nil
+        per_page = options[:per_page] if per_page.nil?
+        per_page = options[:items]    if per_page.nil?
+        per_page = AdMedium.per_page  if per_page.nil?
+        params[:query].merge!({ items: per_page })
+
+        program = options[:program]
+        program = program.to_i        unless program.nil?
+
+        adspace = options[:adspace]
+        adspace = adspace.to_i        unless adspace.nil?
+
+        incentive_type = options[:incentive_type]
+        incentive_type = options[:incentiveType]  if incentive_type.nil?
+        incentive_type = nil unless @@incentive_types.include? incentive_type
+
+        region = options[:region]
+
+        # Build the query on hand of the options received
+        params[:query].merge!({ program: program })               unless program.nil?
+        params[:query].merge!({ adspace: adspace })               unless adspace.nil?
+        params[:query].merge!({ incentiveType: incentive_type })  unless incentive_type.nil?
+        params[:query].merge!({ region: region })                 unless region.nil?
+
+        retval = []
+
+        response = self.connection.signature_get(RESOURCE_PATH, params)
+
+        ExclusiveIncentive.total = response.fetch('total')
+
+        incentives = []
+        incentives = response.fetch('incentiveItems', {}).fetch('incentiveItem', []) if ExclusiveIncentive.total > 0
+        incentives = [incentives] unless incentives.is_a? Array
+
+        incentives.each do |incentive|
+          retval << ExclusiveIncentive.new(incentive, @@exclusive)
+        end
+
+        retval
+      end
+
+      # Returns a single incentiveItem, as queried by its ID.
+      #
+      # This is equivalent to the Zanox API method GetExclusiveIncentive.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-incentives-exclusive-incentive}.
+      #
+      # Authentication: Requires signature.
+      #
+      # @param id [Integer] the ID of the adspace you want to get.
+      # @param adspace [AdSpace, Integer] if you would like tracking links for only one of your publisher ad spaces, pass its ID in this parameter.
+      #
+      # @return [<ExclusiveIncentive>]
+      def find(id, options = {})
+        params  = {}
+
+        adspace = options[:adspace]
+        adspace = adspace.to_i unless adspace.nil?
+
+        params  = { query: { adspace: adspace } } unless adspace.nil?
+
+        response = self.connection.signature_get(RESOURCE_PATH + "/incentive/#{id.to_i}", params)
+
+        ExclusiveIncentive.new(response.fetch('incentiveItem'), @@exclusive)
+      end
+
+      # A connection instance with ExclusiveIncentives' relative_path
+      #
+      # @return [Connection]
+      def connection
+        @connection ||= Connection.new(RESOURCE_PATH)
+      end
+    end
+  end
+end

data/lib/zanox_publisher/format.rb

@@ -0,0 +1,19 @@
+module ZanoxPublisher
+  # Wrapper for the format response from Zanox API
+  class Format
+    attr_reader :id, :name
+
+    def initialize(data = {})
+      @id   = data.fetch('@id').to_i
+      @name = data.fetch('$')
+    end
+
+    def to_s
+      @name
+    end
+
+    def to_i
+      @id
+    end
+  end
+end