ketra 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a3d3b4f31d76efdb3a5658e959c3d6e3cdb524e
-  data.tar.gz: 66904f2e267f408336aa657637dfa382bc17598e
+  metadata.gz: f779511342b176754cdc8f6f13e68ed4b08ef041
+  data.tar.gz: 32e2e7dc98b8cdf4fb24b613214daa8fffb54f5c
 SHA512:
-  metadata.gz: 107c0bc057a83be0dfbace70bf5265d9db3a3957e9e4133c5e9df9700c0024cbbfb19c84358a12f77831358fc1e1b9b5d6c3831bd862a15f4e84a27064b0e67b
-  data.tar.gz: a52a6e1001e31fe99d3cb719f2c623835e2feeddbcab1c2b6d908d2827910b4f33b7edefbe51a7189f880ec96bc52f3dc2ee37a89a328706b2b65fb8eb212c96
+  metadata.gz: a86ceb7291d6892e8ae18721c9e38b445581f11c29f7cc56e17bbc99a663088e4521166c75fdb4b5f08498f5660cc5879c82944ccc1e0e07d7d8f27abcf2b371
+  data.tar.gz: 42131932427c385e3de58addf5e204a2f11dbd41d795c7e4d17d4ce813ed8709e6cb7fffb206025ee6d43c460b0b12ae8b59440eeb555cbee5151d215277c511

data/README.md

