Table of Contents
alexa-smart-home-app
A Node module to simplify the development of Alexa skills (applications.) This module is clone for alexa-app then redesign for alexa smart home skill
Introduction
This module parses HTTP JSON requests from the Alexa platform and builds the JSON response that consumed by an Alexa-compatible device, such as the Echo.
It provides a DSL for defining event.
Features
Examples
Express
var express = ;var alexa = ;var express_app = ; var app = "sample"; // setup the alexa app and attach it to express before anything elseapp; // now POST calls to /sample in express will be handled by the app.request() function// GET calls will not be handled // from here on, you can setup any other express routes or middleware as normal
The express function accepts the following parameters.
expressApp
the express app instance to attach torouter
the express router instance to attach toendpoint
the path to attach the express app or router to (e.g., passing'mine'
attaches to/mine
)preRequest
function to execute before every POSTpostRequest
function to execute after every POST
Either expressApp
or router
is required.
A full express example is available here.
API
Skills define handlers for Discovery, CameraStreamController, and SceneController, just like normal Alexa development. The alexa-smart-home-app module provides a layer around this functionality that simplifies the interaction. Each handler gets passed a request and response object, which are custom for this module.
request
// return the namespace of request receivedString request // check if the namespace is discoverBoolean request // check if the namespace is camera stream controllerBoolean request // check if the namespace is sceneControllerBoolean request // return the header objectDialog request // check if you can read headerBoolean request // return the payload objectDialog request // check if you can read payloadBoolean request // return the endpoint objectDialog request // check if you can read endpointBoolean request // the raw request JSON objectrequestdata
response
The response JSON object is automatically built for you. All you need to do is tell it what you want to output.
// alexa-discovery @see https://developer.amazon.com/zh/docs/device-apis/alexa-discovery.html// skill supports discoveryresponse // alexa-camerastreamcontroller @see https://developer.amazon.com/zh/docs/device-apis/alexa-camerastreamcontroller.html// skill supports camerastreamcontrollerresponse // alexa-camerastreamcontroller @see https://developer.amazon.com/zh/docs/device-apis/alexa-camerastreamcontroller.html// skill supports camerastreamcontrollerresponse // alexa-errorresponse @see https://developer.amazon.com/zh/docs/device-apis/alexa-errorresponse.html// skill supports error responseresponse // send the response to the Alexa device (success) immediately// this returns a promise that you must return to continue the// promise chain. Calling this is optional in most cases as it// will be called automatically when the handler promise chain// resolves, but you can call it and return its value in the// chain to send the response immediately. You can also use it// to send a response from `post` after failure.async response // trigger a response failure// the internal promise containing the response will be rejected, and should be handled by the calling environment// instead of the Alexa response being returned, the failure message will be passed// similar to `response.send()`, you must return the value returned from this call to continue the promise chain// this is equivalent to calling `throw message` in handlers// *NOTE:* this does not generate a response compatible with Alexa, so when calling it explicitly you may want to handle the response with `.error` or `.post`async response
payload
// check if you can read payloadBoolean request // get the payload objectvar session = request // return the value of a session variableString payload // payload details, as passed by Amazon in the requestpayloaddetails = ...
endpoint
// check if you can read endpointBoolean request // get the payload objectvar session = request // return the value of a endpoint variableString endpoint // return the endpoint's scopeString endpointscope // return the endpoint's endpointIdString endpointendpointId // return the endpoint's cookieString endpointcookie // endpoint details, as passed by Amazon in the requestendpointdetails = ...
Request Handlers
Your app can define a single handler for the discovery
event and the cameraStreamController
event, and sceneController
event.
Discovery
alexaApp;
CameraStreamController
alexaApp;
Execute Code On Every Request
In addition to specific event handlers, you can define functions that will run on every request.
pre()
Executed before any event handlers. This is useful to setup new payload, validate the token
, or do any other kind of validations.
You can perform asynchronous functionality in pre
by returning a Promise.
app { if request && requesttoken != "User Token" // fail ungracefully throw "Invalid token"; }; // Asynchronousapp { return db;};
Note that the post()
method still gets called, even if the pre()
function calls send()
or fail()
. The post method can always override anything done before it.
post()
The last thing executed for every request. It is even called if there is an exception or if a response has already been sent. The post()
function can change anything about the response. It can even turn a return response.fail()
into a return respond.send()
with entirely new content. If post()
is called after an exception is thrown, the exception itself will be the 4th argument.
You can perform asynchronous functionality in pre
by returning a Promise similar to pre
or any of the handlers.
app { if exception // always turn an exception into a successful response return response; };
Customizing Default Error Messages
appmessagesINVALID_REQUEST_NAMESPACE = "Sorry, the application didn't know what to do with that namespace";
See the code for default messages you can override.
License
Copyright (c) 2018 Clarence Lin
MIT License, see LICENSE for details.