evercam 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c0feb0f02abd86da77568762f1270e426d26eead
+  data.tar.gz: 34520893b15f4b1a5e25a7704e54c1b830b06daf
+SHA512:
+  metadata.gz: 930158c12281cd62abb347e98e429dcf11832b0daf537129d18cf4bd87603b24eaa36790ca4816f935b891edec21c93295ba9f5182d1bd5970246f72b8d5a738
+  data.tar.gz: 192aa69fff15dcdc0d601bbc4ab6244511e7c9db052dc6b7df5baf91a62bec81c601a2cd1b5b42ad68378511599c5bca8c7daa11473a14a07d828f778bc6e01b

data/CHANGELOG.md

@@ -0,0 +1 @@
+# Change Log

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Peter Wood
+
+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,42 @@
+# Evercam
+
+This gem provides a wrapper around the Evercam REST API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'evercam'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install evercam
+
+## Usage
+
+To use the library in your code the first step is to include the library into
+your sources with the line...
+
+    require 'evercam'
+
+With the library included you next need to create an instance of the API class.
+This requires that you provide your Evercam API id and key and the following
+code...
+
+    api = Evercam::API.new(api_id: '1234567', api_key: '1a2b3c4d5e6a7b8c9d0e')
+
+Once you have an instance of the API class you can make calls to Evercam through
+it such as the following...
+
+    cameras = api.get_user_cameras('my_user_name')
+
+### Logging
+
+To add a logger to the Evercam API object you can do this during the creation
+of the object as follows...
+
+    api = Evercam::API.new(api_id: '1234567', api_key: '1a2b3c4d5e6a7b8c9d0e', logger: Logger.new(STDOUT))

data/lib/evercam.rb

@@ -0,0 +1,25 @@
+# Copyright © 2014, Evercam.
+
+require "faraday"
+require "faraday_middleware"
+require "json"
+require "logger"
+require "net/https"
+require "stringio"
+require "typhoeus"
+require "typhoeus/adapters/faraday"
+require "evercam/version"
+require "evercam/exceptions"
+require "evercam/null_logger"
+require "evercam/cameras"
+require "evercam/logs"
+require "evercam/models"
+require "evercam/public"
+require "evercam/shares"
+require "evercam/snapshots"
+require "evercam/users"
+require "evercam/vendors"
+require "evercam/api"
+
+module Evercam
+end

data/lib/evercam/api.rb

