@nebulahome/integration-sdk 1.6.1 → 1.7.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.7.0
7
+
8
+ Bluetooth proxies scan as the hub decides.
9
+
10
+ - The owner no longer picks a proxy's scan mode. `bluetooth-proxy.install`'s `mode` is the one the
11
+ proxy rests in, which the hub picks: `passive` when the profile lists it, else `active`.
12
+ - `bluetooth-proxy.filter` carries `active`: the hub asks a proxy to scan actively while somebody
13
+ has Nearby open, while a device it hears is being added, and when a followed device's refresh
14
+ falls due; absent or false, the proxy goes back to rest.
15
+ - A Bluetooth driver's `follow` subscription may say `activeEveryMinutes` (1 to 1440): every so
16
+ often the proxy hearing the device best scans actively until it hears it again, 30 s at most, for
17
+ what the device says only in a scan response.
18
+ - `bluetooth-proxy.state` may answer the reason `unsupported`: a model that cannot run the script,
19
+ or whose radio is busy with something else.
20
+
6
21
  ## 1.6.1
7
22
 
8
23
  - `sdk.codecs.infrared`: a Broadlink tick is 8192/269 µs, about 30.45 µs, as measured against real
package/FILES.md CHANGED
@@ -246,7 +246,10 @@ address: the owner adds one from the Bluetooth broker's Found or Nearby, and its
246
246
  address, upper case. Its claim reads `{ deviceKey, kind, name, advert }`, the advertisement it was
247
247
  recognised from; it follows its address with the subscription `{ "op": "follow", "args": {
248
248
  "address": "…" } }` and is delivered each advertisement heard from it, by the server's adapter or
249
- any proxy - one carrying the same name, maker's and service data at most once a minute. Its
249
+ any proxy - one carrying the same name, maker's and service data at most once a minute. A device
250
+ that says some of what it knows only when asked - in a scan response - adds `"activeEveryMinutes":
251
+ N` (1 to 1440): proxies rest passive, and every N minutes the hub asks the proxy hearing it best to
252
+ scan actively until it hears the device again, 30 s at most. Its
250
253
  requests are GATT on the server's own adapter: `gatt.read { service, characteristic }` answers `{
