riaction 0.0.1

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    riaction (0.0.1)
+      activerecord
+      activesupport (~> 2.0)
+      faraday
+      faraday-stack
+      resque
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activerecord (2.3.14)
+      activesupport (= 2.3.14)
+    activesupport (2.3.14)
+    addressable (2.2.6)
+    diff-lcs (1.1.3)
+    faraday (0.7.5)
+      addressable (~> 2.2.6)
+      multipart-post (~> 1.1.3)
+      rack (>= 1.1.0, < 2)
+    faraday-stack (0.1.3)
+      faraday (~> 0.6)
+    multi_json (1.0.3)
+    multipart-post (1.1.3)
+    rack (1.3.5)
+    rack-protection (1.1.4)
+      rack
+    redis (2.2.2)
+    redis-namespace (1.0.3)
+      redis (< 3.0.0)
+    resque (1.19.0)
+      multi_json (~> 1.0)
+      redis-namespace (~> 1.0.2)
+      sinatra (>= 0.9.2)
+      vegas (~> 0.1.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)
+    sinatra (1.3.1)
+      rack (~> 1.3, >= 1.3.4)
+      rack-protection (~> 1.1, >= 1.1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    tilt (1.3.3)
+    vegas (0.1.8)
+      rack (>= 1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  riaction!
+  rspec (~> 2.6)

data/README

@@ -0,0 +1,110 @@
+## Overview ##
+
+riaction provides both a ruby wrapper for IActionable's restful API and an "acts-as" style interface for a Rails application's ActiveRecord models to associate them with IActionable profiles and have them drive the logging of game events.
+
+## API Wrapper ##
+
+The wrapper for IActionable's API is used internally by the rest of the gem, but also may be used directly if desired.  IActionable's API is restful, and this wrapper takes each resource and HTTP verb of that API and wraps them as a method that takes arguments that match to the resource and query or body parameters.  Before the 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
+
+IActionable's API speaks in JSON, and here those responses are wrapped in simple objects where nesting and variable names are determined by [IActionable's documentation](http://www.http://iactionable.com/api/).  For example, here the wrapper is making a call to load a profile summary:
+
+    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"
+  
+## Using riaction In Rails ##
+
+While the API wrapper in riaction can be used directly (and I ought just pull it out as a separate gem), the rest of riaction consists of an "acts-as" style interface for your application's ActiveRecord models that leverages the API wrapper to associate your models with IActionable profiles and to have IActionable event logging be driven by your models' CRUD actions.  riaction relies on Resque for tasking all of the requests made to IActionable's service.
+
+### Initializing the API Wrapper ###
+
+Just as above, before the wrapper can be used (either directly or by the riaction interface) it needs to be initialized with your IActionable credentials.  This can be done in a small rails initializer:
+
+    I_ACTIONABLE_CREDS = (YAML.load_file("#{::Rails.root.to_s}/config/i_actionable.yml")[::Rails.env]).symbolize_keys!
+    IAction::Api.init_settings(I_ACTIONABLE_CREDS)
+
+### Declaring A Model As A Profile ###
+
+Models in your application may declare themselves as profiles that exist on IActionable.
+
+    class User < ActiveRecord::Base
+      riaction :profile, :type => :player, :username => :nickname, :custom => :id
+    end
+    
+    # == Schema Information
+    #
+    # Table name: users
+    #
+    #  id                           :integer(4)
+    #  nickname                     :string(255)
+  
+Here, the class User declares itself as a profile of type "player", identifiable by two of IActionable's supported ID types, username and custom, the values of which are the fields (or any symbol that an instance of the class responds to) nickname and id, respectively.  When a class declares itself as an riaction profile, an after_create callback will be added to register that model on IActionable as a profile as the type, and with the identifiers, described in the class.
+
+#### Profile Instance Methods ####
+
+Classes that declare themselves as IActionable profiles are given instance methods that tie in to the IActionable API, as many uses of the API take a profile as an argument.
+
+    @api.get_profile_summary("player", "username", "zortnac", 10)
+    # is equivalent to the following...
+    @user_instance.riaction_profile_summary(10)
+    
+    @api.get_profile_challenges("player", "username", "zortnac", :completed)
+    # is equivalent to the following...
+    @user_instance.riaction_profile_challenges(:completed)
+    
+    @api.add_profile_identifier("player", "username", "zortnac", "custom", 42)
+    # is equivalent to the following...
+    @user_instance.riaction_update_profile(:custom)
+
+### Declaring Events ###
+
+Models in your application may declare any number of events that they log through IActionable.  For each event that is declared the important elements are:
+
+1. The event's name (or key)
+2. The type of trigger that causes the event to be logged
+3. The profile under which the event is logged
+4. Any optional parameters (key-value pairs) that you want to pass
+
+` `
+
+    class Comment
+      belongs_to :user
+      belongs_to :post
+      
+      riaction :event, :name => :make_a_comment, :trigger => :create, :profile => :user, :params => {:post => :post_id}
+    end
+    
+    # == Schema Information
+    #
+    # Table name: comments
+    #
+    #  id                           :integer(4)
+    #  user_id                      :integer(4)
+    #  post_id                      :integer(4)
+
+Here, the name of the event is `make_a_comment`.  The trigger for the event, in this case, is `:create`, which will add an after_create callback to log the event to the API.  
+
+_Note: If the trigger is one of :create, :update, or :destroy, then the appropriate ActiveRecord callback will log the event.  If the trigger is anything else, then an instance method is provided to log the event by hand.  For example, an argument of `:trigger => :foo` will provide an instance method `trigger_foo!`_
+
+The profile that this event will be logged under can be any object whose class declares itself as a profile.  Here, the profile is the object returned by the ActiveRecord association `:user`, and we assume is an instance of the User class from above.  Lastly, the optional params passed along with the event is the key-value pair `{:post => :post_id}`, where `:post_id` is an ActiveRecord table column.
+
+Putting this all together, whenever an instance of the Comment class is created, an event is logged for which the equivalent call to the API might look like this:
+
+    @api.log_event("player", "username", "zortnac", "make_a_comment", {:post => 33})
+
+_Note: If a class both declares itself as a profile and declares one or more events, and wants to refer to itself as the profile for any of those events, use `:trigger => :self`_
+
+## 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/riaction.rb

@@ -0,0 +1,3 @@
+require "riaction/version"
+require 'riaction/iactionable/api.rb'
+require "riaction/riaction"

data/lib/riaction/iactionable/api.rb

@@ -0,0 +1,209 @@
+require 'riaction/iactionable/connection.rb'
+require 'riaction/iactionable/settings.rb'
+require 'riaction/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(:achievement_count => 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(:display_name => 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")
+        response = request.get
+        response.map{|achievement_json| IActionable::Objects::Achievement.new(achievement_json)}
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/achievements/Available")
+        response = request.get
+        response.map{|achievement_json| IActionable::Objects::Achievement.new(achievement_json)}
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/achievements")
+        response = request.get
+        {
+          :available => response["Available"].map{|achievement_json| IActionable::Objects::Achievement.new(achievement_json)},
+          :completed => response["Completed"].map{|achievement_json| IActionable::Objects::Achievement.new(achievement_json)}
+        }
+      end
+    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")
+        response = request.get
+        response.map{|challenge_json| IActionable::Objects::Challenge.new(challenge_json)}
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/challenges/Available")
+        response = request.get
+        response.map{|challenge_json| IActionable::Objects::Challenge.new(challenge_json)}
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/challenges")
+        response = request.get
+        {
+          :available => response["Available"].map{|challenge_json| IActionable::Objects::Challenge.new(challenge_json)},
+          :completed => response["Completed"].map{|challenge_json| IActionable::Objects::Challenge.new(challenge_json)}
+        }
+      end
+    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")
+        response = request.get
+        response.map{|goal_json| IActionable::Objects::Goal.new(goal_json)}
+      when :available
+        request.to("/#{profile_type}/#{id_type}/#{id}/goals/Available")
+        response = request.get
+        response.map{|goal_json| IActionable::Objects::Goal.new(goal_json)}
+      else
+        request.to("/#{profile_type}/#{id_type}/#{id}/goals")
+        response = request.get
+        {
+          :available => response["Available"].map{|goal_json| IActionable::Objects::Goal.new(goal_json)},
+          :completed => response["Completed"].map{|goal_json| IActionable::Objects::Goal.new(goal_json)}
+        }
+      end
+    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
+      {
+        :achievements => {
+          :available => response["Achievements"]["Available"].map{|a| IActionable::Objects::Achievement.new(a)},
+          :completed => response["Achievements"]["Completed"].map{|a| IActionable::Objects::Achievement.new(a)}
+        },
+        :challenges => {
+          :available => response["Challenges"]["Available"].map{|c| IActionable::Objects::Challenge.new(c)},
+          :completed => response["Challenges"]["Completed"].map{|c| IActionable::Objects::Challenge.new(c)}
+        },
+        :goals => {
+          :available => response["Goals"]["Available"].map{|g| IActionable::Objects::Goal.new(g)},
+          :completed => response["Goals"]["Completed"].map{|g| IActionable::Objects::Goal.new(g)}
+        },
+        :levels => response["Levels"].map{|l| IActionable::Objects::Level.new(l)},
+        :points => response["Points"].map{|p| IActionable::Objects::ProfilePoints.new(p)}
+      }
+    end
+  end
+end

data/lib/riaction/iactionable/connection.rb

@@ -0,0 +1,114 @@
+require 'faraday'
+require 'faraday_stack'
+require 'riaction/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