tesla-fleet-api 0.4.0 → 0.5.0

package/dist/bluetooth/streamglue.d.mts

@@ -0,0 +1,37 @@
+import { Clock, FieldPath, ObservationSink, Publisher, Unsubscribe } from "../funnel.mjs";
+import { BroadcastListeners } from "./broadcast.mjs";
+/**
+ * What the glue feeds. Structurally a Teslemetry stream's `ingest`: no stream
+ * package is imported here, so a sink can be anything with this method.
+ */
+export interface StreamSink {
+  ingest(data: Record<string, unknown>, metadata?: Record<string, unknown>): unknown;
+}
+export declare const GEAR_STATES: ReadonlyMap<number, string>;
+export declare const TONNEAU_POSITION_STATES: ReadonlyMap<number, string>;
+/**
+ * Feeds a vehicle's broadcasts into a stream-shaped sink, so a Bluetooth reading
+ * reaches the listeners a native stream event does. There is no source ranking:
+ * every call reaches them in arrival order.
+ */
+export declare class BleBroadcastStreamGlue {
+  #private;
+  constructor(vehicle: BroadcastListeners, sink: StreamSink);
+  /** Stop listening. Safe to call twice. */
+  stop(): void;
+}
+/**
+ * Publishes VCSEC status broadcasts to an `ObservationFunnel`. Registration only:
+ * a dropped session ends the broadcasts and says nothing about the fields, so it
+ * publishes nothing.
+ */
+export declare class BleBroadcastPublisher implements Publisher {
+  #private;
+  readonly paths: ReadonlySet<FieldPath>;
+  constructor(vehicle: BroadcastListeners, options?: {
+    clock?: Clock;
+  });
+  attach(sink: ObservationSink): Unsubscribe;
+  request(paths: ReadonlySet<FieldPath>): void;
+  release(paths: ReadonlySet<FieldPath>): void;
+}

package/dist/bluetooth/streamglue.mjs