@@ -1,6 +1,8 @@
 # Ketra
 
 [![Gem Version](https://badge.fury.io/rb/ketra.png)](https://badge.fury.io/rb/ketra)
+[![Build Status](https://travis-ci.org/kennyjpowers/ketra.svg?branch=master)](https://travis-ci.org/kennyjpowers/ketra)
+[![Coverage Status](https://coveralls.io/repos/github/kennyjpowers/ketra/badge.svg?branch=master)](https://coveralls.io/github/kennyjpowers/ketra?branch=master)
 
 ## Description
 
@@ -43,13 +45,12 @@ access_token = Ketra.client.access_token
 #### Set Access Token Directly
 
 ```ruby
-Ketra.client.options[:authorization_mode] = :token
 Ketra.client.authorize(:token => 'YOUR ACCESS TOKEN')
 ```
 
 ### Commands
 
-All commands require authentication.
+All commands require authentication and having the :hub_serial option set.
 
 #### Keypad Buttons
 

data/ketra.gemspec

@@ -35,4 +35,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.5'
   spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'coveralls'
 end

data/lib/ketra.rb

@@ -5,18 +5,28 @@ require "ketra/version"
 require "ketra/client"
 require "ketra/commands"
 
+# Friendly Ruby inteface to the Ketra API
+#
+# Author::   Kenneth Priester (github: kennyjpowers)
+# License::  Available as open source under the terms of the MIT License (http://opensource.org/licenses/MIT)
+
+# This module is used to set the client id, client secret
+# and provide access to the actual client.
 module Ketra
-  class Error < RuntimeError; end
 
   class << self
-    attr_accessor :hub_serial
+    # Client ID provided by Ketra
     attr_accessor :client_id
+    # Client Secret proviced by Ketra
     attr_accessor :client_secret
     
     #TODO add permission_scopes
   end
 
+  # Client used for communicating with the Ketra API.
+  # You must call client.Authorize with valid credentials
+  # before using any Commands.
   def self.client
-    @client ||= Client.new client_id, client_secret, :hub_serial => hub_serial
+    @client ||= Client.new client_id, client_secret
   end
 end

data/lib/ketra/client.rb

@@ -1,47 +1,71 @@
 module Ketra
+
+  # The Ketra::Client class is used for gaining an Access Token for 
+  # authorization and performing GET and POST requests to the Ketra API
   class Client
+    # Production Host base url
     PRODUCTION_HOST = 'https://my.goketra.com'
+    # Test Host base url
     TEST_HOST = 'https://internal-my.goketra.com'
+    # Endpoint prefix to be attached to the base url before the rest of the endpoint
     LOCAL_ENDPOINT_PREFIX = 'ketra.cgi/api/v1'
 
     attr_accessor :options
     attr_reader :id, :secret, :access_token
 
-    def initialize(id, secret, options = {}, &block)
+    # Instantiate a new Ketra Client using the
+    # Client ID and Client Secret registered to your application.
+    #
+    # @param [String] id the Client ID value
+    # @param [String] secret the Client Secret value
+    # @param [Hash] options the options to create the client with
+    # @option options [Symbol] :server (:production) which authorization server to use to get an Access Token (:production or :test)
+    # @option options [String] :redirect_uri the redirect uri for the authorization code OAuth2 grant type
+    # @option options [String] :hub_serial the serial number of the Hub to communicate with
+    def initialize(id, secret, options = {})
       opts = options.dup 
       @id = id
       @secret = secret
       @options = {:server             => :production,
-                  :authorization_mode => :password,
                   :redirect_uri       => 'urn:ietf:wg:oauth:2.0:oob',
                   :hub_discovery_mode => :cloud,
-                  :connection_build   => block,
                   :api_mode           => :local}.merge(opts)
                   
     end
     
     # Authorization
 
+    # The authorize endpoint URL of the Ketra OAuth2 provider
+    #
+    # @return [String] authorize endpoint URL
     def authorization_url
       auth_client.auth_code.authorize_url(:redirect_uri => options[:redirect_uri])
     end
 
+    # Sets the access token, must supply either the access token, the authorization code,
+    # or the Design Studio Username and Password 
+    #
+    # @param [Hash] credentials
+    # @option credentials [String] :token previously gained access token value
+    # @option credentials [String] :authorization_code code value from the Ketra OAuth2 provider
+    # @option credentials [String] :username Ketra Desiadgn Studio username
+    # @option credentials [String] :password Design Studio password
+    # @return [OAuth2::AccessToken] Access Token object
     def authorize(credentials)
-      case options[:authorization_mode]
-      when :token
+      if credentials.key?(:token)
         @access_token = OAuth2::AccessToken.new(auth_client, credentials[:token])
-      when :code
+      elsif credentials.key?(:authorization_code)
         @access_token = auth_client.auth_code.get_token(credentials[:authorization_code],
                                                         :redirect_uri => options[:redirect_uri])
-      else :password
-        byebug
+      elsif credentials.key?(:username)
         @access_token = auth_client.password.get_token(credentials[:username],
                                                        credentials[:password])
       end
     end
 
     # OAuth Client
-
+    #
+    # @return [OAuth2::Client] oauth2 client
     def auth_client
       @auth_client ||= OAuth2::Client.new(Ketra.client_id,
                                           Ketra.client_secret,
@@ -49,12 +73,21 @@ module Ketra
                                           :ssl => { :verify => false })
     end
 
-    # Requests
-      
+    # performs a GET Request using the OAuth2 Access Token and parses the result as JSON
+    #
+    # @param [String] endpoint to be appended to the base url
+    # @param [Hash] params to be used as query params for the request
+    # @return [Hash] deserialized response hash
     def get(endpoint, params = {})
       JSON.parse access_token.get(url(endpoint), :params => params).body
     end
-    
+
+    # performs a POST request using the OAuth2 Access Token and parses the result as JSON
+    #
+    # @param [String] endpoint to be appended to the base url
+    # @param [Hash] params except :query_params will be serialized into JSON and supplied as the body of the request
+    # @option params [Hash] :query_params to be used as the query params for the request
+    # @return [Hash] deserialized response hash
     def post(endpoint, params = {})
       internal_params = params.dup
       resp = access_token.post url(endpoint),
@@ -74,34 +107,26 @@ module Ketra
         PRODUCTION_HOST
       end
     end
-
+    
     def url(endpoint)
-      case options[:api_mode]
-      when :local
-        url = "#{local_url}/#{endpoint}"
-      else
-        url = "#{local_url}/#{endpoint}"
-      end
+      #TODO implement additional api modes
+      url = "#{local_url}/#{endpoint}"
       Addressable::URI.encode(url)
     end
     
     def local_url
       "https://#{hub_ip}/#{LOCAL_ENDPOINT_PREFIX}"
     end
-
+    
     def hub_ip
       @hub_ip || discover_hub(options[:hub_serial])
     end
-
+    
     def discover_hub(serial_number)
-      case options[:hub_discovery_mode]
-      when :cloud
-        cloud_discovery(serial_number)
-      else
-        cloud_discovery(serial_number)
-      end
+      #TODO implement additional hub discovery modes
+      cloud_discovery(serial_number)
     end
-
+    
     def cloud_discovery(serial_number)
       @hub_ip ||= perform_cloud_hub_discovery(serial_number)
     end

data/lib/ketra/commands.rb

@@ -1,26 +1,51 @@
 require 'securerandom'
 
 module Ketra
+  # This module is used to execute specific Ketra API commands
   module Commands
+
+    # Activates a keypad button at a specific brightness level
+    #
+    # @param [String] keypad the GUID or Name of the keypad containing the button you want to activate
+    # @param [String] button the GUID or Name of the keypad button you want to activate
+    # @param [Integer] level (65535) the brightness level from 0 to 65535
+    # @return [Hash] deserialized response hash
     def self.activate_button(keypad, button, level=65535)
       Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/Activate",
                         :Level => level)
     end
 
+    # Deactivates a keypad button
+    #
+    # @param [String] keypad the GUID or Name of the keypad containing the button you want to deactivate
+    # @param [String] button the GUID or Name of the keypad button you want to deactivate
+    # @return [Hash] deserialized response hash
     def self.deactivate_button(keypad, button)
       Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/Deactivate",
                         :Level => 0)
     end
 
+    # Pushes a keypad button which will either activate or deactivate based on its current state
+    # and the configuration of the keypad settings
+    #
+    # @param [String] keypad the GUID or Name of the keypad containing the button you want to deactivate
+    # @param [String] button the GUID or Name of the keypad button you want to deactivate
+    # @return [Hash] deserailized response hash
     def self.push_button(keypad, button)
       Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/PushButton",
                         :query_params => { :idempotency_key => SecureRandom.hex })
     end
-    
+
+    # Queries for the available Ketra Keypads
+    #
+    # @return [Hash] deserialized response hash containing the keypad info, see Ketra API documentation for details
     def self.keypads
       Ketra.client.get("Keypads")
     end
 
+    # Queries for the available Ketra Groups
+    #
+    # @return [Hash] deserialized response hash containing the group info, see Ketra API documentation for details
     def self.groups
       Ketra.client.get("Groups")
     end

data/lib/ketra/version.rb

@@ -1,3 +1,4 @@
 module Ketra
-  VERSION = "0.4.0"
+  # current RubyGem version
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ketra
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kenneth Priester
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-21 00:00:00.000000000 Z
+date: 2017-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -120,6 +120,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A friendly Ruby interface to the Ketra API
 email:
 - kennethjpriester@gmail.com