@@ -0,0 +1,215 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   class API
+      # Include the module components.
+      include Cameras
+      include Logs
+      include Models
+      include Public
+      include Shares
+      include Snapshots
+      include Users
+      include Vendors
+
+      # Constructor for the API class.
+      #
+      # ==== Parameters
+      # options::  A Hash of additional options to be used by the instance. At
+      #            a minimum this must include keys for :api_id and :api_key.
+      def initialize(options={})
+         @api_id  = options[:api_id]
+         @api_key = options[:api_key]
+         @logger  = NullLogger.new(STDOUT)
+         @host    = "api.evercam.io"
+         @port    = nil
+         @scheme  = "https"
+         @version = "1"
+         assign_options(options)
+      end
+
+      # This method will ping Evercam and provide feedback details that include
+      # whether the API credentials provided are valid.
+      def test
+         handle_response(call("/test"))
+      end
+
+      private
+
+      # This method is used internally by the class to assign recognised options
+      # to class settings.
+      #
+      # ==== Parameters
+      # options::  A Hash of the options to be processed.
+      def assign_options(options)
+         @logger  = options[:logger] if options.include?(:logger)
+         @host    = options[:host] if options.include?(:host)
+         @port    = options[:port] if options.include?(:port)
+         @scheme  = options[:scheme] if options.include?(:scheme)
+         @version = options[:version] if options.include?(:version)
+      end
+
+      # This method makes the actual call to the API endpoint for a request.
+      #
+      # ==== Parameters
+      # path::        The path to the API endpoint to be called.
+      # verb::        The HTTP verb to be used when making the request. Defaults
+      #               to :get.
+      # parameters::  A Hash of the parameters to be sent with the request.
+      #               Defaults to an empty Hash and need not include the
+      #               requesters API credentials as these are added to the
+      #               request automatically.
+      def call(path, verb=:get, parameters={})
+         connection = Faraday.new(url: base_url) do |faraday|
+            faraday.request :url_encoded
+            faraday.use FaradayMiddleware::FollowRedirects
+            faraday.adapter :typhoeus
+         end
+
+         values = {}.merge(parameters)
+         if @api_id && @api_key
+            values = values.merge(api_id: @api_id, api_key: @api_key)
+         end
+
+         started  = Time.now
+         response = nil
+         case verb
+            when :get
+               @logger.info "GET #{endpoint_url(path)}"
+               @logger.info "Parameters: #{values}"
+               response = connection.get(api_path(path), values)
+            when :delete
+               @logger.info "DELETE #{endpoint_url(path)}"
+               @logger.info "Parameters: #{values}"
+               response = connection.delete(api_path(path), values)
+            when :patch
+               @logger.info "PATCH #{endpoint_url(path)}"
+               @logger.info "Parameters: #{values}"
+               response = connection.patch(api_path(path), values)
+            when :post
+               @logger.info "POST #{endpoint_url(path)}"
+               @logger.info "Parameters: #{values}"
+               response = connection.post(api_path(path), values)
+            when :put
+               @logger.info "PUT #{endpoint_url(path)}"
+               @logger.info "Parameters: #{values}"
+               response = connection.put(api_path(path), values)
+            else
+               message = "Unrecognised HTTP method '#{verb}' specified for request."
+               @logger.error message
+               raise EvercamError.new(message)
+         end
+         finished = Time.now
+         @logger.info "API Call Took: #{finished - started}"
+         response
+      end
+
+      # This method provides generic processing of responses from a call to the
+      # API. The response status is first checked to see whether a success code
+      # was returned from the server. The response will then be checked for
+      # contents and an error raised if there are none. The contents will then
+      # be checked to see if they contain an error response and an error raised
+      # if this is the case. Finally, if all is well the parsed contents are
+      # returned.
+      def handle_response(response)
+         data = nil
+         if (200..299).include?(response.status)
+            if !response.body.nil? && response.body.strip != ''
+               data = parse_response_body(response)
+               if data.nil?
+                  message = "API call failed to return any data or "\
+                            "contained data that could not be parsed."
+                  @logger.error message
+                  raise EvercamError.new(message, "invalid_response", response.status)
+               end
+               handle_error_response(data, response.status) if data.include?("message")
+            end
+         else
+            @logger.error "API call returned with a status of #{response.status}."
+            handle_error_response(parse_response_body(response), response.status)
+         end
+         data
+      end
+
+      # This method is similar to the handle_response method with the exception
+      # that, if the request returns a success status, the method returns the
+      # response body as is, without trying to parse it as JSON.
+      #
+      # ==== Parameters
+      # response::  The request response to be handled.
+      def handle_raw(response)
+         data = nil
+         if !(200..299).include?(response.status)
+            data    = parse_response_body(response)
+            message = nil
+            if !data.nil? && data.include?("message")
+               handle_error_response(data, response.status)
+            else
+               message = "Evercam API call returned a #{response.status} code. "\
+                         "Response body was '#{response.body}'."
+               @logger.error message
+               raise EvercamError.new(message, "invalid_response", response.status)
+            end
+         else
+            data = response.body
+         end
+         data
+      end
+
+      # This method encapsulates the functionality and error handling for
+      # parsing the contents of an API response. The nethod returns nil if it
+      # is unable to parse out contents from the response.
+      #
+      # ==== Parameters
+      # response::  The API call response to be parsed.
+      def parse_response_body(response)
+         contents = nil
+         if !response.body.nil? && response.body.strip != ""
+            begin
+               contents = JSON.parse(response.body)
+            rescue => error
+               @logger.error "Error interpreting response for API call.\nCause: #{error}"
+            end
+         end
+         contents
+      end
+
+      # This method fetches the base URL component for all API endpoints and
+      # constructs it from settings within the class instance.
+      def base_url
+         url = StringIO.new
+         url << @scheme << "://" << @host
+         url << ":" << @port if !@port.nil?
+         url.string
+      end
+
+      # This method generates a versioned path for an API endpoint.
+      #
+      # ==== Parameters
+      # suffix::  The API call dependent part of the path.
+      def api_path(suffix)
+         ((/.+\..+$/ =~ suffix) != 0) ? "/v1#{suffix}.json" : "/v1#{suffix}"
+      end
+
+      # This method generates the fully qualified URL for an API endpoint.
+      #
+      # ==== Parameters
+      # suffix::  The API call dependent part of the path.
+      def endpoint_url(suffix)
+         "#{base_url}#{api_path(suffix)}"
+      end
+
+      # This method processes a standard Evercam API error response to raise
+      # an exception from it.
+      #
+      # ==== Parameters
+      # data::    The parsed response data.
+      # status::  The HTTP status code associated with the response.
+      def handle_error_response(data, status)
+         message = (data["message"] || "Evercam API call returned an error.")
+         @logger.error "API response contains error details.\nMessage: #{message}\n"\
+                       "Code: #{data["code"]}\nStatus: #{status}"
+         raise EvercamError.new(message, data["code"], status, *data["context"])
+      end
+   end
+end