@@ -0,0 +1,154 @@
+import { CLOSURE_STATES, FieldPath, LOCK_STATES } from "../funnel.mjs";
+import { ClosureStateE, GearE, closureStateEToJSON, gearEToJSON, vehicleLockStateEToJSON } from "@teslemetry/tesla-protocol/command/vcsec";
+// src/bluetooth/streamglue.ts
+const GEAR_STATES = /* @__PURE__ */ new Map([
+	[GearE.GEAR_PARK, "ShiftStateP"],
+	[GearE.GEAR_DRIVE, "ShiftStateD"],
+	[GearE.GEAR_REVERSE, "ShiftStateR"],
+	[GearE.GEAR_NEUTRAL, "ShiftStateN"]
+]);
+const TONNEAU_POSITION_STATES = /* @__PURE__ */ new Map([
+	[ClosureStateE.CLOSURESTATE_CLOSED, "TonneauPositionStateClosed"],
+	[ClosureStateE.CLOSURESTATE_OPEN, "TonneauPositionStateFullyOpen"],
+	[ClosureStateE.CLOSURESTATE_AJAR, "TonneauPositionStatePartiallyOpen"]
+]);
+/** A closure state's name, or the bare number for one this build has no name for. */
+function closureName(state) {
+	const name = closureStateEToJSON(state);
+	return name === "UNRECOGNIZED" ? String(state) : name;
+}
+/**
+* Feeds a vehicle's broadcasts into a stream-shaped sink, so a Bluetooth reading
+* reaches the listeners a native stream event does. There is no source ranking:
+* every call reaches them in arrival order.
+*/
+var BleBroadcastStreamGlue = class {
+	#sink;
+	#unsubscribes;
+	constructor(vehicle, sink) {
+		this.#sink = sink;
+		this.#unsubscribes = [
+			vehicle.listen_vehicle_lock_state((state) => this.#onLockState(state)),
+			vehicle.listen_charge_port((state) => this.#onChargePort(state)),
+			vehicle.listen_closure_statuses((closures) => this.#onClosures(closures)),
+			vehicle.listen_gear((gear) => this.#onGear(gear)),
+			vehicle.listen_tonneau((state) => this.#onTonneau(state)),
+			vehicle.listen_tonneau_percent_open((percent) => this.#sink.ingest({ TonneauOpenPercent: percent }, { source: "bluetooth" }))
+		];
+	}
+	/** Stop listening. Safe to call twice. */
+	stop() {
+		for (const unsubscribe of this.#unsubscribes) unsubscribe();
+		this.#unsubscribes = [];
+	}
+	#onLockState(state) {
+		const locked = LOCK_STATES.get(state);
+		if (locked !== void 0) this.#sink.ingest({ Locked: locked }, {
+			source: "bluetooth",
+			raw: vehicleLockStateEToJSON(state)
+		});
+	}
+	#onChargePort(state) {
+		const open = CLOSURE_STATES.get(state);
+		if (open !== void 0) this.#sink.ingest({ ChargePortDoorOpen: open }, {
+			source: "bluetooth",
+			raw: closureStateEToJSON(state)
+		});
+	}
+	/**
+	* Every door listener fires on any `DoorState` event and reads its own key, so
+	* a leaf sent alone would reach the other five as missing. All six go in one
+	* event, as a native event's do, with a leaf in an unmapped state left out.
+	*/
+	#onClosures(closures) {
+		const raw = {
+			DriverFront: closures.frontDriverDoor,
+			PassengerFront: closures.frontPassengerDoor,
+			DriverRear: closures.rearDriverDoor,
+			PassengerRear: closures.rearPassengerDoor,
+			TrunkFront: closures.frontTrunk,
+			TrunkRear: closures.rearTrunk
+		};
+		const leaves = Object.entries(raw);
+		const doorState = leaves.flatMap(([key, state]) => {
+			const open = CLOSURE_STATES.get(state);
+			return open === void 0 ? [] : [[key, open]];
+		});
+		if (doorState.length > 0) this.#sink.ingest({ DoorState: Object.fromEntries(doorState) }, {
+			source: "bluetooth",
+			raw: Object.fromEntries(leaves.map(([key, state]) => [key, closureName(state)]))
+		});
+	}
+	#onGear(gear) {
+		const state = GEAR_STATES.get(gear);
+		if (state !== void 0) this.#sink.ingest({ Gear: state }, {
+			source: "bluetooth",
+			raw: gearEToJSON(gear)
+		});
+	}
+	#onTonneau(state) {
+		const position = TONNEAU_POSITION_STATES.get(state);
+		if (position !== void 0) this.#sink.ingest({ TonneauPosition: position }, {
+			source: "bluetooth",
+			raw: closureStateEToJSON(state)
+		});
+	}
+};
+/** The map and listener behind each field a broadcast carries. */
+const BROADCAST_FIELDS = /* @__PURE__ */ new Map([
+	[FieldPath.LOCKED, {
+		states: LOCK_STATES,
+		listen: (vehicle, callback) => vehicle.listen_vehicle_lock_state(callback)
+	}],
+	[FieldPath.CHARGE_PORT_DOOR_OPEN, {
+		states: CLOSURE_STATES,
+		listen: (vehicle, callback) => vehicle.listen_charge_port(callback)
+	}],
+	[FieldPath.DOOR_STATE_TRUNK_FRONT, {
+		states: CLOSURE_STATES,
+		listen: (vehicle, callback) => vehicle.listen_front_trunk(callback)
+	}]
+]);
+/**
+* Publishes VCSEC status broadcasts to an `ObservationFunnel`. Registration only:
+* a dropped session ends the broadcasts and says nothing about the fields, so it
+* publishes nothing.
+*/
+var BleBroadcastPublisher = class {
+	paths = new Set(BROADCAST_FIELDS.keys());
+	#vehicle;
+	#clock;
+	#subscriptions = /* @__PURE__ */ new Map();
+	#sink = null;
+	constructor(vehicle, options = {}) {
+		this.#vehicle = vehicle;
+		this.#clock = options.clock ?? (() => performance.now() / 1e3);
+	}
+	attach(sink) {
+		this.#sink = sink;
+		return () => {
+			this.release(new Set(this.#subscriptions.keys()));
+			this.#sink = null;
+		};
+	}
+	request(paths) {
+		for (const path of paths) {
+			const field = BROADCAST_FIELDS.get(path);
+			if (field && !this.#subscriptions.has(path)) this.#subscriptions.set(path, field.listen(this.#vehicle, (state) => {
+				const value = field.states.get(state);
+				if (value !== void 0) this.#sink?.publish({
+					path,
+					value,
+					observed_at: this.#clock()
+				});
+			}));
+		}
+	}
+	release(paths) {
+		for (const path of paths) {
+			this.#subscriptions.get(path)?.();
+			this.#subscriptions.delete(path);
+		}
+	}
+};
+export { BleBroadcastPublisher, BleBroadcastStreamGlue, GEAR_STATES, TONNEAU_POSITION_STATES };

