@nebulahome/integration-sdk 0.0.0-stage → 1.0.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.
@@ -0,0 +1,1427 @@
1
+ import { z } from "zod";
2
+ //#region ../contracts/dist/capabilities.d.ts
3
+ /** Every capability an entity may declare. */
4
+ declare const CAPABILITIES: readonly ["on_off", "level", "color_hs", "color_temp", "cover", "lock", "thermostat", "sensor_numeric", "sensor_binary", "sensor_text", "media_player", "camera", "button", "update", "lawn_mower", "select", "number", "vacuum", "image", "custom"];
5
+ /** The name of a single capability. */
6
+ type CapabilityName = (typeof CAPABILITIES)[number];
7
+ /**
8
+ * The composite state of an entity: one entry per capability it declares.
9
+ *
10
+ * An entity is rarely one capability. A dimmable colour bulb is `on_off` plus `level` plus
11
+ * `color_hs`, and its state carries all three, which is why this is a partial record rather
12
+ * than a discriminated union - a union could only ever describe one of them at a time.
13
+ */
14
+ declare const capabilityStateSchema: z.ZodObject<{
15
+ on_off: z.ZodOptional<z.ZodObject<{
16
+ isOn: z.ZodBoolean;
17
+ }, z.core.$strip>>;
18
+ level: z.ZodOptional<z.ZodObject<{
19
+ level: z.ZodNumber;
20
+ }, z.core.$strip>>;
21
+ color_hs: z.ZodOptional<z.ZodObject<{
22
+ hue: z.ZodNumber;
23
+ saturation: z.ZodNumber;
24
+ }, z.core.$strip>>;
25
+ color_temp: z.ZodOptional<z.ZodObject<{
26
+ mireds: z.ZodInt;
27
+ }, z.core.$strip>>;
28
+ cover: z.ZodOptional<z.ZodObject<{
29
+ position: z.ZodNumber;
30
+ tilt: z.ZodOptional<z.ZodNumber>;
31
+ motion: z.ZodEnum<{
32
+ opening: "opening";
33
+ closing: "closing";
34
+ stopped: "stopped";
35
+ }>;
36
+ }, z.core.$strip>>;
37
+ lock: z.ZodOptional<z.ZodObject<{
38
+ lockState: z.ZodEnum<{
39
+ locked: "locked";
40
+ unlocked: "unlocked";
41
+ jammed: "jammed";
42
+ }>;
43
+ }, z.core.$strip>>;
44
+ thermostat: z.ZodOptional<z.ZodObject<{
45
+ currentTemperature: z.ZodNumber;
46
+ targetTemperature: z.ZodNumber;
47
+ mode: z.ZodEnum<{
48
+ off: "off";
49
+ heat: "heat";
50
+ cool: "cool";
51
+ auto: "auto";
52
+ fan_only: "fan_only";
53
+ dry: "dry";
54
+ }>;
55
+ action: z.ZodEnum<{
56
+ off: "off";
57
+ idle: "idle";
58
+ heating: "heating";
59
+ cooling: "cooling";
60
+ drying: "drying";
61
+ fan: "fan";
62
+ }>;
63
+ humidity: z.ZodOptional<z.ZodNumber>;
64
+ }, z.core.$strip>>;
65
+ sensor_numeric: z.ZodOptional<z.ZodObject<{
66
+ value: z.ZodNumber;
67
+ }, z.core.$strip>>;
68
+ sensor_binary: z.ZodOptional<z.ZodObject<{
69
+ isOn: z.ZodBoolean;
70
+ }, z.core.$strip>>;
71
+ sensor_text: z.ZodOptional<z.ZodObject<{
72
+ value: z.ZodString;
73
+ }, z.core.$strip>>;
74
+ media_player: z.ZodOptional<z.ZodObject<{
75
+ playback: z.ZodEnum<{
76
+ stopped: "stopped";
77
+ idle: "idle";
78
+ playing: "playing";
79
+ paused: "paused";
80
+ buffering: "buffering";
81
+ }>;
82
+ volume: z.ZodNumber;
83
+ isMuted: z.ZodBoolean;
84
+ source: z.ZodOptional<z.ZodString>;
85
+ mediaTitle: z.ZodOptional<z.ZodString>;
86
+ mediaArtist: z.ZodOptional<z.ZodString>;
87
+ mediaDurationSeconds: z.ZodOptional<z.ZodNumber>;
88
+ mediaPositionSeconds: z.ZodOptional<z.ZodNumber>;
89
+ }, z.core.$strip>>;
90
+ camera: z.ZodOptional<z.ZodObject<{
91
+ isStreamAvailable: z.ZodBoolean;
92
+ snapshotPath: z.ZodOptional<z.ZodString>;
93
+ isRecording: z.ZodDefault<z.ZodBoolean>;
94
+ }, z.core.$strip>>;
95
+ button: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
96
+ update: z.ZodOptional<z.ZodObject<{
97
+ installedVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
98
+ latestVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
99
+ isInstalling: z.ZodDefault<z.ZodBoolean>;
100
+ progress: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
101
+ }, z.core.$strip>>;
102
+ lawn_mower: z.ZodOptional<z.ZodObject<{
103
+ activity: z.ZodEnum<{
104
+ error: "error";
105
+ idle: "idle";
106
+ paused: "paused";
107
+ mowing: "mowing";
108
+ returning: "returning";
109
+ docked: "docked";
110
+ }>;
111
+ isResumable: z.ZodDefault<z.ZodBoolean>;
112
+ }, z.core.$strip>>;
113
+ select: z.ZodOptional<z.ZodObject<{
114
+ option: z.ZodDefault<z.ZodNullable<z.ZodString>>;
115
+ }, z.core.$strip>>;
116
+ number: z.ZodOptional<z.ZodObject<{
117
+ value: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
118
+ }, z.core.$strip>>;
119
+ vacuum: z.ZodOptional<z.ZodObject<{
120
+ activity: z.ZodEnum<{
121
+ error: "error";
122
+ idle: "idle";
123
+ paused: "paused";
124
+ returning: "returning";
125
+ docked: "docked";
126
+ cleaning: "cleaning";
127
+ }>;
128
+ rooms: z.ZodDefault<z.ZodArray<z.ZodObject<{
129
+ id: z.ZodString;
130
+ name: z.ZodString;
131
+ }, z.core.$strip>>>;
132
+ isResumable: z.ZodDefault<z.ZodBoolean>;
133
+ }, z.core.$strip>>;
134
+ image: z.ZodOptional<z.ZodObject<{
135
+ contentType: z.ZodEnum<{
136
+ "image/svg+xml": "image/svg+xml";
137
+ "image/png": "image/png";
138
+ "image/jpeg": "image/jpeg";
139
+ }>;
140
+ revision: z.ZodString;
141
+ width: z.ZodOptional<z.ZodInt>;
142
+ height: z.ZodOptional<z.ZodInt>;
143
+ }, z.core.$strip>>;
144
+ custom: z.ZodOptional<z.ZodObject<{
145
+ values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
146
+ }, z.core.$strip>>;
147
+ }, z.core.$strip>;
148
+ /** The composite state of an entity, keyed by capability. */
149
+ type CapabilityState = z.output<typeof capabilityStateSchema>;
150
+ //#endregion
151
+ //#region ../contracts/dist/json.d.ts
152
+ /**
153
+ * A JSON object, the shape most `jsonb` columns actually hold.
154
+ *
155
+ * Written as an index signature rather than `Record<string, JsonValue>` because `Record` is a
156
+ * mapped type, which TypeScript resolves eagerly and therefore cannot use in the recursive
157
+ * definition below (TS2456). The index signature is deferred, so it can.
158
+ */
159
+ type JsonObject = {
160
+ [key: string]: JsonValue;
161
+ };
162
+ /** Any value that survives a JSON round trip unchanged. */
163
+ type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
164
+ //#endregion
165
+ //#region ../contracts/dist/entity-id.d.ts
166
+ /** The kinds of thing an entity can be. The domain is the part before the dot. */
167
+ declare const ENTITY_DOMAINS: readonly ["light", "switch", "sensor", "binary_sensor", "cover", "lock", "climate", "media_player", "camera", "button", "update", "lawn_mower", "select", "number", "vacuum", "image", "custom", "alias"];
168
+ /** The kind of thing an entity is. */
169
+ type EntityDomain = (typeof ENTITY_DOMAINS)[number];
170
+ /**
171
+ * Validates an entity identifier and brands the result.
172
+ *
173
+ * The brand means an `EntityId` cannot be produced from a bare string without going through
174
+ * validation. Identifiers reach the database as primary lookups and NATS as subject tokens, so
175
+ * an unvalidated one does not fail where it was created - it fails somewhere else, later.
176
+ */
177
+ declare const entityIdSchema: z.core.$ZodBranded<z.ZodString, "EntityId", "out">;
178
+ /** A validated `<domain>.<object_id>` identifier. */
179
+ type EntityId = z.output<typeof entityIdSchema>;
180
+ //#endregion
181
+ //#region ../contracts/dist/registration.d.ts
182
+ /**
183
+ * How history should aggregate a numeric entity.
184
+ *
185
+ * `total_increasing` is the one that matters: energy consumed over a day is last minus first,
186
+ * not a sum of averages, and only the integration knows which kind of counter it is reading.
187
+ */
188
+ declare const ENTITY_STATE_CLASSES: readonly ["measurement", "total", "total_increasing"];
189
+ /** How history should aggregate a numeric entity. */
190
+ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
191
+ /**
192
+ * What an entity declares it can do, with the device's own limits for each.
193
+ *
194
+ * A partial record rather than a full one: an entity declares the capabilities it has, not every
195
+ * capability that exists. Each capability's parameters are checked against that capability's own
196
+ * schema, because `core` later validates commands against them - `color_temp` without its mired
197
+ * range would be accepted here and then reject every `set_color_temp` for a reason the owner
198
+ * cannot act on.
199
+ */
200
+ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
201
+ number: "number";
202
+ on_off: "on_off";
203
+ level: "level";
204
+ color_hs: "color_hs";
205
+ color_temp: "color_temp";
206
+ cover: "cover";
207
+ lock: "lock";
208
+ thermostat: "thermostat";
209
+ sensor_numeric: "sensor_numeric";
210
+ sensor_binary: "sensor_binary";
211
+ sensor_text: "sensor_text";
212
+ media_player: "media_player";
213
+ camera: "camera";
214
+ button: "button";
215
+ update: "update";
216
+ lawn_mower: "lawn_mower";
217
+ select: "select";
218
+ vacuum: "vacuum";
219
+ image: "image";
220
+ custom: "custom";
221
+ }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
222
+ /** What an entity declares it can do, with the device's own limits for each. */
223
+ type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
224
+ //#endregion
225
+ //#region ../contracts/dist/entity-state.d.ts
226
+ /**
227
+ * What an adapter publishes when a device reports.
228
+ *
229
+ * Deliberately smaller than {@link entityStateSchema}: an adapter reports what it observed, and
230
+ * `core` is the single writer that decides `lastChanged`, resolves the context and persists the
231
+ * result. An adapter that could set `lastChanged` itself would be a second writer of the
232
+ * registry's most load-bearing field.
233
+ */
234
+ declare const stateReportSchema: z.ZodObject<{
235
+ entityId: z.core.$ZodBranded<z.ZodString, "EntityId", "out">;
236
+ state: z.ZodObject<{
237
+ on_off: z.ZodOptional<z.ZodObject<{
238
+ isOn: z.ZodBoolean;
239
+ }, z.core.$strip>>;
240
+ level: z.ZodOptional<z.ZodObject<{
241
+ level: z.ZodNumber;
242
+ }, z.core.$strip>>;
243
+ color_hs: z.ZodOptional<z.ZodObject<{
244
+ hue: z.ZodNumber;
245
+ saturation: z.ZodNumber;
246
+ }, z.core.$strip>>;
247
+ color_temp: z.ZodOptional<z.ZodObject<{
248
+ mireds: z.ZodInt;
249
+ }, z.core.$strip>>;
250
+ cover: z.ZodOptional<z.ZodObject<{
251
+ position: z.ZodNumber;
252
+ tilt: z.ZodOptional<z.ZodNumber>;
253
+ motion: z.ZodEnum<{
254
+ opening: "opening";
255
+ closing: "closing";
256
+ stopped: "stopped";
257
+ }>;
258
+ }, z.core.$strip>>;
259
+ lock: z.ZodOptional<z.ZodObject<{
260
+ lockState: z.ZodEnum<{
261
+ locked: "locked";
262
+ unlocked: "unlocked";
263
+ jammed: "jammed";
264
+ }>;
265
+ }, z.core.$strip>>;
266
+ thermostat: z.ZodOptional<z.ZodObject<{
267
+ currentTemperature: z.ZodNumber;
268
+ targetTemperature: z.ZodNumber;
269
+ mode: z.ZodEnum<{
270
+ off: "off";
271
+ heat: "heat";
272
+ cool: "cool";
273
+ auto: "auto";
274
+ fan_only: "fan_only";
275
+ dry: "dry";
276
+ }>;
277
+ action: z.ZodEnum<{
278
+ off: "off";
279
+ idle: "idle";
280
+ heating: "heating";
281
+ cooling: "cooling";
282
+ drying: "drying";
283
+ fan: "fan";
284
+ }>;
285
+ humidity: z.ZodOptional<z.ZodNumber>;
286
+ }, z.core.$strip>>;
287
+ sensor_numeric: z.ZodOptional<z.ZodObject<{
288
+ value: z.ZodNumber;
289
+ }, z.core.$strip>>;
290
+ sensor_binary: z.ZodOptional<z.ZodObject<{
291
+ isOn: z.ZodBoolean;
292
+ }, z.core.$strip>>;
293
+ sensor_text: z.ZodOptional<z.ZodObject<{
294
+ value: z.ZodString;
295
+ }, z.core.$strip>>;
296
+ media_player: z.ZodOptional<z.ZodObject<{
297
+ playback: z.ZodEnum<{
298
+ stopped: "stopped";
299
+ idle: "idle";
300
+ playing: "playing";
301
+ paused: "paused";
302
+ buffering: "buffering";
303
+ }>;
304
+ volume: z.ZodNumber;
305
+ isMuted: z.ZodBoolean;
306
+ source: z.ZodOptional<z.ZodString>;
307
+ mediaTitle: z.ZodOptional<z.ZodString>;
308
+ mediaArtist: z.ZodOptional<z.ZodString>;
309
+ mediaDurationSeconds: z.ZodOptional<z.ZodNumber>;
310
+ mediaPositionSeconds: z.ZodOptional<z.ZodNumber>;
311
+ }, z.core.$strip>>;
312
+ camera: z.ZodOptional<z.ZodObject<{
313
+ isStreamAvailable: z.ZodBoolean;
314
+ snapshotPath: z.ZodOptional<z.ZodString>;
315
+ isRecording: z.ZodDefault<z.ZodBoolean>;
316
+ }, z.core.$strip>>;
317
+ button: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
318
+ update: z.ZodOptional<z.ZodObject<{
319
+ installedVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
320
+ latestVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
321
+ isInstalling: z.ZodDefault<z.ZodBoolean>;
322
+ progress: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
323
+ }, z.core.$strip>>;
324
+ lawn_mower: z.ZodOptional<z.ZodObject<{
325
+ activity: z.ZodEnum<{
326
+ error: "error";
327
+ idle: "idle";
328
+ paused: "paused";
329
+ mowing: "mowing";
330
+ returning: "returning";
331
+ docked: "docked";
332
+ }>;
333
+ isResumable: z.ZodDefault<z.ZodBoolean>;
334
+ }, z.core.$strip>>;
335
+ select: z.ZodOptional<z.ZodObject<{
336
+ option: z.ZodDefault<z.ZodNullable<z.ZodString>>;
337
+ }, z.core.$strip>>;
338
+ number: z.ZodOptional<z.ZodObject<{
339
+ value: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
340
+ }, z.core.$strip>>;
341
+ vacuum: z.ZodOptional<z.ZodObject<{
342
+ activity: z.ZodEnum<{
343
+ error: "error";
344
+ idle: "idle";
345
+ paused: "paused";
346
+ returning: "returning";
347
+ docked: "docked";
348
+ cleaning: "cleaning";
349
+ }>;
350
+ rooms: z.ZodDefault<z.ZodArray<z.ZodObject<{
351
+ id: z.ZodString;
352
+ name: z.ZodString;
353
+ }, z.core.$strip>>>;
354
+ isResumable: z.ZodDefault<z.ZodBoolean>;
355
+ }, z.core.$strip>>;
356
+ image: z.ZodOptional<z.ZodObject<{
357
+ contentType: z.ZodEnum<{
358
+ "image/svg+xml": "image/svg+xml";
359
+ "image/png": "image/png";
360
+ "image/jpeg": "image/jpeg";
361
+ }>;
362
+ revision: z.ZodString;
363
+ width: z.ZodOptional<z.ZodInt>;
364
+ height: z.ZodOptional<z.ZodInt>;
365
+ }, z.core.$strip>>;
366
+ custom: z.ZodOptional<z.ZodObject<{
367
+ values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
368
+ }, z.core.$strip>>;
369
+ }, z.core.$strip>;
370
+ attributes: z.ZodOptional<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
371
+ isAvailable: z.ZodOptional<z.ZodBoolean>;
372
+ observedAt: z.ZodOptional<z.ZodUnion<readonly [z.ZodDate, z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>]>>;
373
+ }, z.core.$strip>;
374
+ /** What an adapter publishes when a device reports. */
375
+ type StateReport = z.output<typeof stateReportSchema>;
376
+ //#endregion
377
+ //#region ../contracts/dist/integration-setup.d.ts
378
+ /** Validates one field of a group. */
379
+ declare const setupFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
380
+ type: z.ZodLiteral<"text">;
381
+ placeholder: z.ZodOptional<z.ZodString>;
382
+ pattern: z.ZodOptional<z.ZodString>;
383
+ patternMessage: z.ZodOptional<z.ZodString>;
384
+ minLength: z.ZodOptional<z.ZodInt>;
385
+ maxLength: z.ZodDefault<z.ZodInt>;
386
+ default: z.ZodOptional<z.ZodString>;
387
+ key: z.ZodString;
388
+ label: z.ZodString;
389
+ help: z.ZodOptional<z.ZodString>;
390
+ isRequired: z.ZodDefault<z.ZodBoolean>;
391
+ shownWhen: z.ZodOptional<z.ZodObject<{
392
+ key: z.ZodString;
393
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
394
+ }, z.core.$strict>>;
395
+ isLive: z.ZodOptional<z.ZodBoolean>;
396
+ }, z.core.$strict>, z.ZodObject<{
397
+ type: z.ZodLiteral<"secret">;
398
+ pattern: z.ZodOptional<z.ZodString>;
399
+ patternMessage: z.ZodOptional<z.ZodString>;
400
+ minLength: z.ZodOptional<z.ZodInt>;
401
+ maxLength: z.ZodDefault<z.ZodInt>;
402
+ key: z.ZodString;
403
+ label: z.ZodString;
404
+ help: z.ZodOptional<z.ZodString>;
405
+ isRequired: z.ZodDefault<z.ZodBoolean>;
406
+ shownWhen: z.ZodOptional<z.ZodObject<{
407
+ key: z.ZodString;
408
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
409
+ }, z.core.$strict>>;
410
+ isLive: z.ZodOptional<z.ZodBoolean>;
411
+ }, z.core.$strict>, z.ZodObject<{
412
+ type: z.ZodLiteral<"number">;
413
+ min: z.ZodOptional<z.ZodNumber>;
414
+ max: z.ZodOptional<z.ZodNumber>;
415
+ isInteger: z.ZodDefault<z.ZodBoolean>;
416
+ unit: z.ZodOptional<z.ZodString>;
417
+ default: z.ZodOptional<z.ZodNumber>;
418
+ warnBelow: z.ZodOptional<z.ZodNumber>;
419
+ warning: z.ZodOptional<z.ZodString>;
420
+ key: z.ZodString;
421
+ label: z.ZodString;
422
+ help: z.ZodOptional<z.ZodString>;
423
+ isRequired: z.ZodDefault<z.ZodBoolean>;
424
+ shownWhen: z.ZodOptional<z.ZodObject<{
425
+ key: z.ZodString;
426
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
427
+ }, z.core.$strict>>;
428
+ isLive: z.ZodOptional<z.ZodBoolean>;
429
+ }, z.core.$strict>, z.ZodObject<{
430
+ type: z.ZodLiteral<"boolean">;
431
+ default: z.ZodOptional<z.ZodBoolean>;
432
+ key: z.ZodString;
433
+ label: z.ZodString;
434
+ help: z.ZodOptional<z.ZodString>;
435
+ isRequired: z.ZodDefault<z.ZodBoolean>;
436
+ shownWhen: z.ZodOptional<z.ZodObject<{
437
+ key: z.ZodString;
438
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
439
+ }, z.core.$strict>>;
440
+ isLive: z.ZodOptional<z.ZodBoolean>;
441
+ }, z.core.$strict>, z.ZodObject<{
442
+ type: z.ZodLiteral<"choice">;
443
+ choices: z.ZodArray<z.ZodObject<{
444
+ value: z.ZodString;
445
+ label: z.ZodString;
446
+ }, z.core.$strict>>;
447
+ default: z.ZodOptional<z.ZodString>;
448
+ key: z.ZodString;
449
+ label: z.ZodString;
450
+ help: z.ZodOptional<z.ZodString>;
451
+ isRequired: z.ZodDefault<z.ZodBoolean>;
452
+ shownWhen: z.ZodOptional<z.ZodObject<{
453
+ key: z.ZodString;
454
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
455
+ }, z.core.$strict>>;
456
+ isLive: z.ZodOptional<z.ZodBoolean>;
457
+ }, z.core.$strict>, z.ZodObject<{
458
+ type: z.ZodLiteral<"list">;
459
+ placeholder: z.ZodOptional<z.ZodString>;
460
+ minItems: z.ZodDefault<z.ZodInt>;
461
+ maxItems: z.ZodDefault<z.ZodInt>;
462
+ pattern: z.ZodOptional<z.ZodString>;
463
+ patternMessage: z.ZodOptional<z.ZodString>;
464
+ key: z.ZodString;
465
+ label: z.ZodString;
466
+ help: z.ZodOptional<z.ZodString>;
467
+ isRequired: z.ZodDefault<z.ZodBoolean>;
468
+ shownWhen: z.ZodOptional<z.ZodObject<{
469
+ key: z.ZodString;
470
+ equals: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
471
+ }, z.core.$strict>>;
472
+ isLive: z.ZodOptional<z.ZodBoolean>;
473
+ }, z.core.$strict>], "type">;
474
+ /** One field of a group. */
475
+ type SetupField = z.output<typeof setupFieldSchema>;
476
+ //#endregion
477
+ //#region ../package-runtime/dist/transport.d.ts
478
+ /** What an integration asks a transport to do, expressed as data. */
479
+ type TransportRequest = {
480
+ /** Which device, in whatever way this transport identifies one. */
481
+ readonly deviceKey: string;
482
+ /** The transport's own verb: `get` and `post` for HTTP, `publish` for MQTT. */
483
+ readonly op: string;
484
+ /** The verb's arguments, in the transport's own vocabulary. */
485
+ readonly args: JsonObject;
486
+ };
487
+ /**
488
+ * A standing interest an integration has in what a connection carries.
489
+ *
490
+ * No `deviceKey`: a subscription is usually broader than one device - a topic filter, a polling
491
+ * schedule - and the transport reports which device a message came from when it arrives.
492
+ */
493
+ type TransportSubscription = {
494
+ readonly op: string;
495
+ readonly args: JsonObject;
496
+ };
497
+ /** Something a connection delivered without being asked. */
498
+ type TransportInbound = {
499
+ readonly connectionKey: string;
500
+ readonly deviceKey: string;
501
+ /** Raw, as it arrived. Making sense of it is the integration's job. */
502
+ readonly payload: unknown;
503
+ };
504
+ /** Something a scan found, before any integration has claimed it. */
505
+ type Discovered = {
506
+ readonly deviceKey: string;
507
+ /**
508
+ * What the scan saw.
509
+ *
510
+ * The blob an integration decides on and, if it claims the device, describes it from. Keeping
511
+ * it raw is what lets `describe` be a pure function of it.
512
+ */
513
+ readonly payload: unknown;
514
+ };
515
+ /** Whether a connection is currently usable. */
516
+ type TransportStatus = 'up' | 'down';
517
+ /**
518
+ * What a transport is given when it opens a connection.
519
+ *
520
+ * The transport **calls** these. It is the one holding the socket, so it is the one that knows
521
+ * when something arrived and when the connection dropped; `hub` cannot poll for either.
522
+ */
523
+ type TransportContext = {
524
+ readonly logger: BundleLogger;
525
+ /** Called for every message the connection delivered without being asked. */
526
+ deliver: (message: TransportInbound) => void;
527
+ /** Called when the connection comes up or goes down. */
528
+ report: (status: TransportStatus) => void;
529
+ /**
530
+ * The account the connection is for, when its configuration names one
531
+ * (`config.account`) of the transport's own vendor - the session to use, and how to keep a
532
+ * renewed one or say the owner must sign in again. Absent otherwise.
533
+ */
534
+ readonly account?: AccountHandle;
535
+ };
536
+ /**
537
+ * What a scan or a probe is handed beside its arguments - the account its
538
+ * configuration names (`config.account`), as a connection is handed it. Absent otherwise.
539
+ */
540
+ type TransportLookContext = {
541
+ readonly account?: AccountHandle;
542
+ };
543
+ /** One live connection, shared by every instance whose configuration resolves to it. */
544
+ type TransportConnection = {
545
+ /** What this connection is shared under. */
546
+ readonly key: string;
547
+ /**
548
+ * Performs one request.
549
+ *
550
+ * @param request - What to do.
551
+ * @param signal - Cancels the request.
552
+ * @returns Whatever the device answered, raw.
553
+ */
554
+ send: (request: TransportRequest, signal: AbortSignal) => Promise<unknown>;
555
+ /**
556
+ * Replaces the set of standing subscriptions.
557
+ *
558
+ * Replaces rather than adds, so that `hub` can recompute the whole set when an instance is
559
+ * added or removed and apply it without tracking what it asked for last time.
560
+ *
561
+ * @param subscriptions - Everything this connection should now carry.
562
+ * @returns A promise that settles once the transport has applied them.
563
+ */
564
+ apply: (subscriptions: readonly TransportSubscription[]) => Promise<void>;
565
+ /**
566
+ * Closes the connection.
567
+ *
568
+ * @returns A promise that settles once it is closed.
569
+ */
570
+ close: () => Promise<void>;
571
+ };
572
+ /**
573
+ * How a kind of connection is opened, scanned and spoken to.
574
+ *
575
+ * Configuration arrives as `unknown` because this is what a registry holds, and a registry holds
576
+ * transports of every shape. Each one narrows its own with {@link defineTransport}, which is also
577
+ * the single place the settings an owner typed are validated.
578
+ *
579
+ * The alternative - a generic `Transport<TConfig>` - does not survive being put in a collection:
580
+ * a `Transport<HttpConfig>` is not a `Transport<JsonObject>`, because a function taking the
581
+ * narrower type cannot stand in for one taking the wider. Erasing the parameter here and
582
+ * restoring it in the helper keeps both ends honest without a cast anywhere.
583
+ */
584
+ type Transport = {
585
+ /** `http`, `mqtt`, `esphome`. */
586
+ readonly id: string;
587
+ /** Validates the connection settings an owner supplied. */
588
+ readonly configSchema: z.ZodType;
589
+ /**
590
+ * What two configurations must agree on to share one connection.
591
+ *
592
+ * Derived from the configuration rather than declared, because the answer is the transport's:
593
+ * two MQTT instances share a connection when the broker matches, two HTTP ones never do.
594
+ *
595
+ * @param config - The connection settings.
596
+ * @returns The key this configuration's connection is shared under.
597
+ */
598
+ connectionKey: (config: unknown) => string;
599
+ /**
600
+ * Opens a connection.
601
+ *
602
+ * @param config - The connection settings.
603
+ * @param context - Where inbound messages and status changes go.
604
+ * @returns The connection, once it is usable.
605
+ */
606
+ connect: (config: unknown, context: TransportContext) => Promise<TransportConnection>;
607
+ /**
608
+ * Looks for devices this transport can reach.
609
+ *
610
+ * @param config - The connection settings.
611
+ * @param scan - The integration's search terms, in this transport's vocabulary.
612
+ * @param signal - Ends the scan.
613
+ * @param context - The account the configuration names.
614
+ * @returns Candidates as they are found, rather than a list once the scan is over: a scan of a
615
+ * house takes long enough that the interface should be filling in while it runs.
616
+ */
617
+ scan: (config: unknown, scan: JsonObject, signal: AbortSignal, context?: TransportLookContext) => AsyncIterable<Discovered>;
618
+ /**
619
+ * Tries the settings against the world and lets go again.
620
+ *
621
+ * What "Test" in the interface does before an owner saves: open whatever the transport opens
622
+ * - a broker session, a request to each address - then close it, keeping nothing. Resolves
623
+ * with one sentence saying what worked, so the interface can show it; rejects with an error
624
+ * whose message names what did not, in the transport's own words, because "Not authorized"
625
+ * and "ECONNREFUSED" send an owner to different places.
626
+ *
627
+ * @param config - What the owner typed, complete and in the clear.
628
+ * @param signal - Gives up: a host that never answers must not hold the form open.
629
+ * @param context - The account the configuration names.
630
+ */
631
+ probe: (config: unknown, signal: AbortSignal, context?: TransportLookContext) => Promise<string>;
632
+ };
633
+ /** A transport as its author writes it, with its own configuration type. */
634
+ type TransportSpec<TConfig> = {
635
+ readonly id: string;
636
+ readonly configSchema: z.ZodType<TConfig>;
637
+ connectionKey: (config: TConfig) => string;
638
+ connect: (config: TConfig, context: TransportContext) => Promise<TransportConnection>;
639
+ scan: (config: TConfig, scan: JsonObject, signal: AbortSignal, context?: TransportLookContext) => AsyncIterable<Discovered>;
640
+ probe: (config: TConfig, signal: AbortSignal, context?: TransportLookContext) => Promise<string>;
641
+ };
642
+ /**
643
+ * Turns a transport written against its own configuration into one a registry can hold.
644
+ *
645
+ * Validation happens here and only here. Everything above receives whatever an owner put in a
646
+ * `jsonb` column and passes it straight through, so a wrong setting fails once, with the
647
+ * transport's own message, instead of being parsed in every caller that happens to remember to.
648
+ *
649
+ * @param spec - The transport, written against the configuration it understands.
650
+ * @returns The same transport, with its configuration parameter erased.
651
+ */
652
+ declare function defineTransport<TConfig>(spec: TransportSpec<TConfig>): Transport;
653
+ //#endregion
654
+ //#region ../package-runtime/dist/integration.d.ts
655
+ /** A device an integration has recognised as its own. */
656
+ type Claim = {
657
+ /** How the transport addresses it. */
658
+ readonly deviceKey: string;
659
+ /** How the integration identifies it, stable across restarts. */
660
+ readonly externalId: string;
661
+ /**
662
+ * What the integration recognised it from, kept for {@link Integration.describe}.
663
+ *
664
+ * Raw. For zigbee2mqtt this is the `exposes` tree, for ESPHome the entity list, for Matter the
665
+ * endpoint and cluster tree. All three are self-describing, which is exactly why `describe`
666
+ * can be a pure function of this and why those integrations cover thousands of devices each.
667
+ */
668
+ readonly descriptor: unknown;
669
+ };
670
+ /** One entity a device exposes, before `hub` has given it an identifier. */
671
+ type EntityDescriptor = {
672
+ readonly domain: EntityDomain;
673
+ /** Distinguishes it from the device's other entities. Omitted when it is the only one. */
674
+ readonly objectId?: string;
675
+ readonly name: string;
676
+ /** The catalogue icon it starts with, when the bundle names one. */
677
+ readonly icon?: string;
678
+ readonly capabilities: DeclaredCapabilities;
679
+ readonly unitOfMeasurement?: string;
680
+ readonly deviceClass?: string;
681
+ readonly stateClass?: EntityStateClass;
682
+ readonly displayPrecision?: number;
683
+ };
684
+ /** What a claimed device turns out to be. */
685
+ type DeviceDescriptor = {
686
+ readonly externalId: string;
687
+ readonly name: string;
688
+ readonly manufacturer?: string;
689
+ readonly model?: string;
690
+ readonly swVersion?: string;
691
+ readonly hwVersion?: string;
692
+ /**
693
+ * The device this one is reached through, named the way this integration names devices.
694
+ *
695
+ * A BLE thermometer reached through an ESPHome proxy names the proxy here. It is what lets the
696
+ * interface answer "why did six things go offline at once" with the one that actually did.
697
+ */
698
+ readonly viaExternalId?: string;
699
+ readonly entities: readonly EntityDescriptor[];
700
+ };
701
+ /** What a mapper may look at besides its own arguments. */
702
+ type MappingContext = {
703
+ /** The instance's own settings, already validated against the integration's schema. */
704
+ readonly options: JsonObject;
705
+ /** The device being mapped. */
706
+ readonly claim: Claim;
707
+ /** The entity identifiers `hub` gave this device, keyed by descriptor `objectId`. */
708
+ readonly entities: ReadonlyMap<string, EntityId>;
709
+ /**
710
+ * The last state `hub` published for an entity.
711
+ *
712
+ * Present so that a command needing the current value can be built without asking the device.
713
+ * Undefined before the entity has ever reported.
714
+ *
715
+ * @param entityId - The entity to look up.
716
+ * @returns Its last known state, or undefined.
717
+ */
718
+ lastState: (entityId: EntityId) => CapabilityState | undefined;
719
+ };
720
+ /** A command, resolved to the device and entity it is for. */
721
+ type CommandTarget = {
722
+ readonly entityId: EntityId;
723
+ readonly capability: CapabilityName;
724
+ /** Already validated by `core` against the capability's command schema. */
725
+ readonly command: JsonObject;
726
+ };
727
+ /**
728
+ * The picture an image entity's report carries beside its state - an SVG, a PNG - which
729
+ * the hub keeps and never publishes: the state says which picture it is (`revision`), and the
730
+ * bytes are asked for by whoever shows it.
731
+ */
732
+ type ImageBlob = {
733
+ readonly contentType: 'image/svg+xml' | 'image/png' | 'image/jpeg';
734
+ /** The picture: an SVG's text, or bytes. */
735
+ readonly data: string | Buffer;
736
+ /** How often at most a new picture of the entity is announced; 2 s unless said. */
737
+ readonly minIntervalMs?: number;
738
+ };
739
+ /** A report as an integration makes it: the state, and the picture of an image entity. */
740
+ type ReportedState = StateReport & {
741
+ readonly blob?: ImageBlob;
742
+ };
743
+ /** What a kind of device means, in terms of the canonical model. */
744
+ type Integration<TOptions = JsonObject> = {
745
+ /** The bundle kind: `zigbee2mqtt`, `shelly-gen2`. An instance of it gets its own id. */
746
+ readonly id: string;
747
+ /** Which transport carries it. */
748
+ readonly transport: string;
749
+ /** Validates the settings an owner supplied for an instance. */
750
+ readonly optionsSchema: z.ZodType<TOptions>;
751
+ /**
752
+ * What to tell the transport to look for during a scan.
753
+ *
754
+ * The transport's own vocabulary - an mDNS service name, an MQTT topic filter - and opaque
755
+ * here. An empty object means "whatever you would find anyway", which is what a code
756
+ * integration on a transport that enumerates broadly uses.
757
+ */
758
+ readonly discovery: JsonObject;
759
+ /**
760
+ * Decides whether a discovered device is this integration's to own.
761
+ *
762
+ * @param discovered - What the scan found.
763
+ * @param options - The instance's settings.
764
+ * @returns The claim, or null when the device belongs to someone else.
765
+ */
766
+ claim: (discovered: Discovered, options: TOptions) => Claim | null;
767
+ /**
768
+ * States what the transport must carry for these devices.
769
+ *
770
+ * Data rather than an action: `hub` collects the answers from every instance sharing a
771
+ * connection, deduplicates them, and applies the set once.
772
+ *
773
+ * @param claims - The devices this instance owns.
774
+ * @param options - The instance's settings.
775
+ * @returns Everything the transport should subscribe to or poll.
776
+ */
777
+ subscriptions: (claims: readonly Claim[], options: TOptions) => TransportSubscription[];
778
+ /**
779
+ * Says what a claimed device is and what it exposes.
780
+ *
781
+ * @param claim - The device.
782
+ * @param options - The instance's settings.
783
+ * @returns Its identity and its entities.
784
+ */
785
+ describe: (claim: Claim, options: TOptions) => DeviceDescriptor;
786
+ /**
787
+ * Turns something the device sent into canonical state.
788
+ *
789
+ * @param message - What arrived.
790
+ * @param context - The claim, the settings and the last known state.
791
+ * @returns One report per entity the message says something about, which may be none.
792
+ */
793
+ toState: (message: TransportInbound, context: MappingContext) => ReportedState[];
794
+ /**
795
+ * Turns a canonical command into something the transport can perform.
796
+ *
797
+ * @param target - The entity, the capability and the command.
798
+ * @param context - The claim, the settings and the last known state.
799
+ * @returns The request. Performing it is the transport's job.
800
+ */
801
+ toCommand: (target: CommandTarget, context: MappingContext) => TransportRequest;
802
+ /**
803
+ * Reads what a message says about the device itself, beyond its entities: the firmware it runs
804
+ * now, which changes when it is updated and is otherwise only known from when it was found.
805
+ *
806
+ * Optional: an integration whose messages say nothing of the kind leaves it out.
807
+ *
808
+ * @param message - What arrived.
809
+ * @param context - The claim, the settings and the last known state.
810
+ * @returns What the message says, field by field; undefined, or a field left out, when it says
811
+ * nothing about it.
812
+ */
813
+ deviceInfo?: (message: TransportInbound, context: MappingContext) => DeviceInfo | undefined;
814
+ /**
815
+ * Says how a camera entity's picture is read, when it is one.
816
+ *
817
+ * Optional: an integration with no camera leaves it out.
818
+ *
819
+ * @param entityId - The entity.
820
+ * @param context - The claim, the settings and the last known state.
821
+ * @returns The stream source and what it is told to read, or undefined for an entity with none.
822
+ */
823
+ streamOf?: (entityId: EntityId, context: MappingContext) => StreamRequest | undefined;
824
+ };
825
+ /** How one camera's picture is read: which source, told what. */
826
+ type StreamRequest = {
827
+ readonly source: string;
828
+ readonly args: JsonObject;
829
+ };
830
+ /** What a message says about the device itself. */
831
+ type DeviceInfo = {
832
+ readonly swVersion?: string;
833
+ readonly hwVersion?: string;
834
+ };
835
+ //#endregion
836
+ //#region ../package-runtime/dist/stream.d.ts
837
+ /** What a stream carries: stills, or H.264 with the codec string its decoder is set up with. */
838
+ type StreamTrack = {
839
+ readonly kind: 'jpeg';
840
+ } | {
841
+ readonly kind: 'h264';
842
+ readonly codec: string;
843
+ };
844
+ /** One frame of a stream. */
845
+ type StreamFrame = {
846
+ /** A JPEG, or an H.264 access unit in Annex B with its parameter sets before a key frame. */
847
+ readonly data: Uint8Array;
848
+ /** Whether a decoder can start from it. */
849
+ readonly isKey: boolean;
850
+ /** When it was taken, in microseconds from the start of the stream. */
851
+ readonly timestampUs: number;
852
+ };
853
+ /** Where a source puts what it reads. */
854
+ type StreamSink = {
855
+ /** Says what the stream carries; called once, before the first frame. */
856
+ describe: (track: StreamTrack) => void;
857
+ /** Hands over one frame. */
858
+ frame: (frame: StreamFrame) => void;
859
+ };
860
+ /** How a camera's picture is read. */
861
+ type StreamSource = {
862
+ /** `<vendor>/<name>`, as the profile names it. */
863
+ readonly id: string;
864
+ /** Validates the settings it reads the camera with: the instance's transport settings. */
865
+ readonly configSchema: z.ZodType;
866
+ /**
867
+ * Reads the stream until the signal ends it or the camera does.
868
+ *
869
+ * @param config - The instance's transport settings, secrets opened.
870
+ * @param args - What the profile's camera entity says to read.
871
+ * @param sink - Where the track and the frames go.
872
+ * @param signal - Ends the stream.
873
+ * @returns A promise that settles when the stream ended; rejects with why, when it failed.
874
+ */
875
+ open: (config: unknown, args: JsonObject, sink: StreamSink, signal: AbortSignal) => Promise<void>;
876
+ };
877
+ /** A stream source as its author writes it, with its own configuration type. */
878
+ type StreamSourceSpec<TConfig> = {
879
+ readonly id: string;
880
+ readonly configSchema: z.ZodType<TConfig>;
881
+ open: (config: TConfig, args: JsonObject, sink: StreamSink, signal: AbortSignal) => Promise<void>;
882
+ };
883
+ /**
884
+ * Turns a stream source written against its own configuration into one a registry can hold,
885
+ * validating the settings on the way in as {@link defineTransport} does.
886
+ *
887
+ * @param spec - The source.
888
+ * @returns The same source, its configuration parameter erased.
889
+ */
890
+ declare function defineStreamSource<TConfig>(spec: StreamSourceSpec<TConfig>): StreamSource;
891
+ /** One access unit an RTSP session delivered. */
892
+ type RtspFrame = StreamFrame & {
893
+ /** The codec string of the stream, from its sequence parameters. */
894
+ readonly codec: string;
895
+ };
896
+ /** What opening an RTSP session takes. */
897
+ type RtspOptions = {
898
+ /** `rtsp://user:password@host:port/path`, or `rtsps://` over TLS. */
899
+ readonly url: string;
900
+ /** Whether a TLS camera's certificate must chain to an authority this machine trusts. */
901
+ readonly rejectUnauthorized?: boolean;
902
+ /** Ends the session. */
903
+ readonly signal: AbortSignal;
904
+ };
905
+ /**
906
+ * Plays an RTSP stream over TCP and yields its H.264 access units.
907
+ *
908
+ * @throws {Error} From the iteration, when the camera refused or the session failed.
909
+ */
910
+ type OpenRtsp = (options: RtspOptions) => AsyncIterable<RtspFrame>;
911
+ //#endregion
912
+ //#region ../package-runtime/dist/sdk.d.ts
913
+ /**
914
+ * One level of a bundle's log: fields and a message, or a message alone - pino's way, which is the
915
+ * logger `hub` hands over.
916
+ */
917
+ type BundleLogFn = {
918
+ (fields: object, message?: string): void;
919
+ (message: string): void;
920
+ };
921
+ /**
922
+ * The hub's logger, as far as a bundle's code may use it: named here rather than as the platform's
923
+ * logger type, so that what a bundle is written against says nothing of how the platform logs.
924
+ */
925
+ type BundleLogger = {
926
+ readonly trace: BundleLogFn;
927
+ readonly debug: BundleLogFn;
928
+ readonly info: BundleLogFn;
929
+ readonly warn: BundleLogFn;
930
+ readonly error: BundleLogFn;
931
+ readonly fatal: BundleLogFn;
932
+ /**
933
+ * A logger whose every line carries these fields too.
934
+ *
935
+ * @param fields - The fields.
936
+ * @returns The logger.
937
+ */
938
+ child: (fields: Record<string, unknown>) => BundleLogger;
939
+ };
940
+ /** HTTP headers for a WebSocket's opening handshake. */
941
+ type ManagedSocketHeaders = Readonly<Record<string, string>>;
942
+ /** What a drop says beyond its reason. */
943
+ type ManagedSocketClose = {
944
+ /** The WebSocket close code: the peer's, or 1006 for a socket that ended without one. */
945
+ readonly code?: number;
946
+ /**
947
+ * The HTTP status of a handshake the server refused - 401, 403 - so that credentials it turned
948
+ * down can be told from a network that failed. Absent for any other drop.
949
+ */
950
+ readonly status?: number;
951
+ };
952
+ /** What opening a managed WebSocket takes. */
953
+ type ManagedSocketOptions = {
954
+ /** `ws://host/path` or `wss://…`. */
955
+ readonly url: string;
956
+ /**
957
+ * Headers sent on the opening handshake, the first and every reconnect's, for a
958
+ * server that authenticates the socket by them. Never logged. A function is called before each
959
+ * attempt and may answer with a promise - for a token that expires; one that throws fails that
960
+ * attempt as a refused connection would, and the next comes on the usual schedule.
961
+ */
962
+ readonly headers?: ManagedSocketHeaders | (() => ManagedSocketHeaders | Promise<ManagedSocketHeaders>);
963
+ /**
964
+ * A ping every `everyMs`, and the socket dropped - then reconnected - when no pong
965
+ * comes within `timeoutMs`. For a peer that may say nothing for hours, whose silence would
966
+ * otherwise hide a dead connection. Off unless said.
967
+ */
968
+ readonly ping?: {
969
+ readonly everyMs: number;
970
+ readonly timeoutMs: number;
971
+ };
972
+ /**
973
+ * TLS for a `wss://` server: whether its certificate must chain to an authority
974
+ * this machine trusts (on unless said).
975
+ */
976
+ readonly tls?: {
977
+ readonly rejectUnauthorized?: boolean;
978
+ };
979
+ readonly logger: BundleLogger;
980
+ /** Called after every connection, the first and each one after a drop. */
981
+ readonly onOpen: () => void;
982
+ /** Called with each text frame. */
983
+ readonly onMessage: (text: string) => void;
984
+ /**
985
+ * Called when the socket dropped or failed to connect; the helper reconnects by itself unless
986
+ * the socket is closed here. The hub also says the close code and, for a handshake
987
+ * the server refused, its HTTP status.
988
+ */
989
+ readonly onClose: (reason: string, details?: ManagedSocketClose) => void;
990
+ /**
991
+ * How to come back after a drop: doubling from `minMs` (1 s) to `maxMs` (30 s), reset by a
992
+ * connection that opens. `false` is one attempt and no more, for a probe or a scan.
993
+ */
994
+ readonly reconnect?: {
995
+ readonly minMs?: number;
996
+ readonly maxMs?: number;
997
+ } | false;
998
+ };
999
+ /** A WebSocket the hub keeps open on a bundle's behalf. */
1000
+ type ManagedSocket = {
1001
+ /** Whether a frame can be sent right now. */
1002
+ readonly isOpen: boolean;
1003
+ /**
1004
+ * Sends one text frame.
1005
+ *
1006
+ * @throws {Error} When the socket is not open.
1007
+ */
1008
+ send: (text: string) => void;
1009
+ /** Drops the socket so the helper reconnects - after a request that timed out. */
1010
+ reset: (reason: string) => void;
1011
+ /** Closes for good. */
1012
+ close: () => Promise<void>;
1013
+ };
1014
+ /** Opens a managed WebSocket. */
1015
+ type OpenWebSocket = (options: ManagedSocketOptions) => ManagedSocket;
1016
+ /** Where a datagram came from. */
1017
+ type UdpPeer = {
1018
+ readonly address: string;
1019
+ readonly port: number;
1020
+ };
1021
+ /** What opening a managed UDP socket takes. */
1022
+ type ManagedUdpSocketOptions = {
1023
+ /** The port to listen on; absent, whatever port the system picks. */
1024
+ readonly port?: number;
1025
+ /** Whether another socket may bind the same port, as a multicast listener must allow. */
1026
+ readonly reuseAddr?: boolean;
1027
+ /** A multicast group to join, and whether to hear what this host itself sends to it. */
1028
+ readonly multicast?: {
1029
+ readonly group: string;
1030
+ readonly loopback?: boolean;
1031
+ };
1032
+ /** Whether the socket may send to a broadcast address. */
1033
+ readonly broadcast?: boolean;
1034
+ /** Called with each datagram, as bytes: some protocols are text and some are not. */
1035
+ readonly onMessage: (message: Buffer, from: UdpPeer) => void;
1036
+ /** Called when the socket fails after it opened. The hub has logged it already. */
1037
+ readonly onError?: (error: Error) => void;
1038
+ };
1039
+ /** A UDP socket the hub holds on a bundle's behalf. */
1040
+ type ManagedUdpSocket = {
1041
+ /** The port it is bound to, known once it has opened. */
1042
+ readonly port: number;
1043
+ /**
1044
+ * Sends one datagram.
1045
+ *
1046
+ * @throws {Error} When the socket is closed or the send fails.
1047
+ */
1048
+ send: (message: Buffer | string, port: number, address: string) => Promise<void>;
1049
+ /** Closes for good, leaving the group. */
1050
+ close: () => Promise<void>;
1051
+ };
1052
+ /** Opens a managed UDP socket. */
1053
+ type OpenUdpSocket = (options: ManagedUdpSocketOptions) => ManagedUdpSocket;
1054
+ /** What opening a managed MQTT session takes. */
1055
+ type ManagedMqttOptions = {
1056
+ /** `mqtt://host:1883`, or `mqtts://host:8883` behind TLS. */
1057
+ readonly url: string;
1058
+ /** The client id to connect as; one the client makes up when absent. */
1059
+ readonly clientId?: string;
1060
+ readonly username?: string;
1061
+ readonly password?: string;
1062
+ /**
1063
+ * TLS for an `mqtts://` broker: a client certificate as a PKCS#12 bundle and its passphrase,
1064
+ * for a broker that authenticates the client by certificate, and whether the broker's own
1065
+ * certificate must chain to an authority this machine trusts (on unless said).
1066
+ */
1067
+ readonly tls?: {
1068
+ readonly pfx?: Buffer;
1069
+ readonly passphrase?: string;
1070
+ readonly rejectUnauthorized?: boolean;
1071
+ };
1072
+ readonly logger: BundleLogger;
1073
+ /** Called after every connection, the first and each one after a drop. */
1074
+ readonly onConnect?: () => void;
1075
+ /** Called with each message on a topic subscribed to. */
1076
+ readonly onMessage: (topic: string, payload: Buffer) => void;
1077
+ /** Called when the session dropped or failed to come up; the helper reconnects by itself. */
1078
+ readonly onClose?: (reason: string) => void;
1079
+ };
1080
+ /** An MQTT session the hub keeps up on a bundle's behalf. */
1081
+ type ManagedMqtt = {
1082
+ /** Whether a message can be published right now. */
1083
+ readonly isConnected: boolean;
1084
+ /** Subscribes, now and after every reconnect, until unsubscribed. */
1085
+ subscribe: (topic: string) => void;
1086
+ /** Stops hearing a topic. */
1087
+ unsubscribe: (topic: string) => void;
1088
+ /**
1089
+ * Publishes one message, at most once.
1090
+ *
1091
+ * @throws {Error} When the session is not up.
1092
+ */
1093
+ publish: (topic: string, payload: string | Buffer) => Promise<void>;
1094
+ /** Closes for good. */
1095
+ close: () => Promise<void>;
1096
+ };
1097
+ /** Opens a managed MQTT session. */
1098
+ type OpenMqtt = (options: ManagedMqttOptions) => ManagedMqtt;
1099
+ /**
1100
+ * The house's MQTT broker, as the hub reaches it: the package that provides `mqtt-broker`, with
1101
+ * the hub's own username - or the broker `NEBULA_MQTT_URL` names. Read again each time it is needed: the broker may start after
1102
+ * the hub, and a bundle that opens a session later finds it then.
1103
+ */
1104
+ type PlatformMqtt = {
1105
+ readonly url: string;
1106
+ readonly username?: string;
1107
+ readonly password?: string;
1108
+ };
1109
+ /** What the platform offers a bundle beyond the pieces to build a transport from. */
1110
+ type PlatformServices = {
1111
+ /**
1112
+ * The house's broker, for a vendor whose devices report through it - zigbee2mqtt - and which
1113
+ * runs its own program beside the platform. Null on an installation without one.
1114
+ */
1115
+ readonly mqtt: PlatformMqtt | null;
1116
+ };
1117
+ /** One colour of a palette: red, green, blue and, optionally, how opaque, each 0 to 255. */
1118
+ type PaletteColour = readonly [number, number, number] | readonly [number, number, number, number];
1119
+ /** A picture of a few colours: a robot's map, one palette index per cell. */
1120
+ type PalettedPicture = {
1121
+ readonly width: number;
1122
+ readonly height: number;
1123
+ /** At most 256 colours. */
1124
+ readonly palette: readonly PaletteColour[];
1125
+ /** One index into the palette per pixel, row after row from the top left. */
1126
+ readonly pixels: Uint8Array;
1127
+ };
1128
+ /** What a bundle drawing a picture needs, and could not bring as a dependency. */
1129
+ type BundleCodecs = {
1130
+ /**
1131
+ * Unpacks an LZMA stream in the alone format (`.lzma`): a 13-byte header - the properties and
1132
+ * the size, eight bytes of ones when unknown - then the stream. ECOVACS packs its maps so.
1133
+ *
1134
+ * @throws {Error} When the stream is corrupt.
1135
+ */
1136
+ readonly lzma: (bytes: Uint8Array) => Buffer;
1137
+ };
1138
+ /** Pictures a bundle draws, for an image entity. */
1139
+ type BundleImages = {
1140
+ /**
1141
+ * Encodes a paletted picture as a PNG, a colour with an alpha below 255 transparent.
1142
+ *
1143
+ * @throws {Error} When the size, the palette and the pixels do not fit together.
1144
+ */
1145
+ readonly png: (picture: PalettedPicture) => Buffer;
1146
+ };
1147
+ /** What the hub hands a bundle's transport factory. */
1148
+ type BundleSdk = {
1149
+ /** The runtime version, the same string `manifest.sdk` was matched against. */
1150
+ readonly version: string;
1151
+ /** The runtime's zod, so a bundle's schemas validate under the one instance the hub uses. */
1152
+ readonly z: typeof z;
1153
+ /** The hub's logger, for what happens outside a connection: a probe, a scan. */
1154
+ readonly logger: BundleLogger;
1155
+ readonly defineTransport: typeof defineTransport;
1156
+ readonly openWebSocket: OpenWebSocket;
1157
+ readonly openUdpSocket: OpenUdpSocket;
1158
+ /** An MQTT session, for a vendor whose devices report through a broker of its own. */
1159
+ readonly openMqtt: OpenMqtt;
1160
+ /** How a camera's stream source is written, as defineTransport is for a transport. */
1161
+ readonly defineStreamSource: typeof defineStreamSource;
1162
+ /** An RTSP session over TCP, yielding a camera's H.264 as it comes. */
1163
+ readonly openRtsp: OpenRtsp;
1164
+ /** What the platform itself runs that a bundle may use - its MQTT broker. */
1165
+ readonly platform: PlatformServices;
1166
+ /** How an account's sign-in module is written, as defineTransport is for a transport. */
1167
+ readonly defineAccount: typeof defineAccount;
1168
+ /** Unpacking what a vendor's cloud packs. */
1169
+ readonly codecs: BundleCodecs;
1170
+ /** Drawing pictures, for an image entity. */
1171
+ readonly images: BundleImages;
1172
+ };
1173
+ /** What a transport module default-exports. */
1174
+ type TransportFactory = (sdk: BundleSdk) => Transport;
1175
+ /** What a stream module default-exports. */
1176
+ type StreamFactory = (sdk: BundleSdk) => StreamSource;
1177
+ /**
1178
+ * What a code driver may default-export instead of an integration - a function of
1179
+ * the SDK, so the driver can build its schemas with the runtime's zod rather than bring its own.
1180
+ */
1181
+ type IntegrationFactory = (sdk: BundleSdk) => Integration;
1182
+ //#endregion
1183
+ //#region ../package-runtime/dist/account.d.ts
1184
+ /** Who an account signed in as: the cloud's id for it, and what its card calls it. */
1185
+ type AccountIdentity = {
1186
+ /** Stable across sign-ins: the account's id at the cloud. What a device remembers. */
1187
+ readonly id: string;
1188
+ /** What its card calls it: the email it was made with. */
1189
+ readonly label: string;
1190
+ };
1191
+ /** Where a sign-in stands, as the module answers it. */
1192
+ type AccountModuleStep =
1193
+ /** Done: who it is, and what to keep - tokens, a user id - for the next start. */
1194
+ {
1195
+ readonly kind: 'connected';
1196
+ readonly identity: AccountIdentity;
1197
+ readonly session: JsonObject;
1198
+ } |
1199
+ /**
1200
+ * The cloud wants something more - a code it emailed, a second factor. `pending` is whatever
1201
+ * the module needs to carry on; it comes back with the answers.
1202
+ */
1203
+ {
1204
+ readonly kind: 'ask';
1205
+ readonly message: string;
1206
+ readonly fields: readonly SetupField[];
1207
+ readonly pending: JsonObject;
1208
+ } |
1209
+ /** The owner approves on a page of the cloud's; asked again every `pollMs`. */
1210
+ {
1211
+ readonly kind: 'link';
1212
+ readonly message: string;
1213
+ readonly url: string;
1214
+ readonly code?: string;
1215
+ readonly pollMs: number;
1216
+ readonly pending: JsonObject;
1217
+ } |
1218
+ /** It did not work, and why; `field` is the one to correct, when one is to blame. */
1219
+ {
1220
+ readonly kind: 'failed';
1221
+ readonly message: string;
1222
+ readonly field?: string;
1223
+ };
1224
+ /** What a sign-in step is handed beside its arguments. */
1225
+ type AccountStepContext = {
1226
+ /** Ends the step: the owner gave up, or it took too long. */
1227
+ readonly signal: AbortSignal;
1228
+ };
1229
+ /** What signing in to a vendor's account does, as its module writes it. */
1230
+ type AccountModule = {
1231
+ /**
1232
+ * Signs in with what the owner typed, secrets opened.
1233
+ *
1234
+ * @returns Where it stands.
1235
+ */
1236
+ readonly signIn: (values: JsonObject, context: AccountStepContext) => Promise<AccountModuleStep>;
1237
+ /**
1238
+ * Carries on after a question, with its answers.
1239
+ *
1240
+ * @returns Where it stands now; the same question again, with why, for a wrong answer.
1241
+ */
1242
+ readonly answer: (pending: JsonObject, answers: JsonObject, context: AccountStepContext) => Promise<AccountModuleStep>;
1243
+ /**
1244
+ * Asks whether the page the owner was sent to was approved.
1245
+ *
1246
+ * @returns `link` again while it was not.
1247
+ */
1248
+ readonly poll?: (pending: JsonObject, context: AccountStepContext) => Promise<AccountModuleStep>;
1249
+ /**
1250
+ * Tells the cloud the account is forgotten, when the cloud has a way to: a token revoked.
1251
+ * Failing is not refusing - the account is forgotten here all the same.
1252
+ */
1253
+ readonly signOut?: (session: JsonObject, context: AccountStepContext) => Promise<void>;
1254
+ };
1255
+ /**
1256
+ * Declares what signing in to a vendor's account does. The identity function, as
1257
+ * `defineTransport` is: what it adds is the type, for a module written in JavaScript.
1258
+ *
1259
+ * @param module - The steps.
1260
+ * @returns The same steps.
1261
+ */
1262
+ declare function defineAccount(module: AccountModule): AccountModule;
1263
+ /** What an account module default-exports: a function of the SDK. */
1264
+ type AccountFactory = (sdk: BundleSdk) => AccountModule;
1265
+ /**
1266
+ * One account signed in to, as a vendor's transport and listener are handed it.
1267
+ *
1268
+ * `credentials` are what the owner typed, secrets opened - for a module that signs in again with
1269
+ * the password when the session expired; `session` is what the last sign-in kept. A transport
1270
+ * that finds the session refused signs in again and keeps the new one (`update`); one that cannot
1271
+ * - the cloud wants the owner again - says so (`needsSignIn`), and the account's card asks.
1272
+ */
1273
+ type AccountHandle = {
1274
+ readonly id: string;
1275
+ readonly label: string;
1276
+ readonly status: 'connected' | 'needs-sign-in' | 'failed';
1277
+ readonly credentials: JsonObject;
1278
+ readonly session: JsonObject;
1279
+ /**
1280
+ * Keeps a new session - tokens renewed - for this run and the next.
1281
+ *
1282
+ * @returns Once it is stored.
1283
+ */
1284
+ readonly update: (session: JsonObject) => Promise<void>;
1285
+ /**
1286
+ * Says the account needs the owner to sign in again, and why; its devices stop until then.
1287
+ *
1288
+ * @returns Once it is recorded.
1289
+ */
1290
+ readonly needsSignIn: (message: string) => Promise<void>;
1291
+ };
1292
+ //#endregion
1293
+ //#region ../package-runtime/dist/discovery.d.ts
1294
+ /**
1295
+ * What a listening source heard: a device, how to reach it, and what it said.
1296
+ *
1297
+ * `config` is what reaches it in the transport's own terms - `{ host }` - and becomes the
1298
+ * device's connection once adopted. `payload` is what identity and match read.
1299
+ */
1300
+ type Sighting = {
1301
+ readonly config: JsonObject;
1302
+ readonly payload: JsonObject;
1303
+ };
1304
+ /** How a listener is getting on, as the vendor's page says it. */
1305
+ type ListenerStatus = {
1306
+ /** `ok` hears what it listens to; `warning` listens but hears nothing; `error` cannot listen. */
1307
+ readonly level: 'ok' | 'warning' | 'error';
1308
+ /** A sentence for the owner: where it listens, and what to look at when it hears nothing. */
1309
+ readonly message: string;
1310
+ };
1311
+ /**
1312
+ * A device a listener heard and does not report, and why: one its vendor does not support, one
1313
+ * still being paired. The vendor's page lists them, so "why is my device not here" has an answer.
1314
+ */
1315
+ type PassedOverSighting = {
1316
+ /** What tells it from the others: its IEEE address, its id on the account. */
1317
+ readonly id: string;
1318
+ readonly name: string;
1319
+ readonly model?: string | null;
1320
+ /** Why it is not added, in a sentence: `Zigbee2MQTT is still pairing it`. */
1321
+ readonly reason: string;
1322
+ };
1323
+ /** What the hub hands a listener beside the signal. */
1324
+ type DiscoveryListenContext = {
1325
+ /**
1326
+ * Reads what the owner saved for the vendor - an account, a key - secrets opened, for a
1327
+ * listener that asks a cloud which devices the account has. Read it at every pass rather than
1328
+ * once: a change the owner saves is then heard without the listener being started again.
1329
+ *
1330
+ * @returns The vendor's settings; empty while it is not set up.
1331
+ */
1332
+ readonly settings: () => Promise<JsonObject>;
1333
+ /**
1334
+ * Says how listening goes - connected to a broker but hearing nothing, unable to
1335
+ * reach it - which the vendor's page shows. The last one said stands until the next. Optional
1336
+ * for the hub to offer, so a listener calls it as `context.status?.(…)`.
1337
+ */
1338
+ readonly status?: (status: ListenerStatus) => void;
1339
+ /**
1340
+ * Every device the listener hears and does not report, the whole list each time -
1341
+ * it replaces the last one. Optional for the hub to offer, like `status`.
1342
+ */
1343
+ readonly passedOver?: (devices: readonly PassedOverSighting[]) => void;
1344
+ /**
1345
+ * Every account of the vendor signed in to, for a listener that asks each which
1346
+ * devices it has. Read it at every pass, like the settings: an account added is heard then.
1347
+ *
1348
+ * @returns The accounts; none for a vendor without, or before one is signed in to.
1349
+ */
1350
+ readonly accounts?: () => Promise<readonly AccountHandle[]>;
1351
+ };
1352
+ /** A vendor's own listener, for a protocol the platform does not speak. */
1353
+ type DiscoverySource = {
1354
+ /**
1355
+ * Listens until the signal ends it, reporting every device heard.
1356
+ *
1357
+ * @param signal - Ends the listening.
1358
+ * @param context - The vendor's settings, for a listener that needs them.
1359
+ * @returns Every sighting, as it happens. The same device may be reported again.
1360
+ */
1361
+ listen: (signal: AbortSignal, context: DiscoveryListenContext) => AsyncIterable<Sighting>;
1362
+ /**
1363
+ * Asks the network again now, rather than at the listener's own next pass: what the owner's
1364
+ * "look for devices" reaches. Optional, for a listener that only ever hears announcements and
1365
+ * has nothing to ask. Answers arrive through `listen`, like every other sighting.
1366
+ */
1367
+ scan?: () => void;
1368
+ };
1369
+ /** What a discovery module default-exports. */
1370
+ type DiscoverySourceFactory = (sdk: BundleSdk) => DiscoverySource;
1371
+ /**
1372
+ * What the platform's mDNS source reports, which a vendor's match and identity read.
1373
+ *
1374
+ * `txt` holds the service's TXT record as text; a key with no value reads as an empty string.
1375
+ */
1376
+ type MdnsAnnouncement = {
1377
+ readonly service: string;
1378
+ readonly instance: string;
1379
+ readonly host: string;
1380
+ readonly address: string;
1381
+ readonly port: number;
1382
+ readonly txt: Readonly<Record<string, string>>;
1383
+ };
1384
+ //#endregion
1385
+ //#region src/modules.d.ts
1386
+ /**
1387
+ * Types a transport module: `manifest.json`'s `transports`. The transport it builds must call
1388
+ * itself `<vendor>/<name>`, the name the manifest gives it.
1389
+ *
1390
+ * @param factory - Builds the transport from the SDK, with `sdk.defineTransport`.
1391
+ * @returns The factory, as the module's default export.
1392
+ */
1393
+ export declare function defineTransportModule(factory: TransportFactory): TransportFactory;
1394
+ /**
1395
+ * Types a code driver's module: `driver.json`'s `entry`, for a driver whose entities depend on
1396
+ * what the device says.
1397
+ *
1398
+ * @param factory - Builds the integration from the SDK.
1399
+ * @returns The factory, as the module's default export.
1400
+ */
1401
+ export declare function defineDriverModule(factory: IntegrationFactory): IntegrationFactory;
1402
+ /**
1403
+ * Types a discovery module: `discovery.json`'s `{ "module": "./lan/discovery.js" }`, a listener
1404
+ * of the vendor's own for a protocol the platform does not speak.
1405
+ *
1406
+ * @param factory - Builds what listens, from the SDK.
1407
+ * @returns The factory, as the module's default export.
1408
+ */
1409
+ export declare function defineDiscoveryModule(factory: DiscoverySourceFactory): DiscoverySourceFactory;
1410
+ /**
1411
+ * Types an account module: `account.json`'s `module`, which signs in to the account the
1412
+ * vendor's devices are reached through.
1413
+ *
1414
+ * @param factory - Builds the sign-in from the SDK, with `sdk.defineAccount`.
1415
+ * @returns The factory, as the module's default export.
1416
+ */
1417
+ export declare function defineAccountModule(factory: AccountFactory): AccountFactory;
1418
+ /**
1419
+ * Types a stream module: `manifest.json`'s `streams`, a camera's source. It must call itself
1420
+ * `<vendor>/<name>`.
1421
+ *
1422
+ * @param factory - Builds the source from the SDK, with `sdk.defineStreamSource`.
1423
+ * @returns The factory, as the module's default export.
1424
+ */
1425
+ export declare function defineStreamModule(factory: StreamFactory): StreamFactory;
1426
+ //#endregion
1427
+ export type { AccountFactory, AccountHandle, AccountIdentity, AccountModule, AccountModuleStep, AccountStepContext, BundleCodecs, BundleImages, BundleLogFn, BundleLogger, BundleSdk, Claim, CommandTarget, DeviceDescriptor, DeviceInfo, Discovered, DiscoveryListenContext, DiscoverySource, DiscoverySourceFactory, EntityDescriptor, ImageBlob, Integration, IntegrationFactory, ListenerStatus, ManagedMqtt, ManagedMqttOptions, ManagedSocket, ManagedSocketClose, ManagedSocketHeaders, ManagedSocketOptions, ManagedUdpSocket, ManagedUdpSocketOptions, MappingContext, MdnsAnnouncement, OpenMqtt, OpenRtsp, OpenUdpSocket, OpenWebSocket, PaletteColour, PalettedPicture, PassedOverSighting, PlatformMqtt, PlatformServices, ReportedState, RtspFrame, RtspOptions, Sighting, StreamFactory, StreamFrame, StreamRequest, StreamSink, StreamSource, StreamSourceSpec, StreamTrack, Transport, TransportConnection, TransportContext, TransportFactory, TransportInbound, TransportLookContext, TransportRequest, TransportSpec, TransportStatus, TransportSubscription, UdpPeer };