data/lib/evercam/cameras.rb

@@ -0,0 +1,116 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Cameras
+      # Test whether a given set of camera parameters are correct.
+      #
+      # ==== Parameters
+      # external_url::  The external URL of the camera to be tested.
+      # jpg_url::       The JPEG URL of the camera to be tested.
+      # user_name::     The camera user name to be used in the test.
+      # password::      The camera password to be used in the test.
+      def test_camera(external_url, jpg_url, user_name, password)
+         parameters = {external_url: external_url,
+                       jpg_url: jpg_url,
+                       cam_username: user_name,
+                       cam_password: password}
+         handle_response(call("/cameras/test", :get, parameters))
+      end
+
+      # This method attempts to retrieve the details for a specific camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to query.
+      def get_camera(camera_id)
+         data = handle_response(call("/cameras/#{camera_id}"))
+         if !data.include?("cameras") || data["cameras"].size == 0
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["cameras"][0]
+      end
+
+      # This method attempts to update the details associated with a camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to be updated.
+      # values::     A Hash of the values to be set. Keys recognosed in this
+      #              parameter include :name, :is_public, :external_host,
+      #              :internal_host, :external_http_port, :internal_http_port,
+      #              :external_rtsp_port, :internal_rtsp_port, :jpg_url,
+      #              :cam_username and :cam_password - all other parameters
+      #              will be ignored.
+      def update_camera(camera_id, values={})
+         handle_response(call("/cameras/#{camera_id}", :patch, values)) if !values.empty?
+         self
+      end
+
+      # Delete a camera from the system.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to be deleted.
+      def delete_camera(camera_id)
+         handle_response(call("/cameras/#{camera_id}", :delete))
+         self
+      end
+
+      # This method fetches details for a set of cameras based on their unique
+      # identifiers.
+      #
+      # ==== Parameters
+      # camera_ids::  A collection of 1 or more camera ids for the cameras to
+      #               fetch details for.
+      def get_cameras(*camera_ids)
+         data = handle_response(call("", :get, {ids: camera_ids.join(",")})) if !camera_ids.empty?
+         if !data.include?("cameras")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["cameras"]
+      end
+
+      # This method creates a new camera in the system.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier to be assigned to the new camera.
+      # name::       The name for the new camera.
+      # is_public::  A boolean to indicate whether the new camera is public.
+      # values::     A Hash of additional settings for the camera. The following
+      #              keys are recognised :external_host, internal_host,
+      #              :external_http_port, :internal_http_port,
+      #              :external_rtsp_port, :internal_rtsp_port, :jpg_url,
+      #              :cam_username and :cam_password.
+      def create_camera(camera_id, name, is_public, values={})
+         parameters = {id: camera_id,
+                       name: name,
+                       is_public: is_public}.merge(values)
+         data = handle_response(call("/cameras", :post, parameters))
+         if !data.include?("cameras") || data["cameras"].size == 0
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["cameras"][0]
+      end
+
+      # This method changes the owner of a camera. You must be the owner of the
+      # camera to call this method and all artifacts relating to the camera
+      # transfer ownership when the camera does.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to be transferred.
+      # user_id:     The Evercam user name or email address of the new owner for
+      #              the camera.
+      def change_camera_owner(camera_id, user_id)
+         data = handle_response(call("/cameras/#{camera_id}", :put, {user_id: user_id}))
+         if !data.include?("cameras") || data["cameras"].empty?
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["cameras"].first
+      end
+   end
+end

