Skip to content

Commit

Permalink
docs: update typed documentation and API report 🤖 (#6901)
Browse files Browse the repository at this point in the history 
Co-authored-by: Al Calzone <[email protected]>
  • Loading branch information
@zwave-js-bot @AlCalzone
zwave-js-bot and AlCalzone authored Jun 17, 2024
1 parent b0723e0 commit 6cdedab
Show file tree
Hide file tree
Showing 7 changed files with 192 additions and 23 deletions.
21 changes: 20 additions & 1 deletion docs/api/CCs/BinarySensor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<SupervisionResult | undefined>;
```

### `getSupportedSensorTypes`

```ts
async getSupportedSensorTypes(): Promise<readonly BinarySensorType[] | undefined>;
async getSupportedSensorTypes(): Promise<
readonly BinarySensorType[] | undefined
>;
```

### `reportSupportedSensorTypes`

```ts
async reportSupportedSensorTypes(
supported: BinarySensorType[],
): Promise<SupervisionResult | undefined>;
```

## Binary Sensor CC values
Expand Down
17 changes: 17 additions & 0 deletions docs/api/driver.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -989,6 +989,23 @@ interface ZWaveOptions extends ZWaveHostOptions {
*/
userAgent?: Record<string, string>;
/**
* 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;
Expand Down
26 changes: 23 additions & 3 deletions packages/cc/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
//
Expand Down Expand Up @@ -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<CommandClass>;
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)
Expand Down Expand Up @@ -13576,6 +13591,11 @@ export type OwnMethodsOf<API extends CCAPI> = Omit<OnlyMethods<API>, 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
Expand Down
2 changes: 2 additions & 0 deletions packages/config/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,8 @@ export class ConditionalCompatConfig implements ConditionalItem<CompatConfig> {
// (undocumented)
readonly disableStrictMeasurementValidation?: boolean;
// (undocumented)
readonly encodeCCsUsingTargetVersion?: boolean;
// (undocumented)
evaluateCondition(deviceId?: DeviceID): CompatConfig | undefined;
// (undocumented)
readonly forceNotificationIdleReset?: boolean;
Expand Down
12 changes: 10 additions & 2 deletions packages/core/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,8 +151,6 @@ export interface CacheMetadata extends Pick<ValueID, "endpoint" | "property" | "
//
// @public (undocumented)
export interface CacheValue extends Pick<ValueID, "endpoint" | "property" | "propertyKey"> {
// Warning: (ae-forgotten-export) The symbol "SerializedValue" needs to be exported by the entry point index.d.ts
//
// (undocumented)
value: SerializedValue;
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -2457,6 +2460,11 @@ export type SerializableTXReport = Partial<Omit<TXReport, "numRepeaters">> & 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)
Expand Down
30 changes: 26 additions & 4 deletions packages/testing/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -35,6 +45,7 @@ export type CCIdToCapabilities<T extends CommandClasses = CommandClasses> = T ex
export type CCSpecificCapabilities = {
[CommandClasses.Configuration]: ConfigurationCCCapabilities;
[CommandClasses.Notification]: NotificationCCCapabilities;
[48]: BinarySensorCCCapabilities;
[49]: MultilevelSensorCCCapabilities;
[121]: SoundSwitchCCCapabilities;
[106]: WindowCoveringCCCapabilities;
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -209,8 +235,6 @@ export interface MockControllerOptions {
export class MockEndpoint {
constructor(options: MockEndpointOptions);
addCC(cc: CommandClasses, info: Partial<CommandClassInfo>): void;
// Warning: (ae-forgotten-export) The symbol "MockEndpointCapabilities" needs to be exported by the entry point index.d.ts
//
// (undocumented)
readonly capabilities: MockEndpointCapabilities;
// (undocumented)
Expand Down Expand Up @@ -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;
Expand Down
107 changes: 94 additions & 13 deletions packages/zwave-js/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -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<Pick<PartialZWaveOptions, "disableOptimisticValueUpdate" | "emitValueUpdateAfterSetValue" | "inclusionUserCallbacks" | "interview" | "logConfig" | "preferences"> & {
export type EditableZWaveOptions = Expand<Pick<PartialZWaveOptions, "disableOptimisticValueUpdate" | "emitValueUpdateAfterSetValue" | "inclusionUserCallbacks" | "interview" | "logConfig" | "preferences" | "vendor"> & {
userAgent?: Record<string, string | null | undefined>;
}>;

Expand Down Expand Up @@ -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<string, CommandClassDump>;
// (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<number, EndpointDump>;
// (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<string, boolean | "unknown">;
// (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)
Expand Down Expand Up @@ -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<DeepPartial<Omit<ZWaveOptions, "inclusionUserCallbacks" | "logConfig" | "testingHooks">> & Partial<Pick<ZWaveOptions, "inclusionUserCallbacks" | "testingHooks">> & {
export type PartialZWaveOptions = Expand<DeepPartial<Omit<ZWaveOptions, "inclusionUserCallbacks" | "logConfig" | "testingHooks">> & Partial<Pick<ZWaveOptions, "inclusionUserCallbacks" | "testingHooks" | "vendor">> & {
inclusionUserCallbacks?: ZWaveOptions["inclusionUserCallbacks"];
logConfig?: Partial<LogConfig>;
}>;
Expand Down Expand Up @@ -1735,6 +1805,7 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod
get canSleep(): MaybeNotKnown<boolean>;
checkLifelineHealth(rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: LifelineHealthCheckResult) => void): Promise<LifelineHealthCheckSummary>;
checkRouteHealth(targetNodeId: number, rounds?: number, onProgress?: (round: number, totalRounds: number, lastRating: number, lastResult: RouteHealthCheckResult) => void): Promise<RouteHealthCheckSummary>;
createDump(): NodeDump;
get defaultTransitionDuration(): string | undefined;
set defaultTransitionDuration(value: string | Duration_2 | undefined);
get defaultVolume(): number | undefined;
Expand Down Expand Up @@ -1766,6 +1837,8 @@ export class ZWaveNode extends Endpoint implements SecurityClassOwner, IZWaveNod
getValue<T = unknown>(valueId: ValueID_2): MaybeNotKnown<T>;
getValueMetadata(valueId: ValueID_2): ValueMetadata_2;
getValueTimestamp(valueId: ValueID_2): MaybeNotKnown<number>;
// (undocumented)
get hardwareVersion(): MaybeNotKnown<number>;
hasDeviceConfigChanged(): MaybeNotKnown<boolean>;
// (undocumented)
hasSecurityClass(securityClass: SecurityClass_2): MaybeNotKnown<boolean>;
Expand Down Expand Up @@ -2144,6 +2217,14 @@ export interface ZWaveOptions extends ZWaveHostOptions {
serialAPIStarted: number;
};
userAgent?: Record<string, string>;
vendor?: {
manufacturerId: number;
productType: number;
productId: number;
hardwareVersion?: number;
installerIcon?: number;
userIcon?: number;
};
}


Expand All @@ -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

Expand Down

0 comments on commit 6cdedab

Please sign in to comment.