From 6cdedabd23f9ea03c2d685c23f1dc037ea9e2193 Mon Sep 17 00:00:00 2001 From: Z-Wave JS Bot <76957017+zwave-js-bot@users.noreply.github.com> Date: Mon, 17 Jun 2024 08:50:45 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20update=20typed=20documentation=20and=20?= =?UTF-8?q?API=20report=20=F0=9F=A4=96=20(#6901)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Al Calzone --- docs/api/CCs/BinarySensor.md | 21 ++++++- docs/api/driver.md | 17 ++++++ packages/cc/api.md | 26 ++++++++- packages/config/api.md | 2 + packages/core/api.md | 12 +++- packages/testing/api.md | 30 ++++++++-- packages/zwave-js/api.md | 107 ++++++++++++++++++++++++++++++----- 7 files changed, 192 insertions(+), 23 deletions(-) diff --git a/docs/api/CCs/BinarySensor.md b/docs/api/CCs/BinarySensor.md index ba135e4a289c..8e5fe8a96147 100644 --- a/docs/api/CCs/BinarySensor.md +++ b/docs/api/CCs/BinarySensor.md @@ -18,10 +18,29 @@ Retrieves the current value from this sensor. - `sensorType`: The (optional) sensor type to retrieve the value for +### `sendReport` + +```ts +async sendReport( + value: boolean, + sensorType?: BinarySensorType, +): Promise; +``` + ### `getSupportedSensorTypes` ```ts -async getSupportedSensorTypes(): Promise; +async getSupportedSensorTypes(): Promise< + readonly BinarySensorType[] | undefined +>; +``` + +### `reportSupportedSensorTypes` + +```ts +async reportSupportedSensorTypes( + supported: BinarySensorType[], +): Promise; ``` ## Binary Sensor CC values diff --git a/docs/api/driver.md b/docs/api/driver.md index 0a25007e7e5a..362a9fab55fd 100644 --- a/docs/api/driver.md +++ b/docs/api/driver.md @@ -989,6 +989,23 @@ interface ZWaveOptions extends ZWaveHostOptions { */ userAgent?: Record; + /** + * Specify application-specific information to use in queries from other devices + */ + vendor?: { + manufacturerId: number; + productType: number; + productId: number; + + /** The version of the hardware the application is running on. Can be omitted if unknown. */ + hardwareVersion?: number; + + /** The icon type to use for installers. Default: 0x0500 - Generic Gateway */ + installerIcon?: number; + /** The icon type to use for users. Default: 0x0500 - Generic Gateway */ + userIcon?: number; + }; + /** DO NOT USE! Used for testing internally */ testingHooks?: { serialPortBinding?: typeof SerialPort; diff --git a/packages/cc/api.md b/packages/cc/api.md index cb774688b1a2..56c88c65a7a5 100644 --- a/packages/cc/api.md +++ b/packages/cc/api.md @@ -2515,13 +2515,23 @@ export class BinarySensorCCSupportedGet extends BinarySensorCC { // // @public (undocumented) export class BinarySensorCCSupportedReport extends BinarySensorCC { - constructor(host: ZWaveHost_2, options: CommandClassDeserializationOptions); + constructor(host: ZWaveHost_2, options: CommandClassDeserializationOptions | (BinarySensorCCSupportedReportOptions & CCCommandOptions)); + // (undocumented) + serialize(): Buffer; // (undocumented) - readonly supportedSensorTypes: readonly BinarySensorType[]; + supportedSensorTypes: BinarySensorType[]; // (undocumented) toLogEntry(applHost: ZWaveApplicationHost_2): MessageOrCCLogEntry_2; } +// Warning: (ae-missing-release-tag) "BinarySensorCCSupportedReportOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export interface BinarySensorCCSupportedReportOptions { + // (undocumented) + supportedSensorTypes: BinarySensorType[]; +} + // Warning: (ae-missing-release-tag) "BinarySensorCCValues" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -3075,6 +3085,11 @@ export interface CCValueOptions { supportsEndpoints?: boolean; } +// Warning: (ae-missing-release-tag) "CCValuePredicate" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export type CCValuePredicate = (valueId: ValueID) => boolean; + // Warning: (tsdoc-undefined-tag) The TSDoc tag "@publicAPI" is not defined in this configuration // Warning: (ae-missing-release-tag) "ccValues" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -4156,7 +4171,7 @@ export class CommandClass implements ICommandClass { protected getCCValue(valueId: ValueID): StaticCCValue | DynamicCCValue | undefined; static getCommandClass(data: Buffer): CommandClasses_2; static getConstructor(ccData: Buffer): CCConstructor; - getDefinedValueIDs(applHost: ZWaveApplicationHost): ValueID[]; + getDefinedValueIDs(applHost: ZWaveApplicationHost, includeInternal?: boolean): ValueID[]; getEncapsulatedCC(ccId: CommandClasses_2, ccCommand?: number): CommandClass | undefined; getEncapsulatingCC(ccId: CommandClasses_2, ccCommand?: number): CommandClass | undefined; // (undocumented) @@ -13576,6 +13591,11 @@ export type OwnMethodsOf = Omit, keyof OnlyM // @public (undocumented) export function parseWakeUpTime(value: number): WakeUpTime; +// Warning: (ae-missing-release-tag) "PartialCCValuePredicate" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export type PartialCCValuePredicate = (properties: ValueIDProperties) => boolean; + // Warning: (ae-missing-release-tag) "PhysicalCCAPI" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public diff --git a/packages/config/api.md b/packages/config/api.md index 53ee2e488c24..8b7f90dd3a42 100644 --- a/packages/config/api.md +++ b/packages/config/api.md @@ -160,6 +160,8 @@ export class ConditionalCompatConfig implements ConditionalItem { // (undocumented) readonly disableStrictMeasurementValidation?: boolean; // (undocumented) + readonly encodeCCsUsingTargetVersion?: boolean; + // (undocumented) evaluateCondition(deviceId?: DeviceID): CompatConfig | undefined; // (undocumented) readonly forceNotificationIdleReset?: boolean; diff --git a/packages/core/api.md b/packages/core/api.md index 96a9ba01862d..5293bd497d6f 100644 --- a/packages/core/api.md +++ b/packages/core/api.md @@ -151,8 +151,6 @@ export interface CacheMetadata extends Pick { - // Warning: (ae-forgotten-export) The symbol "SerializedValue" needs to be exported by the entry point index.d.ts - // // (undocumented) value: SerializedValue; } @@ -2274,6 +2272,11 @@ export enum SecurityClass { Temporary = -2 } +// Warning: (ae-missing-release-tag) "securityClassIsLongRange" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public +export function securityClassIsLongRange(secClass: SecurityClass | undefined): secClass is S2SecurityClass; + // Warning: (ae-missing-release-tag) "securityClassIsS2" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -2457,6 +2460,11 @@ export type SerializableTXReport = Partial> & Pic // @public export function serializeCacheValue(value: unknown): SerializedValue; +// Warning: (ae-missing-release-tag) "SerializedValue" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export type SerializedValue = number | string | boolean | JSONObject | undefined; + // Warning: (ae-missing-release-tag) "SetNonceOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) diff --git a/packages/testing/api.md b/packages/testing/api.md index 15e65bce0a06..d22d257e5303 100644 --- a/packages/testing/api.md +++ b/packages/testing/api.md @@ -19,6 +19,16 @@ import { ZWaveApiVersion } from '@zwave-js/core/safe'; import type { ZWaveHost } from '@zwave-js/host'; import { ZWaveLibraryTypes } from '@zwave-js/core/safe'; +// Warning: (ae-missing-release-tag) "BinarySensorCCCapabilities" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export interface BinarySensorCCCapabilities { + // (undocumented) + getValue?: (sensorType: number | undefined) => boolean | undefined; + // (undocumented) + supportedSensorTypes: number[]; +} + // Warning: (ae-missing-release-tag) "ccCaps" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -35,6 +45,7 @@ export type CCIdToCapabilities = T ex export type CCSpecificCapabilities = { [CommandClasses.Configuration]: ConfigurationCCCapabilities; [CommandClasses.Notification]: NotificationCCCapabilities; + [48]: BinarySensorCCCapabilities; [49]: MultilevelSensorCCCapabilities; [121]: SoundSwitchCCCapabilities; [106]: WindowCoveringCCCapabilities; @@ -102,6 +113,21 @@ export interface EnergyProductionCCCapabilities { }; } +// Warning: (ae-forgotten-export) The symbol "MockEndpointCapabilities" needs to be exported by the entry point index.d.ts +// Warning: (ae-missing-release-tag) "getDefaultMockEndpointCapabilities" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export function getDefaultMockEndpointCapabilities(nodeCaps: { + genericDeviceClass: number; + specificDeviceClass: number; +}): MockEndpointCapabilities; + +// Warning: (ae-forgotten-export) The symbol "MockNodeCapabilities" needs to be exported by the entry point index.d.ts +// Warning: (ae-missing-release-tag) "getDefaultMockNodeCapabilities" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export function getDefaultMockNodeCapabilities(): MockNodeCapabilities; + // Warning: (ae-missing-release-tag) "getDefaultSupportedFunctionTypes" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -209,8 +235,6 @@ export interface MockControllerOptions { export class MockEndpoint { constructor(options: MockEndpointOptions); addCC(cc: CommandClasses, info: Partial): void; - // Warning: (ae-forgotten-export) The symbol "MockEndpointCapabilities" needs to be exported by the entry point index.d.ts - // // (undocumented) readonly capabilities: MockEndpointCapabilities; // (undocumented) @@ -252,8 +276,6 @@ export class MockNode { errorMessage?: string; }): void; autoAckControllerFrames: boolean; - // Warning: (ae-forgotten-export) The symbol "MockNodeCapabilities" needs to be exported by the entry point index.d.ts - // // (undocumented) readonly capabilities: MockNodeCapabilities; clearReceivedControllerFrames(): void; diff --git a/packages/zwave-js/api.md b/packages/zwave-js/api.md index 7aff15fa4699..f38916754144 100644 --- a/packages/zwave-js/api.md +++ b/packages/zwave-js/api.md @@ -22,6 +22,7 @@ import { CommandClass } from '@zwave-js/cc'; import { CommandClasses } from '@zwave-js/core'; import { CommandClasses as CommandClasses_2 } from '@zwave-js/core/safe'; import { CommandClassInfo } from '@zwave-js/core'; +import type { CommandClassInfo as CommandClassInfo_2 } from '@zwave-js/core/safe'; import { Comparable } from 'alcalzone-shared/comparable'; import { CompareResult } from 'alcalzone-shared/comparable'; import { ConfigManager } from '@zwave-js/config'; @@ -72,7 +73,7 @@ import { IVirtualEndpoint } from '@zwave-js/core/safe'; import { IVirtualNode } from '@zwave-js/core'; import type { IZWaveEndpoint } from '@zwave-js/core'; import { IZWaveNode } from '@zwave-js/core'; -import type { JSONObject } from '@zwave-js/shared'; +import { JSONObject } from '@zwave-js/shared'; import { KEXFailType } from '@zwave-js/cc'; import { LogConfig } from '@zwave-js/core'; import { LogContext } from '@zwave-js/core'; @@ -144,6 +145,7 @@ import { SendCommandOptions } from '@zwave-js/core'; import { SendCommandReturnType } from '@zwave-js/core'; import { SendMessageOptions } from '@zwave-js/core'; import { SensorType } from '@zwave-js/config'; +import type { SerializedValue } from '@zwave-js/core/safe'; import type { SerialPort } from 'serialport'; import { SetbackState } from '@zwave-js/cc'; import { SetValueAPIOptions } from '@zwave-js/cc'; @@ -568,7 +570,7 @@ export { DurationUnit } // Warning: (ae-missing-release-tag) "EditableZWaveOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export type EditableZWaveOptions = Expand & { +export type EditableZWaveOptions = Expand & { userAgent?: Record; }>; @@ -989,6 +991,74 @@ export { NODE_ID_BROADCAST } 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) +// +// @public (undocumented) +export interface NodeDump { + // Warning: (ae-forgotten-export) The symbol "CommandClassDump" needs to be exported by the entry point index.d.ts + // + // (undocumented) + commandClasses: Record; + // (undocumented) + compatFlags?: JSONObject; + // (undocumented) + configFileName?: string; + // (undocumented) + description?: string; + // Warning: (ae-forgotten-export) The symbol "DeviceClassesDump" needs to be exported by the entry point index.d.ts + // + // (undocumented) + deviceClass: DeviceClassesDump | "unknown"; + // (undocumented) + dsk?: string; + // Warning: (ae-forgotten-export) The symbol "EndpointDump" needs to be exported by the entry point index.d.ts + // + // (undocumented) + endpoints?: Record; + // (undocumented) + fingerprint: { + manufacturerId: string; + productType: string; + productId: string; + firmwareVersion: string; + hardwareVersion?: number; + }; + // (undocumented) + id: number; + // (undocumented) + interviewStage: string; + // (undocumented) + isFrequentListening: FLiRS | "unknown"; + // (undocumented) + isListening: boolean | "unknown"; + // (undocumented) + isRouting: boolean | "unknown"; + // (undocumented) + label?: string; + // (undocumented) + manufacturer?: string; + // (undocumented) + maySupportBasicCC: boolean; + // (undocumented) + protocol: string; + // (undocumented) + protocolVersion: string; + // (undocumented) + ready: boolean; + // (undocumented) + sdkVersion: string; + // (undocumented) + securityClasses: Record; + // (undocumented) + supportedDataRates: DataRate[] | "unknown"; + // (undocumented) + supportedProtocols?: string[]; + // (undocumented) + supportsBeaming: boolean | "unknown"; + // (undocumented) + supportsSecurity: boolean | "unknown"; +} + // Warning: (ae-missing-release-tag) "NodeInterviewFailedEventArgs" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -1032,7 +1102,7 @@ export { parseQRCodeString } // Warning: (ae-missing-release-tag) "PartialZWaveOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export type PartialZWaveOptions = Expand> & Partial> & { +export type PartialZWaveOptions = Expand> & Partial> & { inclusionUserCallbacks?: ZWaveOptions["inclusionUserCallbacks"]; logConfig?: Partial; }>; @@ -1735,6 +1805,7 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod get canSleep(): MaybeNotKnown; checkLifelineHealth(rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: LifelineHealthCheckResult) => void): Promise; checkRouteHealth(targetNodeId: number, rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: RouteHealthCheckResult) => void): Promise; + createDump(): NodeDump; get defaultTransitionDuration(): string | undefined; set defaultTransitionDuration(value: string | Duration_2 | undefined); get defaultVolume(): number | undefined; @@ -1766,6 +1837,8 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod getValue(valueId: ValueID_2): MaybeNotKnown; getValueMetadata(valueId: ValueID_2): ValueMetadata_2; getValueTimestamp(valueId: ValueID_2): MaybeNotKnown; + // (undocumented) + get hardwareVersion(): MaybeNotKnown; hasDeviceConfigChanged(): MaybeNotKnown; // (undocumented) hasSecurityClass(securityClass: SecurityClass_2): MaybeNotKnown; @@ -2144,6 +2217,14 @@ export interface ZWaveOptions extends ZWaveHostOptions { serialAPIStarted: number; }; userAgent?: Record; + vendor?: { + manufacturerId: number; + productType: number; + productId: number; + hardwareVersion?: number; + installerIcon?: number; + userIcon?: number; + }; } @@ -2152,17 +2233,17 @@ export * from "@zwave-js/cc"; // Warnings were encountered during analysis: // // src/lib/controller/Controller.ts:849:2 - (ae-missing-getter) The property "provisioningList" has a setter but no getter. -// src/lib/driver/Driver.ts:699: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:4080: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:5151:2 - (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "drainSerialAPIQueue" -// src/lib/driver/Driver.ts:5554: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:5555: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:5597: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:5598: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:5734: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:706: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:4172: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:5242:2 - (ae-unresolved-link) The @link reference could not be resolved: The package "zwave-js" does not have an export "drainSerialAPIQueue" +// src/lib/driver/Driver.ts:5645: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:5646: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:5688: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:5689: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:5825: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:273: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:1016:2 - (ae-missing-getter) The property "deviceConfigHash" has a setter but no getter. -// src/lib/node/Node.ts:2904: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:1026:2 - (ae-missing-getter) The property "deviceConfigHash" has a setter but no getter. +// src/lib/node/Node.ts:2914: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