particlerb 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 42903b63b82b54886a0445733da1e7a61a3dffad
-  data.tar.gz: 2b70acdb2e5a7543d15e6f87c4885544c199c4f5
+  metadata.gz: 60ae309f5efa8ed76934ccce2800ab84ff2e73d0
+  data.tar.gz: 80294252d1049858593e5dadb97a9d9740f1fbf8
 SHA512:
-  metadata.gz: cc343874fa16fba14def9c184e153b1d077e61adb5e8109370cb6e4f1ecf1ac9dae056918cf262c7550753accdbd637b607adbbe7d97a7653af9cb234eb3a753
-  data.tar.gz: 1d6bd48d026c95289e6429bb62e454490f9a83621870404ec0c59afa9f598c2473cece8e88092c44ece31257da3bb09590d54651d873887e6c27de718b2ed5ca
+  metadata.gz: d70c2a7ef5356f444cc468b344cf19e457fc7dbcebe4195b56caab4406f031f9e812bd104586ca878f26962a28f51685238429d3e40649556eafcb2140ef5618
+  data.tar.gz: 7013f5fcb31f8eb05c19ba6ab527173d0d1b0438d0747fa254d1b4c52c5822d5c9c02633340d10660e9fe1079aab597e2c5a2a0a98bd2d57fb32a47b397533e8

data/README.md

@@ -18,7 +18,7 @@ Ruby client for the [Particle.io] Cloud API with an object-oriented interface
 $ gem install particlerb
 
 # or add to your Gemfile
-gem "particlerb", "~> 0.0.3"
+gem "particlerb", "~> 1.4.0"
 
 # Require the gem
 require 'particle'
@@ -62,8 +62,8 @@ client.devices
 
 When using this gem in a multi-threaded program like a Rails application running on the puma server, it's safer to use `Particle::Client.new` in each thread rather than using the global  `Particle.client`.
 
-[Web IDE]: http://docs.particle.io/core/build/#flash-apps-with-particle-build-account-information
-[Particle CLI]: http://docs.particle.io/core/cli
+[Web IDE]: https://docs.particle.io/guide/getting-started/build
+[Particle CLI]: https://docs.particle.io/reference/cli
 
 ## Interacting with devices
 
@@ -139,6 +139,12 @@ device.variable('version') # ==> "1.0.1"
 device.get('version') # aliased as get
 ```
 
+Ping a device to see if it is online. Returns true when online.
+
+```ruby
+Particle.device('nyan_cat').ping
+```
+
 Signal a device to start blinking the RGB LED in rainbow patterns. Returns whether the device is signaling.
 
 ```ruby
@@ -153,12 +159,6 @@ device = Particle.provision_device(product_id: 31)
 device.claim
 ```
 
-Change the product id. The meaning of the product id is specific to your application and account.
-
-```ruby
-Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d').change_product(3)
-```
-
 Update the public key for a device. The public key must be in PEM format. See <spec/fixtures/device.pub.pem> for an example.
 
 ```ruby
@@ -168,7 +168,7 @@ Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d').update_public_key(pu
 
 See the [Particle Cloud API documentation about devices][device docs] for more details.
 
-[device docs]: http://docs.particle.io/core/api/#introduction-device-information
+[device docs]: https://docs.particle.io/reference/api/#devices
 
 ## Interacting with events
 
@@ -185,7 +185,7 @@ Data is converted to JSON if it is a Hash or an Array, otherwise it is converted
 
 See the [Particle Cloud API documentation about publishing events][publish docs] for more details.
 
-[publish docs]: http://docs.particle.io/core/api/#publishing-events
+[publish docs]: https://docs.particle.io/reference/api/#publish-an-event
 
 ### Limitation: Subscribe not supported
 
@@ -255,8 +255,8 @@ Particle.webhooks.each(&:remove) # remove all
 
 See the [Particle Cloud API documentation about webhooks][webhook docs] for more details.
 
