eve 1.0.0

data/lib/eve/api.rb

@@ -0,0 +1,247 @@
+require 'eve/api/request'
+require 'eve/api/response'
+require 'eve/api/services'
+require 'eve/api/connectivity'
+
+module Eve
+  # = Eve API Libraries
+  #
+  # EVE Online has made available various APIs which allow for querying the server for information about the server's
+  # current status, general game information such as skill and certificate trees, top player rankings, and the players
+  # and characters themselves. This library interfaces with that API to provide an intuitive way of retrieving this
+  # data.
+  #
+  # == The Basics
+  #
+  # There are two forms of authentication that the API uses: a limited API key and a full API key. For some information,
+  # such as the server's current status, no API key at all is required; for other information, such as which characters
+  # are owned by a particular user account, a limited API key will suffice. For more personal information, such as
+  # a character's transaction history, a full API key is required. Using an inappropriate or missing API key will result
+  # in an error being raised.
+  #
+  # === Instantiation & [Re]Configuration
+  # To interface with the Eve API, you need to instantiate the API object. This is simple:
+  #   api = Eve::API.new
+  #
+  # If you plan to make use of information requiring an API key, you'll need to pass in those options:
+  #   api = Eve::API.new(:user_id => 'a_user_id', :api_key => 'an_api_key')
+  #
+  # If you need to make use of Character-specific API calls, then you should also pass a +:character_id+ key. Same goes
+  # for Corporation-specific API calls: pass a +corporation_id+ key. If you don't know those yet (for instance, because
+  # you need the user to make a selection), then don't fret. You can always instantiate a new API object, or simply
+  # set the option directly on the API object you've already got:
+  #   api.set(:character_id => 'a_character_id')
+  #   # -or-
+  #   api[:character_id] = 'a_character_id'
+  #
+  # === Making API Calls
+  # Actually retrieving information is just as straightforward as instantiation of the API object was, though the syntax
+  # does sometimes vary from one call to the next. Here's how to get the current server status:
+  #   status = api.server_status
+  #
+  # And retrieving the list of characters belonging to :user_id is done like so:
+  #   charlist = api.account.characters
+  #
+  # === List of API Calls
+  # This section is split into 3 subsections, one for each level of API key required for the call in question. This
+  # table assumes the presence of an "api" object, which is an instantiation of the API object as shown above. For
+  # more information on a particular subset of calls, including the exact return values, click on the corresponding
+  # class name to the left.
+  #
+  # ==== No API Key
+  # Eve::API::Services::Corporation:: api.corporation.corporation_sheet
+  # Eve::API::Services::Eve::         api.eve.alliance_list
+  # Eve::API::Services::Eve::         api.eve.certificate_tree
+  # Eve::API::Services::Eve::         api.eve.conquerable_station_list
+  # Eve::API::Services::Eve::         api.eve.error_list
+  # Eve::API::Services::Eve::         api.eve.fac_war_stats / api.eve.factional_warfare_stats
+  # Eve::API::Services::Eve::         api.eve.fac_war_top_stats / api.eve.factional_warfare_top100
+  # Eve::API::Services::Eve::         api.eve.character_name(*ids)
+  # Eve::API::Services::Eve::         api.eve.character_id(*names)
+  # Eve::API::Services::Eve::         api.eve.corporation_name(*ids)
+  # Eve::API::Services::Eve::         api.eve.corporation_id(*names)
+  # Eve::API::Services::Eve::         api.eve.alliance_name(*ids)
+  # Eve::API::Services::Eve::         api.eve.alliance_id(*names)
+  # Eve::API::Services::Eve::         api.eve.ref_types
+  # Eve::API::Services::Eve::         api.eve.skill_tree
+  # Eve::API::Services::Map::         api.map.fac_war_systems / api.map.contested_systems
+  # Eve::API::Services::Map::         api.map.sovereignty
+  # Eve::API::Services::Map::         api.map.kills
+  # Eve::API::Services::Map::         api.map.jumps
+  # Eve::API::Services::Misc::        api.misc.character_portrait
+  # Eve::API::Services::Server::      api.server.server_status
+  #
+  # ==== Limited API Key
+  # Eve::API::Services::Account::     api.account.characters
+  # Eve::API::Services::Character::   api.character.character_sheet
+  # Eve::API::Services::Character::   api.character.fac_war_stats
+  # Eve::API::Services::Character::   api.character.medals
+  # Eve::API::Services::Character::   api.character.skill_in_training
+  # Eve::API::Services::Character::   api.character.skill_queue
+  # Eve::API::Services::Character::   api.character.standings
+  # Eve::API::Services::Corporation:: api.corporation.corporation_sheet
+  # Eve::API::Services::Corporation:: api.corporation.fac_war_stats
+  # Eve::API::Services::Corporation:: api.corporation.medals
+  # Eve::API::Services::Corporation:: api.corporation.member_medals
+  #
+  # ==== Full API Key
+  # Eve::API::Services::Character::   api.character.account_balance
+  # Eve::API::Services::Character::   api.character.asset_list(version = nil)
+  # Eve::API::Services::Character::   api.character.industry_jobs
+  # Eve::API::Services::Character::   api.character.kill_log(options = {})
+  # Eve::API::Services::Character::   api.character.mailing_lists
+  # Eve::API::Services::Character::   api.character.mail_messages
+  # Eve::API::Services::Character::   api.character.market_orders
+  # Eve::API::Services::Character::   api.character.notifications
+  # Eve::API::Services::Character::   api.character.research
+  # Eve::API::Services::Character::   api.character.wallet_journal(account_key = 1000, options = {})
+  # Eve::API::Services::Character::   api.character.journal_entries(account_key = 1000, options = {})
+  # Eve::API::Services::Character::   api.character.wallet_transactions(options = {})
+  # Eve::API::Services::Corporation:: api.corporation.account_balance
+  # Eve::API::Services::Corporation:: api.corporation.asset_list
+  # Eve::API::Services::Corporation:: api.corporation.container_log
+  # Eve::API::Services::Corporation:: api.corporation.corporation_sheet(corporation_id = nil)
+  # Eve::API::Services::Corporation:: api.corporation.fac_war_stats
+  # Eve::API::Services::Corporation:: api.corporation.industry_jobs
+  # Eve::API::Services::Corporation:: api.corporation.kill_log(options = {})
+  # Eve::API::Services::Corporation:: api.corporation.market_orders
+  # Eve::API::Services::Corporation:: api.corporation.member_security
+  # Eve::API::Services::Corporation:: api.corporation.member_security_log
+  # Eve::API::Services::Corporation:: api.corporation.member_tracking
+  # Eve::API::Services::Corporation:: api.corporation.starbase_detail(item_id, version = 2)
+  # Eve::API::Services::Corporation:: api.corporation.starbase_list
+  # Eve::API::Services::Corporation:: api.corporation.shareholders
+  # Eve::API::Services::Corporation:: api.corporation.standings
+  # Eve::API::Services::Corporation:: api.corporation.titles
+  # Eve::API::Services::Corporation:: api.corporation.wallet_journal(account_key = 1000, options = {})
+  # Eve::API::Services::Corporation:: api.corporation.wallet_transactions(account_key = 1000, options = {})
+  #
+  # === Interpreting Responses
+  # Response objects are generated automatically, and should be able to accommodate any changes in the API reasonably
+  # well.
+  #
+  # The classes listed above attempt to document the API calls. However, if you are unsure of
+  # how to process the return value of a particular API call, don't be afraid to check it out directly:
+  #   irb(main):004:0> puts api.server_status.to_yaml
+  #   ---
+  #   current_time: 2010-03-14T04:41:51+00:00
+  #   cached_until: 2010-03-14T04:44:51+00:00
+  #   online_players: 30694
+  #   server_open: true
+  #   api_version: "2"
+  #
+  # In this example, #server_status provides 5 fields: #api_version, #cached_until, #current_time, #online_players,
+  # and #server_open.
+  #
+  # Some fields in a given response are essentially arrays with some additional fields. These are called Rowsets. For
+  # instance, the call to +api.account.characters+, above, returned a response with a #characters method, which
+  # contained up to 3 characters. Each element, or Row, in a Rowset has in turn its own fields and/or Rowsets. Each
+  # character in this example includes a #character_id, #corporation_id, and #corporation_name.
+  #
+  # Additionally, all responses always have a #name field. For basic responses, the #name is "(Response)", and
+  # probably doesn't mean much to you. For Rowsets, the #name is the name of the Rowset (for example, "characters").
+  # For individual Rows, the #name might mean something more useful -- the name of a character, for instance.
+  #
+  class API
+    include Eve::API::Connectivity
+    include Eve::API::Services
+    attr_reader :options
+    attr_reader :map
+
+    def initialize(options = {})
+      @options = default_options.merge(options)
+      send_includes
+      instantiate_submodules
+    end
+
+    def set(key, value = nil)
+      raise "Key can't be nil" unless key
+      if key.kind_of?(Hash)
+        key.each { |k, v| set(k, v) }
+      else
+        if value then @options[key] = value
+        else @options.delete key
+        end
+        [@options[:submodules]].flatten.each do |sub|
+          self.send(sub).set(key, value) if sub
+        end
+      end
+    end
+
+    def [](key); @options[key]; end
+    def []=(key, value); set(key, value); end
+
+    private
+    class << self
+      def validate_credentials(key_type, *args)
+        case key_type
+          when :limited, :full
+            args.flatten!
+            options = args.extract_options!
+            method_names = options.delete(:for)
+            raise ArgumentError, "Unexpected options: #{options.keys.inspect}" unless options.empty?
+
+            method_names.each do |method_name|
+              define_method "#{method_name}_with_credential_validation" do |*a|
+                validate_credentials(key_type, *args)
+                send("#{method_name}_without_credential_validation", *a)
+              end
+              alias_method_chain method_name, :credential_validation
+            end
+
+          else raise ArgumentError, "Expected :limited or :full credential type"
+        end
+      end
+    end
+
+    def validate_credentials(type, *additional_requirements)
+      raise ArgumentError, "user_id is required" unless options[:user_id]
+      raise ArgumentError, "api_key is required" unless options[:api_key]
+      additional_requirements.each do |r|
+        raise ArgumentError, "#{r} is required" unless options[r]
+      end
+
+      case type
+        when :limited, :full # currently no difference. Wish we could validate on this.
+        else raise ArgumentError, "Expected :limited or :full credential type"
+      end
+    end
+    
+    def validate_options(options, *keys)
+      options.keys.each do |key|
+        raise ArgumentError, "Options should only include #{keys.inspect}" unless keys.include?(key)
+      end
+    end
+
+    def send_includes
+      [@options[:includes]].flatten.each do |mod|
+        next unless mod
+        mod = mod.to_s unless mod.kind_of?(String)
+        eigenclass.send(:include, "::Eve::API::Services::#{mod.camelize}".constantize)
+      end
+    end
+
+    def instantiate_submodules
+      [@options[:submodules]].flatten.each do |mod|
+        next unless mod
+        instance_variable_set("@#{mod}", ::Eve::API.new(options.merge(:includes => mod, :submodules => nil)))
+        eigenclass.send(:attr_reader, mod)
+      end
+    end
+
+    def eigenclass
+      class << self; self; end
+    end
+
+    def default_options
+      {
+        :submodules => [:map, :eve, :account, :character, :corporation],
+        :cache => true
+      }
+    end
+
+    def cache_namespace
+      self.class.name.underscore
+    end
+  end
+end

