lifx-http-api

    1.0.3 • Public • Published

    Lifx HTTP Api Node.js Wrapper

    NPM Version Dependency Status Build Status License MIT codecov.io

    A thin Node.js API wrapper of the Lifx HTTP protocol.

    This library is not, in any way, affiliated or related to Lifi Labs, Inc.. Use at your own risk.

    Installation

    $ npm install lifx-http-api --save

    Compatibility

    Node.js 4.2.6+ is tested and supported on Mac, Linux and Windows.

    Bearer Token

    A bearer token is mandatory to use the API. A new token can be obtain in the Lifx Cloud Settings.

    Usage

    The thin API wrapper uses a client for network communication. This client handles all requests against the Lifx API.

    var lifx = require('lifx-http-api'),
        client;
        
    client = new lifx({
        bearerToken: '<your api token>'
    });

    The Client object provides promises by the great Q library. You can either use callbacks or promises.

    // Using callbacks
    client.listLights('all', function(err, data) {
        if(err) {
         console.error(err);
         return;
        }
        
        console.log(data)
    });
     
    // Using promises
    client.listLights('all').then(console.log, console.error);

    Getting lights and scenes

    client.listLights(selector, [cb])

    Gets lights belonging to the authenticated account. Filter the lights using selectors.

    Option Type Default Description
    selector string Selector for the light bulb you want to get. See the Selector section to get more information.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.listLights('all', function(err, data) {
        if(err) {
         console.error(err);
         return;
        }
        
        console.log(data)
    });
     
    // Using promises
    client.listLights('all').then(console.log, console.error);

    Modifying light state

    client.setState(selector, settings, [cb])

    Sets the state of the lights within the selector.

    Option Type Default Description
    selector string Selector for the light bulb you want to get. See the Selector section to get more information.
    settings object {} State configuration object. See the official documentation for further information.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.setState('all', {
        power: 'on',
        color: 'blue saturation:0.5',
        brightness: 0.5,
        duration: 5
    }, function(err, data) {
        if(err) {
         console.error(err);
         return;
        }
        
        console.log(data)
    });
     
    // Using promises
    client.setState('all', {
        power: 'on',
        color: 'blue saturation:0.5',
        brightness: 0.5,
        duration: 5
    }).then(console.log, console.error);

    client.setStates(settings, [cb])

    This endpoint allows you to set different states on multiple selectors in a single request.

    Option Type Default Description
    settings Mixed {} Multiple State configuration object. See the official documentation for further information.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.setState('all', {
        "states": [ {
            "selector": "all",
            "power": "on"
        }, {
            "selector": "group:test",
            "brightness": 0.5
        } ],
        "defaults": {
            "duration": 5.0
        }
    }, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    client.togglePower(selector, [duration], [cb])

    Turn off lights if they are on, or turn them on if they are off. Physically powered off lights are ignored.

    Option Type Default Description
    selector string all Selector for the light bulb you want to get. See the Selector section to get more information.
    duration int 0 Turning on or off will be faded over the time (in seconds).
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.togglePower('all', 1.5, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    client.breathe(selector, [settings], [cb])

    Performs a breathe effect by slowly fading between the given colors. Use the parameters to tweak the effect.

    Option Type Default Description
    selector string all Selector for the light bulb you want to get. See the Selector section to get more information.
    settings Object {} Breathe effect object, see the official documentation for all available parameter.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.breathe('all', {
        color: '#006633',
        from_color: '#00AF33',
        period: 1,
        cycles: 10,
        persist: true,
        power_on: true,
        peak: 0.8
    }, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    client.pulse(selector, [settings], [cb])

    Performs a pulse effect by quickly flashing between the given colors. Use the parameters to tweak the effect.

    Option Type Default Description
    selector string all Selector for the light bulb you want to get. See the Selector section to get more information.
    settings Object {} Pulse effect object, see the official documentation for all available parameter.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.pulse('all', {
        color: '#006633',
        from_color: '#00AF33',
        period: 1,
        cycles: 10,
        persist: true,
        power_on: true,
        peak: 0.8
    }, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    client.cycle(selector, [settings], [cb])

    Make the light(s) cycle to the next or previous state in a list of states.

    Option Type Default Description
    selector string all Selector for the light bulb you want to get. See the Selector section to get more information.
    settings Object {} Cycle states object, see the official documentation for all available parameter.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.cycle('all', {
        "states": [{
            "brightness": 1.0
        }, {
            "brightness": 0.5
        }, {
            "brightness": 0.1
        }, {
            "power": "off"
        }],
        "defaults": {
            "power": "on", // all states default to on
            "saturation": 0, // every state is white
            "duration": 2.0 // all transitions will be applied over 2 seconds
        }
    }, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    Working with scenes

    client.listScenes([cb])

    Lists all the scenes available in the users account.

    Option Type Default Description
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.listScene(function(err, data) {
        if(err) {
         console.error(err);
         return;
        }
        
        console.log(data)
    });
     
    // Using promises
    client.listScenes().then(console.log, console.error);

    client.activateScene(selector, [duration], [cb])

    Activates a scene from the users account.

    Option Type Default Description
    selector string all Scene selector. See the Selector section to get more information.
    duration int 0 Fades to the scene (in seconds).
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.activateScene('scene_id:d073d501cf2c', 1.2, function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    Utility methods

    client.validateColor(color, [cb])

    This method lets you validate a user's color string and return the hue, saturation, brightness and kelvin values that the API will interpret as.

    Option Type Default Description
    color string Color string you'd like to validate. See the Color section to get more information.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    // Using callbacks
    client.validateColor('#0198E1', function (err, data) {
        if (err) {
            console.error(err);
            return;
        }
     
        console.log(data)
    });

    Client API

    client.getVersion()

    Returns the api version.

    Usage example:

    client.getVersion();  // outputs "v1"

    client.setVersion(version)

    Sets the api version. Returns true if the version was set sucessfully, otherwise false.

    Option Type Default Description
    version string API version which will be used by the Client object.

    Usage example:

    client.setVersion('v2beta');

    client.getUrl()

    Returns the api url.

    Usage example:

    client.getUrl();  // outputs "https://lifx.com/api/"

    client.setUrl(url)

    Sets the api url. Returns true if the url was set sucessfully, otherwise false.

    Option Type Default Description
    url string API url which will be used by the Client object.

    Usage example:

    client.setUrl('https://my-lifx-api-url.com');

    client.getApiUrl()

    Returns the full Lifx api endpoint

    Usage example:

    client.getApiUrl(); // outputs "https://lifx.com/api/v1"

    client.getBearerToken()

    Returns the bearer authentication token.

    Usage example:

    client.getBearerToken();  // outputs "<your-token>"

    client.setBearerToken(token)

    Sets the bearer authentication token. Returns true if the token was set sucessfully, otherwise false.

    Option Type Default Description
    token string Bearer authentication token which will be used by the Client object.

    Usage example:

    client.setBearerToken('<your-token>');

    client.send(settings, cb)

    Sends a request to the Lifx API.

    Option Type Default Description
    settings Object {} request configuration settings. See the offical documentation for further information.
    cb function null function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

    Usage example:

    client.send({
        url: 'lights/all/state',
        body: {
            power: 'on',
            color: 'blue saturation:0.5',
            brightness: 0.5,
            duration: 5        
        },
        method: 'PUT'
    }, function(err, data) {
        if (err) console.error(err);
        else console.log(data);
    })

    Client settings

    The Client object can be configured at initialization:

    var lifx = require('lifx-http-api'),
        client;
        
    client = new lifx({
        bearerToken: '<your api token>', // Authentication token
        version: 'v2beta', // API version
        url: 'https://api.lifx.com' // API endpoint
    });

    Install

    npm i lifx-http-api

    DownloadsWeekly Downloads

    16

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • klarstil