-[webhook docs]: http://docs.particle.io/core/webhooks/
-[webhook options]: http://docs.particle.io/core/webhooks/#webhook-options
+[webhook docs]: https://docs.particle.io/reference/webhooks
+[webhook options]: https://docs.particle.io/reference/webhooks/#webhook-properties
 
 ## Authentication
 
@@ -294,6 +294,9 @@ Particle.token.create("me@example.com", "pa$$w0rd")
 
 * `expires_in`: number of seconds that the token will be valid
 * `expires_at`: `Date` when the token will become invalid
+* `client`: a Particle OAuth client to use. Defaults to `particle`.
+* `secret`: the corresponding OAuth secret. Defaults to `particle`.
+* `grant_type`: Type of OAuth authentication flow to use. Defaults to 'password'
 
 Invalidate and delete a token. Returns true on success.
 
@@ -304,7 +307,7 @@ Particle.tokens.first.remove("me@example.com", "pa$$w0rd")
 
 See the [Particle Cloud API documentation about authentication and token][authentication docs] for more details.
 
-[authentication docs]: http://docs.particle.io/core/api/#introduction-authentication
+[authentication docs]: https://docs.particle.io/reference/api/#authentication
 
 ## Compiling and flashing
 
@@ -343,8 +346,60 @@ File.new('application.bin', 'w') { |f| f.write(binary) }
 
 See the [Particle Cloud API documentation about firmware][firmware docs] for more details.
 
