feat: include reason for low security in "node added" parameter (#5570

)

docs/api/controller.md

@@ -1183,9 +1183,42 @@ The second argument gives additional info about the inclusion result.
 <!-- #import InclusionResult from "zwave-js" -->
 
 ```ts
-interface InclusionResult {
-	/** This flag warns that a node was included with a lower than intended security, meaning unencrypted when it should have been included with Security S0/S2 */
-	lowSecurity?: boolean;
+type InclusionResult =
+	| {
+			/** This flag warns that a node was included with a lower than intended security, meaning unencrypted when it should have been included with Security S0/S2 */
+			lowSecurity?: false;
+	  }
+	| {
+			/** This flag warns that a node was included with a lower than intended security, meaning unencrypted when it should have been included with Security S0/S2 */
+			lowSecurity: true;
+			lowSecurityReason: SecurityBootstrapFailure;
+	  };
+```
+
+If there was a failure during the inclusion, the `lowSecurity` flag will be `true` and the `lowSecurityReason` property will contain additional information why.
+
+<!-- #import SecurityBootstrapFailure from "zwave-js" -->
+
+```ts
+enum SecurityBootstrapFailure {
+	/** Security bootstrapping was canceled by the user */
+	UserCanceled,
+	/** The required security keys were not configured in the driver */
+	NoKeysConfigured,
+	/** No Security S2 user callbacks (or provisioning info) were provided to grant security classes and/or validate the DSK. */
+	S2NoUserCallbacks,
+	/** An expected message was not received within the corresponding timeout */
+	Timeout,
+	/** There was no possible match in encryption parameters between the controller and the node */
+	ParameterMismatch,
+	/** Security bootstrapping was canceled by the included node */
+	NodeCanceled,
+	/** The PIN was incorrect, so the included node could not decode the key exchange commands */
+	S2IncorrectPIN,
+	/** There was a mismatch in security keys between the controller and the node */
+	S2WrongSecurityLevel,
+	/** Some other unspecified error happened */
+	Unknown,
 }
 ```
 

packages/zwave-js/api.md

@@ -602,9 +602,12 @@ export type InclusionOptions = {
 // Warning: (ae-missing-release-tag) "InclusionResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
-export interface InclusionResult {
-    lowSecurity?: boolean;
-}
+export type InclusionResult = {
+    lowSecurity?: false;
+} | {
+    lowSecurity: true;
+    lowSecurityReason: SecurityBootstrapFailure;
+};
 
 // Warning: (ae-missing-release-tag) "InclusionState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -851,6 +854,21 @@ export { Scale }
 // @public (undocumented)
 export type SDKVersion = `${number}.${number}` | `${number}.${number}.${number}`;
 
+// Warning: (ae-missing-release-tag) "SecurityBootstrapFailure" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export enum SecurityBootstrapFailure {
+    NodeCanceled = 5,
+    NoKeysConfigured = 1,
+    ParameterMismatch = 4,
+    S2IncorrectPIN = 6,
+    S2NoUserCallbacks = 2,
+    S2WrongSecurityLevel = 7,
+    Timeout = 3,
+    Unknown = 8,
+    UserCanceled = 0
+}
+
 export { SendMessageOptions }
 
 export { SensorType }