@nebulahome/integration-sdk 1.9.0 → 1.10.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.
@@ -106,6 +106,9 @@ const ENTITY_DOMAINS = [
106
106
  "select",
107
107
  "number",
108
108
  "vacuum",
109
+ "fan",
110
+ "device_tracker",
111
+ "geo_location",
109
112
  "image",
110
113
  "custom",
111
114
  "alias"
@@ -166,6 +169,32 @@ function composeEntityId(domain, deviceId, objectId) {
166
169
  return formatEntityId(domain, `${slugify(deviceId).slice(0, room)}${suffix}`);
167
170
  }
168
171
  //#endregion
172
+ //#region ../contracts/dist/json.js
173
+ /**
174
+ * The JSON value type used wherever the platform stores or transports free-form data.
175
+ *
176
+ * Several columns are `jsonb` and several bus payloads carry caller-defined objects. Typing
177
+ * those as `unknown` pushes a cast onto every reader; typing them as `any` disables the rules
178
+ * that make this codebase safe. `JsonValue` is the honest middle: it says exactly what can be
179
+ * there, and it round-trips through `JSON.stringify` without loss.
180
+ */
181
+ /**
182
+ * Validates any JSON value, to any depth.
183
+ *
184
+ * Recursive by construction, so the annotation is required: TypeScript cannot infer the type of
185
+ * a schema that refers to itself.
186
+ */
187
+ const jsonValueSchema = z.lazy(() => z.union([
188
+ z.string(),
189
+ z.number(),
190
+ z.boolean(),
191
+ z.null(),
192
+ z.array(jsonValueSchema),
193
+ z.record(z.string(), jsonValueSchema)
194
+ ]));
195
+ /** Validates a JSON object. */
196
+ const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
197
+ //#endregion
169
198
  //#region ../contracts/dist/package-id.js
170
199
  /**
171
200
  * A package's identifier, apart from the manifest: the integrations' instance ids share its
@@ -227,6 +256,7 @@ const CAPABILITIES = [
227
256
  "level",
228
257
  "color_hs",
229
258
  "color_temp",
259
+ "effect",
230
260
  "cover",
231
261
  "lock",
232
262
  "thermostat",
@@ -241,42 +271,26 @@ const CAPABILITIES = [
241
271
  "select",
242
272
  "number",
243
273
  "vacuum",
274
+ "fan",
275
+ "location",
244
276
  "image",
245
277
  "custom"
246
278
  ];
247
279
  /** Validates a capability name. */
248
280
  const capabilityNameSchema = z.enum(CAPABILITIES);
249
- /**
250
- * How long a device may take to reach a commanded value.
251
- *
252
- * Bounded at ten minutes: a longer transition is a scene or an automation, not a command, and an
253
- * unbounded value would hold a command slot open indefinitely.
254
- */
255
- const transitionMsSchema = z.int().min(0).max(6e5).optional();
256
281
  /** Capabilities that report only, and accept no commands at all. */
257
282
  const NO_COMMANDS = null;
258
283
  /** Whether the entity is on. */
259
284
  const onOffStateSchema = z.object({ isOn: z.boolean() });
260
285
  /**
261
- * Whether the device can fade in and out rather than switch at once - a dimmable lamp that
262
- * takes a transition. Nothing else about turning on and off differs from one device to another.
263
- */
264
- const onOffParamsSchema = z.object({ hasTransition: z.boolean().default(false) });
265
- /**
266
- * Turning an entity on, off, or to the opposite of what it is now.
267
- *
268
- * On and off can fade where the device says it can; a toggle cannot, because whether it fades in
269
- * or out depends on a state the command does not know.
286
+ * Whether what the entity is said to be is only assumed: a relay or a 433 MHz socket that never
287
+ * reports back, so its state is the last command sent, not a reading.
270
288
  */
289
+ const onOffParamsSchema = z.object({ isAssumed: z.boolean().default(false) });
290
+ /** Turning an entity on, off, or to the opposite of what it is now. */
271
291
  const onOffCommandSchema = z.discriminatedUnion("command", [
272
- z.object({
273
- command: z.literal("turn_on"),
274
- transitionMs: transitionMsSchema
275
- }),
276
- z.object({
277
- command: z.literal("turn_off"),
278
- transitionMs: transitionMsSchema
279
- }),
292
+ z.object({ command: z.literal("turn_on") }),
293
+ z.object({ command: z.literal("turn_off") }),
280
294
  z.object({ command: z.literal("toggle") })
281
295
  ]);
282
296
  /**
@@ -286,33 +300,46 @@ const onOffCommandSchema = z.discriminatedUnion("command", [
286
300
  * that an automation written for one lamp works on another.
287
301
  */
288
302
  const levelStateSchema = z.object({ level: z.number().min(0).max(100) });
289
- /** Whether the device can fade rather than jump to a new level. */
290
- const levelParamsSchema = z.object({ hasTransition: z.boolean().default(false) });
291
- /** Setting the level, optionally over time. */
303
+ /** A level has no limits of its own: every percentage is representable. */
304
+ const levelParamsSchema = z.object({});
305
+ /** Setting the level. */
292
306
  const levelCommandSchema = z.discriminatedUnion("command", [z.object({
293
307
  command: z.literal("set_level"),
294
- level: z.number().min(0).max(100),
295
- transitionMs: transitionMsSchema
308
+ level: z.number().min(0).max(100)
296
309
  })]);
297
- /** Colour as hue and saturation. */
310
+ /**
311
+ * Colour as hue and saturation; on a lamp with a separate white channel (RGBW), how bright that
312
+ * channel is; and, on a lamp that also takes a colour temperature, whether it shows the colour
313
+ * now rather than the white - the one of the two it last took.
314
+ */
298
315
  const colorHsStateSchema = z.object({
299
316
  hue: z.number().min(0).max(360),
300
- saturation: z.number().min(0).max(100)
317
+ saturation: z.number().min(0).max(100),
318
+ white: z.number().min(0).max(100).optional(),
319
+ isActive: z.boolean().optional()
301
320
  });
302
321
  /**
303
- * Whether the lamp can fade from one colour to the next. Every hue and saturation is
322
+ * Whether the lamp has a white channel of its own beside the colour. Every hue and saturation is
304
323
  * representable, so there is nothing else to say.
305
324
  */
306
- const colorHsParamsSchema = z.object({ hasTransition: z.boolean().default(false) });
307
- /** Setting the colour, optionally over time. */
325
+ const colorHsParamsSchema = z.object({ hasWhiteChannel: z.boolean().default(false) });
326
+ /** Setting the colour, or the white channel. */
308
327
  const colorHsCommandSchema = z.discriminatedUnion("command", [z.object({
309
328
  command: z.literal("set_color"),
310
329
  hue: z.number().min(0).max(360),
311
- saturation: z.number().min(0).max(100),
312
- transitionMs: transitionMsSchema
330
+ saturation: z.number().min(0).max(100)
331
+ }), z.object({
332
+ command: z.literal("set_white"),
333
+ white: z.number().min(0).max(100)
313
334
  })]);
314
- /** Colour temperature in mireds, the reciprocal scale Matter and Zigbee both use. */
315
- const colorTempStateSchema = z.object({ mireds: z.int().min(1).max(1e3) });
335
+ /**
336
+ * Colour temperature in mireds, the reciprocal scale Matter and Zigbee both use; and, on a lamp
337
+ * that also takes a colour, whether it shows this white now rather than the colour.
338
+ */
339
+ const colorTempStateSchema = z.object({
340
+ mireds: z.int().min(1).max(1e3),
341
+ isActive: z.boolean().optional()
342
+ });
316
343
  /**
317
344
  * The mired range this particular lamp supports.
318
345
  *
@@ -321,15 +348,27 @@ const colorTempStateSchema = z.object({ mireds: z.int().min(1).max(1e3) });
321
348
  */
322
349
  const colorTempParamsSchema = z.object({
323
350
  minMireds: z.int().min(1).max(1e3),
324
- maxMireds: z.int().min(1).max(1e3),
325
- /** Whether the lamp can fade from one temperature to the next. */
326
- hasTransition: z.boolean().default(false)
351
+ maxMireds: z.int().min(1).max(1e3)
327
352
  }).refine((params) => params.minMireds <= params.maxMireds, { message: "minMireds must not exceed maxMireds" });
328
- /** Setting the colour temperature, optionally over time. */
353
+ /** Setting the colour temperature. */
329
354
  const colorTempCommandSchema = z.discriminatedUnion("command", [z.object({
330
355
  command: z.literal("set_color_temp"),
331
- mireds: z.int().min(1).max(1e3),
332
- transitionMs: transitionMsSchema
356
+ mireds: z.int().min(1).max(1e3)
357
+ })]);
358
+ /** An effect's name as the device calls it: shown as it is, never translated. */
359
+ const effectNameSchema = z.string().min(1).max(64);
360
+ /**
361
+ * The effect a lamp or a strip is running - a colour loop, a candle flicker - or null when none
362
+ * is. The names are the device's own; Matter has no effects, so this is what the adapters of the
363
+ * lamps that do (WLED, Hue, Shelly RGBW) map onto.
364
+ */
365
+ const effectStateSchema = z.object({ effect: effectNameSchema.nullable().default(null) });
366
+ /** The effects this device offers, in the order it lists them. */
367
+ const effectParamsSchema = z.object({ effects: z.array(effectNameSchema).min(1).max(256) });
368
+ /** Starting one of the effects, or stopping the one running with null. */
369
+ const effectCommandSchema = z.discriminatedUnion("command", [z.object({
370
+ command: z.literal("set_effect"),
371
+ effect: effectNameSchema.nullable()
333
372
  })]);
334
373
  /** How far a cover is open, how it is tilted, and whether it is moving. */
335
374
  const coverStateSchema = z.object({
@@ -366,21 +405,48 @@ const coverCommandSchema = z.discriminatedUnion("command", [
366
405
  * `jammed` is a first-class state rather than an error: a lock that failed to throw is a fact
367
406
  * about the house that the interface has to show, not a transient failure to retry.
368
407
  */
369
- const lockStateSchema = z.object({ lockState: z.enum([
370
- "locked",
371
- "unlocked",
372
- "jammed"
373
- ]) });
374
- /** Whether the lock requires a code to be operated remotely. */
375
- const lockParamsSchema = z.object({ hasCode: z.boolean().default(false) });
376
- /** Operating the bolt. */
377
- const lockCommandSchema = z.discriminatedUnion("command", [z.object({
378
- command: z.literal("lock"),
379
- code: z.string().min(1).max(64).optional()
380
- }), z.object({
381
- command: z.literal("unlock"),
382
- code: z.string().min(1).max(64).optional()
383
- })]);
408
+ const lockStateSchema = z.object({
409
+ lockState: z.enum([
410
+ "locked",
411
+ "unlocked",
412
+ "jammed"
413
+ ]),
414
+ /**
415
+ * Where the bolt or the latch is going, while it moves: a lock that says so, rather than jumping
416
+ * from one state to the next. Absent when it stands still.
417
+ */
418
+ motion: z.enum([
419
+ "locking",
420
+ "unlocking",
421
+ "opening"
422
+ ]).optional(),
423
+ /** On a lock that can pull its latch: whether the door is held open (Matter's Unlatched). */
424
+ isOpen: z.boolean().optional()
425
+ });
426
+ /**
427
+ * Whether the lock requires a code to be operated remotely, how many digits that code has when
428
+ * the lock says, and whether it can also pull the latch to open the door.
429
+ */
430
+ const lockParamsSchema = z.object({
431
+ hasCode: z.boolean().default(false),
432
+ codeLength: z.int().min(1).max(16).optional(),
433
+ canOpen: z.boolean().default(false)
434
+ });
435
+ /** Operating the bolt, or pulling the latch. */
436
+ const lockCommandSchema = z.discriminatedUnion("command", [
437
+ z.object({
438
+ command: z.literal("lock"),
439
+ code: z.string().min(1).max(64).optional()
440
+ }),
441
+ z.object({
442
+ command: z.literal("unlock"),
443
+ code: z.string().min(1).max(64).optional()
444
+ }),
445
+ z.object({
446
+ command: z.literal("open"),
447
+ code: z.string().min(1).max(64).optional()
448
+ })
449
+ ]);
384
450
  /** The operating modes a thermostat may be set to. */
385
451
  const THERMOSTAT_MODES = [
386
452
  "off",
@@ -390,41 +456,100 @@ const THERMOSTAT_MODES = [
390
456
  "fan_only",
391
457
  "dry"
392
458
  ];
459
+ /** What a thermostat is currently doing, which is not the same as the mode it is set to. */
460
+ const THERMOSTAT_ACTIONS = [
461
+ "off",
462
+ "idle",
463
+ "heating",
464
+ "cooling",
465
+ "drying",
466
+ "fan",
467
+ "preheating",
468
+ "defrosting"
469
+ ];
470
+ /** A name from one of a thermostat's lists - a preset, a fan mode, a swing - as it calls it. */
471
+ const thermostatChoiceSchema = z.string().min(1).max(64);
472
+ /** One of a thermostat's lists of names, in the order it offers them; empty when it has none. */
473
+ const thermostatChoicesSchema = z.array(thermostatChoiceSchema).max(64).default([]);
393
474
  /**
394
475
  * Measured and target temperature, the mode it is set to, and what it is doing.
395
476
  *
396
477
  * `mode` and `action` are distinct: a thermostat set to `auto` that has reached its target is
397
478
  * `idle`, and an interface showing only the mode could not explain why nothing is running.
479
+ *
480
+ * The measured temperature is absent on a unit that does not measure the room (Matter's
481
+ * LocalTemperature is nullable). A unit with a range keeps the low and the high apart, beside the
482
+ * single target it works to now. The preset, fan mode and swings are the names from its lists.
398
483
  */
399
484
  const thermostatStateSchema = z.object({
400
- currentTemperature: z.number(),
485
+ currentTemperature: z.number().optional(),
401
486
  targetTemperature: z.number(),
487
+ targetTemperatureLow: z.number().optional(),
488
+ targetTemperatureHigh: z.number().optional(),
402
489
  mode: z.enum(THERMOSTAT_MODES),
403
- action: z.enum([
404
- "off",
405
- "idle",
406
- "heating",
407
- "cooling",
408
- "drying",
409
- "fan"
410
- ]),
411
- humidity: z.number().min(0).max(100).optional()
490
+ action: z.enum(THERMOSTAT_ACTIONS),
491
+ humidity: z.number().min(0).max(100).optional(),
492
+ targetHumidity: z.number().min(0).max(100).optional(),
493
+ preset: thermostatChoiceSchema.nullable().optional(),
494
+ fanMode: thermostatChoiceSchema.optional(),
495
+ swingMode: thermostatChoiceSchema.optional(),
496
+ swingHorizontalMode: thermostatChoiceSchema.optional()
412
497
  });
413
- /** The modes and the range this particular thermostat accepts. */
498
+ /**
499
+ * The modes and the range this particular thermostat accepts; whether it keeps a low and a high
500
+ * rather than one target, and a humidity target within its own range; and its lists of presets,
501
+ * fan modes and swings, up and down and side to side.
502
+ */
414
503
  const thermostatParamsSchema = z.object({
415
504
  supportedModes: z.array(z.enum(THERMOSTAT_MODES)).min(1),
416
505
  minTemperature: z.number(),
417
506
  maxTemperature: z.number(),
418
- temperatureStep: z.number().gt(0).default(.5)
419
- }).refine((params) => params.minTemperature <= params.maxTemperature, { message: "minTemperature must not exceed maxTemperature" });
420
- /** Setting the target temperature or the mode. */
421
- const thermostatCommandSchema = z.discriminatedUnion("command", [z.object({
422
- command: z.literal("set_target"),
423
- temperature: z.number()
424
- }), z.object({
425
- command: z.literal("set_mode"),
426
- mode: z.enum(THERMOSTAT_MODES)
427
- })]);
507
+ temperatureStep: z.number().gt(0).default(.5),
508
+ hasTargetRange: z.boolean().default(false),
509
+ hasTargetHumidity: z.boolean().default(false),
510
+ minHumidity: z.number().min(0).max(100).default(30),
511
+ maxHumidity: z.number().min(0).max(100).default(99),
512
+ presets: thermostatChoicesSchema,
513
+ fanModes: thermostatChoicesSchema,
514
+ swingModes: thermostatChoicesSchema,
515
+ swingHorizontalModes: thermostatChoicesSchema
516
+ }).refine((params) => params.minTemperature <= params.maxTemperature, { message: "minTemperature must not exceed maxTemperature" }).refine((params) => params.minHumidity <= params.maxHumidity, { message: "minHumidity must not exceed maxHumidity" });
517
+ /** Setting the target, the range, the humidity, the mode, or one of the named choices. */
518
+ const thermostatCommandSchema = z.discriminatedUnion("command", [
519
+ z.object({
520
+ command: z.literal("set_target"),
521
+ temperature: z.number()
522
+ }),
523
+ z.object({
524
+ command: z.literal("set_target_range"),
525
+ low: z.number(),
526
+ high: z.number()
527
+ }),
528
+ z.object({
529
+ command: z.literal("set_humidity"),
530
+ humidity: z.number().min(0).max(100)
531
+ }),
532
+ z.object({
533
+ command: z.literal("set_mode"),
534
+ mode: z.enum(THERMOSTAT_MODES)
535
+ }),
536
+ z.object({
537
+ command: z.literal("set_preset"),
538
+ preset: thermostatChoiceSchema.nullable()
539
+ }),
540
+ z.object({
541
+ command: z.literal("set_fan_mode"),
542
+ fanMode: thermostatChoiceSchema
543
+ }),
544
+ z.object({
545
+ command: z.literal("set_swing"),
546
+ swingMode: thermostatChoiceSchema
547
+ }),
548
+ z.object({
549
+ command: z.literal("set_swing_horizontal"),
550
+ swingMode: thermostatChoiceSchema
551
+ })
552
+ ]);
428
553
  /**
429
554
  * A single numeric reading.
430
555
  *
@@ -447,32 +572,65 @@ const sensorBinaryParamsSchema = z.object({});
447
572
  * string. Physical adapters that need longer text belong in attributes, not here.
448
573
  */
449
574
  const sensorTextStateSchema = z.object({ value: z.string().max(512) });
450
- /** `sensor_text` has no commandable limits; its metadata lives on the entity row. */
451
- const sensorTextParamsSchema = z.object({});
452
- /** Playback position, volume, input and what is playing. */
575
+ /**
576
+ * The values a text sensor can take, when it is one of a fixed list (a washing machine's phase,
577
+ * an alarm's state): the order they come in, so its history can be drawn as a band coloured by
578
+ * value. Empty for free text. Its other metadata lives on the entity row.
579
+ */
580
+ const sensorTextParamsSchema = z.object({ options: z.array(z.string().min(1).max(128)).max(64).default([]) });
581
+ /** What a player is doing right now. */
582
+ const PLAYBACK_STATES = [
583
+ "playing",
584
+ "paused",
585
+ "stopped",
586
+ "idle",
587
+ "buffering"
588
+ ];
589
+ /** How a player repeats what it plays. */
590
+ const REPEAT_MODES = [
591
+ "off",
592
+ "all",
593
+ "one"
594
+ ];
595
+ /**
596
+ * Playback position, volume, input and what is playing; the sound mode, shuffle and repeat of a
597
+ * player that has them; and where the artwork of what is playing can be fetched - a path, for
598
+ * the reason the camera's snapshot is one.
599
+ *
600
+ * Whether the player is on is not here: a player that can be switched on and off declares
601
+ * `on_off` beside this, as a lamp does.
602
+ */
453
603
  const mediaPlayerStateSchema = z.object({
454
- playback: z.enum([
455
- "playing",
456
- "paused",
457
- "stopped",
458
- "idle",
459
- "buffering"
460
- ]),
604
+ playback: z.enum(PLAYBACK_STATES),
461
605
  volume: z.number().min(0).max(100),
462
606
  isMuted: z.boolean(),
463
607
  source: z.string().max(128).optional(),
608
+ soundMode: z.string().max(128).optional(),
609
+ isShuffled: z.boolean().optional(),
610
+ repeat: z.enum(REPEAT_MODES).optional(),
464
611
  mediaTitle: z.string().max(512).optional(),
465
612
  mediaArtist: z.string().max(512).optional(),
613
+ mediaAlbum: z.string().max(512).optional(),
614
+ mediaImagePath: z.string().max(1024).optional(),
466
615
  mediaDurationSeconds: z.number().min(0).optional(),
467
616
  mediaPositionSeconds: z.number().min(0).optional()
468
617
  });
469
- /** The inputs this player exposes and which transport controls it honours. */
618
+ /**
619
+ * The inputs and sound modes this player exposes, and which controls it honours: stop and
620
+ * skipping, which most do; volume as a level or only one step up and down; shuffle and repeat.
621
+ */
470
622
  const mediaPlayerParamsSchema = z.object({
471
623
  supportedSources: z.array(z.string().max(128)).default([]),
624
+ soundModes: z.array(z.string().max(128)).max(64).default([]),
472
625
  hasSeek: z.boolean().default(false),
473
- hasVolume: z.boolean().default(true)
626
+ hasVolume: z.boolean().default(true),
627
+ hasVolumeStep: z.boolean().default(false),
628
+ canStop: z.boolean().default(true),
629
+ canSkip: z.boolean().default(true),
630
+ hasShuffle: z.boolean().default(false),
631
+ hasRepeat: z.boolean().default(false)
474
632
  });
475
- /** Transport and volume control. */
633
+ /** Transport, volume, input and sound control. */
476
634
  const mediaPlayerCommandSchema = z.discriminatedUnion("command", [
477
635
  z.object({ command: z.literal("play") }),
478
636
  z.object({ command: z.literal("pause") }),
@@ -487,6 +645,8 @@ const mediaPlayerCommandSchema = z.discriminatedUnion("command", [
487
645
  command: z.literal("set_volume"),
488
646
  volume: z.number().min(0).max(100)
489
647
  }),
648
+ z.object({ command: z.literal("volume_up") }),
649
+ z.object({ command: z.literal("volume_down") }),
490
650
  z.object({
491
651
  command: z.literal("set_mute"),
492
652
  isMuted: z.boolean()
@@ -494,6 +654,18 @@ const mediaPlayerCommandSchema = z.discriminatedUnion("command", [
494
654
  z.object({
495
655
  command: z.literal("set_source"),
496
656
  source: z.string().min(1).max(128)
657
+ }),
658
+ z.object({
659
+ command: z.literal("set_sound_mode"),
660
+ soundMode: z.string().min(1).max(128)
661
+ }),
662
+ z.object({
663
+ command: z.literal("set_shuffle"),
664
+ isShuffled: z.boolean()
665
+ }),
666
+ z.object({
667
+ command: z.literal("set_repeat"),
668
+ repeat: z.enum(REPEAT_MODES)
497
669
  })
498
670
  ]);
499
671
  /**
@@ -505,19 +677,31 @@ const mediaPlayerCommandSchema = z.discriminatedUnion("command", [
505
677
  const cameraStateSchema = z.object({
506
678
  isStreamAvailable: z.boolean(),
507
679
  snapshotPath: z.string().max(1024).optional(),
508
- isRecording: z.boolean().default(false)
680
+ isRecording: z.boolean().default(false),
681
+ isMotionDetectionOn: z.boolean().optional()
509
682
  });
510
- /** What this camera can produce. */
683
+ /**
684
+ * What this camera can produce, and whether its own motion detection can be switched from here.
685
+ * Whether the camera is on is `on_off` beside this, as a media player's is.
686
+ */
511
687
  const cameraParamsSchema = z.object({
512
688
  hasSnapshot: z.boolean().default(true),
513
689
  hasStream: z.boolean().default(true),
514
- hasRecording: z.boolean().default(false)
690
+ hasRecording: z.boolean().default(false),
691
+ hasMotionDetection: z.boolean().default(false)
515
692
  });
516
- /** Taking a still, or recording a clip of bounded length. */
517
- const cameraCommandSchema = z.discriminatedUnion("command", [z.object({ command: z.literal("snapshot") }), z.object({
518
- command: z.literal("record"),
519
- durationSeconds: z.int().min(1).max(3600)
520
- })]);
693
+ /** Taking a still, recording a clip of bounded length, or switching motion detection. */
694
+ const cameraCommandSchema = z.discriminatedUnion("command", [
695
+ z.object({ command: z.literal("snapshot") }),
696
+ z.object({
697
+ command: z.literal("record"),
698
+ durationSeconds: z.int().min(1).max(3600)
699
+ }),
700
+ z.object({
701
+ command: z.literal("set_motion_detection"),
702
+ isOn: z.boolean()
703
+ })
704
+ ]);
521
705
  /**
522
706
  * A button holds no state: pressing it is the whole of what it does.
523
707
  *
@@ -547,7 +731,12 @@ const updateStateSchema = z.object({
547
731
  installedVersion: z.string().min(1).max(64).nullable().default(null),
548
732
  latestVersion: z.string().min(1).max(64).nullable().default(null),
549
733
  isInstalling: z.boolean().default(false),
550
- progress: z.number().min(0).max(100).nullable().default(null)
734
+ progress: z.number().min(0).max(100).nullable().default(null),
735
+ /** What the maker calls this firmware, when it names it. */
736
+ title: z.string().min(1).max(128).optional(),
737
+ /** The maker's summary of what the version on offer changes, and where the full notes are. */
738
+ releaseSummary: z.string().min(1).max(4e3).optional(),
739
+ releaseUrl: z.url({ protocol: /^https?$/ }).max(1024).optional()
551
740
  });
552
741
  /** Whether the firmware can be installed from here, and whether its progress is reported. */
553
742
  const updateParamsSchema = z.object({
@@ -605,11 +794,25 @@ const VACUUM_ACTIVITIES = [
605
794
  "idle",
606
795
  "error"
607
796
  ];
608
- /** One room of a robot's map: its id on the map, and what the app calls it. */
797
+ /** A point of a room's outline, in percent of the map's width and height from its top left. */
798
+ const mapPointSchema = z.tuple([z.number().min(0).max(100), z.number().min(0).max(100)]);
799
+ /**
800
+ * One room of a robot's map: its id on the map, what the app calls it, and - from a robot that
801
+ * shares its map - the room's outline, so it can be drawn at its real shape.
802
+ */
609
803
  const vacuumRoomSchema = z.object({
610
804
  id: z.string().min(1).max(32),
611
- name: z.string().min(1).max(64)
805
+ name: z.string().min(1).max(64),
806
+ outline: z.array(mapPointSchema).min(3).max(64).optional()
612
807
  });
808
+ /** How a robot that can mop cleans: vacuuming, mopping, or both in one pass. */
809
+ const VACUUM_CLEAN_MODES = [
810
+ "vacuum",
811
+ "mop",
812
+ "vacuum_and_mop"
813
+ ];
814
+ /** A name from one of a robot's lists - a suction level, a water level - as it calls it. */
815
+ const vacuumChoiceSchema = z.string().min(1).max(64);
613
816
  /**
614
817
  * A robot vacuum's activity, the rooms of its map - which change when the map is edited in the
615
818
  * app, so they are state rather than a fixed parameter; empty for a robot without a map - and
@@ -618,16 +821,28 @@ const vacuumRoomSchema = z.object({
618
821
  const vacuumStateSchema = z.object({
619
822
  activity: z.enum(VACUUM_ACTIVITIES),
620
823
  rooms: z.array(vacuumRoomSchema).max(64).default([]),
621
- isResumable: z.boolean().default(false)
824
+ isResumable: z.boolean().default(false),
825
+ /** The suction level, the clean mode and the water level now, from the robot's own lists. */
826
+ fanSpeed: vacuumChoiceSchema.optional(),
827
+ cleanMode: z.enum(VACUUM_CLEAN_MODES).optional(),
828
+ waterLevel: vacuumChoiceSchema.optional()
622
829
  });
623
- /** Which of the commands this robot takes; `canResume` as a mower's. */
830
+ /**
831
+ * Which of the commands this robot takes - `canResume` as a mower's, `canCleanSpot` a clean of
832
+ * the floor round where it stands - and its lists: suction levels, the clean modes of a robot
833
+ * that mops, and its water levels. Empty lists for a robot without them.
834
+ */
624
835
  const vacuumParamsSchema = z.object({
625
836
  canPause: z.boolean().default(true),
626
837
  canStop: z.boolean().default(true),
627
838
  canDock: z.boolean().default(true),
628
839
  canLocate: z.boolean().default(false),
629
840
  canCleanRooms: z.boolean().default(false),
630
- canResume: z.boolean().default(false)
841
+ canResume: z.boolean().default(false),
842
+ canCleanSpot: z.boolean().default(false),
843
+ fanSpeeds: z.array(vacuumChoiceSchema).max(32).default([]),
844
+ cleanModes: z.array(z.enum(VACUUM_CLEAN_MODES)).default([]),
845
+ waterLevels: z.array(vacuumChoiceSchema).max(32).default([])
631
846
  });
632
847
  /**
633
848
  * Starting - or resuming a paused job - pausing, ending the job where it stands, sending the
@@ -644,6 +859,19 @@ const vacuumCommandSchema = z.discriminatedUnion("command", [
644
859
  z.object({
645
860
  command: z.literal("clean_rooms"),
646
861
  rooms: z.array(z.string().min(1).max(32)).min(1).max(32)
862
+ }),
863
+ z.object({ command: z.literal("clean_spot") }),
864
+ z.object({
865
+ command: z.literal("set_fan_speed"),
866
+ fanSpeed: vacuumChoiceSchema
867
+ }),
868
+ z.object({
869
+ command: z.literal("set_clean_mode"),
870
+ cleanMode: z.enum(VACUUM_CLEAN_MODES)
871
+ }),
872
+ z.object({
873
+ command: z.literal("set_water_level"),
874
+ waterLevel: vacuumChoiceSchema
647
875
  })
648
876
  ]);
649
877
  /** The pictures an image entity may be, as the browser draws them. */
@@ -723,11 +951,16 @@ const selectCommandSchema = z.discriminatedUnion("command", [z.object({
723
951
  * as a sensor's is.
724
952
  */
725
953
  const numberStateSchema = z.object({ value: z.number().nullable().default(null) });
726
- /** How low and how high the setting goes, and in what steps. */
954
+ /** How low and how high the setting goes, in what steps, and how it is set. */
727
955
  const numberParamsSchema = z.object({
728
956
  min: z.number(),
729
957
  max: z.number(),
730
- step: z.number().positive().default(1)
958
+ step: z.number().positive().default(1),
959
+ mode: z.enum([
960
+ "auto",
961
+ "slider",
962
+ "box"
963
+ ]).default("auto")
731
964
  }).refine((params) => params.min < params.max, {
732
965
  message: "min must be below max",
733
966
  path: ["max"]
@@ -737,6 +970,82 @@ const numberCommandSchema = z.discriminatedUnion("command", [z.object({
737
970
  command: z.literal("set_value"),
738
971
  value: z.number()
739
972
  })]);
973
+ /** Which way a fan's blades turn. */
974
+ const FAN_DIRECTIONS = ["forward", "reverse"];
975
+ /** A preset's name as the fan calls it. */
976
+ const fanPresetSchema = z.string().min(1).max(64);
977
+ /**
978
+ * A fan's speed as a percentage, the preset it runs, whether its head swings side to side, and
979
+ * which way its blades turn. Whether it is on is `on_off` beside this, as a lamp's is; each value
980
+ * here is absent on a fan that does not have it.
981
+ */
982
+ const fanStateSchema = z.object({
983
+ percentage: z.number().min(0).max(100).optional(),
984
+ preset: fanPresetSchema.nullable().optional(),
985
+ isOscillating: z.boolean().optional(),
986
+ direction: z.enum(FAN_DIRECTIONS).optional()
987
+ });
988
+ /**
989
+ * How many speeds the fan has (0: none, it only switches; a percentage then moves in steps of
990
+ * 100 / speedCount, as Matter's SpeedMax), its presets, and whether it can oscillate or reverse.
991
+ */
992
+ const fanParamsSchema = z.object({
993
+ speedCount: z.int().min(0).max(100).default(0),
994
+ presets: z.array(fanPresetSchema).max(32).default([]),
995
+ canOscillate: z.boolean().default(false),
996
+ canReverse: z.boolean().default(false)
997
+ });
998
+ /** Setting the speed, a preset, the swing or the direction. */
999
+ const fanCommandSchema = z.discriminatedUnion("command", [
1000
+ z.object({
1001
+ command: z.literal("set_percentage"),
1002
+ percentage: z.number().min(0).max(100)
1003
+ }),
1004
+ z.object({
1005
+ command: z.literal("set_preset"),
1006
+ preset: fanPresetSchema
1007
+ }),
1008
+ z.object({
1009
+ command: z.literal("set_oscillating"),
1010
+ isOscillating: z.boolean()
1011
+ }),
1012
+ z.object({
1013
+ command: z.literal("set_direction"),
1014
+ direction: z.enum(FAN_DIRECTIONS)
1015
+ })
1016
+ ]);
1017
+ /**
1018
+ * Where a location comes from: a GPS fix, or only seen on the network or over Bluetooth - which
1019
+ * says home or away and no position - or an event with a place of its own (an earthquake, a
1020
+ * fire), placed by its distance from the house.
1021
+ */
1022
+ const LOCATION_SOURCES = [
1023
+ "gps",
1024
+ "router",
1025
+ "bluetooth",
1026
+ "bluetooth_le",
1027
+ "event"
1028
+ ];
1029
+ /**
1030
+ * Where a tracked thing is (a phone, a car, a tag), or where an event happened.
1031
+ *
1032
+ * `zone` is `home`, `away`, or the name of the zone it is in; null until there is a fix. Only a
1033
+ * GPS source has a position; a router or Bluetooth source has the network facts instead; an
1034
+ * event has its distance from the house.
1035
+ */
1036
+ const locationStateSchema = z.object({
1037
+ zone: z.string().min(1).max(64).nullable().default(null),
1038
+ latitude: z.number().min(-90).max(90).optional(),
1039
+ longitude: z.number().min(-180).max(180).optional(),
1040
+ accuracyMeters: z.number().min(0).optional(),
1041
+ locationName: z.string().min(1).max(128).optional(),
1042
+ distanceKm: z.number().min(0).optional(),
1043
+ ipAddress: z.string().min(1).max(64).optional(),
1044
+ macAddress: z.string().min(1).max(32).optional(),
1045
+ hostName: z.string().min(1).max(128).optional()
1046
+ });
1047
+ /** Where this location comes from, which decides what it can say. */
1048
+ const locationParamsSchema = z.object({ source: z.enum(LOCATION_SOURCES).default("gps") });
740
1049
  /**
741
1050
  * Every capability, with its state, params and command schemas.
742
1051
  *
@@ -764,6 +1073,11 @@ const CAPABILITY_DEFINITIONS = {
764
1073
  params: colorTempParamsSchema,
765
1074
  commands: colorTempCommandSchema
766
1075
  },
1076
+ effect: {
1077
+ state: effectStateSchema,
1078
+ params: effectParamsSchema,
1079
+ commands: effectCommandSchema
1080
+ },
767
1081
  cover: {
768
1082
  state: coverStateSchema,
769
1083
  params: coverParamsSchema,
@@ -834,6 +1148,16 @@ const CAPABILITY_DEFINITIONS = {
834
1148
  params: vacuumParamsSchema,
835
1149
  commands: vacuumCommandSchema
836
1150
  },
1151
+ fan: {
1152
+ state: fanStateSchema,
1153
+ params: fanParamsSchema,
1154
+ commands: fanCommandSchema
1155
+ },
1156
+ location: {
1157
+ state: locationStateSchema,
1158
+ params: locationParamsSchema,
1159
+ commands: NO_COMMANDS
1160
+ },
837
1161
  image: {
838
1162
  state: imageStateSchema,
839
1163
  params: imageParamsSchema,
@@ -857,6 +1181,7 @@ const capabilityStateSchema = z.object({
857
1181
  level: levelStateSchema.optional(),
858
1182
  color_hs: colorHsStateSchema.optional(),
859
1183
  color_temp: colorTempStateSchema.optional(),
1184
+ effect: effectStateSchema.optional(),
860
1185
  cover: coverStateSchema.optional(),
861
1186
  lock: lockStateSchema.optional(),
862
1187
  thermostat: thermostatStateSchema.optional(),
@@ -871,36 +1196,12 @@ const capabilityStateSchema = z.object({
871
1196
  select: selectStateSchema.optional(),
872
1197
  number: numberStateSchema.optional(),
873
1198
  vacuum: vacuumStateSchema.optional(),
1199
+ fan: fanStateSchema.optional(),
1200
+ location: locationStateSchema.optional(),
874
1201
  image: imageStateSchema.optional(),
875
1202
  custom: customStateSchema.optional()
876
1203
  });
877
1204
  //#endregion
878
- //#region ../contracts/dist/json.js
879
- /**
880
- * The JSON value type used wherever the platform stores or transports free-form data.
881
- *
882
- * Several columns are `jsonb` and several bus payloads carry caller-defined objects. Typing
883
- * those as `unknown` pushes a cast onto every reader; typing them as `any` disables the rules
884
- * that make this codebase safe. `JsonValue` is the honest middle: it says exactly what can be
885
- * there, and it round-trips through `JSON.stringify` without loss.
886
- */
887
- /**
888
- * Validates any JSON value, to any depth.
889
- *
890
- * Recursive by construction, so the annotation is required: TypeScript cannot infer the type of
891
- * a schema that refers to itself.
892
- */
893
- const jsonValueSchema = z.lazy(() => z.union([
894
- z.string(),
895
- z.number(),
896
- z.boolean(),
897
- z.null(),
898
- z.array(jsonValueSchema),
899
- z.record(z.string(), jsonValueSchema)
900
- ]));
901
- /** Validates a JSON object. */
902
- const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
903
- //#endregion
904
1205
  //#region ../contracts/dist/timestamp.js
905
1206
  /**
906
1207
  * The one way a moment in time is validated at a boundary.
@@ -1423,6 +1724,22 @@ const listFieldSchema = z.strictObject({
1423
1724
  pattern: patternSchema.optional(),
1424
1725
  patternMessage: patternMessageSchema.optional()
1425
1726
  });
1727
+ /**
1728
+ * One entity of the house, chosen with the interface's entity picker: its address. Never a
1729
+ * default - no declaration knows what a house holds. For a package's settings and card options.
1730
+ */
1731
+ const entityFieldSchema = z.strictObject({
1732
+ ...fieldBase,
1733
+ type: z.literal("entity"),
1734
+ /** Only entities of these domains may be chosen; any when not said. */
1735
+ domains: z.array(z.enum(ENTITY_DOMAINS)).min(1).max(ENTITY_DOMAINS.length).optional()
1736
+ });
1737
+ /** One icon of the catalogue, chosen with the interface's icon picker: its id. */
1738
+ const iconFieldSchema = z.strictObject({
1739
+ ...fieldBase,
1740
+ type: z.literal("icon"),
1741
+ default: iconIdSchema.optional()
1742
+ });
1426
1743
  /** Validates one field of a group. */
1427
1744
  const setupFieldSchema = z.discriminatedUnion("type", [
1428
1745
  textFieldSchema,
@@ -1430,7 +1747,9 @@ const setupFieldSchema = z.discriminatedUnion("type", [
1430
1747
  numberFieldSchema,
1431
1748
  booleanFieldSchema,
1432
1749
  choiceFieldSchema,
1433
- listFieldSchema
1750
+ listFieldSchema,
1751
+ entityFieldSchema,
1752
+ iconFieldSchema
1434
1753
  ]);
1435
1754
  /** Validates one group: what the bundle fixes and what it asks. */
1436
1755
  const setupGroupSchema = z.strictObject({
@@ -1886,8 +2205,11 @@ const BUNDLE_ORIGINS = [
1886
2205
  * `hub/integrations/<vendor>/.nebula-install.json`, which names the build `hub` loads.
1887
2206
  */
1888
2207
  const integrationInstallSchema = z.strictObject({
1889
- /** The folder of the build, beside the marker: the version, then a nonce. */
1890
- build: z.string().regex(/^[0-9A-Za-z.+-]{1,96}$/u, "Must be a build folder name"),
2208
+ /**
2209
+ * The folder of the build, beside the marker: the version, then a nonce. Never `.` or one
2210
+ * containing `..`, which would name a folder outside the vendor's.
2211
+ */
2212
+ build: z.string().regex(/^(?!\.$)(?!.*\.\.)[0-9A-Za-z.+-]{1,96}$/u, "Must be a build folder name"),
1891
2213
  /** The bundle's version, as its manifest says it. */
1892
2214
  version: z.string().min(1).max(64),
1893
2215
  source: z.enum(["index", "local"]),
@@ -4401,6 +4723,8 @@ z.object({ isLoaded: z.boolean() });
4401
4723
  z.strictObject({ entityRowIds: z.array(z.uuid()).min(1).max(1024) });
4402
4724
  z.object({ synced: z.int().min(0) });
4403
4725
  z.strictObject({ entityId: entityIdSchema });
4726
+ z.object({ isLoaded: z.boolean() });
4727
+ z.strictObject({ entityId: entityIdSchema });
4404
4728
  z.object({ items: z.array(z.object({
4405
4729
  entityId: entityIdSchema,
4406
4730
  /** The instance it comes through. */
@@ -10268,15 +10592,6 @@ function clamp(value, min, max) {
10268
10592
  return Math.min(max, Math.max(min, value));
10269
10593
  }
10270
10594
  /**
10271
- * A fade in Matter's tenths of a second.
10272
- *
10273
- * @param transitionMs - The fade the command asks for, if any.
10274
- * @returns Tenths of a second; 0 for at once.
10275
- */
10276
- function tenthsOf(transitionMs) {
10277
- return typeof transitionMs === "number" ? Math.round(transitionMs / 100) : 0;
10278
- }
10279
- /**
10280
10595
  * A command invoked on a cluster.
10281
10596
  *
10282
10597
  * @param endpoint - The endpoint.
@@ -10298,8 +10613,12 @@ function invoke(endpoint, cluster, command, payload = {}, timedMs) {
10298
10613
  }
10299
10614
  };
10300
10615
  }
10301
- /** What every fade-capable command of the lighting clusters carries besides its own fields. */
10302
- const NO_OPTIONS = {
10616
+ /**
10617
+ * What every move command of the lighting clusters carries besides its own fields: Matter
10618
+ * requires a transition time, and 0 is at once.
10619
+ */
10620
+ const AT_ONCE = {
10621
+ transitionTime: 0,
10303
10622
  optionsMask: 0,
10304
10623
  optionsOverride: 0
10305
10624
  };
@@ -10327,13 +10646,12 @@ function onOffEntity(attributes, endpoint) {
10327
10646
  const minMireds = clamp(numberOf$1(attributeOf(attributes, endpoint, CLUSTER.colorControl, 16395)) ?? 153, 1, 1e3);
10328
10647
  const maxMireds = clamp(numberOf$1(attributeOf(attributes, endpoint, CLUSTER.colorControl, 16396)) ?? 500, minMireds, 1e3);
10329
10648
  const capabilities = {
10330
- on_off: { hasTransition: false },
10331
- ...hasLevel ? { level: { hasTransition: true } } : {},
10332
- ...hasHs ? { color_hs: { hasTransition: true } } : {},
10649
+ on_off: {},
10650
+ ...hasLevel ? { level: {} } : {},
10651
+ ...hasHs ? { color_hs: {} } : {},
10333
10652
  ...hasTemperature ? { color_temp: {
10334
10653
  minMireds,
10335
- maxMireds,
10336
- hasTransition: true
10654
+ maxMireds
10337
10655
  } } : {}
10338
10656
  };
10339
10657
  return {
@@ -10388,20 +10706,17 @@ function onOffEntity(attributes, endpoint) {
10388
10706
  const level = numberOf$1(command["level"]) ?? 0;
10389
10707
  return level <= 0 ? invoke(endpoint, CLUSTER.onOff, "off") : invoke(endpoint, CLUSTER.levelControl, "moveToLevelWithOnOff", {
10390
10708
  level: clamp(Math.round(level / 100 * 254), 1, 254),
10391
- transitionTime: tenthsOf(command["transitionMs"]),
10392
- ...NO_OPTIONS
10709
+ ...AT_ONCE
10393
10710
  });
10394
10711
  }
10395
10712
  case "set_color": return invoke(endpoint, CLUSTER.colorControl, "moveToHueAndSaturation", {
10396
10713
  hue: clamp(Math.round((numberOf$1(command["hue"]) ?? 0) / 360 * 254), 0, 254),
10397
10714
  saturation: clamp(Math.round((numberOf$1(command["saturation"]) ?? 0) / 100 * 254), 0, 254),
10398
- transitionTime: tenthsOf(command["transitionMs"]),
10399
- ...NO_OPTIONS
10715
+ ...AT_ONCE
10400
10716
  });
10401
10717
  case "set_color_temp": return invoke(endpoint, CLUSTER.colorControl, "moveToColorTemperature", {
10402
10718
  colorTemperatureMireds: clamp(Math.round(numberOf$1(command["mireds"]) ?? minMireds), minMireds, maxMireds),
10403
- transitionTime: tenthsOf(command["transitionMs"]),
10404
- ...NO_OPTIONS
10719
+ ...AT_ONCE
10405
10720
  });
10406
10721
  default: return;
10407
10722
  }
@@ -11414,8 +11729,6 @@ function modbusObjectIdOf(entity) {
11414
11729
  */
11415
11730
  function paramsOf(capability, map) {
11416
11731
  switch (capability) {
11417
- case "level": return { hasTransition: false };
11418
- case "on_off": return { hasTransition: false };
11419
11732
  case "number": return {
11420
11733
  min: map.write?.min ?? 0,
11421
11734
  max: map.write?.max ?? 1,
@@ -12067,7 +12380,7 @@ function mqttShapeOf(entity) {
12067
12380
  domain: "light",
12068
12381
  capabilities: {
12069
12382
  on_off: {},
12070
- ...hasLevel ? { level: { hasTransition: false } } : {},
12383
+ ...hasLevel ? { level: {} } : {},
12071
12384
  ...hasWhite ? { color_temp: {
12072
12385
  minMireds: Math.round(numberSetting(entity, "min_mireds", 153)),
12073
12386
  maxMireds: Math.round(numberSetting(entity, "max_mireds", 500))