lifx_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 055c814b51eff3591097009aed7385b3022fd6e2
+  data.tar.gz: d66f4c78f22718034ae0de373b357e344730ac80
+SHA512:
+  metadata.gz: 3be95ba0e47d8d6e1eb53d2bdd7c557e1f755eab02b9ceea431dc7df6d8bde85a40be32e9afcbebcfde145d6b32a4156005f87113087028ca56b2a9e6cdf5a84
+  data.tar.gz: bbf46d92d4e5362098886b8677778ef24d2bba265f59f11c41ef5b9d2e0a3776ff736f20e05eb53b126944e5d8aad18d60367ff7dfb785dcfa0f34c484a0d7d1

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# LifxApi
+
+A Ruby client for the LIFX API.
+
+This provides access to the [LIFX HTTP API](https://api.developer.lifx.com/), so it can control your lights from anywhere in the world. It does not implement the [LAN API](https://lan.developer.lifx.com/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lifx_api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lifx_api
+
+## Usage
+
+You'll need to have some LIFX bulbs already setup and configured. Then you will need to obtain an `access_token` from the [LIFX website](https://cloud.lifx.com/sign_in).
+
+```ruby
+require 'lifx_api'
+
+access_token = "a1b7349df2a...e213"
+client = LifxApi.new access_token
+lights = client.list_lights
+exit() if lights.count == 0
+light_id = lights.first[:id]
+
+client.toggle_power selector: 'all'
+
+client.toggle_power selector: "id:#{light_id}"
+```
+
+## Endpoints and parameters
+
+### TODO. See [LIFX HTTP API](https://api.developer.lifx.com/) in the mean time
+
+## Deviation from the API spec
+
+Some API endpoints require a mandatory [`selector`](https://api.developer.lifx.com/docs/selectors) parameter, which defines which bulbs to apply your action to. This client will default the `selector` parameter to `'all`', if no selector is provided.
+
+```ruby
+# which means that you can call
+client.list_bulbs
+# ...and receive a hash of all your bulbs back
+
+# instead of having to explicitly specify you want all bulbs:
+client.list_bulbs selector: 'all'
+```
+
+## Exceptions
+
+If there is an error, LifxApi will raise an exception. The exception message will usually give a good indication of what went wrong, but you can also rescue the exception and access the request, response and decoded JSON objects, via the `request`, `response` and `data` methods.
+
+## Development
+
+Run `rake test` to run the tests and `rake console` to start an interactive pry console.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cyclotron3k/lifx_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+	t.libs << "test"
+	t.libs << "lib"
+	t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test
+
+desc "Launch an interactive Pry console"
+task :console do
+	exec "pry -r lifx_api -I ./lib"
+end

data/lib/lifx_api/endpoints.rb

@@ -0,0 +1,121 @@
+class LifxApi
+	ENDPOINTS = [{
+		method_name: :list_lights,
+		http_method: :get,
+		path: '/v1/lights/%{selector}',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'},
+		},
+	}, {
+		method_name: :set_state,
+		http_method: :put,
+		path: '/v1/lights/%{selector}/state',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'},
+		},
+		body_params: {
+			power: {type: :string, description: 'The power state you want to set on the selector. on or off'},
+			color: {type: :string, description: 'The color to set the light to.'},
+			brightness: {type: :numeric, description: 'The brightness level from 0.0 to 1.0. Overrides any brightness set in color (if any).'},
+			duration: {type: :numeric, default_decription: '1.0', description: 'How long in seconds you want the power action to take. Range: 0.0 - 3155760000.0 (100 years)'},
+			infrared: {type: :numeric, description: 'The maximum brightness of the infrared channel.'},
+		},
+	}, {
+		method_name: :set_states,
+		http_method: :put,
+		path: '/v1/lights/states',
+		body_params: {
+			states: {required: true},
+			defaults: {type: :hash},
+		},
+	}, {
+		method_name: :stage_delta,
+		http_method: :post,
+		path: '/v1/lights/%{selector}/state/delta',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'}
+		},
+		body_params: {
+			power: {type: :on_off, description: 'The power state you want to set on the selector. on or off'},
+			duration: {type: :numeric, default_decription: '1.0', description: 'How long in seconds you want the power action to take. Range: 0.0 - 3155760000.0 (100 years)'},
+			infrared: {type: :numeric, description: 'The maximum brightness of the infrared channel.'},
+			hue: {type: :numeric, description: 'Rotate the hue by this angle in degrees.'},
+			saturation: {type: :numeric, description: 'Change the saturation by this additive amount; the resulting saturation is clipped to [0, 1].'},
+			brightness: {type: :numeric, description: 'Change the brightness by this additive amount; the resulting brightness is clipped to [0, 1].'},
+			kelvin: {type: :numeric, description: 'Change the kelvin by this additive amount; the resulting kelvin is clipped to [2500, 9000].'},
+		},
+	}, {
+		method_name: :toggle_power,
+		http_method: :post,
+		path: '/v1/lights/%{selector}/toggle',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'},
+		},
+		body_params: {
+			duration:	{type: :numeric, default_decription: '1.0', description: 'The time is seconds to spend perfoming the power toggle.'},
+		},
+	}, {
+		method_name: :breathe_effect,
+		http_method: :post,
+		path: '/v1/lights/%{selector}/effects/breathe',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'},
+		},
+		body_params: {
+			color: {required: :true, type: :string, description: 'The color to use for the breathe effect.'},
+			from_color:	{type: :string, default_decription: 'current bulb color', description: 'The color to start the effect from. If this parameter is omitted then the color the bulb is currently set to is used instead.'},
+			period: {type: :numeric, default_decription: '1.0', description: 'The time in seconds for one cyles of the effect.'},
+			cycles: {type: :numeric, default_decription: '1.0', description: 'The number of times to repeat the effect.'},
+			persist: {type: :boolean, default_decription: 'false', description: 'If false set the light back to its previous value when effect ends, if true leave the last effect color.'},
+			power_on: {type: :boolean, default_decription: 'true', description: 'If true, turn the bulb on if it is not already on.'},
+			peak: {type: :numeric, default_decription: '0.5', description: 'Defines where in a period the target color is at its maximum. Minimum 0.0, maximum 1.0.'},
+		}
+	}, {
+		method_name: :pulse_effect,
+		http_method: :post,
+		path: '/v1/lights/%{selector}/effects/pulse',
+		path_params: {
+			selector: {required: true, type: :selector, default: 'all'},
+		},
+		body_params: {
+			color: {required: true, type: :string, description: 'The color to use for the pulse effect.'},
+			from_color: {type: :string, default_decription: 'current bulb color', description: 'The color to start the effect from. If this parameter is omitted then the color the bulb is currently set to is used instead.'},
+			period: {type: :numeric, default_decription: '1.0', description: 'The time in seconds for one cyles of the effect.'},
+			cycles: {type: :numeric, default_decription: '1.0', description: 'The number of times to repeat the effect.'},
+			persist: {type: :boolean, default_decription: 'false', description: 'If false set the light back to its previous value when effect ends, if true leave the last effect color.'},
+			power_on: {type: :boolean, default_decription: 'true', description: 'If true, turn the bulb on if it is not already on.'},
+		}
+	}, {
+		method_name: :cycle,
+		http_method: :post,
+		path: '/v1/lights/%{selector}/cycle',
+		body_params: {
+			states: {required: true, type: 'array of mixed', description: 'Array of state hashes as per Set State. Must have 2 to 5 entries.'},
+			defaults: {type: 'object', description: 'Default values to use when not specified in each states[] object.'},
+			direction: {type: 'stringforward', description: 'Direction in which to cycle through the list. Can be forward or backward'},
+		}
+	}, {
+		method_name: :list_scenes,
+		http_method: :get,
+		path: '/v1/scenes',
+	}, {
+		method_name: :activate_scene,
+		http_method: :put,
+		path: '/v1/scenes/scene_id:%{scene_uuid}/activate',
+		path_params: {
+			scene_uuid: {required: true, type: :uuid, description: 'The UUID for the scene you wish to activate'},
+		},
+		body_params: {
+			duration: {type: :numeric, default_decription: '1.0', description: 'The time in seconds to spend performing the scene transition.'},
+			ignore: {type: 'array of strings', description: 'Any of "power", "infrared", "duration", "intensity", "hue", "saturation", "brightness" or "kelvin", specifying that these properties should not be changed on devices when applying the scene.'},
+			overrides: {type: 'object', description: 'A state object as per Set State specifying properties to apply to all devices in the scene, overriding those configured in the scene.'},
+		}
+	}, {
+		method_name: :validate_color,
+		http_method: :put,
+		path: '/v1/color',
+		query_params: {
+			color: {type: :string, required: true},
+		},
+	}]
+end

