README.md

#Initial State Initial State is a hosted service that allows you to easily push event based data.

This library wraps Initial State Event API (aka groker).

Usage

Instantiating the class

Instantiate the InitialState class with your Access Key, Bucket Key, and optionally, Bucket Name:

is <- InitialState(IS_ACCESS_KEY, IS_BUCKET_KEY, "optional bucket name");

Send Events

There are two methods to send events to Initial State. One method is.sendEvent is for singular events. The other method is.sendEvents is for a batch of events. If a third parameter, a callback function, is supplied, the request will be made asyncronously and the callback will be fired when the request is complete. If the callback function is ommited, the request will be made syncronously, and result will be returned. Examples of each usage are below:

####Sending Single Event

// send an event sycronously
local result = is.sendEvent("temperature", 72);
if (result.err != null) {
    server.log("Error: " + result.err);
}

// send an event asyncronously
is.sendEvent("temperature", 72, function(err, data) {
    if (err != null) {
        server.log("Error: " + err);
    }
});

####Sending Multiple Events (i.e. sensor readings)

// send an event sycronously
local result = is.sendEvents([
    {"key": "temperature", "value": 72},
    {"key": "humidity", "value": 55}
]);
if (result.err != null) {
    server.log("Error: " + result.err);
}

// send an event asyncronously
is.sendEvents([
    {"key": "temperature", "value": 72},
    {"key": "humidity", "value": 55}
], function(err, data) {
    if (err != null) {
        server.log("Error: " + err);
    }
});

Overriding Event Timestamp

You can optionally override the timestamp of an event by passing in an epoch to the .sendEvent or .sendEvents methods. Here is how to achieve this respectively:

// override timestamp for single event
local time = time();
is.sendEvent("temperature", 72, time);

// override timestamp for multiple events
is.sendEvents([
    {"key": "temperature", "value": 72, "epoch": time },
    {"key": "humidity", "value": 55, "epoch": time }
]);

License

The Initial State library is licensed under the MIT License.

InitialState.class.nut

// Copyright (c) 2015 Initial State Technologies, Inc.
// This file is licensed under the MIT License
// http://opensource.org/licenses/MIT

class InitialState {
    static _baseUrl = "https://groker.initialstate.com/api/";
    static _apiVersion = "~0";
    _bucketKey = null;
    _accessKey = null;
    _bucketName = null;
    _isBucketCreated = false;
    
    _bucketRequestHeaders = null;
    _eventRequestHeaders = null;
    
    constructor(accessKey, bucketKey, bucketName = "") {
        if (bucketName == "")
            bucketName = bucketKey;

        this._bucketKey = bucketKey;
        this._accessKey = accessKey;
        this._bucketName = bucketName;
        
        this._bucketRequestHeaders = {
            "Content-Type": "application/json",
            "X-IS-AccessKey": accessKey,
            "Accept-Version": _apiVersion
        };

        this._eventRequestHeaders = {
            "Content-Type": "application/json",
            "X-IS-AccessKey": accessKey,
            "X-IS-BucketKey": bucketKey,
            "Accept-Version": _apiVersion
        }
    }

    function createBucket(cb = null) {

        local url = _baseUrl + "buckets";
        local data = http.jsonencode({
            "bucketName": _bucketName,
            "bucketKey": _bucketKey
        });
        local req = http.post(url, _bucketRequestHeaders, data);
        
        if (cb != null) {
            req.sendasync(function(respon) {
                local err = null;
                local data = null;
                if (resp.statuscode != 200 || resp.statuscode != 201 || resp.statuscode != 204)
                    err = "StatusCode: " + resp.statuscode + "Message: " + resp.body;
                else {
                    data = http.jsonencode(resp.body);
                    _isBucketCreated = true;
                }
                cb(err, data);
            });
        } else {
            local returnData = { err = null, data = null };
            local resp = req.sendsync();
            if (resp.statuscode != 200 || resp.statuscode != 201 || resp.statuscode != 204)
                returnData.err = "StatusCode: " + resp.statuscode + "Message: " + resp.body;
            else{
                returnData.data = http.jsonencode(resp.body);
                _isBucketCreated = true;
            }

            return returnData;
        }
    }

    function sendEvents(events, cb = null) {
        if (_isBucketCreated == false) {
            createBucket();
        }
        
        local url = _baseUrl + "events";
        server.log(url);
        local data = http.jsonencode(events);
        server.log(data);
        local req = http.post(url, _eventRequestHeaders, data);
        
        if(cb != null) {
            req.sendasync(function(resp) {
                local err = null;
                local data = null;
                if(resp.statuscode != 200 || resp.statuscode != 202) {
                    err = resp.body;
                }
                else {
                    data = resp.body;
                }
                cb(err, data);
            });
        } else {
            local returnData = { err = null, data = null };
            local resp = req.sendsync();
            if(resp.statuscode != 200 || resp.statuscode != 202) {
                returnData.err = resp.body;
            }
            else {
                returnData.data = resp.body;
            }
            
            return returnData;
        }
    }
    
    function sendEvent(eventKey, eventValue, epoch = null, cb = null) {
        if (_isBucketCreated == false) {
            createBucket();
        }

        local url = _baseUrl + "events";
        local eventObject = {
            key = eventKey,
            value = eventValue
        };
        if (epoch != null) {
            eventObject = {
                key = eventKey,
                value = eventValue,
                epoch = epoch
            };
        }

        local data = http.jsonencode(eventObject);
        local req = http.post(url, _eventRequestHeaders, data);
        
        if(cb != null) {
            req.sendasync(function(resp) {
                local err = null;
                local data = null;
                if(resp.statuscode != 200 || resp.statuscode != 202) {
                    err = resp.body;
                }
                else {
                    data = resp.body;
                }
                cb(err, data);
            });
        } else {
            local returnData = { err = null, data = null };
            local resp = req.sendsync();
            if(resp.statuscode != 200 || resp.statuscode != 202) {
                returnData.err = resp.body;
            }
            else {
                returnData.data = resp.body;
            }
            
            return returnData;
        }
    }
}

LICENSE

The MIT License (MIT)

Copyright (c) 2015 Initial State Technologies, Inc

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.