Tidbyt Client for Node.js

Unofficial API client for the Tidbyt API. Use this client to control Tidbyt devices and integrate with other services.

Installation

You can install the package with npm:

> npm install tidbyt

Usage

const Tidbyt = require('tidbyt')

async function main() {
    const deviceId = process.argv[2]
    const tidbyt = new Tidbyt(process.env.TIDBYT_API_TOKEN)

    // get our requested device
    const device = await tidbyt.devices.get(deviceId)
    const { displayName, lastSeen } = device

    console.log(displayName, `Last Seen: (${lastSeen})`)

    // get a list of officially available apps
    // return as map so we can lookup app name/descriptions by id
    const apps = await tidbyt.apps.list({ asMap: true })

    // get the list of installations for this device
    const installations = await device.installations.list()

    for (const { id, appID } of installations) {
        const {
            name = 'Custom',
            description = `Unlike a regular Tidbyt app, this "installation" was pushed to ${displayName} via Tidbyt's API.`,
        } = apps.get(appID) || {}

        console.log(``)
        console.log(`  ${name} - ${id}`)
        console.log(`      ${description}`)
    }
}
main()

Classes

TidbytDevice

Kind: global class
Scope: Tidbyt

• TidbytDevice
  • new TidbytDevice(options, client)
  • .installations : object
    • .list() ⇒ Promise.<Array.<TidbytDeviceInstallation>>
    • .update(installationID, image) ⇒ Promise.<Object>
    • .delete(installationID) ⇒ Promise.<Object>
  • .update(updates) ⇒ Promise.<TidbytDevice>
  • .push(image, options) ⇒ Promise.<Object>

new TidbytDevice(options, client)

Construct a TidbytDevice with provided options.

A valid client is required to use any methods.

Available options:

 - `id`: the device id

 - `lastSeen`: the last time the device was seen

 - `brightness`: the brightness of the device from 0-100

 - `displayName`: the display name of the device

 - `autoDim`: whether the device is auto dimming at night

| Param | Type | | --- | --- | | options | Object | | client | TidByt |

tidbytDevice.installations : object

Kind: instance property of TidbytDevice

• .installations : object
  • .list() ⇒ Promise.<Array.<TidbytDeviceInstallation>>
  • .update(installationID, image) ⇒ Promise.<Object>
  • .delete(installationID) ⇒ Promise.<Object>

installations.list() ⇒ Promise.<Array.<TidbytDeviceInstallation>>

Return a list of installations on the device from the Tidbyt API.

Kind: instance method of installations

installations.update(installationID, imageOrConfig) ⇒ Promise.<Object>

Update an existing installation, either by providing a config object or a buffer containing the image.

Note: Updating configuration only works on Tidbyt-hosted applications. Push an updated image to update custom applications.

Throws if not client is intialized or if no installation ID is provided. Throws if an invalid image or config is provided.

Kind: instance method of installations

| Param | Type | Description | | --- | --- | --- | | installationID | String | Optional installation ID to create/update | | image | Buffer | Buffer containing the images to push |

installations.delete(installationID) ⇒ Promise.<Object>

Delete an existing installation from the device.

Throws if not client is intialized.

Kind: instance method of installations

| Param | Type | Description | | --- | --- | --- | | installationID | String | Optional installation ID to create/update |

tidbytDevice.update(updates) ⇒ Promise.<TidbytDevice>

Update a device with the provided values.

Throws if not client is intialized.

Available fields:

 - `autoDim`: whether the device is auto dimming at night

 - `brightness`: the brightness of the device from 0-100

 - `displayName`: the display name of the device

Kind: instance method of TidbytDevice

| Param | Type | | --- | --- | | updates | Object |

tidbytDevice.push(image, options) ⇒ Promise.<Object>

Push a new installation to the device.

Throws if not client is intialized.

Available options:

installationID: Installation ID to create/update

background: Whether the installation should not interrupt the rotation

Kind: instance method of TidbytDevice

| Param | Type | Description | | --- | --- | --- | | image | Buffer | Buffer containing the images to push | | options | Object | |

Tidbyt

Kind: global class

• Tidbyt
  • new Tidbyt(apiToken, version)
  • .apps : object
    • .list(options) ⇒ Promise.<(Array.<Object>|Map)>
  • .devices : object
    • .get(deviceId) ⇒ Promise.<TidbytDevice>
    • .update(deviceId, updates) ⇒ Promise.<TidbytDevice>
    • .push(deviceId, image, [options]) ⇒ Promise.<Object>
  • .request(path, method, body, headers, raw, encoding) ⇒ Promise.<(Object|Buffer)>

new Tidbyt(apiToken, version)

Construct a Tidbyt with provided options.

Available options:

 - `apiToken`: the API token

 - `apiVersion`: the API version. Defaults to `v0`

| Param | Type | Default | | --- | --- | --- | | apiToken | String | | | version | String | 'v0' |

tidbyt.apps : object

Kind: instance property of Tidbyt

apps.list(options) ⇒ Promise.<(Array.<Object>|Map)>

Return a list of available apps from the Tidbyt API.

Available options:

 - `asMap`: Defaults to false. If true, returns a map of app ids to app objects instead of an array of app objects.

Kind: instance method of apps

| Param | Type | | --- | --- | | options | Object |

tidbyt.devices : object

Kind: instance property of Tidbyt

• .devices : object
  • .get(deviceId) ⇒ Promise.<TidbytDevice>
  • .update(deviceId, updates) ⇒ Promise.<TidbytDevice>
  • .push(deviceId, image, [options]) ⇒ Promise.<Object>

devices.get(deviceId) ⇒ Promise.<TidbytDevice>

Get a device by id from the Tidbyt API.

Kind: instance method of devices

| Param | Type | Description | | --- | --- | --- | | deviceId | String | The device id |

devices.update(deviceId, updates) ⇒ Promise.<TidbytDevice>

Update a device with the provided values by ID.

Available updates:

 - `autoDim`: whether the device is auto dimming at night

 - `brightness`: the brightness of the device from 0-100

 - `displayName`: the display name of the device

Kind: instance method of devices

| Param | Type | Description | | --- | --- | --- | | deviceId | String | The device id | | updates | Object | |

devices.push(deviceId, image, [options]) ⇒ Promise.<Object>

Push a new installation to a device by ID.

Throws if not client is intialized.

Available options:

installationID: Installation ID to create/update

background: Whether the installation should not interrupt the rotation

Kind: instance method of devices

| Param | Type | Description | | --- | --- | --- | | deviceId | String | The device id | | image | Buffer | Buffer containing the images to push | | [options] | Object | Push options |

tidbyt.request(path, method, body, headers, raw, encoding) ⇒ Promise.<(Object|Buffer)>

Send a request to the Tidbyt API.

Kind: instance method of Tidbyt

| Param | Type | Default | | --- | --- | --- | | path | String | | | method | String | 'GET' | | body | Object | | | headers | Object | {} | | raw | Boolean | | | encoding | String | |