data/lib/eve/api/connectivity.rb

@@ -0,0 +1,39 @@
+module Eve
+  class API
+    module Connectivity
+      MAX_JOURNAL_ENTRIES = 1000
+
+      def walk(walk_id, walk_association, options = {}, &block)
+        raise ArgumentError, "Requires :walk_id" if walk_id.blank?
+        raise ArgumentError, "Requires :walk_association" if walk_association.blank?
+        options[walk_id] ||= 0
+        return_value = yield options
+        array = return_value.send(walk_association)
+        if array.size >= MAX_JOURNAL_ENTRIES
+          begin
+            min_id = nil
+            primary_key = array.primary_key
+            array.each { |txn| min_id = txn.send(primary_key) if min_id.nil? || min_id > txn.send(primary_key) }
+            array.concat walk(walk_id, options.merge(walk_id => min_id), &block).send(walk_association)
+          rescue Eve::Errors::UserInputErrors::InvalidBeforeTransID, Eve::Errors::UserInputErrors::InvalidBeforeRefID,
+                 Eve::Errors::UserInputErrors::InvalidBeforeKillID
+            # walking is internal, so we should catch the error internally too.
+          end
+        end
+        return_value
+      end
+
+      def request(namespace, service_name, options = {})
+        walk_id = options.delete(:walk_id) # we don't want these being sent to the server; it messes with the cache.
+        walk_association = options.delete(:walk_association)
+        if options.delete(:walk)
+          walk(walk_id.to_s, walk_association, options) do |walk_options|
+            Eve::API::Request.new(namespace, service_name, self.options.merge(walk_options)).dispatch
+          end
+        else
+          Eve::API::Request.new(namespace, service_name, self.options.merge(options)).dispatch
+        end
+      end
+    end
+  end
+end