package/dist/bluetooth/teslabluetooth.cjs

@@ -0,0 +1,67 @@
+const require_exceptions = require("../exceptions.cjs");
+const require_teslafleetapi = require("../teslafleetapi.cjs");
+const require_vehicle = require("../vehicle.cjs");
+const require_names = require("./names.cjs");
+const require_vehiclebluetooth = require("./vehiclebluetooth.cjs");
+// src/bluetooth/teslabluetooth.ts
+/**
+* The vehicles of a `TeslaBluetooth`. `createBluetooth` lives here, not on the
+* root `Vehicle`, so the root entry never loads Bluetooth code.
+*/
+var VehiclesBluetooth = class extends require_vehicle.default {
+	/** Class `createBluetooth` instantiates; a subclass overrides it to supply its own vehicle type. */
+	static Bluetooth = require_vehiclebluetooth.default;
+	/** Same as `createBluetooth`, under Python's other name. */
+	create(vin, options) {
+		return this.createBluetooth(vin, options);
+	}
+	/** Creates a vehicle reached over Bluetooth through `options.transport`. */
+	createBluetooth(vin, options) {
+		const vehicle = new this.constructor.Bluetooth(this, vin, options);
+		this.byVin.set(vin, vehicle);
+		return vehicle;
+	}
+};
+/**
+* A client with no cloud behind it, for vehicles reached only over Bluetooth.
+* Every REST path raises `BluetoothCloudUnavailableError` before any I/O, so a
+* REST method a vehicle inherits fails clearly, sends nothing, and is safe for
+* a router to fail over on. A cloud client that wants the same key on both
+* paths uses `new VehicleBluetooth(client.vehicles, vin, options)` instead.
+*/
+var TeslaBluetooth = class extends require_teslafleetapi.default {
+	static Vehicles = VehiclesBluetooth;
+	_transport_name = "bluetooth";
+	constructor(options = {}) {
+		super({
+			server: "bluetooth://local",
+			chargingScope: false,
+			energyScope: false,
+			partnerScope: false,
+			userScope: false,
+			debug: options.debug,
+			logger: options.logger
+		});
+		this.private_key = options.privateKey ?? null;
+	}
+	async _request() {
+		throw new require_exceptions.BluetoothCloudUnavailableError();
+	}
+	async _fetch() {
+		throw new require_exceptions.BluetoothCloudUnavailableError();
+	}
+	/** Whether a BLE device name is a valid Tesla vehicle's. */
+	valid_name(name) {
+		return require_names.valid_name(name);
+	}
+	/** The BLE device name of a vehicle. */
+	get_name(vin) {
+		return require_names.get_name(vin);
+	}
+	/** Whether an advertised name belongs to this VIN, with any valid suffix. */
+	name_matches_vin(advertised, vin) {
+		return require_names.name_matches_vin(advertised, vin);
+	}
+};
+exports.VehiclesBluetooth = VehiclesBluetooth;
+exports.default = TeslaBluetooth;

package/dist/bluetooth/teslabluetooth.d.cts

