adafruit-io 2.0.0.beta.7 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d4e361c9a85392c933fe7c35fda6bfd98f6f80cd
-  data.tar.gz: 9a68f813bfff5fedee4511bb6fcd7b940ebfb1e4
+  metadata.gz: c9d6fead5f73917e3333bd69c70965d1e4d23c31
+  data.tar.gz: 1cef173f825142a4ca7c7c4c3eeaf44d11fc1b7d
 SHA512:
-  metadata.gz: 730d7000307a9569797d6904f7fa5fba72e7cf6ec507b753fdad266584b1fed8bfdfbe29ae569f2d8b00fe129cf42f93687d1d202816a2944f457121a94f65a2
-  data.tar.gz: a61eb95bc77ff2aaab6d5893f9d16779e4d60acf1ab9612ba186e395bb73ab93c2e98af86f2f4fcbe518a44fa5f44c863ca12ac2fa3ed8a64ffd99a81ff2d75b
+  metadata.gz: ea27ad2d2ef07fcbcbde215ace2d8e2e46960eb8f05d9fc5d26d0186f9ee10519e80b832237f7793b472e7e8f26a3d760a440613fed3f7b78d05d0c8e7c9d57c
+  data.tar.gz: fbf7c7ef1880a396ceb5aa2e54e1bea2b345a8b610482f35bf3afab6db2c97615fb5e14a8b0f04c8f141dce71d6474dd00d64559c0798be70140bfc2856f6924

data/README.md

@@ -32,20 +32,22 @@ It is our goal to eventually support all API V2 methods, but that will happen in
 - [x] Activities `2.0.0.beta.5`
 - [x] Permissions `2.0.0.beta.5`
 - [x] Triggers `2.0.0.beta.6`
+- [x] Feeds `2.0.0`
+- [x] Data `2.0.0`
+- [x] Tokens `2.0.0`
+- [x] Blocks `2.0.0`
+- [x] Dashboards `2.0.0`
+- [x] Groups `2.0.0`
+- [x] Activities `2.0.0`
+- [x] Permissions `2.0.0`
+- [x] Triggers `2.0.0`
 
 Still needing complete tests:
 
-- [x] Feeds
-- [x] Data
-- [x] Tokens
-- [x] Blocks
-- [ ] Dashboards *has pending*
-- [ ] Groups *has pending*
-- [ ] Activities
-- [ ] Permissions
-- [ ] Triggers
 - [ ] MQTT
 
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -60,9 +62,12 @@ Or install it yourself as:
 
     $ gem install adafruit-io
 
+
+
 ## Basic Usage
 
-Each time you use the library, you'll want to pass your [AIO Key][4] to the client.
+Each time you use the library, you'll have to pass your [Adafruit IO Key][4] to the client.
+
 
 ```ruby
 require 'adafruit/io'
@@ -73,6 +78,7 @@ aio = Adafruit::IO::Client.new key: 'KEY'
 
 Since every API request requires a username, you can also pass a username to the client initializer to use it for every request.
 
+
 ```ruby
 require 'adafruit/io'
 
@@ -80,15 +86,50 @@ require 'adafruit/io'
 aio = Adafruit::IO::Client.new key: 'KEY', username: 'USERNAME'
 ```
 
-All return values are plain Ruby hashes based on the JSON response returned by the API. Most basic requests should get back a Hash with a `key` field. The key can be used in subsequent requests. API requests that return a list of objects will return a simple array of hashes. Feeds, Groups, and Dashboards all rely on the `key` value, other endpoints (Blocks, Permissions, Tokens, Triggers) use `id`.
+
+
+### Environment Variables
+
+Whenever possible, we recommend you keep your Adafruit IO API credentials out of your application code by using environment variables. All the examples
+
+[Others](http://blog.honeybadger.io/ruby-guide-environment-variables/) have written about using environment variables in Ruby, so we're not going to go into detail. We recommend the [dotenv](https://github.com/bkeepers/dotenv) gem if you're building a Ruby project.
+
+
+
+### API Response Values
+
+All return values are **plain Ruby hashes** based on the JSON response returned by the API. Most basic requests should get back a Hash with a `key` field. The key can be used in subsequent requests. API requests that return a list of objects will return a simple array of hashes. Feeds, Groups, and Dashboards all rely on the `key` value, other endpoints (Blocks, Permissions, Tokens, Triggers) use `id`.
+
+You can find the current API documentation at [https://io.adafruit.com/api/docs/](https://io.adafruit.com/api/docs/). This library implements v2 of the Adafruit IO API.
+
+
+
+### API Error Responses
+
+As of **v2.0.0**, this library raises an `Adafruit::IO::RequestError` on any non HTTP 200 status responses. Generally, this means your code should wrap API calls in `begin...rescue...end` blocks.
+
+```ruby
+require 'adafruit/io'
+
+api_key = ENV['IO_KEY']
+username = ENV['IO_USER']
+
+api = Adafruit::IO::Client.new key: api_key, username: username
+
+
+
+```
+
+## Example
 
 Here's an example of creating, adding data to, and deleting a feed.
 
+
 ```ruby
 require 'adafruit/io'
 
