cloud_connect 2.0.2 → 3.0.3

data/lib/cloud_connect/client/fields.rb

@@ -1,21 +1,94 @@
 module CloudConnect
-  module Fields
+  class Client
+    module Fields
 
-    # Retrieve a list of fields.
-    # WARNING: This method uses calls not officially supported by Mobile Devices.
-    #
-    # @return [[Hashie::Mash]] Array of Fields
-    def fields(reload = false)
-      return @fields if @fields && !reload
-      page  = 1
-      limit = 100
-      fields = []
-      while (slice = connection.get(connection.build_url("fields", :per_page => limit, :page => page)).body).size > 0
-        page += 1
-        fields += slice.map!{|hash| hash.values.first} if slice.size > 0
-        slice.size < limit ? break : sleep(1)
+      # Get a field
+      #
+      # @param name [String] Name of the field
+      # @return [Field] The field you requested, if it exists
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields
+      # @example Get field 0123456789012345
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.field("0123456789012345")
+      def field(name, options={})
+        enhance( get("fields/#{name}", options), with: FieldMethods )
+      end
+
+      # Search fields
+      #
+      # @param search_term [String] The term to search for
+      # @return [Array] A list of fields matching the search term
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields
+      # @example Search for 'TEMPERATURE' in the fields
+      #   @client = CloudConnect::Client.new(:account => 'foor', :token => 'bar')
+      #   @client.search_fields
+      def search_fields(search_term, options={})
+        enhance( get("fields?q=#{search_term}", options), with: FieldMethods )
+      end
+
+      # Get fields
+      #
+      # @return [Array] A list of all fields
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields
+      # @example List all fields
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.fields
+      def fields(options={})
+        enhance( get("fields", options), with: FieldMethods )
+      end
+      alias :list_fields :fields
+
+      # Create a field
+      #
+      # @param name [String] Name of the field
+      # @param options [Hash] A customizable set of options
+      # @options options [Integer] :field ID of the field
+      # @options options [String] :field_type Type of the field: <tt>unknown</tt>, <tt>boolean</tt>, <tt>integer</tt>, <tt>decimal</tt>, <tt>string</tt>, or <tt>base64</tt>
+      # @options options [String] :size Size of the field
+      # @options options [String] :ack
+      # @options options [String] :description Description of the field
+      # @return [Field] Your newly created field
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields#create_a_new_field
+      # @example Create a new Field
+      #   @client = CloudConnect::CloudConnect.new(:account => 'foo', :token => 'bar')
+      #   @client.create_field("CUSTOM_SENSOR_TEMP", :field_type => 'integer', :size => 1, :description => "Custom sensor temp in Celsius")
+      def create_field(name, options={})
+        enhance( post("fields", options.merge({:name => name})), with: FieldMethods )
+      end
+
+      # Update an field
+      #
+      # @param name [String] Name of the field
+      # @param options [Hash] A customizable set of options
+      # @options options [Integer] :field ID of the field
+      # @options options [String] :field_type Type of the field: <tt>unknown</tt>, <tt>boolean</tt>, <tt>integer</tt>, <tt>decimal</tt>, <tt>string</tt>, or <tt>base64</tt>
+      # @options options [String] :size Size of the field
+      # @options options [String] :ack
+      # @options options [String] :description Description of the field
+      # @return [Field] Your newly updated field
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields#update_a_field
+      # @example Update a Field
+      #   @client = CloudConnect::CloudConnect.new(:account => 'foo', :token => 'bar')
+      #   @client.update_field("CUSTOM_SENSOR_TEMP", :field_type => 'integer', :size => 1, :description => "Custom sensor temp in Celsius")
+      def update_field(name, options={})
+        enhance( put("/fields/#{name}", options.merge({:name => name})), with: FieldMethods )
+      end
+
+      # Delete a single field
+      #
+      # @param name [String] Name fo the field
+      # @return [Response] A response object with status
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0006-fields#delete_a_field
+      # @example Delete the CUSTOM_SENSOR_TEMP field
+      #   @client = CloudConnect::CloudConnect.new(:account => 'foo', :token => 'bar')
+      #   @client.delete_field("CUSTOM_SENSOR_TEMP")
+      def delete_field(name, options={})
+        delete("fields/#{name}", options, true)
+      end
+
+      module FieldMethods
+        extend CustomMethods
       end
