@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 +15 -0
- package/FILES.md +26 -16
- package/dist/chunks/node-dist.js +14 -14
- package/dist/chunks/node-index.d.ts +1 -1
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +8 -3
- package/package.json +5 -5
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.
|
|
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
|
|
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
|
|
940
|
-
| ------------------------- |
|
|
941
|
-
| `bluetooth-proxy.state` | `{}`
|
|
942
|
-
| `bluetooth-proxy.install` | `{ mode }`
|
|
943
|
-
| `bluetooth-proxy.remove` | `{}`
|
|
944
|
-
| `bluetooth-proxy.filter` | `{ addresses }` | 10 s | forward those addresses
|
|
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
|
|
949
|
-
the
|
|
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
|
|
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.
|
|
957
|
-
|
|
958
|
-
|
|
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
|
package/dist/chunks/node-dist.js
CHANGED
|
@@ -5072,12 +5072,16 @@ const BLUETOOTH_ADAPTER_PROBLEMS = [
|
|
|
5072
5072
|
"powered-off",
|
|
5073
5073
|
"disabled"
|
|
5074
5074
|
];
|
|
5075
|
-
/**
|
|
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
|
|
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({
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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.
|
|
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.
|
|
66
|
-
"@nebulahome/tsconfig": "2026.10.0-alpha.
|
|
67
|
-
"@nebulahome/
|
|
68
|
-
"@nebulahome/
|
|
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",
|