vkontakte_api 0.2.1 → 1.0.rc

data/lib/vkontakte_api/logger.rb

@@ -0,0 +1,35 @@
+module VkontakteApi
+  # Faraday middleware for logging requests and responses.
+  # 
+  # It's behaviour depends on the logging options in the configuration.
+  class Logger < Faraday::Response::Middleware
+    # Creates a middleware instance.
+    # The logger is set from `:logger` configuration option.
+    def initialize(app)
+      super(app)
+      @logger = VkontakteApi.logger
+    end
+    
+    # Logs the request if needed.
+    # @param [Hash] env Request data.
+    def call(env)
+      if VkontakteApi.log_requests?
+        @logger.debug "#{env[:method].to_s.upcase} #{env[:url].to_s}"
+      end
+      
+      super
+    end
+    
+    # Logs the response (successful or not) if needed.
+    # @param [Hash] env Response data.
+    def on_complete(env)
+      if env[:body].error?
+        @logger.warn env[:raw_body]  if VkontakteApi.log_errors?
+      else
+        @logger.debug env[:raw_body] if VkontakteApi.log_responses?
+      end
+    end
+  end
+end
+
+Faraday.register_middleware :response, :vk_logger => VkontakteApi::Logger

data/lib/vkontakte_api/method.rb

@@ -0,0 +1,40 @@
+module VkontakteApi
+  # An API method. It is responsible for generating it's full name and determining it's type.
+  class Method
+    include Resolvable
+    
+    # A pattern for names of methods with a boolean result.
+    PREDICATE_NAMES = /^is.*\?$/
+    
+    # Calling the API method.
+    # It delegates the network request to `API.call` and result processing to `Result.process`.
+    # @param [Hash] args Arguments for the API method.
+    def call(args = {}, &block)
+      response = API.call(full_name, args, token)
+      Result.process(response, type, block)
+    end
+    
+  private
+    def full_name
+      parts = [@previous_resolver.name, @name].compact.map { |part| camelize(part) }
+      parts.join('.').gsub(/[^A-Za-z.]/, '')
+    end
+    
+    def type
+      @name =~ PREDICATE_NAMES ? :boolean : :anything
+    end
+    
+    # camelize('get_profiles')
+    # => 'getProfiles'
+    def camelize(name)
+      words = name.split('_')
+      first_word = words.shift
+      
+      words.each do |word|
+        word.sub!(/^[a-z]/, &:upcase)
+      end
+      
+      words.unshift(first_word).join
+    end
+  end
+end

data/lib/vkontakte_api/namespace.rb

@@ -0,0 +1,7 @@
+module VkontakteApi
+  # An API method namespace (such as `users` or `friends`). It just includes `Resolvable` and `Resolver`.
+  class Namespace
+    include Resolvable
+    include Resolver
+  end
+end

data/lib/vkontakte_api/resolvable.rb

@@ -0,0 +1,20 @@
+module VkontakteApi
+  # A mixin for classes that will be resolved via `#method_missing`.
+  module Resolvable
+    attr_reader :name
+    
+    # Creates a resolvable object keeping it's name and the object that resolved it.
+    # @param [String] name The name of this resolvable.
+    # @option options [Hashie::Mash] :resolver A mash holding information about the previous resolver.
+    def initialize(name, options = {})
+      @name = name
+      @previous_resolver = options.delete(:resolver)
+    end
+    
+    # Returns the token from the previous resolver.
+    # @return [String] A token.
+    def token
+      @previous_resolver.token
+    end
+  end
+end

data/lib/vkontakte_api/resolver.rb

@@ -1,125 +1,40 @@
 module VkontakteApi
