particlerb 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c21a444cf3a1c9100b0c8c8d9b70105ee65e28dc
-  data.tar.gz: 9d7b3d4150a9c4d4f69306f47c411761c7a6d06b
+  metadata.gz: 3df82a4b9e831fa635c52d24e9d0f59bd3b6209d
+  data.tar.gz: 61c6aa2eba790faeee99e4cde8ea6f04e214946b
 SHA512:
-  metadata.gz: 6daacb4b3fb434bfa5d5f250e2c7b90784b8e8319643998bce95732e7c6b47520e4fe9aa96767b4d2fd6e1b576b5f759bffe37de43281205d65c7ecc3a8e6bcd
-  data.tar.gz: f6cd397e20992d386419f36e889fcdcdaeda9ae007777900752c847d1e5c99ca94cc79980b41989d7c6cf1b04140d8bd6766c5905d63cc71301bc2999a207643
+  metadata.gz: 4a4f275a4d1b7b1dde368e620a76205e4ee34fd23aaca4682d3df0bee6c3407786504d05b648cfe56ddb8ea0e88404a69d5a3479705e58ee6e9eb2276cb5f1d5
+  data.tar.gz: 95e421509a8109498915efcb25096969204afb0fb673a38edca51957ea20874d784a9dca23383e5d6cce600bb65e429f0ad7b8048b8de06985eb09b7c8d6d32f

data/README.md

@@ -1,12 +1,16 @@
-# particlerb [![Build Status](https://travis-ci.org/monkbroc/particlerb.svg)](https://travis-ci.org/monkbroc/particlerb)
+## particlerb ##
 