-      @fields = fields.sort_by(&:id)
     end
   end
 end

data/lib/cloud_connect/client/messages.rb

@@ -1,56 +1,68 @@
 module CloudConnect
-  module Messages
+  class Client
+    module Messages
+      # Get a message
+      #
+      # @param id [String] ID of the message
+      # @return [Message] The message you requested, if it exists
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0005-messages
+      # @example Get message 380342888036303061
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.message("380342888036303061")
+      def message(id, options={})
+        enhance( get("messages/#{id}", options), with: MessageMethods )
+      end
 
-    require 'open-uri'
+      # Search messages
+      #
+      # @param search_term [String] The term to search for
+      # @return [Array] A list of messages matching the search term
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0005-messages
+      # @example Search for '123' in the messages
+      #   @client = CloudConnect::Client.new(:account => 'foor', :token => 'bar')
+      #   @client.search_messages
+      def search_messages(search_term, options={})
+        enhance( get("messages?q=#{search_term}", options), with: MessageMethods )
+      end
 
-    # Returns all messages that match parameters provided in +opts+ list
-    # (if +opts+ is provided)
-    #
-    # @param [Hash] opts the options to filter the messages.
-    # @option opts [String] :ret ('id, time') Select attributes to fetch
-    # @option opts [String] :channelids List of channel ids
-    # @option opts [String] :messageids List of message ids
-    # @option opts [String] :unitids List of unit ids
-    # @option opts [String] :userids List of user ids
-    # @option opts [String] :status Message status
-    #   (0 (new), 1 (sent), 2 (received), 3 (failed))
-    # @option opts [String] :timedout (false) Include timed-out messages
-    # @option opts [String] :from Minimum date
-    # @option opts [String] :to Maximum date
-    # @option opts [String] :direction Message direction
-    #   (unittouser or usertounit)
-    # @option opts [String] :replyto List of reference message ids
-    # @option opts [Integer] :id_min Minimum ID
-    # @option opts [Integer] :id_max Maximum ID
-    # @option opts [Integer] :limit (25) Number of elements to fetch
-    # @return [Array<Hashie::Mash>] Messages
-    # @see http://develop.g8teway.com/p/messages.html#listing_messages
-    def messages(opts = {})
-      messages = connection.get(connection.build_url("messages", opts)).body
-      messages.map!{|hash| hash.values.first}
-    end
+      # Get messages from an asset
+      #
+      # @param imei [String] IMEI of the asset
+      # @return [Array] The messages you requested, if it exists
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0005-messages
+      # @example Get messages from the asset 351732050019192
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.asset_messages("351732050019192")
+      def asset_messages(imei, options={})
+        enhance( get("assets/#{imei}/messages", options), with: MessageMethods )
+      end
+
+      # Get all messages
+      #
+      # @return [Array] A list of all messages
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0005-messages
+      # @example List all messages
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.messages
+      def messages(options={})
+        enhance( get("messages", options), with: MessageMethods )
+      end
+      alias :list_messages :messages
+
+      # Send a message to the unit
+      #
+      # @param imei [String] IMEI of the asset
+      # @param channel [String] Channel for the message
+      # @param payload [String] Payload of the message to send
+      # @return [Message] The message
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0005-messages#push_a_message_to_an_asset
+      def send_message(imei, channel, payload, options={})
+        enhance( post("messages", options.merge({recipient: imei, asset: imei, channel: channel, b64_payload: Base64.encode64(payload)})), with: MessageMethods )
+      end
 
-    # Send a message to a specific device
-    #
-    # @param [Integer] unit
-    # @param [Integer] channel
-    # @param [String] content
-    # @param [Hash] opts
-    # @return [Hashie::Mash] The message
-    # @see http://develop.g8teway.com/p/messages.html#sending_a_new_message
-    def send_message(unit, channel, content, opts = {})
-      # TODO: rename #message_create ?
-      opts.merge! :channelid => channel, :unitid => unit, :content => content
-      response = connection.post do |req|
-        if version == "v1.5"
-          req.url 'ws?messagesend'
-          req.body = "unit=#{unit}&channel=#{channel}&content=#{URI::encode(content)}"
-        else
-          req.url 'messages'
-          req.body = {:message => opts}
-        end
+      module MessageMethods
+        extend CustomMethods
       end
-      response.body.values.first
     end
   end
 end

