Release of Version 1.6.0

aws-greengrass-core-sdk/index.js

@@ -1,7 +1,33 @@
 /*
- * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  */
-exports.GreengrassInterfaceVersion = '1.4';
-exports.Lambda = require('./lambda');
-exports.IotData = require('./iotdata');
-exports.SecretsManager = require('./secretsmanager');
+exports.GreengrassInterfaceVersion = '1.5';
+
+/**
+ * @namespace aws-greengrass-core-sdk
+ */
+
+const fail = (name, error) => {
+    console.error(`Unable to load aws-greengrass-core-sdk.${name} due to: `, error);
+};
+
+try {
+    exports.Lambda = require('./lambda');
+} catch (e) {
+    fail('Lambda', e);
+}
+try {
+    exports.IotData = require('./iotdata');
+} catch (e) {
+    fail('IotData', e);
+}
+try {
+    exports.SecretsManager = require('./secretsmanager');
+} catch (e) {
+    fail('SecretsManager', e);
+}
+try {
+    exports.StreamManager = require('./stream-manager');
+} catch (e) {
+    fail('StreamManager', e);
+}

aws-greengrass-core-sdk/iotdata.js

@@ -2,28 +2,66 @@
  * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  */
 
-const Buffer = require('buffer').Buffer;
+const { Buffer } = require('buffer');
 
+const GreengrassCommon = require('aws-greengrass-common-js');
 const Lambda = require('./lambda');
 const Util = require('./util');
-const GreengrassCommon = require('aws-greengrass-common-js');
-
-const envVars = GreengrassCommon.envVars;
-const MY_FUNCTION_ARN = envVars.MY_FUNCTION_ARN;
-const SHADOW_FUNCTION_ARN = envVars.SHADOW_FUNCTION_ARN;
-const ROUTER_FUNCTION_ARN = envVars.ROUTER_FUNCTION_ARN;
 