-  # A class for resolving namespaced methods like `friends.get`.
-  # 
-  # Methods are dispatched the following way:
-  # 
-  # 1. API client gets an unknown method, creates a `VkontakteApi::Resolver` instance and sends it the method
-  # 2. if the method is a namespace (like `friends`), it creates another `VkontakteApi::Resolver` instance, namespaced this time; else go to 3
-  # 3. the `VkontakteApi::Resolver` instance gets the last method, inserts an access token into params and sends it to `VkontakteApi::API`
-  # 4. the result is typecasted and/or yielded (mapped) to a block depending on it's type
-  class Resolver
-    # A pattern for names of methods with a boolean result.
-    PREDICATE_NAMES = /^(is.*)\?$/
-    
-    # A namespace of the current instance (if present).
-    attr_reader :namespace
-    
-    # A new resolver.
-    # @option options [String] :namespace A namespace.
-    # @option options [String] :access_token An access token.
-    def initialize(options = {})
-      @namespace    = options.delete(:namespace)
-      @access_token = options.delete(:access_token)
-    end
-    
+  # A mixin for classes that will resolve other classes' objects via `#method_missing`.
+  module Resolver
     # Main methods dispatch.
     # 
-    # If the called method is a namespace, it creates and returns a new `VkontakteApi::Resolver` instance.
-    # Otherwise it determines the full method name and result type, and sends everything to `VkontakteApi::API`.
-    # 
-    # If the result is enumerable, each element is yielded to the block (or returned as is if called without a block).
-    # Non-enumerable results are typecasted (and yielded if the block is present).
-    # 
-    # Called with a block, it returns the result of the block; called without a block it returns just the result.
-    # @todo Break this crap into several small methods.
+    # If the called method is a namespace, it creates and returns a new `VkontakteApi::Namespace` instance.
+    # Otherwise it creates a `VkontakteApi::Method` instance and invokes it's `#call` method passing it the arguments and a block.
     def method_missing(method_name, *args, &block)
       method_name = method_name.to_s
       
       if Resolver.namespaces.include?(method_name)
-        # first level of method with a two-level name called
-        Resolver.new(:namespace => method_name, :access_token => @access_token)
+        # called from Client
+        Namespace.new(method_name, :resolver => resolver)
       else
-        # method with a one-level name called (or second level of a two-level method)
-        name, type = Resolver.vk_method_name(method_name, @namespace)
-        
-        args = args.first || {}
-        args[:access_token] = @access_token unless @access_token.nil?
-        
-        result = API.call(name, args, &block)
-        
-        if result.respond_to?(:each)
-          # enumerable result receives :map with a block when called with a block
-          # or is returned untouched otherwise
-          block_given? ? result.map(&block) : result
-        else
-          # non-enumerable result is typecasted
-          # (and yielded if block_given?)
-          result = typecast(result, type)
-          block_given? ? yield(result) : result
-        end
+        # called from Namespace or one-level method
+        Method.new(method_name, :resolver => resolver).call(args.first || {}, &block)
       end
     end
     
-  private
-    def typecast(parameter, type)
-      case type
-      when :boolean
-        # '1' becomes true, '0' becomes false
-        !parameter.to_i.zero?
-      else
-        parameter
-      end
+    # A `Hashie::Mash` structure holding the name and token of current instance.
+    # @return [Hashie::Mash]
+    def resolver
+      @resolver ||= Hashie::Mash.new(:name => @name, :token => token)
     end
     
     class << self
       # An array of method namespaces.
+      # Lazily loads the list from `namespaces.yml` and caches it.
       # @return [Array]
-      attr_reader :namespaces
-      
-      # Loading namespaces array from `namespaces.yml`.
-      # This method is called automatically at startup time.
-      def load_namespaces
-        filename    = File.expand_path('../namespaces.yml', __FILE__)
-        file        = File.read(filename)
-        @namespaces = YAML.load(file)
-      end
-      
-      # A complete method name needed by VKontakte.
-      # 
-      # Returns a full name and the result type (:boolean or :anything).
-      # @example
-      #   vk_method_name('is_app_user?')
-      #   # => 'isAppUser'
-      #   vk_method_name('get_country_by_id', 'places')
-      #   # => 'places.getCountryById'
-      # @return [Array] full method name and type
-      def vk_method_name(method_name, namespace = nil)
-        method_name = method_name.to_s
-        
-        if method_name =~ PREDICATE_NAMES
-          # predicate methods should return true or false
-          method_name.sub!(PREDICATE_NAMES, '\1')
-          type = :boolean
-        else
-          # other methods can return anything they want
-          type = :anything
+      def namespaces
+        if @namespaces.nil?
+          filename    = File.expand_path('../namespaces.yml', __FILE__)
+          @namespaces = YAML.load_file(filename)
         end
         
