Suggested change to docs regarding asynchronous calls in intent handlers

[roschler]

I used these docs to develop my intent handler that requires an asynchronous call to an external server:

https://www.npmjs.com/package/alexa-app#asynchronous-handlers-example

The docs give this code sample as an example of an async call inside an alexa-app intent handler:

app.intent("checkStatus", function(request, response) {
  // `getAsync` returns a Promise in this example. When
  // returning a Promise, the response is sent after it
  // resolves. If rejected, it is treated as an error.
  return http.getAsync("http://server.com/status.html").then(function (rc) {
    response.say(rc.statusText);
  });
});

I think the docs need a fully fleshed out Promise example. In order to get the body of my Promise working I had to make an explicit call to resolve(response) when I was done. Without that call, alexa-app returned an ERROR to Alexa with an empty payload and the end session flag set to true.

Perhaps something like this?:

/**
 * Sample promise that makes an async call that can be called inside an alexa-app intent handler.
 *
 * @param {Object} request - An alexa-app request object.
 * @param {Object} reponse - An alexa-app response object.
 * @return {Promise}
 */
function asyncCallInsideIntent_promise(request, response)
{
	// Build a new promise object that calls the dialog server and process the result before
	//  returning our response to Alexa
	return new Promise(
		function(resolve, reject)
		{
			try
			{
				// Validate input parameters.
				if (request == null)
					throw new Error('The request object is unassigned.');
	
				if (response == null)
					throw new Error('The response object is unassigned.');
					
				// Make the async call.  Do not make any explicit return calls.  See the
				//  comment above the resolve() call in the "then" block below.  The
				//  fake async call below simply returns some text to say to Alexa.
				doAsyncCall()
				.then(function(newText)
				{
					// Resolve with the response or the intent will
					//  end up returning an empty JSON payload to Alexa with the
					//  end-session flag set to TRUE.
					resolve(response);
				})
				.catch(function(err)
				{
					// Convert the error into a promise rejection
					reject(err);
				});
			}
			catch (err)
			{
				// Convert the error into a promise rejection
				reject(err);
			}
		});
}

If you want me to fork the repo and make a pull request I'm happy to do that, but I'd like to get your comments first before doing that.

[dblock]

Please make a PR, we can look at the actual change.

[roschler]

@dblock Just did:

roschler#1

[gnickm]

+1 on this doc change. I spent several hours struggling with the promise resolve until I read the above. Thx @roschler !

[dblock]

Thanks! Please make a PR into the root project (aka here) @roschler.