-api_key = ENV['AIO_KEY']
-username = ENV['AIO_USER']
+api_key = ENV['IO_KEY']
+username = ENV['IO_USER']
 
 api = Adafruit::IO::Client.new key: api_key, username: username
 
@@ -120,19 +161,25 @@ puts "read?"
 puts api.feed(garbage['key']).inspect
 ```
 
+
+This code and more is available in [the examples/ directory](examples/).
+
 ## License
 
-Copyright (c) 2017 Adafruit Industries. Licensed under the MIT license.
+Copyright (c) 2018 Adafruit Industries. Licensed under the MIT license.
 
 [Adafruit](https://adafruit.com) invests time and resources providing this open source code. Please support Adafruit and open-source hardware by purchasing products from [Adafruit](https://adafruit.com).
 
 ## Contributing
 
 1. Fork it ( http://github.com/adafruit/io-client-ruby/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 new Pull Request
+1. Create your feature branch (`git checkout -b my-new-feature`)
+1. Write tests, write code, and run the tests (`bundle exec rspec`)
+1. Commit your changes (`git commit -am 'Add some feature'`)
+1. Push to the branch (`git push origin my-new-feature`)
+1. Create a new Pull Request
+
+If you'd like to contribute and don't know where to start, [reach out on the Adafruit IO forum](https://forums.adafruit.com/viewforum.php?f=56) or in the [adafruit-io channel on our Discord server](https://discord.gg/adafruit).
 
 [1]: https://www.ruby-lang.org
 [2]: https://io.adafruit.com

data/lib/adafruit/io/client/dashboards.rb

@@ -40,6 +40,14 @@ module Adafruit
 
           put api_url(username, 'dashboards', dashboard_key), query
         end
+
+        def update_dashboard_layouts(*args)
+          username, arguments = extract_username(args)
+          dashboard_key = get_key_from_arguments(arguments)
+          query = get_query_from_arguments(arguments, %w(layouts))
+
+          post api_url(username, 'dashboards', dashboard_key, 'update_layouts'), query
+        end
       end
     end
   end

data/lib/adafruit/io/client/permissions.rb

@@ -2,6 +2,7 @@ module Adafruit
   module IO
     class Client
       module Permissions
+        VALID_TYPES = %(feed group dashboard)
 
         # Get all permissions for a resource.
         #
@@ -9,40 +10,62 @@ module Adafruit
         def permissions(*args)
           username, arguments = extract_username(args)
 
-          if arguments.size < 2
-            raise 'permissions requires model type (string) and model key (string) values. valid types are feeds, groups, or dashboards'
-          end
+          assert_argument_size(arguments, 2)
+          assert_resource_type(arguments[0])
 
-          get api_url(username, arguments[0], arguments[1], 'acl')
+          get api_url(username, pluralize_type(arguments[0]), arguments[1], 'acl')
         end
 
         def permission(*args)
           username, arguments = extract_username(args)
 
-          if arguments.size < 3
-            raise 'permission requires model type (string), model key (string), and id (integer) values. valid types are feeds, groups, or dashboards'
-          end
+          assert_argument_size(arguments, 3)
+          assert_resource_type(arguments[0])
 
-          get api_url(username, arguments[0], arguments[1], 'acl', arguments[2])
+          get api_url(username, pluralize_type(arguments[0]), arguments[1], 'acl', arguments[2])
         end
 
         def create_permission(*args)
           username, arguments = extract_username(args)
-          if arguments.size < 3
-            raise 'permission requires model type (string), model key (string), and id (integer) values. valid types are feeds, groups, or dashboards'
-          end
+
+          assert_argument_size(arguments, 2)
+          assert_resource_type(arguments[0])
+
           permission_attrs = arguments.pop
-          post api_url(username, arguments[0], arguments[1], 'acl'), permission_attrs
+          post api_url(username, pluralize_type(arguments[0]), arguments[1], 'acl'), permission_attrs
         end
 
         def delete_permission(*args)
           username, arguments = extract_username(args)
 
-          if arguments.size < 3
-            raise 'permission requires model type (string), key (string), and id (integer) values. valid types are feeds, groups, or dashboards'
+          assert_argument_size(arguments, 3)
+          assert_resource_type(arguments[0])
+
+          delete api_url(username, pluralize_type(arguments[0]), arguments[1], 'acl', arguments[2])
+        end
+
+        private
+
+        def assert_resource_type(resource_type)
+          if !VALID_TYPES.include?(resource_type)
+            raise Adafruit::IO::Arguments::ArgumentError.new('permission resource type must be one of: feed, group, or dashboard')
+          end
+        end
+
+        def assert_argument_size(arguments, size)
+          if size === 3
+            if arguments.size < 3
+              raise Adafruit::IO::Arguments::ArgumentError.new('permission requires resource type (string), key (string), and permission id (integer) values. valid types are feeds, groups, or dashboards')
+            end
+          elsif size == 2
+            if arguments.size < size
+              raise Adafruit::IO::Arguments::ArgumentError.new('permissions requires resource type (string) and resource key (string) values. valid types are feed, group, or dashboard')
+            end
           end
+        end
 
-          delete api_url(username, arguments[0], arguments[1], 'acl', arguments[2])
+        def pluralize_type(resource_type)
+          "#{resource_type}s"
         end
       end
     end

data/lib/adafruit/io/client/triggers.rb

@@ -38,7 +38,7 @@ module Adafruit
           trigger_id = get_id_from_arguments(arguments)
           attrs = valid_trigger_attrs(arguments)
 
-          put api_url(username, 'triggers', feed_key), query
+          put api_url(username, 'triggers', trigger_id), attrs
         end
 
         private

data/lib/adafruit/io/mqtt.rb

@@ -95,11 +95,18 @@ module Adafruit
 
       # Subscribe to the feed with the given key. Use .get to retrieve messages
       # from subscribed feeds.
-      def subscribe(key)
+      #
+      # Include the { last_value: true } option if you'd like the feed to
+      # receive the last value immediately. (like MQTT retain)
+      def subscribe(key, options={})
         raise 'client is not connected' unless @client.connected?
 
         topic = key_to_feed_topic(key)
         @client.subscribe(topic)
+
+        if options[:last_value]
+          @client.publish(topic + '/get', '')
+        end
       end
 
       def unsubscribe(key)
@@ -143,15 +150,21 @@ module Adafruit
       #     # do something
       #   end
       #
-      # NOTE: if a feed already has a value, subscribing and calling get will
-      # immediately return the most recent value for the subscription,
-      # regardless of when it was received by IO.
       def get(&block)
         @client.get(&block)
       end
 
       private
 
+      def encode_json(record)
+        begin
+          JSON.generate record
+        rescue JSON::GeneratorError => ex
+          puts "failed to generate JSON from record: #{record.inspect}"
+          raise ex
+        end
+      end
+
       def key_to_feed_topic(key)
         "%s/f/%s" % [@options[:username], key]
       end
@@ -169,7 +182,7 @@ module Adafruit
           end
         end
 
-        JSON.generate payload
+        encode_json payload
       end
 
       def payload_from_values_with_location(values, location)
@@ -183,7 +196,7 @@ module Adafruit
           end
         end
 
-        JSON.generate payload
+        encode_json payload
       end
 
       def indifferent_keys(hash)

data/lib/adafruit/io/request_handler.rb

@@ -2,6 +2,15 @@ require 'open-uri'
 
 module Adafruit
   module IO
+    class RequestError < StandardError
+      attr_reader :response
+
+      def initialize(message, response)
+        super(message)
+        @response = response
+      end
+    end
+
     module RequestHandler
 
       attr_reader :last_response, :pagination
@@ -70,11 +79,7 @@ module Adafruit
         update_pagination(response)
 
         if response.status < 200 || response.status > 299
-          if response.status === 404
-            nil
-          else
-            raise "GET error: #{ response.body }"
-          end
+          raise Adafruit::IO::RequestError.new("GET error: #{ response.body }", response)
         else
           parsed_response response
         end
@@ -87,7 +92,7 @@ module Adafruit
         end
 
         if response.status < 200 || response.status > 299
-          raise "POST error: #{ response.body }"
+          raise Adafruit::IO::RequestError.new("POST error: #{ response.body }", response)
         else
           parsed_response response
         end
@@ -100,7 +105,7 @@ module Adafruit
         end
 
         if response.status < 200 || response.status > 299
-          raise "PUT error: #{ response.body }"
+          raise Adafruit::IO::RequestError.new("PUT error: #{ response.body }", response)
         else
           parsed_response response
         end
@@ -115,7 +120,7 @@ module Adafruit
           if response.status === 404
             nil
           else
-            raise "DELETE error: #{ response.body }"
+            raise Adafruit::IO::RequestError.new("DELETE error: #{ response.body }", response)
           end
         else
           parsed_response response

data/lib/adafruit/io/version.rb

@@ -1,5 +1,5 @@
 module Adafruit
   module IO
-    VERSION = "2.0.0.beta.7"
+    VERSION = "2.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: adafruit-io
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.7
+  version: 2.0.0
 platform: ruby
 authors:
 - Justin Cooper
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-02 00:00:00.000000000 Z
+date: 2018-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -138,9 +138,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.2