@@ -0,0 +1,41 @@
+import { Logger } from "../log.cjs";
+import TeslaFleetApi from "../teslafleetapi.cjs";
+import Vehicle from "../vehicle.cjs";
+import VehicleBluetooth, { VehicleBluetoothOptions } from "./vehiclebluetooth.cjs";
+/**
+ * The vehicles of a `TeslaBluetooth`. `createBluetooth` lives here, not on the
+ * root `Vehicle`, so the root entry never loads Bluetooth code.
+ */
+export declare class VehiclesBluetooth extends Vehicle {
+  /** Class `createBluetooth` instantiates; a subclass overrides it to supply its own vehicle type. */
+  static Bluetooth: new (parent: Vehicle, vin: string, options: VehicleBluetoothOptions) => VehicleBluetooth;
+  /** Same as `createBluetooth`, under Python's other name. */
+  create(vin: string, options: VehicleBluetoothOptions): VehicleBluetooth;
+  /** Creates a vehicle reached over Bluetooth through `options.transport`. */
+  createBluetooth(vin: string, options: VehicleBluetoothOptions): VehicleBluetooth;
+}
+/**
+ * A client with no cloud behind it, for vehicles reached only over Bluetooth.
+ * Every REST path raises `BluetoothCloudUnavailableError` before any I/O, so a
+ * REST method a vehicle inherits fails clearly, sends nothing, and is safe for
+ * a router to fail over on. A cloud client that wants the same key on both
+ * paths uses `new VehicleBluetooth(client.vehicles, vin, options)` instead.
+ */
+export default class TeslaBluetooth extends TeslaFleetApi {
+  static Vehicles: new (parent: TeslaFleetApi) => Vehicle;
+  vehicles: VehiclesBluetooth;
+  readonly _transport_name: string;
+  constructor(options?: {
+    privateKey?: Buffer;
+    debug?: boolean;
+    logger?: Logger;
+  });
+  _request(): Promise<never>;
+  protected _fetch(): Promise<never>;
+  /** Whether a BLE device name is a valid Tesla vehicle's. */
+  valid_name(name: string): boolean;
+  /** The BLE device name of a vehicle. */
+  get_name(vin: string): string;
+  /** Whether an advertised name belongs to this VIN, with any valid suffix. */
+  name_matches_vin(advertised: string, vin: string): boolean;
+}

package/dist/bluetooth/teslabluetooth.d.mts

@@ -0,0 +1,41 @@
+import { Logger } from "../log.mjs";
+import TeslaFleetApi from "../teslafleetapi.mjs";
+import Vehicle from "../vehicle.mjs";
+import VehicleBluetooth, { VehicleBluetoothOptions } from "./vehiclebluetooth.mjs";
+/**
+ * The vehicles of a `TeslaBluetooth`. `createBluetooth` lives here, not on the
+ * root `Vehicle`, so the root entry never loads Bluetooth code.
+ */
+export declare class VehiclesBluetooth extends Vehicle {
+  /** Class `createBluetooth` instantiates; a subclass overrides it to supply its own vehicle type. */
+  static Bluetooth: new (parent: Vehicle, vin: string, options: VehicleBluetoothOptions) => VehicleBluetooth;
+  /** Same as `createBluetooth`, under Python's other name. */
+  create(vin: string, options: VehicleBluetoothOptions): VehicleBluetooth;
+  /** Creates a vehicle reached over Bluetooth through `options.transport`. */
+  createBluetooth(vin: string, options: VehicleBluetoothOptions): VehicleBluetooth;
+}
+/**
+ * A client with no cloud behind it, for vehicles reached only over Bluetooth.
+ * Every REST path raises `BluetoothCloudUnavailableError` before any I/O, so a
+ * REST method a vehicle inherits fails clearly, sends nothing, and is safe for
+ * a router to fail over on. A cloud client that wants the same key on both
+ * paths uses `new VehicleBluetooth(client.vehicles, vin, options)` instead.
+ */
+export default class TeslaBluetooth extends TeslaFleetApi {
+  static Vehicles: new (parent: TeslaFleetApi) => Vehicle;
+  vehicles: VehiclesBluetooth;
+  readonly _transport_name: string;
+  constructor(options?: {
+    privateKey?: Buffer;
+    debug?: boolean;
+    logger?: Logger;
+  });
+  _request(): Promise<never>;
+  protected _fetch(): Promise<never>;
+  /** Whether a BLE device name is a valid Tesla vehicle's. */
+  valid_name(name: string): boolean;
+  /** The BLE device name of a vehicle. */
+  get_name(vin: string): string;
+  /** Whether an advertised name belongs to this VIN, with any valid suffix. */
+  name_matches_vin(advertised: string, vin: string): boolean;
+}

package/dist/bluetooth/teslabluetooth.mjs