data/lib/cloud_connect/client/tracks.rb

@@ -0,0 +1,46 @@
+module CloudConnect
+  class Client
+    module Tracks
+
+      # Get a track
+      #
+      # @param id [String] ID of the track
+      # @return [Track] The track you requested, if it existsle ||
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0004-tracks
+      # @example Get track 0123456789012345
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.track("0123456789012345")
+      def track(id, options={})
+        enhance( get("tracks/#{id}", options), with: TrackMethods )
+      end
+
+      # Search tracks
+      #
+      # @param search_term [String] The term to search for
+      # @return [Array] A list of tracks matching the search term
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0004-tracks
+      # @example Search for '123' in the tracks
+      #   @client = CloudConnect::Client.new(:account => 'foor', :token => 'bar')
+      #   @client.search_tracks
+      def search_tracks(search_term, options={})
+        enhance( get("tracks?q=#{search_term}", options), with: TrackMethods )
+      end
+
+      # Get tracks
+      #
+      # @return [Array] A list of all tracks
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0004-messages
+      # @example List all tracks
+      #   @client = CloudConnect::Client.new(:account => 'foo', :token => 'bar')
+      #   @client.tracks
+      def tracks(options={})
+        enhance( get("tracks", options), with: TrackMethods )
+      end
+
+      alias :list_tracks :tracks
+      module TrackMethods
+        extend CustomMethods
+      end
+    end
+  end
+end

data/lib/cloud_connect/client.rb

@@ -1,66 +1,52 @@
+require 'cloud_connect/authentication'
+require 'cloud_connect/connection'
+require 'cloud_connect/request'
+
+require 'cloud_connect/client/custom_methods'
+require 'cloud_connect/client/assets'
+require 'cloud_connect/client/configurations'
+require 'cloud_connect/client/fields'
+require 'cloud_connect/client/channels'
+require 'cloud_connect/client/tracks'
+require 'cloud_connect/client/messages'
+
 module CloudConnect
   class Client
-    attr_reader :username, :password, :account, :env, :cookie, :version
-    attr_writer :cookie
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
 
     def initialize(options={})
-      @username = options[:username] || CloudConnect.username
-      @password = options[:password] || CloudConnect.password
-      @account  = options[:account]  || CloudConnect.account
-      @env      = options[:env]      || CloudConnect.env      || "prod"
-      @version  = options[:version]  || "v2"
-    end
-
-    # Raw HTTP connection, either Faraday::Connection
-    #
-    # @return [Faraday::Connection]
-    def connection
-      params = {}
-      params[:access_token] = @access_token if @access_token
-      @connection ||= Faraday::Connection.new(:url => api_url, :params => params, :headers => default_headers) do |builder|
-        builder.use Faraday::Request::CookieAuth, self
-        builder.adapter Faraday.default_adapter
-        builder.use Faraday::Response::RaiseHttp5xx
-        builder.use Faraday::Response::ParseJson
-        builder.use Faraday::Response::RaiseHttp4xx
-        builder.use Faraday::Response::Mashify
-        #builder.response :yajl     # Faraday::Request::Yajl
-      end
-    end
-
-    # Provides the URL for accessing the API
-    #
-    # @return [String]
-    def api_url
-      if env == "preprod"
-        "http://srv/api/v2"
-      else
-        "http://#{env}.g8teway.com/api/#{version}"
+      options = CloudConnect.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
       end
     end
 
-    def login
-      if version == "v1.5"
-        req = connection.post('ws?login', "username=#{username}&password=#{password}&client=#{account}")
-      else
-        req = connection.post('sessions', {:login => username, :password => password, :client => account})
+    def enhance(object, with_opts)
+      # @private
+      # Add custom methods to provided object(s).
+      # This method provides syntaxic suggar upon <tt>Module.apply_to(object)</tt>,
+      # allowing you to write <tt>enhance object, with: Module</tt>
+      #
+      # @param object [Object] An Object or Array of Objects to enhance.
+      # @param with_opts [Hash] Customizable set of options.
+      # @options with_opts [Module] :with Module to include.
+      # @return [Object] Enhanced initial object.
+      # @example Enhance an instance of Hashie::Mash with methods defined in the AssetMethods module
+      #   enhance( Hashie::Mash.new, :with => AssetMethods)
+      object.tap do |obj|
+        with_opts[:with].apply_to(obj, client: self)
       end
     end
 
