helium-ruby 0.20.0 → 0.21.0

data/docs/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.9.3
+    &mdash; Documentation by YARD 0.9.5
   
 </title>
 
@@ -102,9 +102,9 @@
 </div>
 
       <div id="footer">
-  Generated on Thu Sep  1 16:28:30 2016 by
+  Generated on Thu Jan 12 15:58:34 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.3 (ruby-2.3.1).
+  0.9.5 (ruby-2.3.1).
 </div>
 
     </div>

data/lib/helium.rb

@@ -7,7 +7,9 @@ require "helium/error"
 require "helium/utils"
 require "helium/client"
 require "helium/cursor"
+require "helium/collection"
 require "helium/resource"
+require "helium/metadata"
 require "helium/user"
 require "helium/organization"
 require "helium/sensor"

data/lib/helium/client/configurations.rb

@@ -10,18 +10,6 @@ module Helium
         Configuration.find(id, client: self)
       end
 
-      def config_device_configurations(id)
-        path = "/configuration/#{id}/device-configuration"
-        response = get(path)
-        device_confs_data = JSON.parse(response.body)["data"]
-
-        device_confs = device_confs_data.map do |dc|
-          DeviceConfiguration.new(client: self, params: dc)
-        end
-
-        return device_confs
-      end
-
       # Configurations are immutable, so no updates are available
       def create_configuration(attributes)
         Configuration.create(attributes, client: self)

data/lib/helium/client/elements.rb

@@ -9,18 +9,6 @@ module Helium
         Element.find(id, client: self)
       end
 
-      def element_sensors(element)
-        path = "/element/#{element.id}/sensor"
-        response = get(path)
-        sensors_data = JSON.parse(response.body)["data"]
-
-        sensors = sensors_data.map do |sensor|
-          Sensor.new(client: self, params: sensor)
-        end
-
-        return sensors
-      end
-
       def element_device_configuration(element)
         path = "/element/#{element.id}/device-configuration"
         response = get(path)

data/lib/helium/client/labels.rb

@@ -13,18 +13,7 @@ module Helium
         Label.create(attributes, client: self)
       end
 
-      def label_sensors(label)
-        path = "/label/#{label.id}/sensor"
-        response = get(path)
-        sensors_data = JSON.parse(response.body)["data"]
-
-        sensors = sensors_data.map do |sensor_data|
-          Sensor.new(client: self, params: sensor_data)
-        end
-
-        return sensors
-      end
-
+      # TODO incorporate this logic into Helium::Collection
       def update_label_sensors(label, opts = {})
         sensors = opts.fetch(:sensors, [])
 

data/lib/helium/client/organizations.rb

@@ -2,53 +2,7 @@ module Helium
   class Client
     module Organizations
       def organization
-        response = get('/organization')
-        org_data = JSON.parse(response.body)["data"]
-        return Organization.new(client: self, params: org_data)
-      end
-
-      def organization_users
-        response = get('/organization/user')
-        users_data = JSON.parse(response.body)["data"]
-
-        users = users_data.map do |user_data|
-          User.new(client: self, params: user_data)
-        end
-
-        return users
-      end
-
-      def organization_labels
-        response = get('/organization/label')
-        labels_data = JSON.parse(response.body)["data"]
-
-        labels = labels_data.map do |label_data|
-          Label.new(client: self, params: label_data)
-        end
-
-        return labels
-      end
-
-      def organization_elements
-        response = get('/organization/element')
-        elements_data = JSON.parse(response.body)["data"]
-
-        elements = elements_data.map do |element_data|
-          Element.new(client: self, params: element_data)
-        end
-
-        return elements
-      end
-
-      def organization_sensors
-        response = get('/organization/sensor')
-        sensors_data = JSON.parse(response.body)["data"]
-
-        sensors = sensors_data.map do |sensor_data|
-          Sensor.new(client: self, params: sensor_data)
-        end
-
-        return sensors
+        Organization.singleton(client: self)
       end
     end
   end

data/lib/helium/client/sensors.rb

@@ -18,18 +18,6 @@ module Helium
         return element
       end
 
-      def sensor_labels(sensor)
-        path = "/sensor/#{sensor.id}/label"
-        response = get(path)
-        labels_data = JSON.parse(response.body)["data"]
-
-        labels = labels_data.map do |label|
-          Label.new(client: self, params: label)
-        end
-
-        return labels
-      end
-
       def sensor_device_configuration(sensor)
         path = "/sensor/#{sensor.id}/device-configuration"
         response = get(path)

data/lib/helium/client/users.rb

@@ -2,9 +2,7 @@ module Helium
   class Client
     module Users
       def user
