@nebulahome/integration-sdk 1.1.0 → 1.2.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 +15 -0
- package/FILES.md +27 -3
- package/dist/chunks/node-dist.js +377 -22
- package/dist/chunks/node-index.d.ts +34 -3
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +22 -3
- package/dist/schemas.d.ts +20 -3
- package/package.json +3 -3
- package/schemas/discovery.schema.json +63 -0
- package/schemas/manifest.schema.json +12 -0
- package/schemas/profile.schema.json +49 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,21 @@
|
|
|
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.2.0
|
|
7
|
+
|
|
8
|
+
One device reached two ways.
|
|
9
|
+
|
|
10
|
+
- The manifest may say what makes two of the vendor's devices one, `"twins": ["mac"]` (or
|
|
11
|
+
`["mac", "serial"]`): a device added over the vendor's own transport and again through the
|
|
12
|
+
Matter broker is then offered to the owner to link, and becomes one device with two ways in.
|
|
13
|
+
- A profile's `identity` and `discovery.json`'s `identity` take `mac` and `serialNumber`, written
|
|
14
|
+
any way the device writes them; `discovery.json`'s `identity` also takes `auth`, where the device
|
|
15
|
+
says it is behind a password, which its row on the Found tab shows.
|
|
16
|
+
- An entity of a profile may carry `link`: its key in the transport's terms (`"switch:0"`), shown
|
|
17
|
+
beside the transport's name, and where the same reading sits in Matter
|
|
18
|
+
(`{ "endpoint": 1, "cluster": 6, "attribute": 0 }`), which links the two at once when the device
|
|
19
|
+
is linked.
|
|
20
|
+
|
|
6
21
|
## 1.1.0
|
|
7
22
|
|
|
8
23
|
Matter, and a wider grammar for conditions.
|
package/FILES.md
CHANGED
|
@@ -63,6 +63,15 @@ with `padding` (0 to 16, default 0): extra room, in pixels, the interface leaves
|
|
|
63
63
|
inside its tile. Every logo already gets a small margin; this is on top of it, for a mark drawn
|
|
64
64
|
to the very edge of its file. It cannot ask for less than the margin, only for more.
|
|
65
65
|
|
|
66
|
+
`twins` says what makes two of the vendor's devices **one device reached two ways**: `["mac"]`,
|
|
67
|
+
or `["mac", "serial"]` for both to agree. A Shelly added over its RPC and again through the Matter
|
|
68
|
+
broker is the same plug; with `twins`, the house compares what each said - the MAC and the serial
|
|
69
|
+
its `identity` reads, and its Matter identity's - and offers the owner to link them, when the
|
|
70
|
+
Matter node is added and as a suggestion on the vendor's page. Linked, it is one device with two
|
|
71
|
+
ways in: its readings come the way the owner prefers, and the other way carries them while that
|
|
72
|
+
one is silent. A vendor without `twins` is never offered a link. Each entity's `link` (below) says
|
|
73
|
+
which of its readings is which in Matter.
|
|
74
|
+
|
|
66
75
|
`requires` says what the vendor's devices need besides the hub, in the grammar a
|
|
67
76
|
package's manifest uses (PACKAGES.md §8, Dependencies):
|
|
68
77
|
`{ "services": ["mqtt-broker"] }` for Zigbee2MQTT, which talks through the house's broker, or a
|
|
@@ -183,6 +192,18 @@ on anything its device says, so it is available exactly when the device is, and
|
|
|
183
192
|
`"deviceClass": "restart"` the interface asks before pressing, since the device goes away for a
|
|
184
193
|
while.
|
|
185
194
|
|
|
195
|
+
An entity may carry **`link`**, for a vendor whose devices the house may also reach through the
|
|
196
|
+
Matter broker (`twins`, above): `"link": { "key": "switch:0", "matter": { "endpoint": 1,
|
|
197
|
+
"cluster": 6, "attribute": 0 } }`. `key` is the entity's name in the transport's terms, shown on
|
|
198
|
+
its page beside the transport's name; `matter` is where the same reading sits in Matter - the
|
|
199
|
+
endpoint, the cluster and the attribute the platform's Matter mapping reads it from (the first
|
|
200
|
+
cluster and attribute of an entity it reads from several: 0 for a light). When the device is
|
|
201
|
+
linked, an entity whose `matter` names a Matter entity of the twin is linked to it at once,
|
|
202
|
+
whatever it is; a sensor without one is linked when exactly one Matter sensor reads the same
|
|
203
|
+
thing, and a control never without one. The identity's `mac` and `serialNumber` are what the twin
|
|
204
|
+
is found by: `"identity": { "externalId": "id", "mac": "mac" }`, written any way the device writes
|
|
205
|
+
it.
|
|
206
|
+
|
|
186
207
|
An entity may report **attributes** beside its state: `"attributes": { "endsAt":
|
|
187
208
|
"pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
|
|
188
209
|
for what a page needs of the entity and the entity itself is not - the Zigbee2MQTT bridge's
|
|
@@ -275,7 +296,9 @@ because a device announced it there.
|
|
|
275
296
|
- `identity` - paths to the model code, the id, the name and the firmware version. Only the model
|
|
276
297
|
is ever required. A field may be a list of paths, tried in order, for generations that answer
|
|
277
298
|
in different words: a Shelly Gen1 says `type`, `mac` and `fw` where later ones say `model`,
|
|
278
|
-
`id` and `ver`.
|
|
299
|
+
`id` and `ver`. `mac` and `serialNumber` are what the Found tab shows and a twin is told by
|
|
300
|
+
(`twins`), and `auth` is where the device says it is behind a password - `["auth_en", "auth"]`
|
|
301
|
+
on a Shelly - which its row shows before anyone tries to add it.
|
|
279
302
|
- `adopt` - who adds a device found: `owner` (the default) proposes it on the vendor's
|
|
280
303
|
page to adopt; `automatic` has `api` add it as soon as the hub proposes it, named as it named
|
|
281
304
|
itself, with the id the add form would have offered - for devices the owner already chose
|
|
@@ -338,8 +361,9 @@ at once to the vendor whose `matter` rules take it:
|
|
|
338
361
|
A vendor may have `matter` alone, with no `listen`. A device behind a Matter bridge is a device of
|
|
339
362
|
its own, ruled on by what the bridge says of it. A device that more than one vendor's rules take,
|
|
340
363
|
and one that none takes, is added as the platform's own Matter device, and the Brokers page says
|
|
341
|
-
which vendors want it.
|
|
342
|
-
|
|
364
|
+
which vendors want it. One added as the platform's before the vendor was installed becomes the
|
|
365
|
+
vendor's once it is, with its entities. Removing a Matter device from the house takes it off the
|
|
366
|
+
house's fabric; it stays in the other apps it was shared from.
|
|
343
367
|
|
|
344
368
|
**A listener of the vendor's own** is a module - plain JavaScript, like a transport, handed the
|
|
345
369
|
same SDK - whose default export returns `{ listen(signal, context), scan?() }`: an async iterable
|
package/dist/chunks/node-dist.js
CHANGED
|
@@ -1726,6 +1726,8 @@ z.object({ vendorId: z.string().min(1).max(64) });
|
|
|
1726
1726
|
*
|
|
1727
1727
|
* Defined in ARCHITECTURE.md 8.
|
|
1728
1728
|
*/
|
|
1729
|
+
/** What an integration may say makes two of its devices one: the same MAC, the same serial. */
|
|
1730
|
+
const TWIN_FACTS = ["mac", "serial"];
|
|
1729
1731
|
/**
|
|
1730
1732
|
* Integration instance identifier.
|
|
1731
1733
|
*
|
|
@@ -1800,15 +1802,23 @@ const vendorPairingSchema = z.object({
|
|
|
1800
1802
|
});
|
|
1801
1803
|
/** What a logo may be served as: an image the interface can put straight into an `img`. */
|
|
1802
1804
|
const LOGO_DATA_URL_PATTERN = /^data:image\/(?:svg\+xml|png);base64,[A-Za-z0-9+/]+=*$/;
|
|
1803
|
-
/**
|
|
1804
|
-
|
|
1805
|
+
/**
|
|
1806
|
+
* The lifecycle states `hub` records for a configured instance.
|
|
1807
|
+
*
|
|
1808
|
+
* `identifying` sits between `starting` and `running`: the transport is open, and the instance
|
|
1809
|
+
* is waiting to hear from the one device it was added for. A device that has been identified
|
|
1810
|
+
* before starts straight into `running`, bound from what the registry kept about it.
|
|
1811
|
+
*/
|
|
1812
|
+
const INTEGRATION_STATES = [
|
|
1805
1813
|
"stopped",
|
|
1806
1814
|
"starting",
|
|
1807
1815
|
"identifying",
|
|
1808
1816
|
"running",
|
|
1809
1817
|
"failed",
|
|
1810
1818
|
"disabled"
|
|
1811
|
-
]
|
|
1819
|
+
];
|
|
1820
|
+
/** Validates an instance lifecycle state. */
|
|
1821
|
+
const integrationStateSchema = z.enum(INTEGRATION_STATES);
|
|
1812
1822
|
z.strictObject({ vendorId: z.string().regex(VENDOR_ID_PATTERN$1) });
|
|
1813
1823
|
z.object({ isLoaded: z.boolean() });
|
|
1814
1824
|
/**
|
|
@@ -2000,6 +2010,11 @@ const integrationVendorSchema = z.object({
|
|
|
2000
2010
|
discoverySources: z.array(z.enum(DISCOVERY_SOURCES)).default([]),
|
|
2001
2011
|
/** Who adds what discovery finds: the owner, or the platform on its own. */
|
|
2002
2012
|
adoption: z.enum(DEVICE_ADOPTIONS).default("owner"),
|
|
2013
|
+
/**
|
|
2014
|
+
* What makes two of its devices one device reached two ways - the same MAC, the same serial -
|
|
2015
|
+
* as its manifest's `twins` says. Empty for a vendor that offers no links.
|
|
2016
|
+
*/
|
|
2017
|
+
twins: z.array(z.enum(TWIN_FACTS)).max(TWIN_FACTS.length).default([]),
|
|
2003
2018
|
/** The entities pairing is run by, for a vendor whose devices are paired through one of its own. */
|
|
2004
2019
|
pairing: vendorPairingSchema.nullable().default(null),
|
|
2005
2020
|
drivers: z.array(integrationKindSchema$1),
|
|
@@ -4194,6 +4209,26 @@ const declaredCapabilitiesSchema = z.partialRecord(capabilityNameSchema, jsonObj
|
|
|
4194
4209
|
message: `Parameters do not match the ${capability} capability`
|
|
4195
4210
|
});
|
|
4196
4211
|
});
|
|
4212
|
+
/**
|
|
4213
|
+
* Where a reading sits in Matter's terms: the endpoint, the cluster and the attribute. A Matter
|
|
4214
|
+
* entity carries its own; an entity of another transport may carry the one that reads the same
|
|
4215
|
+
* thing, so the two are linked when the device is reached both ways.
|
|
4216
|
+
*/
|
|
4217
|
+
const matterReferenceSchema = z.strictObject({
|
|
4218
|
+
endpoint: z.int().min(0).max(65535),
|
|
4219
|
+
cluster: z.int().min(0),
|
|
4220
|
+
attribute: z.int().min(0)
|
|
4221
|
+
});
|
|
4222
|
+
/**
|
|
4223
|
+
* What lets an entity be told apart from the same reading reached another way: its own key in its
|
|
4224
|
+
* transport's terms - `switch:0` on a Shelly - and where it sits in Matter.
|
|
4225
|
+
*/
|
|
4226
|
+
const entityLinkHintSchema = z.strictObject({
|
|
4227
|
+
/** The entity's key in its transport, as its page shows it beside the transport's name. */
|
|
4228
|
+
key: z.string().min(1).max(64).optional(),
|
|
4229
|
+
/** Where it sits in Matter: its own place, or, for another transport, its Matter twin's. */
|
|
4230
|
+
matter: matterReferenceSchema.optional()
|
|
4231
|
+
});
|
|
4197
4232
|
/** One entity a device exposes. */
|
|
4198
4233
|
const entityRegistrationSchema = z.object({
|
|
4199
4234
|
entityId: entityIdSchema,
|
|
@@ -4204,7 +4239,9 @@ const entityRegistrationSchema = z.object({
|
|
|
4204
4239
|
unitOfMeasurement: z.string().max(32).optional(),
|
|
4205
4240
|
deviceClass: z.string().max(64).optional(),
|
|
4206
4241
|
stateClass: z.enum(ENTITY_STATE_CLASSES).optional(),
|
|
4207
|
-
displayPrecision: z.int().min(0).max(6).optional()
|
|
4242
|
+
displayPrecision: z.int().min(0).max(6).optional(),
|
|
4243
|
+
/** Kept in the entity's `config.link`: what links it to its twin on another transport. */
|
|
4244
|
+
link: entityLinkHintSchema.optional()
|
|
4208
4245
|
}).superRefine((entity, ctx) => {
|
|
4209
4246
|
const issue = sensorRegistrationIssue(entity);
|
|
4210
4247
|
if (issue !== void 0) ctx.addIssue({
|
|
@@ -4229,6 +4266,10 @@ z.strictObject({
|
|
|
4229
4266
|
model: z.string().max(128).optional(),
|
|
4230
4267
|
swVersion: z.string().max(64).optional(),
|
|
4231
4268
|
hwVersion: z.string().max(64).optional(),
|
|
4269
|
+
/** The hardware's MAC address, as {@link normalizeMac} writes it, when it says one. */
|
|
4270
|
+
mac: z.string().min(1).max(64).optional(),
|
|
4271
|
+
/** The hardware's serial number, when it says one. */
|
|
4272
|
+
serialNumber: z.string().min(1).max(256).optional(),
|
|
4232
4273
|
/**
|
|
4233
4274
|
* What the owner needs to find the device again after a restart.
|
|
4234
4275
|
*
|
|
@@ -4289,6 +4330,16 @@ z.strictObject({
|
|
|
4289
4330
|
z.object({ isChanged: z.boolean() });
|
|
4290
4331
|
z.strictObject({ entityId: entityIdSchema });
|
|
4291
4332
|
z.object({ isLoaded: z.boolean() });
|
|
4333
|
+
z.strictObject({ entityRowIds: z.array(z.uuid()).min(1).max(1024) });
|
|
4334
|
+
z.object({ synced: z.int().min(0) });
|
|
4335
|
+
z.strictObject({ entityId: entityIdSchema });
|
|
4336
|
+
z.object({ items: z.array(z.object({
|
|
4337
|
+
entityId: entityIdSchema,
|
|
4338
|
+
/** The instance it comes through. */
|
|
4339
|
+
source: z.string(),
|
|
4340
|
+
isActive: z.boolean(),
|
|
4341
|
+
state: entityStateSchema.nullable()
|
|
4342
|
+
})) });
|
|
4292
4343
|
z.strictObject({ entityId: entityIdSchema });
|
|
4293
4344
|
z.object({ entityId: entityIdSchema });
|
|
4294
4345
|
z.object({
|
|
@@ -4300,6 +4351,191 @@ z.object({
|
|
|
4300
4351
|
entityIds: z.array(entityIdSchema)
|
|
4301
4352
|
});
|
|
4302
4353
|
//#endregion
|
|
4354
|
+
//#region ../contracts/dist/links.js
|
|
4355
|
+
/**
|
|
4356
|
+
* One device reached two ways, and the readings it gives both ways linked into one.
|
|
4357
|
+
*
|
|
4358
|
+
* A Shelly added over its own RPC and again over Matter is the same plug. The house keeps one
|
|
4359
|
+
* device for it and one entity for each thing it reads, each with a **source** per transport:
|
|
4360
|
+
* readings come from the preferred one, and the other takes over while it is silent.
|
|
4361
|
+
*
|
|
4362
|
+
* **The longer history leads.** Linking adds no row. Of two devices, the one the house had first
|
|
4363
|
+
* is the one it shows, and the other names it in `linked_to`; of two entities, the one with the
|
|
4364
|
+
* longer history is the linked entity, keeps its address and goes on recording, and the other
|
|
4365
|
+
* names it and stops. Every address and row of a linked entity means the one it names - to an
|
|
4366
|
+
* automation, a scene, a card - so nothing that used either is rewritten, and unlinking gives each
|
|
4367
|
+
* back its own.
|
|
4368
|
+
*/
|
|
4369
|
+
/** How a pair of entities was linked: declared by the integration, read alike, or by the owner. */
|
|
4370
|
+
const LINK_ORIGINS = [
|
|
4371
|
+
"declared",
|
|
4372
|
+
"auto",
|
|
4373
|
+
"manual"
|
|
4374
|
+
];
|
|
4375
|
+
/** One thing two devices have alike, and its value. */
|
|
4376
|
+
const linkReasonSchema = z.object({
|
|
4377
|
+
kind: z.enum([
|
|
4378
|
+
"mac",
|
|
4379
|
+
"serial",
|
|
4380
|
+
"model"
|
|
4381
|
+
]),
|
|
4382
|
+
value: z.string().max(256)
|
|
4383
|
+
});
|
|
4384
|
+
/**
|
|
4385
|
+
* A MAC address the way the house compares them: six bytes, lower case, colons.
|
|
4386
|
+
*
|
|
4387
|
+
* Devices write theirs every way - Shelly `08F9E0124C7A`, Matter `08:f9:e0:12:4c:7a` - and a
|
|
4388
|
+
* Thread radio's eight-byte address is not a MAC anybody else reports.
|
|
4389
|
+
*
|
|
4390
|
+
* @param raw - The address as the device said it.
|
|
4391
|
+
* @returns It, normalised; null when it is not a six-byte address.
|
|
4392
|
+
*/
|
|
4393
|
+
function normalizeMac(raw) {
|
|
4394
|
+
const hex = (raw ?? "").replaceAll(/[^0-9a-f]/giu, "").toLowerCase();
|
|
4395
|
+
if (hex.length !== 12 || (raw ?? "").replaceAll(/[0-9a-f:.\-\s]/giu, "") !== "") return null;
|
|
4396
|
+
return hex.replaceAll(/(..)(?!$)/gu, "$1:");
|
|
4397
|
+
}
|
|
4398
|
+
/** One way into a linked device: the instance, its transport and how it stands. */
|
|
4399
|
+
const deviceWaySchema = z.object({
|
|
4400
|
+
/** The instance, which is the way's own device id. */
|
|
4401
|
+
deviceId: integrationIdSchema,
|
|
4402
|
+
kind: z.string(),
|
|
4403
|
+
vendorId: z.string(),
|
|
4404
|
+
transport: z.string(),
|
|
4405
|
+
driverName: z.string(),
|
|
4406
|
+
state: z.enum(INTEGRATION_STATES),
|
|
4407
|
+
/** Whether its entities answer now. */
|
|
4408
|
+
isAvailable: z.boolean(),
|
|
4409
|
+
/** Whether readings come this way first. */
|
|
4410
|
+
isPreferred: z.boolean(),
|
|
4411
|
+
externalId: z.string().nullable(),
|
|
4412
|
+
/** Where it is reached, when its transport names a host: `192.168.178.112`. */
|
|
4413
|
+
address: z.string().nullable(),
|
|
4414
|
+
/** The Matter node, for a way through the Matter broker. */
|
|
4415
|
+
nodeId: z.string().nullable(),
|
|
4416
|
+
swVersion: z.string().nullable(),
|
|
4417
|
+
lastUpdatedAt: timestampSchema.nullable(),
|
|
4418
|
+
createdAt: timestampSchema
|
|
4419
|
+
});
|
|
4420
|
+
z.object({
|
|
4421
|
+
ways: z.array(deviceWaySchema).min(2),
|
|
4422
|
+
/** The instance its entities are read through first. */
|
|
4423
|
+
preferred: integrationIdSchema
|
|
4424
|
+
});
|
|
4425
|
+
/** One source of a linked entity: the same reading through one way in. */
|
|
4426
|
+
const entitySourceSchema = z.object({
|
|
4427
|
+
entityId: entityIdSchema,
|
|
4428
|
+
/** The way in, by its instance. */
|
|
4429
|
+
deviceId: integrationIdSchema,
|
|
4430
|
+
vendorId: z.string(),
|
|
4431
|
+
transport: z.string(),
|
|
4432
|
+
/** Its key in its transport, `switch:0`, when the integration names one. */
|
|
4433
|
+
key: z.string().nullable(),
|
|
4434
|
+
/** Where it sits in Matter, for a Matter source. */
|
|
4435
|
+
matter: matterReferenceSchema.nullable(),
|
|
4436
|
+
/** Whether readings come from it now. */
|
|
4437
|
+
isActive: z.boolean(),
|
|
4438
|
+
isAvailable: z.boolean(),
|
|
4439
|
+
/** What it last said, whether or not it is the one read. */
|
|
4440
|
+
state: jsonObjectSchema.nullable(),
|
|
4441
|
+
lastUpdated: timestampSchema.nullable(),
|
|
4442
|
+
/** How it was linked; null for the entity that leads. */
|
|
4443
|
+
origin: z.enum(LINK_ORIGINS).nullable()
|
|
4444
|
+
});
|
|
4445
|
+
z.object({
|
|
4446
|
+
/** Every source, the one that leads first. */
|
|
4447
|
+
sources: z.array(entitySourceSchema).min(2),
|
|
4448
|
+
/** The instance this entity is read through first, overriding its device; null follows it. */
|
|
4449
|
+
transport: integrationIdSchema.nullable(),
|
|
4450
|
+
/** The instance the device is read through first. */
|
|
4451
|
+
preferred: integrationIdSchema,
|
|
4452
|
+
/** The instance it is read through now; null while no source answers. */
|
|
4453
|
+
active: integrationIdSchema.nullable()
|
|
4454
|
+
});
|
|
4455
|
+
z.object({ entityIds: z.tuple([entityIdSchema, entityIdSchema]) });
|
|
4456
|
+
z.object({ with: integrationIdSchema });
|
|
4457
|
+
z.object({ with: entityIdSchema });
|
|
4458
|
+
z.object({ preview: z.stringbool().default(false) });
|
|
4459
|
+
/** What uses an address: what follows an entity when it is linked or unlinked. */
|
|
4460
|
+
const linkUseSchema = z.object({
|
|
4461
|
+
automations: z.array(z.string()),
|
|
4462
|
+
scenes: z.array(z.string()),
|
|
4463
|
+
aliases: z.array(z.string()),
|
|
4464
|
+
/** Cards, by dashboard. */
|
|
4465
|
+
cards: z.array(z.object({
|
|
4466
|
+
dashboard: z.string(),
|
|
4467
|
+
count: z.int().min(1)
|
|
4468
|
+
}))
|
|
4469
|
+
});
|
|
4470
|
+
/** One entity in a link's account. */
|
|
4471
|
+
const linkSideSchema = z.object({
|
|
4472
|
+
entityId: entityIdSchema,
|
|
4473
|
+
name: z.string(),
|
|
4474
|
+
deviceId: integrationIdSchema,
|
|
4475
|
+
vendorId: z.string(),
|
|
4476
|
+
transport: z.string(),
|
|
4477
|
+
usedBy: linkUseSchema
|
|
4478
|
+
});
|
|
4479
|
+
/** Entities that are, or would be, one: the one that leads, and those that read through it. */
|
|
4480
|
+
const linkPairSchema = z.object({
|
|
4481
|
+
holder: linkSideSchema,
|
|
4482
|
+
others: z.array(linkSideSchema).min(1),
|
|
4483
|
+
origin: z.enum(LINK_ORIGINS)
|
|
4484
|
+
});
|
|
4485
|
+
/** A device in a link's account. */
|
|
4486
|
+
const linkDeviceSchema = z.object({
|
|
4487
|
+
id: integrationIdSchema,
|
|
4488
|
+
name: z.string(),
|
|
4489
|
+
model: z.string().nullable(),
|
|
4490
|
+
vendorId: z.string(),
|
|
4491
|
+
transport: z.string(),
|
|
4492
|
+
areaName: z.string().nullable()
|
|
4493
|
+
});
|
|
4494
|
+
z.object({
|
|
4495
|
+
action: z.enum(["link", "unlink"]),
|
|
4496
|
+
scope: z.enum(["device", "entity"]),
|
|
4497
|
+
/** The device the house shows, and the other way into it; null for an entity's link. */
|
|
4498
|
+
device: linkDeviceSchema.nullable(),
|
|
4499
|
+
other: linkDeviceSchema.nullable(),
|
|
4500
|
+
/** What is linked, or unlinked. */
|
|
4501
|
+
pairs: z.array(linkPairSchema),
|
|
4502
|
+
/** What a device's link leaves read one way. */
|
|
4503
|
+
single: z.array(linkSideSchema),
|
|
4504
|
+
/** The way read first, after a link; the way the leading entity keeps, after an unlink. */
|
|
4505
|
+
preferred: z.object({
|
|
4506
|
+
deviceId: integrationIdSchema,
|
|
4507
|
+
vendorId: z.string(),
|
|
4508
|
+
transport: z.string()
|
|
4509
|
+
}),
|
|
4510
|
+
/** Since when the entities were linked, for an unlink. */
|
|
4511
|
+
linkedSince: timestampSchema.nullable()
|
|
4512
|
+
});
|
|
4513
|
+
/** One device in a suggestion. */
|
|
4514
|
+
const suggestedDeviceSchema = z.object({
|
|
4515
|
+
id: integrationIdSchema,
|
|
4516
|
+
name: z.string(),
|
|
4517
|
+
model: z.string().nullable(),
|
|
4518
|
+
vendorId: z.string(),
|
|
4519
|
+
transport: z.string(),
|
|
4520
|
+
createdAt: timestampSchema
|
|
4521
|
+
});
|
|
4522
|
+
/**
|
|
4523
|
+
* Two devices that look like one, offered to link: the one the house had first, and the newer
|
|
4524
|
+
* way in.
|
|
4525
|
+
*/
|
|
4526
|
+
const linkSuggestionViewSchema = z.object({
|
|
4527
|
+
id: z.uuid(),
|
|
4528
|
+
vendorId: z.string().regex(VENDOR_ID_PATTERN$1),
|
|
4529
|
+
device: suggestedDeviceSchema,
|
|
4530
|
+
twin: suggestedDeviceSchema,
|
|
4531
|
+
reasons: z.array(linkReasonSchema),
|
|
4532
|
+
/** When the owner set it aside; null while it is offered. */
|
|
4533
|
+
dismissedAt: timestampSchema.nullable(),
|
|
4534
|
+
createdAt: timestampSchema
|
|
4535
|
+
});
|
|
4536
|
+
z.object({ items: z.array(linkSuggestionViewSchema) });
|
|
4537
|
+
z.object({ isDismissed: z.boolean() });
|
|
4538
|
+
//#endregion
|
|
4303
4539
|
//#region ../contracts/dist/matter.js
|
|
4304
4540
|
/**
|
|
4305
4541
|
* The house's Matter fabric, as the hub runs it and the Brokers page shows it.
|
|
@@ -4318,6 +4554,8 @@ z.object({
|
|
|
4318
4554
|
const MATTER_TRANSPORT = "matter";
|
|
4319
4555
|
/** The platform's own vendor: the Matter devices no integration claims. */
|
|
4320
4556
|
const MATTER_VENDOR = "matter";
|
|
4557
|
+
/** The UDP port the controller listens on, which the engine does not let anyone change. */
|
|
4558
|
+
const MATTER_PORT = 5540;
|
|
4321
4559
|
/** A node id, in decimal: a 64-bit number, which JSON cannot carry as a number. */
|
|
4322
4560
|
const matterNodeIdSchema = z.string().regex(/^[0-9]{1,20}$/u, "Must be a node id");
|
|
4323
4561
|
/**
|
|
@@ -4369,23 +4607,76 @@ const MATTER_CONTROLLER_STATES = [
|
|
|
4369
4607
|
"disabled"
|
|
4370
4608
|
];
|
|
4371
4609
|
/**
|
|
4372
|
-
*
|
|
4373
|
-
*
|
|
4374
|
-
* until it ends.
|
|
4610
|
+
* How a commissioning goes. `needs-answer` is a job that stopped before the node joined and waits
|
|
4611
|
+
* for the owner: a device whose certificate is a test one, added only when they say so.
|
|
4375
4612
|
*/
|
|
4376
|
-
const
|
|
4377
|
-
|
|
4613
|
+
const MATTER_COMMISSIONING_STATES = [
|
|
4614
|
+
"running",
|
|
4615
|
+
"needs-answer",
|
|
4616
|
+
"succeeded",
|
|
4617
|
+
"failed"
|
|
4618
|
+
];
|
|
4619
|
+
/**
|
|
4620
|
+
* The steps of a commissioning, in order: the code read, the device found on the network, its
|
|
4621
|
+
* certificate checked against the DCL, joining the fabric, reading what it can do, and the device
|
|
4622
|
+
* in the house.
|
|
4623
|
+
*/
|
|
4624
|
+
const MATTER_COMMISSIONING_STEPS = [
|
|
4625
|
+
"code",
|
|
4626
|
+
"found",
|
|
4627
|
+
"certificate",
|
|
4628
|
+
"joining",
|
|
4629
|
+
"reading",
|
|
4630
|
+
"in-house"
|
|
4631
|
+
];
|
|
4632
|
+
/** One step of a commissioning, and what it found. */
|
|
4633
|
+
const matterCommissioningStepSchema = z.object({
|
|
4634
|
+
id: z.enum(MATTER_COMMISSIONING_STEPS),
|
|
4378
4635
|
state: z.enum([
|
|
4636
|
+
"pending",
|
|
4379
4637
|
"running",
|
|
4380
|
-
"
|
|
4638
|
+
"done",
|
|
4639
|
+
"warning",
|
|
4381
4640
|
"failed"
|
|
4382
4641
|
]),
|
|
4642
|
+
/**
|
|
4643
|
+
* What the step found, as facts the page words itself: the discriminator a code carries, the
|
|
4644
|
+
* address and product a device answered with, the vendor and product a test certificate names.
|
|
4645
|
+
*/
|
|
4646
|
+
detail: z.object({
|
|
4647
|
+
discriminator: z.int().min(0).max(4095).nullable().default(null),
|
|
4648
|
+
isQrCode: z.boolean().default(false),
|
|
4649
|
+
address: z.string().max(256).nullable().default(null),
|
|
4650
|
+
product: z.string().max(256).nullable().default(null),
|
|
4651
|
+
vendorId: z.int().min(0).max(65535).nullable().default(null),
|
|
4652
|
+
productId: z.int().min(0).max(65535).nullable().default(null)
|
|
4653
|
+
}).default({
|
|
4654
|
+
discriminator: null,
|
|
4655
|
+
isQrCode: false,
|
|
4656
|
+
address: null,
|
|
4657
|
+
product: null,
|
|
4658
|
+
vendorId: null,
|
|
4659
|
+
productId: null
|
|
4660
|
+
})
|
|
4661
|
+
});
|
|
4662
|
+
/**
|
|
4663
|
+
* One commissioning: started by a pairing code, done once the device is in the house. A node takes
|
|
4664
|
+
* from seconds to a minute or two, longer than one request may wait, so the page reads the job
|
|
4665
|
+
* until it ends.
|
|
4666
|
+
*/
|
|
4667
|
+
const matterCommissioningSchema = z.object({
|
|
4668
|
+
id: z.string().min(1).max(64),
|
|
4669
|
+
state: z.enum(MATTER_COMMISSIONING_STATES),
|
|
4383
4670
|
startedAt: timestampSchema,
|
|
4384
4671
|
finishedAt: timestampSchema.nullable(),
|
|
4385
|
-
/** The node it made; null until it
|
|
4672
|
+
/** The node it made; null until it is on the fabric. */
|
|
4386
4673
|
nodeId: matterNodeIdSchema.nullable(),
|
|
4387
4674
|
/** Why it failed, in a sentence; null unless it did. */
|
|
4388
|
-
error: z.string().max(2048).nullable()
|
|
4675
|
+
error: z.string().max(2048).nullable(),
|
|
4676
|
+
/** Each step in order, with how it stands. */
|
|
4677
|
+
steps: z.array(matterCommissioningStepSchema).max(MATTER_COMMISSIONING_STEPS.length).default([]),
|
|
4678
|
+
/** The device it became in the house; null until it is in. */
|
|
4679
|
+
deviceId: integrationIdSchema.nullable().default(null)
|
|
4389
4680
|
});
|
|
4390
4681
|
z.object({
|
|
4391
4682
|
state: z.enum(MATTER_CONTROLLER_STATES),
|
|
@@ -4403,7 +4694,15 @@ z.object({
|
|
|
4403
4694
|
online: z.int().min(0)
|
|
4404
4695
|
}),
|
|
4405
4696
|
/** The last commissioning; null when none was started since the hub started. */
|
|
4406
|
-
commissioning: matterCommissioningSchema.nullable()
|
|
4697
|
+
commissioning: matterCommissioningSchema.nullable(),
|
|
4698
|
+
/** When the controller last started; null while it is not running. */
|
|
4699
|
+
startedAt: timestampSchema.nullable().default(null),
|
|
4700
|
+
/** The engine under the controller, as `matter.js 0.17`. */
|
|
4701
|
+
controllerVersion: z.string().max(64).nullable().default(null),
|
|
4702
|
+
/** The UDP port the controller listens on. */
|
|
4703
|
+
port: z.int().min(1).max(65535).default(MATTER_PORT),
|
|
4704
|
+
/** When this hub made the fabric; null for one made before the hub kept the date. */
|
|
4705
|
+
fabricCreatedAt: timestampSchema.nullable().default(null)
|
|
4407
4706
|
});
|
|
4408
4707
|
/** One device a node is in the house: the node itself, or one endpoint behind a bridge. */
|
|
4409
4708
|
const matterNodeDeviceSchema = z.object({
|
|
@@ -4416,8 +4715,8 @@ const matterNodeDeviceSchema = z.object({
|
|
|
4416
4715
|
/** The driver it was added as; null while it is not added. */
|
|
4417
4716
|
kind: integrationKindIdSchema.nullable(),
|
|
4418
4717
|
/**
|
|
4419
|
-
* The integrations whose rules all take it
|
|
4420
|
-
* platform's own
|
|
4718
|
+
* The integrations whose rules all take it. One is the integration it belongs to; several, and it
|
|
4719
|
+
* is added as the platform's own and the page says who else wants it. Empty when none takes it.
|
|
4421
4720
|
*/
|
|
4422
4721
|
claimedBy: z.array(z.string().regex(VENDOR_ID_PATTERN$1)).max(16),
|
|
4423
4722
|
/** Removed from the house, its node still on the fabric: the page offers it back. */
|
|
@@ -4427,6 +4726,10 @@ const matterNodeDeviceSchema = z.object({
|
|
|
4427
4726
|
const matterNodeSchema = z.object({
|
|
4428
4727
|
nodeId: matterNodeIdSchema,
|
|
4429
4728
|
isAvailable: z.boolean(),
|
|
4729
|
+
/** When it joined the fabric, as the controller recorded it; null when it did not say. */
|
|
4730
|
+
commissionedAt: timestampSchema.nullable().default(null),
|
|
4731
|
+
/** Since when it has not answered, as far as this hub saw; null while it answers. */
|
|
4732
|
+
offlineSince: timestampSchema.nullable().default(null),
|
|
4430
4733
|
/** The node itself first, then each device behind it when it is a bridge. */
|
|
4431
4734
|
devices: z.array(matterNodeDeviceSchema).min(1).max(256)
|
|
4432
4735
|
});
|
|
@@ -4441,16 +4744,24 @@ z.object({
|
|
|
4441
4744
|
endpoint: z.int().min(0).max(65535).nullable()
|
|
4442
4745
|
});
|
|
4443
4746
|
z.object({ isRestored: z.boolean() });
|
|
4747
|
+
z.object({
|
|
4748
|
+
jobId: z.string().min(1).max(64),
|
|
4749
|
+
isAccepted: z.boolean()
|
|
4750
|
+
});
|
|
4444
4751
|
/** The brokers the platform runs, as the Brokers page lists them. */
|
|
4445
4752
|
const BROKER_IDS = [MATTER_VENDOR];
|
|
4446
4753
|
/** One broker, for its card. */
|
|
4447
4754
|
const brokerSummarySchema = z.object({
|
|
4448
4755
|
id: z.enum(BROKER_IDS),
|
|
4449
4756
|
state: z.enum(MATTER_CONTROLLER_STATES),
|
|
4450
|
-
/**
|
|
4757
|
+
/**
|
|
4758
|
+
* The devices the house has through it, how many of them answer, and how many are also
|
|
4759
|
+
* reached another way.
|
|
4760
|
+
*/
|
|
4451
4761
|
devices: z.object({
|
|
4452
4762
|
total: z.int().min(0),
|
|
4453
|
-
online: z.int().min(0)
|
|
4763
|
+
online: z.int().min(0),
|
|
4764
|
+
linked: z.int().min(0).default(0)
|
|
4454
4765
|
})
|
|
4455
4766
|
});
|
|
4456
4767
|
z.object({ items: z.array(brokerSummarySchema) });
|
|
@@ -4593,6 +4904,12 @@ const vendorManifestSchema = z.strictObject({
|
|
|
4593
4904
|
/** Whether the devices stop working when the internet does. Shown as a warning on the card. */
|
|
4594
4905
|
internetRequired: z.boolean().default(false),
|
|
4595
4906
|
/**
|
|
4907
|
+
* What makes two of the vendor's devices one device reached two ways - over its own transport
|
|
4908
|
+
* and through the Matter broker, say: `["mac"]`, or `["mac", "serial"]` for both to agree.
|
|
4909
|
+
* The house then offers to link them. Absent, it never does.
|
|
4910
|
+
*/
|
|
4911
|
+
twins: z.array(z.enum(TWIN_FACTS)).min(1).max(TWIN_FACTS.length).optional(),
|
|
4912
|
+
/**
|
|
4596
4913
|
* Path to a `setup.json` of settings every device of this vendor shares - a cloud API key,
|
|
4597
4914
|
* an account - relative to the bundle. Absent for the vendors whose devices are reached
|
|
4598
4915
|
* directly, which is most of them.
|
|
@@ -5410,6 +5727,8 @@ function createDeclarativeIntegration(manifest, profile) {
|
|
|
5410
5727
|
const model = text(identity.model);
|
|
5411
5728
|
const swVersion = text(identity.swVersion);
|
|
5412
5729
|
const hwVersion = text(identity.hwVersion);
|
|
5730
|
+
const mac = normalizeMac(text(identity.mac)) ?? void 0;
|
|
5731
|
+
const serialNumber = text(identity.serialNumber);
|
|
5413
5732
|
const entities = profile.entities.map((entity) => {
|
|
5414
5733
|
const measurement = registeredMeasurement(entity);
|
|
5415
5734
|
return {
|
|
@@ -5419,7 +5738,8 @@ function createDeclarativeIntegration(manifest, profile) {
|
|
|
5419
5738
|
...entity.icon === void 0 ? {} : { icon: entity.icon },
|
|
5420
5739
|
capabilities: entity.capabilities,
|
|
5421
5740
|
...measurement,
|
|
5422
|
-
...entity.displayPrecision === void 0 ? {} : { displayPrecision: entity.displayPrecision }
|
|
5741
|
+
...entity.displayPrecision === void 0 ? {} : { displayPrecision: entity.displayPrecision },
|
|
5742
|
+
...entity.link === void 0 ? {} : { link: entity.link }
|
|
5423
5743
|
};
|
|
5424
5744
|
});
|
|
5425
5745
|
return {
|
|
@@ -5429,6 +5749,8 @@ function createDeclarativeIntegration(manifest, profile) {
|
|
|
5429
5749
|
...model === void 0 ? {} : { model },
|
|
5430
5750
|
...swVersion === void 0 ? {} : { swVersion },
|
|
5431
5751
|
...hwVersion === void 0 ? {} : { hwVersion },
|
|
5752
|
+
...mac === void 0 ? {} : { mac },
|
|
5753
|
+
...serialNumber === void 0 ? {} : { serialNumber },
|
|
5432
5754
|
entities
|
|
5433
5755
|
};
|
|
5434
5756
|
},
|
|
@@ -5690,7 +6012,13 @@ const identityMappingSchema = z.strictObject({
|
|
|
5690
6012
|
manufacturer: pathSchema.optional(),
|
|
5691
6013
|
model: pathSchema.optional(),
|
|
5692
6014
|
swVersion: pathSchema.optional(),
|
|
5693
|
-
hwVersion: pathSchema.optional()
|
|
6015
|
+
hwVersion: pathSchema.optional(),
|
|
6016
|
+
/**
|
|
6017
|
+
* The hardware's MAC address, written any way - `08F9E0124C7A`, `08:f9:e0:12:4c:7a` - so the
|
|
6018
|
+
* house can tell this device from the same one reached another way.
|
|
6019
|
+
*/
|
|
6020
|
+
mac: pathSchema.optional(),
|
|
6021
|
+
serialNumber: pathSchema.optional()
|
|
5694
6022
|
});
|
|
5695
6023
|
/**
|
|
5696
6024
|
* A path into the command, with what to do to what it names.
|
|
@@ -5786,6 +6114,13 @@ const entityProfileSchema = z.strictObject({
|
|
|
5786
6114
|
stateClass: z.enum(ENTITY_STATE_CLASSES).optional(),
|
|
5787
6115
|
displayPrecision: z.int().min(0).max(6).optional(),
|
|
5788
6116
|
/**
|
|
6117
|
+
* What links it to the same reading reached another way: its key in the transport's terms
|
|
6118
|
+
* (`switch:0`), shown beside the transport's name, and where that reading sits in Matter
|
|
6119
|
+
* (`{ "endpoint": 1, "cluster": 6, "attribute": 0 }`), for a device the house also reaches
|
|
6120
|
+
* through the Matter broker.
|
|
6121
|
+
*/
|
|
6122
|
+
link: entityLinkHintSchema.optional(),
|
|
6123
|
+
/**
|
|
5789
6124
|
* For a camera: the stream source that reads its picture, `<vendor>/<name>`, and what it is
|
|
5790
6125
|
* told to read. The source is handed the instance's transport settings as well.
|
|
5791
6126
|
*/
|
|
@@ -5935,7 +6270,15 @@ const discoveryIdentitySchema = z.strictObject({
|
|
|
5935
6270
|
/** What makes the device the same device next time: the same value identification reads. */
|
|
5936
6271
|
externalId: identityPathSchema.optional(),
|
|
5937
6272
|
name: identityPathSchema.optional(),
|
|
5938
|
-
swVersion: identityPathSchema.optional()
|
|
6273
|
+
swVersion: identityPathSchema.optional(),
|
|
6274
|
+
/** Its MAC address, written any way the device writes it: what tells it from its twin. */
|
|
6275
|
+
mac: identityPathSchema.optional(),
|
|
6276
|
+
serialNumber: identityPathSchema.optional(),
|
|
6277
|
+
/**
|
|
6278
|
+
* Where the device says it is behind a password - `auth_en` on a Shelly - so its row says so
|
|
6279
|
+
* before anyone tries to add it. True there means a password is needed.
|
|
6280
|
+
*/
|
|
6281
|
+
auth: identityPathSchema.optional()
|
|
5939
6282
|
});
|
|
5940
6283
|
/**
|
|
5941
6284
|
* What to ask an announced address.
|
|
@@ -6080,11 +6423,15 @@ function textAt(payload, path) {
|
|
|
6080
6423
|
*/
|
|
6081
6424
|
function identifySighting(plan, payload) {
|
|
6082
6425
|
const { identity } = plan.discovery;
|
|
6426
|
+
const auth = identity.auth === void 0 ? [] : [identity.auth].flat();
|
|
6083
6427
|
return {
|
|
6084
6428
|
externalId: textAt(payload, identity.externalId),
|
|
6085
6429
|
name: textAt(payload, identity.name),
|
|
6086
6430
|
modelCode: textAt(payload, identity.model),
|
|
6087
|
-
swVersion: textAt(payload, identity.swVersion)
|
|
6431
|
+
swVersion: textAt(payload, identity.swVersion),
|
|
6432
|
+
mac: normalizeMac(textAt(payload, identity.mac)),
|
|
6433
|
+
serialNumber: textAt(payload, identity.serialNumber),
|
|
6434
|
+
needsPassword: auth.some((path) => resolvePath(payload, path) === true)
|
|
6088
6435
|
};
|
|
6089
6436
|
}
|
|
6090
6437
|
/**
|
|
@@ -8504,7 +8851,12 @@ function matterEntitiesOf(device) {
|
|
|
8504
8851
|
descriptor: {
|
|
8505
8852
|
...descriptor,
|
|
8506
8853
|
objectId,
|
|
8507
|
-
name: isShared ? `${descriptor.name} ${String(rest.endpoint)}` : descriptor.name
|
|
8854
|
+
name: isShared ? `${descriptor.name} ${String(rest.endpoint)}` : descriptor.name,
|
|
8855
|
+
link: { matter: {
|
|
8856
|
+
endpoint: rest.endpoint,
|
|
8857
|
+
cluster: rest.clusters[0] ?? 0,
|
|
8858
|
+
attribute: rest.attribute ?? 0
|
|
8859
|
+
} }
|
|
8508
8860
|
}
|
|
8509
8861
|
};
|
|
8510
8862
|
});
|
|
@@ -8607,9 +8959,12 @@ function createMatterIntegration(manifest) {
|
|
|
8607
8959
|
const device = deviceOf(claim.descriptor);
|
|
8608
8960
|
if (device === void 0) throw new ValidationError(`${manifest.id} cannot describe a claim with no Matter device`, { details: { integration: manifest.id } });
|
|
8609
8961
|
const { identity } = device;
|
|
8962
|
+
const mac = identity.macAddresses.map(normalizeMac).find((each) => each !== null);
|
|
8610
8963
|
return {
|
|
8611
8964
|
externalId: claim.externalId,
|
|
8612
8965
|
name: nameOf$1(identity).slice(0, 128),
|
|
8966
|
+
...mac === void 0 ? {} : { mac },
|
|
8967
|
+
...identity.serialNumber === null ? {} : { serialNumber: identity.serialNumber },
|
|
8613
8968
|
...identity.vendorName === null ? {} : { manufacturer: identity.vendorName },
|
|
8614
8969
|
...identity.productName === null ? {} : { model: identity.productName },
|
|
8615
8970
|
...identity.softwareVersionString === null ? {} : { swVersion: identity.softwareVersionString.slice(0, 64) },
|
|
@@ -199,10 +199,8 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
|
|
|
199
199
|
*/
|
|
200
200
|
declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
201
201
|
number: "number";
|
|
202
|
-
custom: "custom";
|
|
203
|
-
image: "image";
|
|
204
|
-
level: "level";
|
|
205
202
|
on_off: "on_off";
|
|
203
|
+
level: "level";
|
|
206
204
|
color_hs: "color_hs";
|
|
207
205
|
color_temp: "color_temp";
|
|
208
206
|
cover: "cover";
|
|
@@ -218,9 +216,25 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
|
218
216
|
lawn_mower: "lawn_mower";
|
|
219
217
|
select: "select";
|
|
220
218
|
vacuum: "vacuum";
|
|
219
|
+
image: "image";
|
|
220
|
+
custom: "custom";
|
|
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>;
|
|
224
|
+
/**
|
|
225
|
+
* What lets an entity be told apart from the same reading reached another way: its own key in its
|
|
226
|
+
* transport's terms - `switch:0` on a Shelly - and where it sits in Matter.
|
|
227
|
+
*/
|
|
228
|
+
declare const entityLinkHintSchema: z.ZodObject<{
|
|
229
|
+
key: z.ZodOptional<z.ZodString>;
|
|
230
|
+
matter: z.ZodOptional<z.ZodObject<{
|
|
231
|
+
endpoint: z.ZodInt;
|
|
232
|
+
cluster: z.ZodInt;
|
|
233
|
+
attribute: z.ZodInt;
|
|
234
|
+
}, z.core.$strict>>;
|
|
235
|
+
}, z.core.$strict>;
|
|
236
|
+
/** What lets an entity be told apart from the same reading reached another way. */
|
|
237
|
+
type EntityLinkHint = z.output<typeof entityLinkHintSchema>;
|
|
224
238
|
//#endregion
|
|
225
239
|
//#region ../contracts/dist/entity-state.d.ts
|
|
226
240
|
/**
|
|
@@ -915,6 +929,8 @@ type EntityDescriptor = {
|
|
|
915
929
|
readonly deviceClass?: string;
|
|
916
930
|
readonly stateClass?: EntityStateClass;
|
|
917
931
|
readonly displayPrecision?: number;
|
|
932
|
+
/** What links it to the same reading reached another way. */
|
|
933
|
+
readonly link?: EntityLinkHint;
|
|
918
934
|
};
|
|
919
935
|
/** What a claimed device turns out to be. */
|
|
920
936
|
type DeviceDescriptor = {
|
|
@@ -924,6 +940,9 @@ type DeviceDescriptor = {
|
|
|
924
940
|
readonly model?: string;
|
|
925
941
|
readonly swVersion?: string;
|
|
926
942
|
readonly hwVersion?: string;
|
|
943
|
+
/** The hardware's MAC address, lower case with colons, when it says one. */
|
|
944
|
+
readonly mac?: string;
|
|
945
|
+
readonly serialNumber?: string;
|
|
927
946
|
/**
|
|
928
947
|
* The device this one is reached through, named the way this integration names devices.
|
|
929
948
|
*
|
|
@@ -1648,6 +1667,10 @@ declare const vendorManifestSchema: z.ZodObject<{
|
|
|
1648
1667
|
padding: number;
|
|
1649
1668
|
}>>>;
|
|
1650
1669
|
internetRequired: z.ZodDefault<z.ZodBoolean>;
|
|
1670
|
+
twins: z.ZodOptional<z.ZodArray<z.ZodEnum<{
|
|
1671
|
+
mac: "mac";
|
|
1672
|
+
serial: "serial";
|
|
1673
|
+
}>>>;
|
|
1651
1674
|
setup: z.ZodOptional<z.ZodString>;
|
|
1652
1675
|
account: z.ZodOptional<z.ZodString>;
|
|
1653
1676
|
transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
@@ -1836,6 +1859,9 @@ declare const vendorDiscoverySchema: z.ZodObject<{
|
|
|
1836
1859
|
externalId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1837
1860
|
name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1838
1861
|
swVersion: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1862
|
+
mac: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1863
|
+
serialNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1864
|
+
auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
1839
1865
|
}, z.core.$strict>>;
|
|
1840
1866
|
matter: z.ZodOptional<z.ZodObject<{
|
|
1841
1867
|
match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
|
|
@@ -1908,6 +1934,11 @@ type SightingIdentity = {
|
|
|
1908
1934
|
readonly name: string | null;
|
|
1909
1935
|
readonly modelCode: string | null;
|
|
1910
1936
|
readonly swVersion: string | null;
|
|
1937
|
+
/** Lower case with colons. */
|
|
1938
|
+
readonly mac: string | null;
|
|
1939
|
+
readonly serialNumber: string | null;
|
|
1940
|
+
/** Whether it said it is behind a password; false when it did not say. */
|
|
1941
|
+
readonly needsPassword: boolean;
|
|
1911
1942
|
};
|
|
1912
1943
|
/** The driver a device belongs to, and which of its models it is. */
|
|
1913
1944
|
type Association = {
|
|
@@ -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.
|
|
92
|
+
const SDK_VERSION = "1.2.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
|
@@ -199,10 +199,8 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
|
|
|
199
199
|
*/
|
|
200
200
|
declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
201
201
|
number: "number";
|
|
202
|
-
custom: "custom";
|
|
203
|
-
image: "image";
|
|
204
|
-
level: "level";
|
|
205
202
|
on_off: "on_off";
|
|
203
|
+
level: "level";
|
|
206
204
|
color_hs: "color_hs";
|
|
207
205
|
color_temp: "color_temp";
|
|
208
206
|
cover: "cover";
|
|
@@ -218,9 +216,25 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
|
218
216
|
lawn_mower: "lawn_mower";
|
|
219
217
|
select: "select";
|
|
220
218
|
vacuum: "vacuum";
|
|
219
|
+
image: "image";
|
|
220
|
+
custom: "custom";
|
|
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>;
|
|
224
|
+
/**
|
|
225
|
+
* What lets an entity be told apart from the same reading reached another way: its own key in its
|
|
226
|
+
* transport's terms - `switch:0` on a Shelly - and where it sits in Matter.
|
|
227
|
+
*/
|
|
228
|
+
declare const entityLinkHintSchema: z.ZodObject<{
|
|
229
|
+
key: z.ZodOptional<z.ZodString>;
|
|
230
|
+
matter: z.ZodOptional<z.ZodObject<{
|
|
231
|
+
endpoint: z.ZodInt;
|
|
232
|
+
cluster: z.ZodInt;
|
|
233
|
+
attribute: z.ZodInt;
|
|
234
|
+
}, z.core.$strict>>;
|
|
235
|
+
}, z.core.$strict>;
|
|
236
|
+
/** What lets an entity be told apart from the same reading reached another way. */
|
|
237
|
+
type EntityLinkHint = z.output<typeof entityLinkHintSchema>;
|
|
224
238
|
//#endregion
|
|
225
239
|
//#region ../contracts/dist/entity-state.d.ts
|
|
226
240
|
/**
|
|
@@ -680,6 +694,8 @@ type EntityDescriptor = {
|
|
|
680
694
|
readonly deviceClass?: string;
|
|
681
695
|
readonly stateClass?: EntityStateClass;
|
|
682
696
|
readonly displayPrecision?: number;
|
|
697
|
+
/** What links it to the same reading reached another way. */
|
|
698
|
+
readonly link?: EntityLinkHint;
|
|
683
699
|
};
|
|
684
700
|
/** What a claimed device turns out to be. */
|
|
685
701
|
type DeviceDescriptor = {
|
|
@@ -689,6 +705,9 @@ type DeviceDescriptor = {
|
|
|
689
705
|
readonly model?: string;
|
|
690
706
|
readonly swVersion?: string;
|
|
691
707
|
readonly hwVersion?: string;
|
|
708
|
+
/** The hardware's MAC address, lower case with colons, when it says one. */
|
|
709
|
+
readonly mac?: string;
|
|
710
|
+
readonly serialNumber?: string;
|
|
692
711
|
/**
|
|
693
712
|
* The device this one is reached through, named the way this integration names devices.
|
|
694
713
|
*
|
package/dist/schemas.d.ts
CHANGED
|
@@ -20,6 +20,10 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
20
20
|
padding: number;
|
|
21
21
|
}>>>;
|
|
22
22
|
internetRequired: z.ZodDefault<z.ZodBoolean>;
|
|
23
|
+
twins: z.ZodOptional<z.ZodArray<z.ZodEnum<{
|
|
24
|
+
mac: "mac";
|
|
25
|
+
serial: "serial";
|
|
26
|
+
}>>>;
|
|
23
27
|
setup: z.ZodOptional<z.ZodString>;
|
|
24
28
|
account: z.ZodOptional<z.ZodString>;
|
|
25
29
|
transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
@@ -363,6 +367,8 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
363
367
|
model: z.ZodOptional<z.ZodString>;
|
|
364
368
|
swVersion: z.ZodOptional<z.ZodString>;
|
|
365
369
|
hwVersion: z.ZodOptional<z.ZodString>;
|
|
370
|
+
mac: z.ZodOptional<z.ZodString>;
|
|
371
|
+
serialNumber: z.ZodOptional<z.ZodString>;
|
|
366
372
|
}, z.core.$strict>;
|
|
367
373
|
}, z.core.$strict>;
|
|
368
374
|
subscriptions: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
@@ -399,10 +405,8 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
399
405
|
icon: z.ZodOptional<z.ZodString>;
|
|
400
406
|
capabilities: z.ZodRecord<z.ZodEnum<{
|
|
401
407
|
number: "number";
|
|
402
|
-
custom: "custom";
|
|
403
|
-
image: "image";
|
|
404
|
-
level: "level";
|
|
405
408
|
on_off: "on_off";
|
|
409
|
+
level: "level";
|
|
406
410
|
color_hs: "color_hs";
|
|
407
411
|
color_temp: "color_temp";
|
|
408
412
|
cover: "cover";
|
|
@@ -418,6 +422,8 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
418
422
|
lawn_mower: "lawn_mower";
|
|
419
423
|
select: "select";
|
|
420
424
|
vacuum: "vacuum";
|
|
425
|
+
image: "image";
|
|
426
|
+
custom: "custom";
|
|
421
427
|
}> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
|
|
422
428
|
state: z.ZodRecord<z.ZodEnum<{
|
|
423
429
|
number: "number";
|
|
@@ -526,6 +532,14 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
526
532
|
total_increasing: "total_increasing";
|
|
527
533
|
}>>;
|
|
528
534
|
displayPrecision: z.ZodOptional<z.ZodInt>;
|
|
535
|
+
link: z.ZodOptional<z.ZodObject<{
|
|
536
|
+
key: z.ZodOptional<z.ZodString>;
|
|
537
|
+
matter: z.ZodOptional<z.ZodObject<{
|
|
538
|
+
endpoint: z.ZodInt;
|
|
539
|
+
cluster: z.ZodInt;
|
|
540
|
+
attribute: z.ZodInt;
|
|
541
|
+
}, z.core.$strict>>;
|
|
542
|
+
}, z.core.$strict>>;
|
|
529
543
|
stream: z.ZodOptional<z.ZodObject<{
|
|
530
544
|
source: z.ZodString;
|
|
531
545
|
args: z.ZodDefault<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
|
|
@@ -586,6 +600,9 @@ export declare const BUNDLE_FILE_SCHEMAS: {
|
|
|
586
600
|
externalId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
587
601
|
name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
588
602
|
swVersion: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
603
|
+
mac: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
604
|
+
serialNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
605
|
+
auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
589
606
|
}, z.core.$strict>>;
|
|
590
607
|
matter: z.ZodOptional<z.ZodObject<{
|
|
591
608
|
match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nebulahome/integration-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.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": "0.0.0",
|
|
66
|
-
"@nebulahome/
|
|
66
|
+
"@nebulahome/eslint-config": "0.0.0",
|
|
67
67
|
"@nebulahome/package-runtime": "0.0.0",
|
|
68
|
-
"@nebulahome/
|
|
68
|
+
"@nebulahome/tsconfig": "0.0.0"
|
|
69
69
|
},
|
|
70
70
|
"scripts": {
|
|
71
71
|
"build": "tsdown && node scripts/build-schemas.js",
|
|
@@ -333,6 +333,69 @@
|
|
|
333
333
|
}
|
|
334
334
|
}
|
|
335
335
|
]
|
|
336
|
+
},
|
|
337
|
+
"mac": {
|
|
338
|
+
"anyOf": [
|
|
339
|
+
{
|
|
340
|
+
"type": "string",
|
|
341
|
+
"minLength": 1,
|
|
342
|
+
"maxLength": 256,
|
|
343
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
344
|
+
},
|
|
345
|
+
{
|
|
346
|
+
"minItems": 1,
|
|
347
|
+
"maxItems": 4,
|
|
348
|
+
"type": "array",
|
|
349
|
+
"items": {
|
|
350
|
+
"type": "string",
|
|
351
|
+
"minLength": 1,
|
|
352
|
+
"maxLength": 256,
|
|
353
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
]
|
|
357
|
+
},
|
|
358
|
+
"serialNumber": {
|
|
359
|
+
"anyOf": [
|
|
360
|
+
{
|
|
361
|
+
"type": "string",
|
|
362
|
+
"minLength": 1,
|
|
363
|
+
"maxLength": 256,
|
|
364
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
365
|
+
},
|
|
366
|
+
{
|
|
367
|
+
"minItems": 1,
|
|
368
|
+
"maxItems": 4,
|
|
369
|
+
"type": "array",
|
|
370
|
+
"items": {
|
|
371
|
+
"type": "string",
|
|
372
|
+
"minLength": 1,
|
|
373
|
+
"maxLength": 256,
|
|
374
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
]
|
|
378
|
+
},
|
|
379
|
+
"auth": {
|
|
380
|
+
"anyOf": [
|
|
381
|
+
{
|
|
382
|
+
"type": "string",
|
|
383
|
+
"minLength": 1,
|
|
384
|
+
"maxLength": 256,
|
|
385
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
386
|
+
},
|
|
387
|
+
{
|
|
388
|
+
"minItems": 1,
|
|
389
|
+
"maxItems": 4,
|
|
390
|
+
"type": "array",
|
|
391
|
+
"items": {
|
|
392
|
+
"type": "string",
|
|
393
|
+
"minLength": 1,
|
|
394
|
+
"maxLength": 256,
|
|
395
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
]
|
|
336
399
|
}
|
|
337
400
|
},
|
|
338
401
|
"additionalProperties": false
|
|
@@ -60,6 +60,18 @@
|
|
|
60
60
|
"default": false,
|
|
61
61
|
"type": "boolean"
|
|
62
62
|
},
|
|
63
|
+
"twins": {
|
|
64
|
+
"minItems": 1,
|
|
65
|
+
"maxItems": 2,
|
|
66
|
+
"type": "array",
|
|
67
|
+
"items": {
|
|
68
|
+
"type": "string",
|
|
69
|
+
"enum": [
|
|
70
|
+
"mac",
|
|
71
|
+
"serial"
|
|
72
|
+
]
|
|
73
|
+
}
|
|
74
|
+
},
|
|
63
75
|
"setup": {
|
|
64
76
|
"type": "string",
|
|
65
77
|
"minLength": 1,
|
|
@@ -246,6 +246,18 @@
|
|
|
246
246
|
"minLength": 1,
|
|
247
247
|
"maxLength": 256,
|
|
248
248
|
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
249
|
+
},
|
|
250
|
+
"mac": {
|
|
251
|
+
"type": "string",
|
|
252
|
+
"minLength": 1,
|
|
253
|
+
"maxLength": 256,
|
|
254
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
255
|
+
},
|
|
256
|
+
"serialNumber": {
|
|
257
|
+
"type": "string",
|
|
258
|
+
"minLength": 1,
|
|
259
|
+
"maxLength": 256,
|
|
260
|
+
"pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')(?:\\.(?:[A-Za-z_][A-Za-z0-9_]*|'[^']+')|\\[[0-9]+\\])*$"
|
|
249
261
|
}
|
|
250
262
|
},
|
|
251
263
|
"required": [
|
|
@@ -1303,6 +1315,43 @@
|
|
|
1303
1315
|
"minimum": 0,
|
|
1304
1316
|
"maximum": 6
|
|
1305
1317
|
},
|
|
1318
|
+
"link": {
|
|
1319
|
+
"type": "object",
|
|
1320
|
+
"properties": {
|
|
1321
|
+
"key": {
|
|
1322
|
+
"type": "string",
|
|
1323
|
+
"minLength": 1,
|
|
1324
|
+
"maxLength": 64
|
|
1325
|
+
},
|
|
1326
|
+
"matter": {
|
|
1327
|
+
"type": "object",
|
|
1328
|
+
"properties": {
|
|
1329
|
+
"endpoint": {
|
|
1330
|
+
"type": "integer",
|
|
1331
|
+
"minimum": 0,
|
|
1332
|
+
"maximum": 65535
|
|
1333
|
+
},
|
|
1334
|
+
"cluster": {
|
|
1335
|
+
"type": "integer",
|
|
1336
|
+
"minimum": 0,
|
|
1337
|
+
"maximum": 9007199254740991
|
|
1338
|
+
},
|
|
1339
|
+
"attribute": {
|
|
1340
|
+
"type": "integer",
|
|
1341
|
+
"minimum": 0,
|
|
1342
|
+
"maximum": 9007199254740991
|
|
1343
|
+
}
|
|
1344
|
+
},
|
|
1345
|
+
"required": [
|
|
1346
|
+
"endpoint",
|
|
1347
|
+
"cluster",
|
|
1348
|
+
"attribute"
|
|
1349
|
+
],
|
|
1350
|
+
"additionalProperties": false
|
|
1351
|
+
}
|
|
1352
|
+
},
|
|
1353
|
+
"additionalProperties": false
|
|
1354
|
+
},
|
|
1306
1355
|
"stream": {
|
|
1307
1356
|
"type": "object",
|
|
1308
1357
|
"properties": {
|