-        full_name = ''
-        full_name << convert(namespace) + '.' unless namespace.nil?
-        full_name << convert(method_name)
-        
-        [full_name, type]
-      end
-      
-    private
-      # convert('get_profiles')
-      # => 'getProfiles'
-      def convert(name)
-        name.camelize(:lower)
+        @namespaces
       end
     end
   end
 end
-
-VkontakteApi::Resolver.load_namespaces

data/lib/vkontakte_api/result.rb

@@ -0,0 +1,48 @@
+module VkontakteApi
+  # A module that handles method result processing.
+  # 
+  # It implements method blocks support, result typecasting and raises `VkontakteApi::Error` in case of an error response.
+  module Result
+    class << self
+      # The main method result processing.
+      # @param [Hashie::Mash] response The server response in mash format.
+      # @param [Symbol] type The expected result type (`:boolean` or `:anything`).
+      # @param [Proc] block A block passed to the API method.
+      # @return [Array, Hashie::Mash] The processed result.
+      # @raise [VkontakteApi::Error] raised when VKontakte returns an error response.
+      def process(response, type, block)
+        result = extract_result(response)
+        
+        if result.respond_to?(:each)
+          # enumerable result receives :map with a block when called with a block
+          # or is returned untouched otherwise
+          block.nil? ? result : result.map(&block)
+        else
+          # non-enumerable result is typecasted
+          # (and yielded if block_given?)
+          result = typecast(result, type)
+          block.nil? ? result : block.call(result)
+        end
+      end
+      
+    private
+      def extract_result(response)
+        if response.error?
+          raise VkontakteApi::Error.new(response.error)
+        else
+          response.response
+        end
+      end
+      
+      def typecast(parameter, type)
+        case type
+        when :boolean
+          # '1' becomes true, '0' becomes false
+          !parameter.to_i.zero?
+        else
+          parameter
+        end
+      end
+    end
+  end
+end

data/lib/vkontakte_api/uploading.rb

@@ -0,0 +1,29 @@
+module VkontakteApi
+  # A module implementing files uploading functionality.
+  # 
+  # @note `VkontakteApi::Uploading` extends `VkontakteApi` so these methods should be called from the latter.
+  module Uploading
+    # Files uploading. It uses the same faraday middleware stack as API method calls (by using `VkontakteApi::API.connection`).
+    # @param [Hash] params A list of files to upload (also includes the upload URL). See example for the hash format.
+    # @option params [String] :url URL for the request.
+    # @return [Hashie::Mash] The server response.
+    # @raise [ArgumentError] raised when a `:url` parameter is omitted.
+    # @example
+    #   VkontakteApi.upload(
+    #     url:   'http://example.com/upload',
+    #     file1: ['/path/to/file1.jpg', 'image/jpeg'],
+    #     file2: ['/path/to/file2.png', 'image/png']
+    #   )
+    def upload(params = {})
+      url = params.delete(:url)
+      raise ArgumentError, 'You should pass :url parameter' unless url
+      
+      files = {}
+      params.each do |param_name, (file_path, file_type)|
+        files[param_name] = Faraday::UploadIO.new(file_path, file_type)
+      end
+      
+      API.connection.post(url, files).body
+    end
+  end
+end

data/lib/vkontakte_api/utils.rb

@@ -0,0 +1,28 @@
+module VkontakteApi
+  # An utility module able to flatten arguments (join arrays into comma-separated strings).
+  module Utils
+    class << self
+      # A multiple version of `#flatten_argument`. It transforms a hash flattening each value and keeping the keys untouched.
+      # @param [Hash] arguments The arguments to flatten.
+      # @return [Hash] Flattened arguments.
+      def flatten_arguments(arguments)
+        arguments.inject({}) do |flat_args, (arg_name, arg_value)|
+          flat_args[arg_name] = flatten_argument(arg_value)
+          flat_args
+        end
+      end
+      
+      # If an argument is an array, it will be joined with a comma; otherwise it'll be returned untouched.
+      # @param [Object] argument The argument to flatten.
+      def flatten_argument(argument)
+        if argument.respond_to?(:join)
+          # if argument is an array, we join it with a comma
+          argument.join(',')
+        else
+          # otherwise leave it untouched
+          argument
+        end
+      end
+    end
+  end
+end