251
254
  data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.notify { service,
252
255
  characteristic, isOn }`, whose values are delivered as `{ service, characteristic, data }` - hex
@@ -933,29 +936,36 @@ what the sweep found. A learn that rejects with an error named `TimeoutError` or
933
936
  at or after `timeoutMs`, reads "Nothing reached the blaster in 30 s." on the page; any other shows
934
937
  its message.
935
938
 
936
- **A Bluetooth proxy** declares `bluetoothProxy: { modes }`, the scan modes it can run, `passive`
937
- and `active`, each once.
939
+ **A Bluetooth proxy** declares `bluetoothProxy: { modes }`, the scan modes its radio can run,
940
+ `passive` and `active`, each once. The owner does not choose one: the hub does. A proxy rests
941
+ passive when it can, and the hub asks it to scan actively only while the house needs more than
942
+ adverts - while somebody has Nearby open (every proxy), while a device is being added (the proxies
943
+ hearing it), and when a followed device's `activeEveryMinutes` falls due (the proxy hearing it
944
+ best).
938
945
 
939
- | Op | Arguments | The hub waits | Answer |
940
- | ------------------------- | --------------- | ------------- | --------------------------------------------------------- |
941
- | `bluetooth-proxy.state` | `{}` | 10 s | `BluetoothProxyState`; anything else counts as no answer |
942
- | `bluetooth-proxy.install` | `{ mode }` | 60 s | install the script, or update it, and run it in that mode |
943
- | `bluetooth-proxy.remove` | `{}` | 10 s | stop the script and remove it; throw to refuse |
944
- | `bluetooth-proxy.filter` | `{ addresses }` | 10 s | forward those addresses from now on |
946
+ | Op | Arguments | The hub waits | Answer |
947
+ | ------------------------- | ------------------------ | ------------- | --------------------------------------------------------- |
948
+ | `bluetooth-proxy.state` | `{}` | 10 s | `BluetoothProxyState`; anything else counts as no answer |
949
+ | `bluetooth-proxy.install` | `{ mode }` | 60 s | install the script, or update it, resting in that mode |
950
+ | `bluetooth-proxy.remove` | `{}` | 10 s | stop the script and remove it; throw to refuse |
951
+ | `bluetooth-proxy.filter` | `{ addresses, active? }` | 10 s | forward those addresses, scanning actively while `active` |
945
952
 
946
953
  - `state` answers `{ eligible: true, installed, version?, shipped, running }` - the script on the
947
954
  device, the one the vendor ships now, whether it runs - or `{ eligible: false, reason, update? }`,
948
- the reason `gen1`, `battery`, `firmware` or `no-bluetooth`, and `update` whether a firmware update
949
- the device offers would make it eligible. The hub asks it for the list of devices that could be
955
+ the reason `gen1`, `battery`, `firmware`, `no-bluetooth` or `unsupported` - a model that cannot
956
+ run the script, or whose radio is busy with something else - and `update` whether a firmware
957
+ update the device offers would make it eligible. The hub asks it for the list of devices that could be
950
958
  proxies, when the device's scanner opens, and after an install, a second apart until it says
951
959
  `running`. The script is outdated when `version` and `shipped` are both strict semver and
952
960
  `version` is the lower, otherwise whenever they differ.
953
- - `install` is also how the owner changes the mode and updates the script; a throw fails the job
954
- with its message.
961
+ - `install` is also how the script is updated. `mode` is the one it rests in, which the hub picks:
962
+ `passive` when the profile lists it, else `active`. A throw fails the job with its message.
955
963
  - `filter` is `"all"` while somebody has Nearby open, otherwise the house's devices, those being
956
- added and those a rule recognises - upper case, sorted, 4096 at most. It comes at the hub's
957
- start, when the scanner opens, on every change and again every five minutes. Keep only the last
958
- one; a script that restarted forwards nothing until it is told again.
964
+ added and those a rule recognises - upper case, sorted, 4096 at most. `active: true` asks it to
965
+ scan actively until a filter says otherwise; absent or false, it goes back to the mode it rests
966
+ in. A proxy whose profile does not list `active` is never asked. It comes at the hub's start,
967
+ when the scanner opens, on every change and again every five minutes. Keep only the last one; a
968
+ script that restarted forwards nothing, and rests, until it is told again.
959
969
 
960
970
  What the proxy hears reaches the house through `sdk.bluetooth.scanner({ key, deviceKey })`: `key`
961
971
  is the instance connection's key and `deviceKey` the device's on it, or the hub cannot tell which
@@ -5072,12 +5072,16 @@ const BLUETOOTH_ADAPTER_PROBLEMS = [
5072
5072
  "powered-off",
5073
5073
  "disabled"
5074
5074
  ];
5075
- /** Why a device cannot be a proxy: Gen1, battery powered, firmware too old, no Bluetooth. */
5075
+ /**
5076
+ * Why a device cannot be a proxy: Gen1, battery powered, firmware too old, no Bluetooth, or a
5077
+ * model that cannot run the script (no scripts, or its radio busy with something else).
5078
+ */
5076
5079
  const BLUETOOTH_PROXY_INELIGIBLE_REASONS = [
5077
5080
  "gen1",
5078
5081
  "battery",
5079
5082
  "firmware",
5080
- "no-bluetooth"
5083
+ "no-bluetooth",
5084
+ "unsupported"
5081
5085
  ];
5082
5086
  /** What a proxy forwards: the house's devices and what a rule recognises, or everything. */
5083
5087
  const BLUETOOTH_FORWARDING = ["house", "everything"];
@@ -5107,12 +5111,16 @@ const bluetoothAdvertSchema = z.object({
5107
5111
  });
5108
5112
  z.array(bluetoothAdvertSchema).max(1024);
5109
5113
  /**
5110
- * What a device that can be a proxy declares in its profile: the scan modes it can run.
5114
+ * What a device that can be a proxy declares in its profile: the scan modes its radio can run.
5111
5115
  */
5112
5116
  const bluetoothProxyProfileSchema = z.strictObject({ modes: z.array(z.enum(BLUETOOTH_SCAN_MODES)).min(1).max(BLUETOOTH_SCAN_MODES.length).refine((modes) => new Set(modes).size === modes.length, "Each mode once") });
5113
5117
  z.object({});
5114
5118
  z.object({ mode: z.enum(BLUETOOTH_SCAN_MODES) });
5115
- z.object({ addresses: z.union([z.literal("all"), z.array(bluetoothAddressSchema).max(4096)]) });
5119
+ z.object({
5120
+ addresses: z.union([z.literal("all"), z.array(bluetoothAddressSchema).max(4096)]),
5121
+ /** Whether to scan actively until the next filter; absent or false rests in the install's mode. */
5122
+ active: z.boolean().optional()
5123
+ });
5116
5124
  /** What `bluetooth-proxy.state` answers: a device that can be a proxy, and whether it is one. */
5117
5125
  const bluetoothProxyStateSchema = z.discriminatedUnion("eligible", [z.object({
5118
5126
  eligible: z.literal(true),
@@ -5151,8 +5159,6 @@ const bluetoothSettingsSchema = z.object({
5151
5159
  /** Which adapter, `hci0`; null for the first BlueZ has. */
5152
5160
  adapterId: z.string().regex(/^hci\d{1,3}$/u).nullable().default(null),
5153
5161
  localScanMode: z.enum(BLUETOOTH_SCAN_MODES).default("active"),
5154
- /** How a new proxy scans. */
5155
- proxyScanMode: z.enum(BLUETOOTH_SCAN_MODES).default("passive"),
5156
5162
  /** Addresses not heard for this long are dropped. */
5157
5163
  forgetAfterDays: z.int().min(1).max(365).default(7),
5158
5164
  /** Whether Nearby lists private addresses: phones and watches that change theirs. */
@@ -5341,6 +5347,7 @@ const bluetoothScannerSchema = z.object({
5341
5347
  chip: z.string().max(128).nullable(),
5342
5348
  isOnline: z.boolean(),
5343
5349
  isEnabled: z.boolean(),
5350
+ /** The adapter's setting; for a proxy, how it scans right now, as the hub asks. */
5344
5351
  scanMode: z.enum(BLUETOOTH_SCAN_MODES),
5345
5352
  canPassive: z.boolean(),
5346
5353
  advertsPerMinute: z.int().min(0),
@@ -5380,19 +5387,12 @@ const bluetoothProxyCandidateSchema = z.object({
5380
5387
  modes: z.array(z.enum(BLUETOOTH_SCAN_MODES)).max(BLUETOOTH_SCAN_MODES.length)
5381
5388
  });
5382
5389
  z.object({ items: z.array(bluetoothProxyCandidateSchema) });
5383
- z.object({
5384
- deviceId: integrationIdSchema,
5385
- mode: z.enum(BLUETOOTH_SCAN_MODES)
5386
- });
5387
5390
  z.object({ deviceId: integrationIdSchema });
5388
5391
  brokerJobSchemaOf([
5389
5392
  "installing",
5390
5393
  "started",
5391
5394
  "first-report"
5392
- ]).extend({
5393
- deviceId: integrationIdSchema,
5394
- mode: z.enum(BLUETOOTH_SCAN_MODES)
5395
- });
5395
+ ]).extend({ deviceId: integrationIdSchema });
5396
5396
  z.object({ jobId: z.string().min(1).max(64) });
5397
5397
  z.object({ isRemoved: z.boolean() });
5398
5398
  //#endregion
@@ -185,7 +185,7 @@ type BluetoothAdvertInput = z.input<typeof bluetoothAdvertSchema>;
185
185
  /** One advertisement heard. */
186
186
  type BluetoothAdvert = z.output<typeof bluetoothAdvertSchema>;
187
187
  /**
188
- * What a device that can be a proxy declares in its profile: the scan modes it can run.
188
+ * What a device that can be a proxy declares in its profile: the scan modes its radio can run.
189
189
  */
190
190
  declare const bluetoothProxyProfileSchema: z.ZodObject<{
191
191
  modes: z.ZodArray<z.ZodEnum<{
@@ -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.6.1";
833
+ const SDK_VERSION = "1.7.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
@@ -190,7 +190,7 @@ type BluetoothAdvertInput = z.input<typeof bluetoothAdvertSchema>;
190
190
  /** One advertisement heard. */
191
191
  type BluetoothAdvert = z.output<typeof bluetoothAdvertSchema>;
192
192
  /**
193
- * What a device that can be a proxy declares in its profile: the scan modes it can run.
193
+ * What a device that can be a proxy declares in its profile: the scan modes its radio can run.
194
194
  */
195
195
  declare const bluetoothProxyProfileSchema: z.ZodObject<{
196
196
  modes: z.ZodArray<z.ZodEnum<{
@@ -207,13 +207,17 @@ declare const bluetoothProxyInstallArgsSchema: z.ZodObject<{
207
207
  active: "active";
208
208
  }>;
209
209
  }, z.core.$strip>;
210
- /** Arguments of `bluetooth-proxy.install`: the mode to scan in. */
210
+ /** Arguments of `bluetooth-proxy.install`: the mode to rest in, which the hub picks. */
211
211
  type BluetoothProxyInstallArgs = z.output<typeof bluetoothProxyInstallArgsSchema>;
212
212
  /** Arguments of `bluetooth-proxy.filter`. */
213
213
  declare const bluetoothProxyFilterArgsSchema: z.ZodObject<{
214
214
  addresses: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>]>;
215
+ active: z.ZodOptional<z.ZodBoolean>;
215
216
  }, z.core.$strip>;
216
- /** Arguments of `bluetooth-proxy.filter`: the addresses to forward, upper case, or `all`. */
217
+ /**
218
+ * Arguments of `bluetooth-proxy.filter`: the addresses to forward, upper case, or `all`, and
219
+ * whether the hub wants it scanning actively now.
220
+ */
217
221
  type BluetoothProxyFilterArgs = z.output<typeof bluetoothProxyFilterArgsSchema>;
218
222
  /** What `bluetooth-proxy.state` answers: a device that can be a proxy, and whether it is one. */
219
223
  declare const bluetoothProxyStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -229,6 +233,7 @@ declare const bluetoothProxyStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
229
233
  battery: "battery";
230
234
  firmware: "firmware";
231
235
  "no-bluetooth": "no-bluetooth";
236
+ unsupported: "unsupported";
232
237
  }>;
233
238
  update: z.ZodOptional<z.ZodBoolean>;
234
239
  }, z.core.$strip>], "eligible">;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nebulahome/integration-sdk",
3
- "version": "1.6.1",
3
+ "version": "1.7.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",
@@ -62,10 +62,10 @@
62
62
  "tsdown": "^0.23.0",
63
63
  "typescript": "^6.0.3",
64
64
  "vitest": "^4.1.11",
65
- "@nebulahome/contracts": "2026.10.0-alpha.8",
66
- "@nebulahome/tsconfig": "2026.10.0-alpha.8",
67
- "@nebulahome/package-runtime": "2026.10.0-alpha.8",
68
- "@nebulahome/eslint-config": "2026.10.0-alpha.8"
65
+ "@nebulahome/contracts": "2026.10.0-alpha.36",
66
+ "@nebulahome/tsconfig": "2026.10.0-alpha.36",
67
+ "@nebulahome/eslint-config": "2026.10.0-alpha.36",
68
+ "@nebulahome/package-runtime": "2026.10.0-alpha.36"
69
69
  },
70
70
  "scripts": {
71
71
  "build": "tsdown && node scripts/build-schemas.js",