ruby-iactionable 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+.bundle
+.DS_Store
+.rvmrc

data/.rvmrc

@@ -0,0 +1,3 @@
+rvm_gemset_create_on_use_flag=1
+rvm use ruby-1.9.2-p136@ruby_iactionable
+rvm wrapper ruby-1.9.2-p136@ruby_iactionable textmate

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG #
+
+## 0.0.1 ##
+
+* Pulling API wrapper out as separate gem (this).

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    Ruby IActionable (0.0.1)
+      activesupport (>= 3.0.0)
+      faraday
+      faraday-stack
+      rake
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.2.1)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    addressable (2.2.6)
+    diff-lcs (1.1.3)
+    faraday (0.7.6)
+      addressable (~> 2.2)
+      multipart-post (~> 1.1)
+      rack (~> 1.1)
+    faraday-stack (0.1.5)
+      faraday (>= 0.6, < 0.8)
+    i18n (0.6.0)
+    multi_json (1.0.4)
+    multipart-post (1.1.4)
+    rack (1.4.1)
+    rake (0.9.2.2)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  Ruby IActionable!
+  rspec (>= 2.6)

data/README.md

@@ -0,0 +1,49 @@
+# Overview #
+
+Ruby IActionable is a straightforward wrapper for IActionable's restful API.  The JSON-encoded responses from IActionable are wrapped in objects that provide a few extra functions here and there, but are mostly just a representation of the API response.
+
+# How To Use #
+
+## Installation ##
+
+    gem install ruby-iactionable
+
+## IRB ##
+
+    require 'iactionable'
+
+## Bundler ##
+
+    gem 'ruby-iactionable', :require => 'iactionable'
+
+## API Credentials And Initialization ##
+
+Before the API wrapper can be instantiated or used it must be pre-initialized with your IActionable credentials and version number (IActionable supports older versions but recommends staying up to date):
+
+    IActionable::Api.init_settings( :app_key => "12345",
+                                    :api_key => "abcde",
+                                    :version => 3 )
+    @api = IActionable::Api.new
+
+The responses for each of the endpoints of IActionable's API are described through example by [their documentation](http://www.iactionable.com/api/).  Here is an example of the response from a [profile summary](http://iactionable.com/api/profiles/#getprofilesummary) returned as an object by the wrapper.
+
+    profile_summary = @api.get_profile_summary("user", "username", "zortnac", 10)
+    profile_summary.display_name # => "Chris Eberz"
+    profile_summary.identifiers.first # => instance of IActionable::Objects::Identifier
+    profile_summary.identifiers.first.id_type # => "username"
+    profile_summary.identifiers.first.id # => "zortnac"
+
+Each object can be dumped back in to its original form of arrays and key/value pairs:
+
+    profile_summary.to_hash # => { "DisplayName" => "Chris Eberz", "Identifiers" => [ {"ID" => "zortnac", "IDType" => "username", ...} ] ... }
+                            # (not shown in entirety)
+
+----------------
+
+## IActionable ##
+
+[Visit their website!](http://www.iactionable.com)
+
+## Author ##
+
+Christopher Eberz; chris@chriseberz.com; @zortnac

data/Rakefile

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

data/lib/iactionable/api.rb

@@ -0,0 +1,170 @@
+require 'iactionable/connection.rb'
+require 'iactionable/settings.rb'
+require 'iactionable/objects.rb'
+
+module IActionable
+  
+  class Api
+    attr :connection
+    @@settings = nil
+  
+    def initialize
+      if @@settings
+        @connection = IActionable::Connection.new(@@settings)
+      else
+        raise IActionable::ConfigError.new("IActionable::Api cannot be initialized without credentials being set in IActionable::Api.init_settings()")
+      end
+    end
+  
+    def self.init_settings(values)
+      @@settings = IActionable::Settings.new(values)
+    rescue IActionable::ConfigError => e
+      raise e
+    end
+  
+    def self.settings
+      @@settings
+    end
+  
+    # =================
+    # = Event Logging =
+    # =================
+  
+    def log_event(profile_type, id_type, id, event_key, event_attrs = {})
+      response = @connection.request.with_app_key.with_api_key.to("/#{profile_type}/#{id_type}/#{id}/events/#{event_key}").with_params(event_attrs).post
+    end
+  
+    # =====================
+    # = Profile API calls =
+    # =====================
+  
+    def get_profile_summary(profile_type, id_type, id, achievement_count = nil)
+      request = @connection.request.with_app_key.to("/#{profile_type}/#{id_type}/#{id}")
+      request.with_params(:achievementCount => achievement_count) unless achievement_count.blank?
+      response = request.get
+      IActionable::Objects::ProfileSummary.new(response)
+    end
+  
+    def create_profile(profile_type, id_type, id, display_name = nil)
+      request = @connection.request.with_app_key.with_api_key.to("/#{profile_type}/#{id_type}/#{id}")
+      request.with_params(:displayName => display_name) unless display_name.blank?
+      request.post
+    end
+    alias_method :update_profile, :create_profile
+  
+    def add_profile_identifier(profile_type, id_type, id, alt_id_type, alt_id)
+      @connection.request.with_app_key.with_api_key.to("/#{profile_type}/#{id_type}/#{id}/identifiers/#{alt_id_type}/#{alt_id}").post
+    end
+  
+    # ====================
+    # = Points API calls =
+    # ====================
+  
+    def get_profile_points(profile_type, id_type, id, point_type)
+      response = @connection.request.with_app_key.to("/#{profile_type}/#{id_type}/#{id}/points/#{point_type}").get
+      IActionable::Objects::ProfilePoints.new(response)
+    end
+  
+    def update_profile_points(profile_type, id_type, id, point_type, amount, reason = nil)
+      request = @connection.request.with_app_key.with_api_key.to("/#{profile_type}/#{id_type}/#{id}/points/#{point_type}").with_params(:value => amount)
+      request.with_params(:description => reason) unless reason.blank?
+      response = request.post
+      IActionable::Objects::ProfilePoints.new(response)
+    end
+  
+    # =========================
+    # = Achievement API calls =
+    # =========================
+  
+    def get_profile_achievements(profile_type, id_type, id, filter_type = nil)
+      request = @connection.request.with_app_key
+      case filter_type
+      when :completed
+        request.to("/#{profile_type}/#{id_type}/#{id}/achievements/Completed")
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/achievements/Available")
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/achievements")
+      end
+      IActionable::Objects::ProfileAchievements.new(request.get)
+    end
+  
+    def get_achievements()
+      response = @connection.request.with_app_key.to("/achievements").get
+      response.map{|achievement_json| IActionable::Objects::Achievement.new(achievement_json)}
+    rescue NoMethodError => e
+      []
+    end
+  
+    # ========================
+    # = Challenges API calls =
+    # ========================
+  
+    def get_profile_challenges(profile_type, id_type, id, filter_type = nil)
+      request = @connection.request.with_app_key
+      case filter_type
+      when :completed
+        request.to("/#{profile_type}/#{id_type}/#{id}/challenges/Completed")
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/challenges/Available")
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/challenges")
+      end
+      IActionable::Objects::ProfileChallenges.new(request.get)
+    end
+  
+    def get_challenges()
+      response = @connection.request.with_app_key.to("/challenges").get
+      response.map{|challenge_json| IActionable::Objects::Challenge.new(challenge_json)}
+    rescue NoMethodError => e
+      []
+    end
+  
+    # ===================
+    # = Goals API calls =
+    # ===================
+  
+    def get_profile_goals(profile_type, id_type, id, filter_type = nil)
+      request = @connection.request.with_app_key
+      case filter_type
+      when :completed
+        request.to("/#{profile_type}/#{id_type}/#{id}/goals/Completed")
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/goals/Available")
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/goals")
+      end
+      IActionable::Objects::ProfileGoals.new(request.get)
+    end
+  
+    def get_goals()
+      response = @connection.request.with_app_key.to("/goals").get
+      response.map{|goal_json| IActionable::Objects::Goal.new(goal_json)}
+    rescue NoMethodError => e
+      []
+    end
+  
+    # =========================
+    # = Leaderboard API calls =
+    # =========================
+  
+    def get_leaderboard(profile_type, point_type, leaderboard, page_number=nil, page_count=nil, id=nil, id_type=nil)
+      request = @connection.request.with_app_key.to("/#{profile_type}/leaderboards/points/#{point_type}/#{leaderboard}")
+      request.with_params(:pageNumber => page_number) unless page_number.blank?
+      request.with_params(:pageCount => page_count) unless page_count.blank?
+      request.with_params(:id => id) unless id.blank? || id_type.blank?
+      request.with_params(:idType => id_type) unless id.blank? || id_type.blank?
+      response = request.get
+      IActionable::Objects::LeaderboardReport.new(response)
+    end
+  
+    # ===================================
+    # = Profile Notifications API calls =
+    # ===================================
+  
+    def get_profile_notifications(profile_type, id_type, id)
+      response = @connection.request.with_app_key.to("/#{profile_type}/#{id_type}/#{id}/notifications").get
+      IActionable::Objects::ProfileNotifications.new(response)
+    end
+  end
+end

data/lib/iactionable/connection.rb

@@ -0,0 +1,114 @@
+require 'faraday'
+require 'faraday_stack'
+require 'iactionable/error'
+
+module IActionable
+  class Request < Struct.new(:path, :params, :headers, :body)
+    attr :settings
+    
+    def initialize(settings)
+      @settings = settings
+      self.path = nil
+      self.params = {}
+      self.headers = {}
+      self.body = {}
+    end
+    
+    def to(path)
+      self.path = path unless path.nil? || path.empty?
+      self
+    end
+    
+    def with_api_key
+      (self.headers[:Authorization] = @settings.api_key) and self
+    end
+    
+    def with_app_key
+      (self.params[:appKey] = @settings.app_key) and self
+    end
+    
+    def with_params(params={})
+      self.params.merge!(params) and self
+    end
+    
+    def with_body(body={})
+      self.body.merge!(body) and self
+    end
+  end
+  
+  class Connection
+    attr :connection
+    attr :settings
+    attr :request
+    attr_accessor :response
+    
+    def initialize(settings)
+      @settings = settings
+      
+      @connection = Faraday.new api_url(@settings.version) do |builder|
+        builder.use FaradayStack::ResponseJSON, content_type: 'application/json'
+        builder.use Faraday::Response::RaiseError
+        builder.use Faraday::Adapter::NetHttp
+      end
+      
+      @request = nil
+    end
+    
+    def request
+      (@request = Request.new(@settings)) and self
+    end
+    
+    def get(path=nil, query_params={})
+      @request ||= Request.new(@settings)
+      @request.to(path).with_params(query_params)
+      @response = @connection.get do |req|
+        req.headers.merge! @request.headers
+        req.url @request.path, @request.params
+      end
+      @response.body
+    rescue Faraday::Error::ClientError => e
+      handle_client_error e
+    ensure
+      @request = nil
+    end
+    
+    def post(path=nil, query_params={}, body_params={})
+      @request ||= Request.new(@settings)
+      @request.to(path).with_params(query_params)
+      @response = @connection.post do |req|
+        req.headers.merge! @request.headers
+        req.url @request.path, @request.params
+        req.body = @request.body unless @request.body.empty?
+      end
+      @response.body
+    rescue Exception => e
+      handle_client_error e
+    ensure
+      @request = nil
+    end
+    
+    private
+    
+    def method_missing(symbol, *args)
+      @request.send(symbol, *args) and self
+    rescue NoMethodError => e
+      raise e
+    end
+    
+    def api_url(version)
+      "http://api.iactionable.com/v#{version}/"
+    end
+    
+    def handle_client_error(e)
+      # http://iactionable.com/api/response-codes/
+      case e.response[:status]
+      when 400
+        raise IActionable::Error::BadRequest.new(e.response)
+      when 401
+        raise IActionable::Error::Unauthorized.new(e.response)
+      when 500
+        raise IActionable::Error::Internal.new(e.response)
+      end
+    end
+  end
+end

data/lib/iactionable/error.rb

@@ -0,0 +1,17 @@
+module IActionable
+  module Error
+    class Error < StandardError
+      attr_accessor :response
+      
+      def initialize(response)
+        @response = response
+        super
+      end
+    end
+  
+    # http://iactionable.com/api/response-codes/
+    class BadRequest < Error; end
+    class Unauthorized < Error; end
+    class Internal < Error; end
+  end
+end

data/lib/iactionable/objects/achievement.rb

@@ -0,0 +1,29 @@
+module IActionable
+  module Objects
+    class Achievement < IActionableObject
+      attr_accessor :key
+      attr_accessor :description
+      attr_accessor :image_url
+      attr_accessor :name
+      
+      def initialize(key_values={})
+        initialize_awardable(key_values)
+        super(key_values)
+      end
+      
+      awardable
+      
+      def to_hash
+        hash = {
+          "Key" => @key,
+          "Description" => @description,
+          "ImageURL" => @image_url,
+          "Name" => @name
+        }
+        hash.merge!(awardable_hash) unless @progress.empty?
+        hash.delete("AwardDate") if @award_date.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/iactionable/objects/awardable.rb

@@ -0,0 +1,50 @@
+module IActionable
+  module Objects
+    module Awardable
+      def self.included(base)
+        base.extend(ClassMethods)  
+      end
+    
+      module ClassMethods
+        def awardable
+          attr_accessor :award_date
+          attr_accessor :original_award_date
+          attr_accessor :progress
+          include IActionable::Objects::Awardable::InstanceMethods
+        end
+      end
+
+      module InstanceMethods
+        def initialize_awardable(key_values={})
+          @progress = extract_many_as(key_values, "Progress", IActionable::Objects::Progress)
+          # convert the miliseconds within the date string to seconds (per ruby)
+          # "/Date(1275706032317-0600)/" => "1275706032-0600"
+          @original_award_date = @award_date = key_values.delete("AwardDate")
+          @award_date = IActionableObject.timestamp_to_seconds(@award_date) unless @award_date.blank?
+        end
+      
+        def complete?
+          @progress.any? && @progress.all?
+        end
+      
+        def percent_complete
+          Integer(Float(@progress.select{|p| p.complete?}.size) / @progress.size * 100)
+        rescue TypeError => e
+          0
+        end
+      
+        def awarded_on
+          # bug in ruby 1.9.2 where Time.strptime does not support seconds-since-epoch format, but Date.strptime does, so we'll use that for now
+          Date.strptime(@award_date, "%s%z").to_time unless @award_date.blank?
+        end
+        
+        def awardable_hash
+          {
+            "AwardDate" => @original_award_date,
+            "Progress" => @progress.map{|prog| prog.to_hash}
+          }
+        end
+      end
+    end
+  end
+end

data/lib/iactionable/objects/challenge.rb

@@ -0,0 +1,27 @@
+module IActionable
+  module Objects
+    class Challenge < IActionableObject
+      awardable
+      
+      attr_accessor :key
+      attr_accessor :description
+      attr_accessor :name
+      
+      def initialize(key_values={})
+        initialize_awardable(key_values)
+        super(key_values)
+      end
+      
+      def to_hash
+        hash = {
+          "Key" => @key,
+          "Description" => @description,
+          "Name" => @name
+        }
+        hash.merge!(awardable_hash) unless @progress.empty?
+        hash.delete("AwardDate") if @award_date.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/iactionable/objects/goal.rb

@@ -0,0 +1,30 @@
+module IActionable
+  module Objects
+    class Goal < IActionableObject
+      awardable
+      
+      attr_accessor :key
+      attr_accessor :description
+      attr_accessor :name
+      attr_accessor :interval
+      
+      def initialize(key_values={})
+        initialize_awardable(key_values)
+        super(key_values)
+      end
+      
+      def to_hash
+        hash = {
+          "Key" => @key,
+          "Description" => @description,
+          "Name" => @name,
+          "Interval" => @interval
+        }
+        hash.merge!(awardable_hash) unless @progress.empty?
+        hash.delete("AwardDate") if @award_date.nil?
+        hash.delete("Interval") if @interval.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/iactionable/objects/i_actionable_object.rb

@@ -0,0 +1,36 @@
+module IActionable
+  module Objects
+    class IActionableObject
+      def initialize(key_values={})
+        key_values.each_pair do |key, value|
+          instance_variable_set "@#{key.camelize.underscore}".to_sym, value
+        end
+      end
+      
+      def self.timestamp_regexp
+        /\/Date\((\d+)((\-|\+)\d{4})\)\//
+      end
+      
+      def self.timestamp_to_seconds(timestamp)
+        milliseconds = timestamp[timestamp_regexp, 1]
+        tz = timestamp[timestamp_regexp, 2]
+        "#{Integer(milliseconds)/1000}#{tz}"
+      end
+      
+      private
+      
+      def extract_many_as(key_values, field, klass)
+        if key_values.fetch(field, nil).respond_to?(:inject)
+          loaded = []
+          content = key_values.delete(field)
+          content.each do |c|
+            loaded << klass.new(c)
+          end
+          loaded
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/iactionable/objects/identifier.rb

@@ -0,0 +1,17 @@
+module IActionable
+  module Objects
+    class Identifier < IActionableObject
+      attr_accessor :id
+      attr_accessor :id_hash
+      attr_accessor :id_type
+      
+      def to_hash
+        {
+          "ID" => @id,
+          "IDHash" => @id_hash,
+          "IDType" => @id_type
+        }
+      end
+    end
+  end
+end

data/lib/iactionable/objects/leaderboard.rb

@@ -0,0 +1,15 @@
+module IActionable
+  module Objects
+    class Leaderboard < IActionableObject
+      attr_accessor :key
+      attr_accessor :name
+      
+      def to_hash
+        {
+          "Key" => @key,
+          "Name" => @name
+        }
+      end
+    end
+  end
+end

data/lib/iactionable/objects/leaderboard_report.rb

@@ -0,0 +1,30 @@
+module IActionable
+  module Objects
+    class LeaderboardReport < IActionableObject
+      attr_accessor :page_count
+      attr_accessor :page_number
+      attr_accessor :total_count
+      attr_accessor :leaderboard
+      attr_accessor :point_type
+      attr_accessor :profiles
+      
+      def initialize(key_values={})
+        @leaderboard = IActionable::Objects::PointType.new(key_values.delete("Leaderboard"))
+        @point_type = IActionable::Objects::PointType.new(key_values.delete("PointType"))
+        @profiles = extract_many_as(key_values, "Profiles", IActionable::Objects::ProfileSummary)
+        super(key_values)
+      end
+      
+      def to_hash
+        {
+          "PageCount" => @page_count,
+          "PageNumber" => @page_number,
+          "TotalCount" => @total_count,
+          "Leaderboard" => @leaderboard.to_hash,
+          "PointType" => @point_type.to_hash,
+          "Profiles" => @profiles.map{|profile| profile.to_hash}
+        }
+      end
+    end
+  end
+end

data/lib/iactionable/objects/level.rb

@@ -0,0 +1,24 @@
+module IActionable
+  module Objects
+    class Level < IActionableObject
+      attr_accessor :name
+      attr_accessor :number
+      attr_accessor :required_points
+      attr_accessor :level_type
+      
+      def initialize(key_values={})
+        @level_type = IActionable::Objects::LevelType.new(key_values.delete("LevelType"))
+        super(key_values)
+      end
+      
+      def to_hash
+        {
+          "Name" => @name,
+          "Number" => @number,
+          "RequiredPoints" => @required_points,
+          "LevelType" => @level_type.to_hash
+        }
+      end
+    end
+  end
+end