data/lib/eve/api/request.rb

@@ -0,0 +1,74 @@
+module Eve
+  class API
+    class Request
+      extend ActiveSupport::Memoizable
+      attr_reader :response, :uri, :options, :namespace, :service
+      
+      def initialize(namespace, service, options = {})
+        options.reverse_merge! default_options
+        namespace = namespace.to_s if namespace.is_a?(Symbol)
+        service   = service.to_s   if service.is_a?(Symbol)
+
+        unless [:xml,:string].include? options[:response_type]
+          raise ArgumentError, "Expected :response_type to be :xml or :string"
+        end
+
+        @options = options.dup
+        @service = options[:camelize] ? service.camelize : service
+        @namespace = namespace
+        @response_type = options[:response_type]
+
+        @uri = File.join(@options.delete(:base_uri), @namespace, "#{@service}.#{options[:extension]}")
+      end
+
+      def dispatch
+        r = (cached_response || cache_response(Net::HTTP.post_form(URI.parse(uri), post_options).body))
+        if r.respond_to?(:error) && r.error
+          Eve::Errors.raise(:code => r.error.code, :message => r.error)
+        end
+        r
+      end
+
+      def cached_response
+        if xml = (options[:cache] ? Eve.cache.read(cache_key) : nil)
+          potential_response = response_for(xml)
+          if !potential_response.respond_to?(:cached_until) || potential_response.cached_until >= Time.now
+            return potential_response
+          end
+        end
+        nil
+      end
+
+      def response_for(body)
+        @response_type == :xml ? Eve::API::Response.new(body, options) : body
+      end
+
+      def cache_response(xml)
+        Eve.cache.write(cache_key, xml) if options[:cache]
+        response_for xml
+      end
+
+      def cache_key
+        ActiveSupport::Cache.expand_cache_key(post_options, @uri)
+      end
+
+      memoize :cache_key
+
+      private
+      def post_options
+        options.without(default_options.keys).camelize_keys
+      end
+
+      def default_options
+        {
+          :base_uri => "http://api.eve-online.com",
+          :extension => "xml.aspx",
+          :camelize => true,
+          :response_type => :xml,
+          :column_mapping => nil,
+          :cache => true
+        }
+      end
+    end
+  end
+end

