zanox_publisher 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5c6bf86e78f08a2c0843e4bbd65559a199ecafd8
+  data.tar.gz: cf5642ccc19e98e22ed773532b3e46c29dad6a70
+SHA512:
+  metadata.gz: 735892e5eda13333689055bd9bb34566c7f24e5ea1dd9813aa051145198520686894bc8061d52646964ce3f7ffd98f5ce1c509021963bf5fe522fcdb835ac087
+  data.tar.gz: 9086e6044aa019dd1f197b6f3fd1a012d07a10181d0ceadefe444073aeb27466105320f564b0baa8a11c00b0b28221bb6cdc494c4b14ca6df4c3dbebd824159e

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+spec/config/credentials.yml

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Oliver Prater
+
+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,178 @@
+# ZanoxPublisher
+
+This is a ruby wrapper for the [ZANOX Publisher API](https://developer.zanox.com/web/guest/publisher-api-2011), released on March 1, 2011.
+
+## Installation
+
+The simplest way to install ZanoxPublisher is with [Bundler](http://gembundler.com/).
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'zanox_publisher'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
+
+    $ gem install zanox_publisher
+
+## Configuration
+
+The Zanox Publisher API requires a connect ID and a secret key to make requests directly related with the account.
+General information can often be retrieved with just the connect ID.
+
+The required information for each request can be found in the [documentation][documentation].
+
+The connect ID and secret key can be set with the authenticate method:
+
+```ruby
+ZanoxPublisher.authenticate('Connect ID', 'Secret key')
+```
+
+Or directly on ZanoxPublisher.
+
+```ruby
+ZanoxPublisher.connect_id = 'Connect ID'
+ZanoxPublisher.secret_key = 'Secret key'
+```
+
+## Usage
+
+The gem is designed for integratation with Ruby on Rails in mind.
+The method names try to follow the common methods found on an ActiveRecord object.
+
+### Usage with Rails
+
+Install ZanoxPublisher by adding it to your projects `Gemfile`.
+
+```ruby
+gem 'zanox_publisher'
+```
+
+And then execute:
+
+    $ bundle
+
+Finally, create an initializer file `config/initializers/zanox_publisher.rb` to hold the configuration.
+
+```ruby
+ZanoxPublisher.authenticate('Connect ID', 'Secret key')
+```
+
+To make an API call in your application simply use the gems corresponding ruby object.
+
+### Usage outside of Rails
+
+To use ZanoxPublisher in plain ruby require the gem and set the configuration before running your code.
+
+```ruby
+require 'zanox_publisher'
+
+ZanoxPublisher.authenticate('Connect ID', 'Secret key')
+
+# Your code here
+```
+
+### Basic examples
+
+ZanoxPublisher is designed to be a full ruby object representation for each of the Zanox API endpoints.
+The matching of ruby objects to Zanox API method name's is given in the List of Objects.
+
+The examples below expect that ZanoxPublisher is correctly configured and show only some basic usage examples.
+Check the [documentation][documentation] for the complete reference.
+
+**Search for a program that sells hats**
+
+```ruby
+programs_that_sell_hats = ZanoxPublisher::Program.all q: 'hats', has_products: true
+#=> [<Program>,...]
+
+programs_that_sell_hats.count
+#=> 84
+
+first_program = programs_that_sell_hats.first
+#=> <Program>
+
+first_program.name
+#=> "Asos.com DE"
+
+first_program.products
+#=> 50129
+```
+
+**Search for a fitting product to an comment**
+
+```ruby
+adspaces = ZanoxPublisher::AdSpace.all
+#=> [<AdSpace>,...]
+
+adspace  = adspaces.select { |adspace| adspace.url == 'http://www.my-blog.com/' }.first
+#=> <AdSpace>
+
+my_programs = ZanoxPublisher::ProgramApplication.all(status: 'confirmed').map(&:program)
+#=> [<Program>,...]
+
+comment = params['comment']
+#=> 'I also want a baseball cap.'
+
+products = ZanoxPublisher::Product.page 0, per_page: 1, query: comment, adspace: adspace, programs: my_programs
+#=> [<Product>]
+
+product = products.first
+#=> <Product>
+
+product.tracking_links.first.ppc
+#=> "http://ad.zanox.com/ppv/?..."
+```
+
+### List of Objects (Implimented)
+
+* `ZanoxPublisher::AdMedium`: GetAdmedia, GetAdmedium
+* `ZanoxPublisher::AdSpace`: GetAdspaces, GetAdspace
+* `ZanoxPublisher::Incentive`: SearchIncentives, GetIncentive
+* `ZanoxPublisher::ExclusiveIncentive`: SearchExclusiveIncentives, GetExclusiveIncentive
+* `ZanoxPublisher::Product`: SearchProducts, GetProduct
+* `ZanoxPublisher::Profile`: getProfiles
+* `ZanoxPublisher::Program`: SearchPrograms, GetProgram
+* `ZanoxPublisher::ProgramApplication`: GetProgramApplications
+
+## Documentation
+
+[http://www.rubydoc.info/github/oliverprater/zanox_publisher/master][documentation]
+
+[documentation]: http://www.rubydoc.info/github/oliverprater/zanox_publisher/master
+
+## Versioning
+
+This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
+of this scheme should be reported as bugs. Specifically, if a minor or patch
+version is released that breaks backward compatibility, that version should be
+immediately yanked and/or a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will only be
+introduced with new major versions. As a result of this policy, you can (and
+should) specify a dependency on this gem using the [Pessimistic Version
+Constraint][pvc] with two digits of precision. For example:
+
+    'zanox_publisher', '~> 0.1'
+
+[semver]: http://semver.org/
+[pvc]: http://docs.rubygems.org/read/chapter/16#page74
+
+## Contributing
+
+1. Fork it ( https://github.com/oliverprater/zanox_publisher/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
+
+## Copyright
+
+Copyright (c) 2015 Oliver Prater.
+See [LICENSE][license] for details.
+
+[license]: LICENSE.md

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+# Console for active development
+# http://stackoverflow.com/questions/4493114/developing-gems-and-testing
+#
+# => rake console
+#
+task :console do
+  exec "irb -r zanox_publisher -I ./lib"
+end

data/lib/zanox_publisher/ad_medium.rb

@@ -0,0 +1,232 @@
+module ZanoxPublisher
+  # AdMedium
+  #
+  # Get banners and links, including tracking links
+  #
+  # @attr [Integer]               id              The admediumItem's identifer from Zanox
+  # @attr [String]                name            The name for the ad medium
+  # @attr [Fixnum]                adrank          The adrank of the ad medium
+  # @attr [String]                admedium_type   The type of ad medium
+  # @attr [Program]               program         The program to which the ad medium belongs
+  # @attr [String]                title           The title of the ad medium
+  # @attr [Integer]               height          The height in pixel of the image
+  # @attr [Integer]               width           The width in pixel of the image
+  # @attr [Format]                format          The formats' Zanox identifer and name
+  # @attr [String]                code            The code of the ad medium
+  # @attr [String]                description     The description from the advertiser
+  # @attr [String]                instruction     The instructions from the advertiser
+  # @attr [String]                purpose         The purpose assigned to the ad medium
+  # @attr [Array<Category>]       category        The merchants' given category to the ad medium
+  # @attr [Hash]                  group           The group given to the ad medium
+  # @attr [Array]                 tags            A list of tags for the ad medium
+  # @attr [Array<TrackingLink>]   tracking_links  The tracking links of the ad medium for each ad space
+  class AdMedium < Base
+    RESOURCE_PATH = '/admedia'
+
+    # ENUM types
+    @@admedia_types    = %w(html script lookatMedia image imageText text)
+    @@admedia_purposes = %w(startPage productDeeplink categoryDeeplink searchDeeplink)
+
+    class << self
+      # Returns the Zanox API admediaTypeEnum datatype
+      #
+      # @return [Array<String>]
+      def admedia_types
+        @@admedia_types
+      end
+
+      # Returns the Zanox API admediaPurposeEnum datatype
+      #
+      # @return [Array<String>]
+      def admedia_purposes
+        @@admedia_purposes
+      end
+
+      # Retrieves all affiliate link's dependent on search parameters.
+      #
+      # This is equivalent to the Zanox API method GetAdmedia.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-admedia}.
+      #
+      # Authentication: Requires connect ID.
+      #
+      # 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 [Integer] Limits results to a particular program ID.
+      # @param region [String] Limits results to programs from a particular region.
+      # @param format [String] Limits results to an ad media format.
+      # @param admedium_type [String] Limits results to an ad media type (API equivalent is admediumtype).
+      # @param admediumtype [String] Limits results to an ad media type (API name).
+      # @param purpose [String] Limits results to a type of link to the advertiser shop.
+      # @param partnership [String] Limits results to either programs to whom the publisher has successfully applied ("direct"), or to those who belong to zanox's publicly available ad pool ("indirect").
+      # @param category [String] Limits results to one of the program's ad media categories. Ad media categories are defined by each advertiser for their program, and can be retrieved using GetAdmediumCategories.
+      # @param adspace [AdSpace, Integer] Limits results to tracking links associated with this ad space.
+      #
+      # @return [Array<AdMedium>]
+      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 AdMedium.total > retval.size
+
+        retval
+      end
+
+      # Retrieves the requested page of admedium items dependent on search parameters.
+      #
+      # This is equivalent to the Zanox API method GetAdmedia.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-admedia}.
+      #
+      # Authentication: Requires connect ID.
+      #
+      # @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 region [String] Limits results to programs from a particular region.
+      # @param format [String] Limits results to an ad media format.
+      # @param admedium_type [String] Limits results to an ad media type (API equivalent is admediumtype).
+      # @param admediumtype [String] Limits results to an ad media type (API name).
+      # @param purpose [String] Limits results to a type of link to the advertiser shop.
+      # @param partnership [String] Limits results to either programs to whom the publisher has successfully applied ("direct"), or to those who belong to zanox's publicly available ad pool ("indirect").
+      # @param category [Category, String] Limits results to one of the program's ad media categories. Ad media categories are defined by each advertiser for their program, and can be retrieved using GetAdmediumCategories.
+      # @param adspace [AdSpace, Integer] Limits results to tracking links associated with this ad space.
+      #
+      # @return [Array<AdSpace>]
+      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?
+
+        region = options[:region]
+
+        format = options[:format]
+
+        admedium_type = options[:admedium_type]
+        admedium_type = options[:admediumtype]  if admedium_type.nil?
+        admedium_type = nil unless @@admedia_types.include? admedium_type
+
+        purpose = options[:purpose]
+        purpose = nil unless @@admedia_purposes.include? purpose
+
+        partnership = options[:partnership]
+
+        # Limits results to one of the program's ad media categories. Ad media categories are defined by each advertiser for their program, and can be retrieved using GetAdmediumCategories.
+        category = options[:category]
+        category = category.to_i unless category.nil?
+
+        adspace = options[:adspace]
+        adspace = adspace.to_i unless adspace.nil?
+
+        # Build the query on hand of the options received
+        params[:query].merge!({ program: program })             unless program.nil?
+        params[:query].merge!({ region: region })               unless region.nil?
+        params[:query].merge!({ format: format })               unless format.nil?
+        params[:query].merge!({ admediumtype: admedium_type })  unless admedium_type.nil?
+        params[:query].merge!({ purpose: purpose })             unless purpose.nil?
+        params[:query].merge!({ partnership: partnership })     unless partnership.nil?
+        params[:query].merge!({ category: category })           unless category.nil?
+        params[:query].merge!({ adspace: adspace })             unless adspace.nil?
+
+        retval = []
+
+        response = self.connection.get(RESOURCE_PATH, params)
+
+        AdMedium.total = response.fetch('total')
+
+        admedia = []
+        admedia = response.fetch('admediumItems', {}).fetch('admediumItem', []) if AdMedium.total > 0
+
+        admedia.each do |admedium|
+          retval << AdMedium.new(admedium)
+        end
+
+        retval
+      end
+
+      # Returns a single admediumItem, as queried by its ID.
+      #
+      # The use of the trackingLink of the ID is not supported at the moment.
+      #
+      # This is equivalent to the Zanox API method GetAdmedium.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-admedia-admedium}.
+      #
+      # Authentication: Requires connect ID.
+      #
+      # @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 [<AdMedium>]
+      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.get(RESOURCE_PATH + "/admedium/#{id}", params)
+        admedium = response.fetch('admediumItem', [])
+
+        AdMedium.new(admedium)
+      end
+
+      # A connection instance with AdMediums' relative_path
+      #
+      # @return [Connection]
+      def connection
+        @connection ||= Connection.new(RESOURCE_PATH)
+      end
+    end
+
+    def initialize(data = {})
+      @id             = data.fetch('@id').to_i
+      @name           = data.fetch('name')
+      @adrank         = data.fetch('adrank')
+      @admedium_type  = data.fetch('admediumType')
+      @program        = Program.new(data.fetch('program'))
+      # Optionally returned data
+      @title          = data.fetch('title', nil)
+      @height         = data.fetch('height', nil)
+      @width          = data.fetch('width', nil)
+      @format         = data.fetch('format', nil)
+      @format         = Format.new(@format) unless @format.nil?
+      @code           = data.fetch('code', nil)
+      @description    = data.fetch('description', nil)
+      @instruction    = data.fetch('instruction', nil)
+      @purpose        = data.fetch('purpose', nil)
+      @category       = data.fetch('category', nil)
+      @category       = Category.new(@category) unless @category.nil?
+      @group          = data.fetch('group', nil)
+      @tags           = data.fetch('tags', nil)
+      @tracking_links = TrackingLink.fetch(data.fetch('trackingLinks', {})['trackingLink'])
+    end
+
+    # Returns the admediumItems' ID as integer representation
+    #
+    # @return [Integer]
+    def to_i
+      @id
+    end
+
+    attr_accessor :id, :name, :adrank, :admedium_type, :program,
+      :title, :height, :width, :format, :code,
+      :description, :instruction, :purpose, :category,
+      :group, :tags, :tracking_links
+
+    # make API names available
+    alias admediumType admedium_type
+    alias trackingLinks tracking_links
+  end
+end

data/lib/zanox_publisher/ad_space.rb

@@ -0,0 +1,159 @@
+module ZanoxPublisher
+  # AdSpaces
+  #
+  # Access and modify your AdSpace information
+  #
+  # @attr [Integer]         id              The profileItem's identifer from Zanox
+  # @attr [String]          name            The name of your ad space
+  # @attr [String]          url             The url of your ad space
+  # @attr [String]          description     The description for your ad space
+  # @attr [String]          adspace_type    The type of ad space
+  # @attr [Integer]         visitors        The number of visitors to your ad space
+  # @attr [Integer]         impressions     The number of impressions of your ad space
+  # @attr [String]          scope           The scope of your ad space
+  # @attr [Array<String>]   regions         The regions for the ad space
+  # @attr [Array<Category>] categories      The categories of your ad space
+  # @attr [String]          language        The language of your ad space
+  # @attr [Integer]         check_number    The check number for this ad space
+  class AdSpace < Base
+    RESOURCE_PATH = '/adspaces'
+
+    ADSPACE_TYPE_ENUM = %w(website email searchengine)
+    ADSPACE_SCOPE_ENUM = %w(private business)
+
+    class << self
+      # Retrieves all adspace items related to the publisher account.
+      #
+      # This is equivalent to the Zanox API method GetAdspaces.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-adspaces}.
+      #
+      # Authentication: Requires signature.
+      #
+      # This can require multiple requests, as internally every page is pulled.
+      # The ZanoxPublisher::AdSpace.page function can be used to better control the requests made.
+      #
+      # @return [Array<AdSpace>]
+      def all
+        retval = []
+        current_page = 0
+
+        begin
+          retval       += self.page(current_page, { per_page: maximum_per_page })
+          current_page += 1
+        end while AdSpace.total > retval.size
+
+        retval
+      end
+
+      # Retrieves the requested page of adspace items related to the publisher account.
+      #
+      # This is equivalent to the Zanox API method GetAdspaces.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-adspaces}.
+      #
+      # 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 option name)
+      #
+      # @example
+      #         ZanoxPublisher::AdSpace.page(1, per_page: 50) #=> [<AdSpace...>]
+      #
+      # @example
+      #         ZanoxPublisher::AdSpace.page(2) #=> [<AdSpace...>]
+      #
+      # @example
+      #         ZanoxPublisher::AdSpace.page #=> [<AdSpace...>]
+      #
+      # @return [Array<AdSpace>]
+      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 = AdSpace.per_page   if per_page.nil?
+        params[:query].merge!({ items: per_page })
+
+        retval = []
+
+        response = self.connection.signature_get(RESOURCE_PATH, params)
+
+        AdSpace.total = response.fetch('total')
+        adspaces = response.fetch('adspaceItems', []).fetch('adspaceItem', [])
+
+        adspaces.each do |adspace|
+          retval << AdSpace.new(adspace)
+        end
+
+        retval
+      end
+
+      # Returns a single adspaceItem, as queried by its ID.
+      #
+      # This is equivalent to the Zanox API method GetAdspace.
+      # The method documentation can be found under {https://developer.zanox.com/web/guest/publisher-api-2011/get-adspaces-adspace}.
+      #
+      # Authentication: Requires signature.
+      #
+      # @param id [Integer] the ID of the adspace you want to get
+      #
+      # @return [<AdSpace>]
+      def find(id)
+        response = self.connection.signature_get(RESOURCE_PATH + "/adspace/#{id}")
+        adspace = response.fetch('adspaceItem', []).first
+
+        AdSpace.new(adspace)
+      end
+
+      # A connection instance with AdSpaces' relative_path
+      #
+      # @return [Connection]
+      def connection
+        @connection ||= Connection.new(RESOURCE_PATH)
+      end
+    end
+
+    # TODO: POST   {https://developer.zanox.com/web/guest/publisher-api-2011/post-adspaces-adspace}
+    # TODO: PUT    {https://developer.zanox.com/web/guest/publisher-api-2011/put-adspaces-adspace}
+    # TODO: DELETE {https://developer.zanox.com/web/guest/publisher-api-2011/delete-adspaces-adspace}
+    #
+    def initialize(data = {})
+      @id             = data.fetch('@id').to_i
+
+      # Depending on short or long representation of object
+      if data.fetch('$', nil).nil?
+        @name           = data.fetch('name')
+        @url            = data.fetch('url')
+        @description    = data.fetch('description')
+        @adspace_type   = data.fetch('adspaceType')
+        @visitors       = data.fetch('visitors')
+        @impressions    = data.fetch('impressions')
+        @scope          = data.fetch('scope', nil)
+        @regions        = data.fetch('regions', []).first
+        @regions        = @regions.fetch('region') unless @regions.nil?
+        @regions        = [@regions] if @regions.is_a? String
+        @categories     = Category.fetch(data['categories'])
+        @language       = data.fetch('language')
+        @check_number   = data.fetch('checkNumber')
+      else
+        @name                 = data.fetch('$')
+      end
+    end
+
+    # Returns the adspaceItems' ID as integer representation
+    #
+    # @return [Integer]
+    def to_i
+      @id
+    end
+
+    attr_accessor :id, :name, :url, :description, :adspace_type,
+      :visitors, :impressions, :scope, :regions,
+      :categories, :language, :check_number
+
+    # make API names available
+    alias adspaceType adspace_type
+    alias checkNumber check_number
+  end
+end