@nebulahome/integration-sdk 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/FILES.md +703 -0
- package/LICENSE +21 -0
- package/README.md +128 -2
- package/dist/chunks/node-dist.js +9253 -0
- package/dist/chunks/node-index.d.ts +2090 -0
- package/dist/chunks/node-project.js +545 -0
- package/dist/chunks/node-rolldown-runtime.js +24 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +3783 -0
- package/dist/index.d.ts +1427 -0
- package/dist/index.js +53 -0
- package/dist/schemas.d.ts +741 -0
- package/dist/schemas.js +53 -0
- package/dist/testing.d.ts +286 -0
- package/dist/testing.js +271 -0
- package/package.json +76 -3
- package/schemas/account.schema.json +595 -0
- package/schemas/discovery.schema.json +613 -0
- package/schemas/driver.schema.json +119 -0
- package/schemas/manifest.schema.json +557 -0
- package/schemas/profile.schema.json +1480 -0
- package/schemas/setup.schema.json +1166 -0
package/dist/schemas.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { d as accountDeclarationSchema, h as integrationSetupSchema, l as vendorDiscoverySchema, m as vendorManifestSchema, p as driverManifestSchema, u as integrationProfileSchema } from "./chunks/node-dist.js";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
//#region src/schemas.ts
|
|
4
|
+
/**
|
|
5
|
+
* The JSON Schemas of a bundle's files, for an editor: `src/manifest.json` and the others carry a
|
|
6
|
+
* `$schema` pointing at them, and are checked and completed as they are typed.
|
|
7
|
+
*
|
|
8
|
+
* Generated at build from the zod schemas `hub` reads the files with - the same ones `validate`
|
|
9
|
+
* runs - into `schemas/<file>.schema.json`. A JSON Schema says less than zod - a refinement, a
|
|
10
|
+
* check across files - so a file the editor accepts may still be refused by `validate`; never the
|
|
11
|
+
* other way round. The manifest's is the sources': without `version` and `sdk`, which the build
|
|
12
|
+
* writes, and without what the catalogue stamps.
|
|
13
|
+
*/
|
|
14
|
+
/** Each file's schema, by the name its JSON Schema is written under. */
|
|
15
|
+
const BUNDLE_FILE_SCHEMAS = {
|
|
16
|
+
manifest: vendorManifestSchema.omit({
|
|
17
|
+
version: true,
|
|
18
|
+
sdk: true,
|
|
19
|
+
integrity: true,
|
|
20
|
+
signature: true
|
|
21
|
+
}),
|
|
22
|
+
driver: driverManifestSchema,
|
|
23
|
+
setup: integrationSetupSchema,
|
|
24
|
+
profile: integrationProfileSchema,
|
|
25
|
+
discovery: vendorDiscoverySchema,
|
|
26
|
+
account: accountDeclarationSchema
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* One file's JSON Schema, with room for the `$schema` that points at it.
|
|
30
|
+
*
|
|
31
|
+
* @param name - The file.
|
|
32
|
+
* @returns The JSON Schema.
|
|
33
|
+
*/
|
|
34
|
+
function jsonSchemaOf(name) {
|
|
35
|
+
const json = z.toJSONSchema(BUNDLE_FILE_SCHEMAS[name], {
|
|
36
|
+
io: "input",
|
|
37
|
+
unrepresentable: "any"
|
|
38
|
+
});
|
|
39
|
+
const properties = json["properties"];
|
|
40
|
+
return {
|
|
41
|
+
...json,
|
|
42
|
+
title: `NebulaHome integration: ${name}.json`,
|
|
43
|
+
...properties !== null && typeof properties === "object" ? { properties: {
|
|
44
|
+
$schema: {
|
|
45
|
+
type: "string",
|
|
46
|
+
description: "The JSON Schema an editor checks the file with."
|
|
47
|
+
},
|
|
48
|
+
...properties
|
|
49
|
+
} } : {}
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
//#endregion
|
|
53
|
+
export { BUNDLE_FILE_SCHEMAS, jsonSchemaOf };
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
import { C as TransportSubscription, D as CapabilityState, E as CapabilityName, S as TransportRequest, T as JsonObject, _ as Claim, a as LoadedListenSource, b as ReportedState, c as SightingIdentity, d as ManagedSocketClose, f as ManagedSocketHeaders, g as UdpPeer, h as PlatformServices, i as LoadedDiscovery, m as ManagedUdpSocketOptions, n as LoadedAccount, o as LoadedVendor, p as ManagedSocketOptions, r as LoadedBundle, s as Association, t as BundleFailure, u as BundleSdk, v as DeviceDescriptor, w as EntityId, x as Discovered, y as Integration } from "./chunks/node-index.js";
|
|
2
|
+
//#region src/testing/fake-sdk.d.ts
|
|
3
|
+
/** The levels a bundle may log at. */
|
|
4
|
+
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
|
|
5
|
+
/** One line a bundle logged. */
|
|
6
|
+
type LogRecord = {
|
|
7
|
+
readonly level: LogLevel;
|
|
8
|
+
/** Its fields, a child logger's among them. */
|
|
9
|
+
readonly fields: Readonly<Record<string, unknown>>;
|
|
10
|
+
readonly message: string | undefined;
|
|
11
|
+
};
|
|
12
|
+
/** A datagram a bundle sent. */
|
|
13
|
+
type SentDatagram = {
|
|
14
|
+
readonly message: Buffer;
|
|
15
|
+
readonly port: number;
|
|
16
|
+
readonly address: string;
|
|
17
|
+
};
|
|
18
|
+
/** A UDP socket a bundle opened through the fake SDK. */
|
|
19
|
+
type FakeUdpSocket = {
|
|
20
|
+
/** What it was opened with: the port, the group, `onMessage`. */
|
|
21
|
+
readonly options: ManagedUdpSocketOptions;
|
|
22
|
+
readonly port: number;
|
|
23
|
+
/** What the bundle sent through it, in order. */
|
|
24
|
+
readonly sent: readonly SentDatagram[];
|
|
25
|
+
/** Whether the bundle, or the release, closed it. */
|
|
26
|
+
readonly isClosed: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* Hands the bundle a datagram, as if it arrived.
|
|
29
|
+
*
|
|
30
|
+
* @param message - What arrived.
|
|
31
|
+
* @param from - Who sent it; `192.0.2.1:4000` when not said.
|
|
32
|
+
*/
|
|
33
|
+
deliver: (message: Buffer | string, from?: UdpPeer) => void;
|
|
34
|
+
};
|
|
35
|
+
/** A WebSocket a bundle opened through the fake SDK. */
|
|
36
|
+
type FakeWebSocket = {
|
|
37
|
+
/** What it was opened with: the URL, the headers, the ping, the callbacks. */
|
|
38
|
+
readonly options: ManagedSocketOptions;
|
|
39
|
+
readonly url: string;
|
|
40
|
+
/** The headers of the last opening: a function's answer, once `open` has called it. */
|
|
41
|
+
readonly headers: ManagedSocketHeaders | undefined;
|
|
42
|
+
/** What the bundle sent through it, in order, across every connection. */
|
|
43
|
+
readonly sent: readonly string[];
|
|
44
|
+
/** The reasons the bundle reset it for, in order. */
|
|
45
|
+
readonly resets: readonly string[];
|
|
46
|
+
/** Whether a frame can be sent now. */
|
|
47
|
+
readonly isOpen: boolean;
|
|
48
|
+
/** Whether the bundle, or the release, closed it for good. */
|
|
49
|
+
readonly isClosed: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* Opens it - or opens it again after a drop or a reset, as the hub's reconnection would: reads
|
|
52
|
+
* the headers, a function's answer awaited, then calls `onOpen`.
|
|
53
|
+
*
|
|
54
|
+
* @throws {Error} When it is open already, or closed for good.
|
|
55
|
+
*/
|
|
56
|
+
open: () => Promise<void>;
|
|
57
|
+
/**
|
|
58
|
+
* Hands the bundle a text frame, as if it arrived.
|
|
59
|
+
*
|
|
60
|
+
* @throws {Error} When it is not open.
|
|
61
|
+
*/
|
|
62
|
+
deliver: (text: string) => void;
|
|
63
|
+
/**
|
|
64
|
+
* Ends the connection - or refuses an attempt to make one - as the network or the server
|
|
65
|
+
* would, and tells the bundle: `drop('connection not accepted (HTTP 401 Unauthorized)',
|
|
66
|
+
* { code: 1006, status: 401 })` is a handshake the server turned down.
|
|
67
|
+
*
|
|
68
|
+
* @throws {Error} When it is closed for good.
|
|
69
|
+
*/
|
|
70
|
+
drop: (reason: string, details?: ManagedSocketClose) => void;
|
|
71
|
+
};
|
|
72
|
+
/** What a test builds a fake SDK with. */
|
|
73
|
+
type FakeSdkOptions = {
|
|
74
|
+
/** What the platform runs that the bundle may use: no broker when not said. */
|
|
75
|
+
readonly platform?: PlatformServices;
|
|
76
|
+
/** Pieces of the SDK the test supplies itself: `openMqtt`, `openRtsp`, `codecs`… */
|
|
77
|
+
readonly overrides?: Partial<Omit<BundleSdk, 'version' | 'z'>>;
|
|
78
|
+
};
|
|
79
|
+
/** A fake SDK, and what the bundle did with it. */
|
|
80
|
+
type FakeSdk = {
|
|
81
|
+
readonly sdk: BundleSdk;
|
|
82
|
+
/** What the bundle logged, in order. */
|
|
83
|
+
readonly logs: readonly LogRecord[];
|
|
84
|
+
/** The UDP sockets the bundle opened, in order. */
|
|
85
|
+
readonly udpSockets: readonly FakeUdpSocket[];
|
|
86
|
+
/** The WebSockets the bundle opened, in order; none is open until the test opens it. */
|
|
87
|
+
readonly webSockets: readonly FakeWebSocket[];
|
|
88
|
+
/**
|
|
89
|
+
* Closes every socket the bundle left open, as the hub does when it lets go of a vendor.
|
|
90
|
+
*
|
|
91
|
+
* @returns Once they are closed.
|
|
92
|
+
*/
|
|
93
|
+
release: () => Promise<void>;
|
|
94
|
+
};
|
|
95
|
+
/**
|
|
96
|
+
* Builds a fake SDK.
|
|
97
|
+
*
|
|
98
|
+
* @param options - The platform's services, and the pieces the test supplies.
|
|
99
|
+
* @returns The SDK, and what the bundle does with it.
|
|
100
|
+
*/
|
|
101
|
+
export declare function createFakeSdk(options?: FakeSdkOptions): FakeSdk;
|
|
102
|
+
//#endregion
|
|
103
|
+
//#region src/testing/harness.d.ts
|
|
104
|
+
/** What the harness is set up with. */
|
|
105
|
+
type DriverHarnessOptions = {
|
|
106
|
+
/** The instance's options, as the owner set them; checked against the driver's schema. */
|
|
107
|
+
readonly options?: JsonObject;
|
|
108
|
+
/** The device's id, which its entities' identifiers are made from: `device` when not said. */
|
|
109
|
+
readonly deviceId?: string;
|
|
110
|
+
/** The connection a message arrives on, as the transport would key it. */
|
|
111
|
+
readonly connectionKey?: string;
|
|
112
|
+
};
|
|
113
|
+
/** A device added through the harness. */
|
|
114
|
+
type HarnessDevice = {
|
|
115
|
+
readonly claim: Claim;
|
|
116
|
+
/** What the driver said the device is. */
|
|
117
|
+
readonly device: DeviceDescriptor;
|
|
118
|
+
/** Each entity's identifier, by its descriptor's `objectId` - `''` for a device's only one. */
|
|
119
|
+
readonly entities: ReadonlyMap<string, EntityId>;
|
|
120
|
+
/** The identifiers, in the descriptor's order. */
|
|
121
|
+
readonly entityIds: readonly EntityId[];
|
|
122
|
+
};
|
|
123
|
+
/** A driver, driven. */
|
|
124
|
+
type DriverHarness = {
|
|
125
|
+
readonly integration: Integration;
|
|
126
|
+
/** The instance's options, checked. */
|
|
127
|
+
readonly options: JsonObject;
|
|
128
|
+
/**
|
|
129
|
+
* Asks the driver whether a device is its own.
|
|
130
|
+
*
|
|
131
|
+
* @param discovered - What a scan or a probe found.
|
|
132
|
+
* @returns The claim, or null.
|
|
133
|
+
*/
|
|
134
|
+
claim: (discovered: Discovered) => Claim | null;
|
|
135
|
+
/**
|
|
136
|
+
* Claims a device and describes it: what adding it does.
|
|
137
|
+
*
|
|
138
|
+
* @param discovered - What a scan or a probe found.
|
|
139
|
+
* @returns The device, its entities named.
|
|
140
|
+
* @throws {Error} When the driver does not claim it.
|
|
141
|
+
*/
|
|
142
|
+
add: (discovered: Discovered) => HarnessDevice;
|
|
143
|
+
/**
|
|
144
|
+
* What the transport must carry for the devices added.
|
|
145
|
+
*
|
|
146
|
+
* @returns The subscriptions.
|
|
147
|
+
*/
|
|
148
|
+
subscriptions: () => TransportSubscription[];
|
|
149
|
+
/**
|
|
150
|
+
* Hands the driver a message from a device added, as the transport would.
|
|
151
|
+
*
|
|
152
|
+
* @param payload - What arrived.
|
|
153
|
+
* @param deviceKey - Which device; the one added last when not said.
|
|
154
|
+
* @returns The reports, each entity's last state kept.
|
|
155
|
+
*/
|
|
156
|
+
receive: (payload: unknown, deviceKey?: string) => ReportedState[];
|
|
157
|
+
/**
|
|
158
|
+
* Turns a command into the request the transport would perform.
|
|
159
|
+
*
|
|
160
|
+
* @param entityId - The entity.
|
|
161
|
+
* @param capability - The capability.
|
|
162
|
+
* @param command - The command, as `core` validated it.
|
|
163
|
+
* @returns The request.
|
|
164
|
+
*/
|
|
165
|
+
command: (entityId: string, capability: CapabilityName, command?: JsonObject) => TransportRequest;
|
|
166
|
+
/**
|
|
167
|
+
* The last state an entity reported.
|
|
168
|
+
*
|
|
169
|
+
* @param entityId - The entity.
|
|
170
|
+
* @returns Its state, or undefined before it reported.
|
|
171
|
+
*/
|
|
172
|
+
lastState: (entityId: string) => CapabilityState | undefined;
|
|
173
|
+
};
|
|
174
|
+
/**
|
|
175
|
+
* Sets a driver up to be driven.
|
|
176
|
+
*
|
|
177
|
+
* @param driver - A driver of an integration loaded with `loadIntegration`, or an integration.
|
|
178
|
+
* @param settings - The instance's options, the device's id, the connection.
|
|
179
|
+
* @returns The harness.
|
|
180
|
+
*/
|
|
181
|
+
export declare function driverHarness(driver: LoadedBundle | Integration, settings?: DriverHarnessOptions): DriverHarness;
|
|
182
|
+
//#endregion
|
|
183
|
+
//#region src/testing/identify.d.ts
|
|
184
|
+
/** What discovery made of what it heard. */
|
|
185
|
+
type Identification = {
|
|
186
|
+
/** Whether the announcement is the vendor's: every `match` condition holds. */
|
|
187
|
+
readonly matches: boolean;
|
|
188
|
+
/** Who the device says it is, by the paths of `identity`. */
|
|
189
|
+
readonly identity: SightingIdentity;
|
|
190
|
+
/** The driver and the model it names; null when no driver takes the device. */
|
|
191
|
+
readonly association: Association | null;
|
|
192
|
+
};
|
|
193
|
+
/**
|
|
194
|
+
* Says what discovery makes of a device heard.
|
|
195
|
+
*
|
|
196
|
+
* @param vendor - The vendor, loaded with `loadIntegration`.
|
|
197
|
+
* @param heard - What was heard: the announcement `match` reads, and the probe's answer that
|
|
198
|
+
* `identity` and the drivers' claims read - the announcement itself for a vendor without a probe.
|
|
199
|
+
* @param heard.announcement - The announcement: an mDNS record, what a listener reported.
|
|
200
|
+
* @param heard.probed - The probe's answer, for a vendor that probes; the announcement when not
|
|
201
|
+
* said.
|
|
202
|
+
* @param heard.deviceKey - How the device is reached, for the drivers' claims: `192.0.2.10` when
|
|
203
|
+
* not said.
|
|
204
|
+
* @returns What discovery makes of it.
|
|
205
|
+
* @throws {Error} When the vendor has no discovery that loaded.
|
|
206
|
+
*/
|
|
207
|
+
export declare function identify(vendor: LoadedVendor, heard: {
|
|
208
|
+
readonly announcement: unknown;
|
|
209
|
+
readonly probed?: unknown;
|
|
210
|
+
readonly deviceKey?: string;
|
|
211
|
+
}): Identification;
|
|
212
|
+
/** What discovery makes of one of the house's Matter devices. */
|
|
213
|
+
type MatterIdentification = {
|
|
214
|
+
/** Whether the vendor's `matter` rules take it: every condition holds. */
|
|
215
|
+
readonly matches: boolean;
|
|
216
|
+
/** The Matter driver and the model it names; null when no driver takes the device. */
|
|
217
|
+
readonly association: Association | null;
|
|
218
|
+
};
|
|
219
|
+
/**
|
|
220
|
+
* Says what discovery makes of one of the house's Matter devices, by the vendor's `matter` rules.
|
|
221
|
+
* A device that another vendor's rules take too is the platform's own instead, which one vendor's
|
|
222
|
+
* test cannot see.
|
|
223
|
+
*
|
|
224
|
+
* @param vendor - The vendor, loaded with `loadIntegration`.
|
|
225
|
+
* @param identity - Who the device says it is: `vendorId`, `productId`, `vendorName`,
|
|
226
|
+
* `isBridged` and the rest of the fields FILES.md lists; a field left out is one it does not say.
|
|
227
|
+
* @returns What discovery makes of it.
|
|
228
|
+
* @throws {Error} When the vendor has no discovery that loaded.
|
|
229
|
+
*/
|
|
230
|
+
export declare function identifyMatter(vendor: LoadedVendor, identity: Readonly<Record<string, unknown>>): MatterIdentification;
|
|
231
|
+
//#endregion
|
|
232
|
+
//#region src/testing/load.d.ts
|
|
233
|
+
/** What loading takes. */
|
|
234
|
+
type LoadIntegrationOptions = {
|
|
235
|
+
/** The repository's folder; the working directory when not said. */
|
|
236
|
+
readonly root?: string;
|
|
237
|
+
/** Which tree: the sources in `src/` (the default), or the build in `dist/`. */
|
|
238
|
+
readonly from?: 'source' | 'build';
|
|
239
|
+
/** The fake SDK the code is handed, or what to build one with; a new one when not said. */
|
|
240
|
+
readonly sdk?: FakeSdk | FakeSdkOptions;
|
|
241
|
+
};
|
|
242
|
+
/** An integration, loaded. */
|
|
243
|
+
type LoadedIntegration = {
|
|
244
|
+
/** The vendor, as `hub` holds it: its drivers, its transports, its discovery. */
|
|
245
|
+
readonly vendor: LoadedVendor;
|
|
246
|
+
/** The drivers, and the `discovery.json`, that did not load: `hub` loads the rest without them. */
|
|
247
|
+
readonly failures: readonly BundleFailure[];
|
|
248
|
+
/** The SDK its code was handed, and what the code did with it. */
|
|
249
|
+
readonly fake: FakeSdk;
|
|
250
|
+
/**
|
|
251
|
+
* One driver.
|
|
252
|
+
*
|
|
253
|
+
* @param driverId - Its folder's name.
|
|
254
|
+
* @returns The driver.
|
|
255
|
+
* @throws {Error} When it is not one that loaded.
|
|
256
|
+
*/
|
|
257
|
+
driver: (driverId: string) => LoadedBundle;
|
|
258
|
+
/**
|
|
259
|
+
* Lets go of what the integration's code opened, as `hub` does when it lets go of a vendor.
|
|
260
|
+
*
|
|
261
|
+
* @returns Once it is let go of.
|
|
262
|
+
*/
|
|
263
|
+
release: () => Promise<void>;
|
|
264
|
+
};
|
|
265
|
+
/**
|
|
266
|
+
* Loads an integration as `hub` would.
|
|
267
|
+
*
|
|
268
|
+
* @param options - The repository, which tree, and the fake SDK.
|
|
269
|
+
* @returns The vendor and its drivers, loaded.
|
|
270
|
+
* @throws {IntegrationError} When the vendor does not load at all, with why.
|
|
271
|
+
*/
|
|
272
|
+
export declare function loadIntegration(options?: LoadIntegrationOptions): Promise<LoadedIntegration>;
|
|
273
|
+
//#endregion
|
|
274
|
+
//#region src/project.d.ts
|
|
275
|
+
/** Every problem found, each a sentence: what the command prints, one per line. */
|
|
276
|
+
export declare class IntegrationError extends Error {
|
|
277
|
+
readonly problems: readonly string[];
|
|
278
|
+
/**
|
|
279
|
+
* Makes the error.
|
|
280
|
+
*
|
|
281
|
+
* @param problems - Each problem, in a sentence.
|
|
282
|
+
*/
|
|
283
|
+
constructor(problems: readonly string[]);
|
|
284
|
+
}
|
|
285
|
+
//#endregion
|
|
286
|
+
export type { Association, BundleFailure, DriverHarness, DriverHarnessOptions, FakeSdk, FakeSdkOptions, FakeUdpSocket, FakeWebSocket, HarnessDevice, Identification, LoadIntegrationOptions, LoadedAccount, LoadedBundle, LoadedDiscovery, LoadedIntegration, LoadedListenSource, LoadedVendor, LogLevel, LogRecord, MatterIdentification, SentDatagram, SightingIdentity };
|
package/dist/testing.js
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
import { a as associateModel, c as matchesMatter, g as composeEntityId, i as associateMatter, n as readVendorDirectory, o as identifySighting, s as matchesAnnouncement, t as instantiateVendor } from "./chunks/node-dist.js";
|
|
2
|
+
import { a as sourceModule, i as runtimeVersion, o as createFakeSdk, r as readProject, t as IntegrationError } from "./chunks/node-project.js";
|
|
3
|
+
import { pathToFileURL } from "node:url";
|
|
4
|
+
//#region src/testing/harness.ts
|
|
5
|
+
/**
|
|
6
|
+
* A driver under test, driven the way `hub` drives one: a device found is claimed and described,
|
|
7
|
+
* its entities get the identifiers `hub` would give them, what it sends becomes state - the last
|
|
8
|
+
* state of each entity kept, as `hub` keeps it for a command that needs it - and a command
|
|
9
|
+
* becomes the request the transport would perform. No transport and no bus: an integration is
|
|
10
|
+
* pure, so what it does with what it is handed is all there is to test.
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* const harness = driverHarness(integration.driver('panels'));
|
|
14
|
+
* const device = harness.add({ deviceKey: '192.168.1.40', payload: statusJson });
|
|
15
|
+
* harness.receive(statusJson); // → [{ entityId: 'light.device', state: { on_off: { isOn: true } } }]
|
|
16
|
+
* harness.command(device.entityIds[0], 'on_off', { command: 'turn_on' });
|
|
17
|
+
* ```
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* Sets a driver up to be driven.
|
|
21
|
+
*
|
|
22
|
+
* @param driver - A driver of an integration loaded with `loadIntegration`, or an integration.
|
|
23
|
+
* @param settings - The instance's options, the device's id, the connection.
|
|
24
|
+
* @returns The harness.
|
|
25
|
+
*/
|
|
26
|
+
function driverHarness(driver, settings = {}) {
|
|
27
|
+
const integration = "integration" in driver ? driver.integration : driver;
|
|
28
|
+
const options = integration.optionsSchema.parse(settings.options ?? {});
|
|
29
|
+
const deviceId = settings.deviceId ?? "device";
|
|
30
|
+
const connectionKey = settings.connectionKey ?? "test";
|
|
31
|
+
const devices = /* @__PURE__ */ new Map();
|
|
32
|
+
const lastStates = /* @__PURE__ */ new Map();
|
|
33
|
+
let lastAdded;
|
|
34
|
+
/**
|
|
35
|
+
* What a mapper of a device is handed.
|
|
36
|
+
*
|
|
37
|
+
* @param device - The device.
|
|
38
|
+
* @returns The context.
|
|
39
|
+
*/
|
|
40
|
+
const contextFor = (device) => ({
|
|
41
|
+
options,
|
|
42
|
+
claim: device.claim,
|
|
43
|
+
entities: device.entities,
|
|
44
|
+
/**
|
|
45
|
+
* The last state an entity reported.
|
|
46
|
+
*
|
|
47
|
+
* @param entityId - The entity.
|
|
48
|
+
* @returns Its state.
|
|
49
|
+
*/
|
|
50
|
+
lastState: (entityId) => lastStates.get(entityId)
|
|
51
|
+
});
|
|
52
|
+
/**
|
|
53
|
+
* The device added with a key.
|
|
54
|
+
*
|
|
55
|
+
* @param deviceKey - The key; the one added last when not said.
|
|
56
|
+
* @returns The device.
|
|
57
|
+
* @throws {Error} When none was added with it.
|
|
58
|
+
*/
|
|
59
|
+
const deviceOf = (deviceKey) => {
|
|
60
|
+
const device = devices.get(deviceKey ?? lastAdded ?? "");
|
|
61
|
+
if (device === void 0) throw new Error(deviceKey === void 0 ? "No device was added: call add() first" : `No device was added as ${deviceKey}`);
|
|
62
|
+
return device;
|
|
63
|
+
};
|
|
64
|
+
return {
|
|
65
|
+
integration,
|
|
66
|
+
options,
|
|
67
|
+
/**
|
|
68
|
+
* Asks the driver whether a device is its own.
|
|
69
|
+
*
|
|
70
|
+
* @param discovered - What was found.
|
|
71
|
+
* @returns The claim, or null.
|
|
72
|
+
*/
|
|
73
|
+
claim: (discovered) => integration.claim(discovered, options),
|
|
74
|
+
/**
|
|
75
|
+
* Claims a device and describes it.
|
|
76
|
+
*
|
|
77
|
+
* @param discovered - What was found.
|
|
78
|
+
* @returns The device.
|
|
79
|
+
* @throws {Error} When the driver does not claim it.
|
|
80
|
+
*/
|
|
81
|
+
add: (discovered) => {
|
|
82
|
+
const claim = integration.claim(discovered, options);
|
|
83
|
+
if (claim === null) throw new Error(`${integration.id} does not claim ${discovered.deviceKey}`);
|
|
84
|
+
const device = integration.describe(claim, options);
|
|
85
|
+
const entities = device.entities.map((entity) => ({
|
|
86
|
+
objectId: entity.objectId ?? "",
|
|
87
|
+
entityId: composeEntityId(entity.domain, deviceId, entity.objectId)
|
|
88
|
+
}));
|
|
89
|
+
const added = {
|
|
90
|
+
claim,
|
|
91
|
+
device,
|
|
92
|
+
entities: new Map(entities.map((entity) => [entity.objectId, entity.entityId])),
|
|
93
|
+
entityIds: entities.map((entity) => entity.entityId)
|
|
94
|
+
};
|
|
95
|
+
devices.set(claim.deviceKey, added);
|
|
96
|
+
lastAdded = claim.deviceKey;
|
|
97
|
+
return added;
|
|
98
|
+
},
|
|
99
|
+
/**
|
|
100
|
+
* What the transport must carry.
|
|
101
|
+
*
|
|
102
|
+
* @returns The subscriptions.
|
|
103
|
+
*/
|
|
104
|
+
subscriptions: () => integration.subscriptions([...devices.values()].map((device) => device.claim), options),
|
|
105
|
+
/**
|
|
106
|
+
* Hands the driver a message.
|
|
107
|
+
*
|
|
108
|
+
* @param payload - What arrived.
|
|
109
|
+
* @param deviceKey - Which device.
|
|
110
|
+
* @returns The reports.
|
|
111
|
+
*/
|
|
112
|
+
receive: (payload, deviceKey) => {
|
|
113
|
+
const device = deviceOf(deviceKey);
|
|
114
|
+
const reports = integration.toState({
|
|
115
|
+
connectionKey,
|
|
116
|
+
deviceKey: device.claim.deviceKey,
|
|
117
|
+
payload
|
|
118
|
+
}, contextFor(device));
|
|
119
|
+
for (const report of reports) lastStates.set(report.entityId, report.state);
|
|
120
|
+
return reports;
|
|
121
|
+
},
|
|
122
|
+
/**
|
|
123
|
+
* Turns a command into a request.
|
|
124
|
+
*
|
|
125
|
+
* @param entityId - The entity.
|
|
126
|
+
* @param capability - The capability.
|
|
127
|
+
* @param command - The command.
|
|
128
|
+
* @returns The request.
|
|
129
|
+
* @throws {Error} When no device added has the entity.
|
|
130
|
+
*/
|
|
131
|
+
command: (entityId, capability, command = {}) => {
|
|
132
|
+
const device = [...devices.values()].find((candidate) => candidate.entityIds.includes(entityId));
|
|
133
|
+
if (device === void 0) throw new Error(`No device added has the entity ${entityId}`);
|
|
134
|
+
return integration.toCommand({
|
|
135
|
+
entityId,
|
|
136
|
+
capability,
|
|
137
|
+
command
|
|
138
|
+
}, contextFor(device));
|
|
139
|
+
},
|
|
140
|
+
/**
|
|
141
|
+
* The last state an entity reported.
|
|
142
|
+
*
|
|
143
|
+
* @param entityId - The entity.
|
|
144
|
+
* @returns Its state.
|
|
145
|
+
*/
|
|
146
|
+
lastState: (entityId) => lastStates.get(entityId)
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
//#endregion
|
|
150
|
+
//#region src/testing/identify.ts
|
|
151
|
+
/**
|
|
152
|
+
* Says what discovery makes of a device heard.
|
|
153
|
+
*
|
|
154
|
+
* @param vendor - The vendor, loaded with `loadIntegration`.
|
|
155
|
+
* @param heard - What was heard: the announcement `match` reads, and the probe's answer that
|
|
156
|
+
* `identity` and the drivers' claims read - the announcement itself for a vendor without a probe.
|
|
157
|
+
* @param heard.announcement - The announcement: an mDNS record, what a listener reported.
|
|
158
|
+
* @param heard.probed - The probe's answer, for a vendor that probes; the announcement when not
|
|
159
|
+
* said.
|
|
160
|
+
* @param heard.deviceKey - How the device is reached, for the drivers' claims: `192.0.2.10` when
|
|
161
|
+
* not said.
|
|
162
|
+
* @returns What discovery makes of it.
|
|
163
|
+
* @throws {Error} When the vendor has no discovery that loaded.
|
|
164
|
+
*/
|
|
165
|
+
function identify(vendor, heard) {
|
|
166
|
+
const plan = vendor.discovery?.plan;
|
|
167
|
+
if (plan === void 0) throw new Error(`${vendor.manifest.id} has no discovery.json that loaded`);
|
|
168
|
+
const answer = plan.discovery.probe === void 0 ? heard.announcement : heard.probed ?? heard.announcement;
|
|
169
|
+
const identity = identifySighting(plan, answer);
|
|
170
|
+
const discovered = {
|
|
171
|
+
deviceKey: heard.deviceKey ?? "192.0.2.10",
|
|
172
|
+
payload: answer
|
|
173
|
+
};
|
|
174
|
+
const claims = plan.discovery.probe === void 0 ? void 0 : (driverId) => {
|
|
175
|
+
return vendor.drivers.find((candidate) => candidate.driverId === driverId)?.integration.claim(discovered, {}) != null;
|
|
176
|
+
};
|
|
177
|
+
return {
|
|
178
|
+
matches: matchesAnnouncement(plan, heard.announcement),
|
|
179
|
+
identity,
|
|
180
|
+
association: associateModel(plan, identity.modelCode, claims)
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Says what discovery makes of one of the house's Matter devices, by the vendor's `matter` rules.
|
|
185
|
+
* A device that another vendor's rules take too is the platform's own instead, which one vendor's
|
|
186
|
+
* test cannot see.
|
|
187
|
+
*
|
|
188
|
+
* @param vendor - The vendor, loaded with `loadIntegration`.
|
|
189
|
+
* @param identity - Who the device says it is: `vendorId`, `productId`, `vendorName`,
|
|
190
|
+
* `isBridged` and the rest of the fields FILES.md lists; a field left out is one it does not say.
|
|
191
|
+
* @returns What discovery makes of it.
|
|
192
|
+
* @throws {Error} When the vendor has no discovery that loaded.
|
|
193
|
+
*/
|
|
194
|
+
function identifyMatter(vendor, identity) {
|
|
195
|
+
const plan = vendor.discovery?.plan;
|
|
196
|
+
if (plan === void 0) throw new Error(`${vendor.manifest.id} has no discovery.json that loaded`);
|
|
197
|
+
const matches = matchesMatter(plan, identity);
|
|
198
|
+
return {
|
|
199
|
+
matches,
|
|
200
|
+
association: matches ? associateMatter(plan, identity) : null
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
//#endregion
|
|
204
|
+
//#region src/testing/load.ts
|
|
205
|
+
/**
|
|
206
|
+
* Loading an integration in a test, the way `hub` loads it: every file read and checked by the
|
|
207
|
+
* hub's own loader, every module imported and handed an SDK - a fake one, whose sockets and logs
|
|
208
|
+
* the test reads. The sources are loaded as they stand - a module in TypeScript is imported as
|
|
209
|
+
* the test runner imports TypeScript - or the build in `dist/`, to test what is released.
|
|
210
|
+
*/
|
|
211
|
+
/**
|
|
212
|
+
* Loads an integration as `hub` would.
|
|
213
|
+
*
|
|
214
|
+
* @param options - The repository, which tree, and the fake SDK.
|
|
215
|
+
* @returns The vendor and its drivers, loaded.
|
|
216
|
+
* @throws {IntegrationError} When the vendor does not load at all, with why.
|
|
217
|
+
*/
|
|
218
|
+
async function loadIntegration(options = {}) {
|
|
219
|
+
const project = await readProject(options.root ?? process.cwd());
|
|
220
|
+
const isBuild = options.from === "build";
|
|
221
|
+
const fake = options.sdk !== void 0 && "sdk" in options.sdk ? options.sdk : createFakeSdk(options.sdk);
|
|
222
|
+
let found;
|
|
223
|
+
try {
|
|
224
|
+
const declaration = await readVendorDirectory(isBuild ? project.outputDirectory : project.sourceDirectory, isBuild ? {
|
|
225
|
+
expectedId: project.vendorId,
|
|
226
|
+
runtimeVersion: runtimeVersion()
|
|
227
|
+
} : {
|
|
228
|
+
expectedId: project.vendorId,
|
|
229
|
+
stamp: project.stamp,
|
|
230
|
+
runtimeVersion: runtimeVersion(),
|
|
231
|
+
resolveModule: sourceModule
|
|
232
|
+
});
|
|
233
|
+
found = await instantiateVendor(declaration, {
|
|
234
|
+
sdk: fake.sdk,
|
|
235
|
+
release: fake.release,
|
|
236
|
+
origin: "development",
|
|
237
|
+
/**
|
|
238
|
+
* Imports a module, as the test runner imports one: TypeScript too.
|
|
239
|
+
*
|
|
240
|
+
* @param file - The module.
|
|
241
|
+
* @returns The module.
|
|
242
|
+
*/
|
|
243
|
+
importModule: async (file) => import(pathToFileURL(file).href)
|
|
244
|
+
});
|
|
245
|
+
} catch (error) {
|
|
246
|
+
await fake.release();
|
|
247
|
+
throw new IntegrationError([error instanceof Error ? error.message : String(error)]);
|
|
248
|
+
}
|
|
249
|
+
const { vendor, failures } = found;
|
|
250
|
+
if (vendor === null) throw new IntegrationError(failures.map((failure) => failure.message));
|
|
251
|
+
return {
|
|
252
|
+
vendor,
|
|
253
|
+
failures,
|
|
254
|
+
fake,
|
|
255
|
+
/**
|
|
256
|
+
* One driver.
|
|
257
|
+
*
|
|
258
|
+
* @param driverId - Its folder's name.
|
|
259
|
+
* @returns The driver.
|
|
260
|
+
* @throws {Error} When it did not load.
|
|
261
|
+
*/
|
|
262
|
+
driver: (driverId) => {
|
|
263
|
+
const driver = vendor.drivers.find((candidate) => candidate.driverId === driverId);
|
|
264
|
+
if (driver === void 0) throw new Error(`${vendor.manifest.id} has no driver ${driverId} that loaded; it has ${vendor.drivers.map((candidate) => candidate.driverId).join(", ")}`);
|
|
265
|
+
return driver;
|
|
266
|
+
},
|
|
267
|
+
release: vendor.release
|
|
268
|
+
};
|
|
269
|
+
}
|
|
270
|
+
//#endregion
|
|
271
|
+
export { IntegrationError, createFakeSdk, driverHarness, identify, identifyMatter, loadIntegration };
|
package/package.json
CHANGED
|
@@ -1,6 +1,79 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nebulahome/integration-sdk",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Write a NebulaHome integration: check it, build it, test it and release it for the platform.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"sideEffects": false,
|
|
8
|
+
"keywords": [
|
|
9
|
+
"nebulahome",
|
|
10
|
+
"smart-home",
|
|
11
|
+
"home-automation",
|
|
12
|
+
"integration",
|
|
13
|
+
"sdk"
|
|
14
|
+
],
|
|
15
|
+
"homepage": "https://github.com/nebulahome/platform/tree/main/packages/integration-sdk#readme",
|
|
16
|
+
"bugs": "https://github.com/nebulahome/platform/issues",
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/nebulahome/platform.git",
|
|
20
|
+
"directory": "packages/integration-sdk"
|
|
21
|
+
},
|
|
22
|
+
"exports": {
|
|
23
|
+
".": {
|
|
24
|
+
"types": "./dist/index.d.ts",
|
|
25
|
+
"default": "./dist/index.js"
|
|
26
|
+
},
|
|
27
|
+
"./testing": {
|
|
28
|
+
"types": "./dist/testing.d.ts",
|
|
29
|
+
"default": "./dist/testing.js"
|
|
30
|
+
},
|
|
31
|
+
"./schemas/*": "./schemas/*",
|
|
32
|
+
"./package.json": "./package.json"
|
|
33
|
+
},
|
|
34
|
+
"bin": {
|
|
35
|
+
"nebulahome-integration": "./dist/cli.js"
|
|
36
|
+
},
|
|
37
|
+
"files": [
|
|
38
|
+
"dist",
|
|
39
|
+
"schemas",
|
|
40
|
+
"README.md",
|
|
41
|
+
"FILES.md",
|
|
42
|
+
"CHANGELOG.md",
|
|
43
|
+
"LICENSE"
|
|
44
|
+
],
|
|
45
|
+
"engines": {
|
|
46
|
+
"node": ">=22"
|
|
47
|
+
},
|
|
48
|
+
"publishConfig": {
|
|
49
|
+
"access": "public"
|
|
50
|
+
},
|
|
51
|
+
"dependencies": {
|
|
52
|
+
"rolldown": "^1.2.7",
|
|
53
|
+
"zod": "^4.5.4"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
57
|
+
"@types/node": "^22.20.1",
|
|
58
|
+
"@types/semver": "^7.7.1",
|
|
59
|
+
"publint": "^0.3.25",
|
|
60
|
+
"semver": "^7.8.5",
|
|
61
|
+
"tar": "^7.5.22",
|
|
62
|
+
"tsdown": "^0.23.0",
|
|
63
|
+
"typescript": "^6.0.3",
|
|
64
|
+
"vitest": "^4.1.11",
|
|
65
|
+
"@nebulahome/contracts": "0.0.0",
|
|
66
|
+
"@nebulahome/tsconfig": "0.0.0",
|
|
67
|
+
"@nebulahome/package-runtime": "0.0.0",
|
|
68
|
+
"@nebulahome/eslint-config": "0.0.0"
|
|
69
|
+
},
|
|
70
|
+
"scripts": {
|
|
71
|
+
"build": "tsdown && node scripts/build-schemas.js",
|
|
72
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
73
|
+
"lint": "eslint .",
|
|
74
|
+
"test": "vitest run",
|
|
75
|
+
"api:report": "node scripts/api-report.js",
|
|
76
|
+
"api:check": "node scripts/api-report.js --check",
|
|
77
|
+
"check:package": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints ./schemas/*"
|
|
78
|
+
}
|
|
6
79
|
}
|