@nebulahome/integration-sdk 1.7.0 → 1.8.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,28 @@
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.8.0
7
+
8
+ One device reached more than one way.
9
+
10
+ - The twins of a vendor - its devices on different transports with the same `mac` or serial - link
11
+ their entities of the same `link.key` and domain when the owner links them, whichever ways they
12
+ are; until now an entity was linked by key only to a Matter one.
13
+ - `manifest.json` may say `twinsPrefer`: transports in order, the first the linked device is read
14
+ and commanded through while it answers - `["matter", "bluetooth", "acme/cloud"]`.
15
+ - A command on a linked entity that cannot reach the device one way - its transport down, the
16
+ device out of reach - goes the next way. One that timed out is not sent again: it may have been
17
+ done.
18
+ - The `bluetooth` transport answers `gatt.exchange`: a write, then the first notification on
19
+ another characteristic, for devices that answer each command.
20
+ - A code driver's `continueCommand(target, step, context)` carries a command through a
21
+ conversation with the device: handed each answer (`CommandStep`), it returns the next request, or
22
+ null when done; at most 8 steps in the command's one deadline. `driverHarness(...).converse()`
23
+ plays one against answers a test gives.
24
+ - `discovery.json` `bluetooth` may list up to four rule sets, the first that holds read; a model may
25
+ be some bytes of the advertisement's data - `{ "path", "bytes": [start, length], "mask" }` - and
26
+ of several places for it the first that reads a code the drivers map is the model.
27
+
6
28
  ## 1.7.0
7
29
 
8
30
  Bluetooth proxies scan as the hub decides.
package/FILES.md CHANGED
@@ -70,7 +70,16 @@ its `identity` reads, and its Matter identity's - and offers the owner to link t
70
70
  Matter node is added and as a suggestion on the vendor's page. Linked, it is one device with two
71
71
  ways in: its readings come the way the owner prefers, and the other way carries them while that
72
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.
73
+ which of its readings is which in Matter, or, between two ways of the vendor's own - its cloud and
74
+ its Bluetooth, say - which of them read the same thing.
75
+
76
+ `twinsPrefer` says which way into a linked device is read first, by transport, best first:
77
+ `["matter", "bluetooth", "switchbot/cloud"]` reads a SwitchBot through Matter while Matter answers,
78
+ then through Bluetooth, and through the cloud last. When twins are linked, the way whose transport
79
+ comes earliest is the one preferred, and the dialog says so before the owner confirms; the owner may
80
+ pick another on the device's page. Without it, the device the house had first is read first.
81
+ Commands go the same way, and to the next way when one cannot reach the device - a Bluetooth device
82
+ only proxies hear, a cloud that does not answer.
74
83
 
75
84
  `requires` says what the vendor's devices need besides the hub, in the grammar a
76
85
  package's manifest uses (PACKAGES.md §8, Dependencies):
@@ -251,10 +260,24 @@ that says some of what it knows only when asked - in a scan response - adds `"ac
251
260
  N` (1 to 1440): proxies rest passive, and every N minutes the hub asks the proxy hearing it best to
252
261
  scan actively until it hears the device again, 30 s at most. Its
253
262
  requests are GATT on the server's own adapter: `gatt.read { service, characteristic }` answers `{
254
- data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.notify { service,
255
- characteristic, isOn }`, whose values are delivered as `{ service, characteristic, data }` - hex
256
- throughout. They are refused when the server has no usable adapter, or only proxies hear the
257
- device: proxies listen and never connect. `BLUETOOTH_GATT_OPS` names them.
263
+ data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.exchange { service,
264
+ characteristic, notify, data, withResponse, timeoutMs }` - a request written to `characteristic`,
265
+ answered `{ data }` with the first value `notify` notifies after it (`withResponse` false and 5 s
266
+ unless said, 10 s at most) - and `gatt.notify { service, characteristic, isOn }`, whose values are
267
+ delivered as `{ service, characteristic, data }` - hex throughout. They are refused when the server
268
+ has no usable adapter, or only proxies hear the device: proxies listen and never connect - a
269
+ command to a device linked to another way then goes that way (`twinsPrefer`, above).
270
+ `BLUETOOTH_GATT_OPS` names them.
271
+
272
+ A device spoken to in a **conversation** - a lock that hands out a session first and takes the
273
+ command sealed with it, a blind that wants two frames - is a code driver with `continueCommand(
274
+ target, { request, answer, index }, context)` beside `toCommand`: the hub sends the request
275
+ `toCommand` built, hands the driver what the transport answered, and sends the request it returns,
276
+ until it returns null - eight requests at most, all within the command's deadline. Each step is a
277
+ pure function of the answers, as `toCommand` is; a throw fails the command with its message. A
278
+ command whose deadline passes is reported unanswered, and is never sent another way, since the
279
+ device may still carry it out. `driverHarness(...).converse(entityId, capability, command,
280
+ answers)` runs one in a test.
258
281
 
