wialon_api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd519972faecf419d0180f12009d82e1ba6e5ed3
+  data.tar.gz: ab634f19f8dadb0f25c3095eeec8b4b1e72a5830
+SHA512:
+  metadata.gz: d1e5a3a53d4b092302901232efdcb1150aea0b24f856703dee84927af98343d3daa45ce11d7822eb995976d4954e3e1f12f12ada7acac3320e01249d242ce060
+  data.tar.gz: b6a87a752eb5838441fde82c38725cc1ff76044aaca8e1b218635865b2121a7d38e549f8b4eb9dcb4c7dd0f0c57191284bd52338d553e36977d173845ddab0d6

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version
+.ruby-gemset

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,4 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.2

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 wialon_api.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,22 @@
+guard :rspec, cmd: "bin/rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end
+
+guard 'yard' do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+  watch(%r{README.md})
+  watch(%r{CHANGELOG.md})
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Arsen
+
+MIT License
+
+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,170 @@
+# WialonApi
+[![Build Status](https://travis-ci.org/thorn/wialon_api.svg?branch=master)](https://travis-ci.org/thorn/wialon_api)
+[![Join the chat at https://gitter.im/thorn/wialon_api](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/thorn/wialon_api?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+`wialon_api` is a ruby client for a [Wialon](http://wialon.com/) web-based GPS tracking software platform [API](http://sdk.wialon.com/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wialon_api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wialon_api
+
+## Usage
+
+### Api method call
+
+```ruby
+# The first thing to do is to authorize client
+client = WialonApi.authorize("wialon_test", "test")
+
+# Now we can use API
+client.core.get_account_data(type: 1)
+# => {"plan"=>"Gurtam External",
+#  "enabled"=>1,
+#  "flags"=>16,
+#  "created"=>1362386585,
+#  "balance"=>"0.00",
+#  "daysCounter"=>0,
+#  "services"=>
+#   ....
+
+# API calls with nested params could be implemented as follows
+client.core.search_items({
+  "spec" => {
+    "itemsType" => "avl_unit",
+    "propName" => "sys_name",
+    "propValueMask" => "*",
+    "sortType" => "sys_name"
+  },
+  "force" => 1,
+  "flags" => 0x3FFFFFFFFFFFFFFF,
+  "from" => 0,
+  "to" => 0
+})
+
+=> {"searchSpec"=>{"itemsType"=>"avl_unit", "propName"=>"sys_name", "propValueMask"=>"*", "sortType"=>"sys_name", "propType"=>""},
+# "dataFlags"=>4611686018427387903,
+# "totalItemsCount"=>27,
+# "indexFrom"=>0,
+# "indexTo"=>0,
+# "items"=>
+#  [{"nm"=>"_TK102",
+#    "cls"=>2,
+#    "id"=>12417697,
+#    "prp"=>{},
+#    "crt"=>717313,
+#     ..........
+```
+
+`wialon_api` uses a list of namespaces from API documentation:
+
+  * core
+  * items
+  * user
+  * resource
+  * account
+  * unit
+  * unit_group
+  * retranslator
+  * route
+  * messages
+  * report
+  * exchange
+  * render
+  * file
+
+### Error handling
+
+When wialon server returns an error, the WialonApi::Error exception is raised
+
+```ruby
+[1] pry(main)> WialonApi.authorize("wrong_user", "password")
+WialonApi::Error: Wialon server https://hst-api.wialon.com/wialon/ajax.html returned error 8: Invalid user name or password
+```
+
+### Logging
+
+`wialon_api` logs information in `STDOUT` by default. This can be changed in configuration to any other logger e.g. `Rails.logger`.
+
+Three types of information could be logged:
+
+|                        | configuration key  | default value | log level |
+| ---------------------- | ---------------    | ------------  | --------- |
+| URL Request            | `log_requests`     | `true`        | `debug`   |
+| error response JSON    | `log_errors`       | `true`        | `warn`    |
+| success response JSON  | `log_responses`    | `false`       | `debug`   |
+
+In a rails applications with default settings in production mode only server
+response errors are logged. In development mode the gem logs server responses
+and request URLs.
+
+### Configuration
+
+Global parameters could be set in a block of `WialonApi.configure`:
+
+```ruby
+WialonApi.configure do |config|
+  # Faraday adapter to make requests with:
+  # config.adapter = :net_http
+
+  # Faraday connection options
+  # config.faraday_options = {}
+
+  # HTTP verb for API methods (:get or :post)
+  # config.http_verb = :post
+
+  # Number of retries when connection is failed
+  # config.max_retries = 1
+
+
+  # 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
+
+  # Wialon server host
+  # config.wialon_host = 'https://hst-api.wialon.com/wialon/ajax.html'
+end
+```
+
+`Net::HTTP` is used by default for a HTTP requests. One can choose any [other adapter](https://github.com/technoweenie/faraday/blob/master/lib/faraday/adapter.rb) suported by `faraday`.
+
+Options for faraday connection (e.g. proxy settings or SSL certificates path) could be set through `faraday_options` when configuring `wialon_api`
+
+The default configuration could be generated in a Rails application using `wialon_api:install` command:
+
+``` sh
+$ cd /path/to/app
+$ rails generate wialon_api:install
+```
+## TODO
+
+  * Implement methods from "Other request" documentation section
+  * Add documentation
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/wialon_api/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+desc 'Fires up the console with preloaded wialon_api'
+task :console do
+  sh 'pry -I ./lib -r ./lib/wialon_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,16 @@
+#!/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'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

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

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

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

@@ -0,0 +1,30 @@
+WialonApi.configure do |config|
+  # Faraday adapter to make requests with:
+  # config.adapter = :net_http
+
+  # Faraday connection options
+  # config.faraday_options = {}
+
+  # HTTP verb for API methods (:get or :post)
+  # config.http_verb = :post
+
+  # Number of retries when connection is failed
+  # config.max_retries = 1
+
+
+  # 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
+
+  # Wialon server host
+  # config.wialon_host = 'https://hst-api.wialon.com/wialon/ajax.html'
+end

data/lib/wialon_api/api.rb

@@ -0,0 +1,24 @@
+require 'json'
+
+module WialonApi
+  module Api
+    def self.call(service_name, args = {}, sid = nil)
+      parameters = { svc: service_name, params: args.to_json, sid: sid }
+      connection(url: WialonApi.wialon_host, sid: sid).send(WialonApi.http_verb, WialonApi.wialon_host, parameters).body
+    end
+
+    def self.connection(options = {})
+      url = options.delete(:url)
+      Faraday.new(url, WialonApi.faraday_options) do |builder|
+        builder.request :url_encoded
+        builder.request :retry, WialonApi.max_retries
+
+        builder.response :wialon_logger
+        builder.response :mashify
+        builder.response :oj, preserve_raw: true
+
+        builder.adapter WialonApi.adapter
+      end
+    end
+  end
+end

data/lib/wialon_api/authorization.rb

@@ -0,0 +1,9 @@
+module WialonApi
+  module Authorization
+    def authorize(user, password)
+      response = WialonApi::Api.call('core/login', user: user, password: password)
+      result = WialonApi::Result.process(response)
+      WialonApi::Client.new(result.eid)
+    end
+  end
+end

data/lib/wialon_api/client.rb

@@ -0,0 +1,29 @@
+module WialonApi
+  class Client
+    include WialonApi::Resolver
+
+    attr_reader :sid
+
+    def initialize(sid = nil)
+      @sid = sid
+    end
+
+    def authorized?
+      !@sid.nil?
+    end
+
+    def execute(*args)
+      call_method(*args)
+    end
+
+    # If the called method is a namespace, it creates and returns a new `WialonApi::Namespace` instance.
+    # Otherwise it creates a `WialonApi::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
+  end
+end

data/lib/wialon_api/configuration.rb

@@ -0,0 +1,54 @@
+require 'logger'
+
+module WialonApi
+  module Configuration
+    OPTION_NAMES = [
+      :wialon_host,
+      :http_verb,
+      :max_retries,
+      :faraday_options,
+      :adapter,
+      :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_WIALON_HOST = 'https://hst-api.wialon.com/wialon/ajax.html'
+    DEFAULT_HTTP_VERB = :post
+    DEFAULT_MAX_RETRIES = 1
+    DEFAULT_ADAPTER = Faraday.default_adapter
+    DEFAULT_LOGGER_OPTIONS = {
+      requests:  true,
+      errors:    true,
+      responses: false
+    }
+
+    def configure
+      yield self if block_given?
+      self
+    end
+
+    def reset
+      @wialon_host = DEFAULT_WIALON_HOST
+      @http_verb   = DEFAULT_HTTP_VERB
+      @max_retries = DEFAULT_MAX_RETRIES
+      @faraday_options = {}
+      @adapter         = DEFAULT_ADAPTER
+      @logger          = ::Logger.new(STDOUT)
+      @log_requests    = DEFAULT_LOGGER_OPTIONS[:requests]
+      @log_errors      = DEFAULT_LOGGER_OPTIONS[:errors]
+      @log_responses   = DEFAULT_LOGGER_OPTIONS[:responses]
+    end
+
+    def self.extended(base)
+      base.reset
+    end
+  end
+end

data/lib/wialon_api/error.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+module WialonApi
+  class Error < StandardError
+    attr_reader :error_code
+    attr_reader :error_messages
+    attr_reader :message
+
+    def initialize(data)
+      @error_code = data.error
+      @message = "Wialon server #{WialonApi.wialon_host} returned error #{error_code}: #{error_descriptions[@error_code.to_s]}"
+    end
+
+    def error_descriptions
+      {
+        '0' => 'Successful operation (for example for logout it will be success exit)',
+        '1' => 'Invalid session',
+        '2' => 'Invalid service name',
+        '3' => 'Invalid result',
+        '4' => 'Invalid input',
+        '5' => 'Error performing request',
+        '6' => 'Unknown error',
+        '7' => 'Access denied',
+        '8' => 'Invalid user name or password',
+        '9' => 'Authorization server is unavailable',
+        '10' => 'Reached limit of concurrent requests',
+        '1001' => 'No messages for selected interval',
+        '1002' => 'Item with such unique property already exists or Item cannot be created according to billing restrictions',
+        '1003' => 'Only one request is allowed at the moment',
+        '2014' => 'Selected user is a creator for some system objects, thus this user cannot be bound to a new account'
+      }
+    end
+  end
+end
+
+
+

data/lib/wialon_api/logger.rb

@@ -0,0 +1,36 @@
+module WialonApi
+  # 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 = WialonApi.logger
+    end
+
+    # Logs the request if needed.
+    # @param [Hash] env Request data.
+    def call(env)
+      if WialonApi.log_requests?
+        @logger.debug "#{env[:method].to_s.upcase} #{env[:url]}"
+        @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 WialonApi.log_errors?
+      else
+        @logger.debug env[:raw_body] if WialonApi.log_responses?
+      end
+    end
+  end
+
+  Faraday::Response.register_middleware wialon_logger: Logger
+end

data/lib/wialon_api/method.rb

@@ -0,0 +1,23 @@
+module WialonApi
+  # 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, sid)
+      Result.process(response, block)
+    end
+
+    private
+
+    def full_name
+      [@previous_resolver.name, @name].join('/')
+    end
+  end
+end

data/lib/wialon_api/namespace.rb

@@ -0,0 +1,36 @@
+module WialonApi
+  # An API method namespace (such as `users` or `friends`).
+  #
+  # 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 `WialonApi::Method` using `WialonApi::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/wialon_api/namespaces.yml

@@ -0,0 +1,14 @@
+- core
+- items
+- user
+- resource
+- account
+- unit
+- unit_group
+- retranslator
+- route
+- messages
+- report
+- exchange
+- render
+- file

data/lib/wialon_api/resolvable.rb

@@ -0,0 +1,20 @@
+module WialonApi
+  # 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 sid from the previous resolver.
+    # @return [String] A sid.
+    def sid
+      @previous_resolver.sid
+    end
+  end
+end

data/lib/wialon_api/resolver.rb

@@ -0,0 +1,34 @@
+module WialonApi
+  # A mixin for classes that will resolve other classes' objects via `#method_missing`.
+  module Resolver
+    # A `Hashie::Mash` structure holding the name and sid of current instance.
+    # @return [Hashie::Mash]
+    def resolver
+      @resolver ||= Hashie::Mash.new(name: @name, sid: sid)
+    end
+
+    private
+
+    def create_namespace(name)
+      WialonApi::Namespace.new(name, resolver: resolver)
+    end
+
+    def create_method(name)
+      WialonApi::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