You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SDK that wraps the SmartThings REST API and reduces the amount of code necessary to write a SmartApp app. It supports
18
-
both webhook and AWS Lambda implementations. This is a preview version of the API and will change over time time.
17
+
For a detailed look at the API, check out the [reference documentation](docs/index.md).
19
18
20
-
## Version 2.0 Release
19
+
## Getting Started
21
20
22
-
_ATTENTION! This major release is not completely backwardly compatible with the 1.X version, though for most
23
-
SmartApps the changes required should be relatively minor. The major non-backwardly changes are:_
24
-
*_Methods that return lists now return arrays rather that an object with the properties `items` and `_links`._
25
-
*_Axios is now used rather than request-promise-native for making HTTP calls, resulting in changes to the error
26
-
objects thrown when exceptions occur._
21
+
>**Version 2.0 Release**
22
+
>
23
+
>This major release is not fully backwards compatible with version 1.X, though for most SmartApps the changes required should be relatively minor. The major non-backwards compatible changes include:
24
+
>* Methods that return lists now return arrays instead of objects with the properties `items` and `_links`.
25
+
>* Axios is now used rather than request-promise-native for making HTTP calls, resulting in changes to the error
26
+
objects thrown when exceptions occur.
27
+
>
28
+
>See the [Version 2.0.0 release notes](docs/V2_RELEASE_NOTES.md) for more information.
27
29
28
-
_See the [Version 2.0.0 release notes](docs/V2_RELEASE_NOTES.md) for more information._
30
+
This SDK includes a set of Node.js libraries for building Webhook and AWS Lambda SmartApps, and interacting with the public SmartThings API.
31
+
32
+
Highlights include:
33
+
34
+
- ✅ Javascript API hides details of REST calls and authentication.
35
+
- ✅ Event handler framework dispatches lifecycle events to named event handlers.
36
+
- ✅ Configuration page API simplifies page definition.
SmartApps are custom applications that execute outside of the SmartThings Platform. All of the SmartApp execution will happen on the server or Lambda that you control. The complexity of execution and the number of expected users will need to be examined to understand the hardware or execution requirements your app needs to handle. Your application will respond to lifecycle events sent from SmartThings to perform actions on behalf of your users and will execute any scheduled tasks that you have created in the SmartApp. Creating a SmartApp allows you to control and get status notifications from SmartThings devices using the SmartThings API.
46
+
47
+
#### Hosting Your SmartApp
48
+
49
+
There are two distinct options for hosting your SmartApp: AWS Lambda and Webhook.
50
+
51
+
-**Webhook** SmartApps are any publicly-accessible web server that will receive a POST request payload.
52
+
53
+
-**AWS Lambda** SmartApps are hosted in the Amazon Web Services cloud and are invoked by ARN instead of a public-DNS address.
54
+
55
+
To learn more about SmartApps, including choosing the best hosting solution for your SmartApp, visit the [SmartApp developer documentation](https://developer-preview.smartthings.com/docs/connected-services/smartapp-basics).
29
56
30
57
## Installation
31
58
@@ -35,7 +62,7 @@ npm i @smartthings/smartapp --save
35
62
36
63
## Importing
37
64
38
-
`NodeJS`:
65
+
`Node.js`:
39
66
40
67
```javascript
41
68
constSmartApp=require('@smartthings/smartapp')
@@ -47,24 +74,15 @@ Or `ES2015`+:
47
74
importSmartAppfrom'@smartthings/smartapp'
48
75
```
49
76
50
-
## Highlights
51
-
52
-
-[x] Javascript API hides details of REST calls and authentication.
53
-
-[x] Event handler framework dispatches lifecycle events to named event handlers.
54
-
-[x] Configuration page API simplifies page definition.
The following example automation is the equivalent of a simple Rule (if contact sensor opens/closes, turn lights on/off) which is easily achieved via our [Rules API](https://smartthings.developer.samsung.com/docs/rules/overview.html). It is given here as a brief showcase of the SDK, and not meant to be a good candidate for a SmartApp. Be sure to check if your automation is possible with the Rules API, as it will benefit from speed, stability, and security through future local execution support.
79
+
The example SmartApp below is the equivalent of a simple Rule (if contact sensor opens/closes, turn lights on/off) which is easily achieved via our Rules API. It is given here as a brief showcase of the SDK, and is not meant to be a good candidate for a SmartApp.
64
80
65
-
### Running it as a web service
81
+
>Before hosting your own Automation, be sure to check out [Rules](https://developer-preview.smartthings.com/docs/automations/rules). When all services and Device features involved in a Rule are local, Rules execute locally on a Hub, allowing you to benefit from greater speed, stability, and security than cloud-reliant solutions.
66
82
67
-
To run the app with an HTTP server, like Express.js:
83
+
### Running as a Web Service
84
+
85
+
To run your SmartApp with an HTTP server, such as Express.js:
68
86
69
87
```javascript
70
88
constSmartApp=require('@smartthings/smartapp');
@@ -111,11 +129,11 @@ server.post('/', function (req, res, next) {
111
129
server.listen(PORT, () =>console.log(`Server is up and running on port ${PORT}`));
112
130
```
113
131
114
-
### Running as an AWS Lambda function
132
+
### Running as an AWS Lambda Function
115
133
116
-
To run as a Lambda function instead of an HTTP server, ensure that your main entry file exports `smartapp.handleLambdaCallback(...)`.
134
+
To run your SmartApp as a Lambda function instead of an HTTP server, ensure that your main entry file exports `smartapp.handleLambdaCallback(...)`.
117
135
118
-
> **Note:** This snippet is heavily truncated for brevity.
136
+
Note that this snippet is heavily truncated for brevity:
More detailed examples to use as a starting point can be found with our [smartthings-smartapp-example](https://github.com/topics/smartthings-smartapp-example) Github Topic.
160
+
More detailed examples to use as a starting point can be found in our [smartthings-smartapp-example](https://github.com/topics/smartthings-smartapp-example) Github Topic.
140
161
141
-
###Localization
162
+
## Localization
142
163
143
-
Configuration page strings are specified in a separate `locales/en.json` file, which can be automatically created the first time you run the app. Here's a completed English localization file for the previous example:
164
+
Configuration page strings are specified in a separate `locales/en.json` file, which can be automatically created the first time you run the app. Here's a completed English localization file for the previous simple SmartApp example:
144
165
145
166
```json
146
167
{
@@ -153,25 +174,25 @@ Configuration page strings are specified in a separate `locales/en.json` file, w
153
174
}
154
175
```
155
176
156
-
### Unhandled Promise Rejection Handling
177
+
## Unhandled Promise Rejection Handling
178
+
179
+
By default, instantiation of the SmartApp object registers an `unhandledReject` handler that logs unhandled promise rejections. You can disable this behavior by passing an option to the SmartApp instantiation (e.g. `new SmartApp({logUnhandledRejections: false})`).
157
180
158
-
By default, instantiation of the SmartApp object registers an "unhandledReject" handler
159
-
that logs unhandled promise rejections. If you don't want this behavior you can disable
160
-
it by passing an option to the SmartApp instantiation, e.g. `new SmartApp({logUnhandledRejections: false})`.
161
-
If you want to replace the handler you can do that by calling `unhandledRejectionHandler(promise => {...})`
162
-
on the SmartApp object.
181
+
If desired, you can replace the handler by calling `unhandledRejectionHandler(promise => {...})` on the SmartApp object.
163
182
164
-
###Making API calls outside of an EVENT handler
183
+
## Making API Calls Outside of an `EVENT` Handler
165
184
166
-
By default, the SmartApp SDK will facilitate API calls on behalf of a user within the `EVENT` lifecycle. These user tokens are ephemeral and last *5 minutes*. These access tokens are not able to be refreshed and should _not_ be stored. If you're making out-of-band API calls on behalf of a user's installed app, you will need to use the 24-hour access token that are supplied after `INSTALL` and `UPDATE` lifecycles. This token includes a `refresh_token`, and will be automatically refreshed by the SDK when necessary.
185
+
By default, the SmartApp SDK will facilitate API calls on behalf of a user within the `EVENT` lifecycle. These user tokens are ephemeral and last *5 minutes*. These access tokens are not able to be refreshed and should _not_ be stored.
167
186
168
-
> Be aware that **there is no in-memory context store**, you must use a context store plugin. If you'd like to add a custom context store plugin, please [contribute](CONTRIBUTING.md)!
187
+
If you are making out-of-band API calls on behalf of a user's installed app, you will need to use the 24-hour access token that is supplied after the `INSTALL` and `UPDATE` lifecycles. This token includes a `refresh_token`, and will automatically be refreshed by the SDK when necessary.
169
188
170
-
To get started, let's add a compatible `ContextStore` plugin that will persist these tokens (among other things) to a database.
189
+
>Note that **there is no in-memory context store**; you must use a context store plugin. If you'd like to add a custom context store plugin, please consider [contributing](CONTRIBUTING.md).
171
190
172
-
#### Amazon AWS DynamoDB
191
+
To get started with our context store example below, we will add a compatible `ContextStore` plugin that will persist these tokens (among other things) to a database.
173
192
174
-
Available as a node package on [NPM](https://www.npmjs.com/package/@smartthings/dynamodb-context-store) or [fork on GitHub](https://github.com/SmartThingsCommunity/dynamodb-context-store-nodejs/fork).
193
+
### Amazon AWS DynamoDB
194
+
195
+
>Available as a node package on [NPM](https://www.npmjs.com/package/@smartthings/dynamodb-context-store) or [fork on GitHub](https://github.com/SmartThingsCommunity/dynamodb-context-store-nodejs/fork).
175
196
176
197
If you are hosting your SmartApp as an AWS Lambda, this DynamoDB context store makes perfect sense. This assumes you've already configured the [`aws-sdk`](https://www.npmjs.com/package/aws-sdk) package to interact with your Lambda, so extending your context store to DynamoDB is a drop-in solution.
177
198
@@ -185,21 +206,22 @@ If you are self-hosted and still want to use DynamoDB, you can do that, too:
185
206
186
207
For complete directions on usage, please see this project's GitHub repository. ([SmartThingsCommunity/dynamodb-context-store-nodejs](https://github.com/SmartThingsCommunity/dynamodb-context-store-nodejs))
187
208
188
-
#### Firebase Cloud Firestore
209
+
### Firebase Cloud Firestore
210
+
211
+
>Available as a node package on [NPM](https://www.npmjs.com/package/@smartthings/firestore-context-store) or [fork on GitHub](https://github.com/SmartThingsCommunity/firestore-context-store-nodejs/fork).
189
212
190
-
Available as a node package on [NPM](https://www.npmjs.com/package/@smartthings/firestore-context-store) or [fork on GitHub](https://github.com/SmartThingsCommunity/firestore-context-store-nodejs/fork). Usage is generally the same as DynamoDB:
213
+
Usage is generally the same as DynamoDB:
191
214
192
215
1. Generate a Firebase service account. You will receive a JSON file with the credentials.
193
216
1. Load your Google Services JSON
194
217
1. Create the context store
195
218
196
-
See the full usage guide on the project's GitHub repository. ([SmartThingsCommunity/firestore-context-store-nodejs](https://github.com/SmartThingsCommunity/firestore-context-store-nodejs#usage))
219
+
See the full usage guide on the [project's GitHub repository](https://github.com/SmartThingsCommunity/firestore-context-store-nodejs#usage).
and callbacks. It is instantiated and configured with handlers for appropriate and invoked
6
-
in response to either web-server HTTP requests or AWS Lambda function calls.
3
+
The [SmartApp](classes/_smart_app_d_.smartapp.md) class handles all SmartApp [lifecycle events](https://developer-preview.smartthings.com/docs/connected-services/lifecycles) and callbacks. It is instantiated and configured with handlers where appropriate and is invoked in response to either web server HTTP requests, or in response to AWS Lambda function calls.
0 commit comments