-        response = get('/user')
-        user_data = JSON.parse(response.body)["data"]
-        return User.new(client: self, params: user_data)
+        User.singleton(client: self)
       end
     end
   end

data/lib/helium/collection.rb

@@ -0,0 +1,129 @@
+module Helium
+  class Collection
+    include Enumerable
+
+    attr_reader :filter_criteria
+
+    def initialize(opts)
+      @client     = opts.fetch(:client)
+      @klass      = opts.fetch(:klass)
+      @belongs_to = opts.fetch(:belongs_to, nil)
+
+      @filter_criteria = {}
+    end
+
+    # Returns all resources
+    # @option opts [Client] :client A Helium::Client
+    # @return [Helium::Collection] a Collection of all of the given Resource
+    def all
+      @filter_criteria = {}
+      self
+    end
+
+    # Uses metadata filtering
+    # (https://docs.helium.com/api/v1/metadata/index.html#filtering)
+    # to search for a collection of resources matching the search parameters
+    # @param [Hash] a set of search criteria
+    #
+    # @example Search for sensors by location
+    #   client.sensors.where(location: 'Building B') #=> [Sensor, Sensor]
+    #
+    # @example Search for multiple matching search parameters
+    #   client.sensors.where(departments: ['it', 'engineering']) #=> [Sensor, Sensor]
+    #
+    # @return [Collection] a Collection of resources matching the provided search criteria
+    def where(criteria)
+      add_filter_criteria(criteria)
+      self
+    end
+
+    # Returns an array of the Resources belonging to the Collection
+    # @return [Resource]
+    def collection
+      fetch_collection
+    end
+
+    def each
+      collection.each{ |element| yield element }
+    end
+
+    def inspect
+      collection
+    end
+
+    def to_json(*options)
+      collection.to_json(*options)
+    end
+
+    # TODO: could support something like label.sensors << new_sensor
+    # see Label#add_sensors for where it would be applied
+    def +(other)
+      collection + other
+    end
+
+    def -(other)
+      collection - other
+    end
+
+    def [](index)
+      collection[index]
+    end
+
+    # Collections are considered equal if they contain the same resources
+    # as determined by the resources' ids
+    def ==(other)
+      self.map(&:id).sort == other.map(&:id).sort
+    end
+
+    # NOTE: if we implement pagination, we'll need to rethink this
+    def last
+      collection.last
+    end
+
+    protected
+
+    def add_filter_criteria(criteria)
+      criteria.each do |key, value|
+        if existing_value = @filter_criteria[key]
+          @filter_criteria[key] = (Array(existing_value) + Array(value)).uniq
+        else
+          @filter_criteria[key] = value
+        end
+      end
+    end
+
+    def fetch_collection
+      response = @client.get(resource_path)
+      return collection_from_response(response)
+    end
+
+    def filter_param
+      "filter[metadata]=#{@filter_criteria.to_json}"
+    end
+
+    def resource_path
+      uri = if @belongs_to
+              URI.parse("#{@belongs_to.resource_path}/#{@klass.resource_name}")
+            else
+              URI.parse(@klass.all_path)
+            end
+
+      if @filter_criteria.any?
+        uri.query = [uri.query, filter_param].compact.join('&')
+      end
+
+      uri.to_s
+    end
+
+    def collection_from_response(response)
+      resources_data = JSON.parse(response.body)["data"]
+
+      resources = resources_data.map do |resource_data|
+        @klass.new(client: @client, params: resource_data)
+      end
+
+      return resources
+    end
+
+  end
+end

data/lib/helium/configuration.rb

@@ -8,7 +8,11 @@ module Helium
     end
 
     def device_configurations
-      @client.config_device_configurations(self.id)
+      Collection.new(
+        klass: DeviceConfiguration,
+        client: @client,
+        belongs_to: self
+      )
     end
 
   end

data/lib/helium/element.rb

@@ -11,7 +11,7 @@ module Helium
     end
 
     def sensors
-      @client.element_sensors(self)
+      Collection.new(klass: Sensor, client: @client, belongs_to: self)
     end
 
     def device_configuration

data/lib/helium/label.rb

@@ -8,10 +8,8 @@ module Helium
       @name = @params.dig("attributes", "name")
     end
 
-    # TODO: would be nice to wrap this in a proxy collection, that way
-    # we could do something like label.sensors << new_sensor
     def sensors
-      @client.label_sensors(self)
+      Collection.new(klass: Sensor, client: @client, belongs_to: self)
     end
 
     def add_sensors(sensors_to_add = [])

data/lib/helium/metadata.rb

