Merge pull request #19 from braiden-vasco/development

Version 1.0.0

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## [v1.0.0](https://github.com/braiden-vasco/lita-vkontakte/tree/v1.0.0) (2015-06-18)
+
+[Full Changelog](https://github.com/braiden-vasco/lita-vkontakte/compare/v0.1.0...v1.0.0)
+
+**Merged pull requests:**
+
+- Rename configuration fields [\#18](https://github.com/braiden-vasco/lita-vkontakte/pull/18) ([braiden-vasco](https://github.com/braiden-vasco))
+
+- Basic testing [\#17](https://github.com/braiden-vasco/lita-vkontakte/pull/17) ([braiden-vasco](https://github.com/braiden-vasco))
+
+- Add code documentation [\#16](https://github.com/braiden-vasco/lita-vkontakte/pull/16) ([braiden-vasco](https://github.com/braiden-vasco))
+
+- Add instructions [\#15](https://github.com/braiden-vasco/lita-vkontakte/pull/15) ([braiden-vasco](https://github.com/braiden-vasco))
+
+- Fix changelog generator [\#14](https://github.com/braiden-vasco/lita-vkontakte/pull/14) ([braiden-vasco](https://github.com/braiden-vasco))
+
 ## [v0.1.0](https://github.com/braiden-vasco/lita-vkontakte/tree/v0.1.0) (2015-06-17)
 
 **Merged pull requests:**
@@ -28,4 +44,4 @@
 
 
 
-\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

README.md

@@ -5,4 +5,63 @@ Lita::Adapters::Vkontakte
 [![Build Status](https://travis-ci.org/braiden-vasco/lita-vkontakte.svg)](https://travis-ci.org/braiden-vasco/lita-vkontakte)
 [![Coverage Status](https://coveralls.io/repos/braiden-vasco/lita-vkontakte/badge.svg)](https://coveralls.io/r/braiden-vasco/lita-vkontakte)
 
-VKontakte adapter for the Lita chat bot
+[VKontakte](https://vk.com) adapter for the [Lita](https://lita.io) chat bot.
+
+Usage
+-----
+
+At first, see the documentation for Lita: https://docs.lita.io/
+
+### Installation
+
+Add **lita-vkontakte** to your Lita instance's Gemfile:
+
+```ruby
+gem 'lita-vkontakte', '~> 1.0.0'
+```
+
+### Preparation
+
+Go to https://vk.com/editapp?act=create and create standalone application.
+Then go to application settings page and look at application ID and secure key.
+
+Open the Ruby console (for example with `irb` command) and type the following
+(replace `LITA_VK_APP_ID` with your application ID):
+
+```ruby
+require 'vkontakte_api'
+
+VkontakteApi.app_id = 'LITA_VK_APP_ID'
+VkontakteApi.redirect_uri = 'https://oauth.vk.com/blank.html'
+
+puts VkontakteApi.authorization_url(type: :client, scope: [:offline, :messages])
+```
+
+You will see a link. Open it in browser where you are authorized in VKontakte
+as your future chat bot's user. You will be redirected to some address.
+We need a parameter `access_token` from this URL.
+
+### Configuration
+
+#### Required attributes
+
+- `app_id` (String) - An ID of your application
+- `app_secret` (String) - A secure key of your application
+- `access_token` (String) - An acces token from URL
+
+#### Example
+
+This is an example `lita_config.rb` file:
+
+```ruby
+Lita.configure do |config|
+  config.robot.name = 'Lita'
+  config.robot.mention_name = 'lita'
+
+  config.robot.adapter = :vkontakte
+
+  config.adapters.vkontakte.app_id     = '2849670'
+  config.adapters.vkontakte.app_secret = 'EtgJI2yFJ0GYzgDLSS8e'
+  config.adapters.vkontakte.access_token  = '51jeIbjmmxJvKo7TTaW0Ext4cx6ajonDIbEkSjFofh7boyxH27JcjKXMODwZTaOxLA1bQbRyY0CEUM2TrXGK6'
+end
+```

Rakefile

@@ -5,6 +5,8 @@ gemspec = Gem::Specification.load('lita-vkontakte.gemspec')
 github_user, github_project =
   gemspec.homepage.scan(%r{^https://github\.com/([^/]+)/([^/]+)/?$})[0]
 
+DEFAULT_EXCLUDE_LABELS = 'duplicate,question,invalid,wontfix'
+
 require 'bundler/gem_tasks'
 
 task default: [:spec, :lint]
@@ -26,7 +28,7 @@ task :changelog, [:token] do |_t, args|
   cmd << " -u #{github_user}"
   cmd << " -p #{github_project}"
   cmd << " -t #{args[:token]}" if args[:token]
-  cmd << ' --exclude-tags version'
+  cmd << " --exclude-labels version,#{DEFAULT_EXCLUDE_LABELS}"
 
   sh cmd
 end

lib/lita/adapters/vkontakte.rb

@@ -14,27 +14,38 @@ module Adapters
     # VKontakte adapter for the Lita chat bot.
     #
     class Vkontakte < Adapter
+      config :app_id,       type: String, required: true
+      config :app_secret,   type: String, required: true
+      config :access_token, type: String, required: true
+
+      # Used version of VKontakte API.
+      # {https://vk.com/dev/versions}
       API_VERSION = '5.34'
 
+      # Needed for VKontakte authentication.
       REDIRECT_URI = 'https:/oauth.vk.com/blank.html'
 
-      config :client_id,     type: String, required: true
-      config :client_secret, type: String, required: true
-      config :access_token,  type: String, required: true
-
+      # Connects to VKontakte API.
+      #
+      # @param robot [Lita::Robot] The currently running robot.
+      #
       def initialize(robot)
         super
 
         VkontakteApi.configure do |vk|
-          vk.app_id       = config.client_id
-          vk.app_secret   = config.client_secret
+          vk.app_id       = config.app_id
+          vk.app_secret   = config.app_secret
           vk.redirect_uri = REDIRECT_URI
           vk.api_version  = API_VERSION
         end
 
         @vk = VkontakteApi::Client.new(config.access_token)
       end
 
+      # The main loop. Listens for incoming messages,
+      # creates {Lita::Message} objects from them,
+      # and dispatches them to the robot.
+      #
       def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         robot.trigger(:connected)
 
@@ -62,6 +73,11 @@ def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         robot.trigger(:disconnected)
       end
 
+      # Sends one or more messages to a user or room.
+      #
+      # @param target [Lita::Source] The user or room to send messages to.
+      # @param messages [Array<String>] An array of messages to send.
+      #
       def send_messages(target, messages)
         messages.reject(&:empty?).each do |message|
           send_message(target, message)
@@ -70,19 +86,38 @@ def send_messages(target, messages)
 
       protected
 
+      # Handlers for events of VKontakte long poll server.
+      # {https://vk.com/dev/using_longpoll}
       HANDLERS = {
         4 => :get_message,
       }
 
+      # Handle event of VKontakte long poll server.
+      # {https://vk.com/dev/using_longpoll}
+      #
+      # @param a [List] Event arguments.
+      #
       def update(a)
         code = a[0]
         data = a[1..-1]
 
         method(HANDLERS[code]).call(*data) if HANDLERS[code]
       end
 
-      def get_message(_msg_id, flags, # rubocop:disable Metrics/ParameterLists
-                      from_id, _timestamp, subject, text, _attachments)
+      # Handle new message
+      # {https://vk.com/dev/using_longpoll}
+      #
+      # @param message_id [Integer] Message ID.
+      # @param flags [Integer] Message flags.
+      # @param from_id [Integer] ID of user who sent this message.
+      # @param timestamp [Integer] Message time in UNIX format.
+      # @param subject [String] Chat theme (" ... " for private messages).
+      # @param text [String] Message text.
+      # @param attachments [Hashie::Mash] Message attachments.
+      #
+      def get_message( # rubocop:disable Metrics/ParameterLists
+        _message_id, flags, from_id, _timestamp, subject, text, _attachments
+      )
         is_private = subject.start_with?(' ')
         is_own = flags & 2 != 0
 
@@ -96,6 +131,11 @@ def get_message(_msg_id, flags, # rubocop:disable Metrics/ParameterLists
         robot.receive(message)
       end
 
+      # Sends one message to a user or room.
+      #
+      # @param target [Lita::Source] The user or room to send message to.
+      # @param messages [String] Messages to send.
+      #
       def send_message(target, message) # rubocop:disable Metrics/AbcSize
         is_private = target.room.start_with?(' ')
 

lita-vkontakte.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = 'lita-vkontakte'
-  spec.version       = '0.1.0'
+  spec.version       = '1.0.0'
   spec.authors       = ['Braiden Vasco']
   spec.email         = ['braiden-vasco@mailtor.net']
 

spec/lita/adapters/vkontakte_spec.rb

@@ -1,2 +1,35 @@
 describe Lita::Adapters::Vkontakte, lita: true do
+  subject { described_class.new(robot) }
+
+  let(:robot) { Lita::Robot.new(registry) }
+
+  before do
+    registry.register_adapter(:vkontakte, described_class)
+
+    registry.configure do |config|
+      config.adapters.vkontakte.app_id       = app_id
+      config.adapters.vkontakte.app_secret   = app_secret
+      config.adapters.vkontakte.access_token = access_token
+    end
+  end
+
+  let(:app_id)       { ENV['LITA_VK_APP_ID'] }
+  let(:app_secret)   { ENV['LITA_VK_APP_SECRET'] }
+  let(:access_token) { ENV['LITA_VK_ACCESS_TOKEN'] }
+
+  it 'registers Lita adapter "vkontakte"' do
+    expect(Lita.adapters[:vkontakte]).to eq described_class
+  end
+
+  describe '#initialize' do
+    it 'runs successful' do
+      expect { described_class.new(robot) }.to_not raise_error
+    end
+
+    it 'creates VKontakte API client' do
+      expect(
+        described_class.new(robot).instance_variable_get(:@vk)
+      ).to be_instance_of VkontakteApi::Client
+    end
+  end
 end