vkontakte_api 1.0.4 → 1.1

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.1 (18.12.2012)
+
+* Передача `redirect_uri` при получении токена
+* Методы для работы с правами и сроком жизни токена
+* Логгирование тела POST-запроса
+* POST-запросы по умолчанию
+
 ## 1.0.4 (22.09.2012)
 
 * Пространство имен `orders`

data/Guardfile

@@ -0,0 +1,7 @@
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end
+
+notification :terminal_notifier, activate: 'com.googlecode.iTerm2'

data/README.md

@@ -136,6 +136,41 @@ VkontakteApi.authorization_url(type: :client, scope: [:friends, :photos])
 @vk = VkontakteApi.authorize(type: :app_server)
 ```
 
+### Прочее
+
+Если клиент API (объект класса `VkontakteApi::Client`) был создан с помощью метода `VkontakteApi.authorize`, он будет содержать информацию об id текущего пользователя (`user_id`) и о времени истечения токена (`expires_at`). Получить их можно с помощью соответствующих методов:
+
+``` ruby
+vk = VkontakteApi.authorize(code: 'c1493e81f69fce1b43')
+# => #<VkontakteApi::Client:0x007fa578f00ad0>
+vk.user_id    # => 628985
+vk.expires_at # => 2012-12-18 23:22:55 +0400
+# можно проверить, истекло ли время жизни токена
+vk.expired?   # => false
+```
+
+Также можно получить список прав доступа, которые дает данный токен, в виде, аналогичном формату параметра `scope` в авторизации:
+
+``` ruby
+vk.scope # => [:friends, :groups]
+```
+
+Это работает на основе метода `getUserSettings`, причем результат запоминается после первого обращения.
+
+Чтобы создать короткий синоним `VK` для модуля `VkontakteApi`, достаточно вызвать метод `VkontakteApi.register_alias`:
+
+``` ruby
+VkontakteApi.register_alias
+VK::Client.new # => #<VkontakteApi::Client:0x007fa578d6d948>
+```
+
+При необходимости можно удалить синоним методом `VkontakteApi.unregister_alias`:
+
+``` ruby
+VK.unregister_alias
+VK # => NameError: uninitialized constant VK
+```
+
 ### Обработка ошибок
 
 Если ВКонтакте API возвращает ошибку, выбрасывается исключение класса `VkontakteApi::Error`.
@@ -179,7 +214,7 @@ VkontakteApi.configure do |config|
   # faraday-адаптер для сетевых запросов
   config.adapter = :net_http
   # HTTP-метод для вызова методов API (:get или :post)
-  config.http_verb = :get
+  config.http_verb = :post
   # параметры для faraday-соединения
   config.faraday_options = {
     ssl: {
@@ -198,14 +233,11 @@ VkontakteApi.configure do |config|
   config.log_errors    = true  # ошибки
   config.log_responses = false # удачные ответы
 end
-
-# создание короткого алиаса VK для модуля VkontakteApi
-VkontakteApi.register_alias
 ```
 
 По умолчанию для HTTP-запросов используется `Net::HTTP`; можно выбрать [любой другой адаптер](https://github.com/technoweenie/faraday/blob/master/lib/faraday/adapter.rb), поддерживаемый `faraday`.
 
-ВКонтакте [позволяет](http://vk.com/developers.php?oid=-1&p=%D0%92%D1%8B%D0%BF%D0%BE%D0%BB%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5_%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%BE%D0%B2_%D0%BA_API) использовать как `GET`-, так и `POST`-запросы при вызове методов API. По умолчанию `vkontakte_api` использует `GET`, но в настройке `http_verb` можно указать `:post`, чтобы совершать `POST`-запросы.
+ВКонтакте [позволяет](http://vk.com/developers.php?oid=-1&p=%D0%92%D1%8B%D0%BF%D0%BE%D0%BB%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5_%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%BE%D0%B2_%D0%BA_API) использовать как `GET`-, так и `POST`-запросы при вызове методов API. По умолчанию `vkontakte_api` использует `POST`, но в настройке `http_verb` можно указать `:get`, чтобы совершать `GET`-запросы.
 
 При необходимости можно указать параметры для faraday-соединения - например, параметры прокси-сервера или путь к SSL-сертификатам.
 
@@ -225,7 +257,8 @@ $ rails generate vkontakte_api:install
 ## Roadmap
 
 * метод, возвращающий права текущего токена в читабельной форме (используя `getUserSettings` и кэшируя результат)
-* сохранение параметра `expires_in` токена в объекте `VkontakteApi::Client` после авторизации через `VkontakteApi.authorize`
+* сохранение параметра `expires_at` токена в объекте `VkontakteApi::Client` после авторизации через `VkontakteApi.authorize`
+* метод `VkontakteApi::Client#offline?`, проверяющий, является ли токен бесконечным, используя значение `VkontakteApi::Client#expires_at`
 * `POST`-запросы по умолчанию
 * логгирование тела `POST`-запроса
 

data/lib/vkontakte_api/authorization.rb

@@ -45,12 +45,14 @@ module VkontakteApi
     def authorize(options = {})
       type = options.delete(:type) || :site
       
+      options[:redirect_uri] ||= VkontakteApi.redirect_uri
+      
       case type
       when :site
         code  = options.delete(:code)
-        token = client.auth_code.get_token(code)
+        token = client.auth_code.get_token(code, options)
       when :app_server
-        token = client.client_credentials.get_token({}, OPTIONS[:client_credentials])
+        token = client.client_credentials.get_token(options, OPTIONS[:client_credentials].dup)
       else
         raise ArgumentError, "Unknown authorization type #{type.inspect}"
       end

data/lib/vkontakte_api/client.rb

@@ -3,22 +3,48 @@ module VkontakteApi
   class Client
     include Resolver
     
+    # Access rights and their respective number representation.
+    SCOPE = {
+      :notify         => 1,
+      :friends        => 2,
+      :photos         => 4,
+      :audio          => 8,
+      :video          => 16,
+      :offers         => 32,
+      :questions      => 64,
+      :pages          => 128,
+      :status         => 1024,
+      :notes          => 2048,
+      :messages       => 4096,
+      :wall           => 8192,
+      :ads            => 32768,
+      :docs           => 131072,
+      :groups         => 262144,
+      :notifications  => 524288,
+      :stats          => 1048576
+    }
+    
     # An access token needed by authorized requests.
     # @return [String]
     attr_reader :token
     # Current user id.
     # @return [Integer]
     attr_reader :user_id
+    # Token expiration time
+    # @return [Time]
+    attr_reader :expires_at
     
     # A new API client.
     # If given an `OAuth2::AccessToken` instance, it extracts and keeps
-    # the token string and the user id; otherwise it just stores the given token.
+    # the token string, the user id and the expiration time;
+    # otherwise it just stores the given token.
     # @param [String, OAuth2::AccessToken] token An access token.
     def initialize(token = nil)
       if token.respond_to?(:token) && token.respond_to?(:params)
         # token is an OAuth2::AccessToken
-        @token   = token.token
-        @user_id = token.params['user_id']
+        @token      = token.token
+        @user_id    = token.params['user_id']
+        @expires_at = Time.at(token.expires_at) unless token.expires_at.nil?
       else
         # token is a String or nil
         @token = token
@@ -29,5 +55,23 @@ module VkontakteApi
     def authorized?
       !@token.nil?
     end
+    
+    # Did the token already expire.
+    def expired?
+      @expires_at && @expires_at < Time.now
+    end
+    
+    # Access rights of this token.
+    # @return [Array] An array of symbols representing the access rights.
+    def scope
+      SCOPE.reject do |access_scope, mask|
+        (settings & mask).zero?
+      end.keys
+    end
+    
+  private
+    def settings
+      @settings ||= self.get_user_settings
+    end
   end
 end

data/lib/vkontakte_api/configuration.rb

@@ -29,7 +29,7 @@ module VkontakteApi
     DEFAULT_ADAPTER = Faraday.default_adapter
     
     # Default HTTP verb for API methods.
-    DEFAULT_HTTP_VERB = :get
+    DEFAULT_HTTP_VERB = :post
     
     # Logger default options.
     DEFAULT_LOGGER_OPTIONS = {

data/lib/vkontakte_api/logger.rb

@@ -15,6 +15,7 @@ module VkontakteApi
     def call(env)
       if VkontakteApi.log_requests?
         @logger.debug "#{env[:method].to_s.upcase} #{env[:url].to_s}"
+        @logger.debug "body: #{env[:body].inspect}" unless env[:method] == :get
       end
       
       super

data/lib/vkontakte_api/version.rb

@@ -1,4 +1,4 @@
 module VkontakteApi
   # Library version.
-  VERSION = '1.0.4'
+  VERSION = '1.1'
 end

data/spec/vkontakte_api/api_spec.rb

@@ -8,7 +8,7 @@ describe VkontakteApi::API do
       builder.response :mashify
       builder.response :oj, :preserve_raw => true
       builder.adapter  :test do |stub|
-        stub.get('/apiMethod') do
+        stub.post('/apiMethod') do
           [200, {}, Oj.dump(@result)]
         end
       end

data/spec/vkontakte_api/authorization_spec.rb

@@ -13,8 +13,8 @@ describe VkontakteApi::Authorization do
     @token = stub("Token")
     
     @auth_code          = stub("Authorization code strategy", :get_token => @token, :authorize_url => @url)
-    @implicit           = stub("Implicit strategy",            :authorize_url => @url)
-    @client_credentials = stub("Client credentials strategy",  :get_token => @token)
+    @implicit           = stub("Implicit strategy",           :authorize_url => @url)
+    @client_credentials = stub("Client credentials strategy", :get_token => @token)
     
     @client = stub("OAuth2::Client instance", :auth_code => @auth_code, :implicit => @implicit, :client_credentials => @client_credentials)
     OAuth2::Client.stub(:new).and_return(@client)
@@ -70,14 +70,14 @@ describe VkontakteApi::Authorization do
       end
       
       it "gets the token" do
-        @auth_code.should_receive(:get_token).with(@code)
+        @auth_code.should_receive(:get_token).with(@code, {:redirect_uri => @redirect_uri})
         @auth.authorize(:type => :site, :code => @code)
       end
     end
     
     context "with an app_server type" do
       it "gets the token" do
-        @client_credentials.should_receive(:get_token).with({}, subject::OPTIONS[:client_credentials])
+        @client_credentials.should_receive(:get_token).with({:redirect_uri => @redirect_uri}, subject::OPTIONS[:client_credentials])
         @auth.authorize(:type => :app_server)
       end
     end

data/spec/vkontakte_api/client_spec.rb

@@ -4,7 +4,12 @@ describe VkontakteApi::Client do
   before(:each) do
     @user_id      = stub("User id")
     @string_token = stub("Access token as a String")
-    @oauth2_token = stub("Access token as an OAuth2::AccessToken", :token => @string_token, :params => {'user_id' => @user_id})
+    @expires_at   = Time.now - 2 * 60 * 60 # 2.hours.ago
+    
+    @oauth2_token = stub("Access token as an OAuth2::AccessToken")
+    @oauth2_token.stub(:token).and_return(@string_token)
+    @oauth2_token.stub(:params).and_return('user_id' => @user_id)
+    @oauth2_token.stub(:expires_at).and_return(@expires_at)
   end
   
   describe "#initialize" do
@@ -28,6 +33,9 @@ describe VkontakteApi::Client do
           client = VkontakteApi::Client.new(@oauth2_token)
           client.token.should == @string_token
           client.user_id.should == @user_id
+          
+          client.expires_at.should be_a(Time)
+          client.expires_at.should be < Time.now
         end
       end
     end
@@ -46,4 +54,62 @@ describe VkontakteApi::Client do
       end
     end
   end
+  
+  describe "#expired?" do
+    context "with an expired token" do
+      before(:each) do
+        @client = VkontakteApi::Client.new(@oauth2_token)
+      end
+      
+      it "returns true" do
+        @client.should be_expired
+      end
+    end
+    
+    context "with an actual token" do
+      before(:each) do
+        @oauth2_token.stub(:expires_at).and_return(Time.now + 2 * 24 * 60 * 60) # 2.days.from_now
+        @client = VkontakteApi::Client.new(@oauth2_token)
+      end
+      
+      it "returns false" do
+        @client.should_not be_expired
+      end
+    end
+    
+    context "with a String token" do
+      before(:each) do
+        @client = VkontakteApi::Client.new(@string_token)
+      end
+      
+      it "returns false" do
+        @client.should_not be_expired
+      end
+    end
+  end
+  
+  describe "#scope" do
+    before(:each) do
+      @client = VkontakteApi::Client.new
+      @client.stub(:get_user_settings).and_return(865310)
+    end
+    
+    it "returns an array of access rights" do
+      scopes_array = @client.scope
+      
+      [
+        :friends,
+        :photos,
+        :audio,
+        :video,
+        :status,
+        :messages,
+        :wall,
+        :groups,
+        :notifications
+      ].each do |access_scope|
+        scopes_array.should include(access_scope)
+      end
+    end
+  end
 end

data/spec/vkontakte_api/logger_spec.rb

@@ -6,6 +6,7 @@ describe VkontakteApi::Logger do
     @fail_response    = Oj.dump('error' => 404)
     
     @connection = Faraday.new(:url => 'http://example.com') do |builder|
+      builder.request  :url_encoded
       builder.response :vk_logger
       builder.response :mashify
       builder.response :oj, :preserve_raw => true
@@ -14,6 +15,9 @@ describe VkontakteApi::Logger do
         stub.get('/success') do
           [200, {}, @success_response]
         end
+        stub.post('/success') do
+          [200, {}, @success_response]
+        end
         stub.get('/fail') do
           [200, {}, @fail_response]
         end
@@ -33,10 +37,18 @@ describe VkontakteApi::Logger do
       VkontakteApi.log_requests = true
     end
     
-    it "logs the request" do
+    it "logs the request URL" do
       @logger.should_receive(:debug).with('GET http://example.com/success')
       @connection.get('/success')
     end
+    
+    context "with a POST request" do
+      it "logs the request URL and the request body" do
+        @logger.should_receive(:debug).with('POST http://example.com/success')
+        @logger.should_receive(:debug).with('body: "param=1"')
+        @connection.post('/success', :param => 1)
+      end
+    end
   end
   
   context "without VkontakteApi.log_requests?" do

data/vkontakte_api.gemspec

@@ -24,6 +24,9 @@ Gem::Specification.new do |s|
   
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rb-fsevent', '~> 0.9.1'
+  s.add_development_dependency 'terminal-notifier-guard'
   s.add_development_dependency 'pry'
   s.add_development_dependency 'awesome_print'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vkontakte_api
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-21 00:00:00.000000000 Z
+date: 2012-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -123,6 +123,54 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: terminal-notifier-guard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -170,6 +218,7 @@ files:
 - .yardopts
 - CHANGELOG.md
 - Gemfile
+- Guardfile
 - MIT-LICENSE
 - README.md
 - Rakefile