data/lib/eve/api/response.rb

@@ -0,0 +1,100 @@
+require 'eve/api/response/inspection'
+require 'eve/api/response/wrap_object'
+require 'eve/api/response/rowsets'
+require 'eve/api/response/rowset'
+
+module Eve
+  class API
+    class Response
+      include Eve::API::Response::WrapObject
+      include Eve::API::Response::Rowsets
+      include Eve::API::Response::Inspection
+      attr_reader :api_version, :content
+
+      def initialize(xml, options = {})
+        @options = options
+        xml = Hpricot::XML(xml).root if xml.kind_of?(String)
+        @xml = xml
+        #@attributes = {}
+
+        parse_xml unless options[:process_xml] == false
+      end
+
+      def to_hash
+        hash = {}
+        (instance_variables - protected_instance_variables + (@name.blank? ? [] : ["@name"])).each do |ivar|
+          value = instance_variable_get(ivar)
+          value = case value
+            when Rowset then value.to_a
+            when Response then value.to_hash
+            else value
+          end
+          hash[ivar[1..-1]] = value
+        end
+        hash
+      end
+
+      def to_yaml(*args)
+        to_hash.to_yaml(*args)
+      end
+
+      def [](key)
+        key = key.to_s if !key.kind_of?(String)
+        key = key.underscore
+        instance_variable_get("@#{key}") ||
+                raise(ArgumentError, "No attribute called '#{key}' seems to exist in #{self.inspect}")
+      end
+
+      protected
+      def parse_xml(node = @xml)
+        case node
+          when Hpricot::Elem
+            parse_elem(node)
+        end
+      end
+
+      def check_for_datetime(value)
+        if value =~ /\A[0-9]{4}\-[0-9]{2}\-[0-9]{2} [0-9]{2}\:[0-9]{2}\:[0-9]{2}\z/
+          DateTime.parse(value)
+        else
+          value
+        end
+      end
+
+      def wrap_method_around_node(node = @xml)
+        # TODO: refactor me.
+        if !node.children || !node.children.select { |c| c.is_a?(Hpricot::Elem) }.empty?
+          @content = node.inner_text.strip if !node.children
+          value = Eve::API::Response.new(node, @options.merge(:process_xml => false))
+          value.send(:copy_attributes, node.attributes.to_hash.keys, node)
+          value.parse_children
+        else
+          value = value_for(node.inner_text)
+          value = check_for_datetime(value)
+          # now define any attributes as methods on the resultant object
+          node_attributes = node.attributes.to_hash
+          copy_attributes(node_attributes.keys, node, value)
+        end
+
+        wrap_object(node.name, value)
+      end
+
+      def parse_elem(node = @xml)
+        case node.name
+          when 'eveapi' then
+            @api_version = node['version']
+            parse_children(node)
+          when 'result' then
+            parse_children(node)
+          when 'rowset' then
+            add_rowset Rowset.new(node, @options)
+          else wrap_method_around_node(node)
+        end
+      end
+
+      def parse_children(node = @xml)
+        node.children.each { |child| parse_xml(child) } if node.children
+      end
+    end
+  end
+end