259
282
  `defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
260
283
  icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
@@ -318,9 +341,12 @@ endpoint, the cluster and the attribute the platform's Matter mapping reads it f
318
341
  cluster and attribute of an entity it reads from several: 0 for a light). When the device is
319
342
  linked, an entity whose `matter` names a Matter entity of the twin is linked to it at once,
320
343
  whatever it is; a sensor without one is linked when exactly one Matter sensor reads the same
321
- thing, and a control never without one. The identity's `mac` and `serialNumber` are what the twin
322
- is found by: `"identity": { "externalId": "id", "mac": "mac" }`, written any way the device writes
323
- it.
344
+ thing, and a control never without one. Between two ways of the vendor's own, neither of them
345
+ Matter, two entities with the same `key` in the same domain are linked at once - a cloud's `cover`
346
+ and the same device's Bluetooth `cover` - so a vendor reaching a device both ways gives each
347
+ reading the same key on both. The identity's `mac` and `serialNumber` are what the twin is found
348
+ by: `"identity": { "externalId": "id", "mac": "mac" }`, written any way the device writes it; a code
349
+ driver says them in its `describe`.
324
350
 
325
351
  An entity may report **attributes** beside its state: `"attributes": { "endsAt":
326
352
  "pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
@@ -569,7 +595,33 @@ sensor is heard as well as the house's own. The platform recognises BTHome senso
569
595
  `serviceUuids` (a list, read with `contains`) and `serviceData.'<uuid>'` (read with `exists`).
570
596
  UUIDs are lower case, a 16-bit one short: `fcd2`.
571
597
  - `model` - where the advertisement says its model, looked up in the `modelCodes` of the vendor's
572
- drivers on the `bluetooth` transport; `name` when absent.
598
+ drivers on the `bluetooth` transport; `name` when absent. A model kept in a byte of the data is
599
+ read as `{ "path", "bytes": [start, length], "mask" }`: the bytes from `start` - counted from the
600
+ end when below zero - each ANDed with `mask` (0-255) when given, written in lower-case hex: the
601
+ letter `H` with its top bit set reads `48` with `"mask": 127`. Data shorter than the bytes reads
602
+ nothing. A list of up to four places is tried in order, and the first that reads a code one of
603
+ the drivers maps is the model.
604
+
605
+ Devices that advertise in more than one way take a **list of up to four rule sets**; the first
606
+ whose `match` holds is the one whose `model` is read:
607
+
608
+ ```json
609
+ {
610
+ "bluetooth": [
611
+ {
612
+ "match": [{ "path": "serviceData.'fd3d'", "exists": true }],
613
+ "model": [
614
+ { "path": "serviceData.'fd3d'", "bytes": [-4, 4] },
615
+ { "path": "serviceData.'fd3d'", "bytes": [0, 1], "mask": 127 }
616
+ ]
617
+ },
618
+ {
619
+ "match": [{ "path": "serviceData.'0d00'", "exists": true }],
620
+ "model": { "path": "serviceData.'0d00'", "bytes": [0, 1], "mask": 127 }
621
+ }
622
+ ]
623
+ }
624
+ ```
573
625
 
574
626
  A vendor may have `serial` or `bluetooth` alone, with no `listen`.
575
627
 
@@ -2073,6 +2073,8 @@ const integrationVendorSchema = z.object({
2073
2073
  * as its manifest's `twins` says. Empty for a vendor that offers no links.
2074
2074
  */
2075
2075
  twins: z.array(z.enum(TWIN_FACTS)).max(TWIN_FACTS.length).default([]),
2076
+ /** Which way into a linked device is read first, by transport, best first; empty when it says none. */
2077
+ twinsPrefer: z.array(z.string().min(1).max(64)).max(8).default([]),
2076
2078
  /** The entities pairing is run by, for a vendor whose devices are paired through one of its own. */
2077
2079
  pairing: vendorPairingSchema.nullable().default(null),
2078
2080
  drivers: z.array(integrationKindSchema$1),
@@ -5147,6 +5149,13 @@ z.object({
5147
5149
  data: bluetoothHexSchema,
5148
5150
  withResponse: z.boolean().default(true)
5149
5151
  });
5152
+ z.object({
5153
+ ...gattTargetShape,
5154
+ notify: bluetoothUuidSchema,
5155
+ data: bluetoothHexSchema,
5156
+ withResponse: z.boolean().default(false),
5157
+ timeoutMs: z.int().min(100).max(1e4).default(5e3)
5158
+ });
5150
5159
  z.object({
5151
5160
  ...gattTargetShape,
5152
5161
  isOn: z.boolean()
@@ -6599,6 +6608,12 @@ const vendorManifestSchema = z.strictObject({
6599
6608
  */
6600
6609
  twins: z.array(z.enum(TWIN_FACTS)).min(1).max(TWIN_FACTS.length).optional(),
6601
6610
  /**
6611
+ * Which way into a linked device is read first, by transport, best first - `["matter",
6612
+ * "bluetooth", "acme/cloud"]`: the way whose transport comes earliest is preferred when twins
6613
+ * are linked, and the owner may pick another. Absent, the device the house had first is.
6614
+ */
6615
+ twinsPrefer: z.array(z.string().min(1).max(64)).min(1).max(8).optional(),
6616
+ /**
6602
6617
  * Path to a `setup.json` of settings every device of this vendor shares - a cloud API key,
6603
6618
  * an account - relative to the bundle. Absent for the vendors whose devices are reached
6604
6619
  * directly, which is most of them.
@@ -8149,17 +8164,43 @@ const modbusDiscoverySchema = brokerDiscoverySchema("values.model").extend({
8149
8164
  * the owner says which device it is.
8150
8165
  */
8151
8166
  const serialDiscoverySchema = brokerDiscoverySchema("product");
8167
+ /** How many rule sets a vendor's `bluetooth` block may list. */
8168
+ const MAXIMUM_RULE_SETS = 4;
8169
+ /**
8170
+ * Some bytes of the hex at a path, read as a model: `bytes` is `[start, length]`, a start below
8171
+ * zero counted from the end, and `mask` is ANDed with every byte. What it reads is the bytes in
8172
+ * lower-case hex - `48` for a model letter `H` - and nothing when the data is shorter.
8173
+ */
8174
+ const bytePlaceSchema = z.strictObject({
8175
+ path: pathSchema,
8176
+ bytes: z.tuple([z.int().min(-32).max(31), z.int().min(1).max(8)]),
8177
+ mask: z.int().min(0).max(255).optional()
8178
+ });
8179
+ /** Where an advertisement says its model: a path, or some of the bytes at one. */
8180
+ const modelPlaceSchema = z.union([pathSchema, bytePlaceSchema]);
8181
+ /** One way a vendor's devices advertise: the rules on it, and where it says its model. */
8182
+ const bluetoothRulesSchema = z.strictObject({
8183
+ /** Every condition must hold. All-of, and at least one: a vendor does not take every device. */
8184
+ match: z.array(claimConditionSchema).min(1).max(MAXIMUM_MATCH),
8185
+ /** Where the device says its model; several are tried in order. */
8186
+ model: z.union([modelPlaceSchema, z.array(modelPlaceSchema).min(1).max(4)]).default("name")
8187
+ });
8152
8188
  /**
8153
8189
  * Which of the devices the house's Bluetooth hears are the vendor's: rules on one advertisement (a
8154
8190
  * {@link BluetoothSighting}) - its `name`; `manufacturerData.'<company id>'`, the id in decimal,
8155
8191
  * that `exists` or `startsWith` the data's first bytes in hex; `serviceUuids`, which `contains` a
8156
8192
  * UUID in lower case; `serviceData.'<uuid>'`, that `exists`. The model is `name` unless said, in
8157
- * the drivers on the `bluetooth` transport.
8193
+ * the drivers on the `bluetooth` transport, or some bytes of the data: `{ "path", "bytes": [start,
8194
+ * length], "mask" }`.
8195
+ *
8196
+ * One rule set, or a list of up to four for a vendor whose devices advertise in more than one way:
8197
+ * the first whose rules hold is the one whose model is read. Of several places for the model, the
8198
+ * first that reads a code one of the vendor's drivers maps is the model.
8158
8199
  *
8159
8200
  * A device the rules take is listed as found for the vendor, and added only by the owner: what a
8160
8201
  * neighbour's sensor advertises is heard as well as the house's own.
8161
8202
  */
8162
- const bluetoothDiscoverySchema = brokerDiscoverySchema("name");
8203
+ const bluetoothDiscoverySchema = z.union([bluetoothRulesSchema, z.array(bluetoothRulesSchema).min(1).max(MAXIMUM_RULE_SETS)]).transform((rules) => Array.isArray(rules) ? rules : [rules]);
8163
8204
  /**
8164
8205
  * The platform's brokers a vendor may take devices of, and the transport each reaches them on.
8165
8206
  * Serial has none of its own: its devices are reached over their vendor's transport, through the
@@ -8361,7 +8402,49 @@ function associateModel(plan, modelCode, claimedBy) {
8361
8402
  * @returns True when the vendor has the broker's block and every one of its conditions holds.
8362
8403
  */
8363
8404
  function matchesBroker(plan, broker, identity) {
8364
- return plan.discovery[broker]?.match.every((condition) => conditionHolds(condition, identity)) ?? false;
8405
+ return rulesOf(plan, broker).some((rules) => holds(rules, identity));
8406
+ }
8407
+ /**
8408
+ * The rule sets of the vendor's block for a broker.
8409
+ *
8410
+ * @param plan - The vendor's discovery.
8411
+ * @param broker - Which broker.
8412
+ * @returns Bluetooth's list, the one block of another broker, or none without a block.
8413
+ */
8414
+ function rulesOf(plan, broker) {
8415
+ const block = plan.discovery[broker];
8416
+ return block === void 0 ? [] : Array.isArray(block) ? block : [block];
8417
+ }
8418
+ /**
8419
+ * Whether every condition of a rule set holds.
8420
+ *
8421
+ * @param rules - The rule set.
8422
+ * @param identity - Who the device says it is.
8423
+ * @returns True when they all hold.
8424
+ */
8425
+ function holds(rules, identity) {
8426
+ return rules.match.every((condition) => conditionHolds(condition, identity));
8427
+ }
8428
+ /**
8429
+ * Reads a model from one place.
8430
+ *
8431
+ * @param identity - Who the device says it is.
8432
+ * @param place - A path, or some bytes of the hex at one.
8433
+ * @returns The text, the bytes in lower-case hex, or null when there is none.
8434
+ */
8435
+ function modelAt(identity, place) {
8436
+ if (typeof place === "string") return textAt(identity, place);
8437
+ const hex = resolvePath(identity, place.path);
8438
+ if (typeof hex !== "string" || !/^(?:[0-9a-f]{2})+$/iu.test(hex)) return null;
8439
+ const [first, length] = place.bytes;
8440
+ const start = first < 0 ? hex.length / 2 + first : first;
8441
+ if (start < 0 || (start + length) * 2 > hex.length) return null;
8442
+ let text = "";
8443
+ for (let at = start * 2; at < (start + length) * 2; at += 2) {
8444
+ const byte = Number.parseInt(hex.slice(at, at + 2), 16) & (place.mask ?? 255);
8445
+ text += byte.toString(16).padStart(2, "0");
8446
+ }
8447
+ return text;
8365
8448
  }
8366
8449
  /**
8367
8450
  * Finds the driver of the vendor's that runs a device of one of the platform's brokers, and its
@@ -8369,7 +8452,8 @@ function matchesBroker(plan, broker, identity) {
8369
8452
  *
8370
8453
  * The model the device says is looked up in the `modelCodes` of the vendor's drivers on that
8371
8454
  * broker's transport - for serial, its drivers of kind `serial` - and one it does not map goes to
8372
- * the vendor's driver there when it has only one.
8455
+ * the vendor's driver there when it has only one. Of several places for the model, the first that
8456
+ * reads a mapped code wins; Bluetooth reads the places of its first rule set that holds.
8373
8457
  *
8374
8458
  * @param plan - The vendor's discovery.
8375
8459
  * @param broker - Which broker holds the device: `matter`, `mqtt`, `serial`.
@@ -8378,8 +8462,18 @@ function matchesBroker(plan, broker, identity) {
8378
8462
  */
8379
8463
  function associateBroker(plan, broker, identity) {
8380
8464
  const drivers = plan.drivers.filter((driver) => broker === "serial" ? driver.kind === "serial" : driver.transport === BROKER_TRANSPORTS[broker]);
8381
- const modelCode = textAt(identity, plan.discovery[broker]?.model ?? BROKER_MODELS[broker]);
8382
- const [first] = modelCode === null ? [] : (plan.codes.get(modelCode) ?? []).filter((entry) => drivers.some((driver) => driver.id === entry.driverId));
8465
+ const sets = rulesOf(plan, broker);
8466
+ const places = (sets.find((rules) => holds(rules, identity)) ?? sets[0])?.model;
8467
+ /**
8468
+ * The vendor's drivers on the broker that map a code.
8469
+ *
8470
+ * @param code - What the device says its model is.
8471
+ * @returns Their entries.
8472
+ */
8473
+ const codedOf = (code) => (plan.codes.get(code) ?? []).filter((entry) => drivers.some((driver) => driver.id === entry.driverId));
8474
+ const read = (Array.isArray(places) ? places : [places ?? BROKER_MODELS[broker]]).map((place) => modelAt(identity, place)).filter((code) => code !== null);
8475
+ const modelCode = read.find((code) => codedOf(code).length > 0) ?? read[0] ?? null;
8476
+ const [first] = modelCode === null ? [] : codedOf(modelCode);
8383
8477
  if (first !== void 0) return {
8384
8478
  driverId: first.driverId,
8385
8479
  model: first.models.length === 1 ? first.models[0] ?? null : null,
@@ -1286,6 +1286,13 @@ type MappingContext = {
1286
1286
  */
1287
1287
  lastState: (entityId: EntityId) => CapabilityState | undefined;
1288
1288
  };
1289
+ /** One request of a command already sent, and what the transport answered. */
1290
+ type CommandStep = {
1291
+ readonly request: TransportRequest;
1292
+ readonly answer: unknown;
1293
+ /** Its place in the command: 0 for the request `toCommand` built. */
1294
+ readonly index: number;
1295
+ };
1289
1296
  /** A command, resolved to the device and entity it is for. */
1290
1297
  type CommandTarget = {
1291
1298
  readonly entityId: EntityId;
@@ -1368,6 +1375,21 @@ type Integration<TOptions = JsonObject> = {
1368
1375
  * @returns The request. Performing it is the transport's job.
1369
1376
  */
1370
1377
  toCommand: (target: CommandTarget, context: MappingContext) => TransportRequest;
1378
+ /**
1379
+ * Carries a command on once the transport answered its last request - for a device spoken to in
1380
+ * a conversation: a Bluetooth lock asked for a session first, then sent the command sealed with
1381
+ * it. Each step is a pure function of what came back; the hub sends what it returns, at most
1382
+ * {@link MAX_COMMAND_STEPS} requests in all, and stops at null. A throw fails the command with
1383
+ * its message.
1384
+ *
1385
+ * Optional: without it a command is the one request `toCommand` builds.
1386
+ *
1387
+ * @param target - The entity, the capability and the command.
1388
+ * @param step - The request just sent, what the transport answered, and its place (0 first).
1389
+ * @param context - The claim, the settings and the last known state.
1390
+ * @returns The next request, or null when the command is done.
1391
+ */
1392
+ continueCommand?: (target: CommandTarget, step: CommandStep, context: MappingContext) => TransportRequest | null;
1371
1393
  /**
1372
1394
  * Reads what a message says about the device itself, beyond its entities: the firmware it runs
1373
1395
  * now, which changes when it is updated and is otherwise only known from when it was found.
@@ -2124,13 +2146,14 @@ declare const vendorManifestSchema: z.ZodObject<{
2124
2146
  serial: "serial";
2125
2147
  mac: "mac";
2126
2148
  }>>>;
2149
+ twinsPrefer: z.ZodOptional<z.ZodArray<z.ZodString>>;
2127
2150
  setup: z.ZodOptional<z.ZodString>;
2128
2151
  account: z.ZodOptional<z.ZodString>;
2129
2152
  transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
2130
2153
  module: z.ZodString;
2131
2154
  wires: z.ZodArray<z.ZodEnum<{
2132
- udp: "udp";
2133
2155
  matter: "matter";
2156
+ udp: "udp";
2134
2157
  mqtt: "mqtt";
2135
2158
  modbus: "modbus";
2136
2159
  serial: "serial";
@@ -2227,9 +2250,9 @@ declare const bundleManifestSchema: z.ZodObject<{
2227
2250
  modelCodes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
2228
2251
  modelSeries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
2229
2252
  kind: z.ZodEnum<{
2253
+ matter: "matter";
2230
2254
  declarative: "declarative";
2231
2255
  code: "code";
2232
- matter: "matter";
2233
2256
  mqtt: "mqtt";
2234
2257
  modbus: "modbus";
2235
2258
  infrared: "infrared";
@@ -2464,7 +2487,7 @@ declare const vendorDiscoverySchema: z.ZodObject<{
2464
2487
  }, z.core.$strict>]>>;
2465
2488
  model: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
2466
2489
  }, z.core.$strict>>;
2467
- bluetooth: z.ZodOptional<z.ZodObject<{
2490
+ bluetooth: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodObject<{
2468
2491
  match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
2469
2492
  path: z.ZodString;
2470
2493
  equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
@@ -2488,8 +2511,148 @@ declare const vendorDiscoverySchema: z.ZodObject<{
2488
2511
  min: z.ZodOptional<z.ZodNumber>;
2489
2512
  max: z.ZodOptional<z.ZodNumber>;
2490
2513
  }, z.core.$strict>]>>;
2491
- model: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
2492
- }, z.core.$strict>>;
2514
+ model: z.ZodDefault<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
2515
+ path: z.ZodString;
2516
+ bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
2517
+ mask: z.ZodOptional<z.ZodInt>;
2518
+ }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
2519
+ path: z.ZodString;
2520
+ bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
2521
+ mask: z.ZodOptional<z.ZodInt>;
2522
+ }, z.core.$strict>]>>]>>;
2523
+ }, z.core.$strict>, z.ZodArray<z.ZodObject<{
2524
+ match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
2525
+ path: z.ZodString;
2526
+ equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
2527
+ }, z.core.$strict>, z.ZodObject<{
2528
+ path: z.ZodString;
2529
+ exists: z.ZodLiteral<true>;
2530
+ }, z.core.$strict>, z.ZodObject<{
2531
+ path: z.ZodString;
2532
+ oneOf: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
2533
+ }, z.core.$strict>, z.ZodObject<{
2534
+ path: z.ZodString;
2535
+ startsWith: z.ZodString;
2536
+ }, z.core.$strict>, z.ZodObject<{
2537
+ path: z.ZodString;
2538
+ endsWith: z.ZodString;
2539
+ }, z.core.$strict>, z.ZodObject<{
2540
+ path: z.ZodString;
2541
+ contains: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
2542
+ }, z.core.$strict>, z.ZodObject<{
2543
+ path: z.ZodString;
2544
+ min: z.ZodOptional<z.ZodNumber>;
2545
+ max: z.ZodOptional<z.ZodNumber>;
2546
+ }, z.core.$strict>]>>;
2547
+ model: z.ZodDefault<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
2548
+ path: z.ZodString;
2549
+ bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
2550
+ mask: z.ZodOptional<z.ZodInt>;
2551
+ }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
2552
+ path: z.ZodString;
2553
+ bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
2554
+ mask: z.ZodOptional<z.ZodInt>;
2555
+ }, z.core.$strict>]>>]>>;
2556
+ }, z.core.$strict>>]>, z.ZodTransform<{
2557
+ match: ({
2558
+ path: string;
2559
+ min?: number | undefined;
2560
+ max?: number | undefined;
2561
+ } | {
2562
+ path: string;
2563
+ equals: string | number | boolean;
2564
+ } | {
2565
+ path: string;
2566
+ exists: true;
2567
+ } | {
2568
+ path: string;
2569
+ oneOf: (string | number | boolean)[];
2570
+ } | {
2571
+ path: string;
2572
+ startsWith: string;
2573
+ } | {
2574
+ path: string;
2575
+ endsWith: string;
2576
+ } | {
2577
+ path: string;
2578
+ contains: string | number | boolean;
2579
+ })[];
2580
+ model: string | {
2581
+ path: string;
2582
+ bytes: [number, number];
2583
+ mask?: number | undefined;
2584
+ } | (string | {
2585
+ path: string;
2586
+ bytes: [number, number];
2587
+ mask?: number | undefined;
2588
+ })[];
2589
+ }[], {
2590
+ match: ({
2591
+ path: string;
2592
+ min?: number | undefined;
2593
+ max?: number | undefined;
2594
+ } | {
2595
+ path: string;
2596
+ equals: string | number | boolean;
2597
+ } | {
2598
+ path: string;
2599
+ exists: true;
2600
+ } | {
2601
+ path: string;
2602
+ oneOf: (string | number | boolean)[];
2603
+ } | {
2604
+ path: string;
2605
+ startsWith: string;
2606
+ } | {
2607
+ path: string;
2608
+ endsWith: string;
2609
+ } | {
2610
+ path: string;
2611
+ contains: string | number | boolean;
2612
+ })[];
2613
+ model: string | {
2614
+ path: string;
2615
+ bytes: [number, number];
2616
+ mask?: number | undefined;
2617
+ } | (string | {
2618
+ path: string;
2619
+ bytes: [number, number];
2620
+ mask?: number | undefined;
2621
+ })[];
2622
+ } | {
2623
+ match: ({
2624
+ path: string;
2625
+ min?: number | undefined;
2626
+ max?: number | undefined;
2627
+ } | {
2628
+ path: string;
2629
+ equals: string | number | boolean;
2630
+ } | {
2631
+ path: string;
2632
+ exists: true;
2633
+ } | {
2634
+ path: string;
2635
+ oneOf: (string | number | boolean)[];
2636
+ } | {
2637
+ path: string;
2638
+ startsWith: string;
2639
+ } | {
2640
+ path: string;
2641
+ endsWith: string;
2642
+ } | {
2643
+ path: string;
2644
+ contains: string | number | boolean;
2645
+ })[];
2646
+ model: string | {
2647
+ path: string;
2648
+ bytes: [number, number];
2649
+ mask?: number | undefined;
2650
+ } | (string | {
2651
+ path: string;
2652
+ bytes: [number, number];
2653
+ mask?: number | undefined;
2654
+ })[];
2655
+ }[]>>>;
2493
2656
  adopt: z.ZodDefault<z.ZodEnum<{
2494
2657
  owner: "owner";
2495
2658
  automatic: "automatic";
@@ -830,7 +830,7 @@ function defineTransport(spec) {
830
830
  * bundle built with this SDK says `^<major>.<minor>.0`.
831
831
  */
832
832
  /** The SDK's own version: `1.0.0`, or a prerelease of it. */
833
- const SDK_VERSION = "1.7.0";
833
+ const SDK_VERSION = "1.8.0";
834
834
  /**
835
835
  * The runtime range a bundle built with this SDK declares: this version's major and minor, so a
836
836
  * platform with the same contract or a later one of the same major loads it.
package/dist/index.d.ts CHANGED
@@ -787,6 +787,8 @@ export declare const BLUETOOTH_GATT_OPS: {
787
787
  readonly read: "gatt.read";
788
788
  readonly write: "gatt.write";
789
789
  readonly notify: "gatt.notify";
790
+ /** Writes a request and answers what the device notifies back. */
791
+ readonly exchange: "gatt.exchange";
790
792
  };
791
793
  declare namespace infrared_codes_d_exports {
792
794
  export { BROADLINK_TICK_US, DEFAULT_IR_CARRIER_HZ, FlipperIrCode, FlipperIrFile, InfraredImportProblem, decodeBroadlink, decodeInfraredProtocol, decodePronto, decodeRawTimings, encodeBroadlink, encodeInfraredProtocol, encodePronto, encodeRawTimings, parseFlipperIr, withInfraredProtocol };
@@ -1154,6 +1156,13 @@ type MappingContext = {
1154
1156
  */
1155
1157
  lastState: (entityId: EntityId) => CapabilityState | undefined;
1156
1158
  };
1159
+ /** One request of a command already sent, and what the transport answered. */
1160
+ type CommandStep = {
1161
+ readonly request: TransportRequest;
1162
+ readonly answer: unknown;
1163
+ /** Its place in the command: 0 for the request `toCommand` built. */
1164
+ readonly index: number;
1165
+ };
1157
1166
  /** A command, resolved to the device and entity it is for. */
1158
1167
  type CommandTarget = {
1159
1168
  readonly entityId: EntityId;
@@ -1236,6 +1245,21 @@ type Integration<TOptions = JsonObject> = {
1236
1245
  * @returns The request. Performing it is the transport's job.
1237
1246
  */
1238
1247
  toCommand: (target: CommandTarget, context: MappingContext) => TransportRequest;
1248
+ /**
1249
+ * Carries a command on once the transport answered its last request - for a device spoken to in
1250
+ * a conversation: a Bluetooth lock asked for a session first, then sent the command sealed with
1251
+ * it. Each step is a pure function of what came back; the hub sends what it returns, at most
1252
+ * {@link MAX_COMMAND_STEPS} requests in all, and stops at null. A throw fails the command with
1253
+ * its message.
1254
+ *
1255
+ * Optional: without it a command is the one request `toCommand` builds.
1256
+ *
1257
+ * @param target - The entity, the capability and the command.
1258
+ * @param step - The request just sent, what the transport answered, and its place (0 first).
1259
+ * @param context - The claim, the settings and the last known state.
1260
+ * @returns The next request, or null when the command is done.
1261
+ */
1262
+ continueCommand?: (target: CommandTarget, step: CommandStep, context: MappingContext) => TransportRequest | null;
1239
1263
  /**
1240
1264
  * Reads what a message says about the device itself, beyond its entities: the firmware it runs
1241
1265
  * now, which changes when it is updated and is otherwise only known from when it was found.
@@ -2003,4 +2027,4 @@ export declare function defineAccountModule(factory: AccountFactory): AccountFac
2003
2027
  */
2004
2028
  export declare function defineStreamModule(factory: StreamFactory): StreamFactory;
2005
2029
  //#endregion
2006
- export type { AccountFactory, AccountHandle, AccountIdentity, AccountModule, AccountModuleStep, AccountStepContext, BluetoothAdvert, BluetoothAdvertInput, BluetoothProxyFilterArgs, BluetoothProxyInstallArgs, BluetoothProxyProfile, BluetoothProxyState, BluetoothScanMode, BluetoothScanner, BluetoothScannerOptions, BluetoothSighting, BundleBluetooth, BundleCodecs, BundleImages, BundleLogFn, BundleLogger, BundleSdk, Claim, CommandTarget, DeviceDescriptor, DeviceInfo, Discovered, DiscoveryListenContext, DiscoverySource, DiscoverySourceFactory, EntityDescriptor, FlipperIrCode, FlipperIrFile, ImageBlob, InfraredCode, InfraredCodec, InfraredImportProblem, InfraredLearnArgs, InfraredProfile, InfraredProtocol, InfraredProtocolName, InfraredSendArgs, InfraredSignal, InfraredSweepArgs, InfraredSweepResult, Integration, IntegrationFactory, ListenerStatus, ManagedMqtt, ManagedMqttOptions, ManagedSocket, ManagedSocketClose, ManagedSocketHeaders, ManagedSocketOptions, ManagedUdpSocket, ManagedUdpSocketOptions, MappingContext, MdnsAnnouncement, OpenMqtt, OpenRtsp, OpenSerial, OpenUdpSocket, OpenWebSocket, PaletteColour, PalettedPicture, PassedOverSighting, PlatformMqtt, PlatformServices, ReportedState, RtspFrame, RtspOptions, SerialDeviceConfig, SerialLine, SerialLineInput, SerialSession, SerialSighting, Sighting, StreamFactory, StreamFrame, StreamRequest, StreamSink, StreamSource, StreamSourceSpec, StreamTrack, Transport, TransportConnection, TransportContext, TransportFactory, TransportInbound, TransportLookContext, TransportRequest, TransportSpec, TransportStatus, TransportSubscription, UdpPeer };
2030
+ export type { AccountFactory, AccountHandle, AccountIdentity, AccountModule, AccountModuleStep, AccountStepContext, BluetoothAdvert, BluetoothAdvertInput, BluetoothProxyFilterArgs, BluetoothProxyInstallArgs, BluetoothProxyProfile, BluetoothProxyState, BluetoothScanMode, BluetoothScanner, BluetoothScannerOptions, BluetoothSighting, BundleBluetooth, BundleCodecs, BundleImages, BundleLogFn, BundleLogger, BundleSdk, Claim, CommandStep, CommandTarget, DeviceDescriptor, DeviceInfo, Discovered, DiscoveryListenContext, DiscoverySource, DiscoverySourceFactory, EntityDescriptor, FlipperIrCode, FlipperIrFile, ImageBlob, InfraredCode, InfraredCodec, InfraredImportProblem, InfraredLearnArgs, InfraredProfile, InfraredProtocol, InfraredProtocolName, InfraredSendArgs, InfraredSignal, InfraredSweepArgs, InfraredSweepResult, Integration, IntegrationFactory, ListenerStatus, ManagedMqtt, ManagedMqttOptions, ManagedSocket, ManagedSocketClose, ManagedSocketHeaders, ManagedSocketOptions, ManagedUdpSocket, ManagedUdpSocketOptions, MappingContext, MdnsAnnouncement, OpenMqtt, OpenRtsp, OpenSerial, OpenUdpSocket, OpenWebSocket, PaletteColour, PalettedPicture, PassedOverSighting, PlatformMqtt, PlatformServices, ReportedState, RtspFrame, RtspOptions, SerialDeviceConfig, SerialLine, SerialLineInput, SerialSession, SerialSighting, Sighting, StreamFactory, StreamFrame, StreamRequest, StreamSink, StreamSource, StreamSourceSpec, StreamTrack, Transport, TransportConnection, TransportContext, TransportFactory, TransportInbound, TransportLookContext, TransportRequest, TransportSpec, TransportStatus, TransportSubscription, UdpPeer };
package/dist/index.js CHANGED
@@ -97,7 +97,9 @@ const BLUETOOTH_PROXY_OPS = {
97
97
  const BLUETOOTH_GATT_OPS = {
98
98
  read: "gatt.read",
99
99
  write: "gatt.write",
100
- notify: "gatt.notify"
100
+ notify: "gatt.notify",
101
+ /** Writes a request and answers what the device notifies back. */
102
+ exchange: "gatt.exchange"
101
103
  };
102
104
  //#endregion
103
105
  export { BLUETOOTH_GATT_OPS, BLUETOOTH_PROXY_OPS, INFRARED_OPS, defineAccountModule, defineDiscoveryModule, defineDriverModule, defineStreamModule, defineTransportModule };