@domicile-desktop/system-bluetooth 0.0.0-alpha-e3866c607353 → 0.0.0-alpha-1fcbde657613

package/README.md

@@ -1,7 +1,7 @@
 # @domicile-desktop/system-bluetooth
 
-BlueZ for a Domicile shell: each adapter and whether it is powered, the
-connected devices, and turning an adapter on or off. Built on
+BlueZ for a Domicile shell: each adapter and whether it is powered or
+scanning, the devices it knows, and the requests that change them. Built on
 [`@domicile-desktop/sdk/system`](../chrome-sdk/README.md).
 
 ## Usage
@@ -14,14 +14,19 @@ const host = system(domicile);
 const stop = watchBluetooth(host, (bluetooth) => {
   bluetooth.match({
     Err: () => hide(),
-    Ok: ({ adapters, connected }) => show(adapters, connected),
+    Ok: ({ adapters, devices }) => show(adapters, devices),
   });
 });
 await setPowered(host, "/org/bluez/hci0", false);
 ```
 
 - Reads `GetManagedObjects` once, then again when an object comes or goes or
-  an adapter's `Powered` or a device's `Connected` or `Alias` changes.
+  one of these changes: an adapter's `Powered` or `Discovering`, a device's
+  `Alias`, `Name`, `Connected` or `Paired`, or its battery's `Percentage`.
+- `devices` holds paired devices and, from a scan, those with a name.
+- Requests: `setPowered`, `startDiscovery`, `stopDiscovery`, `connect`,
+  `disconnect`, `pair` (then trusts the device) and `forget`.
+- `pair` registers no agent, so only devices that need no code pair.
 - An `Err` is a D-Bus failure, such as BlueZ not running or an adapter
   blocked by rfkill.
 - A bug or an unexpected reply shape throws, logged to the console.

package/dist/bluetooth.d.ts

@@ -4,15 +4,28 @@ import type { System, SystemError } from "@domicile-desktop/sdk/system";
 export type Adapter = {
     path: string;
     powered: boolean;
+    discovering: boolean;
 };
-/** A connected device. `name` is its alias, which BlueZ fills from its name. */
+/**
+ * A device BlueZ knows. `name` is its alias, which BlueZ fills from its name.
+ * `battery` is 0 through 100, for a device that reports it.
+ */
 export type Device = {
     path: string;
+    adapter: string;
+    address: string;
     name: string;
+    paired: boolean;
+    connected: boolean;
+    battery: number | undefined;
 };
+/**
+ * Every adapter, and each device that is paired or, found by a scan, has a
+ * name. A scan finds many nameless devices, such as beacons.
+ */
 export type Bluetooth = {
     adapters: Adapter[];
-    connected: Device[];
+    devices: Device[];
 };
 /** The calls this library makes. */
 export type BluetoothSystem = Pick<System, "dbusCall" | "dbusMatch">;
@@ -26,3 +39,16 @@ export type BluetoothSystem = Pick<System, "dbusCall" | "dbusMatch">;
 export declare const watchBluetooth: (system: BluetoothSystem, onBluetooth: (bluetooth: Result<Bluetooth, SystemError>) => void) => (() => void);
 /** Turn the adapter at `adapter` on or off. */
 export declare const setPowered: (system: Pick<System, "dbusCall">, adapter: string, powered: boolean) => Promise<Result<"set", SystemError>>;
+/** Start scanning for devices. BlueZ stops when every scanner has asked. */
+export declare const startDiscovery: (system: Pick<System, "dbusCall">, adapter: string) => Promise<Result<"done", SystemError>>;
+export declare const stopDiscovery: (system: Pick<System, "dbusCall">, adapter: string) => Promise<Result<"done", SystemError>>;
+/** Connect a paired device's profiles. */
+export declare const connect: (system: Pick<System, "dbusCall">, device: string) => Promise<Result<"done", SystemError>>;
+export declare const disconnect: (system: Pick<System, "dbusCall">, device: string) => Promise<Result<"done", SystemError>>;
+/**
+ * Pair with a device, then trust it so it can reconnect on its own. With no
+ * agent registered, BlueZ pairs only devices that need no code.
+ */
+export declare const pair: (system: Pick<System, "dbusCall">, device: string) => Promise<Result<"done", SystemError>>;
+/** Remove a device and its pairing. */
+export declare const forget: (system: Pick<System, "dbusCall">, device: Pick<Device, "adapter" | "path">) => Promise<Result<"done", SystemError>>;

package/dist/bluetooth.js

@@ -1,15 +1,17 @@
-// BlueZ over the system bus: adapters and connected devices, kept current.
-// See docs/SHELL-SYSTEM-ACCESS.md.
+// BlueZ over the system bus: adapters and devices, kept current, and the
+// requests that change them. See docs/SHELL-SYSTEM-ACCESS.md.
 import { Err } from "@cprussin/option-result";
 import { Bus } from "@domicile-desktop/sdk/system";
 import { z } from "zod";
 const SERVICE = "org.bluez";
 const ADAPTER = "org.bluez.Adapter1";
 const DEVICE = "org.bluez.Device1";
+const BATTERY = "org.bluez.Battery1";
 /** The properties whose changes alter a {@link Bluetooth}, by interface. */
 const WATCHED = {
-    [ADAPTER]: ["Powered"],
-    [DEVICE]: ["Alias", "Connected"],
+    [ADAPTER]: ["Discovering", "Powered"],
+    [BATTERY]: ["Percentage"],
+    [DEVICE]: ["Alias", "Connected", "Name", "Paired"],
 };
 /**
  * Calls `onBluetooth` with the adapters and connected devices now and after
@@ -44,6 +46,43 @@ export const setPowered = async (system, adapter, powered) => (await system.dbus
     path: adapter,
     signature: "ssv",
 })).map(() => "set");
+/** Start scanning for devices. BlueZ stops when every scanner has asked. */
+export const startDiscovery = (system, adapter) => call(system, adapter, ADAPTER, "StartDiscovery");
+export const stopDiscovery = (system, adapter) => call(system, adapter, ADAPTER, "StopDiscovery");
+/** Connect a paired device's profiles. */
+export const connect = (system, device) => call(system, device, DEVICE, "Connect");
+export const disconnect = (system, device) => call(system, device, DEVICE, "Disconnect");
+/**
+ * Pair with a device, then trust it so it can reconnect on its own. With no
+ * agent registered, BlueZ pairs only devices that need no code.
+ */
+export const pair = async (system, device) => (await call(system, device, DEVICE, "Pair")).andThenAsync(async () => (await system.dbusCall({
+    body: [DEVICE, "Trusted", { signature: "b", value: true }],
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.Properties",
+    member: "Set",
+    path: device,
+    signature: "ssv",
+})).map(() => "done"));
+/** Remove a device and its pairing. */
+export const forget = async (system, device) => (await system.dbusCall({
+    body: [device.path],
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: ADAPTER,
+    member: "RemoveDevice",
+    path: device.adapter,
+    signature: "o",
+})).map(() => "done");
+/** A BlueZ method that takes no arguments. */
+const call = async (system, path, iface, member) => (await system.dbusCall({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: iface,
+    member,
+    path,
+})).map(() => "done");
 /** Listen, read, then read again on each change until the match ends. */
 const follow = async (system, watch, report) => {
     const matched = await system.dbusMatch({ bus: Bus.System, sender: SERVICE });
@@ -112,21 +151,51 @@ const bluetoothOf = (objects) => {
     return {
         adapters: entries.flatMap(([path, held]) => held[ADAPTER] === undefined
             ? []
-            : [{ path, powered: held[ADAPTER].Powered }]),
-        connected: entries.flatMap(([path, held]) => held[DEVICE]?.Connected === true
-            ? [{ name: held[DEVICE].Alias, path }]
-            : []),
+            : [
+                {
+                    discovering: held[ADAPTER].Discovering,
+                    path,
+                    powered: held[ADAPTER].Powered,
+                },
+            ]),
+        devices: entries.flatMap(([path, held]) => {
+            const device = held[DEVICE];
+            return device === undefined ||
+                (!device.Paired && device.Name === undefined)
+                ? []
+                : [
+                    {
+                        adapter: device.Adapter,
+                        address: device.Address,
+                        battery: held[BATTERY]?.Percentage,
+                        connected: device.Connected,
+                        name: device.Alias,
+                        paired: device.Paired,
+                        path,
+                    },
+                ];
+        }),
     };
 };
 /** A `v`, as `domicile_host::dbus_json` writes it, read as its value. */
 const variant = (value) => z.object({ value }).transform(({ value: held }) => held);
 const managedObjectsSchema = z.tuple([
     z.record(z.string(), z.object({
-        [ADAPTER]: z.object({ Powered: variant(z.boolean()) }).optional(),
+        [ADAPTER]: z
+            .object({
+            Discovering: variant(z.boolean()),
+            Powered: variant(z.boolean()),
+        })
+            .optional(),
+        [BATTERY]: z.object({ Percentage: variant(z.number()) }).optional(),
         [DEVICE]: z
             .object({
+            Adapter: variant(z.string()),
+            Address: variant(z.string()),
             Alias: variant(z.string()),
             Connected: variant(z.boolean()),
+            Name: variant(z.string()).optional(),
+            Paired: variant(z.boolean()),
         })
             .optional(),
     })),

package/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
     "@cprussin/option-result": "^2.0.1",
-    "@domicile-desktop/sdk": "0.0.0-alpha-e3866c607353",
+    "@domicile-desktop/sdk": "0.0.0-alpha-1fcbde657613",
     "zod": "^4.5.4"
   },
   "description": "BlueZ for a Domicile shell: whether each adapter is powered and which devices are connected, kept current, and turning adapters on and off.",
@@ -36,5 +36,5 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-e3866c607353"
+  "version": "0.0.0-alpha-1fcbde657613"
 }