@@ -0,0 +1,58 @@
+module Helium
+  # TODO make Metadata inherit from Resource and implement method_missing
+  # for all resources to automatically generate methods for attributes
+  # rather than whitelisting them with hardcoding
+  class Metadata
+    def initialize(opts = {})
+      @client = opts.fetch(:client)
+      @klass  = opts.fetch(:klass)
+
+      @params = fetch_params
+    end
+
+    def id
+      @klass.id
+    end
+
+    def properties
+      @params["attributes"]
+    end
+
+    def inspect
+      "<Helium::Metadata properties=#{properties}>"
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      properties[method_name.to_s] || super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      properties[method_name.to_s] || super
+    end
+
+    def update(attributes = {})
+      body = {
+        data: {
+          attributes: attributes,
+          id: id,
+          type: "metadata"
+        }
+      }
+
+      response = @client.patch(path, body: body)
+      @params = JSON.parse(response.body)["data"]
+      return self
+    end
+
+    protected
+
+    def path
+      "#{@klass.resource_path}/metadata"
+    end
+
+    def fetch_params
+      response = @client.get(path)
+      JSON.parse(response.body)["data"]
+    end
+  end
+end

data/lib/helium/organization.rb

@@ -15,19 +15,19 @@ module Helium
 
     # TODO refactor into relationships
     def users
-      @client.organization_users
+      Collection.new(klass: User, client: @client, belongs_to: self)
     end
 
     def labels
-      @client.organization_labels
+      Collection.new(klass: Label, client: @client, belongs_to: self)
     end
 
     def elements
-      @client.organization_elements
+      Collection.new(klass: Element, client: @client, belongs_to: self)
     end
 
     def sensors
-      @client.organization_sensors
+      Collection.new(klass: Sensor, client: @client, belongs_to: self)
     end
 
     def as_json

data/lib/helium/resource.rb

@@ -17,28 +17,15 @@ module Helium
     class << self
       include Helium::Utils
 
-      # NOTE seems a bit out of place to be doing client work here, but it
-      # makes sense for the Eigenclass to be responsible for constructing
-      # instances of its inheriting class.
+      # The resource's index API route
+      # @return [String] path to resource's index
+      def all_path
+        "/#{resource_name}"
+      end
 
-      # Returns all resources
-      # @option opts [Client] :client A Helium::Client
-      # @return [Array<Resource>] an Array of all of the inheriting Resource
       def all(opts = {})
         client = opts.fetch(:client)
-
-        response = client.get(all_path)
-        resources_data = JSON.parse(response.body)["data"]
-
-        resources = resources_data.map do |resource_data|
-          self.new(client: client, params: resource_data)
-        end
-
-        return resources
-      end
-
-      def all_path
-        "/#{resource_name}"
+        Collection.new(klass: self, client: client).all
       end
 
       # Finds a single Resource by id
@@ -47,11 +34,15 @@ module Helium
       # @return [Resource]
       def find(id, opts = {})
         client = opts.fetch(:client)
+        initialize_from_path(path: "/#{resource_name}/#{id}", client: client)
+      end
 
-        response = client.get("/#{resource_name}/#{id}")
-        resource_data = JSON.parse(response.body)["data"]
-
-        return self.new(client: client, params: resource_data)
+      # Fetches a singleton resource (e.g. organization, user)
+      # @option opts [Client] :client A Helium::Client
+      # @return [Resource] A singleton resource
+      def singleton(opts = {})
+        client = opts.fetch(:client)
+        initialize_from_path(path: all_path, client: client)
       end
 
       # Creates a new resource with given attributes
@@ -76,11 +67,18 @@ module Helium
         return self.new(client: client, params: resource_data)
       end
 
-      private
-
       def resource_name
         kebab_case(self.name.split('::').last)
       end
+
+      def initialize_from_path(opts = {})
+        client = opts.fetch(:client)
+        path = opts.fetch(:path)
+
+        response = client.get(path)
+        resource_data = JSON.parse(response.body)["data"]
+        return self.new(client: client, params: resource_data)
+      end
     end # << self
 
     # Returns a path identifying the current resource. Can be overridden
@@ -111,8 +109,11 @@ module Helium
     # Deletes the Resource
     # @return [Boolean] Whether the operation was successful
     def destroy
-      path = "/#{resource_name}/#{self.id}"
-      @client.delete(path)
+      @client.delete(resource_path)
+    end
+
+    def metadata
+      Metadata.new(client: @client, klass: self)
     end
 
     # Override equality to use id for comparisons
@@ -161,8 +162,6 @@ module Helium
       as_json.to_json(*options)
     end
 
-    private
-
     def resource_name
       kebab_case(self.class.name.split('::').last)
     end