@@ -0,0 +1,66 @@
+import { BluetoothCloudUnavailableError } from "../exceptions.mjs";
+import TeslaFleetApi from "../teslafleetapi.mjs";
+import Vehicle from "../vehicle.mjs";
+import { get_name, name_matches_vin, valid_name } from "./names.mjs";
+import VehicleBluetooth from "./vehiclebluetooth.mjs";
+// src/bluetooth/teslabluetooth.ts
+/**
+* The vehicles of a `TeslaBluetooth`. `createBluetooth` lives here, not on the
+* root `Vehicle`, so the root entry never loads Bluetooth code.
+*/
+var VehiclesBluetooth = class extends Vehicle {
+	/** Class `createBluetooth` instantiates; a subclass overrides it to supply its own vehicle type. */
+	static Bluetooth = VehicleBluetooth;
+	/** Same as `createBluetooth`, under Python's other name. */
+	create(vin, options) {
+		return this.createBluetooth(vin, options);
+	}
+	/** Creates a vehicle reached over Bluetooth through `options.transport`. */
+	createBluetooth(vin, options) {
+		const vehicle = new this.constructor.Bluetooth(this, vin, options);
+		this.byVin.set(vin, vehicle);
+		return vehicle;
+	}
+};
+/**
+* A client with no cloud behind it, for vehicles reached only over Bluetooth.
+* Every REST path raises `BluetoothCloudUnavailableError` before any I/O, so a
+* REST method a vehicle inherits fails clearly, sends nothing, and is safe for
+* a router to fail over on. A cloud client that wants the same key on both
+* paths uses `new VehicleBluetooth(client.vehicles, vin, options)` instead.
+*/
+var TeslaBluetooth = class extends TeslaFleetApi {
+	static Vehicles = VehiclesBluetooth;
+	_transport_name = "bluetooth";
+	constructor(options = {}) {
+		super({
+			server: "bluetooth://local",
+			chargingScope: false,
+			energyScope: false,
+			partnerScope: false,
+			userScope: false,
+			debug: options.debug,
+			logger: options.logger
+		});
+		this.private_key = options.privateKey ?? null;
+	}
+	async _request() {
+		throw new BluetoothCloudUnavailableError();
+	}
+	async _fetch() {
+		throw new BluetoothCloudUnavailableError();
+	}
+	/** Whether a BLE device name is a valid Tesla vehicle's. */
+	valid_name(name) {
+		return valid_name(name);
+	}
+	/** The BLE device name of a vehicle. */
+	get_name(vin) {
+		return get_name(vin);
+	}
+	/** Whether an advertised name belongs to this VIN, with any valid suffix. */
+	name_matches_vin(advertised, vin) {
+		return name_matches_vin(advertised, vin);
+	}
+};
+export { VehiclesBluetooth, TeslaBluetooth as default };

package/dist/bluetooth/transport.cjs

@@ -0,0 +1,10 @@
+// src/bluetooth/transport.ts
+/**
+* Thrown by an adapter only when bytes provably never entered the BLE stack,
+* such as an unresolved characteristic, or a link the backend reports down
+* before the call. A router can then safely replay the command elsewhere.
+*/
+var BleNotSubmittedError = class extends Error {
+	name = "BleNotSubmittedError";
+};
+exports.BleNotSubmittedError = BleNotSubmittedError;

package/dist/bluetooth/transport.d.cts