data/lib/evercam/exceptions.rb

@@ -0,0 +1,30 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   # This is the base error class for exceptions generated within the Evercam
+   # library.
+   class EvercamError < StandardError
+      # Constructor for the EvercamError class.
+      #
+      # ==== Parameters
+      # message::   A String containing the error message for the exception.
+      # code::      The error code associated with the exception if one is
+      #             available. Defaults to nil.
+      # status::    The HTTP status code associated with the exception if one
+      #             is available. Defaults to nil.
+      # *context::  A collection of contextual data associated with the
+      #             exception.
+      def initialize(message, code=nil, status=nil, *context)
+         super(message)
+         @code    = code
+         @status  = status
+         @context = context
+      end
+
+      attr_reader :status, :context
+
+      def code
+         (@code || "unknown_error")
+      end
+   end
+end

data/lib/evercam/logs.rb

@@ -0,0 +1,37 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Logs
+      # This method fetches activity log details for a specified camera from
+      # the system.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to fetch the logs for.
+      # options::    A Hash of additional parameters for the request. Currently
+      #              recognised keys for this request are :from, :to, :limit,
+      #              :page, :types and :objects.
+      def get_logs(camera_id, options={})
+         parameters = {}
+         parameters[:from] = options[:from].to_i if options.include?(:from)
+         parameters[:to] = options[:to].to_i if options.include?(:to)
+         parameters[:limit] = options[:limit] if options.include?(:limit)
+         parameters[:page] = options[:page] if options.include?(:page)
+         if options.include?(:types)
+            values = options[:types]
+            if values.kind_of?(Array)
+               parameters[:types] = options[:types].join(",")
+            else
+               parameters[:types] = options[:types]
+            end
+         end
+         parameters[:objects] = (options[:objects] == true) if options.include?(:objects)
+         data = handle_response(call("/cameras/#{camera_id}/logs", :get, parameters))
+         if !data.include?("logs") || !data.include?("pages")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         {logs: data["logs"], pages: data["pages"]}
+      end
+   end
+end

data/lib/evercam/models.rb

@@ -0,0 +1,46 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Models
+      # This method fetches a list of all models support within Evercam.
+      def get_all_models
+         data = handle_response(call("/models"))
+         if !data.include?("vendors")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["vendors"]
+      end
+
+      # This method fetches a list of models for a specified vendor.
+      #
+      # ==== Parameters
+      # vendor::  The unique identifier for the vendor to fetch the list of
+      #           models for.
+      def get_vendor_models(vendor)
+         data = handle_response(call("/models/#{vendor}"))
+         if !data.include?("vendors") || data["vendors"].empty?
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["vendors"].first
+      end
+
+      # This method fetches details for a specific model for a given vendor.
+      #
+      # ==== Parameters
+      # vendor::  The unique identifier for the vendor who owns the model.
+      # model::   The unique identifier for the model to fetch.
+      def get_vendor_model(vendor, model)
+         data = handle_response(call("/models/#{vendor}/#{model}"))
+         if !data.include?("models") || data["models"].empty?
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["models"].first
+      end
+   end
+end

data/lib/evercam/null_logger.rb

@@ -0,0 +1,12 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   class NullLogger < Logger
+      def initialize(*args)
+         super(*args)
+      end
+
+      def add(*args, &block)
+      end
+   end
+end

data/lib/evercam/public.rb

