telphin_api 1.0.0

data/lib/telphin_api/authorization.rb

@@ -0,0 +1,38 @@
+module TelphinApi
+  # A module containing the methods for authorization.
+  #
+  # @note `TelphinApi::Authorization` extends `TelphinApi` so these methods should be called from the latter.
+  module Authorization
+    # Authorization options.
+    OPTIONS = {
+        client: {
+            token_url: '/oauth/token.php'
+        },
+        client_credentials: {
+            'auth_scheme' => 'request_body'
+        }
+    }
+
+    # Not used for this strategy
+    #
+    # @raise [NotImplementedError]
+    def authorization_url
+      fail(NotImplementedError, 'The authorization endpoint is not used in this strategy')
+    end
+
+    # Authorization (getting the access token and building a `TelphinApi::Client` with it).
+    # @raise [ArgumentError] raises after receiving an unknown authorization type.
+    # @return [TelphinApi::Client] An API client.
+    def authorize(options = {})
+      options[:client_id] ||= TelphinApi.app_key
+      options[:client_secret] ||= TelphinApi.app_secret
+      token = client.client_credentials.get_token(options, OPTIONS[:client_credentials].dup)
+      Client.new(token)
+    end
+
+    private
+    def client
+      @client ||= OAuth2::Client.new(TelphinApi.app_key, TelphinApi.app_secret, {site: TelphinApi.site}.merge(OPTIONS[:client]))
+    end
+  end
+end

data/lib/telphin_api/client.rb

@@ -0,0 +1,75 @@
+module TelphinApi
+  # A class representing a connection to Telphin. It holds the access token.
+  class Client
+    include Resolver
+
+    # Значение маркера доступа. Это значение используется при выполнении запросов к API.
+    # @return [String]
+    attr_reader :token
+
+    # Тип маркера. Допустимо только значение Bearer.
+    # @return [String]
+    attr_reader :token_type
+
+    # Новый маркер, который можно использовать для обновления маркера с истекшим сроком действия.
+    # @return [String]
+    attr_reader :refresh_token
+
+    # Срок действия маркера доступа (в секундах).
+    # @return [Time]
+    attr_reader :expires_in
+
+    # A new API client.
+    # If given an `OAuth2::AccessToken` instance, it extracts and keeps
+    # 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
+        @token_type = token.params['token_type']
+        @refresh_token = token.params['refresh_token']
+        @expires_in = Time.now + token.expires_in unless token.expires_in.nil?
+      else
+        # token is a String or nil
+        @token = token
+      end
+    end
+
+    # Is a `TelphinApi::Client` instance authorized.
+    def authorized?
+      !@token.nil?
+    end
+
+    # Did the token already expire.
+    def expired?
+      @expires_in && @expires_in < Time.now
+    end
+
+    # Called without arguments it returns the `execute` namespace;
+    # called with arguments it calls the top-level `execute` API method.
+    def execute(*args)
+      if args.empty?
+        create_namespace(:execute)
+      else
+        call_method([:execute, *args])
+      end
+    end
+
+    # If the called method is a namespace, it creates and returns a new `TelphinApi::Namespace` instance.
+    # Otherwise it creates a `TelphinApi::Method` instance and calls it passing the arguments and a block.
+    def method_missing(*args, &block)
+      if Namespace.exists?(args.first)
+        create_namespace(args.first)
+      else
+        call_method(args, &block)
+      end
+    end
+
+    private
+    def settings
+      @settings ||= self.get_user_settings
+    end
+  end
+end

data/lib/telphin_api/configuration.rb

@@ -0,0 +1,75 @@
+require 'logger'
+
+module TelphinApi
+  # General configuration module.
+  #
+  # @note `TelphinApi::Configuration` extends `TelphinApi` so these methods should be called from the latter.
+  module Configuration
+    # Available options.
+    OPTION_NAMES = [
+      :app_key,
+      :app_secret,
+      :site,
+      :adapter,
+      :faraday_options,
+      :max_retries,
+      :logger,
+      :log_requests,
+      :log_errors,
+      :log_responses,
+    ]
+    
+    attr_accessor *OPTION_NAMES
+    
+    alias_method :log_requests?,  :log_requests
+    alias_method :log_errors?,    :log_errors
+    alias_method :log_responses?, :log_responses
+    
+    # Default HTTP adapter.
+    DEFAULT_ADAPTER = Faraday.default_adapter
+    
+    # Default HTTP verb for API methods.
+    DEFAULT_HTTP_VERB = :post
+    
+    # Default max retries count.
+    DEFAULT_MAX_RETRIES = 2
+    
+    # Logger default options.
+    DEFAULT_LOGGER_OPTIONS = {
+      requests:  true,
+      errors:    true,
+      responses: false
+    }
+
+    # Default url for site api
+    DEFAULT_URL = 'https://pbx.telphin.ru/uapi'
+    
+    # A global configuration set via the block.
+    # @example
+    #   TelphinApi.configure do |config|
+    #     config.adapter = :net_http
+    #     config.logger  = Rails.logger
+    #   end
+    def configure
+      yield self if block_given?
+      self
+    end
+    
+    # Reset all configuration options to defaults.
+    def reset
+      @site            = DEFAULT_URL
+      @adapter         = DEFAULT_ADAPTER
+      @faraday_options = {}
+      @max_retries     = DEFAULT_MAX_RETRIES
+      @logger          = ::Logger.new(STDOUT)
+      @log_requests    = DEFAULT_LOGGER_OPTIONS[:requests]
+      @log_errors      = DEFAULT_LOGGER_OPTIONS[:errors]
+      @log_responses   = DEFAULT_LOGGER_OPTIONS[:responses]
+    end
+    
+    # When this module is extended, set all configuration options to their default values.
+    def self.extended(base)
+      base.reset
+    end
+  end
+end

