@nebulahome/integration-sdk 1.4.0 → 1.5.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,15 @@
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.5.0
7
+
8
+ A Modbus template's entities say their icon, and its units are the platform's.
9
+
10
+ - An entity of a Modbus template may name its `icon`, a catalogue icon id; the domain's is used
11
+ when it does not.
12
+ - A read's `unit` must be one the platform knows - a unit of one of its sensor classes (`W`,
13
+ `kWh`, `°C`) - and a template with another is refused when it is checked.
14
+
6
15
  ## 1.4.0
7
16
 
8
17
  The house's Modbus client is the platform's.
package/FILES.md CHANGED
@@ -189,11 +189,13 @@ duplicate:
189
189
  - Each entity is a `domain` - `sensor`, `binary_sensor`, `switch`, `light`, `number`, `select`,
190
190
  `button` - and its capabilities: a sensor `sensor_numeric` or `sensor_text`, a binary sensor
191
191
  `sensor_binary`, a switch `on_off`, a light `on_off` and maybe `level`, the others their own.
192
- `id` is what the entity stays when it is renamed; give every one.
192
+ `id` is what the entity stays when it is renamed; give every one. `icon`, a catalogue icon id,
193
+ is the one it starts with - the domain's when left out.
193
194
  - `read`: `function` 1 (coils), 2 (discrete inputs), 3 (holding registers) or 4 (input registers);
194
195
  `address`, a number or `"0x…"`; for registers a `type` - `u16` (the default), `s16`, `u32`, `s32`,
195
196
  `f32`, or `string` with a `count` of registers - a `bit` for an on/off value, a `scale` (`0.1`
196
- for tenths), a `unit`, and `options` naming what each raw number means (`{ "0": "Off" }`, which
197
+ for tenths), a `unit` the platform knows (`W`, `kWh`, `°C`: those of the sensor classes, an
198
+ unknown one is refused), and `options` naming what each raw number means (`{ "0": "Off" }`, which
197
199
  a select needs).
198
200
  - `write`: `function` 5 (one coil), 6 (one register), 15 (coils) or 16 (registers - a 32-bit value
199
201
  needs it); `address`, the read's when left out; `on` and `off` for a switch; `min`, `max` and
@@ -3970,6 +3970,8 @@ const parsedCatalog = sensorClassesCatalogSchema.parse(sensor_classes_default);
3970
3970
  /** Every class in the catalogue, keyed by id. */
3971
3971
  const SENSOR_CLASSES = new Map(parsedCatalog.classes.map((entry) => [entry.id, entry]));
3972
3972
  parsedCatalog.classes;
3973
+ /** Every unit the catalogue knows, once each - an id is also its symbol. */
3974
+ const SENSOR_UNIT_IDS = new Set(parsedCatalog.classes.flatMap((entry) => entry.units.map((unit) => unit.id)));
3973
3975
  /**
3974
3976
  * Looks up a sensor class by id.
3975
3977
  *
@@ -4987,7 +4989,8 @@ const modbusReadSchema = z.strictObject({
4987
4989
  bit: z.int().min(0).max(15).optional(),
4988
4990
  /** What the raw number is multiplied by: 0.1 for tenths. */
4989
4991
  scale: z.number().refine((scale) => scale !== 0, "Not zero").optional(),
4990
- unit: z.string().trim().max(16).optional(),
4992
+ /** One of the units the platform knows (`SENSOR_UNIT_IDS`): `W`, `kWh`, `°C`. */
4993
+ unit: z.string().refine((unit) => SENSOR_UNIT_IDS.has(unit), "Not a unit the platform knows").optional(),
4991
4994
  /** What each raw number means, for a choice or a text: `{ "0": "Off", "1": "Eco" }`. */
4992
4995
  options: z.record(z.string().regex(/^-?\d{1,10}$/u, "A whole number"), z.string().trim().min(1).max(64)).optional()
4993
4996
  });
@@ -5033,6 +5036,8 @@ const modbusEntitySchema = z.strictObject({
5033
5036
  /** What it stays when renamed; given from the name when saved. */
5034
5037
  id: z.string().regex(MODBUS_ENTITY_ID_PATTERN, "Lower-case letters, digits and _").optional(),
5035
5038
  name: z.string().trim().min(1, "Needed: a name").max(64),
5039
+ /** The catalogue icon it starts with; the domain's when left out. */
5040
+ icon: iconIdSchema.optional(),
5036
5041
  domain: z.enum(MODBUS_DOMAINS),
5037
5042
  capabilities: z.partialRecord(z.enum(MODBUS_CAPABILITIES), modbusCapabilityMapSchema)
5038
5043
  });
@@ -10225,6 +10230,7 @@ function modbusEntityDescriptorOf(entity) {
10225
10230
  objectId: modbusObjectIdOf(entity),
10226
10231
  name: entity.name,
10227
10232
  capabilities,
10233
+ ...entity.icon === void 0 ? {} : { icon: entity.icon },
10228
10234
  ...unit === void 0 || unit === "" ? {} : { unitOfMeasurement: unit }
10229
10235
  };