@@ -0,0 +1,95 @@
+/**
+ * The seam between the library and a Bluetooth backend.
+ *
+ * The library owns framing, reassembly, signing, sessions, retries, keepalive
+ * and confirmation. An adapter owns raw GATT and holds no Tesla logic but the
+ * UUIDs, which it imports. Around every adapter the library adds one call at a
+ * time per connection, a timeout on every call, frame chunking and link-loss
+ * handling, so an adapter needs none of them. This file imports no backend,
+ * and neither does anything else in `./bluetooth`.
+ *
+ * The contract asks only for what the weakest backend, Homey, can do:
+ *
+ * - `scan` may take a fixed window and ignore `timeoutMs`. Homey's `discover()`
+ *   takes no filter and scans for about 5 s, whatever it is asked. The library
+ *   filters what comes back, so an adapter may return all it saw.
+ * - `connect` needs no timeout of its own, and Homey has none. The library
+ *   abandons a hung attempt, and closes the connection if it arrives later.
+ * - `write` is always with response, the only mode Homey offers and the only
+ *   one the vehicle takes.
+ * - `maxWriteSize` may be left out when the backend hides its MTU. The library
+ *   then writes `DEFAULT_MAX_WRITE_SIZE` bytes at a time.
+ * - `isConnected` and `onDisconnect` may both lie: Homey's state goes stale on
+ *   a silent drop, and its event is not guaranteed. Neither has to be right,
+ *   since a failed or timed-out operation is what the library treats as a dead
+ *   link. A rejection with `BleNotSubmittedError` is the exception.
+ *
+ * Adapter rules, each worth a test in the adapter's own suite:
+ *
+ * 1. Never scan with a service filter, because the vehicle advertises none.
+ *    Scan actively where the backend has a choice: the name is in the scan
+ *    response.
+ * 2. `connect` resolves only once the notify subscription is confirmed, as a
+ *    reply sent before that is lost.
+ * 3. `connect` closes a half-open link before it rejects. The vehicle has
+ *    three connection slots.
+ * 4. Subscribe again on every connect. Subscriptions end with the link.
+ * 5. `write` is always with response.
+ * 6. Throw `BleNotSubmittedError` only when the failure is provably before any
+ *    radio I/O, as a read of a characteristic that was never resolved is on a
+ *    stack that hides Generic Access. It leaves the link up. All other failures
+ *    stay plain errors, and the library treats them as a lost link.
+ * 7. Pass notifications unchanged and in order. The library copies them, so a
+ *    reused backend buffer is safe once the handler returns.
+ * 8. Do not retry writes. A retry can run a command twice.
+ * 9. `disconnect` is safe to call twice, and on a dead link.
+ */
+/** Named characteristics, so an adapter resolves service and UUID its own way. */
+export type BleCharacteristic = "version" | "deviceName" | "appearance";
+/** A found vehicle. `id` is opaque: a Homey peripheral uuid, a MAC, a browser device id. */
+export interface BleDeviceRef {
+  id: string;
+  name?: string;
+  rssi?: number;
+  /** `false` means the vehicle already holds its maximum BLE connections. */
+  connectable?: boolean;
+}
+export interface BleLinkHandlers {
+  /** One notification, unchanged and in arrival order. */
+  onNotify(chunk: Uint8Array): void;
+  /** Best effort, and a faster signal only. The library also treats a failed operation as a lost link. */
+  onDisconnect(): void;
+}
+export interface BleConnection {
+  /** The adapter's best knowledge. It may be stale. */
+  readonly isConnected: boolean;
+  /**
+   * Largest bytes per write. `null` means the backend accepts a full frame.
+   * Left out, the library uses `DEFAULT_MAX_WRITE_SIZE`.
+   */
+  readonly maxWriteSize?: number | null;
+  /** One write-with-response to the vehicle write characteristic. Resolves on the ATT response. */
+  write(data: Uint8Array): Promise<void>;
+  read(characteristic: BleCharacteristic): Promise<Uint8Array>;
+  disconnect(): Promise<void>;
+}
+export interface BleScanOptions {
+  /** How long the library will wait. A backend with a fixed scan window may ignore it. */
+  timeoutMs: number;
+  /** Tells an adapter which name it can stop scanning for. */
+  matches?: (name: string) => boolean;
+}
+export interface BleTransport {
+  /** Active, unfiltered scan. Resolves once a match is found, or when the scan ends with what was seen. */
+  scan(options: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Connect, discover, subscribe to notify. Resolves only when notifications are live. */
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}
+/**
+ * Thrown by an adapter only when bytes provably never entered the BLE stack,
+ * such as an unresolved characteristic, or a link the backend reports down
+ * before the call. A router can then safely replay the command elsewhere.
+ */
+export declare class BleNotSubmittedError extends Error {
+  readonly name = "BleNotSubmittedError";
+}

package/dist/bluetooth/transport.d.mts

@@ -0,0 +1,95 @@
+/**
+ * The seam between the library and a Bluetooth backend.
+ *
+ * The library owns framing, reassembly, signing, sessions, retries, keepalive
+ * and confirmation. An adapter owns raw GATT and holds no Tesla logic but the
+ * UUIDs, which it imports. Around every adapter the library adds one call at a
+ * time per connection, a timeout on every call, frame chunking and link-loss
+ * handling, so an adapter needs none of them. This file imports no backend,
+ * and neither does anything else in `./bluetooth`.
+ *
+ * The contract asks only for what the weakest backend, Homey, can do:
+ *
+ * - `scan` may take a fixed window and ignore `timeoutMs`. Homey's `discover()`
+ *   takes no filter and scans for about 5 s, whatever it is asked. The library
+ *   filters what comes back, so an adapter may return all it saw.
+ * - `connect` needs no timeout of its own, and Homey has none. The library
+ *   abandons a hung attempt, and closes the connection if it arrives later.
+ * - `write` is always with response, the only mode Homey offers and the only
+ *   one the vehicle takes.
+ * - `maxWriteSize` may be left out when the backend hides its MTU. The library
+ *   then writes `DEFAULT_MAX_WRITE_SIZE` bytes at a time.
+ * - `isConnected` and `onDisconnect` may both lie: Homey's state goes stale on
+ *   a silent drop, and its event is not guaranteed. Neither has to be right,
+ *   since a failed or timed-out operation is what the library treats as a dead
+ *   link. A rejection with `BleNotSubmittedError` is the exception.
+ *
+ * Adapter rules, each worth a test in the adapter's own suite:
+ *
+ * 1. Never scan with a service filter, because the vehicle advertises none.
+ *    Scan actively where the backend has a choice: the name is in the scan
+ *    response.
+ * 2. `connect` resolves only once the notify subscription is confirmed, as a
+ *    reply sent before that is lost.
+ * 3. `connect` closes a half-open link before it rejects. The vehicle has
+ *    three connection slots.
+ * 4. Subscribe again on every connect. Subscriptions end with the link.
+ * 5. `write` is always with response.
+ * 6. Throw `BleNotSubmittedError` only when the failure is provably before any
+ *    radio I/O, as a read of a characteristic that was never resolved is on a
+ *    stack that hides Generic Access. It leaves the link up. All other failures
+ *    stay plain errors, and the library treats them as a lost link.
+ * 7. Pass notifications unchanged and in order. The library copies them, so a
+ *    reused backend buffer is safe once the handler returns.
+ * 8. Do not retry writes. A retry can run a command twice.
+ * 9. `disconnect` is safe to call twice, and on a dead link.
+ */
+/** Named characteristics, so an adapter resolves service and UUID its own way. */
+export type BleCharacteristic = "version" | "deviceName" | "appearance";
+/** A found vehicle. `id` is opaque: a Homey peripheral uuid, a MAC, a browser device id. */
+export interface BleDeviceRef {
+  id: string;
+  name?: string;
+  rssi?: number;
+  /** `false` means the vehicle already holds its maximum BLE connections. */
+  connectable?: boolean;
+}
+export interface BleLinkHandlers {
+  /** One notification, unchanged and in arrival order. */
+  onNotify(chunk: Uint8Array): void;
+  /** Best effort, and a faster signal only. The library also treats a failed operation as a lost link. */
+  onDisconnect(): void;
+}
+export interface BleConnection {
+  /** The adapter's best knowledge. It may be stale. */
+  readonly isConnected: boolean;
+  /**
+   * Largest bytes per write. `null` means the backend accepts a full frame.
+   * Left out, the library uses `DEFAULT_MAX_WRITE_SIZE`.
+   */
+  readonly maxWriteSize?: number | null;
+  /** One write-with-response to the vehicle write characteristic. Resolves on the ATT response. */
+  write(data: Uint8Array): Promise<void>;
+  read(characteristic: BleCharacteristic): Promise<Uint8Array>;
+  disconnect(): Promise<void>;
+}
+export interface BleScanOptions {
+  /** How long the library will wait. A backend with a fixed scan window may ignore it. */
+  timeoutMs: number;
+  /** Tells an adapter which name it can stop scanning for. */
+  matches?: (name: string) => boolean;
+}
+export interface BleTransport {
+  /** Active, unfiltered scan. Resolves once a match is found, or when the scan ends with what was seen. */
+  scan(options: BleScanOptions): Promise<BleDeviceRef[]>;
+  /** Connect, discover, subscribe to notify. Resolves only when notifications are live. */
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}
+/**
+ * Thrown by an adapter only when bytes provably never entered the BLE stack,
+ * such as an unresolved characteristic, or a link the backend reports down
+ * before the call. A router can then safely replay the command elsewhere.
+ */
+export declare class BleNotSubmittedError extends Error {
+  readonly name = "BleNotSubmittedError";
+}

package/dist/bluetooth/transport.mjs

@@ -0,0 +1,10 @@
+// src/bluetooth/transport.ts
+/**
+* Thrown by an adapter only when bytes provably never entered the BLE stack,
+* such as an unresolved characteristic, or a link the backend reports down
+* before the call. A router can then safely replay the command elsewhere.
+*/
+var BleNotSubmittedError = class extends Error {
+	name = "BleNotSubmittedError";
+};
+export { BleNotSubmittedError };