+const { envVars } = GreengrassCommon;
+const { MY_FUNCTION_ARN } = envVars;
+const { SHADOW_FUNCTION_ARN } = envVars;
+const { ROUTER_FUNCTION_ARN } = envVars;
+
+/**
+ * Constructs a service interface object. Each API operation is exposed as a function on service.
+ *
+ * @class
+ * @memberOf aws-greengrass-core-sdk
+ *
+ * @example <caption>Sending a Request Using IotData</caption>
+ * var iotdata = new GG.IotData();
+ * iotdata.getThingShadow(params, function (err, data) {
+ *   if (err) console.log(err, err.stack); // an error occurred
+ *   else     console.log(data);           // successful response
+ * });
+ */
 class IotData {
+    /**
+     * Constructs a service object. This object has one method for each API operation.
+     *
+     * @example <caption>Constructing a IotData object</caption>
+     * var iotdata = new GG.IotData();
+     */
     constructor() {
         this.lambda = new Lambda();
     }
 
+    /**
+     * Called when a response from the service is returned.
+     *
+     * @callback iotDataCallback
+     * @param err {Error} The error object returned from the request. Set to <tt>null</tt> if the request is successful.
+     * @param data {Object} The de-serialized data returned from the request. Set to <tt>null</tt> if a request error occurs.
+     * @param data.payload {Buffer|TypedArray|Blob|String} The state information in JSON format
+     */
+    /**
+     * Gets the thing shadow for the specified thing.
+     *
+     * @param params {Object}
+     * @param params.thingName {String} The name of the thing.
+     * @param callback {iotDataCallback} The callback.
+     *
+     * @example <caption>Calling the getThingShadow operation</caption>
+     * var params = {
+     *   thingName: 'STRING_VALUE' // required
+     * };
+     * iotdata.getThingShadow(params, function(err, data) {
+     *   if (err) console.log(err, err.stack); // an error occurred
+     *   else     console.log(data);           // successful response
+     * });
+     */
     getThingShadow(params, callback) {
-        /*
-         * Call shadow lambda to obtain current shadow state.
-         * @param {object} params object contains parameters for the call
-         * REQUIRED: 'thingName' the name of the thing
-         */
         const thingName = Util.getParameter(params, 'thingName');
         if (thingName === undefined) {
             callback(new Error('"thingName" is a required parameter.'), null);
@@ -34,13 +72,25 @@ class IotData {
         this._shadowOperation('get', thingName, payload, callback);
     }
 
+    /**
+     * Updates the thing shadow for the specified thing.
+     *
+     * @param params {Object}
+     * @param params.thingName {String} The name of the thing.
+     * @param params.payload {String} The state information as a JSON string.
+     * @param callback {iotDataCallback} The callback.
+     *
+     * @example <caption>Calling the updateThingShadow operation</caption>
+     * var params = {
+     *   payload: 'Proper JSON data', // required
+     *   thingName: 'STRING_VALUE' // required
+     * };
+     * iotdata.updateThingShadow(params, function(err, data) {
+     *   if (err) console.log(err, err.stack); // an error occurred
+     *   else     console.log(data);           // successful response
+     * });
+     */
     updateThingShadow(params, callback) {
-        /*
-         * Call shadow lambda to update current shadow state.
-         * @param {object} params object contains parameters for the call
-         * REQUIRED: 'thingName' the name of the thing
-         *           'payload'   the state information in JSON format
-         */
         const thingName = Util.getParameter(params, 'thingName');
         if (thingName === undefined) {
             callback(new Error('"thingName" is a required parameter.'), null);
@@ -56,12 +106,14 @@ class IotData {
         this._shadowOperation('update', thingName, payload, callback);
     }
 
+    /**
+     * Call shadow lambda to delete the shadow state.
+     *
+     * @param params {Object}
+     * @param params.thingName {String} The name of the thing whose shadow should be deleted.
+     * @param callback {iotDataCallback} The callback.
+     */
     deleteThingShadow(params, callback) {
-        /*
-         * Call shadow lambda to delete the shadow state.
-         * @param {object} params object contains parameters for the call
-         * REQUIRED: 'thingName' the name of the thing
-         */
         const thingName = Util.getParameter(params, 'thingName');
         if (thingName === undefined) {
             callback(new Error('"thingName" is a required parameter.'), null);
@@ -72,14 +124,27 @@ class IotData {
         this._shadowOperation('delete', thingName, payload, callback);
     }
 
+    /**
+     * Publishes a message within Greengrass.
+     *
+     * @param params {Object}
+     * @param params.topic {String} The name of the MQTT topic.
+     * @param params.payload {Buffer|TypedArray|Blob|String} The payload to be sent.
+     * @param params.queueFullPolicy {'AllOrError'|'BestEffort'} Specify whether to enforce message delivery to all destinations. Options are 'AllOrError' and 'BestEffort'. Defaults to 'BestEffort' when omitted.
+     * @param callback {iotDataCallback} The callback.
+     *
+     * @example <caption>Calling the publish operation</caption>
+     * var params = {
+     *   topic: 'STRING_VALUE', // required
+     *   payload: new Buffer('...') || 'STRING_VALUE',
+     *   queueFullPolicy: 'AllOrError' || 'BestEffort'
+     * };
+     * iotdata.publish(params, function(err, data) {
+     *   if (err) console.log(err, err.stack); // an error occurred
+     *   else     console.log(data);           // successful response
+     * });
+     */
     publish(params, callback) {
-        /*
-         * Publishes state information.
-         * @param {object} params object contains parameters for the call
-         * REQUIRED: 'topic'   the topic name to be published
-         *           'payload' the state information in JSON format
-         * OPTIONAL: 'queueFullPolicy' the policy for GGC to take when its internal queue is full
-         */
         const topic = Util.getParameter(params, 'topic');
         if (topic === undefined) {
             callback(new Error('"topic" is a required parameter'), null);
@@ -131,9 +196,9 @@ class IotData {
 
         this.lambda.invoke(invokeParams, (err, data) => {
             if (err) {
-                callback(err, null);            // an error occurred
+                callback(err, null); // an error occurred
             } else {
-                callback(null, data);           // successful response
+                callback(null, data); // successful response
             }
         });
     }

aws-greengrass-core-sdk/lambda.js

@@ -2,20 +2,94 @@
  * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  */
 
-const Util = require('./util');
 const IPCClient = require('aws-greengrass-ipc-sdk-js');
 const GreengrassCommon = require('aws-greengrass-common-js');
-const logging = require('aws-greengrass-common-js').logging;
+const { logging } = require('aws-greengrass-common-js');
+const Util = require('./util');
 
-const AUTH_TOKEN = GreengrassCommon.envVars.AUTH_TOKEN;
+const { AUTH_TOKEN } = GreengrassCommon.envVars;
 
 const logger = new logging.LocalWatchLogger();
 
+/**
+ * Constructs a service interface object. Each API operation is exposed as a function on service.
+ * @class
+ * @memberOf aws-greengrass-core-sdk
+ */
 class Lambda {
+    /**
+     * Constructs a service object. This object has one method for each API operation.
+     *
+     * @example <caption>Constructing a Lambda object</caption>
+     * var lambda = new GG.Lambda();
+     */
     constructor() {
         this.ipc = new IPCClient(AUTH_TOKEN);
     }
 
+    /**
+     * Called when a response from the service is returned.
+     *
+     * @callback lambdaCallback
+     * @param err {Error} The error object returned from the request. Set to <tt>null</tt> if the request is successful.
+     * @param data {Object} The de-serialized data returned from the request. Set to <tt>null</tt> if a request error occurs.
+     * @param data.StatusCode {Integer} The HTTP status code will be in the 200 range for successful request. For the <tt>RequestResponse</tt> invocation type this status code will be 200.
+     * For the <tt>Event</tt> invocation type this status code will be 202.
+     * @param data.FunctionError {String} Indicates whether an error occurred while executing the Lambda function. If an error occurred this field will have one of two values; <tt>Handled</tt> or <tt>Unhandled</tt>.
+     * <tt>Handled</tt> errors are errors that are reported by the function while the Unhandled errors are those detected and reported by AWS Lambda.
+     * <tt>Unhandled</tt> errors include out of memory errors and function timeouts. For information about how to report an <tt>Handled</tt> error,
+     * see <a href="http://docs.aws.amazon.com/lambda/latest/dg/programming-model.html">Programming Model</a>.
+     * @param data.Payload {Buffer|TypedArray|Blob|String} It is the result returned by the Lambda function. This is present only if the invocation type is <tt>RequestResponse</tt>.
+     * <br/>In the event of a function error this field contains a message describing the error. For the <tt>Handled</tt> errors the Lambda function will report this message. For <tt>Unhandled</tt> errors AWS Lambda reports the message.
+     */
+
+    /**
+     * Invokes a specific Lambda function.<br/>
+     * In Greengrass, version of the Lambda which you would like to invoke needs to be provided.
+     *
+     * @param params {Object}
+     * @param params.FunctionName {String} The Lambda function name. You can specify Amazon Resource Name (ARN) of the function (for example, <tt>arn:aws:lambda:us-west-2:account-id:function:ThumbNail</tt>).
+     * @param params.InvocationType {String?} By default, the <tt>Invoke</tt> API assumes <tt>RequestResponse</tt> invocation type.
+     * You can optionally request asynchronous execution by specifying <tt>Event</tt> as the <tt>InvocationType</tt>. Possible values include:
+     * <ul><li>"Event"</li><li>"RequestResponse"</li></ul>
+     * @param params.ClientContext {String?} Using the <tt>ClientContext</tt> you can pass client-specific information to the Lambda function you are invoking.
+     * You can then process the client information in your Lambda function as you choose through the context variable.
+     * For an example of a <tt>ClientContext</tt> JSON, see the main page or an example folder for an example.
+     * <br/>The <tt>ClientContext</tt> JSON must be base64-encoded.
+     * @param params.Payload {Buffer|TypedArray|Blob|String} Payload that you want to provide to your Lambda function as input.
+     * @param params.Qualifier {String?} You can use this optional parameter to specify a Lambda function version if it was not included in the FunctionName field.
+     * If you specify a function version, the API uses the qualified function ARN to invoke a specific Lambda function.
+     * <br/>If you don't provide this parameter, then the API uses the FunctionName field only. If it does not have a version number of the target lambda, the call will fail.
+     * @param callback {lambdaCallback} The callback.
+     *
+     * @example <caption>To invoke a Lambda function</caption>
+     * //This operation invokes a Lambda function
+     *
+     * var params = {
+     *   ClientContext: "MyApp",
+     *   FunctionName: "MyFunction",
+     *   InvocationType: "Event",
+     *   Payload: <json | binary>,
+     *   Qualifier: "1"
+     * };
+     * lambda.invoke(params, function(err, data) {
+     *   if (err) console.log(err, err.stack); // an error occurred
+     *   else     console.log(data);           // successful response
+     * });
+     *
+     * @example <caption>Calling the invoke operation</caption>
+     * var params = {
+     *   FunctionName: 'STRING_VALUE', // required
+     *   ClientContext: 'STRING_VALUE',
+     *   InvocationType: Event | RequestResponse,
+     *   Payload: <json | binary>,
+     *   Qualifier: 'STRING_VALUE'
+     * };
+     * lambda.invoke(params, function(err, data) {
+     *   if (err) console.log(err, err.stack); // an error occurred
+     *   else     console.log(data);           // successful response
+     * });
+     */
     invoke(params, callback) {
         const functionName = Util.getParameter(params, 'FunctionName');
         if (functionName === undefined) {
@@ -67,11 +141,12 @@ class Lambda {
             // GGC v1.9.0 or newer
             functionArn = GreengrassCommon.buildFunctionArn(
                 arnFields.unqualifiedArn,
-                finalQualifier);
+                finalQualifier,
+            );
         } else {
             // older version of GGC
-            throw new Error('Function buildFunctionArn not found. buildFunctionArn is introduced in GGC v1.9.0. ' +
-                    'Please check your GGC version.');
+            throw new Error('Function buildFunctionArn not found. buildFunctionArn is introduced in GGC v1.9.0. '
+                    + 'Please check your GGC version.');
         }
 
         // verify client context is base64 encoded

aws-greengrass-core-sdk/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "aws-greengrass-core-sdk",
+  "version": "1.6.0",
+  "main": "index.js",
+  "dependencies": {
+    "cbor": "5.0.1"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Amazon Web Services",
+    "url": "https://aws.amazon.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/aws/aws-greengrass-core-sdk-js"
+  }
+}