tesla-fleet-api 0.4.0 → 0.5.0

package/dist/bluetooth/constants.mjs

@@ -0,0 +1,72 @@
+// src/bluetooth/constants.ts
+/** The vehicle's GATT service. It is never advertised, so never scan for it. */
+const SERVICE_UUID = "00000211-b2d1-43f0-9b88-960cebf8b91e";
+/** Client to car. Tesla's Go SDK names the two by the opposite view, hence these names. */
+const VEHICLE_WRITE_UUID = "00000212-b2d1-43f0-9b88-960cebf8b91e";
+/** Car to client. */
+const VEHICLE_NOTIFY_UUID = "00000213-b2d1-43f0-9b88-960cebf8b91e";
+/** Python's name for `VEHICLE_WRITE_UUID`. */
+const WRITE_UUID = VEHICLE_WRITE_UUID;
+/** Python's name for `VEHICLE_NOTIFY_UUID`. */
+const READ_UUID = VEHICLE_NOTIFY_UUID;
+/** The keepalive read target. */
+const VERSION_UUID = "00000214-b2d1-43f0-9b88-960cebf8b91e";
+/** GATT Device Name. */
+const NAME_UUID = "00002a00-0000-1000-8000-00805f9b34fb";
+/** GATT Appearance. */
+const APPEARANCE_UUID = "00002a01-0000-1000-8000-00805f9b34fb";
+/** Generic Access, for a backend that needs a service UUID to reach the two above. */
+const GENERIC_ACCESS_UUID = "00001800-0000-1000-8000-00805f9b34fb";
+/** Client Characteristic Configuration. Only an ESPHome proxy needs it written by hand. */
+const CCCD_UUID = "00002902-0000-1000-8000-00805f9b34fb";
+/** Largest frame accepted, length prefix included. Tesla's Go SDK allows 2 more bytes. */
+const MAX_FRAME_SIZE = 1024;
+/**
+* Bytes per write when a connection does not say: the ATT default MTU of 23,
+* less 3 of header. Safe on any link, and all Homey offers, as it hides the MTU.
+*/
+const DEFAULT_MAX_WRITE_SIZE = 20;
+/** A chunk after this much silence means the partial frame before it was abandoned. */
+const STALE_CHUNK_TIMEOUT_MS = 1e3;
+/** An idle held link drops at about 42 s on average; a read this often keeps it about 10 times longer. */
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 2e4;
+/** Infotainment answers a handshake 4 to 16 s after an RKE wake. */
+const DEFAULT_WAKE_TIMEOUT_MS = 3e4;
+/**
+* One infotainment readiness probe. A ready infotainment answers in 0.26 to 0.39 s.
+* The window opens once the request is fully written, so a slow 20-byte link
+* spends none of it writing. Raise it with `wake_probe_timeout_ms` if a link's
+* replies are slower than this, as a probe that keeps timing out never proves
+* the car is ready.
+*/
+const DEFAULT_WAKE_PROBE_TIMEOUT_MS = 1e3;
+/** How often a wake is resent while infotainment stays silent: a first wake can be missed after a long sleep. */
+const WAKE_RESEND_INTERVAL_MS = 3e3;
+/** How long an awake car's infotainment may take to finish booting. */
+const INFOTAINMENT_BOOT_TIMEOUT_MS = 2e4;
+/** How long a charge-port opening has to show in charge state. It took about 1.4 s in live trials. */
+const CHARGE_PORT_VERIFY_TIMEOUT_MS = 5e3;
+/** Between charge-state polls, while waiting for readiness or for the latch. */
+const CHARGE_PORT_VERIFY_INTERVAL_MS = 250;
+/** How long `pair` waits for someone to tap a key card. */
+const DEFAULT_PAIR_TIMEOUT_MS = 3e5;
+/** Between `pair`'s checks of whether the key was accepted. */
+const DEFAULT_PAIR_POLL_INTERVAL_MS = 5e3;
+/** Connect attempts. Each is bounded by `DEFAULT_CONNECT_TIMEOUT_MS`. */
+const DEFAULT_CONNECT_ATTEMPTS = 3;
+/** One connect attempt. Python takes the same figure from `bleak-retry-connector`. */
+const DEFAULT_CONNECT_TIMEOUT_MS = 2e4;
+/** One scan. It must outlast the backend's window, which Homey fixes at about 5 s. */
+const DEFAULT_SCAN_TIMEOUT_MS = 1e4;
+/** Bound on tearing down a link: the failure behind it is what gets reported. */
+const LINK_TEARDOWN_TIMEOUT_MS = 5e3;
+/**
+* One write call. Not in Python, whose backends bound their own writes. Homey's
+* have no timeout and its link state can be stale, so a hung write must end
+* here. A design choice. BLE-00 step 10 measures how long a failing write takes
+* on Homey, which sets it.
+*/
+const GATT_WRITE_TIMEOUT_MS = 5e3;
+/** One read call, other than a keepalive's. */
+const GATT_READ_TIMEOUT_MS = 5e3;
+export { APPEARANCE_UUID, CCCD_UUID, CHARGE_PORT_VERIFY_INTERVAL_MS, CHARGE_PORT_VERIFY_TIMEOUT_MS, DEFAULT_CONNECT_ATTEMPTS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_KEEPALIVE_INTERVAL_MS, DEFAULT_MAX_WRITE_SIZE, DEFAULT_PAIR_POLL_INTERVAL_MS, DEFAULT_PAIR_TIMEOUT_MS, DEFAULT_SCAN_TIMEOUT_MS, DEFAULT_WAKE_PROBE_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, GATT_READ_TIMEOUT_MS, GATT_WRITE_TIMEOUT_MS, GENERIC_ACCESS_UUID, INFOTAINMENT_BOOT_TIMEOUT_MS, LINK_TEARDOWN_TIMEOUT_MS, MAX_FRAME_SIZE, NAME_UUID, READ_UUID, SERVICE_UUID, STALE_CHUNK_TIMEOUT_MS, VEHICLE_NOTIFY_UUID, VEHICLE_WRITE_UUID, VERSION_UUID, WAKE_RESEND_INTERVAL_MS, WRITE_UUID };