-    private
-      # @private
-      def default_headers
-        headers = {
-          :accept =>  'application/json',
-          :user_agent => 'CloudClient Ruby gem'
-        }
-      end
+    include CloudConnect::Authentication
+    include CloudConnect::Connection
+    include CloudConnect::Request
 
-    include Units
-    include Users
-    include Channels
-    include Messages
-    include Fields
-    include Trackings
+    include CloudConnect::Client::Assets
+    include CloudConnect::Client::Configurations
+    include CloudConnect::Client::Fields
+    include CloudConnect::Client::Channels
+    include CloudConnect::Client::Tracks
+    include CloudConnect::Client::Messages
   end
 end

data/lib/cloud_connect/configuration.rb

@@ -0,0 +1,60 @@
+require 'faraday'
+require 'cloud_connect/version'
+
+module CloudConnect
+  module Configuration
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :faraday_config_block,
+      :api_version,
+      :api_url,
+      :api_path,
+      :account,
+      :token,
+      :proxy,
+      :request_host,
+      :user_agent,
+      :auto_traversal,
+      :per_page,
+    ].freeze
+
+    API_VERSION            = 3
+
+    DEFAULT_ADAPTER        = Faraday.default_adapter
+    DEFAULT_API_URL        = "cloudconnect.io"
+    API_PATH               = "/api/v#{API_VERSION}/"
+    DEFAULT_USER_AGENT     = "CloudConnect Ruby Gem #{CloudConnect::VERSION}".freeze
+    DEFAULT_AUTO_TRAVERSAL = false
+
+    attr_accessor(*VALID_OPTIONS_KEYS)
+
+    def self.extended(base)
+      base.reset
+    end
+
+    def configure
+      yield self
+    end
+
+    def options
+      VALID_OPTIONS_KEYS.inject({}){|o,k| o.merge!(k => send(k)) }
+    end
+
+    def faraday_config(&block)
+      @faraday_config_block = block
+    end
+
+    def reset
+      self.adapter        = DEFAULT_ADAPTER
+      self.api_version    = API_VERSION
+      self.api_url        = DEFAULT_API_URL
+      self.api_path       = API_PATH
+      self.account        = nil
+      self.token          = nil
+      self.proxy          = nil
+      self.request_host   = nil
+      self.user_agent     = DEFAULT_USER_AGENT
+      self.auto_traversal = DEFAULT_AUTO_TRAVERSAL
+    end
+  end
+end

data/lib/cloud_connect/connection.rb

@@ -0,0 +1,49 @@
+require 'faraday_middleware'
+require 'faraday/response/raise_cloud_connect_error'
+
+module CloudConnect
+  # @private
+  module Connection
+    private
+
+    def api_endpoint
+      File.join(@api_url, @api_path, "")
+    end
+
+    def url
+      url = "http://#{[account, api_endpoint].join('.')}"
+    end
+
+    def connection(raw=false, force_urlencoded=false)
+      options = {
+        :ssl => { :verify => false },
+        :url => url,
+      }
+
+      options[:proxy] = proxy unless proxy.nil?
+
+      # TODO: Don't build on every request
+      connection = Faraday.new(options) do |builder|
+        if !force_urlencoded
+          builder.request :json
+        else
+          builder.request :url_encoded
+        end
+
+        builder.use Faraday::Response::RaiseCloudConnectError
+
+        unless raw
+          builder.use FaradayMiddleware::Mashify
+          builder.use FaradayMiddleware::ParseJson
+        end
+
+        faraday_config_block.call(builder) if faraday_config_block
+
+        builder.adapter *adapter
+      end
+
+      connection.basic_auth authentication[:token], 'X'
+      connection
+    end
+  end
+end

data/lib/cloud_connect/error.rb

@@ -1,12 +1,34 @@
 module CloudConnect
+  # Custom error class for rescuing from all CloudConnect errors
   class Error < StandardError; end
-  class BadGateway < Error; end
+
+  # Raised when CloudConnect returns a 400 HTTP status code
   class BadRequest < Error; end
+
+  # Raised when CloudConnect returns a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised when CloudConnect returns a 403 HTTP status code
   class Forbidden < Error; end
-  class InternalServerError < Error; end
-  class NotAcceptable < Error; end
+
+  # Raised when CloudConnect returns a 404 HTTP status code
   class NotFound < Error; end
