cloud-api-http-client
Lightweight wrapper for littleBits Cloud HTTP API
Installation
npm install --save littlebits-cloud-http
Example
var api = // We've created a new instance of our api with an access_token to be used by all requests. api = api// All api functions will now default to using device_id// 'foobar' for those abstracting HTTP endpoints that use// the {device_id} path-param (e.g. /devices/{device_id}/output). api// -> <err> <result>// Neat; By default functions log to console// which is great for playing around. api// The device_id can also be specified as the// first argument (overriding defaults, not mutating),// allowing the second argument to focus on// your payload... api// like so :). Of course you can work with objects only// as needed/desired... api// Hm, these arguments are getting repetitive, lets stop this. var output = apioutput// Better. Now we have a output function with new defaults.// and we can always call .defaults again should we wish.// Lets use it now. ;// Pass your own callback to handle the// the io error and/or return value. This of course// elliminates the default logging seen above. // Helpful notes about .defaults() // 1. it does not mutate// - .defaults() on the api object returns an entirely new api// - .defaults() on a function returns an entirely new functionassert api !== api // 2. it is infinitly recrusive so this is possible (but psychotic)api/* ad infinitum*/output /* ad infinitum */ // 3. defaults can be introspected by passing no arguments, e.g. given a stock api instnaceapi// -> { host: 'https://api-http.littlebitscloud.cc', version: '2' } // Fin. // You've seen several different function signatures.// They are at your disposal to choose as desired.// See API docs for more details and Have fun!
API Functions
Abbreviated information. See API Function Signatures for details about the argument pattern uniformly accepted.
.defaults()
See Defaults System.
Key Points:
- Supports snake_case or camelCase key names
- Returns new instances, does not mutate existing defaults
- Returns current defaults if invoked with no arguments
.devices()
Get information for all devices.
callback
result argument: [Device]
.device()
Get information for one device.
options
arguments
device_id :: String
callback
result argument: Device
.activate()
Activate one device. (FYI: associates device to user; User id is attained from the provided access_token)
options
arguments
device_id :: String
callback
result argument: Device
.deactivate()
Dectivate one device.
options
arguments
device_id :: String
callback
result argument: Device
.output()
Send amplitude out of the device.
options
arguments:
percent :: Float | >= 0, <= 100
duration_ms :: Integer | >= 0
device_id :: String
callback
result argument: TODO
.light()
Activate device light.
options
arguments:
color :: String | "green" "yellow" "red" "blue" "purple" "white" "cyan" "clownbarf"
mode :: String | "blink" "hold"
duration_ms :: Integer | >= 0
device_id :: String
callback
result argument: TODO
.subscriptions()
Get the subscriptions for given sub/pub.
options
arguments:
?
subscriber_id :: device_id || uri
Filter subscriptions to those wheresubscriber_id
matches.?
publisher_id :: device_id
Filter subscriptions to those wherepublisher_id
matches.
callback
result argument: [Subscription]
.unsubscribe()
Delete the subscription for given sub/pub.
options
arguments:
subscriber_id :: device_id || uri
publisher_id :: device_id
callback
result argument: TODO
.subscribe()
Create a new subscription for given sub/pub.
options
arguments:
subscriber_id :: device_id || uri
publisher_id :: device_id
?
publisher_events :: [Event]
Defaults to:["amplitude:delta:ignite"]
callback
result argument: TODO
Types
Event
A String of any following value:
"amplitude"
"amplitude:delta:sustain"
"amplitude:delta:ignite"
"amplitude:delta:release"
"amplitude:delta:nap"
"amplitude:level:active"
"amplitude:level:idle"
Subscription
{
subscriber_id :: device_id || URI
publisher_id :: device_id
publisher_events :: [Event]
}
Device
{
id :: String
user_id :: Integer
label :: String
subscribers :: [Subscription]
subscriptions :: [Subscription]
}
API Function Signatures
All API functions (***except .defaults
***) are variadic-polymorphic, following these defintions.
Arity 0
f :: -> void
e.g.:
api
Arity 1
f :: (err, * -> void) -> void
f :: ID -> void
f :: Options -> void
e.g.:
apiapiapi
Arity 2
f :: ID, (err, * -> void) -> void
f :: Options, (err, * -> void) -> void
f :: ID, Options -> void
e.g.:
apiapiapi
Arity 3
f :: ID, Options, (err, * -> void) -> void
e.g.:
api
For all arity cases:
-
Options
arguments that you omit are patched by defaults. You may customize defaults (see next section). -
ID
refers todevice_id
which can alternatively be argued inOptions
asdevice_id
. Certain functions do not need adevice_id
, such assubscribe
in which case it is useless (but harmless), to argue this. -
callback
is patched byconsole.log
. This is useful for rapid manual tests, playing around, etc. It also helps keep track of unhandledcallbacks
which you should be handling in non-trivial work. If you really want anoop
then just argue one.
Defaults system
.defaults()
get
defaults :: -> Options
Get the current defaults.
set
defaults :: Options -> API
Create a new api with new defaults. Existing api instance is not mutated. All functions of new api instance will read from these new defaults.
This is a good place to argue access_token
etc.
options
arguments:
?
host :: URI
The HTTP server to make requests against. By default equals'api-http.littlebitscloud.cc'
but you may override as desired, e.g. work against local development servers.?
version :: String
The littleBits Cloud HTTP API version to use. By default equals'2'
.?
access_token :: String
The OAuth access_token that will be used by the server to authorize your requsts.
.{api_function}.defaults()
get
defaults :: -> Options
Get the current defaults.
set
defaults :: Options -> API_Function
Create a new api function (f) with new defaults. Existing f is not mutated.
options
arguments: See docs for each function respectively.