From 4ca1b85d250b6eb40329051868cef820ac8a0746 Mon Sep 17 00:00:00 2001 From: Al Calzone Date: Thu, 25 Jul 2024 09:32:32 +0000 Subject: [PATCH] docs: update typed documentation and API report --- packages/cc/cc.api.md | 4 +- packages/core/core.api.md | 7 +-- packages/testing/testing.api.md | 44 ++++++++++++++-- packages/zwave-js/zwave-js.api.md | 87 +++++++++++++++++++++++++++---- 4 files changed, 122 insertions(+), 20 deletions(-) diff --git a/packages/cc/cc.api.md b/packages/cc/cc.api.md index 6444c64b3cf3..b0d1dca62573 100644 --- a/packages/cc/cc.api.md +++ b/packages/cc/cc.api.md @@ -79,6 +79,7 @@ import { MultiCommandCCAPI } from '../cc/MultiCommandCC'; import { MultilevelSensorCCAPI } from '../cc/MultilevelSensorCC'; import { MultilevelSwitchCCAPI } from '../cc/MultilevelSwitchCC'; import { NODE_ID_BROADCAST } from '@zwave-js/core'; +import { NODE_ID_BROADCAST_LR } from '@zwave-js/core'; import { NodeInformationFrame } from '@zwave-js/core'; import { NodeNamingAndLocationCCAPI } from '../cc/NodeNamingCC'; import { NodeProtocolInfoAndDeviceClass } from '@zwave-js/core'; @@ -2915,7 +2916,7 @@ export class CCAPI { // (undocumented) protected isBroadcast(): this is this & { endpoint: IVirtualEndpoint & { - nodeId: typeof NODE_ID_BROADCAST; + nodeId: typeof NODE_ID_BROADCAST | typeof NODE_ID_BROADCAST_LR; }; }; // (undocumented) @@ -22016,7 +22017,6 @@ export enum ZWaveProtocolCommand { // // src/cc/TransportServiceCC.ts:47:2 - (ae-unresolved-link) The @link reference could not be resolved: The package "@zwave-js/cc" does not have an export "RELAXED_TIMING_THRESHOLD" // src/cc/TransportServiceCC.ts:49:2 - (ae-unresolved-link) The @link reference could not be resolved: The package "@zwave-js/cc" does not have an export "RELAXED_TIMING_THRESHOLD" -// /home/runner/work/node-zwave-js/node-zwave-js/packages/serial/src/message/ZnifferMessages.ts:268:18 - (TS2564) Property 'checksumOK' has no initializer and is not definitely assigned in the constructor. // (No @packageDocumentation comment for this package) diff --git a/packages/core/core.api.md b/packages/core/core.api.md index f7a7562fcfe3..78625703b78e 100644 --- a/packages/core/core.api.md +++ b/packages/core/core.api.md @@ -108,7 +108,7 @@ export enum BeamingInfo { // // @public (undocumented) export type BroadcastCC = T & { - nodeId: typeof NODE_ID_BROADCAST; + nodeId: typeof NODE_ID_BROADCAST | typeof NODE_ID_BROADCAST_LR; }; // Warning: (ae-missing-release-tag) "CacheBackedMap" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -4262,6 +4262,7 @@ export enum ZWaveErrorCodes { FWUpdateService_RequestError = 261, HealthCheck_Busy = 400, Invalid_Firmware_File = 1506, + LinkReliabilityCheck_Busy = 401, ManufacturerProprietaryCC_NoManufacturerId = 1200, NVM_InvalidFormat = 283, NVM_InvalidJSON = 281, @@ -4386,8 +4387,8 @@ export interface ZWaveLogInfo extends // Warnings were encountered during analysis: // -// src/security/Manager2.ts:116:79 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// src/security/Manager2.ts:116:98 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// src/security/Manager2.ts:117:79 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag +// src/security/Manager2.ts:117:98 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // src/security/QR.ts:99:3 - (ae-unresolved-link) The @link reference could not be resolved: The package "@zwave-js/core" does not have an export "requestedSecurityClasses" // (No @packageDocumentation comment for this package) diff --git a/packages/testing/testing.api.md b/packages/testing/testing.api.md index 693ff1d799ee..89b77068fdcd 100644 --- a/packages/testing/testing.api.md +++ b/packages/testing/testing.api.md @@ -4,6 +4,7 @@ ```ts +import { CommandClass } from '@zwave-js/cc'; import { CommandClasses } from '@zwave-js/core'; import { CommandClassInfo } from '@zwave-js/core'; import { ConfigValue } from '@zwave-js/core'; @@ -85,7 +86,7 @@ export function createMockZWaveAckFrame(options?: Partial ICommandClass), options?: Partial>): LazyMockZWaveRequestFrame; +export function createMockZWaveRequestFrame(payload: CommandClass | (() => CommandClass), options?: Partial>): LazyMockZWaveRequestFrame; // Warning: (ae-missing-release-tag) "EnergyProductionCCCapabilities" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -142,7 +143,7 @@ export type LazyMockZWaveFrame = LazyMockZWaveRequestFrame | MockZWaveAckFrame; // @public (undocumented) export interface LazyMockZWaveRequestFrame { ackRequested: boolean; - payload: ICommandClass | (() => ICommandClass); + payload: CommandClass | (() => CommandClass); repeaters: number[]; // (undocumented) type: MockZWaveFrameType.Request; @@ -333,7 +334,9 @@ export class MockNode { // // @public (undocumented) export interface MockNodeBehavior { - onControllerFrame?: (controller: MockController, self: MockNode, frame: MockZWaveFrame) => Promise | boolean | undefined; + handleCC?: (controller: MockController, self: MockNode, receivedCC: CommandClass) => Promise | MockNodeResponse | undefined; + transformIncomingCC?: (controller: MockController, self: MockNode, cc: CommandClass) => Promise | CommandClass; + transformResponse?: (controller: MockController, self: MockNode, receivedCC: CommandClass, response: MockNodeResponse) => Promise | MockNodeResponse; } // Warning: (ae-missing-release-tag) "MockNodeOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -353,6 +356,23 @@ export interface MockNodeOptions { id: number; } +// Warning: (ae-missing-release-tag) "MockNodeResponse" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public +export type MockNodeResponse = { + action: "sendCC"; + cc: CommandClass; + ackRequested?: boolean; +} | { + action: "ack"; +} | { + action: "stop"; +} | { + action: "ok"; +} | { + action: "fail"; +}; + // Warning: (ae-missing-release-tag) "MockZWaveAckFrame" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -384,7 +404,7 @@ export enum MockZWaveFrameType { // @public (undocumented) export interface MockZWaveRequestFrame { ackRequested: boolean; - payload: ICommandClass; + payload: CommandClass; repeaters: number[]; // (undocumented) type: MockZWaveFrameType.Request; @@ -502,7 +522,21 @@ export interface WindowCoveringCCCapabilities { // Warnings were encountered during analysis: // -// /home/runner/work/node-zwave-js/node-zwave-js/packages/serial/src/message/ZnifferMessages.ts:268:18 - (TS2564) Property 'checksumOK' has no initializer and is not definitely assigned in the constructor. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/ColorSwitchCC.ts:477:9 - (TS2345) Argument of type '("index" | "warmWhite" | "coldWhite" | "red" | "green" | "blue" | "amber" | "cyan" | "purple" | undefined)[]' is not assignable to parameter of type 'readonly (string | number | symbol)[]'. +// Type 'string | undefined' is not assignable to type 'string | number | symbol'. +// Type 'undefined' is not assignable to type 'string | number | symbol'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/ConfigurationCC.ts:1273:41 - (TS2345) Argument of type 'string | number' is not assignable to parameter of type 'number'. +// Type 'string' is not assignable to type 'number'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/ConfigurationCC.ts:1280:20 - (TS2345) Argument of type 'string | number' is not assignable to parameter of type 'number'. +// Type 'string' is not assignable to type 'number'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/ConfigurationCC.ts:1398:40 - (TS2345) Argument of type 'string | number' is not assignable to parameter of type 'number'. +// Type 'string' is not assignable to type 'number'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1355:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MGRPExtension | undefined'. +// Property 'groupId' is missing in type 'Security2Extension' but required in type 'MGRPExtension'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1366:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MPANExtension | undefined'. +// Type 'Security2Extension' is missing the following properties from type 'MPANExtension': groupId, innerMPANState +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1380:25 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1438:19 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. // (No @packageDocumentation comment for this package) diff --git a/packages/zwave-js/zwave-js.api.md b/packages/zwave-js/zwave-js.api.md index c7653ccd0e78..da5b3cb07fd6 100644 --- a/packages/zwave-js/zwave-js.api.md +++ b/packages/zwave-js/zwave-js.api.md @@ -98,7 +98,8 @@ import { MulticastDestination } from '@zwave-js/core/safe'; import { MultilevelSwitchCommand } from '@zwave-js/cc/safe'; import { NODE_ID_BROADCAST } from '@zwave-js/core/safe'; import { NODE_ID_BROADCAST as NODE_ID_BROADCAST_2 } from '@zwave-js/core'; -import { NODE_ID_BROADCAST_LR } from '@zwave-js/core'; +import { NODE_ID_BROADCAST_LR } from '@zwave-js/core/safe'; +import { NODE_ID_BROADCAST_LR as NODE_ID_BROADCAST_LR_2 } from '@zwave-js/core'; import { NODE_ID_MAX } from '@zwave-js/core/safe'; import { NodeIDType } from '@zwave-js/core'; import type { NodeSchedulePollOptions } from '@zwave-js/host'; @@ -869,6 +870,66 @@ export interface LifelineRoutes { nlwr?: RouteStatistics; } +// Warning: (ae-missing-release-tag) "LinkReliabilityCheckMode" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export enum LinkReliabilityCheckMode { + // (undocumented) + BasicSetOnOff = 0 +} + +// Warning: (ae-missing-release-tag) "LinkReliabilityCheckOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export interface LinkReliabilityCheckOptions { + // (undocumented) + interval: number; + // (undocumented) + mode: LinkReliabilityCheckMode; + // (undocumented) + onProgress?: (progress: LinkReliabilityCheckResult) => void; + // (undocumented) + rounds?: number; +} + +// Warning: (ae-missing-release-tag) "LinkReliabilityCheckResult" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export interface LinkReliabilityCheckResult { + // (undocumented) + ackRSSI: { + min: number; + max: number; + average: number; + }; + // (undocumented) + commandErrors: number; + // (undocumented) + commandsSent: number; + // (undocumented) + latency?: { + min: number; + max: number; + average: number; + }; + // (undocumented) + missingResponses?: number; + // (undocumented) + responseRSSI?: { + min: number; + max: number; + average: number; + }; + // (undocumented) + rounds: number; + // (undocumented) + rtt: { + min: number; + max: number; + average: number; + }; +} + // Warning: (ae-missing-release-tag) "LongRangeFrame" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -891,7 +952,7 @@ export type LongRangeFrame = { payload: Buffer | CommandClass; } | { type: LongRangeFrameType.Broadcast; - destinationNodeId: typeof NODE_ID_BROADCAST_LR; + destinationNodeId: typeof NODE_ID_BROADCAST_LR_2; ackRequested: boolean; payload: Buffer | CommandClass; } | { @@ -982,6 +1043,8 @@ export { MultilevelSwitchCommand } export { NODE_ID_BROADCAST } +export { NODE_ID_BROADCAST_LR } + export { NODE_ID_MAX } // Warning: (ae-missing-release-tag) "NodeDump" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -1498,6 +1561,7 @@ export class ZWaveController extends TypedEventEmitter rssiChannel3?: RSSI_2; }>; getBroadcastNode(): VirtualNode; + getBroadcastNodeLR(): VirtualNode; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "assignCustomReturnRoutes" getCustomReturnRoutesCached(nodeId: number, destinationNodeId: number): Route[]; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "assignCustomSUCReturnRoutes" @@ -1800,11 +1864,14 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "checkLifelineHealth" // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "checkRouteHealth" abortHealthCheck(): void; + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "checkLinkReliability" + abortLinkReliabilityCheck(): void; // (undocumented) get aggregatedEndpointCount(): MaybeNotKnown; // (undocumented) get canSleep(): MaybeNotKnown; checkLifelineHealth(rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: LifelineHealthCheckResult) => void): Promise; + checkLinkReliability(options: LinkReliabilityCheckOptions): Promise; checkRouteHealth(targetNodeId: number, rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: RouteHealthCheckResult) => void): Promise; createDump(): NodeDump; get defaultTransitionDuration(): string | undefined; @@ -1860,6 +1927,7 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod isFirmwareUpdateInProgress(): boolean; get isFrequentListening(): MaybeNotKnown; isHealthCheckInProgress(): boolean; + isLinkReliabilityCheckInProgress(): boolean; get isListening(): MaybeNotKnown; get isRouting(): MaybeNotKnown; get isSecure(): MaybeNotKnown; @@ -2241,14 +2309,13 @@ export * from "@zwave-js/cc"; // Type 'string' is not assignable to type 'number'. // /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/ConfigurationCC.ts:1398:40 - (TS2345) Argument of type 'string | number' is not assignable to parameter of type 'number'. // Type 'string' is not assignable to type 'number'. -// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1338:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MGRPExtension | undefined'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1355:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MGRPExtension | undefined'. // Property 'groupId' is missing in type 'Security2Extension' but required in type 'MGRPExtension'. -// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1349:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MPANExtension | undefined'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1366:3 - (TS2322) Type 'Security2Extension | undefined' is not assignable to type 'MPANExtension | undefined'. // Type 'Security2Extension' is missing the following properties from type 'MPANExtension': groupId, innerMPANState -// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1363:25 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. -// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1421:19 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. -// /home/runner/work/node-zwave-js/node-zwave-js/packages/serial/src/message/ZnifferMessages.ts:268:18 - (TS2564) Property 'checksumOK' has no initializer and is not definitely assigned in the constructor. -// src/lib/controller/Controller.ts:852:2 - (ae-missing-getter) The property "provisioningList" has a setter but no getter. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1380:25 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. +// /home/runner/work/node-zwave-js/node-zwave-js/packages/cc/src/cc/Security2CC.ts:1438:19 - (TS2339) Property 'senderEI' does not exist on type 'Security2Extension'. +// src/lib/controller/Controller.ts:865:2 - (ae-missing-getter) The property "provisioningList" has a setter but no getter. // src/lib/driver/Driver.ts:701:24 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // src/lib/driver/Driver.ts:4191:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/lib/driver/Driver.ts:5340:2 - (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "drainSerialAPIQueue" @@ -2258,8 +2325,8 @@ export * from "@zwave-js/cc"; // src/lib/driver/Driver.ts:5777:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/lib/driver/Driver.ts:5913:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/lib/driver/ZWaveOptions.ts:270:120 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// src/lib/node/Node.ts:1028:2 - (ae-missing-getter) The property "deviceConfigHash" has a setter but no getter. -// src/lib/node/Node.ts:3003:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen +// src/lib/node/Node.ts:1032:2 - (ae-missing-getter) The property "deviceConfigHash" has a setter but no getter. +// src/lib/node/Node.ts:3018:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/lib/zniffer/Zniffer.ts:620:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/lib/zniffer/Zniffer.ts:621:5 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen