azure-iot-common - npm Package Compare versions

Comparing version 1.1.11 to 1.1.12

common.d.ts

@@ -14,2 +14,4 @@ // Copyright (c) Microsoft. All rights reserved.
 export { SharedAccessSignature } from './lib/shared_access_signature';
+export { RetryOperation } from './lib/retry_operation';
+export { RetryPolicy, NoRetry, ExponentialBackOffWithJitter } from './lib/retry_policy';
 
@@ -16,0 +18,0 @@ // Typescript only, used by other modules in azure-iot-sdk

common.js

@@ -8,3 +8,3 @@ // Copyright (c) Microsoft. All rights reserved.
  * The `azure-iot-common` module contains code common to the Azure IoT Hub Device and Service SDKs.
- * 
+ *
  * @module azure-iot-common
@@ -21,3 +21,7 @@ */
   Message: require('./lib/message.js').Message,
-  SharedAccessSignature: require('./lib/shared_access_signature.js').SharedAccessSignature
+  SharedAccessSignature: require('./lib/shared_access_signature.js').SharedAccessSignature,
+  RetryOperation: require('./lib/retry_operation.js').RetryOperation,
+  RetryPolicy: require('./lib/retry_policy.js').RetryPolicy,
+  NoRetry: require('./lib/retry_policy.js').NoRetry,
+  ExponentialBackOffWithJitter: require('./lib/retry_policy.js').ExponentialBackOffWithJitter,
 };

lib/connection_string.d.ts

 /*! Copyright (c) Microsoft. All rights reserved.
  *! Licensed under the MIT license. See LICENSE file in the project root for full license information.
  */
-export interface ConnectionString {
+/**
+ * Describes the parameters that enable a device or cloud application to connect to an Azure IoT hub.
+ */
+export declare class ConnectionString {
+    /**
+     * Hostname of the Azure IoT hub.
+     * @memberof {azure-iot-common.ConnectionString}
+     */
     HostName?: string;
+    /**
+     * Unique device identifier as it exists in the device identity registry. This is only used for device connection strings.
+     * @memberof {azure-iot-common.ConnectionString}
+     */
     DeviceId?: string;
+    /**
+     * Symmetric key used to create shared access signature tokens that are in turn used to authenticate the connection. Associated either with a specific device or a specific service policy.
+     * @memberof {azure-iot-common.ConnectionString}
+     */
     SharedAccessKey?: string;
+    /**
+     * Name of the access policy used to connect to the Azure IoT hub. used only in the case of the service SDK, unused with the Device SDK (which uses `DeviceId` instead).
+     * @memberof {azure-iot-common.ConnectionString}
+     */
     SharedAccessKeyName?: string;
+    /**
+     * This was used in public preview when MQTT support required the use of a protocol gateway.
+     * Now that MQTT is supported natively in Azure IoT Hub, this parameter is ignored and kept only for compatibility purposes.
+     * @memberof {azure-iot-common.ConnectionString}
+     * @deprecated
+     */
     GatewayHostName?: string;
+    /**
+     * This property exists only if a device uses x509 certificates for authentication and if it exists, will be set to True.
+     * @memberof {azure-iot-common.ConnectionString}
+     */
     x509?: string;
+    /**
+     * Parses a string and returns the corresponding {@link azure-iot-common.ConnectionString} object.
+     * @param {string}   source          string from which the connection string will be extracted
+     * @param {string[]} requiredFields  array of strings listing the fields that are expected to be found.
+     */
+    static parse(source: string, requiredFields?: string[]): ConnectionString;
 }
-export declare namespace ConnectionString {
-    function parse(source: string, requiredFields?: string[]): ConnectionString;
-}

lib/connection_string.js

@@ -7,5 +7,14 @@ /*! Copyright (c) Microsoft. All rights reserved.
 var errors_1 = require('./errors');
-var ConnectionString;
-(function (ConnectionString) {
-    function parse(source, requiredFields) {
+/**
+ * Describes the parameters that enable a device or cloud application to connect to an Azure IoT hub.
+ */
+var ConnectionString = (function () {
+    function ConnectionString() {
+    }
+    /**
+     * Parses a string and returns the corresponding {@link azure-iot-common.ConnectionString} object.
+     * @param {string}   source          string from which the connection string will be extracted
+     * @param {string[]} requiredFields  array of strings listing the fields that are expected to be found.
+     */
+    ConnectionString.parse = function (source, requiredFields) {
         /*Codes_SRS_NODE_CONNSTR_05_001: [The input argument source shall be converted to string if necessary.]*/
@@ -26,5 +35,6 @@ /*Codes_SRS_NODE_CONNSTR_05_002: [The parse method shall create a new instance of ConnectionString.]*/
         return connectionString;
-    }
-    ConnectionString.parse = parse;
-})(ConnectionString = exports.ConnectionString || (exports.ConnectionString = {}));
+    };
+    return ConnectionString;
+}());
+exports.ConnectionString = ConnectionString;
 //# sourceMappingURL=connection_string.js.map

