kontagent 0.0.1

data/Manifest

@@ -0,0 +1,5 @@
+Manifest
+Rakefile
+kontagent.gemspec
+lib/kontagent.rb
+spec/kontagent_spec.rb

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('kontagent', '0.0.1') do |p|
+  p.description    = "A gem that provides basic integration with Kontagent's REST API"
+  p.url            = "http://github.com/gamesthatgive/kontagent"
+  p.author         = "Kristofer Goss"
+  p.email          = "goss@gamesthatgive.net"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.runtime_dependencies = [["uuidtools", ">= 1.0.7"], ["rest-client", ">=1.1.0"]]
+  # p.development_dependencies = []
+end

data/kontagent.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{kontagent}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kristofer Goss"]
+  s.date = %q{2010-07-30}
+  s.description = %q{A gem that provides basic integration with Kontagent's REST API}
+  s.email = %q{goss@gamesthatgive.net}
+  s.extra_rdoc_files = ["lib/kontagent.rb"]
+  s.files = ["Manifest", "Rakefile", "kontagent.gemspec", "lib/kontagent.rb", "spec/kontagent_spec.rb"]
+  s.homepage = %q{http://github.com/gamesthatgive/kontagent}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Kontagent"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{kontagent}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A gem that provides basic integration with Kontagent's REST API}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<uuidtools>, [">= 1.0.7"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 1.1.0"])
+    else
+      s.add_dependency(%q<uuidtools>, [">= 1.0.7"])
+      s.add_dependency(%q<rest-client>, [">= 1.1.0"])
+    end
+  else
+    s.add_dependency(%q<uuidtools>, [">= 1.0.7"])
+    s.add_dependency(%q<rest-client>, [">= 1.1.0"])
+  end
+end

data/lib/kontagent.rb

@@ -0,0 +1,143 @@
+require 'rubygems'
+require 'rest_client'
+require 'uuidtools'
+require 'ostruct'
+
+module Kontagent
+  def self.config
+    @@config
+  end
+
+  def self.base_url
+    @@base_url
+  end
+
+  PARAMS_MAP = {
+    :uid                => :s,
+    :birth_year         => :b,
+    :sex                => [:g, :escape],
+    :city               => [:ly, :escape],
+    :country            => [:lc, :escape],
+    :zip                => [:lp, :escape],
+    :state              => [:ls, :escape],
+    :friend_count       => :f,
+    :short_tag          => :su,
+    :tag                => :u,
+    :channel            => :tu,
+    :link_type          => :tu,
+    :st1                => [:st1, :escape],
+    :st2                => [:st2, :escape],
+    :st3                => [:st3, :escape],
+    :responder_uid      => :r,
+    :recipient_uids     => [:r, :escape],
+    :existing_install?  => :i,
+    :timestamp          => :ts,
+  }
+
+  def self.create_tracking_tag
+    tag = UUID.random_create.to_s.gsub("-", "")
+    yield tag if block_given?
+    tag
+  end
+
+  def self.create_short_tag
+    create_tracking_tag
+  end
+
+  def self.initialize!(options = {})
+    raise "Missing required api_url setting" unless options["api_url"]
+    raise "Missing required ab_url setting" unless options["ab_url"]
+    @@config = OpenStruct.new(options)
+    @@base_url = File.join(self.config.api_url, self.config.api_key)
+  end
+
+  def self.application_added(options = {})
+    assert_options(options, :uid)
+    call_method("apa", options)
+  end
+
+  def self.application_removed(options = {})
+    assert_options(options, :uid)
+    call_method("apr", options)
+  end
+
+  def self.get_page_request_url(options = {})
+    assert_options(options, :uid)
+    options[:timestamp] ||= Time.now.strftime("%Y-%m-%dT%H:%M:%S")
+    build_url("pgr", options)
+  end
+
+  def self.track_user(options = {})
+    assert_options(options, :uid)
+    options[:sex] = options[:sex].to_s[0,1]
+    call_method("cpu", options)
+  end
+
+  def self.track_post(options = {})
+    assert_options(options, :uid, :tag, :channel)
+    assert_channel(options[:channel])
+    call_method("pst", options)
+  end
+
+  def self.track_post_response(options = {})
+    assert_options(options, :responder_uid, :tag, :channel, :existing_install?)
+    assert_channel(options[:channel])
+    options[:existing_install?] = options[:existing_install?] && 1 || 0  
+    call_method("psr", options)
+  end
+
+  def self.track_invite(options = {})
+    assert_options(options, :uid, :tag, :recipient_uids)
+    options[:recipient_uids] = options[:recipient_uids].join(",")
+    call_method("ins", options)
+  end
+
+  def self.track_invite_response(options = {})
+    assert_options(options, :responder_uid, :tag, :existing_install?)
+    options[:existing_install?] = options[:existing_install?] && 1 || 0  
+    call_method("inr", options)
+  end
+
+  def self.build_url(method, options = {})
+    File.join(self.base_url, method, "?#{kontagent_params(options)}")
+  end
+
+  def self.track_link(options)
+    assert_options(options, :link_type, :existing_install?, :short_tag)
+    options[:existing_install?] = options[:existing_install?] ? 1 : 0
+    call_method("ucc", options)
+  end
+
+  private
+
+    def self.assert_options(options, *required_keys)
+      required_keys.each { |k| assert(options.key?(k), "#{k} is required") }
+    end
+
+    def self.assert_channel(value)
+      assert([:stream, :feedpub, :feedstory, :multifeedstory].member?(value.to_sym), "channel type #{value} not supported")
+    end
+
+    def self.assert(value, message = "Assertion failed")
+      raise Exception, message, caller unless value
+    end
+
+    def self.call_method(method, options = {})
+      url = build_url(method, options)
+      RestClient.get(url)
+    end
+
+    def self.kontagent_params(options)
+      opts = options.inject({}) do |rewritten_hash, (original_key, value)|
+        unless value.nil? || value.to_s.strip.empty?
+          if PARAMS_MAP[original_key].is_a? Array
+            rewritten_hash[PARAMS_MAP[original_key].first] = CGI.escape(value)
+          elsif PARAMS_MAP[original_key]
+            rewritten_hash[PARAMS_MAP[original_key]] = value
+          end
+        end
+        rewritten_hash
+      end
+      opts.map { |k,v| "#{k}=#{v}" }.sort.join("&")
+    end
+end

data/spec/kontagent_spec.rb

@@ -0,0 +1,323 @@
+require "kontagent"
+
+describe Kontagent do
+  before(:each) do
+    Kontagent.initialize!("api_url" => "http://kontagent.com/api/v1", "api_key" => "12345", "ab_url" => "http://kontagent.com")
+  end
+
+  it "should initialize" do
+    Kontagent.config.should_not be_nil
+    Kontagent.base_url.should == "http://kontagent.com/api/v1/12345"
+  end
+
+  it "should not initialize without an API key" do
+    lambda { Kontagent.initialize!("api_url" => "http://kontagent.com/api/v1", "ab_url" => "http://kontagent.com") }.should raise_error
+  end
+
+  it "should not initialize without an A/B url" do
+    lambda { Kontagent.initialize!("api_url" => "http://kontagent.com/api/v1", "api_key" => "12345") }.should raise_error
+  end
+
+  context "when adding an application" do
+    before(:each) do
+      @tracking_tag = UUID.random_create.to_s.gsub("-", "")
+    end
+
+    it "should record the user id" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/apa/?s=1")
+      Kontagent.application_added :uid => 1
+    end
+
+    it "should raise without user id" do
+      lambda { Kontagent.application_added }.should raise_error
+    end
+
+    it "should record the tracking tag" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/apa/?s=1&u=#{@tracking_tag}")
+      Kontagent.application_added :uid => 1, :tag => @tracking_tag
+    end
+
+    it "should record the short tracking tag" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/apa/?s=1&su=#{@tracking_tag}")
+      Kontagent.application_added :uid => 1, :short_tag => @tracking_tag
+    end
+  end
+
+  context "when removing an application" do
+    it "should record the user id" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/apr/?s=1")
+      Kontagent.application_removed :uid => 1
+    end
+
+    it "should raise without user id" do
+      lambda { Kontagent.application_removed }.should raise_error
+    end
+  end
+
+  context "when tracking a page request" do
+    before(:each) do
+      @now = Time.now
+      Time.stub!(:now).and_return(@now)
+    end
+
+    it "should build the proper tracking url" do
+      expected_timestamp = @now.strftime("%Y-%m-%dT%H:%M:%S")
+      Kontagent.get_page_request_url(:uid => 1).should == "#{Kontagent.base_url}/pgr/?s=1&ts=#{expected_timestamp}"
+    end
+
+    it "should raise without user id" do
+      lambda { Kontagent.get_page_request_url }.should raise_error
+    end
+  end
+
+  context "when tracking user demograpics" do
+    it "should record" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/cpu/?b=1955&f=3&g=f&lc=USA&lp=04103&ls=ME&ly=San+Francisco&s=1")
+      Kontagent.track_user(:uid => 1,
+                           :birth_year => 1955,
+                           :sex => "female",
+                           :city => "San Francisco",
+                           :country => "USA",
+                           :state => "ME",
+                           :zip => "04103",
+                           :friend_count => 3)
+    end
+
+    it "should handle empty values" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/cpu/?b=1955&f=3&lc=USA&lp=04103&s=1")
+      Kontagent.track_user(:uid => 1,
+                           :birth_year => 1955,
+                           :sex => "",
+                           :city => "  ",
+                           :country => "USA",
+                           :state => "",
+                           :zip => "04103",
+                           :friend_count => 3)
+    end
+
+    it "should handle nil values" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/cpu/?b=1955&f=3&g=f&lc=USA&lp=04103&s=1")
+      Kontagent.track_user(:uid => 1,
+                           :birth_year => 1955,
+                           :sex => "female",
+                           :city => nil,
+                           :country => "USA",
+                           :state => nil,
+                           :zip => "04103",
+                           :friend_count => 3)
+    end
+  end
+
+  context "when tracking a post" do
+    it "should record a stream post" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/pst/?s=1&tu=stream&u=12345")
+      Kontagent.track_post(:channel => :stream, :uid => 1, :tag => "12345")
+    end
+
+    it "should record a feed publication" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/pst/?s=1&tu=feedpub&u=12345")
+      Kontagent.track_post(:channel => :feedpub, :uid => 1, :tag => "12345")
+    end
+
+    it "should record a feed story" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/pst/?s=1&tu=feedstory&u=12345")
+      Kontagent.track_post(:channel => :feedstory, :uid => 1, :tag => "12345")
+    end
+
+    it "should record a multifeed story" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/pst/?s=1&tu=multifeedstory&u=12345")
+      Kontagent.track_post(:channel => :multifeedstory, :uid => 1, :tag => "12345")
+    end
+
+    it "should record with subtypes" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/pst/?s=1&st1=subtype1&st2=subtype2&st3=subtype3&tu=multifeedstory&u=12345")
+      Kontagent.track_post(:channel => :multifeedstory,
+                           :uid => 1,
+                           :st1 => "subtype1",
+                           :st2 => "subtype2",
+                           :st3 => "subtype3",
+                           :tag => "12345")
+    end
+
+    it "should raise given unknown channel type" do
+      lambda { Kontagent.track_post(:channel => :bogus, :uid => 1, :tag => "12345") }.should raise_error
+    end
+
+    it "should raise given missing uid" do
+      lambda { Kontagent.track_post(:channel => :stream, :tag => "12345") }.should raise_error
+    end
+
+    it "should raise given missing tag" do
+      lambda { Kontagent.track_post(:channel => :stream, :uid => 1) }.should raise_error
+    end
+  end
+
+  context "when tracking a post response" do
+    it "should record a stream response" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/psr/?i=0&r=2&tu=stream&u=12345")
+      Kontagent.track_post_response(:channel => :stream,
+                                    :responder_uid => 2,
+                                    :tag => 12345,
+                                    :existing_install? => false)
+    end
+
+    it "should record with subtypes" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/psr/?i=0&r=2&st1=subtype1&st2=subtype2&st3=subtype3&tu=stream&u=12345")
+      Kontagent.track_post_response(:channel => :stream,
+                                    :responder_uid => 2,
+                                    :st1 => "subtype1",
+                                    :st2 => "subtype2",
+                                    :st3 => "subtype3",
+                                    :tag => 12345,
+                                    :existing_install? => false)
+    end
+
+    it "should record a feedpub post response" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/psr/?i=0&r=2&tu=feedpub&u=12345")
+      Kontagent.track_post_response(:channel => :feedpub,
+                                    :responder_uid => 2,
+                                    :tag => 12345,
+                                    :existing_install? => false)
+    end
+
+    it "should record a feedstory post response" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/psr/?i=1&r=2&tu=feedstory&u=12345")
+      Kontagent.track_post_response(:channel => :feedstory,
+                                    :responder_uid => 2,
+                                    :tag => 12345,
+                                    :existing_install? => true)
+    end
+
+    it "should record a multifeedstory post response" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/psr/?i=1&r=2&tu=multifeedstory&u=12345")
+      Kontagent.track_post_response(:channel => :multifeedstory,
+                                    :responder_uid => 2,
+                                    :tag => 12345,
+                                    :existing_install? => true)
+    end
+
+    it "should raise given missing recipient" do
+      lambda { Kontagent.track_post_response(:channel => :multifeedstory,
+                                             :tag => 12345,
+                                             :existing_install? => true) }.should raise_error
+    end
+
+    it "should raise given missing channel" do
+      lambda { Kontagent.track_post_response(:responder_uid => 2,
+                                             :tag => 12345,
+                                             :existing_install? => true) }.should raise_error
+    end
+
+    it "should raise given missing tag" do
+      lambda { Kontagent.track_post_response(:channel => :stream,
+                                             :responder_uid => 2,
+                                             :existing_install? => true) }.should raise_error
+    end
+
+    it "should raise given missing install status" do
+      lambda { Kontagent.track_post_response(:channel => :stream,
+                                             :responder_uid => 2,
+                                             :tag => 12345) }.should raise_error
+    end
+
+    it "should raise given invalid channel" do
+      lambda { Kontagent.track_post_response(:channel => :bogus,
+                                             :responder_uid => 2,
+                                             :tag => 12345,
+                                             :existing_install? => true) }.should raise_error
+    end
+  end
+
+  context "creating tags" do
+    it "should be able to create a tracking tag" do
+      Kontagent.create_tracking_tag.should_not be_empty
+    end
+
+    it "should be able to create a short tag" do
+      Kontagent.create_short_tag.should_not be_empty
+    end
+
+    it "should yield when creating a tracking tag" do 
+      yielded = false
+
+      Kontagent.create_tracking_tag do |tag|
+        tag.should_not be_nil
+        tag.should_not be_empty
+        yielded = true
+      end
+
+      yielded.should be_true
+    end
+  end
+
+  context "when tracking link traffic" do
+    it "should record an undirected communication click" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/ucc/?i=0&st1=Facebook&st2=GamePhun&st3=2&su=short_tag&tu=ad")
+      Kontagent.track_link(:link_type => 'ad', :st1 => 'Facebook', :st2 => 'GamePhun',
+                           :st3 => '2', :existing_install? => false, :short_tag => 'short_tag')
+    end
+
+    it "should encode its parameters" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/ucc/?i=0&st1=%2F&st2=%24&st3=%26&su=short_tag&tu=ad")
+      Kontagent.track_link(:link_type => 'ad', :st1 => '/', :st2 => '$', :st3 => '&',
+                           :existing_install? => false, :short_tag => 'short_tag')
+    end
+  end
+
+  context "when tracking an invitation" do
+    before(:each) do
+      @tag = Kontagent.create_tracking_tag
+    end
+
+    it "should record the invite" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/ins/?r=1%2C2%2C3%2C4%2C5&s=12345&u=#{@tag}")
+      Kontagent.track_invite :uid => 12345, :tag => @tag, :recipient_uids => [1,2,3,4,5]
+    end
+
+    it "should require a uid" do
+      RestClient.should_not_receive(:get)
+      lambda { Kontagent.track_invite :tag => @tag, :recipient_uids => [1,2,3,4,5] }.should raise_error("uid is required")
+    end
+
+    it "should require recipient identifiers" do
+      RestClient.should_not_receive(:get)
+      lambda { Kontagent.track_invite :uid => 12345, :tag => @tag }.should raise_error("recipient_uids is required")
+    end
+
+    it "should require a tracking tag" do
+      RestClient.should_not_receive(:get)
+      lambda { Kontagent.track_invite :uid => 12345, :recipient_uids => [1,2,3,4,5] }.should raise_error("tag is required")
+    end
+
+    it "should record with st1 param" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/ins/?r=1%2C2%2C3%2C4%2C5&s=12345&st1=st1&u=#{@tag}")
+      Kontagent.track_invite :uid => 12345, :tag => @tag, :recipient_uids => [1,2,3,4,5], :st1 => "st1"
+    end
+
+    it "should record with st2 param" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/ins/?r=1%2C2%2C3%2C4%2C5&s=12345&st2=st2&u=#{@tag}")
+      Kontagent.track_invite :uid => 12345, :tag => @tag, :recipient_uids => [1,2,3,4,5], :st2 => "st2"
+    end
+  end
+
+  context "when tracking an invitation response" do
+    before(:each) do
+      @tag = Kontagent.create_tracking_tag
+    end
+
+    it "should record the response" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/inr/?i=1&r=12345&u=#{@tag}")
+      Kontagent.track_invite_response(:responder_uid => 12345, :existing_install? => true, :tag => @tag)
+    end
+
+    it "should record with st1 param" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/inr/?i=1&r=12345&st1=st1&u=#{@tag}")
+      Kontagent.track_invite_response(:responder_uid => 12345, :existing_install? => true, :tag => @tag, :st1 => "st1")
+    end
+
+    it "should record with st2 param" do
+      RestClient.should_receive(:get).with("#{Kontagent.base_url}/inr/?i=1&r=12345&st2=st2&u=#{@tag}")
+      Kontagent.track_invite_response(:responder_uid => 12345, :existing_install? => true, :tag => @tag, :st2 => "st2")
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification 
+name: kontagent
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Kristofer Goss
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-30 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: uuidtools
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 1
+        - 0
+        - 7
+        version: 1.0.7
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id002
+description: A gem that provides basic integration with Kontagent's REST API
+email: goss@gamesthatgive.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/kontagent.rb
+files: 
+- Manifest
+- Rakefile
+- kontagent.gemspec
+- lib/kontagent.rb
+- spec/kontagent_spec.rb
+has_rdoc: true
+homepage: http://github.com/gamesthatgive/kontagent
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Kontagent
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: kontagent
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A gem that provides basic integration with Kontagent's REST API
+test_files: []
+