package/dist/bluetooth/esphome.cjs

@@ -0,0 +1,292 @@
+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/esphome.ts
+/** The bytes that turn notifications on in a CCCD. */
+const CCCD_ENABLE_NOTIFICATIONS = Buffer.from([1, 0]);
+/** How long a proxy takes to answer a connect. The package's own wait is the same. */
+const DEVICE_CONNECT_WAIT_MS = 1e4;
+/** How long the API connection to the proxy may take. */
+const API_CONNECT_TIMEOUT_MS = 1e4;
+const ADVERTISEMENT = "message.BluetoothLEAdvertisementResponse";
+const CONNECTION_STATE = "message.BluetoothDeviceConnectionResponse";
+const NOTIFY_DATA = "message.BluetoothGATTNotifyDataResponse";
+/** One queue per proxy, however many transports or links share it. */
+const proxyQueues = /* @__PURE__ */ new WeakMap();
+function queueFor(proxy) {
+	let queue = proxyQueues.get(proxy);
+	if (!queue) {
+		queue = new require_async.AsyncLock();
+		proxyQueues.set(proxy, queue);
+	}
+	return queue;
+}
+/** A proxy's 48-bit address as a MAC, the form a caller would recognize. */
+function formatAddress(address) {
+	return address.toString(16).padStart(12, "0").replace(/(..)(?=.)/g, "$1:").toUpperCase();
+}
+function parseAddress(id) {
+	const hex = id.replace(/:/g, "");
+	if (!/^[0-9a-fA-F]{12}$/.test(hex)) throw new Error("An ESPHome device id must be a 48-bit address.");
+	return Number.parseInt(hex, 16);
+}
+function sameUuid(entry, uuid) {
+	return entry.uuid ? require_shared.compactUuid(entry.uuid) === require_shared.compactUuid(uuid) : (entry.shortUuid ?? 0).toString(16).padStart(4, "0") === require_shared.compactUuid(uuid);
+}
+/** A late reply to an abandoned call can land on the next call of its type. */
+function assertReplyFor(reply, address, handle) {
+	if (reply.address !== address || reply.handle !== handle) throw new Error("The proxy's reply was for another request.");
+}
+var EsphomeConnection = class {
+	proxy;
+	address;
+	id;
+	handlers;
+	claims;
+	lost = false;
+	closed = false;
+	closing;
+	handles = /* @__PURE__ */ new Map();
+	mtu = 0;
+	onLost = () => {
+		if (this.lost) return;
+		this.lost = true;
+		this.stopListening();
+		if (!this.closed) this.handlers.onDisconnect();
+	};
+	onState = (state) => {
+		if (state.address === this.address && !state.connected) this.onLost();
+	};
+	notifyHandle;
+	onNotifyData = (message) => {
+		if (message.address === this.address && message.handle === this.notifyHandle) this.handlers.onNotify(Buffer.from(message.data, "base64"));
+	};
+	constructor(proxy, address, id, handlers, claims) {
+		this.proxy = proxy;
+		this.address = address;
+		this.id = id;
+		this.handlers = handlers;
+		this.claims = claims;
+	}
+	get queue() {
+		return queueFor(this.proxy);
+	}
+	get isConnected() {
+		return !this.lost && !this.closed && this.proxy.connected && this.proxy.authorized;
+	}
+	get maxWriteSize() {
+		return this.mtu > 3 ? this.mtu - 3 : 20;
+	}
+	/** Ask the proxy to connect. The reply is matched here, as a link dropping elsewhere sends the same message type. */
+	requestLink(addressType) {
+		const { proxy, address } = this;
+		return this.queue.run(async () => {
+			let onReply;
+			const reply = new Promise((resolve) => {
+				onReply = (state) => {
+					if (state.address === address) resolve(state);
+				};
+			});
+			proxy.on(CONNECTION_STATE, onReply);
+			try {
+				return await require_async.withTimeout(() => Promise.race([reply, proxy.connectBluetoothDeviceService(address, addressType, false).then(() => reply)]), DEVICE_CONNECT_WAIT_MS);
+			} finally {
+				proxy.off(CONNECTION_STATE, onReply);
+			}
+		});
+	}
+	/** Connect, map the handles, and subscribe. Resolves once the CCCD write is done. */
+	async open(addressType) {
+		const state = await this.requestLink(addressType);
+		if (!state.connected || state.error) {
+			this.lost = true;
+			throw new Error(`The proxy could not connect: error ${state.error}.`);
+		}
+		this.assertCurrent();
+		this.mtu = state.mtu;
+		const { proxy, address } = this;
+		proxy.on(CONNECTION_STATE, this.onState);
+		proxy.on("disconnected", this.onLost);
+		proxy.on("unauthorized", this.onLost);
+		const { servicesList } = await this.queue.run(() => proxy.listBluetoothGATTServicesService(address));
+		const service = servicesList.find((candidate) => sameUuid(candidate, require_constants.SERVICE_UUID));
+		const characteristic = (uuid) => service?.characteristicsList.find((candidate) => sameUuid(candidate, uuid));
+		const write = characteristic(require_constants.VEHICLE_WRITE_UUID);
+		const notify = characteristic(require_constants.VEHICLE_NOTIFY_UUID);
+		const cccd = notify?.descriptorsList.find((descriptor) => sameUuid(descriptor, require_constants.CCCD_UUID));
+		if (!write || !notify || !cccd) throw new Error("The vehicle's write or notify characteristic, or its CCCD, was not found.");
+		this.handles.set("write", write.handle);
+		const version = characteristic(require_constants.VERSION_UUID);
+		if (version) this.handles.set("version", version.handle);
+		const genericAccess = servicesList.find((candidate) => sameUuid(candidate, require_constants.GENERIC_ACCESS_UUID));
+		for (const [name, uuid] of [["deviceName", require_constants.NAME_UUID], ["appearance", require_constants.APPEARANCE_UUID]]) {
+			const entry = genericAccess?.characteristicsList.find((candidate) => sameUuid(candidate, uuid));
+			if (entry) this.handles.set(name, entry.handle);
+		}
+		this.assertCurrent();
+		this.notifyHandle = notify.handle;
+		proxy.on(NOTIFY_DATA, this.onNotifyData);
+		await this.queue.run(() => proxy.notifyBluetoothGATTCharacteristicService(address, notify.handle));
+		await this.queue.run(() => proxy.writeBluetoothGATTDescriptorService(address, cccd.handle, CCCD_ENABLE_NOTIFICATIONS));
+	}
+	/** A superseded attempt stops here, before it changes a link another attempt owns. */
+	assertCurrent() {
+		if (this.claims.superseded(this.id, this)) throw new Error("A newer connect attempt took over this link.");
+	}
+	async write(data) {
+		const { proxy, address } = this;
+		const handle = this.handles.get("write");
+		if (handle === void 0) throw new require_transport.BleNotSubmittedError("The vehicle write characteristic was not found.");
+		const queuedAt = performance.now();
+		await this.queue.run(async () => {
+			if (!this.isConnected) throw new require_transport.BleNotSubmittedError("The link is down.");
+			if (performance.now() - queuedAt >= 5e3) throw new require_transport.BleNotSubmittedError("The write outlasted its timeout in the proxy queue.");
+			assertReplyFor(await proxy.writeBluetoothGATTCharacteristicService(address, handle, Buffer.from(data), true), address, handle);
+		});
+	}
+	async read(characteristic) {
+		const { proxy, address } = this;
+		const handle = this.handles.get(characteristic);
+		if (handle === void 0) throw new require_transport.BleNotSubmittedError(`The ${characteristic} characteristic was not found.`);
+		const reply = await this.queue.run(() => {
+			if (!this.isConnected) throw new require_transport.BleNotSubmittedError("The link is down.");
+			return proxy.readBluetoothGATTCharacteristicService(address, handle);
+		});
+		assertReplyFor(reply, address, handle);
+		return Buffer.from(reply.data, "base64");
+	}
+	stopListening() {
+		const { proxy } = this;
+		proxy.off(CONNECTION_STATE, this.onState);
+		proxy.off("disconnected", this.onLost);
+		proxy.off("unauthorized", this.onLost);
+		proxy.off(NOTIFY_DATA, this.onNotifyData);
+	}
+	disconnect() {
+		this.closing ??= (async () => {
+			this.closed = true;
+			this.stopListening();
+			const { claims, id, proxy, address } = this;
+			const superseded = claims.superseded(id, this);
+			claims.release(id, this);
+			if (!superseded && !this.lost && proxy.authorized) await require_shared.quietly(() => this.queue.run(() => proxy.disconnectBluetoothDeviceService(address)));
+		})();
+		return this.closing;
+	}
+};
+var EsphomeBleTransport = class {
+	options;
+	proxy;
+	ownsProxy;
+	scans = new require_async.AsyncLock();
+	claims = new require_shared.LinkClaims();
+	/** A proxy refuses a connect with no address type, and only an advertisement carries it. */
+	addressTypes = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+		this.ownsProxy = !("connection" in options);
+		if ("connection" in options) this.proxy = options.connection;
+	}
+	/** The API connection, up and authorized. */
+	async ready() {
+		const proxy = this.proxy ??= await this.buildProxy();
+		if (proxy.authorized) return proxy;
+		if (this.ownsProxy && !proxy.connected) proxy.connect();
+		let onAuthorized;
+		let onError;
+		try {
+			await require_async.withTimeout(() => new Promise((resolve, reject) => {
+				onAuthorized = resolve;
+				onError = reject;
+				proxy.on("authorized", onAuthorized);
+				proxy.on("error", onError);
+			}), API_CONNECT_TIMEOUT_MS);
+		} finally {
+			proxy.off("authorized", onAuthorized);
+			proxy.off("error", onError);
+		}
+		return proxy;
+	}
+	async buildProxy() {
+		if ("connection" in this.options) return this.options.connection;
+		const specifier = "@2colors/esphome-native-api";
+		let module;
+		try {
+			module = await import(specifier);
+		} catch (cause) {
+			throw new Error("EsphomeBleTransport needs @2colors/esphome-native-api, or a `connection` option.", { cause });
+		}
+		const Connection = module.Connection ?? module.default?.Connection;
+		if (!Connection) throw new Error("@2colors/esphome-native-api has no Connection.");
+		const { host, port, encryptionKey, password } = this.options;
+		const proxy = new Connection({
+			host,
+			port,
+			encryptionKey,
+			password
+		});
+		proxy.on("error", () => void 0);
+		return proxy;
+	}
+	async scan({ timeoutMs, matches }) {
+		const proxy = await this.ready();
+		return this.listen(proxy, timeoutMs, (device) => device.name !== void 0 && matches?.(device.name) === true);
+	}
+	/** Listen to advertisements until `done` accepts a device or the window ends. A proxy filters nothing. */
+	listen(proxy, timeoutMs, done) {
+		return this.scans.run(async () => {
+			const seen = /* @__PURE__ */ new Map();
+			let finish;
+			const finished = new Promise((resolve) => {
+				finish = resolve;
+			});
+			const onAdvertisement = (advertisement) => {
+				const id = formatAddress(advertisement.address);
+				this.addressTypes.set(id, advertisement.addressType ?? this.addressTypes.get(id));
+				const device = {
+					id,
+					name: advertisement.name || seen.get(id)?.name,
+					rssi: advertisement.rssi
+				};
+				seen.set(id, device);
+				if (done(device)) finish();
+			};
+			proxy.on(ADVERTISEMENT, onAdvertisement);
+			const timer = setTimeout(finish, Math.max(0, timeoutMs - 250));
+			try {
+				proxy.subscribeBluetoothAdvertisementService();
+				await finished;
+			} finally {
+				clearTimeout(timer);
+				proxy.off(ADVERTISEMENT, onAdvertisement);
+				await require_shared.quietly(() => proxy.unsubscribeBluetoothAdvertisementService());
+			}
+			return [...seen.values()];
+		});
+	}
+	async connect(device, handlers) {
+		const address = parseAddress(device.id);
+		const id = formatAddress(address);
+		const proxy = await this.ready();
+		if (this.addressTypes.get(id) === void 0) await this.listen(proxy, require_constants.DEFAULT_SCAN_TIMEOUT_MS, (seen) => seen.id === id && this.addressTypes.get(id) !== void 0);
+		const connection = new EsphomeConnection(proxy, address, id, handlers, this.claims);
+		this.claims.claim(id, connection);
+		try {
+			await connection.open(this.addressTypes.get(id));
+		} catch (error) {
+			await connection.disconnect();
+			throw error;
+		}
+		return connection;
+	}
+	/** Close the API connection, if this transport opened it. */
+	close() {
+		if (this.ownsProxy) {
+			this.proxy?.disconnect();
+			this.proxy = void 0;
+		}
+	}
+};
+exports.EsphomeBleTransport = EsphomeBleTransport;

