@nebulahome/integration-sdk 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,20 @@
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.1.0
7
+
8
+ Matter, and a wider grammar for conditions.
9
+
10
+ - A driver may run on the platform's `matter` transport with `"kind": "matter"`: the platform's
11
+ Matter mapping is its driver, with neither a profile nor code.
12
+ - `discovery.json` may say which of the house's Matter devices are the vendor's, in a `matter`
13
+ block of conditions on who each device says it is; `listen` may then be left out.
14
+ - Conditions, in claims and in `discovery.json`, take `endsWith`, `contains` (a part of a text, or
15
+ an item of a list) and `min` / `max` (a number in a range) beside `equals`, `exists`, `oneOf`
16
+ and `startsWith`.
17
+ - `identifyMatter(vendor, identity)` in `@nebulahome/integration-sdk/testing` says whether the
18
+ vendor's `matter` rules take a Matter device, and as which driver and model.
19
+
6
20
  ## 1.0.0
7
21
 
8
22
  The first public release.
package/FILES.md CHANGED
@@ -118,10 +118,17 @@ the vendor's models by series, across its drivers - the series by name, the mode
118
118
  counting order - and a device's page says its series where it would say the driver's name. A
119
119
  model given no series is grouped under its driver. Every model named must be in `models`.
120
120
 
121
- `transport` is a platform transport - `http`, `mqtt` - or one the driver's own vendor ships,
122
- named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
121
+ `transport` is a platform transport - `http`, `mqtt`, `matter` - or one the driver's own vendor
122
+ ships, named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
123
123
  order, and a driver leaning on another's transport would load or not by luck.
124
124
 
125
+ A driver of the vendor's **Matter devices** is `"transport": "matter"` with `"kind": "matter"` and
126
+ neither a profile nor an entry: the platform's own Matter mapping runs it - lights, switches,
127
+ covers, locks, thermostats, the usual sensors, power and energy, the firmware - so the vendor's
128
+ Matter devices are its own, on its page, without code. Which devices those are its
129
+ `discovery.json` says (below), and `modelCodes` maps what they call their model - their product id,
130
+ unless the vendor says another field - onto the models it lists.
131
+
125
132
  `defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
126
133
  icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
127
134
  `relay`, `printer`, `sensor`… - and every lucide icon is there under its own name). The owner
@@ -144,6 +151,14 @@ serves a family of models - and a state may be **looked up in a table** -
144
151
  renames what a device says into what a capability accepts. A list is membership, not an `or`
145
152
  between paths; a table renames and cannot compute.
146
153
 
154
+ A condition, in a claim or a `discovery.json`, may also ask that a text **start** or **end** with
155
+ something (`startsWith`, `endsWith`, without regard to case - a MAC address's maker is its first
156
+ three bytes), that a text or a list **contain** something (`contains`: a part of a text, without
157
+ regard to case, or one item of a list - `{ "path": "deviceTypes", "contains": 266 }`), or that a
158
+ number lie **in a range** (`{ "path": "softwareVersion", "min": 10 }`, both ends included). There
159
+ is no regular expression, on purpose: one written badly holds the hub's thread for as long as it
160
+ backtracks, and the grammar is what keeps a bundle of data from doing that.
161
+
147
162
  A third form reads whether something is **there** -
148
163
  `{ "path": "sys.available_updates.stable", "present": true }` - true when the path names a value,
149
164
  false when the object that would hold it is there without it. It is the one read that turns an
@@ -295,6 +310,37 @@ driver takes is not proposed, and the hub logs its model once at info: it is the
295
310
  my device not found". A `discovery.json` that does not load leaves the vendor loaded without discovery, and the
296
311
  failure names the file.
297
312
 
313
+ **Matter devices.** The house's Matter devices are commissioned on the platform's Brokers page,
314
+ with the code the maker's app - or Google Home, Apple Home, Alexa - shares, and each is then added
315
+ at once to the vendor whose `matter` rules take it:
316
+
317
+ ```json
318
+ {
319
+ "matter": {
320
+ "match": [{ "path": "vendorId", "equals": 5264 }],
321
+ "model": "productId"
322
+ }
323
+ }
324
+ ```
325
+
326
+ - `match` - at least one condition, all of which must hold of who the device says it is: its
327
+ `vendorId` and `productId` (numbers), `vendorName`, `productName`, `productLabel`, `nodeLabel`,
328
+ `serialNumber`, `uniqueId`, `hardwareVersion`, `softwareVersion` (numbers) and their `…String`
329
+ texts, `macAddresses` (a list of `aa:bb:cc:dd:ee:ff`), `deviceTypes` and `clusters` (lists of
330
+ numbers), `isBridge` and `isBridged`. A field the device does not say is `null`. The vendor id is
331
+ the one to rule on: the CSA assigns it to the maker, and it does not change with a name.
332
+ - `model` - where the device says its model, looked up in the `modelCodes` of the vendor's drivers
333
+ that say `"kind": "matter"`; `productId` when absent. A model no driver maps goes to the vendor's
334
+ Matter driver when it has only one. Matter devices are added on their own, with no one to pick a
335
+ model: a Matter driver that lists models must map every product in `modelCodes`, or a product
336
+ it misses is never added. A driver that lists none takes them all, under its own name.
337
+
338
+ A vendor may have `matter` alone, with no `listen`. A device behind a Matter bridge is a device of
339
+ its own, ruled on by what the bridge says of it. A device that more than one vendor's rules take,
340
+ and one that none takes, is added as the platform's own Matter device, and the Brokers page says
341
+ which vendors want it. Removing a Matter device from the house takes it off the house's fabric; it
342
+ stays in the other apps it was shared from.
343
+
298
344
  **A listener of the vendor's own** is a module - plain JavaScript, like a transport, handed the
299
345
  same SDK - whose default export returns `{ listen(signal, context), scan?() }`: an async iterable
300
346
  of sightings, `{ config: { host }, payload }`, reported as they happen until the signal ends it,
package/README.md CHANGED
@@ -85,7 +85,8 @@ light.receive(stateJson); // → state reports
85
85
  light.command('light.device', 'on_off', { command: 'turn_on' }); // → the HTTP request
86
86
  ```
87
87
 
88
- `identify` says what discovery makes of a device heard, and `createFakeSdk` is the SDK handed to
88
+ `identify` says what discovery makes of a device heard, `identifyMatter` what the vendor's `matter`
89
+ rules make of one of the house's Matter devices, and `createFakeSdk` is the SDK handed to
89
90
  the code, recording what it logged and sent: its UDP sockets and WebSockets connect to nothing, and
90
91
  a test opens, delivers to and drops them.
91
92
 
@@ -103,7 +104,7 @@ built with it declares `^<major>.<minor>.0`. The full guide is `INTEGRATIONS_DOC
103
104
  ## Releasing the SDK
104
105
 
105
106
  For the platform's maintainers. The hub reads the contract's version from this `package.json`, so
106
- the version is raised by hand - not by changesets, which ignore this package:
107
+ the version is raised by hand:
107
108
 
108
109
  - **patch** - a fix, or a change to the command, the tests' helpers or the documentation that
109
110
  leaves what a bundle can use as it is. Bundles keep declaring `^<major>.<minor>.0`, so it is