lib/dictionary.d.ts

@@ -6,2 +6,5 @@ /*! Copyright (c) Microsoft. All rights reserved.
 export declare namespace createDictionary {
+    /**
+     * @private
+     */
     interface Dictionary<T> {
@@ -8,0 +11,0 @@ [key: string]: T;

lib/errors.d.ts

@@ -6,4 +6,3 @@ /// <reference types="node" />
 /**
- * @class       module:azure-iot-common.ArgumentError
- * @classdesc   Error thrown when an argument is invalid.
+ * Error thrown when an argument is invalid.
  *
@@ -16,4 +15,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.ArgumentOutOfRangeError
- * @classdesc   Error thrown when an argument has a value that is out of the admissible range.
+ * Error thrown when an argument has a value that is out of the admissible range.
  *
@@ -26,4 +24,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceMaximumQueueDepthExceededError
- * @classdesc   Error thrown when the message queue for a device is full.
+ * Error thrown when the message queue for a device is full.
  *
@@ -36,4 +33,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceNotFoundError
- * @classdesc   Error thrown when a device cannot be found in the IoT Hub instance registry.
+ * Error thrown when a device cannot be found in the IoT Hub instance registry.
  *
@@ -46,4 +42,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.FormatError
- * @classdesc   Error thrown when a string that is supposed to have a specific formatting is not formatted properly.
+ * Error thrown when a string that is supposed to have a specific formatting is not formatted properly.
  *
@@ -56,4 +51,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.UnauthorizedError
- * @classdesc   Error thrown when the connection parameters are wrong and the server refused the connection.
+ * Error thrown when the connection parameters are wrong and the server refused the connection.
  *
@@ -65,20 +59,56 @@ * @augments {Error}
 }
+/**
+ * Error thrown when a feature is not implemented yet but the placeholder is present.
+ *
+ * @augments {Error}
+ */
 export declare class NotImplementedError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when the device is disconnected and the operation cannot be completed.
+ *
+ * @augments {Error}
+ */
 export declare class NotConnectedError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown the the Azure IoT hub quota has been exceeded. Quotas are reset periodically, this operation will have to wait until then.
+ * To learn more about quotas, see {@link https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling|Azure IoT Hub quotas and throttling}
+ *
+ * @augments {Error}
+ */
 export declare class IotHubQuotaExceededError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when the message sent is too large: the maximum size is 256Kb.
+ *
+ * @augments {Error}
+ */
 export declare class MessageTooLargeError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when an internal server error occured. You may have found a bug?
+ *
+ * @augments {Error}
+ */
 export declare class InternalServerError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when the service is unavailable. The operation should be retried.
+ *
+ * @augments {Error}
+ */
 export declare class ServiceUnavailableError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when the Azure IoT hub was not found.
+ *
+ * @augments {Error}
+ */
 export declare class IotHubNotFoundError extends Error {
@@ -88,4 +118,3 @@ constructor(message?: string);
 /**
- * @class       module:azure-iot-common.IoTHubSuspendedError
- * @classdesc   Error thrown when IoT Hub has been suspended.
+ * Error thrown when IoT Hub has been suspended.
  *
@@ -97,5 +126,15 @@ * @augments {Error}
 }
+/**
+ * Error thrown when the job with the specified identifier was not found.
+ *
+ * @augments {Error}
+ */
 export declare class JobNotFoundError extends Error {
     constructor(message?: string);
 }
+/**
+ * Error thrown when the maximum number of devices on a specific hub has been reached.
+ *
+ * @augments {Error}
+ */
 export declare class TooManyDevicesError extends Error {
@@ -105,4 +144,4 @@ constructor(message?: string);
 /**
- * @class       module:azure-iot-common.ThrottlingError
- * @classdesc   Error thrown when IoT Hub is throttled due to excessive activity.
+ * Error thrown when IoT Hub is throttled due to excessive activity.
+ * To learn more about quotas, see {@link https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling|Azure IoT Hub quotas and throttling}
  *
@@ -115,4 +154,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceAlreadyExistsError
- * @classdesc   Error thrown when the device id used for device creation already exists in the Device Identity Registry.
+ * Error thrown when the device id used for device creation already exists in the Device Identity Registry.
  *
@@ -125,4 +163,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceMessageLockLostError
- * @classdesc   Error thrown when settling a message fails because the lock token associated with the message is lost.
+ * Error thrown when settling a message fails because the lock token associated with the message is lost.
  *
@@ -135,4 +172,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.InvalidEtagError
- * @classdesc   Error thrown when the eTag specified is incorrectly formatted or out of date.
+ * Error thrown when the eTag specified is incorrectly formatted or out of date.
  *
@@ -145,4 +181,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.InvalidOperationError
- * @classdesc   Error thrown when an operation is attempted but is not allowed.
+ * Error thrown when an operation is attempted but is not allowed.
  *
@@ -155,4 +190,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.PreconditionFailedError
- * @classdesc   Error thrown when a condition that should have been met in order to execute an operation was not.
+ * Error thrown when a condition that should have been met in order to execute an operation was not.
  *
@@ -165,4 +199,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.TimeoutError
- * @classdesc   Error thrown when a timeout occurs
+ * Error thrown when a timeout occurs
  *
@@ -175,4 +208,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.BadDeviceResponseError
- * @classdesc   Error thrown when a device sends a bad response to a device method call.
+ * Error thrown when a device sends a bad response to a device method call.
  *
@@ -185,4 +217,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.GatewayTimeoutError
- * @classdesc   Error thrown when the IoT Hub instance doesn't process the device method call in time.
+ * Error thrown when the IoT Hub instance doesn't process the device method call in time.
  *
@@ -195,4 +226,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceTimeoutError
- * @classdesc   Error thrown when the device doesn't process the method call in time.
+ * Error thrown when the device doesn't process the method call in time.
  *
@@ -199,0 +229,0 @@ * @augments {Error}

lib/errors.js

@@ -11,4 +11,3 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class       module:azure-iot-common.ArgumentError
- * @classdesc   Error thrown when an argument is invalid.
+ * Error thrown when an argument is invalid.
  *
@@ -29,4 +28,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.ArgumentOutOfRangeError
- * @classdesc   Error thrown when an argument has a value that is out of the admissible range.
+ * Error thrown when an argument has a value that is out of the admissible range.
  *
@@ -47,4 +45,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceMaximumQueueDepthExceededError
- * @classdesc   Error thrown when the message queue for a device is full.
+ * Error thrown when the message queue for a device is full.
  *
@@ -65,4 +62,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceNotFoundError
- * @classdesc   Error thrown when a device cannot be found in the IoT Hub instance registry.
+ * Error thrown when a device cannot be found in the IoT Hub instance registry.
  *
@@ -83,4 +79,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.FormatError
- * @classdesc   Error thrown when a string that is supposed to have a specific formatting is not formatted properly.
+ * Error thrown when a string that is supposed to have a specific formatting is not formatted properly.
  *
@@ -101,4 +96,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.UnauthorizedError
- * @classdesc   Error thrown when the connection parameters are wrong and the server refused the connection.
+ * Error thrown when the connection parameters are wrong and the server refused the connection.
  *
@@ -118,2 +112,7 @@ * @augments {Error}
 exports.UnauthorizedError = UnauthorizedError;
+/**
+ * Error thrown when a feature is not implemented yet but the placeholder is present.
+ *
+ * @augments {Error}
+ */
 var NotImplementedError = (function (_super) {
@@ -130,2 +129,7 @@ __extends(NotImplementedError, _super);
 exports.NotImplementedError = NotImplementedError;
+/**
+ * Error thrown when the device is disconnected and the operation cannot be completed.
+ *
+ * @augments {Error}
+ */
 var NotConnectedError = (function (_super) {
@@ -142,2 +146,8 @@ __extends(NotConnectedError, _super);
 exports.NotConnectedError = NotConnectedError;
+/**
+ * Error thrown the the Azure IoT hub quota has been exceeded. Quotas are reset periodically, this operation will have to wait until then.
+ * To learn more about quotas, see {@link https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling|Azure IoT Hub quotas and throttling}
+ *
+ * @augments {Error}
+ */
 var IotHubQuotaExceededError = (function (_super) {
@@ -154,2 +164,7 @@ __extends(IotHubQuotaExceededError, _super);
 exports.IotHubQuotaExceededError = IotHubQuotaExceededError;
+/**
+ * Error thrown when the message sent is too large: the maximum size is 256Kb.
+ *
+ * @augments {Error}
+ */
 var MessageTooLargeError = (function (_super) {
@@ -166,2 +181,7 @@ __extends(MessageTooLargeError, _super);
 exports.MessageTooLargeError = MessageTooLargeError;
+/**
+ * Error thrown when an internal server error occured. You may have found a bug?
+ *
+ * @augments {Error}
+ */
 var InternalServerError = (function (_super) {
@@ -178,2 +198,7 @@ __extends(InternalServerError, _super);
 exports.InternalServerError = InternalServerError;
+/**
+ * Error thrown when the service is unavailable. The operation should be retried.
+ *
+ * @augments {Error}
+ */
 var ServiceUnavailableError = (function (_super) {
@@ -190,2 +215,7 @@ __extends(ServiceUnavailableError, _super);
 exports.ServiceUnavailableError = ServiceUnavailableError;
+/**
+ * Error thrown when the Azure IoT hub was not found.
+ *
+ * @augments {Error}
+ */
 var IotHubNotFoundError = (function (_super) {
@@ -203,4 +233,3 @@ __extends(IotHubNotFoundError, _super);
 /**
- * @class       module:azure-iot-common.IoTHubSuspendedError
- * @classdesc   Error thrown when IoT Hub has been suspended.
+ * Error thrown when IoT Hub has been suspended.
  *
@@ -220,2 +249,7 @@ * @augments {Error}
 exports.IoTHubSuspendedError = IoTHubSuspendedError;
+/**
+ * Error thrown when the job with the specified identifier was not found.
+ *
+ * @augments {Error}
+ */
 var JobNotFoundError = (function (_super) {
@@ -232,2 +266,7 @@ __extends(JobNotFoundError, _super);
 exports.JobNotFoundError = JobNotFoundError;
+/**
+ * Error thrown when the maximum number of devices on a specific hub has been reached.
+ *
+ * @augments {Error}
+ */
 var TooManyDevicesError = (function (_super) {
@@ -245,4 +284,4 @@ __extends(TooManyDevicesError, _super);
 /**
- * @class       module:azure-iot-common.ThrottlingError
- * @classdesc   Error thrown when IoT Hub is throttled due to excessive activity.
+ * Error thrown when IoT Hub is throttled due to excessive activity.
+ * To learn more about quotas, see {@link https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling|Azure IoT Hub quotas and throttling}
  *
@@ -263,4 +302,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceAlreadyExistsError
- * @classdesc   Error thrown when the device id used for device creation already exists in the Device Identity Registry.
+ * Error thrown when the device id used for device creation already exists in the Device Identity Registry.
  *
@@ -281,4 +319,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceMessageLockLostError
- * @classdesc   Error thrown when settling a message fails because the lock token associated with the message is lost.
+ * Error thrown when settling a message fails because the lock token associated with the message is lost.
  *
@@ -299,4 +336,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.InvalidEtagError
- * @classdesc   Error thrown when the eTag specified is incorrectly formatted or out of date.
+ * Error thrown when the eTag specified is incorrectly formatted or out of date.
  *
@@ -317,4 +353,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.InvalidOperationError
- * @classdesc   Error thrown when an operation is attempted but is not allowed.
+ * Error thrown when an operation is attempted but is not allowed.
  *
@@ -335,4 +370,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.PreconditionFailedError
- * @classdesc   Error thrown when a condition that should have been met in order to execute an operation was not.
+ * Error thrown when a condition that should have been met in order to execute an operation was not.
  *
@@ -353,4 +387,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.TimeoutError
- * @classdesc   Error thrown when a timeout occurs
+ * Error thrown when a timeout occurs
  *
@@ -371,4 +404,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.BadDeviceResponseError
- * @classdesc   Error thrown when a device sends a bad response to a device method call.
+ * Error thrown when a device sends a bad response to a device method call.
  *
@@ -389,4 +421,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.GatewayTimeoutError
- * @classdesc   Error thrown when the IoT Hub instance doesn't process the device method call in time.
+ * Error thrown when the IoT Hub instance doesn't process the device method call in time.
  *
@@ -407,4 +438,3 @@ * @augments {Error}
 /**
- * @class       module:azure-iot-common.DeviceTimeoutError
- * @classdesc   Error thrown when the device doesn't process the method call in time.
+ * Error thrown when the device doesn't process the method call in time.
  *
@@ -411,0 +441,0 @@ * @augments {Error}

lib/message.d.ts

@@ -7,51 +7,59 @@ /// <reference types="node" />
 /**
- * @class module:azure-iot-common.Message
- * @classdesc Constructs a {@linkcode Message} object with the given data.
- *            `data` can be a Node [Buffer]{@linkcode https://nodejs.org/api/globals.html#globals_class_buffer}
- *            object or anything that can be used to construct a `Buffer`
- *            object from.
- * @property {Object}   properties      A map containing string
- *                                      keys and values for storing
- *                                      custom message properties.
- * @property {String}   messageId       Used to correlate two-way
- *                                      communication.
- *                                      Format: A case-sensitive string
- *                                      (up to 128 char long) of ASCII
- *                                      7-bit alphanumeric chars and the
- *                                      following special symbols:
- *                                      <br/>`- : . + % _ # * ? ! ( ) , = @ ; $ '`
- * @property {String}   to              Destination of the message
- * @property {Date}     expiryTimeUtc   Expiry time in UTC interpreted by hub on
- *                                      C2D messages. Ignored in other cases.
- * @property {String}   lockToken       Used by receiver to Abandon, Reject or
- *                                      Complete the message
- * @property {String}   correlationId   Used in message responses and feedback
- * @property {String}   userId          Used to specify the entity creating the
- *                                      message
- * @see {@link https://nodejs.org/api/globals.html#globals_class_buffer|Buffer}
+ * The {@link azure-iot-common.Message} object is used for telemetry (device-to-cloud) and commands (cloud-to-device) asynchronous
+ * messaging between the device and the IoT Hub service. It is transport-agnostic, meaning it works the same way over AMQP, MQTT and HTTP.
  */
 export declare class Message {
     data: any;
+    /**
+     * A map containing string keys and values for storing custom message properties.
+     */
     properties: Properties;
+    /**
+     * Used to correlate two-way communication. Format: A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars and the following special symbols: <br/>`- : . + % _ # * ? ! ( ) , = @ ; $ '`.
+     */
     messageId: string;
+    /**
+     * Destination of the message.
+     */
     to: string;
+    /**
+     * Expiry time in UTC interpreted by hub on C2D messages. Ignored in other cases.
+     */
     expiryTimeUtc: any;
+    /**
+     * Used to Abandon, Reject or Accept the message
+     */
     lockToken: string;
+    /**
+     * Used in message responses and feedback
+     */
     correlationId: string;
+    /**
+     * Used to specify the entity creating the message
+     */
     userId: string;
+    /**
+     * Type of feedback requested (in case of cloud-to-device command)
+     */
     ack: string;
+    /**
+     * @private
+     */
     transportObj: any;
+    /**
+     * Creates a new {@link azure-iot-common.Message} object
+     * @constructor
+     * @param data a Node [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer}
+     *             object or anything that can be passed to the [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer} constructor
+     *             to construct a [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer} from.
+     */
     constructor(data: Message.BufferConvertible);
     /**
-     * @method          module:azure-iot-common.Message#getData
-     * @description     Returns the data that was passed in to the [constructor]{@link Message}.
+     * Gets the content (body) of the {@link azure-iot-common.Message}.
      *
-     * @returns {*} The data that was passed to the [constructor]{@link Message}.
+     * @returns {*} The content of the {@link azure-iot-common.Message}.
      */
     getData(): Message.BufferConvertible;
     /**
-     * @method          module:azure-iot-common.Message#getBytes
-     * @description     Returns the data passed to the constructor as a Node
-     *                  [Buffer]{@linkcode https://nodejs.org/api/globals.html#globals_class_buffer}
-     *                  of bytes.
+     * Gets the data passed to the constructor as a [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer}
      *
@@ -58,0 +66,0 @@ * @returns {Buffer}

lib/message.js

@@ -7,28 +7,13 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class module:azure-iot-common.Message
- * @classdesc Constructs a {@linkcode Message} object with the given data.
- *            `data` can be a Node [Buffer]{@linkcode https://nodejs.org/api/globals.html#globals_class_buffer}
- *            object or anything that can be used to construct a `Buffer`
- *            object from.
- * @property {Object}   properties      A map containing string
- *                                      keys and values for storing
- *                                      custom message properties.
- * @property {String}   messageId       Used to correlate two-way
- *                                      communication.
- *                                      Format: A case-sensitive string
- *                                      (up to 128 char long) of ASCII
- *                                      7-bit alphanumeric chars and the
- *                                      following special symbols:
- *                                      <br/>`- : . + % _ # * ? ! ( ) , = @ ; $ '`
- * @property {String}   to              Destination of the message
- * @property {Date}     expiryTimeUtc   Expiry time in UTC interpreted by hub on
- *                                      C2D messages. Ignored in other cases.
- * @property {String}   lockToken       Used by receiver to Abandon, Reject or
- *                                      Complete the message
- * @property {String}   correlationId   Used in message responses and feedback
- * @property {String}   userId          Used to specify the entity creating the
- *                                      message
- * @see {@link https://nodejs.org/api/globals.html#globals_class_buffer|Buffer}
+ * The {@link azure-iot-common.Message} object is used for telemetry (device-to-cloud) and commands (cloud-to-device) asynchronous
+ * messaging between the device and the IoT Hub service. It is transport-agnostic, meaning it works the same way over AMQP, MQTT and HTTP.
  */
 var Message = (function () {
+    /**
+     * Creates a new {@link azure-iot-common.Message} object
+     * @constructor
+     * @param data a Node [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer}
+     *             object or anything that can be passed to the [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer} constructor
+     *             to construct a [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer} from.
+     */
     /*Codes_SRS_NODE_IOTHUB_MESSAGE_07_004: [The Message constructor shall accept a variable message that will be transmitted.]*/
@@ -46,6 +31,5 @@ function Message(data) {
     /**
-     * @method          module:azure-iot-common.Message#getData
-     * @description     Returns the data that was passed in to the [constructor]{@link Message}.
+     * Gets the content (body) of the {@link azure-iot-common.Message}.
      *
-     * @returns {*} The data that was passed to the [constructor]{@link Message}.
+     * @returns {*} The content of the {@link azure-iot-common.Message}.
      */
@@ -58,6 +42,3 @@ Message.prototype.getData = function () {
     /**
-     * @method          module:azure-iot-common.Message#getBytes
-     * @description     Returns the data passed to the constructor as a Node
-     *                  [Buffer]{@linkcode https://nodejs.org/api/globals.html#globals_class_buffer}
-     *                  of bytes.
+     * Gets the data passed to the constructor as a [Buffer]{@link https://nodejs.org/api/globals.html#globals_class_buffer}
      *
@@ -64,0 +45,0 @@ * @returns {Buffer}

lib/properties.d.ts

@@ -5,7 +5,16 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class Properties
- * @classdesc Collection of user defined properties. Values can only be
- *            strings.
+ * Collection of user defined properties of a {@link azure-iot-common.Message} object that are going to be sent alongside the body of the message
+ * and can be used for [routing](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-csharp-csharp-process-d2c).
+ * Values can only be strings.
  */
 export declare class Properties {
+    /**
+     * Array containing the properties stored as key/value pairs
+     * ```json
+     * [
+     *   { key: 'prop1', value: 'value1' },
+     *   { key: 'prop2', value: 'value2' }
+     * ]
+     * ```
+     */
     propertyList: any[];
@@ -12,0 +21,0 @@ /**

lib/properties.js

 /*! Copyright (c) Microsoft. All rights reserved.
  *! Licensed under the MIT license. See LICENSE file in the project root for full license information.
  */
-/**
- * The `properties` module exports the {@linkcode Properties} class which
- * is a collection type that allows you to store a collection of user
- * defined properties.
- *
- * @module common/properties
- */
 'use strict';
 /**
- * @class Properties
- * @classdesc Collection of user defined properties. Values can only be
- *            strings.
+ * Collection of user defined properties of a {@link azure-iot-common.Message} object that are going to be sent alongside the body of the message
+ * and can be used for [routing](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-csharp-csharp-process-d2c).
+ * Values can only be strings.
  */
 var Properties = (function () {
     function Properties() {
+        /**
+         * Array containing the properties stored as key/value pairs
+         * ```json
+         * [
+         *   { key: 'prop1', value: 'value1' },
+         *   { key: 'prop2', value: 'value2' }
+         * ]
+         * ```
+         */
         this.propertyList = [];
@@ -20,0 +22,0 @@ }

lib/results.d.ts

 /*! Copyright (c) Microsoft. All rights reserved.
  *! Licensed under the MIT license. See LICENSE file in the project root for full license information.
  */
+/**
+ * @private
+ */
 export interface Result {
@@ -8,98 +11,124 @@ transportObj?: any;
 /**
- * @class       module:azure-iot-common.MessageEnqueued
- * @classdesc   Result returned when a message was successfully enqueued.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully enqueued.
  */
 export declare class MessageEnqueued implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.MessageCompleted
- * @classdesc   Result returned when a message was successfully rejected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully rejected.
  */
 export declare class MessageCompleted implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.MessageRejected
- * @classdesc   Result returned when a message was successfully rejected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully rejected.
  */
 export declare class MessageRejected implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.MessageAbandoned
- * @classdesc   Result returned when a message was successfully abandoned.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully abandoned.
  */
 export declare class MessageAbandoned implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.Connected
- * @classdesc   Result returned when a transport is successfully connected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a transport is successfully connected.
  */
 export declare class Connected implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.Disconnected
- * @classdesc   Result returned when a transport is successfully disconnected.
- *
- * @property {Object} transportObj  The transport-specific object.
- * @property {String} reason        The reason why the disconnected event is emitted.
- *
- * @augments {Object}
+ * Result returned when a transport is successfully disconnected.
  */
 export declare class Disconnected implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * The reason why the disconnected event is emitted.
+     */
     reason: string;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any, reason?: string);
 }
 /**
- * @class       module:azure-iot-common.TransportConfigured
- * @classdesc   Result returned when a transport is successfully configured.
- *
- * @property {Object} transportObj  The transport-specific object.
- *
- * @augments {Object}
+ * Result returned when a transport is successfully configured.
  */
 export declare class TransportConfigured implements Result {
+    /**
+     * @private
+     */
     transportObj?: any;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(transportObj?: any);
 }
 /**
- * @class       module:azure-iot-common.SharedAccessSignatureUpdated
- * @classdesc   Result returned when a SAS token has been successfully updated.
- *
- * @param {Boolean} needToReconnect  Value indicating whether the client needs to reconnect or not.
- *
- * @augments {Object}
+ * Result returned when a SAS token has been successfully updated.
  */
 export declare class SharedAccessSignatureUpdated {
+    /**
+     * Boolean indicating whether the client needs to reconnect or not.
+     */
     needToReconnect: boolean;
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     constructor(needToReconnect: boolean);
 }

lib/results.js

@@ -6,10 +6,10 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class       module:azure-iot-common.MessageEnqueued
- * @classdesc   Result returned when a message was successfully enqueued.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully enqueued.
  */
 var MessageEnqueued = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function MessageEnqueued(transportObj) {
@@ -22,10 +22,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.MessageCompleted
- * @classdesc   Result returned when a message was successfully rejected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully rejected.
  */
 var MessageCompleted = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function MessageCompleted(transportObj) {
@@ -38,10 +38,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.MessageRejected
- * @classdesc   Result returned when a message was successfully rejected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully rejected.
  */
 var MessageRejected = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function MessageRejected(transportObj) {
@@ -54,10 +54,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.MessageAbandoned
- * @classdesc   Result returned when a message was successfully abandoned.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a message was successfully abandoned.
  */
 var MessageAbandoned = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function MessageAbandoned(transportObj) {
@@ -70,10 +70,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.Connected
- * @classdesc   Result returned when a transport is successfully connected.
- *
- * @property {Object} transportObj  The transport-specific object
- *
- * @augments {Object}
+ * Result returned when a transport is successfully connected.
  */
 var Connected = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function Connected(transportObj) {
@@ -86,11 +86,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.Disconnected
- * @classdesc   Result returned when a transport is successfully disconnected.
- *
- * @property {Object} transportObj  The transport-specific object.
- * @property {String} reason        The reason why the disconnected event is emitted.
- *
- * @augments {Object}
+ * Result returned when a transport is successfully disconnected.
  */
 var Disconnected = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function Disconnected(transportObj, reason) {
@@ -104,10 +103,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.TransportConfigured
- * @classdesc   Result returned when a transport is successfully configured.
- *
- * @property {Object} transportObj  The transport-specific object.
- *
- * @augments {Object}
+ * Result returned when a transport is successfully configured.
  */
 var TransportConfigured = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function TransportConfigured(transportObj) {
@@ -120,10 +119,10 @@ this.transportObj = transportObj;
 /**
- * @class       module:azure-iot-common.SharedAccessSignatureUpdated
- * @classdesc   Result returned when a SAS token has been successfully updated.
- *
- * @param {Boolean} needToReconnect  Value indicating whether the client needs to reconnect or not.
- *
- * @augments {Object}
+ * Result returned when a SAS token has been successfully updated.
  */
 var SharedAccessSignatureUpdated = (function () {
+    /**
+     * @private
+     * @constructor
+     * @param transportObj optional transport object to help with debugging.
+     */
     function SharedAccessSignatureUpdated(needToReconnect) {
@@ -130,0 +129,0 @@ this.needToReconnect = needToReconnect;

lib/shared_access_signature.d.ts

@@ -5,15 +5,20 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class           module:azure-iot-common.SharedAccessSignature
- * @classdesc       An object representing a shared access signature
- * @param {String}  resourceUri   The resource URI to encode into the signature
- * @param {String}  keyName       An identifier associated with the key
- * @param {String}  key           A base64-encoded key value
- * @param {String}  expiry        An integer value representing the number of
- *                                seconds since the epoch 00:00:00 UTC on
- *                                1 January 1970.
+ * Shared access signature tokens are used to authenticate the connection when using symmetric keys (as opposed to x509 certificates) to secure the connection with the Azure IoT hub.
  */
 export declare class SharedAccessSignature {
+    /**
+     * @private
+     */
     sr: string;
+    /**
+     * @private
+     */
     se: string | number;
+    /**
+     * @private
+     */
     sig: string;
+    /**
+     * @private
+     */
     skn: string;
@@ -20,0 +25,0 @@ private _key;

lib/shared_access_signature.js

@@ -9,10 +9,3 @@ /*! Copyright (c) Microsoft. All rights reserved.
 /**
- * @class           module:azure-iot-common.SharedAccessSignature
- * @classdesc       An object representing a shared access signature
- * @param {String}  resourceUri   The resource URI to encode into the signature
- * @param {String}  keyName       An identifier associated with the key
- * @param {String}  key           A base64-encoded key value
- * @param {String}  expiry        An integer value representing the number of
- *                                seconds since the epoch 00:00:00 UTC on
- *                                1 January 1970.
+ * Shared access signature tokens are used to authenticate the connection when using symmetric keys (as opposed to x509 certificates) to secure the connection with the Azure IoT hub.
  */
@@ -19,0 +12,0 @@ var SharedAccessSignature = (function () {

package.json

 {
   "name": "azure-iot-common",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "description": "Common components shared by Azure IoT device and service SDKs",
@@ -9,6 +9,5 @@ "author": "Microsoft Corporation",
   "typings": "common.d.ts",
-  "dependencies": {
-    "crypto": "^0.0.3"
-  },
+  "dependencies": {},
   "devDependencies": {
+    "@types/node": "^7.0.5",
     "chai": "^3.5.0",
@@ -18,5 +17,5 @@ "istanbul": "^0.4.4",
     "mocha": "^3.0.1",
+    "sinon": "^3.2.1",
     "tslint": "^4.5.1",
-    "typescript": "2.0.6",
-    "@types/node": "^7.0.5"
+    "typescript": "2.0.6"
   },
@@ -32,3 +31,3 @@ "scripts": {
     "test": "npm -s run lint && npm -s run build && npm -s run unittest",
-    "check-cover": "istanbul check-coverage --statements 99 --branches 96 --functions 97 --lines 99"
+    "check-cover": "istanbul check-coverage --statements 99 --branches 97 --functions 98 --lines 99"
   },
@@ -35,0 +34,0 @@ "engines": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

86086

increased by32.55%

Dependency count

0

decreased by-100%

Number of package files

31

increased by24%

Lines of code

2072

increased by37.77%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

8

increased by14.29%

Dependency changes

• - Removedcrypto@^0.0.3

• - Removedcrypto@0.0.3(transitive)