package/dist/bluetooth/esphome.d.cts

@@ -0,0 +1,83 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.cjs";
+export interface EsphomeAdvertisement {
+  address: number;
+  addressType?: number;
+  name?: string;
+  rssi?: number;
+}
+export interface EsphomeConnectionState {
+  address: number;
+  connected: boolean;
+  mtu: number;
+  error: number;
+}
+export interface EsphomeGattDescriptor {
+  uuid?: string;
+  /** Set in place of `uuid` for a short UUID, on API 1.12 and up. */
+  shortUuid?: number;
+  handle: number;
+}
+export interface EsphomeGattCharacteristic extends EsphomeGattDescriptor {
+  descriptorsList: EsphomeGattDescriptor[];
+}
+export interface EsphomeGattService extends EsphomeGattDescriptor {
+  characteristicsList: EsphomeGattCharacteristic[];
+}
+export interface EsphomeGattReply {
+  address: number;
+  handle: number;
+}
+export interface EsphomeGattData extends EsphomeGattReply {
+  data: string;
+}
+/** The parts of the package's `Connection` this adapter uses. */
+export interface EsphomeConnectionLike {
+  connected: boolean;
+  authorized: boolean;
+  connect(): void;
+  disconnect(): void;
+  on(event: string, listener: (...args: any[]) => void): unknown;
+  off(event: string, listener: (...args: any[]) => void): unknown;
+  subscribeBluetoothAdvertisementService(): void;
+  unsubscribeBluetoothAdvertisementService(): void;
+  connectBluetoothDeviceService(address: number, addressType?: number, useCache?: boolean): Promise<unknown>;
+  disconnectBluetoothDeviceService(address: number): Promise<unknown>;
+  listBluetoothGATTServicesService(address: number): Promise<{
+    servicesList: EsphomeGattService[];
+  }>;
+  readBluetoothGATTCharacteristicService(address: number, handle: number): Promise<EsphomeGattData>;
+  writeBluetoothGATTCharacteristicService(address: number, handle: number, value: Uint8Array, response?: boolean): Promise<EsphomeGattReply>;
+  notifyBluetoothGATTCharacteristicService(address: number, handle: number): Promise<unknown>;
+  writeBluetoothGATTDescriptorService(address: number, handle: number, value: Uint8Array): Promise<void>;
+}
+export type EsphomeBleTransportOptions = {
+  /** A `Connection` you own. This adapter never closes it. */
+  connection: EsphomeConnectionLike;
+} | {
+  /** The proxy's address. `@2colors/esphome-native-api` loads on first use. */
+  host: string;
+  /** Defaults to the package's 6053. */
+  port?: number;
+  /** The proxy's Noise key, base64. Never logged. */
+  encryptionKey?: string;
+  password?: string;
+};
+export declare class EsphomeBleTransport implements BleTransport {
+  private readonly options;
+  private proxy;
+  private readonly ownsProxy;
+  private readonly scans;
+  private readonly claims;
+  /** A proxy refuses a connect with no address type, and only an advertisement carries it. */
+  private readonly addressTypes;
+  constructor(options: EsphomeBleTransportOptions);
+  /** The API connection, up and authorized. */
+  private ready;
+  private buildProxy;
+  scan({ timeoutMs, matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Listen to advertisements until `done` accepts a device or the window ends. A proxy filters nothing. */
+  private listen;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+  /** Close the API connection, if this transport opened it. */
+  close(): void;
+}

package/dist/bluetooth/esphome.d.mts

@@ -0,0 +1,83 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.mjs";
+export interface EsphomeAdvertisement {
+  address: number;
+  addressType?: number;
+  name?: string;
+  rssi?: number;
+}
+export interface EsphomeConnectionState {
+  address: number;
+  connected: boolean;
+  mtu: number;
+  error: number;
+}
+export interface EsphomeGattDescriptor {
+  uuid?: string;
+  /** Set in place of `uuid` for a short UUID, on API 1.12 and up. */
+  shortUuid?: number;
+  handle: number;
+}
+export interface EsphomeGattCharacteristic extends EsphomeGattDescriptor {
+  descriptorsList: EsphomeGattDescriptor[];
+}
+export interface EsphomeGattService extends EsphomeGattDescriptor {
+  characteristicsList: EsphomeGattCharacteristic[];
+}
+export interface EsphomeGattReply {
+  address: number;
+  handle: number;
+}
+export interface EsphomeGattData extends EsphomeGattReply {
+  data: string;
+}
+/** The parts of the package's `Connection` this adapter uses. */
+export interface EsphomeConnectionLike {
+  connected: boolean;
+  authorized: boolean;
+  connect(): void;
+  disconnect(): void;
+  on(event: string, listener: (...args: any[]) => void): unknown;
+  off(event: string, listener: (...args: any[]) => void): unknown;
+  subscribeBluetoothAdvertisementService(): void;
+  unsubscribeBluetoothAdvertisementService(): void;
+  connectBluetoothDeviceService(address: number, addressType?: number, useCache?: boolean): Promise<unknown>;
+  disconnectBluetoothDeviceService(address: number): Promise<unknown>;
+  listBluetoothGATTServicesService(address: number): Promise<{
+    servicesList: EsphomeGattService[];
+  }>;
+  readBluetoothGATTCharacteristicService(address: number, handle: number): Promise<EsphomeGattData>;
+  writeBluetoothGATTCharacteristicService(address: number, handle: number, value: Uint8Array, response?: boolean): Promise<EsphomeGattReply>;
+  notifyBluetoothGATTCharacteristicService(address: number, handle: number): Promise<unknown>;
+  writeBluetoothGATTDescriptorService(address: number, handle: number, value: Uint8Array): Promise<void>;
+}
+export type EsphomeBleTransportOptions = {
+  /** A `Connection` you own. This adapter never closes it. */
+  connection: EsphomeConnectionLike;
+} | {
+  /** The proxy's address. `@2colors/esphome-native-api` loads on first use. */
+  host: string;
+  /** Defaults to the package's 6053. */
+  port?: number;
+  /** The proxy's Noise key, base64. Never logged. */
+  encryptionKey?: string;
+  password?: string;
+};
+export declare class EsphomeBleTransport implements BleTransport {
+  private readonly options;
+  private proxy;
+  private readonly ownsProxy;
+  private readonly scans;
+  private readonly claims;
+  /** A proxy refuses a connect with no address type, and only an advertisement carries it. */
+  private readonly addressTypes;
+  constructor(options: EsphomeBleTransportOptions);
+  /** The API connection, up and authorized. */
+  private ready;
+  private buildProxy;
+  scan({ timeoutMs, matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Listen to advertisements until `done` accepts a device or the window ends. A proxy filters nothing. */
+  private listen;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+  /** Close the API connection, if this transport opened it. */
+  close(): void;
+}