@@ -0,0 +1,23 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Public
+      # This method fetches a list of public and discoverable cameras from
+      # with Evercam.
+      #
+      # ==== Parameters
+      # critera::  A Hash of search criteria to use for the list returned
+      #            by the request. Currently recognised options include
+      #            :case_sensitive, :id_starts_with, :id_ends_with,
+      #            :id_contains, :offset and :limit.
+      def get_public_cameras(criteria={})
+         data = handle_response(call("/public/cameras", :get, criteria))
+         if !data.include?("cameras")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         {cameras: data["cameras"], pages: data["pages"]}
+      end
+   end
+end

data/lib/evercam/shares.rb

@@ -0,0 +1,169 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Shares
+      # Fetches details for the camera share for a specific camera and user.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera that was shared.
+      # user_id::    Either the user name or email address of the user that the
+      #              camera was shared with.
+      def get_camera_share(camera_id, user_id)
+         data = handle_response(call("/shares", :get, camera_id: camera_id, user_id: user_id))
+         if !data.include?("shares")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["shares"].first
+      end
+
+      # This method fetches a list of shares for a specified camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to produce the list of
+      #              shares for.
+      def get_camera_shares(camera_id)
+         data = handle_response(call("/shares/cameras/#{camera_id}"))
+         if !data.include?("shares")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["shares"]
+      end
+
+      # This method shares an existing camera with an email address. If the
+      # email address ties to an Evercam user account then a share is created
+      # for the account. If this is not the case then an email is dispatched
+      # to invite the user to come join Evercam and make use of the camera
+      # shared with them.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera being shared.
+      # email::      The email address of the individual to share the camera
+      #              with.
+      # rights::     Either a String indicating the rights to be granted
+      #              to the user as a comma separated list or an Array of
+      #              Strings containing the name of the rights to be granted
+      #              with the share.
+      # options::    A Hash of addition parameters to the request. Currently
+      #              recognised keys within this Hash are :grantor, :message
+      #              and :notify.
+      def share_camera(camera_id, email, rights, options={})
+         parameters = {email: email}
+         parameters[:rights] = (rights.kind_of?(String) ? rights : rights.join(","))
+         parameters[:grantor] = options[:grantor] if options.include?(:grantor)
+         parameters[:message] = options[:message] if options.include?(:message)
+         parameters[:notify] = (options[:notify] == true) if options.include?(:notify)
+         data = handle_response(call("/shares/cameras/#{camera_id}", :post, parameters))
+
+         output = nil
+         if data.include?("shares")
+            if !data["shares"].empty?
+               output = data["shares"].first
+               output["type"] = "share"
+            end
+         elsif data.include?("share_requests")
+            if !data["share_requests"].empty?
+               output = data["share_requests"].first
+               output["type"] = "share_request"
+            end
+         end
+
+         if output.nil?
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         output
+      end
+
+      # This method deletes an existing camera share.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera that was shared.
+      # share_id::   The unique identifier of the share that is being deleted.
+      def delete_camera_share(camera_id, share_id)
+         handle_response(call("/shares/cameras/#{camera_id}", :delete, share_id: share_id))
+         self
+      end
+
+      # This method updates the settings on a camera share, altering the right
+      # available to the user that the camera was shared with.
+      #
+      # ==== Parameters
+      # share_id::  The unique identifier of the camera share to be updated.
+      # rights::    Either an array of right name strings or a single string
+      #             consisting of a comma separated array of right names.
+      def update_camera_share(share_id, rights)
+         parameters = {rights: (rights.kind_of?(String) ? rights : rights.join(","))}
+         handle_response(call("/shares/cameras/#{share_id}", :patch, parameters))
+         self
+      end
+
+      # Fetches a list of the camera shares currently available to a specified
+      # user.
+      #
+      # ==== Parameters
+      # user_id::  The unique identifier of the user to fetch the list of shares
+      #            for.
+      def get_user_camera_shares(user_id)
+         data = handle_response(call("/shares/users/#{user_id}"))
+         if !data.include?("shares")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["shares"]
+      end
+
+      # This method fetches a list of share requests pending on a specified
+      # camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to fetch the list
+      #              of pending share requests for.
+      # status::     The status of the camera share requests to be retrieved.
+      #              This should be either 'PENDING', 'USED' or 'CANCELLED'.
+      #              Defaults to nil to indicate no particular status is
+      #              being requested.
+      def get_camera_share_requests(camera_id, status=nil)
+         parameters = {}
+         parameters[:status] = status if !status.nil?
+         data = handle_response(call("/shares/requests/#{camera_id}", :get, parameters))
+         if !data.include?("share_requests")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["share_requests"]
+      end
+
+      # This method is used to cancel a pending camera share request.
+      #
+      # ==== Parameters
+      # request_id::  The unique identifier of the share request to be
+      #               cancelled.
+      # email::       The email address associated with the share request
+      #               being cancelled.
+      def cancel_camera_share_request(request_id, email)
+         handle_response(call("/shares/requests/#{request_id}", :delete, email: email))
+         self
+      end
+
+      # This method updates the rights to be granted when a pending camera share
+      # request is accepted.
+      #
+      # ==== Parameters
+      # request_id::  The unique identifier of the share request to be
+      #               updated.
+      # rights::      Either an array of right name strings or a string
+      #               containing a comma separated list of right names.
+      def update_camera_share_request(request_id, rights)
+         parameters = {rights: (rights.kind_of?(String) ? rights : rights.join(","))}
+         handle_response(call("/shares/requests/#{request_id}", :patch, parameters))
+         self
+      end
+   end
+end