-[firmware docs]: http://docs.particle.io/core/api/#basic-functions-verifying-and-flashing-new-firmware
+[firmware docs]: https://docs.particle.io/reference/api/#firmware
+
+## Libraries
+
+Interact with firmware libraries.
+
+List most popular libraries. Response array has pagination.
+
+```ruby
+libs = Particle.libraries
+libs.each { |lib| puts lib.name }
+libs.next_page if libs.has_next?
+
+libs = Particle.libraries name: "gps"
+```
+
+Get details about a library.
+
+```ruby
+lib = Particle.library("internet_button")
+puts "#{lib.name}@#{lib.version}: #{lib.sentence}"
+```
+
+See the [Particle Cloud API documentation about libraries][library docs] for more details.
+
+[library docs]: https://docs.particle.io/reference/api/#libraries
+
+## OAuth Clients
+
+Interact with OAuth clients used to authenticate requests with the Particle cloud. See [Authentication](#authentication).
+
+List OAuth clients. Returns an `Array` of `Particle::OAuthClinet`.
+
+```ruby
+clients = Particle.oauth_clients
+clients.each { |client| puts client.id }
+```
+
+Create an OAuth client. Returns a `Particle::OAuthClient`. Note that
+this is the only time that the `secret` attribute will be returned by
+the Particle API.
 
+```ruby
+client = Particle.create_oauth_client(name: "my-client", type: "installed")
+puts "OAuth client ID: #{client.id} OAuth client secret: #{client.secret}"
+```
+
+Remove an OAuth client by id. Returns `true` on success.
+
+```ruby
+Particle.remove_oauth_client("my-client-1234")
+client = Particle.oauth_clients.first
+client.remove
+```
 
 ## Errors
 
@@ -364,7 +419,43 @@ See [a description of each error on the Particle API docs][error docs].
 
 This gem uses the Faraday HTTP client library, so API call may raise `Faraday::ClientError` for things like SSL errors, DNS errors, HTTP connection timed out.
 
-[error docs]: http://docs.particle.io/core/api/#introduction-errors
+[error docs]: https://docs.particle.io/reference/api/#errors
+
+## TODO
+
+Some Particle API endpoints are not implemented yet
+
+List devices in a product
+
+Import devices into a product
+
+Remove a device from a product
+
+Update an OAuth client
+
+Add device notes
+
+Create a device claim code
+
+Request a device transfer
+
+Approve/deny a quarantined device
+
+All SIM card endpoints (list, data usage, activate, deactivate, set data limit, release from account)
+
+Integrations that are not webhooks
+
+All product firmware endpoints (list, get, upload, edit, download, release)
+
+Get library versions
+
+Upload library
+
+Publish library
+
+Main product endpoints (list, get, invite team member, remove team member)
+
+**Product functionality for many of the existing endpoints like device, firmware, etc**
 
 ## Advanced
 
@@ -401,6 +492,8 @@ Set the following environment variables:
 - `TEST_PARTICLE_PASSWORD`: your Particle password
 - `TEST_PARTICLE_ACCESS_TOKEN`: a Particle access token. You can get this from the web IDE
 - `TEST_PARTICLE_DEVICE_IDS`: a comma separated list of your device ids. You can get this from the Particle CLI `particle list`
+- `TEST_PARTICLE_OAUTH_CLIENT`: a valid Particle OAuth client
+- `TEST_PARTICLE_OAUTH_SECRET`: the corresponding OAuth secret
 
 Make sure **the first Particle device in `TEST_PARTICLE_DEVICE_IDS` is online** and run
 

data/lib/particle/build_target.rb

@@ -22,6 +22,10 @@ module Particle
       super(client, attributes)
     end
     attribute_reader :platforms, :prereleases, :firmware_vendor, :version
+
+    def self.path
+      "v1/build_targets"
+    end
   end
 end
 

data/lib/particle/client.rb

@@ -6,6 +6,7 @@ require 'particle/client/tokens'
 require 'particle/client/firmware'
 require 'particle/client/build_targets'
 require 'particle/client/platforms'
+require 'particle/client/oauth_clients'
 
 module Particle
 
@@ -22,6 +23,7 @@ module Particle
     include Particle::Client::Firmware
     include Particle::Client::BuildTargets
     include Particle::Client::Platforms
+    include Particle::Client::OAuthClients
 
     def initialize(options = {})
       # Use options passed in, but fall back to module defaults

data/lib/particle/client/build_targets.rb

@@ -4,12 +4,11 @@ require 'ostruct'
 module Particle
   class Client
     module BuildTargets
-      HTTP_PATH = "v1/build_targets"
       # List all available Particle cloud compile build targets
       #
       # @return [Array<BuildTarget>] List of Particle Build Targets you can compile sources with
       def build_targets
-        get(HTTP_PATH)[:targets].map do |target_h|
+        get(BuildTarget.path)[:targets].map do |target_h|
           BuildTarget.new(self, target_h)
         end
       end

data/lib/particle/client/devices.rb

@@ -5,7 +5,7 @@ module Particle
 
     # Client methods for the Particle device API
     #
-    # @see http://docs.particle.io/core/api/#introduction-list-devices
+    # @see https://docs.particle.io/reference/api/#devices
     module Devices
 
       # Create a domain model for a Particle device
@@ -97,6 +97,15 @@ module Particle
         result[:result]
       end
 
+      # Ping a device to see if it is online
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @return [boolean] true when online, false when offline
+      def ping_device(target)
+        result = put(device(target).ping_path)
+        result[:online]
+      end
+
       # Signal the device to start blinking the RGB LED in a rainbow
       # pattern. Useful to identify a particular device.
       #
@@ -108,27 +117,6 @@ module Particle
         result[:signaling]
       end
 
-      # Change the product_id on the device.
-      # Use this carefully, it will impact what updates you receive, and
-      # can only be used for products that have given their permission
-      #
-      # @param target [String, Device] A device id, name or {Device} object
-      # @param product_id [String] New product id
-      # @param should_update [String] if the device should be
-      #                   immediately updated after changing the product_id
-      # @return [boolean] true on success
-      def change_device_product(target, product_id, should_update = false)
-        params = {
-          product_id: product_id,
-          update_after_claim: should_update
-        }
-        result = put(device(target).path, params)
-        if result[:error] == "Nothing to do?"
-          result[:ok] = false
-        end
-        result[:ok]
-      end
-
       # Update the public key for a device you own
       #
       # @param target [String, Device] A device id, name or {Device} object

data/lib/particle/client/library.rb

@@ -0,0 +1,28 @@
+require 'particle/library'
+
+module Particle
+  class Client
+
+    # Client methods for the Particle firmware library API
+    # 
+    # @see https://docs.particle.io/reference/api/#libraries
+    module Libraries
+
+      # Create a domain model for a firmware library
+      #
+      # @param target [String, Hash, Library] A library name, hash of attributes or {Library} object
+      # @return [Library] A library object to interact with
+      def library(target)
+        if target.is_a? Library
+          target
+        else
+          Library.new(self, target)
+        end
+      end
+
+      # List firmware libraries, sorted, filtered and paginated
+      # 
+        
+    end
+  end
+end

data/lib/particle/client/oauth_clients.rb

@@ -0,0 +1,52 @@
+require 'particle/oauth_client'
+
+module Particle
+  class Client
+
+    # Client methods for the Particle OAuth client API
+    #
+    # @see https://docs.particle.io/reference/api/#oauth-clients
+    module OAuthClients
+
+      # Create a domain model for a Particle OAuth client
+      #
+      # @param target [String, Hash, OAuthClient] A client id, hash of attributes or {OAuthClient} object
+      # @return [OAuthClient] A OAuth client object to interact with
+      def oauth_client(target)
+        if target.is_a? OAuthClient
+          target
+        else
+          OAuthClient.new(self, target)
+        end
+      end
+
+      # List all Particle OAuth clients on the account
+      #
+      # @return [Array<OAuthClient>] List of Particle OAuth clients to interact with
+      def oauth_clients
+        result = get(OAuthClient.list_path)
+        result[:clients].map do |attributes|
+          oauth_client(attributes)
+        end
+      end
+
+      # Create a Particle OAuth client
+      #
+      # @param options [Hash] Options to configure the client
+      # @return [OAuthClient] An OAuth client object to interact with
+      def create_oauth_client(attributes)
+        result = post(OAuthClient.create_path, attributes)
+        oauth_client(result[:client])
+      end
+
+      # Remove a Particle OAuth client
+      #
+      # @param target [String, OAuthClient] A client id or {OAuthClient} object
+      # @return [boolean] true for success
+      def remove_oauth_client(target)
+        delete(oauth_client(target).path)
+        true
+      end
+    end
+  end
+end

data/lib/particle/client/platforms.rb

@@ -10,7 +10,7 @@ module Particle
       # @return [Array<Platform>] List of Particle Hardware platforms that have build targets you can compile sources with
       def platforms
         @platforms = []
-        get(Particle::Client::BuildTargets::HTTP_PATH)[:platforms].each_pair do |platform_name, platform_id|
+        get(BuildTarget.path)[:platforms].each_pair do |platform_name, platform_id|
           @platforms << Platform.new(self, {name: platform_name, id: platform_id})
         end
         @platforms

data/lib/particle/client/tokens.rb

@@ -49,17 +49,25 @@ module Particle
       #                       :expires_in => How many seconds should the token last for?
       #                                      0 means a token that never expires
       #                       :expires_at => Date and time when should the token expire
+      #                       :client => Particle OAuth client to use.
+      #                                  Defaults to 'particle'
+      #                       :secret => Corresponding OAuth secret to use.
+      #                                  Defaults to 'particle'
+      #                       :grant_type => Type of OAuth authentication flow to use
+      #                                      Defaults to 'password'
       # @return [Token] The token object
       def create_token(username, password, options = {})
+        client = options.delete(:client) { 'particle' }
+        secret = options.delete(:secret) { 'particle' }
         data = URI.encode_www_form({
-          grant_type: 'password',     # specified by docs
+          grant_type: 'password',
           username: username,
           password: password
         }.merge(options))
         http_options = {
           headers: { content_type: "application/x-www-form-urlencoded" },
-          username: 'particle', # specified by docs
-          password: 'particle'  # specified by docs
+          username: client,
+          password: secret
         }
         result = request(:post, Token.create_path, data, http_options)
         result[:token] = result.delete(:access_token)

data/lib/particle/device.rb

@@ -116,6 +116,13 @@ module Particle
     end
     alias_method :get, :variable
 
+    # Ping a device to see if it is online
+    #
+    # @return [boolean] true when online, false when offline
+    def ping
+      @client.ping_device(self)
+    end
+
     # Signal the device to start blinking the RGB LED in a rainbow
     # pattern. Useful to identify a particular device.
     #
@@ -152,19 +159,7 @@ module Particle
       @client.compile(file_paths, device_id: id)
     end
 
-    # Change the product_id on the device.
-    # Use this carefully, it will impact what updates you receive, and
-    # can only be used for products that have given their permission
-    #
-    # @param product_id [String] New product id
-    # @param should_update [String] if the device should be
-    #                   immediately updated after changing the product_id
-    # @return [boolean] true on success
-    def change_product(product_id, should_update = false)
-      @client.change_device_product(self, product_id, should_update)
-    end
-
-    # Update the public key for a device you own
+    # Update the public key for this device
     #
     # @param public_key [String] The public key in PEM format (default
     #                            format generated by openssl)
@@ -202,6 +197,10 @@ module Particle
     def variable_path(name)
       path + "/#{name}"
     end
+
+    def ping_path
+      path + "/ping"
+    end
   end
 end
 

data/lib/particle/library.rb

@@ -0,0 +1,15 @@
+require 'particle/model'
+
+module Particle
+
+  # Domain model for a firmware library
+  class Library < Model
+    def initialize(client, attributes)
+      super(client, attributes)
+      if attributes.is_a? String
+        @attributes = { name: attributes }
+      end
+    end
+
+  end
+end

data/lib/particle/oauth_client.rb

@@ -0,0 +1,40 @@
+require 'particle/model'
+module Particle
+  # Domain model for one Particle OAuth client
+  class OAuthClient < Model
+    def initialize(client, attributes)
+      super(client, attributes)
+    end
+    attribute_reader :name, :id, :type, :redirect_uri, :secret
+
+    # OAuth clients can't be loaded. What you see is what you get...
+    def get_attributes
+      @loaded = true
+      @attributes
+    end
+
+    # Remove this OAuth client
+    #
+    # @example
+    #   client = Particle.oauth_clients.first
+    #   client.remove
+    #
+    # @return [boolean] true for success
+    def remove
+      @client.remove_oauth_client(self)
+    end
+
+    def self.list_path
+      "/v1/clients"
+    end
+
+    def self.create_path
+      "/v1/clients"
+    end
+
+    def path
+      "/v1/clients/#{id}"
+    end
+  end
+end
+

data/lib/particle/version.rb

@@ -1,3 +1,3 @@
 module Particle
-  VERSION = "1.3.1".freeze
+  VERSION = "1.4.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: particlerb
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Julien Vanier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-26 00:00:00.000000000 Z
+date: 2017-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -222,6 +222,8 @@ files:
 - lib/particle/client/build_targets.rb
 - lib/particle/client/devices.rb
 - lib/particle/client/firmware.rb
+- lib/particle/client/library.rb
+- lib/particle/client/oauth_clients.rb
 - lib/particle/client/platforms.rb
 - lib/particle/client/publish.rb
 - lib/particle/client/tokens.rb
@@ -231,7 +233,9 @@ files:
 - lib/particle/default.rb
 - lib/particle/device.rb
 - lib/particle/error.rb
+- lib/particle/library.rb
 - lib/particle/model.rb
+- lib/particle/oauth_client.rb
 - lib/particle/platform.rb
 - lib/particle/response/parse_json_symbols.rb
 - lib/particle/response/raise_error.rb
@@ -260,7 +264,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.5
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Ruby client for the Particle.io Cloud API