10230
10236
  }
@@ -200,14 +200,13 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
200
200
  declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
201
201
  number: "number";
202
202
  custom: "custom";
203
- image: "image";
204
- level: "level";
205
203
  select: "select";
206
204
  button: "button";
207
205
  sensor_numeric: "sensor_numeric";
208
206
  sensor_text: "sensor_text";
209
207
  sensor_binary: "sensor_binary";
210
208
  on_off: "on_off";
209
+ level: "level";
211
210
  color_hs: "color_hs";
212
211
  color_temp: "color_temp";
213
212
  cover: "cover";
@@ -218,6 +217,7 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
218
217
  update: "update";
219
218
  lawn_mower: "lawn_mower";
220
219
  vacuum: "vacuum";
220
+ image: "image";
221
221
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
222
222
  /** What an entity declares it can do, with the device's own limits for each. */
223
223
  type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
@@ -744,6 +744,7 @@ declare const modbusTemplateSchema: z.ZodObject<{
744
744
  entities: z.ZodArray<z.ZodObject<{
745
745
  id: z.ZodOptional<z.ZodString>;
746
746
  name: z.ZodString;
747
+ icon: z.ZodOptional<z.ZodString>;
747
748
  domain: z.ZodEnum<{
748
749
  number: "number";
749
750
  sensor: "sensor";
@@ -1800,13 +1801,13 @@ declare const vendorManifestSchema: z.ZodObject<{
1800
1801
  transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
1801
1802
  module: z.ZodString;
1802
1803
  wires: z.ZodArray<z.ZodEnum<{
1804
+ udp: "udp";
1803
1805
  matter: "matter";
1804
- modbus: "modbus";
1805
1806
  mqtt: "mqtt";
1807
+ modbus: "modbus";
1806
1808
  http: "http";
1807
1809
  ble: "ble";
1808
1810
  zigbee: "zigbee";
1809
- udp: "udp";
1810
1811
  }>>;
1811
1812
  }, z.core.$strict>]>>>;
1812
1813
  streams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -1895,11 +1896,11 @@ declare const bundleManifestSchema: z.ZodObject<{
1895
1896
  modelCodes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
1896
1897
  modelSeries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
1897
1898
  kind: z.ZodEnum<{
1899
+ declarative: "declarative";
1900
+ code: "code";
1898
1901
  matter: "matter";
1899
- modbus: "modbus";
1900
1902
  mqtt: "mqtt";
1901
- code: "code";
1902
- declarative: "declarative";
1903
+ modbus: "modbus";
1903
1904
  }>;
1904
1905
  defaultIcon: z.ZodOptional<z.ZodString>;
1905
1906
  webPagePort: z.ZodOptional<z.ZodInt>;
@@ -89,7 +89,7 @@ function defineTransport(spec) {
89
89
  * bundle built with this SDK says `^<major>.<minor>.0`.
90
90
  */
91
91
  /** The SDK's own version: `1.0.0`, or a prerelease of it. */
92
- const SDK_VERSION = "1.4.0";
92
+ const SDK_VERSION = "1.5.0";
93
93
  /**
94
94
  * The runtime range a bundle built with this SDK declares: this version's major and minor, so a
95
95
  * platform with the same contract or a later one of the same major loads it.
package/dist/index.d.ts CHANGED
@@ -200,14 +200,13 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
200
200
  declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
201
201
  number: "number";
202
202
  custom: "custom";
203
- image: "image";
204
- level: "level";
205
203
  select: "select";
206
204
  button: "button";
207
205
  sensor_numeric: "sensor_numeric";
208
206
  sensor_text: "sensor_text";
209
207
  sensor_binary: "sensor_binary";
210
208
  on_off: "on_off";
209
+ level: "level";
211
210
  color_hs: "color_hs";
212
211
  color_temp: "color_temp";
213
212
  cover: "cover";
@@ -218,6 +217,7 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
218
217
  update: "update";
219
218
  lawn_mower: "lawn_mower";
220
219
  vacuum: "vacuum";
220
+ image: "image";
221
221
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
222
222
  /** What an entity declares it can do, with the device's own limits for each. */
223
223
  type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
package/dist/schemas.d.ts CHANGED
@@ -29,13 +29,13 @@ export declare const BUNDLE_FILE_SCHEMAS: {
29
29
  transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
30
30
  module: z.ZodString;
31
31
  wires: z.ZodArray<z.ZodEnum<{
32
+ udp: "udp";
32
33
  matter: "matter";
33
- modbus: "modbus";
34
34
  mqtt: "mqtt";
35
+ modbus: "modbus";
35
36
  http: "http";
36
37
  ble: "ble";
37
38
  zigbee: "zigbee";
38
- udp: "udp";
39
39
  }>>;
40
40
  }, z.core.$strict>]>>>;
41
41
  streams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -113,11 +113,11 @@ export declare const BUNDLE_FILE_SCHEMAS: {
113
113
  modelCodes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
114
114
  modelSeries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
115
115
  kind: z.ZodEnum<{
116
+ declarative: "declarative";
117
+ code: "code";
116
118
  matter: "matter";
117
- modbus: "modbus";
118
119
  mqtt: "mqtt";
119
- code: "code";
120
- declarative: "declarative";
120
+ modbus: "modbus";
121
121
  }>;
122
122
  defaultIcon: z.ZodOptional<z.ZodString>;
123
123
  webPagePort: z.ZodOptional<z.ZodInt>;
@@ -385,22 +385,22 @@ export declare const BUNDLE_FILE_SCHEMAS: {
385
385
  entities: z.ZodArray<z.ZodObject<{
386
386
  domain: z.ZodEnum<{
387
387
  number: "number";
388
+ image: "image";
388
389
  custom: "custom";
390
+ light: "light";
391
+ switch: "switch";
389
392
  sensor: "sensor";
390
393
  binary_sensor: "binary_sensor";
391
- switch: "switch";
392
- light: "light";
393
- select: "select";
394
- button: "button";
395
- image: "image";
396
394
  cover: "cover";
397
395
  lock: "lock";
396
+ climate: "climate";
398
397
  media_player: "media_player";
399
398
  camera: "camera";
399
+ button: "button";
400
400
  update: "update";
401
401
  lawn_mower: "lawn_mower";
402
+ select: "select";
402
403
  vacuum: "vacuum";
403
- climate: "climate";
404
404
  alias: "alias";
405
405
  }>;
406
406
  objectId: z.ZodOptional<z.ZodString>;
@@ -409,14 +409,13 @@ export declare const BUNDLE_FILE_SCHEMAS: {
409
409
  capabilities: z.ZodRecord<z.ZodEnum<{
410
410
  number: "number";
411
411
  custom: "custom";
412
- image: "image";
413
- level: "level";
414
412
  select: "select";
415
413
  button: "button";
416
414
  sensor_numeric: "sensor_numeric";
417
415
  sensor_text: "sensor_text";
418
416
  sensor_binary: "sensor_binary";
419
417
  on_off: "on_off";
418
+ level: "level";
420
419
  color_hs: "color_hs";
421
420
  color_temp: "color_temp";
422
421
  cover: "cover";
@@ -427,6 +426,7 @@ export declare const BUNDLE_FILE_SCHEMAS: {
427
426
  update: "update";
428
427
  lawn_mower: "lawn_mower";
429
428
  vacuum: "vacuum";
429
+ image: "image";
430
430
  }> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
431
431
  state: z.ZodRecord<z.ZodEnum<{
432
432
  number: "number";
@@ -831,6 +831,7 @@ export declare const BUNDLE_FILE_SCHEMAS: {
831
831
  entities: z.ZodArray<z.ZodObject<{
832
832
  id: z.ZodOptional<z.ZodString>;
833
833
  name: z.ZodString;
834
+ icon: z.ZodOptional<z.ZodString>;
834
835
  domain: z.ZodEnum<{
835
836
  number: "number";
836
837
  sensor: "sensor";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nebulahome/integration-sdk",
3
- "version": "1.4.0",
3
+ "version": "1.5.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",
@@ -63,9 +63,9 @@
63
63
  "typescript": "^6.0.3",
64
64
  "vitest": "^4.1.11",
65
65
  "@nebulahome/contracts": "2026.10.0-alpha.4",
66
+ "@nebulahome/tsconfig": "2026.10.0-alpha.4",
66
67
  "@nebulahome/package-runtime": "2026.10.0-alpha.4",
67
- "@nebulahome/eslint-config": "2026.10.0-alpha.4",
68
- "@nebulahome/tsconfig": "2026.10.0-alpha.4"
68
+ "@nebulahome/eslint-config": "2026.10.0-alpha.4"
69
69
  },
70
70
  "scripts": {
71
71
  "build": "tsdown && node scripts/build-schemas.js",
@@ -1059,8 +1059,7 @@
1059
1059
  "type": "number"
1060
1060
  },
1061
1061
  "unit": {
1062
- "type": "string",
1063
- "maxLength": 16
1062
+ "type": "string"
1064
1063
  },
1065
1064
  "options": {
1066
1065
  "type": "object",
@@ -58,6 +58,10 @@
58
58
  "minLength": 1,
59
59
  "maxLength": 64
60
60
  },
61
+ "icon": {
62
+ "type": "string",
63
+ "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
64
+ },
61
65
  "domain": {
62
66
  "type": "string",
63
67
  "enum": [
@@ -149,8 +153,7 @@
149
153
  "type": "number"
150
154
  },
151
155
  "unit": {
152
- "type": "string",
153
- "maxLength": 16
156
+ "type": "string"
154
157
  },
155
158
  "options": {
156
159
  "type": "object",