-  class ServiceUnavailable < Error; end
+
+  # Raised when CloudConnect returns a 406 HTTP status code
+  class NotAcceptable < Error; end
+
+  # Raised when CloudConnect returns a 422 HTTP status code
   class UnprocessableEntity < Error; end
-  class Unauthorized < Error; end
+
+  # Raised when CloudConnect returns a 500 HTTP status code
+  class InternalServerError < Error; end
+
+  # Raised when CloudConnect returns a 501 HTTP status code
+  class NotImplemented < Error; end
+
+  # Raised when CloudConnect returns a 502 HTTP status code
+  class BadGateway < Error; end
+
+  # Raised when CloudConnect returns a 503 HTTP status code
+  class ServiceUnavailable < Error; end
 end

data/lib/cloud_connect/notification/notification.rb

@@ -0,0 +1,78 @@
+require 'json'
+require 'base64'
+require 'faraday_middleware'
+require 'faraday/response/raise_cloud_connect_error'
+
+module CloudConnect
+  class Notification
+    module Notification
+
+      # Notification
+      #
+      # @param json [String] JSON of the POST request
+      # @return [Array] The fields from the json, deserialized and decoded
+      # @see http://wordsabout.it/mobile-devices/cloudconnect-user-documentation/cc-0013-notifications
+      # @example Notification
+      # @client = CloudConnect::Client.new(:account => 'foor', :token => 'bar')
+      # @client.notification(json)
+      def notification(json)
+        result = connection(false, false)
+        json = JSON.parse(json)
+        if json.class == [].class
+          mash = []
+          json.each do |obj|
+            mash << Hashie::Mash.new(obj)
+          end
+        else
+          mash = Hashie::Mash.new(json)
+        end
+        return parse_notification(mash)
+      end
+
+      alias :list_notification :notification
+
+      module NotificationMethods
+        extend CustomMethods
+      end
+
+      private
+
+      def decode_b64(b64, type)
+        if type == "string"
+          return Base64.decode64(b64)
+        elsif type == "integer"
+          decoded_value = 0
+          bytes = Base64.decode64(b64).bytes
+          for byte in bytes
+            decoded_value <<= 8
+            decoded_value += byte
+          end
+          decoded_value
+          return decoded_value
+        end
+      end
+
+      def decode_notification(mash)
+        if mash.meta.event == "message"
+          mash.payload.payload = decode_b64(mash.payload.b64_payload, "string")
+        elsif mash.meta.event == "track"
+          mash.payload.fields.each do |attr|
+            attr.last.b64_value = decode_b64(attr.last.b64_value, "integer")
+          end
+        end
+        return mash
+      end
+
+      def parse_notification(mashes)
+        if mashes.class == [].class
+          mashes.each do |mash|
+            mash = parse_notification(mash)
+          end
+          return mashes
+        else
+          return decode_notification(mashes)
+        end
+      end
+    end
+  end
+end

data/lib/cloud_connect/notification.rb

@@ -0,0 +1,43 @@
+require 'cloud_connect/authentication'
+require 'cloud_connect/connection'
+require 'cloud_connect/request'
+
+require 'cloud_connect/client/custom_methods'
+require 'cloud_connect/notification/notification'
+
+module CloudConnect
+  class Notification
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    def initialize(options={})
+      options = CloudConnect.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def enhance(object, with_opts)
+      # @private
+      # Add custom methods to provided object(s).
+      # This method provides syntaxic suggar upon <tt>Module.apply_to(object)</tt>,
+      # allowing you to write <tt>enhance object, with: Module</tt>
+      #
+      # @param object [Object] An Object or Array of Objects to enhance.
+      # @param with_opts [Hash] Customizable set of options.
+      # @options with_opts [Module] :with Module to include.
+      # @return [Object] Enhanced initial object.
+      # @example Enhance an instance of Hashie::Mash with methods defined in the AssetMethods module
+      #   enhance( Hashie::Mash.new, :with => AssetMethods)
+      object.tap do |obj|
+        with_opts[:with].apply_to(obj, client: self)
+      end
+    end
+
+    include CloudConnect::Authentication
+    include CloudConnect::Connection
+    include CloudConnect::Request
+
+    include CloudConnect::Notification::Notification
+
+  end
+end