data/lib/telphin_api/error.rb

@@ -0,0 +1,21 @@
+module TelphinApi
+  # An exception raised by `TelphinApi::Result` when given a response with an error.
+  class Error < StandardError
+    # An error code.
+    # @return [String]
+    attr_reader :error_code
+
+    # An exception is initialized by the data from response mash.
+    # @param [Hash] data Error data.
+    def initialize(data)
+      @error_code = data.code
+      @error_msg = data.message
+    end
+
+    # A full description of the error.
+    # @return [String]
+    def message
+      "Telphin returned an error #{@error_code}: '#{@error_msg}'"
+    end
+  end
+end

data/lib/telphin_api/logger.rb

@@ -0,0 +1,36 @@
+module TelphinApi
+  # 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 = TelphinApi.logger
+    end
+    
+    # Logs the request if needed.
+    # @param [Hash] env Request data.
+    def call(env)
+      if TelphinApi.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
+    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 TelphinApi.log_errors?
+      else
+        @logger.debug env[:raw_body] if TelphinApi.log_responses?
+      end
+    end
+  end
+  
+  Faraday::Response.register_middleware telphin_logger: Logger
+end

data/lib/telphin_api/method.rb

@@ -0,0 +1,39 @@
+module TelphinApi
+  # 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_method, args, token)
+      Result.process(response, type, block)
+    end
+    
+  private
+    def full_method
+      [@previous_resolver.name, @name].compact.map { |part| camelize(part).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/telphin_api/namespace.rb

@@ -0,0 +1,36 @@
+module TelphinApi
+  # An API method namespace (such as `extensions` or `phone_calls`).
+  #
+  # It includes `Resolvable` and `Resolver` and calls API methods via `Resolver#call_method`.
+  # It also holds the list of all known namespaces.
+  class Namespace
+    include Resolvable
+    include Resolver
+    
+    # Creates and calls the `TelphinApi::Method` using `TelphinApi::Resolver#call_method`.
+    def method_missing(*args, &block)
+      call_method(args, &block)
+    end
+    
+    class << self
+      # An array of all method namespaces.
+      #
+      # Lazily loads the list from `namespaces.yml` and caches it.
+      # @return [Array] An array of strings
+      def names
+        if @names.nil?
+          filename = File.expand_path('../namespaces.yml', __FILE__)
+          @names   = YAML.load_file(filename)
+        end
+        
+        @names
+      end
+      
+      # Does a given namespace exist?
+      # @param [String, Symbol] name
+      def exists?(name)
+        names.include?(name.to_s)
+      end
+    end
+  end
+end

data/lib/telphin_api/namespaces.yml

@@ -0,0 +1,4 @@
+- extensions
+- phone_calls
+- cdr
+- faxes

data/lib/telphin_api/resolvable.rb

@@ -0,0 +1,20 @@
+module TelphinApi
+  # 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.to_s
+      @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/telphin_api/resolver.rb

@@ -0,0 +1,33 @@
+module TelphinApi
+  # A mixin for classes that will resolve other classes' objects via `#method_missing`.
+  module Resolver
+    # 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
+    
+  private
+    def create_namespace(name)
+      Namespace.new(name, resolver: resolver)
+    end
+    
+    def create_method(name)
+      Method.new(name, resolver: resolver)
+    end
+    
+    def call_method(args, &block)
+      create_method(args.shift).call(args.first || {}, &block)
+    end
+    
+    class << self
+      # When this module is included, it undefines the `:send` instance method in the `base_class`
+      # so it can be resolved via `method_missing`.
+      def included(base_class)
+        base_class.class_eval do
+          undef_method :send
+        end
+      end
+    end
+  end
+end

data/lib/telphin_api/result.rb

@@ -0,0 +1,48 @@
+module TelphinApi
+  # A module that handles method result processing.
+  #
+  # It implements method blocks support, result typecasting and raises `TelphinApi::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 [TelphinApi::Error] raised when Telphin 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 TelphinApi::Error.new(response.error)
+        else
+          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/telphin_api/utils.rb

@@ -0,0 +1,28 @@
+module TelphinApi
+  # 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