data/lib/vkontakte_api/version.rb

@@ -1,3 +1,4 @@
 module VkontakteApi
-  VERSION = '0.2.1'
+  # Library version.
+  VERSION = '1.0.rc'
 end

data/lib/vkontakte_api.rb

@@ -1,19 +1,30 @@
 require 'faraday'
-require 'yajl'
+require 'faraday_middleware'
+require 'faraday_middleware/parse_oj'
+require 'oauth2'
 require 'yaml'
-require 'active_support/core_ext/string/inflections'
-require 'active_support/core_ext/object/to_query'
+require 'hashie'
 
 require 'vkontakte_api/version'
 require 'vkontakte_api/error'
 require 'vkontakte_api/configuration'
+require 'vkontakte_api/authorization'
+require 'vkontakte_api/uploading'
+require 'vkontakte_api/utils'
 require 'vkontakte_api/api'
 require 'vkontakte_api/resolver'
+require 'vkontakte_api/resolvable'
 require 'vkontakte_api/client'
+require 'vkontakte_api/namespace'
+require 'vkontakte_api/method'
+require 'vkontakte_api/result'
+require 'vkontakte_api/logger'
 
 # Main module.
 module VkontakteApi
   extend VkontakteApi::Configuration
+  extend VkontakteApi::Authorization
+  extend VkontakteApi::Uploading
 end
 
 # short alias

data/spec/integration_spec.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+require 'spec_helper'
+
+describe "Integration" do
+  before(:all) do
+    # turn off all the logging
+    VkontakteApi.configure do |config|
+      config.log_requests  = false
+      config.log_errors    = false
+      config.log_responses = false
+    end
+  end
+  
+  describe "unauthorized requests" do
+    before(:each) do
+      @vk = VkontakteApi::Client.new
+    end
+    
+    it "get users" do
+      user = @vk.users.get(:uid => 1).first
+      user.uid.should        == 1
+      user.last_name.should  == 'Дуров'
+      user.first_name.should == 'Павел'
+    end
+  end
+  
+  describe "authorized requests" do
+    before(:each) do
+      @vk = VkontakteApi::Client.new(ENV['TOKEN'])
+    end
+    
+    it "get groups" do
+      groups = @vk.groups.get
+      groups.should include(1)
+    end
+  end if ENV['TOKEN']
+  
+  describe "requests with camelCase and predicate methods" do
+    before(:each) do
+      @vk = VkontakteApi::Client.new(ENV['TOKEN'])
+    end
+    
+    it "convert method names to vk.com format" do
+      @vk.is_app_user?.should be_true
+    end
+  end if ENV['TOKEN']
+  
+  describe "requests with array arguments" do
+    before(:each) do
+      @vk = VkontakteApi::Client.new
+    end
+    
+    it "join arrays with a comma" do
+      users = @vk.users.get(:uids => [1, 2, 3], :fields => %w[first_name last_name screen_name])
+      users.first.screen_name.should == 'durov'
+    end
+  end
+  
+  describe "requests with blocks" do
+    before(:each) do
+      @vk = VK::Client.new
+    end
+    
+    it "map the result with a block" do
+      users = @vk.users.get(:uid => 1) do |user|
+        "#{user.last_name} #{user.first_name}"
+      end
+      
+      users.first.should == 'Дуров Павел'
+    end
+  end
+  
+  describe "authorization" do
+    context "with a scope" do
+      it "returns a correct url" do
+        VkontakteApi.authorization_url(:scope => %w[friends groups]).should include('scope=friends%2Cgroups')
+      end
+    end
+  end
+  
+  after(:all) do
+    VkontakteApi.reset
+  end
+end

data/spec/spec_helper.rb

@@ -1,2 +1,20 @@
 require 'vkontakte_api'
 require 'pry'