data/lib/lifx_api/error.rb

@@ -0,0 +1,17 @@
+class LifxApi
+	class Error < StandardError
+		attr_reader :request, :response, :data
+
+		def initialize(request, response, data=nil)
+			@request = request
+			@response = response
+			@data = data
+			message = if data.is_a?(Hash) and data.key? :error
+				"#{response.code} - #{data[:error]}"
+			else
+				"#{response.code}"
+			end
+			super message
+		end
+	end
+end

data/lib/lifx_api/version.rb

@@ -0,0 +1,3 @@
+class LifxApi
+	VERSION = '0.1.0'
+end

data/lib/lifx_api.rb

@@ -0,0 +1,125 @@
+require 'net/http'
+require 'openssl'
+require 'cgi'
+require 'json'
+require 'lifx_api/version'
+require 'lifx_api/endpoints'
+require 'lifx_api/error'
+
+class LifxApi
+
+	PROTOCOL = 'https'
+	HOST     = 'api.lifx.com'
+	DEBUG    = false
+
+	def initialize(access_token)
+		@access_token = access_token
+		@base_uri = URI "#{PROTOCOL}://#{HOST}"
+
+		@agent = Net::HTTP.new @base_uri.host, @base_uri.port
+		@agent.use_ssl = PROTOCOL == 'https',
+		@agent.keep_alive_timeout = 10
+		@agent.set_debug_output $stdout if DEBUG
+	end
+
+	ENDPOINTS.each do |endpoint_spec|
+		define_method endpoint_spec[:method_name], Proc.new { |params={}|
+			parsed_params = parse_params endpoint_spec, params
+			request = create_request endpoint_spec, parsed_params
+			process_request request
+		}
+	end
+
+	private
+
+	def parse_params(endpoint_spec, params)
+		[:path_params, :body_params, :query_params].each_with_object({}) do |field, parsed|
+			next unless endpoint_spec[field]
+
+			parsed[field] = endpoint_spec[field].each_with_object({}) do |(key, field_spec), clean|
+				value = params[key] || field_spec[:default]
+				raise "Missing #{key}" if field_spec[:required] and value.nil?
+				next if value.nil?
+				raise ArgumentError, "#{key} (#{value}) failed validation" unless valid? value, field_spec[:type]
+				clean[key] = value
+			end
+		end
+	end
+
+	def valid?(value, value_format)
+		case value_format
+		when :selector
+			value =~ /^((label|id|(location|group)(_id)?|scene_id):.*|all)$/
+		when :numeric
+			value.is_a?(Numeric) or value =~ /^[\d\.]+$/
+		when :boolean
+			['true', 'false', true, false].include? value
+		when :on_off
+			['on', 'off'].include? value
+		when :hash
+			value.is_a? Hash
+		when :string
+			value.is_a? String
+		when :uuid
+			value.is_a?(String) and value =~ /^[\da-f]{4}([\da-f]{4}-){4}[\da-f]{12}$/
+		else
+			puts "Don't know how to validate #{value_format}" if DEBUG
+			true
+		end
+	end
+
+	def create_request(endpoint_spec, params)
+		uri = @base_uri.clone
+
+		uri.path = if params.key? :path_params
+			endpoint_spec[:path] % Hash[params[:path_params].map { |k, v| [k, CGI.escape(v).gsub('+', '%20')]}]
+		else
+			endpoint_spec[:path]
+		end
+
+		if params.key? :query_params
+			uri.query = URI.encode_www_form params[:query_params]
+		end
+
+		request = case endpoint_spec[:http_method]
+		when :get
+			Net::HTTP::Get.new uri
+		when :put
+			Net::HTTP::Put.new uri
+		when :post
+			Net::HTTP::Post.new uri
+		else
+			raise NotImplementedError, "Invalid HTTP method: #{endpoint_spec[:http_method]}"
+		end
+
+		if params.key? :body_params
+			request.set_form_data params[:body_params]
+		end
+
+		request
+	end
+
+	def process_request(request)
+		request['Authorization'] = "Bearer #{@access_token}"
+
+		puts "\n\n\e[1;32mDespatching request to #{request.path}\e[0m" if DEBUG
+
+		@session = @agent.start unless @agent.active?
+		response = @session.request request
+
+		puts "\e[1;32mResponse received\e[0m" if DEBUG
+
+		data = case response['content-type']
+		when /application\/json/
+			JSON.parse response.read_body, symbolize_names: true
+		else
+			raise "Don't know how to parse #{response['content-type']}"
+		end
+
+		unless (200..299).include? response.code.to_i
+			raise LifxApi::Error.new request, response, data
+		end
+
+		data
+	end
+end

data/lifx_api.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "lifx_api/version"
+
+Gem::Specification.new do |spec|
+	spec.name          = "lifx_api"
+	spec.version       = LifxApi::VERSION
+	spec.authors       = "cyclotron3k"
+
+	spec.summary       = "A client for the LIFX HTTP API"
+	spec.homepage      = "https://github.com/cyclotron3k/lifx_api"
+	spec.license       = "MIT"
+
+	spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+		f.match(%r{^(test|spec|features)/})
+	end
+
+	spec.require_paths = ["lib"]
+
+	spec.add_development_dependency "bundler", "~> 1.15"
+	spec.add_development_dependency "rake", "~> 10.0"
+	spec.add_development_dependency "minitest", "~> 5.0"
+	spec.add_development_dependency "pry", "~> 0.10"
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: lifx_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- cyclotron3k
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/lifx_api.rb
+- lib/lifx_api/endpoints.rb
+- lib/lifx_api/error.rb
+- lib/lifx_api/version.rb
+- lifx_api.gemspec
+homepage: https://github.com/cyclotron3k/lifx_api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A client for the LIFX HTTP API
+test_files: []