ketra 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 2a3d3b4f31d76efdb3a5658e959c3d6e3cdb524e
4
- data.tar.gz: 66904f2e267f408336aa657637dfa382bc17598e
3
+ metadata.gz: f779511342b176754cdc8f6f13e68ed4b08ef041
4
+ data.tar.gz: 32e2e7dc98b8cdf4fb24b613214daa8fffb54f5c
5
5
  SHA512:
6
- metadata.gz: 107c0bc057a83be0dfbace70bf5265d9db3a3957e9e4133c5e9df9700c0024cbbfb19c84358a12f77831358fc1e1b9b5d6c3831bd862a15f4e84a27064b0e67b
7
- data.tar.gz: a52a6e1001e31fe99d3cb719f2c623835e2feeddbcab1c2b6d908d2827910b4f33b7edefbe51a7189f880ec96bc52f3dc2ee37a89a328706b2b65fb8eb212c96
6
+ metadata.gz: a86ceb7291d6892e8ae18721c9e38b445581f11c29f7cc56e17bbc99a663088e4521166c75fdb4b5f08498f5660cc5879c82944ccc1e0e07d7d8f27abcf2b371
7
+ data.tar.gz: 42131932427c385e3de58addf5e204a2f11dbd41d795c7e4d17d4ce813ed8709e6cb7fffb206025ee6d43c460b0b12ae8b59440eeb555cbee5151d215277c511
data/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # Ketra
2
2
 