-Ruby client for the [Particle.io] Cloud API
+[![Gem Version](https://badge.fury.io/rb/particlerb.svg)](http://badge.fury.io/rb/particlerb)
+[![Build Status](https://travis-ci.org/monkbroc/particlerb.svg)](https://travis-ci.org/monkbroc/particlerb)
+[![Code Climate](https://codeclimate.com/github/monkbroc/particlerb/badges/gpa.svg)](https://codeclimate.com/github/monkbroc/particlerb)
+
+Ruby client for the [Particle.io] Cloud API with an object-oriented interface
 
 [Particle.io]: https://www.particle.io
 
 *Note: this is not an official gem by Particle. It is maintained by Julien Vanier.*
 
-## Quick start
+## Installation
 
 Install via Rubygems
 
@@ -14,82 +18,111 @@ Install via Rubygems
 
 ... or add to your Gemfile
 
-    gem "particlerb", "~> 0.0.1"
+    gem "particlerb", "~> 0.0.2"
 
 
-### Making requests
+### Providing credentials
 
-API methods are available as module methods (consuming module-level
-configuration) or as client instance methods.
+**A Particle cloud API access token is necessary for most requests.** You can use the one from the [Web IDE][] for testing, but it's recommended to generate a new token with this gem using `Particle.login` or with the [Particle CLI][] using `particle token new`
 
 ```ruby
-# Provide authentication credentials
+# Provide acess token as an environment variable
+ENV['PARTICLE_ACCESS_TOKEN']
+
+# Or configure global authentication credentials
+# If you use Rails, you can put this in config/initializers/particle.rb
 Particle.configure do |c|
   c.access_token = "38bb7b318cc6898c80317decb34525844bc9db55"
 end
 
-# Fetch the list of devices
-Particle.devices
+# Or pass access token when creating a client
+# If no token is passed to Particle::Client.new, the global or environment one is used
+client = Particle::Client.new(access_token: "38bb7b318cc6898c80317decb34525844bc9db55")
 ```
-or
+
+### Making requests
+
+API methods are available as module methods (consuming module-level
+configuration) or as client instance methods.
 
 ```ruby
-# Provide authentication credentials
-client = Particle::Client.new(access_token: "38bb7b318cc6898c80317decb34525844bc9db55")
+# Fetch the list of devices using the global client
+Particle.devices
+
+# Or used a newly created client
+client = Particle::Client.new
 # Fetch the list of devices
 client.devices
 ```
 
-## Device commands
+[Web IDE]: http://docs.particle.io/core/build/#flash-apps-with-particle-build-account-information
+[Particle CLI]: http://docs.particle.io/core/cli
+
+## Interacting with devices
 
-See the [Particle Cloud API documentation][API docs] for more details.
+List all devices. Rreturns an `Array` of `Particle::Device`.
 
-List all devices (returns an `Array` of `Device`)
 ```ruby
 devices = Particle.devices
 ```
 
-Get a `Device` by id or name
+Get a `Particle::Device` by id or name.
+
 ```ruby
 device = Particle.device('blue_fire')
 device = Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d')
 ```
 
-Get information about a device
+Get information about a device.
+
 ```ruby
 device = Particle.device('blue_fire')
-device.id
-device.name
-device.connected?
-device.variables
-device.functions
 device.attributes     # Hash of all attributes
+device.id             # ==> 'f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d'
+device.name           # ==> 'blue_fire'
+device.connected?     # true
+device.variables      # {:myvar => "double" } or nil if not connected
+device.functions      # ["myfunction"] or nil if not connected
 device.get_attributes # forces refresh of all attributes from the cloud
+
+# If you get a Device from the Particle.devices call, you will need to call
+# get_attributes to get the list of functions and variables since that's not
+# returned by the cloud when calling Particle.devices
+device = Particle.devices.first
+device.connected?     # ==> true
+device.functions      # ==> nil
+device.get_attributes
+device.functions      # ==> ["myfunction"]
 ```
 
-Claim a device and add it to your account (returns the `Device`)
+Claim a device by id and add it to your account. Returns a `Particle::Device`.
+
 ```ruby
-Particle.device('blue_fire').claim
+Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d').claim
 ```
 
-Remove a device from your account
+Remove a device from your account. Returns true on success.
+
 ```ruby
 Particle.device('blue_fire').remove
 Particle.devices.first.remove
 ```
 
-Rename a device
+Rename a device. Returns true on success.
+
 ```ruby
 Particle.device('red').rename('green')
 ```
 
-Call a function on the firmware (returns the result of running the function)
+Call a function on the firmware with an optional `String` argument. Returns the result of running the function as as `Number`.
+
 ```ruby
-Particle.device('coffeemaker').function('brew') # String argument optional
+Particle.device('coffeemaker').function('brew')
 Particle.devices.first.function('digitalWrite', '1')
 ```
 
-Get the value of a firmware variable (returns the result as a String or Number)
+Get the value of a firmware variable. Returns the result as a `String` or `Number`.
+
 ```ruby
 Particle.device('mycar').variable('battery') # ==> 12.33
 device = Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d')
@@ -97,13 +130,145 @@ device.variable('version') # ==> "1.0.1"
 ```
 
 
-Signal a device to start blinking the RGB LED in rainbow patterns.
+Signal a device to start blinking the RGB LED in rainbow patterns. Returns whether the device is signaling.
+
 ```ruby
 Particle.device('nyan_cat').signal(true)
 ```
+See the [Particle Cloud API documentation about devices][device docs] for more details.
+
+[device docs]: http://docs.particle.io/core/api/#introduction-device-information
+
+## Interacting with events
+
+Publish an event to your devices. Returns true on success.
+
+```ruby
+Particle.publish(name: "wakeup")
+Particle.publish(name: "server_ip", data: "8.8.8.8", ttl: 3600, private: true)
+```
+
+Data, ttl and private are optional.
+
+Data is converted to JSON if it is a Hash or an Array, otherwise it is converted to a String.
+
+See the [Particle Cloud API documentation about publishing events][publish docs] for more details.
+
+[publish docs]: http://docs.particle.io/core/api/#publishing-events
+
+### Limitation: Subscribe not supported
+
+This gem does not support subscribing (listening) to events from devices.
+
+This would require an HTTP client that supports streaming responses which is not common in Ruby. Some clients like EM-HTTP-Request do support streaming responses, but are tied to specific architectures like EventMachine.
+
+For web server applications, webhooks are better suited to process incoming events.
+
+## Interacting with webhooks
+
+List existing webhooks. Returns an `Array` of `Particle::Webhook`
+
+```ruby
+Particle.webhooks
+```
+
+Get info about an existing webhook by id. Returns a `Particle::Webhook`
+
+```ruby
+webhook = Particle.webhook('ffcddbd30b860ea3cadd22db')
+webhook.attributes
+webhook.event
+webhook.url
+```
+
+Calling `attributes` will also send a test message to your webhook url and report the `response` or `error`.
+
+```ruby
+webhook.response
+webhook.error
+
+webhook = Particle.webhooks.first
+webhook.get_attributes # force reloading attributes from the cloud
+# get_attributes necessary to get the response when Webhook was returned from the
+# Particle.webhooks() method as it doesn't do a test message on each webhook
+webhook.response
+```
+
+Create a new webhook. Pass a hash of [any options accepted by the Particle Cloud API][webhook options]. Returns a `Particle::Webhook`
+
+```ruby
+Particle.webhook(event: "weather", url: "http://myserver.com/report").create
+```
+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
+
+## Authentication
+
+Replace the access token on a client
+
+```ruby
+Particle.access_token = 'f1d52ea0de921fad300027763d8c5ebd03b1934d'
+
+# On client instance
+client = Particle::Client.new
+client.access_token = 'f1d52ea0de921fad300027763d8c5ebd03b1934d'
+```
+
+**All these following methods requires the account username (email) and password.**
+
+List all tokens that can be used to access an account. Returns an `Array` of `Particle::Token`
+
+```ruby
+Particle.tokens("me@example.com", "pa$$w0rd")
+```
+
+Log in and create a new token. Returns a `Particle::Token`. This will also set the token on the client for future calls.
+
+```ruby
+Particle.login("me@example.com", "pa$$w0rd")
+```
+
+Create a token but don't set it on the client. Returns a `Particle::Token`
+
+```ruby
+Particle.token.create("me@example.com", "pa$$w0rd")
+```
+
+Invalidate and delete a token. Returns true on success.
+
+```ruby
+Particle.token('f1d52ea0de921fad300027763d8c5ebd03b1934d').remove("me@example.com", "pa$$w0rd")
+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
+
 
+## Errors
 
-[API docs]: http://docs.particle.io/core/api
+When any API error occurs, a subclass of `Particle::Error` will be raised.
+
+The actual error classes are
+
+- `MissingTokenError`
+- `BadRequest`
+- `Unauthorized`
+- `Forbidden` 
+- `NotFound`
+- `TimedOut`
+- `ServerError`
+
+See [a description of each error on the Particle API docs][error docs].
+
+[error docs]: http://docs.particle.io/core/api/#introduction-errors
+
+## Advanced
+
+All API endpoints are availble directly on the client object as method calls like `Particle.claim_device(id)` but the preferred usage is to call methods on domain objects like `Particle.device(id).claim`. See the various `Particle::Client` subclasses for more details.
 
 ### Accessing HTTP responses
 
@@ -117,6 +282,19 @@ response = Particle.last_response
 headers  = response.headers
 ```
 
+## Support
+
+Open a [GitHub issue][] if you find a bug.
+
+[Join the conversion on the awesome Particle community forums][forum] to discuss any other topic!
+
+[GitHub issue]: https://github.com/monkbroc/particlerb/issues
+[forum]: http://community.particle.io/
+
+## Versioning
+
+particlerb follows the [Semantic Versioning](http://semver.org/) standard.
+
 ## Thanks
 
 This gem is heavily inspired by [Octokit][] by GitHub. I stand on the shoulder of giants. Thanks!

data/lib/particle/client/devices.rb

@@ -1,13 +1,16 @@
+require 'particle/device'
+
 module Particle
   class Client
 
-    # Methods for the Particle device API
+    # Client methods for the Particle device API
+    #
     # @see http://docs.particle.io/core/api/#introduction-list-devices
     module Devices
 
       # Create a domain model for a Particle device
       #
-      # @param target [String, Sawyer::Resource, Device] A device id, name or {Device} object
+      # @param target [String, Sawyer::Resource, Device] A device id, name, Sawyer::Resource or {Device} object
       # @return [Device] A device object to interact with
       def device(target)
         if target.is_a? Device
@@ -15,18 +18,16 @@ module Particle
         elsif target.respond_to?(:to_attrs)
           Device.new(self, target.to_attrs)
         else
-          Device.new(self, target.to_s)
+          Device.new(self, target)
         end
       end
 
       # List all Particle devices on the account
       #
-      # @see http://docs.particle.io/core/api/#introduction-list-devices
-      #
       # @return [Array<Device>] List of Particle devices to interact with
       def devices
         get(Device.list_path).map do |resource|
-          Device.new(self, resource)
+          device(resource)
         end
       end
 

data/lib/particle/client/publish.rb

@@ -0,0 +1,38 @@
+require 'particle/event'
+
+module Particle
+  class Client
+
+    # Client methods for the Particle publish API
+    #
+    # @see http://docs.particle.io/core/api/#publishing-events
+    module Publish
+
+      # Publish an event to your devices
+      #
+      # @param options [Hash]
+      #     * :name [String]: name of the event to publish
+      #     * :data [String,Hash]: optional data to include with the event
+      #     * :ttl [Number]: optional Time-To-Live in seconds for the
+      #       event (currently ignored by the cloud)
+      #     * :private [boolean]: optional key to indicate event should
+      #       be published only to your own devices
+      # @return [boolean] true for success
+      def publish(options)
+        params = {
+          name: options.fetch(:name)
+        }
+        case options[:data]
+        when Hash, Array then params[:data] = options[:data].to_json
+        else params[:data] = options[:data].to_s
+        end
+
+        params[:ttl] = options[:ttl] if options[:ttl]
+        params[:private] = true if options[:private]
+
+        result = post(Event.publish_path, params)
+        result.ok
+      end
+    end
+  end
+end

data/lib/particle/client/tokens.rb

@@ -0,0 +1,101 @@
+require 'particle/token'
+require 'uri'
+
+module Particle
+  class Client
+
+    # Client methods for the Particle authentication/token API
+    #
+    # @see http://docs.particle.io/core/api/#introduction-authentication
+    module Tokens
+
+      # Create a domain model for a Particle token
+      #
+      # @param target [String, Sawyer::Resource, Token] A token id, Sawyer::Resource or {Token} object
+      # @return [Token] A token object to interact with
+      def token(target = {})
+        if target.is_a? Token
+          target
+        elsif target.respond_to?(:to_attrs)
+          Token.new(self, target.to_attrs)
+        else
+          Token.new(self, target)
+        end
+      end
+
+      # List all Particle tokens for the account
+      #
+      # @param username [String] The username (email) used to log in to
+      #                          the Particle Cloud API
+      # @param password [String] The password used to log in to
+      #                          the Particle Cloud API
+      # @return [Array<Token>] List of Particle tokens
+      def tokens(username, password)
+        http_options = {
+          username: username,
+          password: password
+        }
+        request(:get, Token.list_path, "", http_options).map do |resource|
+          token(resource)
+        end
+      end
+
+      # Authenticate with Particle and create a new token
+      #
+      # @param username [String] The username (email) used to log in to
+      #                          the Particle Cloud API
+      # @param password [String] The password used to log in to
+      #                          the Particle Cloud API
+      # @param options [Hash] Additional Particle Cloud API options to
+      #                       create the token.
+      # @return [Token] The token object
+      def create_token(username, password, options = {})
+        data = URI.encode_www_form({
+          grant_type: 'password',     # specified by docs
+          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
+        }
+        result = request(:post, Token.create_path, data, http_options)
+        token(result.access_token)
+      end
+
+      # Authenticate with Particle and start using the token on the
+      # client right away
+      #
+      # @param username [String] The username (email) used to log in to
+      #                          the Particle Cloud API
+      # @param password [String] The password used to log in to
+      #                          the Particle Cloud API
+      # @param options [Hash] Additional Particle Cloud API options to
+      #                       create the token.
+      # @return [Token] The token object
+      def login(username, password, options = {})
+        token = create_token(username, password, options)
+        self.access_token = token
+        token
+      end
+
+      # Remove a Particle token
+      #
+      # @param username [String] The username (email) used to log in to
+      #                          the Particle Cloud API
+      # @param password [String] The password used to log in to
+      #                          the Particle Cloud API
+      # @param target [String, Token] An token id or {Token} object
+      # @return [boolean] true for success
+      def remove_token(username, password, target)
+        http_options = {
+          username: username,
+          password: password
+        }
+        result = request(:delete, token(target).path, "", http_options)
+        result.ok
+      end
+    end
+  end
+end

data/lib/particle/client/webhooks.rb

@@ -0,0 +1,66 @@
+require 'particle/webhook'
+
+module Particle
+  class Client
+
+    # Client methods for the Particle webhook API
+    #
+    # @see http://docs.particle.io/core/webhooks/
+    module Webhooks
+
+      # Create a domain model for a Particle webhook
+      #
+      # @param target [String, Sawyer::Resource, Webhook] A webhook id, Sawyer::Resource or {Device} object
+      # @return [Webhook] A webhook object to interact with
+      def webhook(target)
+        if target.is_a? Webhook
+          target
+        elsif target.respond_to?(:to_attrs)
+          Webhook.new(self, target.to_attrs)
+        else
+          Webhook.new(self, target)
+        end
+      end
+
+      # List all Particle webhooks on the account
+      #
+      # @return [Array<Webhook>] List of Particle webhooks to interact with
+      def webhooks
+        get(Webhook.list_path).map do |resource|
+          webhook(resource)
+        end
+      end
+
+      # Get information about a Particle webhook
+      #
+      # The Particle cloud will send a test message to the webhook URL
+      # when this is called
+      #
+      # @param target [String, Webhook] A webhook id or {Webhook} object
+      # @return [Hash] The webhook attributes and test message response
+      def webhook_attributes(target)
+        result = get(webhook(target).path)
+        result.to_attrs
+      end
+
+      # Creates a new Particle webhook
+      #
+      # @param options [Hash] Options to configure the webhook
+      # @return [Webhook] The webhook object
+      # @see http://docs.particle.io/core/webhooks/#Webhook-options
+      def create_webhook(options)
+        result = post(Webhook.create_path, options)
+        webhook(result)
+      end
+
+      # Remove a Particle webhook
+      #
+      # @param target [String, Webhook] A webhook id or {Webhook} object
+      # @return [boolean] true for success
+      def remove_webhook(target)
+        result = delete(webhook(target).path)
+        result.ok
+      end
+    end
+  end
+end

data/lib/particle/client.rb

@@ -1,6 +1,8 @@
 require 'particle/connection'
-require 'particle/device'
 require 'particle/client/devices'
+require 'particle/client/publish'
+require 'particle/client/webhooks'
+require 'particle/client/tokens'
 
 module Particle
 
@@ -11,6 +13,9 @@ module Particle
     include Particle::Configurable
     include Particle::Connection
     include Particle::Client::Devices
+    include Particle::Client::Publish
+    include Particle::Client::Webhooks
+    include Particle::Client::Tokens
 
     def initialize(options = {})
       # Use options passed in, but fall back to module defaults
@@ -38,7 +43,12 @@ module Particle
     # @param value [String] 40 character Particle OAuth2 access token
     def access_token=(value)
       reset_agent
-      @access_token = value
+      @access_token = 
+        if value.respond_to? :access_token
+          value.access_token
+        else
+          value
+        end
     end
   end
 end

data/lib/particle/configurable.rb

@@ -3,7 +3,7 @@ module Particle
   # Configuration options for {Client}, defaulting to values in
   # {Default}
   module Configurable
-    # @!attribute [w] access_token
+    # @!attribute [String] access_token
     #   @see http://docs.particle.io/core/api/#introduction-authentication
     #   @return [String] Particle access token for authentication
     # @!attribute api_endpoint

data/lib/particle/connection.rb

@@ -57,15 +57,6 @@ module Particle
       request :delete, url, options
     end
 
-    # Make a HTTP HEAD request
-    #
-    # @param url [String] The path, relative to {#api_endpoint}
-    # @param options [Hash] Query and header params for request
-    # @return [Sawyer::Resource]
-    def head(url, options = {})
-      request :head, url, parse_query_and_convenience_headers(options)
-    end
-
     # Hypermedia agent for the Particle API
     #
     # @return [Sawyer::Agent]
@@ -98,13 +89,21 @@ module Particle
 
     def request(method, path, data, options = {})
       if data.is_a?(Hash)
-        options[:query]   = data.delete(:query) || {}
-        options[:headers] = data.delete(:headers) || {}
+        options[:query]   ||= data.delete(:query) || {}
+        options[:headers] ||= data.delete(:headers) || {}
         if accept = data.delete(:accept)
           options[:headers][:accept] = accept
         end
       end
 
+      username = options.delete(:username)
+      password = options.delete(:password)
+      if username && password
+        options[:headers] ||= {}
+        options[:headers][:authorization] =
+          basic_auth_header(username, password)
+      end
+
       @last_response = response = agent.call(method, URI::Parser.new.escape(path.to_s), data, options)
       response.data
     end
@@ -120,6 +119,12 @@ module Particle
 
       opts
     end
+
+    # Temporarily set the Authorization to use basic auth
+    def basic_auth_header(username, password)
+      Faraday::Request.lookup_middleware(:basic_auth).
+        header(username, password)
+    end
   end
 end
 

data/lib/particle/device.rb

@@ -1,20 +1,20 @@
+require 'particle/model'
+
 module Particle
 
   # Domain model for one Particle device
-  class Device
+  class Device < Model
     ID_REGEX = /\h{24}/
 
     def initialize(client, attributes)
-      @client = client
-      @attributes =
+      super(client, attributes)
+
       if attributes.is_a? String
         if attributes =~ ID_REGEX
-          { id: attributes }
+          @attributes = { id: attributes }
         else
-          { name: attributes }
+          @attributes = { name: attributes }
         end
-      else
-        attributes
       end
     end
 
@@ -32,17 +32,10 @@ module Particle
       @attributes[:id] || @attributes[:name]
     end
 
-    %w(connected functions variables product_id last_heard).each do |key|
-      define_method key do
-        attributes[key.to_sym]
-      end
-    end
-    alias_method :connected?, :connected
+    attribute_reader :connected, :functions, :variables, :product_id,
+      :last_heard, :last_app, :last_ip_address
 
-    def attributes
-      get_attributes unless @loaded
-      @attributes
-    end
+    alias_method :connected?, :connected
 
     def get_attributes
       @loaded = true

data/lib/particle/error.rb

@@ -1,5 +1,7 @@
 module Particle
   # Custom error class for rescuing from all Particle errors
+  #
+  # @see http://docs.particle.io/core/api/#introduction-errors
   class Error < StandardError
 
     # Returns the appropriate Particle::Error subclass based

data/lib/particle/event.rb

@@ -0,0 +1,10 @@
+module Particle
+
+  # Domain model for Particle event
+  class Event
+    def self.publish_path
+      "v1/devices/events"
+    end
+  end
+end
+

data/lib/particle/model.rb

@@ -0,0 +1,49 @@
+module Particle
+
+  # Base class for domain models
+  class Model
+    def initialize(client, attributes)
+      @client = client
+      @attributes =
+        if attributes.is_a? String
+          { id: attributes }
+        else
+          # Consider attributes loaded when passed in through constructor
+          @loaded = true
+          attributes
+        end
+    end
+
+    # Display the attributes when inspecting the object in the console
+    def inspect
+      "#<#{self.class} #{@attributes}>"
+    end
+
+    # Accessor for the id
+    def id
+      @attributes[:id]
+    end
+
+    # Define accessor methods for attributes.
+    #
+    # Will load the attributes from the cloud if not already done
+    def self.attribute_reader(*keys)
+      keys.each do |key|
+        define_method key do
+          attributes[key]
+        end
+      end
+    end
+
+    # Hash of all attributes returned by the cloud
+    def attributes
+      get_attributes unless @loaded
+      @attributes
+    end
+
+    # Load the model attributes with the correct API call in subclasses
+    def get_attributes
+      raise "Implement in subclasses and set @loaded = true"
+    end
+  end
+end

data/lib/particle/token.rb

@@ -0,0 +1,76 @@
+module Particle
+
+  # Domain model for one Particle token
+  class Token < Model
+    def initialize(client, attributes)
+      @client = client
+      @attributes =
+        if attributes.is_a? String
+          { token: attributes }
+        else
+          # Consider attributes loaded when passed in through constructor
+          @loaded = true
+          attributes
+        end
+    end
+
+    # The id of the token
+    def token
+      @attributes[:token]
+    end
+    alias_method :id, :token
+    alias_method :access_token, :token
+
+    attribute_reader :expires_at, :client
+
+    # Tokens can't be loaded. What you see is what you get...
+    def get_attributes
+      @loaded = true
+      @attributes
+    end
+
+    # Text representation of the token, masking the secret part
+    #
+    # @return [String]
+    def inspect
+      inspected = super
+
+      # Only show last 4 of token, secret
+      if id
+        inspected = inspected.gsub! id, "#{'*'*36}#{id[36..-1]}"
+      end
+
+      inspected
+    end
+
+    # Create a Particle token
+    # @param username [String] The username (email) used to log in to
+    #                          the Particle Cloud API
+    # @param password [String] The password used to log in to
+    #                          the Particle Cloud API
+    def create(username, password)
+      @client.create_token(username, password)
+    end
+
+    # Remove a Particle token
+    # @param username [String] The username (email) used to log in to
+    #                          the Particle Cloud API
+    # @param password [String] The password used to log in to
+    #                          the Particle Cloud API
+    def remove(username, password)
+      @client.remove_token(username, password, self)
+    end
+
+    def self.list_path
+      "v1/access_tokens"
+    end
+
+    def self.create_path
+      "/oauth/token"
+    end
+
+    def path
+      "/v1/access_tokens/#{access_token}"
+    end
+  end
+end

data/lib/particle/version.rb

@@ -1,3 +1,3 @@
 module Particle
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.2".freeze
 end

data/lib/particle/webhook.rb

@@ -0,0 +1,62 @@
+require 'particle/model'
+
+module Particle
+
+  # Domain model for one Particle device
+  class Webhook < Model
+    def initialize(client, attributes)
+      super(client, attributes)
+    end
+
+    attribute_reader :url, :deviceID, :event, :created_at, :mydevices,
+      :requestType, :headers, :json, :query, :auth
+
+    # The response of the web server to a test message
+    # If nil, check error
+    def response
+      get_attributes unless @loaded
+      @response
+    end
+
+    # The error from the web server to a test message
+    # If nil, check response
+    def error
+      get_attributes unless @loaded
+      @error
+    end
+
+    # Force reloading the attributes for the webhook
+    def get_attributes
+      @loaded = true
+      result = @client.webhook_attributes(self)
+      @response = result[:response]
+      @error = result[:error]
+      @attributes = result[:webhook]
+    end
+
+    # Add a Particle webhook
+    def create
+      new_webhook = @client.create_webhook(@attributes)
+      @attributes = new_webhook.attributes
+      self
+    end
+
+    # Remove a Particle webhook
+    def remove
+      @client.remove_webhook(self)
+    end
+
+    def self.list_path
+      "v1/webhooks"
+    end
+
+    def self.create_path
+      "v1/webhooks"
+    end
+
+    def path
+      "/v1/webhooks/#{id}"
+    end
+  end
+end
+

data/lib/particle.rb

@@ -11,6 +11,25 @@ module Particle
       @client = Particle::Client.new(options)
     end
 
+    # Authenticate with Particle and start using the new token as the
+    # global token
+    #
+    # Delegates actual functionality to the client.
+    #
+    # @param username [String] The username (email) used to log in to
+    #                          the Particle Cloud API
+    # @param password [String] The password used to log in to
+    #                          the Particle Cloud API
+    # @param options [Hash] Additional Particle Cloud API options to
+    #                       create the token.
+    # @return [Token] The token object
+    # @see {Particle::Client::Tokens#login}
+    def login(username, password, options = {})
+      token = client.login(username, password, options)
+      self.access_token = token.access_token
+      token
+    end
+
     private
 
     def respond_to_missing?(method_name, include_private = false)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: particlerb
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Julien Vanier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-25 00:00:00.000000000 Z
+date: 2015-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sawyer
@@ -149,13 +149,20 @@ files:
 - lib/particle.rb
 - lib/particle/client.rb
 - lib/particle/client/devices.rb
+- lib/particle/client/publish.rb
+- lib/particle/client/tokens.rb
+- lib/particle/client/webhooks.rb
 - lib/particle/configurable.rb
 - lib/particle/connection.rb
 - lib/particle/default.rb
 - lib/particle/device.rb
 - lib/particle/error.rb
+- lib/particle/event.rb
+- lib/particle/model.rb
 - lib/particle/response/raise_error.rb
+- lib/particle/token.rb
 - lib/particle/version.rb
+- lib/particle/webhook.rb
 - lib/particlerb.rb
 - particlerb.gemspec
 homepage: https://github.com/monkbroc/particlerb