@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 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. 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.
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
@@ -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
- /** Validates an instance lifecycle state. */
1804
- const integrationStateSchema = z.enum([
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
- * One commissioning: started by a pairing code, done once the node is on the fabric. A node takes
4373
- * from seconds to a minute or two, longer than one request may wait, so the page reads the job
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 matterCommissioningSchema = z.object({
4377
- id: z.string().min(1).max(64),
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
- "succeeded",
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 succeeded. */
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, when there are several: it is then added as the
4420
- * platform's own, and the page says who else wants it. Empty otherwise.
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
- /** The devices the house has through it, and how many of them answer. */
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.1.0";
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.1.0",
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/tsconfig": "0.0.0",
66
+ "@nebulahome/eslint-config": "0.0.0",
67
67
  "@nebulahome/package-runtime": "0.0.0",
68
- "@nebulahome/eslint-config": "0.0.0"
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": {