data/lib/evercam/snapshots.rb

@@ -0,0 +1,204 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Snapshots
+      # This method fetches a Base64 encoded snapshot from a camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to take the snapshot
+      #              from.
+      def get_live_image(camera_id)
+         data = handle_response(call("/cameras/#{camera_id}/live"))
+         if !data.include?("data")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["data"]
+      end
+
+      # This method returns details for all snapshots stored for a specified
+      # camera.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to list snapshots
+      #              for.
+      def get_snapshots(camera_id)
+         data = handle_response(call("/cameras/#{camera_id}/snapshots"))
+         if !data.include?("snapshots")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["snapshots"].inject([]) do |list, entry|
+            entry["created_at"] = Time.at(entry["created_at"])
+            list << entry
+         end
+      end
+
+      # This method grabs a snapshot from a specified camera and stores it using
+      # the current timestamp.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to grab the snapshot
+      #              from.
+      # comment::    An optional comment to put on the newly created snapshot.
+      #              Defaults to nil to indicate no comment.
+      def store_snapshot(camera_id, comment=nil)
+         parameters = {}
+         parameters[:notes] = comment.to_s if !comment.nil?
+         data = handle_response(call("/cameras/#{camera_id}/snapshots", :post, parameters))
+         if !data.include?("snapshots") || data["snapshots"].size == 0
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["snapshots"].first["created_at"] = Time.at(data["snapshots"].first["created_at"])
+         data["snapshots"].first
+      end
+
+      # This method fetches the most up-to-date snapshot for a specified camera
+      # stored in the system.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier to fetch the snapshot for.
+      # complete::   A flag to indicate whether the response should include the
+      #              image data for the snapshot. Defaults to false.
+      def get_latest_snapshot(camera_id, complete=false)
+         parameters = {}
+         parameters[:with_data] = true if complete == true
+         data = handle_response(call("/cameras/#{camera_id}/snapshots/latest", :get, parameters))
+         if !data.include?("snapshots")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         snapshot = nil
+         if !data["snapshots"].empty?
+            snapshot               = data["snapshots"].first
+            snapshot["created_at"] = Time.at(snapshot["created_at"])
+         end
+         snapshot
+      end
+
+      # This method fetches a list of snapshot stored in the system for a
+      # specified camera between a stated start and end date.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to fetch snapshots for.
+      # from::       The date/time of the start of the range to fetch snapshots
+      #              for.
+      # to::         The date/time of the end of the range to fetch snapshots
+      #              for.
+      # options::    A Hash of the options to be given to the request. Keys
+      #              recognised in this Hash are :with_data, :limit and
+      #              :page.
+      def get_snapshots_in_date_range(camera_id, from, to, options={})
+         parameters = {from: from.to_i, to: to.to_i, with_data: (options[:with_data] == true)}
+         if options.include?(:limit)
+            parameters[:limit] = options[:limit]
+         else
+            parameters[:limit] = (options[:with_data] ? 10 : 100)
+         end
+         parameters[:page] = options[:page] if options.include?(:page)
+         data = handle_response(call("/cameras/#{camera_id}/snapshots/range", :get, parameters))
+         if !data.include?("snapshots")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["snapshots"].inject([]) do |list, entry|
+            entry["created_at"] = Time.at(entry["created_at"])
+            list << entry
+         end
+      end
+
+      # This method returns a list of dates for which stored snapshots are
+      # available on a specified camera given a specific month and year.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to perform the check
+      #              for.
+      # month::      The month of the year, as an integer, to perform the
+      #              check for. Defaults to nil to indicate the current
+      #              month.
+      # year::       The year to perform the check for. Defaults to nil to
+      #              indicate the current year.
+      def get_snapshot_dates(camera_id, month=nil, year=nil)
+         month = (month || Time.now.month)
+         year  = (year || Time.now.year)
+         data  = handle_response(call("/cameras/#{camera_id}/snapshots/#{year}/#{month}/days"))
+         if !data.include?("days")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["days"].inject([]) {|list, entry| list << Time.local(year, month, entry)}
+      end
+
+      # This method retrieves a list of Time objects for a specified camera for
+      # which their are snapshots stored in the system. The Time objects
+      # returned aren't specific snapshot timestamps but are used to indicate
+      # the hours during the day for which snapshots are available.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera to fetch the snapshot
+      #              details for.
+      # date::       The day to perfom this check for. The time part of this
+      #              value is not taken into consideration. Defaults to the
+      #              current date.
+      def get_snapshots_by_hour(camera_id, date=Time.now)
+         data = handle_response(call("/cameras/#{camera_id}/snapshots/#{date.year}/#{date.month}/#{date.day}/hours"))
+         if !data.include?("hours")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["hours"].inject([]) {|list, entry| list << Time.local(date.year, date.month, date.day, entry)}
+      end
+
+      # This method fetches a snapshot for a given timestamp.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera that generated the
+      #              snapshot.
+      # timestamp::  The timestamp of the snapshot to retrieve.
+      # options::    A Hash of optional settings for the request. Keys
+      #              recognised in this Hash are :with_data and :range.
+      def get_snapshot_at(camera_id, timestamp, options={})
+         parameters = {with_data: (options[:with_data] == true)}
+         parameters[:range] = options[:range] if options.include?(:range)
+         data = handle_response(call("/cameras/#{camera_id}/snapshots/#{timestamp.to_i}",
+                                     :get, parameters))
+         if !data.include?("snapshots") || data["snapshots"].size == 0
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["snapshots"].first["created_at"] = Time.at(data["snapshots"].first["created_at"])
+         data["snapshots"].first
+      end
+
+      # This method deletes a snapshot from the system.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier of the camera that the snapshot
+      #              is stored under.
+      # timestamp::  The timestamp of the snapshot to be deleted.
+      def delete_snapshot(camera_id, timestamp)
+         data = handle_response(call("/cameras/#{camera_id}/snapshots/#{timestamp.to_i}", :delete))
+         self
+      end
+
+      # This method takes a snapshot from a specified camera and returns
+      # it's details. Note that the method, when successful, returns a String
+      # containing the raw image data.
+      #
+      # ==== Parameters
+      # camera_id::  The unique identifier for the camera to get the snapshot
+      #              from.
+      def get_snapshot(camera_id)
+         handle_raw(call("/cameras/#{camera_id}/snapshot.jpg"))
+      end
+   end
+end

