@nebulahome/integration-sdk 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,17 @@
3
3
  The SDK's version is the version of the integration contract the platform implements: a minor
4
4
  version adds to the contract, a major one breaks it, and a patch leaves it as it is.
5
5
 
6
+ ## 1.9.0
7
+
8
+ A device whose entities depend on how it is set up.
9
+
10
+ - A code driver's `deviceInfo` may say `descriptor`: what the device is now - the claim's own
11
+ descriptor while it still is that, a new one once it was set up differently (a Bot switched from
12
+ press to switch mode in its vendor's app). When the device still says the new one thirty seconds
13
+ later, the hub describes it again from it: an entity described both times stays with its
14
+ history, one no longer described is removed with its history, one described only now is added.
15
+ The device's Activity says so, and the readings of a linked device are linked again.
16
+
6
17
  ## 1.8.0
7
18
 
8
19
  One device reached more than one way.
package/FILES.md CHANGED
@@ -394,6 +394,20 @@ A profile may also say where its reports carry the firmware the device runs now
394
394
  device's row as it hears it, so the device page follows an update without the device being added
395
395
  again.
396
396
 
397
+ A device whose entities depend on how it is set up - a Bot that is a switch in switch mode and a
398
+ button in press mode, a relay that is two switches or one cover - says so through a code driver's
399
+ `deviceInfo(message, context)`: `descriptor` is what the device is now. Return the claim's own
400
+ descriptor (`context.claim.descriptor`) while the message shows it is still set up that way, a new
401
+ descriptor once it shows otherwise, and leave `descriptor` out when the message does not say. A
402
+ new one is taken when the device still says it thirty seconds later; one message saying the
403
+ claim's own again drops it, so a misread advertisement changes nothing. The hub then describes
404
+ the device again from the new descriptor and keeps it as the claim: entities described both times
405
+ stay, with their history and the owner's names; one no longer described is removed, with its
406
+ history, and an automation using it says so; one described only now is added. The device's
407
+ Activity says what was removed and added, and on a linked device the readings of the same `key`
408
+ are linked again. Keep an entity's `objectId` the same in every setup where it is the same thing
409
+ (a battery), so it is never removed for nothing.
410
+
397
411
  The logo rides inside the catalogue the hub serves, as a data URL, so it must be an `.svg` or a
398
412
  `.png` and at most 64 KiB; anything else fails the vendor at startup. Draw a monogram in the
399
413
  vendor's colour - nobody's trademark -; the interface draws the same monogram itself for a vendor
@@ -4342,7 +4342,13 @@ z.strictObject({
4342
4342
  */
4343
4343
  config: jsonObjectSchema.default({}),
4344
4344
  /** At least one: a device row nothing points at is a device the interface cannot explain. */
4345
- entities: z.array(entityRegistrationSchema).min(1)
4345
+ entities: z.array(entityRegistrationSchema).min(1),
4346
+ /**
4347
+ * Whether these are all the entities the device has now - it was described again, set up
4348
+ * differently - so any other it had is removed, with its history. Left out, an entity is only
4349
+ * ever added or updated: a device heard again after a restart keeps what it had.
4350
+ */
4351
+ replacesEntities: z.boolean().optional()
4346
4352
  });
4347
4353
  /** One device a package has, with its entities. */
4348
4354
  const packageDeviceRegistrationSchema = z.object({
@@ -4410,7 +4416,21 @@ z.object({
4410
4416
  /** The integration instance or package that owns it. */
4411
4417
  source: sourceRefSchema,
4412
4418
  name: z.string().min(1).max(128),
4413
- entityIds: z.array(entityIdSchema)
4419
+ entityIds: z.array(entityIdSchema),
4420
+ /**
4421
+ * On `updated`, for a device described again because it was set up differently: the entities
4422
+ * removed and added, each by its address and its name then.
4423
+ */
4424
+ described: z.object({
4425
+ added: z.array(z.object({
4426
+ entityId: entityIdSchema,
4427
+ name: z.string().max(128)
4428
+ })),
4429
+ removed: z.array(z.object({
4430
+ entityId: entityIdSchema,
4431
+ name: z.string().max(128)
4432
+ }))
4433
+ }).optional()
4414
4434
  });
4415
4435
  //#endregion
4416
4436
  //#region ../contracts/dist/links.js
@@ -234,9 +234,8 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
234
234
  declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
235
235
  number: "number";
236
236
  custom: "custom";
237
- image: "image";
238
- level: "level";
239
237
  on_off: "on_off";
238
+ level: "level";
240
239
  color_hs: "color_hs";
241
240
  color_temp: "color_temp";
242
241
  cover: "cover";
@@ -252,6 +251,7 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
252
251
  lawn_mower: "lawn_mower";
253
252
  select: "select";
254
253
  vacuum: "vacuum";
254
+ image: "image";
255
255
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
256
256
  /** What an entity declares it can do, with the device's own limits for each. */
257
257
  type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
@@ -1392,7 +1392,8 @@ type Integration<TOptions = JsonObject> = {
1392
1392
  continueCommand?: (target: CommandTarget, step: CommandStep, context: MappingContext) => TransportRequest | null;
1393
1393
  /**
1394
1394
  * Reads what a message says about the device itself, beyond its entities: the firmware it runs
1395
- * now, which changes when it is updated and is otherwise only known from when it was found.
1395
+ * now, which changes when it is updated and is otherwise only known from when it was found;
1396
+ * and how it is set up, when that decides its entities (`descriptor`).
1396
1397
  *
1397
1398
  * Optional: an integration whose messages say nothing of the kind leaves it out.
1398
1399
  *
@@ -1422,6 +1423,17 @@ type StreamRequest = {
1422
1423
  type DeviceInfo = {
1423
1424
  readonly swVersion?: string;
1424
1425
  readonly hwVersion?: string;
1426
+ /**
1427
+ * What the device is now, for a device whose entities depend on how it is set up - a Bot in
1428
+ * switch or in press mode: the claim's own descriptor while it is still that, a new one to
1429
+ * describe it from once it changed. Left out when the message does not say.
1430
+ *
1431
+ * A new one is taken when the device still says it thirty seconds later - a message saying
1432
+ * the claim's own again drops it. The device is then described again: an entity
1433
+ * described both times stays, with its history; one no longer described is removed, with its
1434
+ * history; one described only now is added.
1435
+ */
1436
+ readonly descriptor?: unknown;
1425
1437
  };
1426
1438
  //#endregion
1427
1439
  //#region ../package-runtime/dist/stream.d.ts
@@ -830,7 +830,7 @@ function defineTransport(spec) {
830
830
  * bundle built with this SDK says `^<major>.<minor>.0`.
831
831
  */
832
832
  /** The SDK's own version: `1.0.0`, or a prerelease of it. */
833
- const SDK_VERSION = "1.8.0";
833
+ const SDK_VERSION = "1.9.0";
834
834
  /**
835
835
  * The runtime range a bundle built with this SDK declares: this version's major and minor, so a
836
836
  * platform with the same contract or a later one of the same major loads it.
package/dist/index.d.ts CHANGED
@@ -278,9 +278,8 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
278
278
  declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
279
279
  number: "number";
280
280
  custom: "custom";
281
- image: "image";
282
- level: "level";
283
281
  on_off: "on_off";
282
+ level: "level";
284
283
  color_hs: "color_hs";
285
284
  color_temp: "color_temp";
286
285
  cover: "cover";
@@ -296,6 +295,7 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
296
295
  lawn_mower: "lawn_mower";
297
296
  select: "select";
298
297
  vacuum: "vacuum";
298
+ image: "image";
299
299
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
300
300
  /** What an entity declares it can do, with the device's own limits for each. */
301
301
  type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
@@ -1262,7 +1262,8 @@ type Integration<TOptions = JsonObject> = {
1262
1262
  continueCommand?: (target: CommandTarget, step: CommandStep, context: MappingContext) => TransportRequest | null;
1263
1263
  /**
1264
1264
  * Reads what a message says about the device itself, beyond its entities: the firmware it runs
1265
- * now, which changes when it is updated and is otherwise only known from when it was found.
1265
+ * now, which changes when it is updated and is otherwise only known from when it was found;
1266
+ * and how it is set up, when that decides its entities (`descriptor`).
1266
1267
  *
1267
1268
  * Optional: an integration whose messages say nothing of the kind leaves it out.
1268
1269
  *
@@ -1292,6 +1293,17 @@ type StreamRequest = {
1292
1293
  type DeviceInfo = {
1293
1294
  readonly swVersion?: string;
1294
1295
  readonly hwVersion?: string;
1296
+ /**
1297
+ * What the device is now, for a device whose entities depend on how it is set up - a Bot in
1298
+ * switch or in press mode: the claim's own descriptor while it is still that, a new one to
1299
+ * describe it from once it changed. Left out when the message does not say.
1300
+ *
1301
+ * A new one is taken when the device still says it thirty seconds later - a message saying
1302
+ * the claim's own again drops it. The device is then described again: an entity
1303
+ * described both times stays, with its history; one no longer described is removed, with its
1304
+ * history; one described only now is added.
1305
+ */
1306
+ readonly descriptor?: unknown;
1295
1307
  };
1296
1308
  //#endregion
1297
1309
  //#region ../package-runtime/dist/stream.d.ts
package/dist/schemas.d.ts CHANGED
@@ -433,9 +433,8 @@ export declare const BUNDLE_FILE_SCHEMAS: {
433
433
  capabilities: z.ZodRecord<z.ZodEnum<{
434
434
  number: "number";
435
435
  custom: "custom";
436
- image: "image";
437
- level: "level";
438
436
  on_off: "on_off";
437
+ level: "level";
439
438
  color_hs: "color_hs";
440
439
  color_temp: "color_temp";
441
440
  cover: "cover";
@@ -451,6 +450,7 @@ export declare const BUNDLE_FILE_SCHEMAS: {
451
450
  lawn_mower: "lawn_mower";
452
451
  select: "select";
453
452
  vacuum: "vacuum";
453
+ image: "image";
454
454
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
455
455
  state: z.ZodRecord<z.ZodEnum<{
456
456
  number: "number";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nebulahome/integration-sdk",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "Write a NebulaHome integration: check it, build it, test it and release it for the platform.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -62,10 +62,10 @@
62
62
  "tsdown": "^0.23.0",
63
63
  "typescript": "^6.0.3",
64
64
  "vitest": "^4.1.11",
65
- "@nebulahome/package-runtime": "2026.10.0-alpha.40",
66
- "@nebulahome/contracts": "2026.10.0-alpha.40",
67
- "@nebulahome/tsconfig": "2026.10.0-alpha.40",
68
- "@nebulahome/eslint-config": "2026.10.0-alpha.40"
65
+ "@nebulahome/contracts": "2026.10.0-alpha.45",
66
+ "@nebulahome/package-runtime": "2026.10.0-alpha.45",
67
+ "@nebulahome/eslint-config": "2026.10.0-alpha.45",
68
+ "@nebulahome/tsconfig": "2026.10.0-alpha.45"
69
69
  },
70
70
  "scripts": {
71
71
  "build": "tsdown && node scripts/build-schemas.js",