Nefariously Programmed Mecha

    @smartthings/core-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    5.1.1 • Public • Published

    SmartThings Core SDK

    The SmartThings Core SDK is a wrapper designed to simplify the use of the SmartThings REST API from JavaScript and TypeScript applications. This is the very first release of this SDK and should be considered a work in progress. Changes may still be made that are not backwardly compatible.

    Installation

    npm install @smartthings/core-sdk

    Importing

    NodeJS:

    const {SmartThingsClient} = require('@smartthings/core-sdk')

    Or ES2015+:

    import {SmartThingsClient} from '@smartthings/core-sdk'

    Example Usage

    Substitue your Personal Access Token (PAT) with at least the r:locations:* scope for {YOUR-PAT-TOKEN} in the following code.

    const {SmartThingsClient, BearerTokenAuthenticator} = require('@smartthings/core-sdk')
    const client = new SmartThingsClient(new BearerTokenAuthenticator('{YOUR-PAT-TOKEN}'))
    
    client.locations.list().then(locations => {
        console.log(`Found ${locations.length} locations`)
    })

    Logging

    There is some logging done of requests and responses made to the API. The default logger does nothing but you can pass your own. Logging is done via a generic interface so you can use whatever logger you want in your application.

    First, write an implementation of the Logger interface defined in logger.ts which proxies to your logger. For example:

    import { Logger as WinstonLogger } from 'winston'
    import { Logger } from '@smartthings/core-sdk'
    
    
    export class WinstonLoggerProxy implements Logger {
    	proxy: WinstonLogger
    	level: string
    
    	constructor(winstonLogger) {
    		this.level = proxy.level
    	}
    
    	trace(message: any, ...args: any[]): void {
    		// Winston doesn't have a "trace" level but it has a "silly" level in the same place.
    		proxy.silly(message, args)
    	}
    
    	debug(message: any, ...args: any[]): void {
    		proxy.debug(message, args)
    	}
    
    	info(message: any, ...args: any[]): void {
    		proxy.info(message, args)
    	}
    
    	...
    
    	isTraceEnabled(): boolean {
    		return proxy.isSillyEnabled()
    	}
    
    	...
    }

    Then, when you create your SmartThingsClient, pass this in via the config parameter.

    const config = {
    	logger: new WinstonLoggerProxy(myWinstonLoggerInstance)
    }
    const client = new SmartThingsClient(new BearerTokenAuthenticator('{YOUR-PAT-TOKEN}'), config)

    Reference

    Authenticators

    This SDK supports multiple ways of authenticating with the SmartThings platform. The currently available authenticators are:

    • BearerTokenAuthenticator -- Authenticator that is instantiated with any valid bearer token. This is the authenticator you would use with a PAT (Personal Access) Token.

    • RefreshTokenAuthenticator -- Authenticator that is instantiated with a bearer token and a RefreshTokenStore that provides methods for retrieving and storing access and refresh tokens. When this authenticator is used the API will automatically refresh expired access tokens, save the new tokens, and retry the original request.

    • SequentialRefreshTokenAuthenticator

    Endpoints

    • apps -- A SmartApp can be an AWS lambda function or WebHook endpoint. Like to code interface here, link to wiki page description here

    • capabilities - Operations to read standard capability definitions as well as create and modify custom capabilities. Link to code interface here, link to wiki page here.

    • deviceProfiles - A device profile contains the components, capabilities, and metadata (ID, name, ownership, etc.) that define a SmartThings device. Link to code interface here, link to wiki page here

    • devices - Operations to access, control, create, update, and delete devices. Like to code interface here, link to wiki page here

    • history - Operations to query event history. Link to code interface here.

    • installedApps - Apps are installed by users. Link to code interface here, link to wiki page descripotion here

    • locations - Locations can include hubs, devices, and Automations. Link to code interface here, link to wiki page description here

    • modes - Operations to change the current mode of a location. Link to code interface here, link to wiki page description here

    • notifications - Operations to send push notifications to SmartThings mobile app. Link to code interface here, link to wiki page description here

    • organizations - Operations to list and get organizations. Link to code interface here. Future feature. Not yet supported.

    • presentation - Operation on device configurations and presentations. Link to code interface here.

    • rooms - Operations related to Rooms, a grouping of devices within a location. Link to code interface here, link to wiki page description here

    • rules - Operations for working with Rules. Rules allow you to create automations that can operate on SmartThings connected devices. Link to code interface here, link to wiki page description here

    • scenes - Operations to list and execute scenes. Currently this endpoint does not support creating or updating scenes. Link to code interface here, link to wiki page description here

    • schedules - Operations for schedules for use in SmartApps. Link to code interface here, link to wiki page description here

    • schema - Operations for ST Schema connectors and installed instances, along with operations to list the devices owned by each installed instance. Link to code interface here, link to wiki page description here

    • services - Operations to query for and subscribe to location service data, currently consisting of current weather conditions, weather forecast, and air quality data. Link to code interface here, link to wiki page description here

    • subscriptions - Operations for subscribing to events, for use in SmartApps and API Access apps. Link to code interface here, link to wiki page description here

    Keywords

    none

    Install

    npm i @smartthings/core-sdk

    DownloadsWeekly Downloads

    1,231

    Version

    5.1.1

    License

    Apache-2.0

    Unpacked Size

    461 kB

    Total Files

    102

    Last publish

    Collaborators

    • john-u
    • workmonk
    • xres
    • bflorian
    • erode
    • smartthingspi
    • rossiam
    • jodyalbritton