data/lib/evercam/users.rb

@@ -0,0 +1,87 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Users
+      # Fetch details for a specified user.
+      #
+      # ==== Parameters
+      # user::    The Evercam user name or email address of the user to fetch
+      #           the list of cameras for.
+      def get_user(user)
+         data = handle_response(call("/users/#{user}"))
+         if !data.include?("users") || data["users"].size == 0
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["users"][0]
+      end
+
+      # Fetches a list of user cameras for a specified user.
+      #
+      # ==== Parameters
+      # user::    The Evercam user name or email address of the user to fetch
+      #           the list of cameras for.
+      # shared::  A boolean to indicate if shared cameras should be included in
+      #          the fetch. Defaults to false.
+      def get_user_cameras(user, shared=false)
+         data = handle_response(call("/users/#{user}/cameras", :get, include_shared: shared))
+         if !data.include?("cameras")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["cameras"]
+      end
+
+      # Updates the details for a user.
+      #
+      # ==== Parameters
+      # user::    The Evercam user name or email address of the user to be
+      #           updated.
+      # values::  A Hash of the values to be updated. Recognized keys in this
+      #           Hash are :forename, :lastname, :username, :country and :email.
+      def update_user(user, values={})
+         handle_response(call("/users/#{user}", :patch, values)) if !values.empty?
+         self
+      end
+
+      # This method deletes a user account and all details associated with it.
+      #
+      # ==== Parameters
+      # user::    The Evercam user name or email address of the user to be
+      #           deleted.
+      def delete_user(user)
+         handle_response(call("/users/#{user}", :delete))
+         self
+      end
+
+      # This method creates a new user within the Evercam system.
+      #
+      # ==== Parameters
+      # first_name::  The first name for the new user.
+      # last_name::   The last name for the new user.
+      # user_name::   The unique system user name for the new user.
+      # email::       The email address for the new user.
+      # password::    The new users password.
+      # country::     The country for the new user.
+      # key::         A share request key to be processed during the process
+      #               of creating the new user account. Defaults to nil.
+      def create_user(first_name, last_name, user_name, email, password, country, key=nil)
+         parameters = {forename: first_name,
+                       lastname: last_name,
+                       username: user_name,
+                       country: country,
+                       email: email,
+                       password: password}
+         parameters[:share_request_key] = key if !key.nil?
+         data = handle_response(call("/users", :post, parameters))
+         if !data.include?('users') || data['users'].empty?
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data['users'].first
+      end
+   end
+end