3
3
  [![Gem Version](https://badge.fury.io/rb/ketra.png)](https://badge.fury.io/rb/ketra)
4
+ [![Build Status](https://travis-ci.org/kennyjpowers/ketra.svg?branch=master)](https://travis-ci.org/kennyjpowers/ketra)
5
+ [![Coverage Status](https://coveralls.io/repos/github/kennyjpowers/ketra/badge.svg?branch=master)](https://coveralls.io/github/kennyjpowers/ketra?branch=master)
4
6
 
5
7
  ## Description
6
8
 
@@ -43,13 +45,12 @@ access_token = Ketra.client.access_token
43
45
  #### Set Access Token Directly
44
46
 
45
47
  ```ruby
46
- Ketra.client.options[:authorization_mode] = :token
47
48
  Ketra.client.authorize(:token => 'YOUR ACCESS TOKEN')
48
49
  ```
49
50
 
50
51
  ### Commands
51
52
 
52
- All commands require authentication.
53
+ All commands require authentication and having the :hub_serial option set.
53
54
 
54
55
  #### Keypad Buttons
55
56
 
@@ -35,4 +35,5 @@ Gem::Specification.new do |spec|
35
35
  spec.add_development_dependency 'rake', '~> 10.0'
36
36
  spec.add_development_dependency 'rspec', '~> 3.5'
37
37
  spec.add_development_dependency 'byebug'
38
+ spec.add_development_dependency 'coveralls'
38
39
  end
@@ -5,18 +5,28 @@ require "ketra/version"
5
5
  require "ketra/client"
6
6
  require "ketra/commands"
7
7
 
8
+ # Friendly Ruby inteface to the Ketra API
9
+ #
10
+ # Author:: Kenneth Priester (github: kennyjpowers)
11
+ # License:: Available as open source under the terms of the MIT License (http://opensource.org/licenses/MIT)
12
+
13
+ # This module is used to set the client id, client secret
14
+ # and provide access to the actual client.
8
15
  module Ketra
9
- class Error < RuntimeError; end
10
16
 
11
17
  class << self
12
- attr_accessor :hub_serial
18
+ # Client ID provided by Ketra
13
19
  attr_accessor :client_id
20
+ # Client Secret proviced by Ketra
14
21
  attr_accessor :client_secret
15
22
 
16
23
  #TODO add permission_scopes
17
24
  end
18
25
 
26
+ # Client used for communicating with the Ketra API.
27
+ # You must call client.Authorize with valid credentials
28
+ # before using any Commands.
19
29
  def self.client
20
- @client ||= Client.new client_id, client_secret, :hub_serial => hub_serial
30
+ @client ||= Client.new client_id, client_secret
21
31
  end
22
32
  end
@@ -1,47 +1,71 @@
1
1
  module Ketra
2
+
3
+ # The Ketra::Client class is used for gaining an Access Token for
4
+ # authorization and performing GET and POST requests to the Ketra API
2
5
  class Client
6
+ # Production Host base url
3
7
  PRODUCTION_HOST = 'https://my.goketra.com'
8
+ # Test Host base url
4
9
  TEST_HOST = 'https://internal-my.goketra.com'
10
+ # Endpoint prefix to be attached to the base url before the rest of the endpoint
5
11
  LOCAL_ENDPOINT_PREFIX = 'ketra.cgi/api/v1'
6
12
 
7
13
  attr_accessor :options
8
14
  attr_reader :id, :secret, :access_token
9
15
 
10
- def initialize(id, secret, options = {}, &block)
16
+ # Instantiate a new Ketra Client using the
17
+ # Client ID and Client Secret registered to your application.
18
+ #
19
+ # @param [String] id the Client ID value
20
+ # @param [String] secret the Client Secret value
21
+ # @param [Hash] options the options to create the client with
22
+ # @option options [Symbol] :server (:production) which authorization server to use to get an Access Token (:production or :test)
23
+ # @option options [String] :redirect_uri the redirect uri for the authorization code OAuth2 grant type
24
+ # @option options [String] :hub_serial the serial number of the Hub to communicate with
25
+ def initialize(id, secret, options = {})
11
26
  opts = options.dup
12
27
  @id = id
13
28
  @secret = secret
14
29
  @options = {:server => :production,
15
- :authorization_mode => :password,
16
30
  :redirect_uri => 'urn:ietf:wg:oauth:2.0:oob',
17
31
  :hub_discovery_mode => :cloud,
18
- :connection_build => block,
19
32
  :api_mode => :local}.merge(opts)
20
33
 
21
34
  end
22
35
 
23
36
  # Authorization
24
37
 
38
+ # The authorize endpoint URL of the Ketra OAuth2 provider
39
+ #
40
+ # @return [String] authorize endpoint URL
25
41
  def authorization_url
26
42
  auth_client.auth_code.authorize_url(:redirect_uri => options[:redirect_uri])
27
43
  end
28
44
 
45
+ # Sets the access token, must supply either the access token, the authorization code,
46
+ # or the Design Studio Username and Password
47
+ #
48
+ # @param [Hash] credentials
49
+ # @option credentials [String] :token previously gained access token value
50
+ # @option credentials [String] :authorization_code code value from the Ketra OAuth2 provider
51
+ # @option credentials [String] :username Ketra Desiadgn Studio username
52
+ # @option credentials [String] :password Design Studio password
53
+ # @return [OAuth2::AccessToken] Access Token object
29
54
  def authorize(credentials)
30
- case options[:authorization_mode]
31
- when :token
55
+ if credentials.key?(:token)
32
56
  @access_token = OAuth2::AccessToken.new(auth_client, credentials[:token])
33
- when :code
57
+ elsif credentials.key?(:authorization_code)
34
58
  @access_token = auth_client.auth_code.get_token(credentials[:authorization_code],
35
59
  :redirect_uri => options[:redirect_uri])
36
- else :password
37
- byebug
60
+ elsif credentials.key?(:username)
38
61
  @access_token = auth_client.password.get_token(credentials[:username],
39
62
  credentials[:password])
40
63
  end
41
64
  end
42
65
 
43
66
  # OAuth Client
44
-
67
+ #
68
+ # @return [OAuth2::Client] oauth2 client
45
69
  def auth_client
46
70
  @auth_client ||= OAuth2::Client.new(Ketra.client_id,
47
71
  Ketra.client_secret,
@@ -49,12 +73,21 @@ module Ketra
49
73
  :ssl => { :verify => false })
50
74
  end
51
75
 
52
- # Requests
53
-
76
+ # performs a GET Request using the OAuth2 Access Token and parses the result as JSON
77
+ #
78
+ # @param [String] endpoint to be appended to the base url
79
+ # @param [Hash] params to be used as query params for the request
80
+ # @return [Hash] deserialized response hash
54
81
  def get(endpoint, params = {})
55
82
  JSON.parse access_token.get(url(endpoint), :params => params).body
56
83
  end
57
-
84
+
85
+ # performs a POST request using the OAuth2 Access Token and parses the result as JSON
86
+ #
87
+ # @param [String] endpoint to be appended to the base url
88
+ # @param [Hash] params except :query_params will be serialized into JSON and supplied as the body of the request
89
+ # @option params [Hash] :query_params to be used as the query params for the request
90
+ # @return [Hash] deserialized response hash
58
91
  def post(endpoint, params = {})
59
92
  internal_params = params.dup
60
93
  resp = access_token.post url(endpoint),
@@ -74,34 +107,26 @@ module Ketra
74
107
  PRODUCTION_HOST
75
108
  end
76
109
  end
77
-
110
+
78
111
  def url(endpoint)
79
- case options[:api_mode]
80
- when :local
81
- url = "#{local_url}/#{endpoint}"
82
- else
83
- url = "#{local_url}/#{endpoint}"
84
- end
112
+ #TODO implement additional api modes
113
+ url = "#{local_url}/#{endpoint}"
85
114
  Addressable::URI.encode(url)
86
115
  end
87
116
 
88
117
  def local_url
89
118
  "https://#{hub_ip}/#{LOCAL_ENDPOINT_PREFIX}"
90
119
  end
91
-
120
+
92
121
  def hub_ip
93
122
  @hub_ip || discover_hub(options[:hub_serial])
94
123
  end
95
-
124
+
96
125
  def discover_hub(serial_number)
97
- case options[:hub_discovery_mode]
98
- when :cloud
99
- cloud_discovery(serial_number)
100
- else
101
- cloud_discovery(serial_number)
102
- end
126
+ #TODO implement additional hub discovery modes
127
+ cloud_discovery(serial_number)
103
128
  end
104
-
129
+
105
130
  def cloud_discovery(serial_number)
106
131
  @hub_ip ||= perform_cloud_hub_discovery(serial_number)
107
132
  end
@@ -1,26 +1,51 @@
1
1
  require 'securerandom'
2
2
 
3
3
  module Ketra
4
+ # This module is used to execute specific Ketra API commands
4
5
  module Commands
6
+
7
+ # Activates a keypad button at a specific brightness level
8
+ #
9
+ # @param [String] keypad the GUID or Name of the keypad containing the button you want to activate
10
+ # @param [String] button the GUID or Name of the keypad button you want to activate
11
+ # @param [Integer] level (65535) the brightness level from 0 to 65535
12
+ # @return [Hash] deserialized response hash
5
13
  def self.activate_button(keypad, button, level=65535)
6
14
  Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/Activate",
7
15
  :Level => level)
8
16
  end
9
17
 
18
+ # Deactivates a keypad button
19
+ #
20
+ # @param [String] keypad the GUID or Name of the keypad containing the button you want to deactivate
21
+ # @param [String] button the GUID or Name of the keypad button you want to deactivate
22
+ # @return [Hash] deserialized response hash
10
23
  def self.deactivate_button(keypad, button)
11
24
  Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/Deactivate",
12
25
  :Level => 0)
13
26
  end
14
27
 
28
+ # Pushes a keypad button which will either activate or deactivate based on its current state
29
+ # and the configuration of the keypad settings
30
+ #
31
+ # @param [String] keypad the GUID or Name of the keypad containing the button you want to deactivate
32
+ # @param [String] button the GUID or Name of the keypad button you want to deactivate
33
+ # @return [Hash] deserailized response hash
15
34
  def self.push_button(keypad, button)
16
35
  Ketra.client.post("Keypads/#{keypad}/Buttons/#{button}/PushButton",
17
36
  :query_params => { :idempotency_key => SecureRandom.hex })
18
37
  end
19
-
38
+
39
+ # Queries for the available Ketra Keypads
40
+ #
41
+ # @return [Hash] deserialized response hash containing the keypad info, see Ketra API documentation for details
20
42
  def self.keypads
21
43
  Ketra.client.get("Keypads")
22
44
  end
23
45
 
46
+ # Queries for the available Ketra Groups
47
+ #
48
+ # @return [Hash] deserialized response hash containing the group info, see Ketra API documentation for details
24
49
  def self.groups
25
50
  Ketra.client.get("Groups")
26
51
  end
@@ -1,3 +1,4 @@
1
1
  module Ketra
2
- VERSION = "0.4.0"
2
+ # current RubyGem version
3
+ VERSION = "0.5.0"
3
4
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ketra
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.0
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kenneth Priester
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2017-12-21 00:00:00.000000000 Z
11
+ date: 2017-12-31 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: oauth2
@@ -120,6 +120,20 @@ dependencies:
120
120
  - - ">="
121
121
  - !ruby/object:Gem::Version
122
122
  version: '0'
123
+ - !ruby/object:Gem::Dependency
124
+ name: coveralls
125
+ requirement: !ruby/object:Gem::Requirement
126
+ requirements:
127
+ - - ">="
128
+ - !ruby/object:Gem::Version
129
+ version: '0'
130
+ type: :development
131
+ prerelease: false
132
+ version_requirements: !ruby/object:Gem::Requirement
133
+ requirements:
134
+ - - ">="
135
+ - !ruby/object:Gem::Version
136
+ version: '0'
123
137
  description: A friendly Ruby interface to the Ketra API
124
138
  email:
125
139
  - kennethjpriester@gmail.com