tesla-fleet-api 0.4.0 → 0.6.0

package/dist/bluetooth/homey.d.mts

@@ -0,0 +1,84 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.mjs";
+/**
+ * Bytes per write: `null`, a whole frame in one write. Homey hides the MTU.
+ * BLE-00 (HW-0, 2026-11-03) measured a 114-byte frame in one write at 232 ms to
+ * a reply, against 562 ms for 6 writes of 20 bytes. Only 114 bytes were tried:
+ * a signed frame (about 200 bytes) is confirmed by HW-5. Pass `maxWriteSize: 20`
+ * to `HomeyBleTransport` to chunk at the ATT minimum if that run shows a failure.
+ */
+export declare const HOMEY_MAX_WRITE_SIZE: null;
+/**
+ * Bound on one scan. `discover()` takes a fixed 10.04 s when it is not cached
+ * (HW-0), so the library's 10 s default would time out about 40 ms early.
+ * `VehicleBluetooth` uses this when `scan_timeout_ms` is not set.
+ */
+export declare const HOMEY_SCAN_TIMEOUT_MS = 15000;
+/**
+ * For `connect_timeout_ms` and `max_connect_attempts`, not applied by this
+ * adapter: `discover()` caches for 30 s, so a fast retry sees old data, and
+ * these fit Homey's 9 s action window. BLE-00 step 11 sets both, against its
+ * target of a connect under 4 s in 9 of 10. A flow with no such window should
+ * keep the library's defaults until then, as a link slower than this never lands.
+ */
+export declare const HOMEY_VEHICLE_OPTIONS: {
+  readonly connect_timeout_ms: 4000;
+  readonly max_connect_attempts: 1;
+};
+/**
+ * Bound on discovery and subscribing once a link is up. Homey has no timeout of
+ * its own, and if these hang, nothing else could release the vehicle's slot.
+ * BLE-00 steps 3 and 4 show what a slow link takes.
+ */
+export declare const HOMEY_SETUP_TIMEOUT_MS = 20000;
+/** Bound on unsubscribing, which must not keep `disconnect` from running on a dead link. BLE-00 step 10. */
+export declare const HOMEY_UNSUBSCRIBE_TIMEOUT_MS = 1000;
+export interface HomeyCharacteristicLike {
+  uuid: string;
+  read(): Promise<Buffer>;
+  /** Always a write with response: the only kind Homey offers. */
+  write(data: Buffer): Promise<unknown>;
+  subscribeToNotifications(callback: (data: Buffer) => void): Promise<void>;
+  unsubscribeFromNotifications(): Promise<void>;
+}
+export interface HomeyServiceLike {
+  discoverCharacteristics(): Promise<HomeyCharacteristicLike[]>;
+}
+export interface HomeyPeripheralLike {
+  /** Can stay true after a silent drop, so it is only ever a faster signal. BLE-00 step 9 measures it. */
+  readonly isConnected: boolean;
+  getService(uuid: string): Promise<HomeyServiceLike>;
+  disconnect(): Promise<void>;
+  /** Not guaranteed on every drop, but if it fires, the link is gone. BLE-00 step 9 measures it. */
+  once(event: "disconnect", listener: () => void): unknown;
+  removeListener(event: "disconnect", listener: () => void): unknown;
+}
+export interface HomeyAdvertisementLike {
+  uuid: string;
+  /** Typed as a string, but Homey's guide says it is optional. BLE-00 step 2 measures how often it is there. */
+  localName?: string;
+  rssi?: number;
+  connectable?: boolean;
+  /** If already connected, returns the existing connection. It has no timeout: the library bounds it. */
+  connect(): Promise<HomeyPeripheralLike>;
+}
+/** What this adapter needs of `this.homey.ble`. */
+export interface HomeyBleManagerLike {
+  /** About 10 s, fixed, when not cached (BLE-00 HW-0). Called with no filter, because the vehicle advertises no service. */
+  discover(): Promise<HomeyAdvertisementLike[]>;
+  find(uuid: string): Promise<HomeyAdvertisementLike>;
+}
+export interface HomeyBleTransportOptions {
+  /** Bytes per write, or `null` for a whole frame in one write. Defaults to `HOMEY_MAX_WRITE_SIZE`. */
+  maxWriteSize?: number | null;
+}
+export declare class HomeyBleTransport implements BleTransport {
+  private readonly ble;
+  private readonly maxWriteSize;
+  private readonly claims;
+  readonly scanTimeoutMs = 15000;
+  /** @param ble `this.homey.ble`. The app needs the `homey:wireless:ble` permission. */
+  constructor(ble: HomeyBleManagerLike, options?: HomeyBleTransportOptions);
+  /** Takes Homey's fixed window, whatever `timeoutMs` says. Never pass `discover` a filter. */
+  scan({ matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}

package/dist/bluetooth/homey.mjs

@@ -0,0 +1,159 @@
+import { withTimeout } from "./async.mjs";
+import { APPEARANCE_UUID, DEFAULT_CONNECT_TIMEOUT_MS, GENERIC_ACCESS_UUID, NAME_UUID, SERVICE_UUID, VEHICLE_NOTIFY_UUID, VEHICLE_WRITE_UUID, VERSION_UUID } from "./constants.mjs";
+import { BleNotSubmittedError } from "./transport.mjs";
+import { LinkClaims, compactUuid, quietly } from "./adapters/shared.mjs";
+// src/bluetooth/adapters/homey.ts
+/**
+* Bytes per write: `null`, a whole frame in one write. Homey hides the MTU.
+* BLE-00 (HW-0, 2026-11-03) measured a 114-byte frame in one write at 232 ms to
+* a reply, against 562 ms for 6 writes of 20 bytes. Only 114 bytes were tried:
+* a signed frame (about 200 bytes) is confirmed by HW-5. Pass `maxWriteSize: 20`
+* to `HomeyBleTransport` to chunk at the ATT minimum if that run shows a failure.
+*/
+const HOMEY_MAX_WRITE_SIZE = null;
+/**
+* Bound on one scan. `discover()` takes a fixed 10.04 s when it is not cached
+* (HW-0), so the library's 10 s default would time out about 40 ms early.
+* `VehicleBluetooth` uses this when `scan_timeout_ms` is not set.
+*/
+const HOMEY_SCAN_TIMEOUT_MS = 15e3;
+/**
+* For `connect_timeout_ms` and `max_connect_attempts`, not applied by this
+* adapter: `discover()` caches for 30 s, so a fast retry sees old data, and
+* these fit Homey's 9 s action window. BLE-00 step 11 sets both, against its
+* target of a connect under 4 s in 9 of 10. A flow with no such window should
+* keep the library's defaults until then, as a link slower than this never lands.
+*/
+const HOMEY_VEHICLE_OPTIONS = {
+	connect_timeout_ms: 4e3,
+	max_connect_attempts: 1
+};
+/**
+* Bound on discovery and subscribing once a link is up. Homey has no timeout of
+* its own, and if these hang, nothing else could release the vehicle's slot.
+* BLE-00 steps 3 and 4 show what a slow link takes.
+*/
+const HOMEY_SETUP_TIMEOUT_MS = DEFAULT_CONNECT_TIMEOUT_MS;
+/** Bound on unsubscribing, which must not keep `disconnect` from running on a dead link. BLE-00 step 10. */
+const HOMEY_UNSUBSCRIBE_TIMEOUT_MS = 1e3;
+function find(characteristics, uuid) {
+	return characteristics.find((characteristic) => compactUuid(characteristic.uuid) === compactUuid(uuid));
+}
+var HomeyConnection = class {
+	id;
+	handlers;
+	maxWriteSize;
+	claims;
+	lost = false;
+	closed = false;
+	closing;
+	peripheral;
+	characteristics = [];
+	genericAccess;
+	subscribed = false;
+	onDisconnect = () => {
+		this.lost = true;
+		if (!this.closed) this.handlers.onDisconnect();
+	};
+	constructor(id, handlers, maxWriteSize, claims) {
+		this.id = id;
+		this.handlers = handlers;
+		this.maxWriteSize = maxWriteSize;
+		this.claims = claims;
+	}
+	/** Stale after a silent drop. The library's timeouts are what find a dead link. */
+	get isConnected() {
+		return !this.lost && !this.closed && this.peripheral?.isConnected === true;
+	}
+	/** Discover, then subscribe: the link is live only once this resolves. */
+	async attach(peripheral) {
+		this.peripheral = peripheral;
+		this.assertCurrent();
+		peripheral.once("disconnect", this.onDisconnect);
+		const characteristics = await (await peripheral.getService(compactUuid(SERVICE_UUID))).discoverCharacteristics();
+		const notify = find(characteristics, VEHICLE_NOTIFY_UUID);
+		if (!notify || !find(characteristics, "00000212-b2d1-43f0-9b88-960cebf8b91e")) throw new Error("The vehicle's write or notify characteristic was not found.");
+		this.assertCurrent();
+		this.characteristics = characteristics;
+		await notify.subscribeToNotifications((data) => this.handlers.onNotify(data));
+		this.subscribed = true;
+	}
+	/**
+	* Homey hands every attempt the same link, and one subscription per
+	* characteristic. A superseded attempt stops here, before it changes either.
+	*/
+	assertCurrent() {
+		if (this.claims.superseded(this.id, this)) throw new Error("A newer connect attempt took over this link.");
+	}
+	async write(data) {
+		const characteristic = find(this.characteristics, VEHICLE_WRITE_UUID);
+		if (!characteristic) throw new BleNotSubmittedError("The vehicle write characteristic was not found.");
+		if (!this.isConnected) throw new BleNotSubmittedError("The link is down.");
+		await characteristic.write(Buffer.from(data));
+	}
+	async read(characteristic) {
+		const target = characteristic === "version" ? find(this.characteristics, VERSION_UUID) : find(await this.discoverGenericAccess(), characteristic === "deviceName" ? NAME_UUID : APPEARANCE_UUID);
+		if (!target) throw new BleNotSubmittedError(`The ${characteristic} characteristic was not found.`);
+		return target.read();
+	}
+	/**
+	* Homey's stack may hide this service, which BLE-00 step 8 settles. A failed
+	* lookup leaves a characteristic unresolved on a healthy link, so it must not
+	* read as a lost one.
+	*/
+	discoverGenericAccess() {
+		const { peripheral } = this;
+		if (!peripheral) return Promise.reject(new BleNotSubmittedError("The link is down."));
+		this.genericAccess ??= peripheral.getService(compactUuid(GENERIC_ACCESS_UUID)).then((service) => service.discoverCharacteristics()).catch((cause) => {
+			this.genericAccess = void 0;
+			throw new BleNotSubmittedError("Generic Access could not be resolved.", { cause });
+		});
+		return this.genericAccess;
+	}
+	disconnect() {
+		this.closing ??= (async () => {
+			this.closed = true;
+			const { peripheral, claims, id } = this;
+			peripheral?.removeListener("disconnect", this.onDisconnect);
+			const superseded = claims.superseded(id, this);
+			claims.release(id, this);
+			if (superseded || !peripheral) return;
+			if (this.subscribed) await quietly(() => withTimeout(() => find(this.characteristics, VEHICLE_NOTIFY_UUID).unsubscribeFromNotifications(), HOMEY_UNSUBSCRIBE_TIMEOUT_MS));
+			await quietly(() => peripheral.disconnect());
+		})();
+		return this.closing;
+	}
+};
+var HomeyBleTransport = class {
+	ble;
+	maxWriteSize;
+	claims = new LinkClaims();
+	scanTimeoutMs = HOMEY_SCAN_TIMEOUT_MS;
+	/** @param ble `this.homey.ble`. The app needs the `homey:wireless:ble` permission. */
+	constructor(ble, options = {}) {
+		this.ble = ble;
+		this.maxWriteSize = options.maxWriteSize === void 0 ? null : options.maxWriteSize;
+	}
+	/** Takes Homey's fixed window, whatever `timeoutMs` says. Never pass `discover` a filter. */
+	async scan({ matches }) {
+		return (await this.ble.discover()).filter((advertisement) => !matches || advertisement.localName !== void 0 && matches(advertisement.localName)).map((advertisement) => ({
+			id: advertisement.uuid,
+			name: advertisement.localName,
+			rssi: advertisement.rssi,
+			connectable: advertisement.connectable
+		}));
+	}
+	async connect(device, handlers) {
+		const connection = new HomeyConnection(device.id, handlers, this.maxWriteSize, this.claims);
+		this.claims.claim(device.id, connection);
+		try {
+			const peripheral = await (await this.ble.find(device.id)).connect();
+			await withTimeout(() => connection.attach(peripheral), HOMEY_SETUP_TIMEOUT_MS);
+		} catch (error) {
+			await connection.disconnect();
+			throw error;
+		}
+		return connection;
+	}
+};
+export { HOMEY_MAX_WRITE_SIZE, HOMEY_SCAN_TIMEOUT_MS, HOMEY_SETUP_TIMEOUT_MS, HOMEY_UNSUBSCRIBE_TIMEOUT_MS, HOMEY_VEHICLE_OPTIONS, HomeyBleTransport };

package/dist/bluetooth/names.cjs

@@ -0,0 +1,24 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+let crypto = require("crypto");
+crypto = require_runtime.__toESM(crypto, 1);
+// src/bluetooth/names.ts
+const VALID_NAME = /^S[a-f0-9]{16}[CDRP]$/;
+/** Whether a BLE device name is a valid Tesla vehicle's. */
+function valid_name(name) {
+	return VALID_NAME.test(name);
+}
+/** The BLE device name of a vehicle. */
+function get_name(vin) {
+	return `S${crypto.default.createHash("sha1").update(vin, "utf8").digest("hex").slice(0, 16)}C`;
+}
+/**
+* Whether an advertised name belongs to this VIN. The hash matches, with any of
+* the four suffixes `valid_name` allows, which is wider than Python's exact
+* match on `C`.
+*/
+function name_matches_vin(advertised, vin) {
+	return valid_name(advertised) && advertised.slice(0, 17) === get_name(vin).slice(0, 17);
+}
+exports.get_name = get_name;
+exports.name_matches_vin = name_matches_vin;
+exports.valid_name = valid_name;

package/dist/bluetooth/names.d.cts

@@ -0,0 +1,10 @@
+/** Whether a BLE device name is a valid Tesla vehicle's. */
+export declare function valid_name(name: string): boolean;
+/** The BLE device name of a vehicle. */
+export declare function get_name(vin: string): string;
+/**
+ * Whether an advertised name belongs to this VIN. The hash matches, with any of
+ * the four suffixes `valid_name` allows, which is wider than Python's exact
+ * match on `C`.
+ */
+export declare function name_matches_vin(advertised: string, vin: string): boolean;

package/dist/bluetooth/names.d.mts

@@ -0,0 +1,10 @@
+/** Whether a BLE device name is a valid Tesla vehicle's. */
+export declare function valid_name(name: string): boolean;
+/** The BLE device name of a vehicle. */
+export declare function get_name(vin: string): string;
+/**
+ * Whether an advertised name belongs to this VIN. The hash matches, with any of
+ * the four suffixes `valid_name` allows, which is wider than Python's exact
+ * match on `C`.
+ */
+export declare function name_matches_vin(advertised: string, vin: string): boolean;

package/dist/bluetooth/names.mjs

@@ -0,0 +1,20 @@
+import crypto from "crypto";
+// src/bluetooth/names.ts
+const VALID_NAME = /^S[a-f0-9]{16}[CDRP]$/;
+/** Whether a BLE device name is a valid Tesla vehicle's. */
+function valid_name(name) {
+	return VALID_NAME.test(name);
+}
+/** The BLE device name of a vehicle. */
+function get_name(vin) {
+	return `S${crypto.createHash("sha1").update(vin, "utf8").digest("hex").slice(0, 16)}C`;
+}
+/**
+* Whether an advertised name belongs to this VIN. The hash matches, with any of
+* the four suffixes `valid_name` allows, which is wider than Python's exact
+* match on `C`.
+*/
+function name_matches_vin(advertised, vin) {
+	return valid_name(advertised) && advertised.slice(0, 17) === get_name(vin).slice(0, 17);
+}
+export { get_name, name_matches_vin, valid_name };

package/dist/bluetooth/noble.cjs

@@ -0,0 +1,178 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_async = require("./async.cjs");
+const require_constants = require("./constants.cjs");
+const require_transport = require("./transport.cjs");
+const require_shared = require("./adapters/shared.cjs");
+// src/bluetooth/adapters/noble.ts
+function find(characteristics, uuid) {
+	return characteristics.find((characteristic) => require_shared.compactUuid(characteristic.uuid) === require_shared.compactUuid(uuid));
+}
+async function loadNoble(bindings) {
+	const specifier = "@stoprocent/noble/lib/resolve-bindings.js";
+	let module;
+	try {
+		module = await import(specifier);
+	} catch (cause) {
+		throw new Error("NobleBleTransport needs @stoprocent/noble, or a `noble` option.", { cause });
+	}
+	return module.default(bindings);
+}
+var NobleConnection = class {
+	peripheral;
+	handlers;
+	claims;
+	lost = false;
+	closed = false;
+	closing;
+	genericAccess;
+	characteristics = [];
+	onData = (data, isNotification) => {
+		if (isNotification !== false) this.handlers.onNotify(data);
+	};
+	onDisconnect = () => {
+		this.lost = true;
+		if (!this.closed) this.handlers.onDisconnect();
+	};
+	constructor(peripheral, handlers, claims) {
+		this.peripheral = peripheral;
+		this.handlers = handlers;
+		this.claims = claims;
+	}
+	get isConnected() {
+		return !this.lost && !this.closed && this.peripheral.state === "connected";
+	}
+	/** Read each time: noble can report a larger MTU after the link is up. */
+	get maxWriteSize() {
+		const { mtu } = this.peripheral;
+		return mtu && mtu > 3 ? mtu - 3 : 20;
+	}
+	/** Resolve the characteristics and turn notifications on. */
+	async subscribe() {
+		const { peripheral } = this;
+		const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync([require_shared.compactUuid(require_constants.SERVICE_UUID)], [
+			require_constants.VEHICLE_WRITE_UUID,
+			require_constants.VEHICLE_NOTIFY_UUID,
+			require_constants.VERSION_UUID
+		].map(require_shared.compactUuid));
+		const notify = find(characteristics, require_constants.VEHICLE_NOTIFY_UUID);
+		if (!notify || !find(characteristics, "00000212-b2d1-43f0-9b88-960cebf8b91e")) throw new Error("The vehicle's write or notify characteristic was not found.");
+		this.assertCurrent();
+		this.characteristics = characteristics;
+		notify.on("data", this.onData);
+		await notify.subscribeAsync();
+	}
+	/** A superseded attempt stops here, before it changes a link another attempt owns. */
+	assertCurrent() {
+		if (this.claims.superseded(this.peripheral.id, this)) throw new Error("A newer connect attempt took over this link.");
+	}
+	async write(data) {
+		const characteristic = find(this.characteristics, require_constants.VEHICLE_WRITE_UUID);
+		if (!characteristic) throw new require_transport.BleNotSubmittedError("The vehicle write characteristic was not found.");
+		if (!this.isConnected) throw new require_transport.BleNotSubmittedError("The link is down.");
+		await characteristic.writeAsync(Buffer.from(data), false);
+	}
+	async read(characteristic) {
+		const target = characteristic === "version" ? find(this.characteristics, require_constants.VERSION_UUID) : find(await this.discoverGenericAccess(), characteristic === "deviceName" ? require_constants.NAME_UUID : require_constants.APPEARANCE_UUID);
+		if (!target) throw new require_transport.BleNotSubmittedError(`The ${characteristic} characteristic was not found.`);
+		return target.readAsync();
+	}
+	/**
+	* BlueZ and CoreBluetooth can hide this service. A failed lookup leaves a
+	* characteristic unresolved on a healthy link, so it must not read as a lost one.
+	*/
+	discoverGenericAccess() {
+		this.genericAccess ??= this.peripheral.discoverSomeServicesAndCharacteristicsAsync([require_shared.compactUuid(require_constants.GENERIC_ACCESS_UUID)], [require_shared.compactUuid(require_constants.NAME_UUID), require_shared.compactUuid(require_constants.APPEARANCE_UUID)]).then(({ characteristics }) => characteristics).catch((cause) => {
+			this.genericAccess = void 0;
+			throw new require_transport.BleNotSubmittedError("Generic Access could not be resolved.", { cause });
+		});
+		return this.genericAccess;
+	}
+	disconnect() {
+		this.closing ??= (async () => {
+			this.closed = true;
+			const { peripheral, claims } = this;
+			peripheral.removeListener("disconnect", this.onDisconnect);
+			find(this.characteristics, require_constants.VEHICLE_NOTIFY_UUID)?.removeListener("data", this.onData);
+			const superseded = claims.superseded(peripheral.id, this);
+			claims.release(peripheral.id, this);
+			if (!superseded && peripheral.state !== "disconnected") await require_shared.quietly(() => peripheral.disconnectAsync());
+		})();
+		return this.closing;
+	}
+};
+var NobleBleTransport = class {
+	options;
+	backend;
+	scans = new require_async.AsyncLock();
+	peripherals = /* @__PURE__ */ new Map();
+	claims = new require_shared.LinkClaims();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	noble() {
+		if (this.options.noble) return Promise.resolve(this.options.noble);
+		const fallback = process.platform === "linux" ? "dbus" : "default";
+		const loading = this.backend ??= loadNoble(this.options.bindings ?? fallback);
+		loading.catch(() => {
+			this.backend = void 0;
+		});
+		return loading;
+	}
+	async scan({ timeoutMs, matches }) {
+		const noble = await this.noble();
+		return this.listen(noble, timeoutMs, (device) => device.name !== void 0 && matches?.(device.name) === true);
+	}
+	/** Scan with no service filter until `done` accepts a device or the window ends. */
+	listen(noble, timeoutMs, done) {
+		return this.scans.run(async () => {
+			await noble.waitForPoweredOnAsync(timeoutMs);
+			const seen = /* @__PURE__ */ new Map();
+			let finish;
+			const finished = new Promise((resolve) => {
+				finish = resolve;
+			});
+			const onDiscover = (peripheral) => {
+				this.peripherals.set(peripheral.id, peripheral);
+				const device = {
+					id: peripheral.id,
+					name: peripheral.advertisement.localName ?? seen.get(peripheral.id)?.name,
+					rssi: peripheral.rssi,
+					connectable: peripheral.connectable
+				};
+				seen.set(peripheral.id, device);
+				if (done(device)) finish();
+			};
+			noble.on("discover", onDiscover);
+			const timer = setTimeout(finish, Math.max(0, timeoutMs - 250));
+			try {
+				await noble.startScanningAsync([], true);
+				await finished;
+			} finally {
+				clearTimeout(timer);
+				noble.removeListener("discover", onDiscover);
+				await require_shared.quietly(() => noble.stopScanningAsync());
+			}
+			return [...seen.values()];
+		});
+	}
+	async connect(device, handlers) {
+		const noble = await this.noble();
+		if (!this.peripherals.has(device.id)) await this.listen(noble, require_constants.DEFAULT_SCAN_TIMEOUT_MS, ({ id }) => id === device.id);
+		const peripheral = this.peripherals.get(device.id);
+		if (!peripheral) throw new Error("The device was not seen in a scan.");
+		await require_shared.quietly(() => noble.stopScanningAsync());
+		const connection = new NobleConnection(peripheral, handlers, this.claims);
+		this.claims.claim(device.id, connection);
+		peripheral.once("disconnect", connection.onDisconnect);
+		try {
+			await peripheral.connectAsync();
+			connection.assertCurrent();
+			await require_async.withTimeout(() => connection.subscribe(), require_constants.DEFAULT_CONNECT_TIMEOUT_MS);
+		} catch (error) {
+			await connection.disconnect();
+			throw error;
+		}
+		return connection;
+	}
+};
+exports.NobleBleTransport = NobleBleTransport;

package/dist/bluetooth/noble.d.cts

@@ -0,0 +1,58 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.cjs";
+export interface NobleCharacteristicLike {
+  uuid: string;
+  on(event: "data", listener: (data: Buffer, isNotification?: boolean) => void): unknown;
+  removeListener(event: "data", listener: (data: Buffer, isNotification?: boolean) => void): unknown;
+  subscribeAsync(): Promise<void>;
+  /** `withoutResponse: false` is a write with response. */
+  writeAsync(data: Buffer, withoutResponse: boolean): Promise<void>;
+  readAsync(): Promise<Buffer>;
+}
+export interface NoblePeripheralLike {
+  id: string;
+  state: string;
+  mtu: number | null;
+  rssi?: number;
+  connectable?: boolean;
+  advertisement: {
+    localName?: string;
+  };
+  connectAsync(): Promise<void>;
+  disconnectAsync(): Promise<void>;
+  discoverSomeServicesAndCharacteristicsAsync(serviceUUIDs: string[], characteristicUUIDs: string[]): Promise<{
+    characteristics: NobleCharacteristicLike[];
+  }>;
+  once(event: "disconnect", listener: () => void): unknown;
+  removeListener(event: "disconnect", listener: () => void): unknown;
+}
+export interface NobleLike {
+  waitForPoweredOnAsync(timeout?: number): Promise<void>;
+  startScanningAsync(serviceUUIDs?: string[], allowDuplicates?: boolean): Promise<void>;
+  stopScanningAsync(): Promise<void>;
+  on(event: "discover", listener: (peripheral: NoblePeripheralLike) => void): unknown;
+  removeListener(event: "discover", listener: (peripheral: NoblePeripheralLike) => void): unknown;
+}
+export interface NobleBleTransportOptions {
+  /** A noble you built, such as `withBindings("dbus")`. Without it, `@stoprocent/noble` loads on first use. */
+  noble?: NobleLike;
+  /**
+   * Which bindings to load. Defaults to `"dbus"` on Linux, which shares the
+   * adapter with BlueZ and needs no root but does need `dbus-next`, and to
+   * `"default"` elsewhere. `"hci"` needs `sudo setcap cap_net_raw+eip` on the
+   * Node binary.
+   */
+  bindings?: "default" | "dbus" | "hci" | "mac" | "win";
+}
+export declare class NobleBleTransport implements BleTransport {
+  private readonly options;
+  private backend;
+  private readonly scans;
+  private readonly peripherals;
+  private readonly claims;
+  constructor(options?: NobleBleTransportOptions);
+  private noble;
+  scan({ timeoutMs, matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Scan with no service filter until `done` accepts a device or the window ends. */
+  private listen;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}

package/dist/bluetooth/noble.d.mts

@@ -0,0 +1,58 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.mjs";
+export interface NobleCharacteristicLike {
+  uuid: string;
+  on(event: "data", listener: (data: Buffer, isNotification?: boolean) => void): unknown;
+  removeListener(event: "data", listener: (data: Buffer, isNotification?: boolean) => void): unknown;
+  subscribeAsync(): Promise<void>;
+  /** `withoutResponse: false` is a write with response. */
+  writeAsync(data: Buffer, withoutResponse: boolean): Promise<void>;
+  readAsync(): Promise<Buffer>;
+}
+export interface NoblePeripheralLike {
+  id: string;
+  state: string;
+  mtu: number | null;
+  rssi?: number;
+  connectable?: boolean;
+  advertisement: {
+    localName?: string;
+  };
+  connectAsync(): Promise<void>;
+  disconnectAsync(): Promise<void>;
+  discoverSomeServicesAndCharacteristicsAsync(serviceUUIDs: string[], characteristicUUIDs: string[]): Promise<{
+    characteristics: NobleCharacteristicLike[];
+  }>;
+  once(event: "disconnect", listener: () => void): unknown;
+  removeListener(event: "disconnect", listener: () => void): unknown;
+}
+export interface NobleLike {
+  waitForPoweredOnAsync(timeout?: number): Promise<void>;
+  startScanningAsync(serviceUUIDs?: string[], allowDuplicates?: boolean): Promise<void>;
+  stopScanningAsync(): Promise<void>;
+  on(event: "discover", listener: (peripheral: NoblePeripheralLike) => void): unknown;
+  removeListener(event: "discover", listener: (peripheral: NoblePeripheralLike) => void): unknown;
+}
+export interface NobleBleTransportOptions {
+  /** A noble you built, such as `withBindings("dbus")`. Without it, `@stoprocent/noble` loads on first use. */
+  noble?: NobleLike;
+  /**
+   * Which bindings to load. Defaults to `"dbus"` on Linux, which shares the
+   * adapter with BlueZ and needs no root but does need `dbus-next`, and to
+   * `"default"` elsewhere. `"hci"` needs `sudo setcap cap_net_raw+eip` on the
+   * Node binary.
+   */
+  bindings?: "default" | "dbus" | "hci" | "mac" | "win";
+}
+export declare class NobleBleTransport implements BleTransport {
+  private readonly options;
+  private backend;
+  private readonly scans;
+  private readonly peripherals;
+  private readonly claims;
+  constructor(options?: NobleBleTransportOptions);
+  private noble;
+  scan({ timeoutMs, matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Scan with no service filter until `done` accepts a device or the window ends. */
+  private listen;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}