telphin_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c44141d306d2360eee15812c692ee1a45be00527
+  data.tar.gz: 1a8daf10b99b12993a9c8123af8e0f3cd7809fcd
+SHA512:
+  metadata.gz: 93962713545230f25507ebcc1e5bd7539d969d26e589203c5acbb43699018815d9f51a1018b07a8eec43a3449466b27465b7aed72bec868023660259cdbfbe0f
+  data.tar.gz: 5b0f68ef059f86a7dee318fccfd04e46d783b9cd5f37c906b1c6c8599c42fe6065e2fad416afb327286342651ca791de503789bd0734cc16a930514bad8be049

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+tmp/*
+.yardoc/*
+.idea
+spec/support/credentials.yml
+doc/
+*.iml

data/.rspec

@@ -0,0 +1 @@
+--color --format=documentation

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1
+  - 2.2
+  - ruby-head
+  - jruby-19mode
+  - jruby-9.0.0.0
+  - jruby-head
+
+jdk:
+  - oraclejdk8
+  
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/.yardopts

@@ -0,0 +1,3 @@
+--files README.md,CHANGELOG.md
+--markup markdown
+--markup-provider redcarpet

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,14 @@
+guard 'rspec', all_on_start: true, all_after_pass: true, cmd: 'bin/rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+  
+  watch('spec/support/mechanized_authorization.rb') { 'spec/integration_spec.rb' }
+end
+
+
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+end unless defined?(JRUBY_VERSION)
+
+notification :terminal_notifier, activate: 'com.googlecode.iTerm2'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Konstantin Tyutyunnikov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+## telphin_api [![Build Status](https://secure.travis-ci.org/rootooz/telphin_api.png)](http://travis-ci.org/rootooz/telphin_api) [![Gem Version](https://badge.fury.io/rb/telphin_api.png)](http://badge.fury.io/rb/telphin_api) [![Dependency Status](https://gemnasium.com/7even/telphin_api.png)](https://gemnasium.com/7even/telphin_api) [![Code Climate](https://codeclimate.com/github/7even/telphin_api.png)](https://codeclimate.com/github/7even/telphin_api)
+
+`telphin_api` — ruby-адаптер для Телфин. Он позволяет вызывать методы API, а также поддерживает получение токена для работы с API.
+
+## Установка
+
+``` ruby
+# Gemfile
+gem 'telphin_api'
+```
+
+или просто
+
+``` sh
+$ gem install telphin_api
+```
+
+## Использование
+
+### Вызов методов
+
+``` ruby
+# создаем клиент
+@tph = TelphinApi::Client.new
+# и вызываем методы API
+@tph.extensions.phone_call_events(:user_id => '@me', :extension_number => '00000*101', :method => :get)
+
+# в ruby принято использовать snake_case в названиях методов,
+# поэтому extensions.phoneCallEvents становится extensions.phone_call_events
+@tph.extensions.phone_call_events
+
+# большинство методов возвращает структуры Hashie::Mash
+# и массивы из них
+call_events.first.id        # => bMf0iCJneuA0YWawjUOjVTzAGn
+call_events.first.url       # => https://site/api/telphin/call/out
+call_events.first.method    # => 0
+call_events.first.status    # => 1
+call_events.first.type      # => 1
+
+# если метод, возвращающий массив, вызывается с блоком,
+# то блок будет выполнен для каждого элемента,
+# и метод вернет обработанный массив
+@tph.extensions.phone_call_events(:user_id => '@me', :extension_number => '00000*101', :method => :get) do |event|
+  "#{event.id} '#{event.url}' #{event.method}"
+end
+# => ["bMf0iCJneuA0YWawjUOjVTzAGn 'https://site/api/telphin/call/out' 0"]
+```
+
+### Авторизация
+
+Для авторизации необходимо задать параметры `app_key` (Ключ клиента), `app_secret` (Секрет клиента) и `site` (адрес вашего API сервера, полученного при заключении договора) в настройках `TelphinApi.configure`. Более подробно о конфигурировании `telphin_api` см. далее в соответствующем разделе.
+
+`telphin_api` предоставляет метод `TelphinApi.authorize`, который делает запрос к Телфин, получает токен и создает клиент:
+
+``` ruby
+@tph = TelphinApi.authorize
+# и теперь можно вызывать методы API на объекте @tph
+@tph.token
+```
+
+Клиент будет содержать token пользователя, авторизовавшего приложение
+Также в этот момент полезно сохранить полученный токен в БД либо в сессии, чтобы использовать их повторно:
+
+``` ruby
+current_user.token = @vk.token
+current_user.save
+# позже
+@tph = TelphinApi::Client.new(current_user.token)
+```
+
+### Прочее
+
+Если клиент API (объект класса `TelphinApi::Client`) был создан с помощью метода `TelphinApi.authorize`, он будет содержать информацию о времени истечения токена (`expires_at`). Получить их можно с помощью соответствующих методов:
+
+``` ruby
+@tph = TelphinApi.authorize
+# => #<TelphinApi::Client:0x007fa578f00ad0>
+tph.expires_at # => 2015-12-18 23:22:55 +0400
+# можно проверить, истекло ли время жизни токена
+tph.expired?   # => false
+```
+
+Чтобы создать короткий синоним `TPH` для модуля `TelphinApi`, достаточно вызвать метод `TelphinApi.register_alias`:
+
+``` ruby
+TelphinApi.register_alias
+TPH::Client.new # => #<TelphinApi::Client:0x007fa578d6d948>
+```
+
+При необходимости можно удалить синоним методом `TelphinApi.unregister_alias`:
+
+``` ruby
+TPH.unregister_alias
+TPH # => NameError: uninitialized constant VK
+```
+
+### Обработка ошибок
+
+Если Телфин API возвращает ошибку, выбрасывается исключение класса `TelphinApi::Error`.
+
+``` ruby
+tph = TPH::Client.new
+@tph.extensions.phone_call_events
+# TelphinApi::Error: Telphin returned an error extension_invalid: 'Value supplied in the URI-Fragment as extension is invalid. The parameter must reference the number of an existing extension and cannot be set to @self.'
+```
+
+### Логгирование
+
+`telphin_api` логгирует служебную информацию о запросах при вызове методов.
+По умолчанию все пишется в `STDOUT`, но в настройке можно указать
+любой другой совместимый логгер, например `Rails.logger`.
+
+Есть возможность логгирования 3 типов информации,
+каждому соответствует ключ в глобальных настройках.
+
+|                        | ключ настройки  | по умолчанию | уровень логгирования |
+| ---------------------- | --------------- | ------------ | -------------------- |
+| URL запроса            | `log_requests`  | `true`       | `debug`              |
+| JSON ответа при ошибке | `log_errors`    | `true`       | `warn`               |
+| JSON удачного ответа   | `log_responses` | `false`      | `debug`              |
+
+Таким образом, в rails-приложении с настройками по умолчанию в production
+записываются только ответы сервера при ошибках;
+в development также логгируются URL-ы запросов.
+
+
+## Настройка
+
+Глобальные параметры `telphin_api` задаются в блоке `TelphinApi.configure` следующим образом:
+
+``` ruby
+TelphinApi.configure do |config|
+  # параметры, необходимые для авторизации средствами telphin_api
+  # (не нужны при использовании сторонней авторизации)
+  config.app_key      = '123'
+  config.app_secret   = 'AbCdE654'
+  config.site         = 'https://pbx.telphin.ru/uapi' # По умолчанию https://pbx.telphin.ru/uapi
+  
+  # faraday-адаптер для сетевых запросов
+  config.adapter = :net_http
+  
+  # параметры для faraday-соединения
+  config.faraday_options = {
+    ssl: {
+      ca_path:  '/usr/lib/ssl/certs'
+    },
+    proxy: {
+      uri:      'http://proxy.example.com',
+      user:     'foo',
+      password: 'bar'
+    }
+  }
+  # максимальное количество повторов запроса при ошибках
+  config.max_retries = 2
+  
+  # логгер
+  config.logger        = Rails.logger
+  config.log_requests  = true  # URL-ы запросов
+  config.log_errors    = true  # ошибки
+  config.log_responses = false # удачные ответы
+end
+```
+
+По умолчанию для HTTP-запросов используется `Net::HTTP`; можно выбрать
+[любой другой адаптер](https://github.com/technoweenie/faraday/blob/master/lib/faraday/adapter.rb),
+поддерживаемый `faraday`.
+
+При необходимости можно указать параметры для faraday-соединения &mdash; например,
+параметры прокси-сервера или путь к SSL-сертификатам.
+
+Чтобы сгенерировать файл с настройками по умолчанию в rails-приложении,
+можно воспользоваться генератором `telphin_api:install`:
+
+``` sh
+$ cd /path/to/app
+$ rails generate telphin_api:install
+```
+
+## JSON-парсер
+
+`telphin_api` использует парсер [Oj](https://github.com/ohler55/oj)
+
+Также в библиотеке `multi_json` (обертка для различных JSON-парсеров,
+которая выбирает самый быстрый из установленных в системе и парсит им)
+`Oj` поддерживается и имеет наивысший приоритет; поэтому если он установлен
+в системе, `multi_json` будет использовать именно его.
+
+## Участие в разработке
+
+Если вы хотите поучаствовать в разработке проекта, форкните репозиторий,
+положите свои изменения в отдельную ветку, покройте их спеками
+и отправьте мне pull request.
+
+`telphin_api` тестируется под MRI `2.1.2`.
+Если что-то работает неправильно, либо вообще не работает,
+то это следует считать багом, и написать об этом
+в [issues на Github](https://github.com/rootooz/telphin_api/issues).

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/gem_tasks'
+
+desc 'Fires up the console with preloaded telphin_api'
+task :console do
+  sh 'pry -I ./lib -r ./lib/telphin_api'
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = '--color --format doc'
+end
+
+task default: :spec

data/bin/rspec

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= Pathname.new(__FILE__).expand_path.join('../../Gemfile').to_s
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/example/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'sinatra'
+gem 'sinatra-reloader'
+gem 'telphin_api', :path => '../'
+
+

data/example/app.rb

@@ -0,0 +1,23 @@
+require 'bundler/setup'
+require 'sinatra'
+require 'telphin_api'
+
+class OmniTelphinDemo < Sinatra::Base
+  use Rack::Session::Cookie
+
+  TelphinApi.configure do |config|
+    # Authorization parameters (not needed when using an external authorization):
+    config.app_key      = 'F~PUJXc8X5_2vUy7W5B~IBjXm6Hv~dRT'
+    config.app_secret   = 'x~X1r206MB~ckpYhb6c.W4ch4OLx_9If'
+  end
+
+  get '/' do
+    @tph = TelphinApi.authorize
+    ar = @tph.extensions.phone_call_events(:user_id => '@me', :extension_number => '17608s*101', :method => :get)
+
+    abort ar.inspect
+  end
+
+end
+
+OmniTelphinDemo.run!

data/lib/generators/telphin_api/install/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Create a telphin_api config file in config/initializers/telphin_api.rb.

data/lib/generators/telphin_api/install/install_generator.rb

@@ -0,0 +1,10 @@
+# A rails generator `telphin_api:install`.
+# It creates a config file in `config/initializers/telphin_api.rb`.
+class TelphinApi::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path('../templates', __FILE__)
+  
+  # Creates the config file.
+  def create_initializer
+    copy_file 'initializer.rb', 'config/initializers/telphin_api.rb'
+  end
+end

data/lib/generators/telphin_api/install/templates/initializer.rb

@@ -0,0 +1,25 @@
+TelphinApi.configure do |config|
+  # Authorization parameters (not needed when using an external authorization):
+  # config.app_key       = '123'
+  # config.app_secret   = 'AbCdE654'
+  # config.site = 'https://pbx.telphin.ru/uapi'
+  
+  # Faraday adapter to make requests with:
+  # config.adapter = :net_http
+  
+  # Logging parameters:
+  # log everything through the rails logger
+  config.logger = Rails.logger
+  
+  # log requests' URLs
+  # config.log_requests = true
+  
+  # log response JSON after errors
+  # config.log_errors = true
+  
+  # log response JSON after successful responses
+  # config.log_responses = false
+end
+
+# create a short alias TPH for TelphinApi module
+# TelphinApi.register_alias

data/lib/telphin_api.rb

@@ -0,0 +1,39 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'oj' unless defined?(JRUBY_VERSION)
+require 'faraday_middleware/multi_json'
+require 'oauth2'
+require 'yaml'
+require 'hashie'
+
+require 'telphin_api/version'
+require 'telphin_api/error'
+require 'telphin_api/configuration'
+require 'telphin_api/authorization'
+require 'telphin_api/utils'
+require 'telphin_api/api'
+require 'telphin_api/resolver'
+require 'telphin_api/resolvable'
+require 'telphin_api/client'
+require 'telphin_api/namespace'
+require 'telphin_api/method'
+require 'telphin_api/result'
+require 'telphin_api/logger'
+
+# Main module.
+module TelphinApi
+  extend TelphinApi::Configuration
+  extend TelphinApi::Authorization
+
+  class << self
+    # Creates a short alias `TPH` for `TelphinApi` module.
+    def register_alias
+      Object.const_set(:TPH, TelphinApi)
+    end
+    
+    # Removes the `TPH` alias.
+    def unregister_alias
+      Object.send(:remove_const, :TPH) if defined?(TPH)
+    end
+  end
+end

data/lib/telphin_api/api.rb

@@ -0,0 +1,59 @@
+module TelphinApi
+  # A low-level module which handles the requests to Telphin API and returns their results as mashes.
+  #
+  # It uses Faraday with middleware underneath the hood.
+  module API
+    class << self
+      # API method call.
+      # @param [String] full_method A full name of the method.
+      # @param [Hash] args Method arguments.
+      # @param [String] token The access token.
+      # @return [Hashie::Mash] Mashed server response.
+      def call(full_method, args = {}, token = nil)
+        namespace = full_method.first
+        action = full_method.last
+
+        http_method = args.delete(:method)
+        http_method ||= :get
+
+        user_id = args.delete(:user_id)
+        extension_number = args.delete(:extension_number)
+        id = args.delete(:id)
+
+        flat_arguments = Utils.flatten_arguments(args)
+        url = [TelphinApi.site, namespace, user_id, extension_number, action].join('/')
+        url = url + '/' + id unless id.nil?
+        connection = connection(url: url, token: token)
+
+        if flat_arguments.empty?
+          connection.send(http_method).body
+        else
+          connection.send(http_method, flat_arguments).body
+        end
+      end
+
+      # Faraday connection.
+      # @param [Hash] options Connection options.
+      # @option options [String] :url Connection URL (either full or just prefix).
+      # @option options [String] :token OAuth2 access token (not used if omitted).
+      # @return [Faraday::Connection] Created connection.
+      def connection(options = {})
+        url = options.delete(:url)
+        token = options.delete(:token)
+        url = url + '?accessRequestToken=' + token
+
+        Faraday.new(url, TelphinApi.faraday_options) do |builder|
+          builder.request :multipart
+          builder.request :url_encoded
+          builder.request :retry, TelphinApi.max_retries
+
+          builder.response :telphin_logger
+          builder.response :mashify
+          builder.response :multi_json, preserve_raw: true
+
+          builder.adapter TelphinApi.adapter
+        end
+      end
+    end
+  end
+end