+
+RSpec::Matchers.define :log_requests do
+  match do |logger|
+    logger.log_requests?
+  end
+end
+
+RSpec::Matchers.define :log_errors do
+  match do |logger|
+    logger.log_errors?
+  end
+end
+
+RSpec::Matchers.define :log_responses do
+  match do |logger|
+    logger.log_responses?
+  end
+end

data/spec/vkontakte_api/api_spec.rb

@@ -1,81 +1,62 @@
 require 'spec_helper'
 
 describe VkontakteApi::API do
-  before(:each) do
-    @method_name =  'apiMethod'
-    @args = {
-      :field        => 'value',
-      :access_token => 'some_token'
-    }
+  def create_connection
+    @result = {'response' => {'key' => 'value'}}
+    
+    @connection = Faraday.new do |builder|
+      builder.response :mashify
+      builder.response :json, :preserve_raw => true
+      builder.adapter  :test do |stub|
+        stub.get('/apiMethod') do
+          [200, {}, Oj.dump(@result)]
+        end
+      end
+    end
+    subject.stub(:connection).and_return(@connection)
   end
   
   describe ".call" do
     before(:each) do
-      @url = stub("URL")
-      VkontakteApi::API.stub(:url_for).and_return(@url)
-      
-      @connection = stub("Faraday connection")
-      Faraday.stub(:new).and_return(@connection)
-      
-      body = stub("Response body")
-      response = stub("Response", :body => body)
-      @connection.stub(:get).and_return(response)
-      
-      @result = stub("Result")
-      @result.stub(:has_key?) { |key| key == 'response' }
-      
-      @result_response  = stub("Result[response]")
-      @result_error     = stub("Result[error]").as_null_object
-      
-      @result.stub(:[]) do |key|
-        if key == :response
-          @result_response
-        else
-          @result_error
-        end
-      end
-      
-      Yajl::Parser.stub(:parse).and_return(@result)
-    end
-    
-    it "calls the url from .url_for" do
-      @connection.should_receive(:get).with(@url)
-      VkontakteApi::API.call('apiMethod')
+      create_connection
     end
     
-    context "with a successful response" do
-      it "returns the response body" do
-        VkontakteApi::API.call('apiMethod').should == @result_response
+    context "called with a token parameter" do
+      it "sends it to .connection" do
+        subject.should_receive(:connection).with(:url => VkontakteApi::API::URL_PREFIX, :token => 'token')
+        subject.call('apiMethod', {:some => :params}, 'token')
       end
     end
     
-    context "with an error response" do
-      before(:each) do
-        @result.stub(:has_key?) { |key| key != 'response' }
-      end
-      
-      it "raises a VkontakteApi::Error" do
-        expect {
-          VkontakteApi::API.call('apiMethod')
-        }.to raise_error(VkontakteApi::Error)
-      end
+    it "returns the response body" do
+      subject.call('apiMethod').should == @result
     end
   end
   
-  describe ".url_for" do
-    it "constructs a valid VK API url" do
-      url = VkontakteApi::API.send(:url_for, @method_name, @args)
-      url.should == '/method/apiMethod?access_token=some_token&field=value'
+  describe ".connection" do
+    it "uses the :url parameter" do
+      url = stub("URL")
+      Faraday.should_receive(:new).with(url)
+      connection = subject.connection(:url => url)
+    end
+    
+    context "without a token" do
+      it "creates a connection without an oauth2 middleware" do
+        connection = subject.connection
+        connection.builder.handlers.map(&:name).should_not include('FaradayMiddleware::OAuth2')
+      end
     end
     
-    context "with an array argument" do
+    context "with a token" do
       before(:each) do
-        @args_with_array = @args.merge(:array_arg => [1, 2, 3])
+        @token = stub("Token")
       end
       
-      it "concats it with a comma" do
-        url = VkontakteApi::API.send(:url_for, @method_name, @args_with_array)
-        url.should == "/method/apiMethod?access_token=some_token&array_arg=#{CGI.escape('1,2,3')}&field=value"
+      it "creates a connection with an oauth2 middleware" do
+        connection = subject.connection(:token => @token)
+        handler = connection.builder.handlers.first
+        handler.name.should == 'FaradayMiddleware::OAuth2'
+        handler.instance_variable_get(:@args).should == [@token]
       end
     end
   end