data/lib/evercam/vendors.rb

@@ -0,0 +1,31 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   module Vendors
+      # This method returns a list of all vendors in Evercam.
+      def get_all_vendors
+         data = handle_response(call("/vendors"))
+         if !data.include?("vendors")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["vendors"]
+      end
+
+      # This method returns a list of vendors that match a specified MAC
+      # address prefix.
+      #
+      # ==== Parameters
+      # mac_prefix::  The MAC address prefix to use in the vendor search.
+      def get_vendors_by_mac(mac_prefix)
+         data = handle_response(call("/vendors/#{mac_prefix}"))
+         if !data.include?("vendors")
+            message = "Invalid response received from server."
+            @logger.error message
+            raise EvercamError.new(message)
+         end
+         data["vendors"]
+      end
+   end
+end

data/lib/evercam/version.rb

@@ -0,0 +1,5 @@
+# Copyright © 2014, Evercam.
+
+module Evercam
+   VERSION = "0.1.1"
+end

metadata

@@ -0,0 +1,200 @@
+--- !ruby/object:Gem::Specification
+name: evercam
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Evercam
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0.beta2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0.beta2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: This library provides a wrapper for using the Evercam API.
+email:
+- howrya@evercam.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/evercam.rb
+- lib/evercam/api.rb
+- lib/evercam/cameras.rb
+- lib/evercam/exceptions.rb
+- lib/evercam/logs.rb
+- lib/evercam/models.rb
+- lib/evercam/null_logger.rb
+- lib/evercam/public.rb
+- lib/evercam/shares.rb
+- lib/evercam/snapshots.rb
+- lib/evercam/users.rb
+- lib/evercam/vendors.rb
+- lib/evercam/version.rb
+homepage: https://evercam.io
+licenses:
+- Commercial Proprietary
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A wrapper for the Evercam API.
+test_files: []