tesla-fleet-api 0.4.0 → 0.5.0

package/dist/router/base.cjs

@@ -0,0 +1,203 @@
+const require_exceptions = require("../exceptions.cjs");
+// src/router/base.ts
+/**
+* Failures in one backend's own path, before the device judged the command, so
+* the next backend (a different path to the same device) may still succeed.
+* Anything else, typically the device answering and refusing, propagates: the
+* next backend reaches the same device and would get the same answer.
+*/
+const FAILOVER_SAFE_ERRORS = [
+	require_exceptions.TeslaFleetConnectionError,
+	require_exceptions.BluetoothTransportError,
+	require_exceptions.BluetoothTimeout,
+	require_exceptions.BluetoothCommandFailed,
+	require_exceptions.BluetoothCloudUnavailableError,
+	require_exceptions.VehicleOffline,
+	require_exceptions.RateLimited,
+	require_exceptions.InternalServerError,
+	require_exceptions.BadGateway,
+	require_exceptions.ServiceUnavailable,
+	require_exceptions.GatewayTimeout,
+	...require_exceptions.KEY_REJECTED_FAULTS,
+	require_exceptions.SessionInfoAuthenticationFault,
+	require_exceptions.SigningDisabled,
+	require_exceptions.SignedCommandRequired,
+	require_exceptions.TeslaFleetMessageFaultFieldExceedsMTU,
+	require_exceptions.TeslaFleetMessageFaultResponseSizeExceedsMTU,
+	require_exceptions.InvalidToken,
+	require_exceptions.MissingToken,
+	require_exceptions.OAuthExpired,
+	require_exceptions.OAuthInvalid,
+	require_exceptions.LoginRequired,
+	require_exceptions.PaymentRequired,
+	require_exceptions.SubscriptionRequired,
+	require_exceptions.VehicleSubscriptionRequired,
+	require_exceptions.InsufficientCredits,
+	require_exceptions.Forbidden,
+	require_exceptions.InvalidScope
+];
+/**
+* Whether a command that threw `error` may already have executed. The field
+* check is the one that matters across the dual-package hazard: a process that
+* loads this package through both `import` and `require` has two copies of the
+* class, and `instanceof` fails across them.
+*/
+function is_unconfirmed(error) {
+	return error instanceof require_exceptions.BluetoothUnconfirmedCommand || error?.unconfirmed === true;
+}
+/**
+* Whether a call that threw `error` may be retried on the next backend. Accepts
+* any thrown value. A boolean `failover_safe` on the value decides for itself,
+* in both directions, which lets a backend the router cannot import mark its own
+* errors. Otherwise it is safe only as an instance of `FAILOVER_SAFE_ERRORS`.
+*
+* An unconfirmed command is never safe, whatever it is marked. Python's
+* `is_failover_safe` answers true for it (it subclasses `BluetoothTimeout`) and
+* relies on the router checking first; here the predicate is safe to use alone.
+*/
+function is_failover_safe(error) {
+	if (is_unconfirmed(error)) return false;
+	const marker = error?.failover_safe;
+	if (typeof marker === "boolean") return marker;
+	return FAILOVER_SAFE_ERRORS.some((cls) => error instanceof cls);
+}
+/**
+* The names `backend` routes: plain function properties, own or inherited, up
+* to `Object.prototype`. The most-derived property of a name decides, so a
+* subclass that shadows a method with a getter or a value stops it routing.
+* Getters are never invoked, and symbol keys (`Symbol.asyncDispose`) are not
+* seen, so a context manager is not proxied.
+*/
+function methodNames(backend) {
+	const names = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	for (let target = backend; target !== null && target !== Object.prototype; target = Object.getPrototypeOf(target)) for (const name of Object.getOwnPropertyNames(target)) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		if (name === "constructor" || name === "then" || name.startsWith("_")) continue;
+		if (typeof Object.getOwnPropertyDescriptor(target, name)?.value === "function") names.add(name);
+	}
+	return names;
+}
+/**
+* A `TeslaFleetError`'s message is its class's, so it is safe to log. Anything
+* else may hold a secret, so only its type is logged (see `src/log.ts`).
+*/
+function errorText(error) {
+	if (error instanceof require_exceptions.TeslaFleetError) return `${error.name}: ${error.message}`;
+	return error instanceof Error ? error.name : typeof error;
+}
+/**
+* Routes calls across an ordered list of backends, trying each in order.
+*
+* Use {@link VehicleRouter} or `EnergySiteRouter`, which type the routed
+* methods. Methods are derived from the backends' prototypes at construction, so
+* a new backend method is routed with no change here. A name on no backend does
+* not exist. A backend without the method is skipped. A method added to a backend
+* after construction is not routed.
+*
+* Each call is attempted on the backends that have the method. If one throws a
+* value `is_failover_safe` accepts, the same call is retried on the next with
+* the same arguments. Anything else propagates at once. When every backend fails
+* over, the last thrown value is rethrown unchanged, even if it is not an `Error`.
+*
+* **Warning:** a failed call is replayed on the next backend, so a non-idempotent
+* command (`honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails
+* mid-flight, after a backend may have partly applied it, can be double-executed,
+* or executed more than once across a longer chain. This is the accepted tradeoff
+* of per-command failover. Callers that need exactly-once semantics gate dispatch
+* with a health check or call a backend directly.
+*
+* `BluetoothUnconfirmedCommand` is the exception. The command may already have
+* executed, so it propagates at once on any backend in the chain, is never
+* replayed, and never reaches `on_result`.
+*
+* The health check gates the first backend only: when it is false the primary is
+* skipped and the call routes to the rest. There is deliberately no per-backend
+* health matrix.
+*
+* Plain attributes are not routed; read them from `primary` or `backends`. A
+* backend's connection lifecycle is not proxied either.
+*
+* TS `private` methods exist at run time, so they are installed too: the types
+* hide them. `#private` members are unreachable, which keeps a signing key off
+* the router as it is off the backend.
+*/
+var Router = class {
+	backends;
+	#health;
+	#on_result;
+	#logger;
+	constructor(backends, options = {}) {
+		if (backends.length < 2) throw new TypeError("A router needs a primary and a secondary backend.");
+		this.backends = Object.freeze([...backends]);
+		this.#health = options.health;
+		this.#on_result = options.on_result;
+		this.#logger = options.logger;
+		const targets = /* @__PURE__ */ new Map();
+		for (const backend of backends) for (const name of methodNames(backend)) targets.set(name, [...targets.get(name) ?? [], backend]);
+		for (const [name, having] of targets) {
+			if (name in this) continue;
+			Object.defineProperty(this, name, { value: (...args) => this.#dispatch(name, having, args) });
+		}
+	}
+	/** The first backend, tried first when healthy. */
+	get primary() {
+		return this.backends[0];
+	}
+	/** The second backend, tried when the primary is unhealthy or fails. */
+	get secondary() {
+		return this.backends[1];
+	}
+	/** Resolve the health check. With none configured this reports `true`. */
+	async is_healthy() {
+		const health = this.#health;
+		if (health == null) return true;
+		if (typeof health === "boolean") return health;
+		return Boolean(await health());
+	}
+	/** The `key=value` log field naming a backend. */
+	_backend_field(backend) {
+		return `backend=${backend.constructor?.name ?? "Object"}`;
+	}
+	/** `name` on the first backend that has it, for a plain attribute getter. */
+	_first_attribute(name) {
+		return this.backends.find((candidate) => name in candidate)?.[name];
+	}
+	async #dispatch(name, targets, args) {
+		let start = 0;
+		if (this.#health != null && targets.length > 1 && targets[0] === this.backends[0] && !await this.is_healthy()) start = 1;
+		let last;
+		for (const backend of targets.slice(start)) {
+			const field = this._backend_field(backend);
+			let result;
+			try {
+				result = await backend[name](...args);
+			} catch (error) {
+				if (is_unconfirmed(error)) {
+					this.#logger?.debug(`command=${name} ${field} result=unconfirmed error=${errorText(error)}`);
+					throw error;
+				}
+				last = error;
+				this.#logger?.debug(`command=${name} ${field} result=error error=${errorText(error)}`);
+				if (!(this.#on_result ? await this.#on_result(error, backend, name) : is_failover_safe(error))) throw error;
+				continue;
+			}
+			this.#logger?.debug(`command=${name} ${field} result=success`);
+			await this.#on_result?.(null, backend, name);
+			return result;
+		}
+		throw last;
+	}
+};
+var VehicleRouterBase = class extends Router {
+	/** The VIN of the first backend that has one. */
+	get vin() {
+		return this._first_attribute("vin");
+	}
+};
+const VehicleRouter = VehicleRouterBase;
+exports.FAILOVER_SAFE_ERRORS = FAILOVER_SAFE_ERRORS;
+exports.Router = Router;
+exports.VehicleRouter = VehicleRouter;
+exports.is_failover_safe = is_failover_safe;

package/dist/router/base.d.cts

@@ -0,0 +1,112 @@
+import { Logger } from "../log.cjs";
+type MethodKeys<B> = { [K in keyof B]-?: K extends `_${string}` | "then" ? never : B[K] extends ((...args: never[]) => unknown) ? K : never; }[keyof B];
+type AllMethodKeys<B> = B extends unknown ? MethodKeys<B> : never;
+export type MemberOf<B, K extends PropertyKey> = B extends { [P in K]: infer F; } ? F : never;
+type Asynced<F> = F extends ((...args: infer A) => infer R) ? (...args: A) => Promise<Awaited<R>> : never;
+/** Every method of the union `B`. A name on several members must satisfy all their signatures. */
+export type Routed<B> = { [K in AllMethodKeys<B>]: Asynced<MemberOf<B, K>>; };
+/** A primary, a secondary, and any number of further backends, tried in order. */
+export type Backends = readonly [object, object, ...object[]];
+/**
+ * Gates the primary. Omit it to attempt the primary directly and fail over on a
+ * failover-safe error, with no up-front probe.
+ */
+export type HealthCheck = boolean | (() => boolean | Promise<boolean>);
+/**
+ * Called after every dispatched call. On failure, `error` is the thrown value
+ * and the return decides whether failover continues, replacing
+ * `is_failover_safe` in both directions; return `is_failover_safe(error)` to keep
+ * the default policy. On success, `error` is `null` and the return is ignored.
+ * A handler that throws propagates. `BluetoothUnconfirmedCommand` never gets here.
+ */
+export type ResultHandler = (error: unknown, backend: object, method: string) => boolean | Promise<boolean>;
+export interface RouterOptions {
+  health?: HealthCheck | null;
+  on_result?: ResultHandler | null;
+  /** Receives one `command= backend= result=` line per attempted backend. Silent by default. */
+  logger?: Logger;
+}
+/**
+ * Failures in one backend's own path, before the device judged the command, so
+ * the next backend (a different path to the same device) may still succeed.
+ * Anything else, typically the device answering and refusing, propagates: the
+ * next backend reaches the same device and would get the same answer.
+ */
+export declare const FAILOVER_SAFE_ERRORS: readonly (abstract new (...args: never[]) => unknown)[];
+/**
+ * Whether a call that threw `error` may be retried on the next backend. Accepts
+ * any thrown value. A boolean `failover_safe` on the value decides for itself,
+ * in both directions, which lets a backend the router cannot import mark its own
+ * errors. Otherwise it is safe only as an instance of `FAILOVER_SAFE_ERRORS`.
+ *
+ * An unconfirmed command is never safe, whatever it is marked. Python's
+ * `is_failover_safe` answers true for it (it subclasses `BluetoothTimeout`) and
+ * relies on the router checking first; here the predicate is safe to use alone.
+ */
+export declare function is_failover_safe(error: unknown): boolean;
+/**
+ * Routes calls across an ordered list of backends, trying each in order.
+ *
+ * Use {@link VehicleRouter} or `EnergySiteRouter`, which type the routed
+ * methods. Methods are derived from the backends' prototypes at construction, so
+ * a new backend method is routed with no change here. A name on no backend does
+ * not exist. A backend without the method is skipped. A method added to a backend
+ * after construction is not routed.
+ *
+ * Each call is attempted on the backends that have the method. If one throws a
+ * value `is_failover_safe` accepts, the same call is retried on the next with
+ * the same arguments. Anything else propagates at once. When every backend fails
+ * over, the last thrown value is rethrown unchanged, even if it is not an `Error`.
+ *
+ * **Warning:** a failed call is replayed on the next backend, so a non-idempotent
+ * command (`honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails
+ * mid-flight, after a backend may have partly applied it, can be double-executed,
+ * or executed more than once across a longer chain. This is the accepted tradeoff
+ * of per-command failover. Callers that need exactly-once semantics gate dispatch
+ * with a health check or call a backend directly.
+ *
+ * `BluetoothUnconfirmedCommand` is the exception. The command may already have
+ * executed, so it propagates at once on any backend in the chain, is never
+ * replayed, and never reaches `on_result`.
+ *
+ * The health check gates the first backend only: when it is false the primary is
+ * skipped and the call routes to the rest. There is deliberately no per-backend
+ * health matrix.
+ *
+ * Plain attributes are not routed; read them from `primary` or `backends`. A
+ * backend's connection lifecycle is not proxied either.
+ *
+ * TS `private` methods exist at run time, so they are installed too: the types
+ * hide them. `#private` members are unreachable, which keeps a signing key off
+ * the router as it is off the backend.
+ */
+export declare class Router<Bs extends Backends> {
+  #private;
+  readonly backends: Bs;
+  constructor(backends: Bs, options?: RouterOptions);
+  /** The first backend, tried first when healthy. */
+  get primary(): Bs[0];
+  /** The second backend, tried when the primary is unhealthy or fails. */
+  get secondary(): Bs[1];
+  /** Resolve the health check. With none configured this reports `true`. */
+  is_healthy(): Promise<boolean>;
+  /** The `key=value` log field naming a backend. */
+  protected _backend_field(backend: object): string;
+  /** `name` on the first backend that has it, for a plain attribute getter. */
+  protected _first_attribute<K extends string>(name: K): MemberOf<Bs[number], K>;
+}
+declare class VehicleRouterBase<Bs extends Backends> extends Router<Bs> {
+  /** The VIN of the first backend that has one. */
+  get vin(): MemberOf<Bs[number], "vin">;
+}
+/**
+ * A router over vehicles, typically a Bluetooth primary and a cloud fallback.
+ * See {@link Router} for dispatch, failover and the replay warning.
+ *
+ * A same-named method must accept the caller's arguments on every backend that
+ * has it, or the call does not compile: Python only fails at run time. Where two
+ * backends legitimately differ, call `router.primary.x()`.
+ */
+export type VehicleRouter<Bs extends Backends> = VehicleRouterBase<Bs> & Routed<Bs[number]>;
+export declare const VehicleRouter: new <const Bs extends Backends>(backends: Bs, options?: RouterOptions) => VehicleRouter<Bs>;
+export {};

package/dist/router/base.d.mts

@@ -0,0 +1,112 @@
+import { Logger } from "../log.mjs";
+type MethodKeys<B> = { [K in keyof B]-?: K extends `_${string}` | "then" ? never : B[K] extends ((...args: never[]) => unknown) ? K : never; }[keyof B];
+type AllMethodKeys<B> = B extends unknown ? MethodKeys<B> : never;
+export type MemberOf<B, K extends PropertyKey> = B extends { [P in K]: infer F; } ? F : never;
+type Asynced<F> = F extends ((...args: infer A) => infer R) ? (...args: A) => Promise<Awaited<R>> : never;
+/** Every method of the union `B`. A name on several members must satisfy all their signatures. */
+export type Routed<B> = { [K in AllMethodKeys<B>]: Asynced<MemberOf<B, K>>; };
+/** A primary, a secondary, and any number of further backends, tried in order. */
+export type Backends = readonly [object, object, ...object[]];
+/**
+ * Gates the primary. Omit it to attempt the primary directly and fail over on a
+ * failover-safe error, with no up-front probe.
+ */
+export type HealthCheck = boolean | (() => boolean | Promise<boolean>);
+/**
+ * Called after every dispatched call. On failure, `error` is the thrown value
+ * and the return decides whether failover continues, replacing
+ * `is_failover_safe` in both directions; return `is_failover_safe(error)` to keep
+ * the default policy. On success, `error` is `null` and the return is ignored.
+ * A handler that throws propagates. `BluetoothUnconfirmedCommand` never gets here.
+ */
+export type ResultHandler = (error: unknown, backend: object, method: string) => boolean | Promise<boolean>;
+export interface RouterOptions {
+  health?: HealthCheck | null;
+  on_result?: ResultHandler | null;
+  /** Receives one `command= backend= result=` line per attempted backend. Silent by default. */
+  logger?: Logger;
+}
+/**
+ * Failures in one backend's own path, before the device judged the command, so
+ * the next backend (a different path to the same device) may still succeed.
+ * Anything else, typically the device answering and refusing, propagates: the
+ * next backend reaches the same device and would get the same answer.
+ */
+export declare const FAILOVER_SAFE_ERRORS: readonly (abstract new (...args: never[]) => unknown)[];
+/**
+ * Whether a call that threw `error` may be retried on the next backend. Accepts
+ * any thrown value. A boolean `failover_safe` on the value decides for itself,
+ * in both directions, which lets a backend the router cannot import mark its own
+ * errors. Otherwise it is safe only as an instance of `FAILOVER_SAFE_ERRORS`.
+ *
+ * An unconfirmed command is never safe, whatever it is marked. Python's
+ * `is_failover_safe` answers true for it (it subclasses `BluetoothTimeout`) and
+ * relies on the router checking first; here the predicate is safe to use alone.
+ */
+export declare function is_failover_safe(error: unknown): boolean;
+/**
+ * Routes calls across an ordered list of backends, trying each in order.
+ *
+ * Use {@link VehicleRouter} or `EnergySiteRouter`, which type the routed
+ * methods. Methods are derived from the backends' prototypes at construction, so
+ * a new backend method is routed with no change here. A name on no backend does
+ * not exist. A backend without the method is skipped. A method added to a backend
+ * after construction is not routed.
+ *
+ * Each call is attempted on the backends that have the method. If one throws a
+ * value `is_failover_safe` accepts, the same call is retried on the next with
+ * the same arguments. Anything else propagates at once. When every backend fails
+ * over, the last thrown value is rethrown unchanged, even if it is not an `Error`.
+ *
+ * **Warning:** a failed call is replayed on the next backend, so a non-idempotent
+ * command (`honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails
+ * mid-flight, after a backend may have partly applied it, can be double-executed,
+ * or executed more than once across a longer chain. This is the accepted tradeoff
+ * of per-command failover. Callers that need exactly-once semantics gate dispatch
+ * with a health check or call a backend directly.
+ *
+ * `BluetoothUnconfirmedCommand` is the exception. The command may already have
+ * executed, so it propagates at once on any backend in the chain, is never
+ * replayed, and never reaches `on_result`.
+ *
+ * The health check gates the first backend only: when it is false the primary is
+ * skipped and the call routes to the rest. There is deliberately no per-backend
+ * health matrix.
+ *
+ * Plain attributes are not routed; read them from `primary` or `backends`. A
+ * backend's connection lifecycle is not proxied either.
+ *
+ * TS `private` methods exist at run time, so they are installed too: the types
+ * hide them. `#private` members are unreachable, which keeps a signing key off
+ * the router as it is off the backend.
+ */
+export declare class Router<Bs extends Backends> {
+  #private;
+  readonly backends: Bs;
+  constructor(backends: Bs, options?: RouterOptions);
+  /** The first backend, tried first when healthy. */
+  get primary(): Bs[0];
+  /** The second backend, tried when the primary is unhealthy or fails. */
+  get secondary(): Bs[1];
+  /** Resolve the health check. With none configured this reports `true`. */
+  is_healthy(): Promise<boolean>;
+  /** The `key=value` log field naming a backend. */
+  protected _backend_field(backend: object): string;
+  /** `name` on the first backend that has it, for a plain attribute getter. */
+  protected _first_attribute<K extends string>(name: K): MemberOf<Bs[number], K>;
+}
+declare class VehicleRouterBase<Bs extends Backends> extends Router<Bs> {
+  /** The VIN of the first backend that has one. */
+  get vin(): MemberOf<Bs[number], "vin">;
+}
+/**
+ * A router over vehicles, typically a Bluetooth primary and a cloud fallback.
+ * See {@link Router} for dispatch, failover and the replay warning.
+ *
+ * A same-named method must accept the caller's arguments on every backend that
+ * has it, or the call does not compile: Python only fails at run time. Where two
+ * backends legitimately differ, call `router.primary.x()`.
+ */
+export type VehicleRouter<Bs extends Backends> = VehicleRouterBase<Bs> & Routed<Bs[number]>;
+export declare const VehicleRouter: new <const Bs extends Backends>(backends: Bs, options?: RouterOptions) => VehicleRouter<Bs>;
+export {};

package/dist/router/base.mjs

@@ -0,0 +1,200 @@
+import { BadGateway, BluetoothCloudUnavailableError, BluetoothCommandFailed, BluetoothTimeout, BluetoothTransportError, BluetoothUnconfirmedCommand, Forbidden, GatewayTimeout, InsufficientCredits, InternalServerError, InvalidScope, InvalidToken, KEY_REJECTED_FAULTS, LoginRequired, MissingToken, OAuthExpired, OAuthInvalid, PaymentRequired, RateLimited, ServiceUnavailable, SessionInfoAuthenticationFault, SignedCommandRequired, SigningDisabled, SubscriptionRequired, TeslaFleetConnectionError, TeslaFleetError, TeslaFleetMessageFaultFieldExceedsMTU, TeslaFleetMessageFaultResponseSizeExceedsMTU, VehicleOffline, VehicleSubscriptionRequired } from "../exceptions.mjs";
+// src/router/base.ts
+/**
+* Failures in one backend's own path, before the device judged the command, so
+* the next backend (a different path to the same device) may still succeed.
+* Anything else, typically the device answering and refusing, propagates: the
+* next backend reaches the same device and would get the same answer.
+*/
+const FAILOVER_SAFE_ERRORS = [
+	TeslaFleetConnectionError,
+	BluetoothTransportError,
+	BluetoothTimeout,
+	BluetoothCommandFailed,
+	BluetoothCloudUnavailableError,
+	VehicleOffline,
+	RateLimited,
+	InternalServerError,
+	BadGateway,
+	ServiceUnavailable,
+	GatewayTimeout,
+	...KEY_REJECTED_FAULTS,
+	SessionInfoAuthenticationFault,
+	SigningDisabled,
+	SignedCommandRequired,
+	TeslaFleetMessageFaultFieldExceedsMTU,
+	TeslaFleetMessageFaultResponseSizeExceedsMTU,
+	InvalidToken,
+	MissingToken,
+	OAuthExpired,
+	OAuthInvalid,
+	LoginRequired,
+	PaymentRequired,
+	SubscriptionRequired,
+	VehicleSubscriptionRequired,
+	InsufficientCredits,
+	Forbidden,
+	InvalidScope
+];
+/**
+* Whether a command that threw `error` may already have executed. The field
+* check is the one that matters across the dual-package hazard: a process that
+* loads this package through both `import` and `require` has two copies of the
+* class, and `instanceof` fails across them.
+*/
+function is_unconfirmed(error) {
+	return error instanceof BluetoothUnconfirmedCommand || error?.unconfirmed === true;
+}
+/**
+* Whether a call that threw `error` may be retried on the next backend. Accepts
+* any thrown value. A boolean `failover_safe` on the value decides for itself,
+* in both directions, which lets a backend the router cannot import mark its own
+* errors. Otherwise it is safe only as an instance of `FAILOVER_SAFE_ERRORS`.
+*
+* An unconfirmed command is never safe, whatever it is marked. Python's
+* `is_failover_safe` answers true for it (it subclasses `BluetoothTimeout`) and
+* relies on the router checking first; here the predicate is safe to use alone.
+*/
+function is_failover_safe(error) {
+	if (is_unconfirmed(error)) return false;
+	const marker = error?.failover_safe;
+	if (typeof marker === "boolean") return marker;
+	return FAILOVER_SAFE_ERRORS.some((cls) => error instanceof cls);
+}
+/**
+* The names `backend` routes: plain function properties, own or inherited, up
+* to `Object.prototype`. The most-derived property of a name decides, so a
+* subclass that shadows a method with a getter or a value stops it routing.
+* Getters are never invoked, and symbol keys (`Symbol.asyncDispose`) are not
+* seen, so a context manager is not proxied.
+*/
+function methodNames(backend) {
+	const names = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	for (let target = backend; target !== null && target !== Object.prototype; target = Object.getPrototypeOf(target)) for (const name of Object.getOwnPropertyNames(target)) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		if (name === "constructor" || name === "then" || name.startsWith("_")) continue;
+		if (typeof Object.getOwnPropertyDescriptor(target, name)?.value === "function") names.add(name);
+	}
+	return names;
+}
+/**
+* A `TeslaFleetError`'s message is its class's, so it is safe to log. Anything
+* else may hold a secret, so only its type is logged (see `src/log.ts`).
+*/
+function errorText(error) {
+	if (error instanceof TeslaFleetError) return `${error.name}: ${error.message}`;
+	return error instanceof Error ? error.name : typeof error;
+}
+/**
+* Routes calls across an ordered list of backends, trying each in order.
+*
+* Use {@link VehicleRouter} or `EnergySiteRouter`, which type the routed
+* methods. Methods are derived from the backends' prototypes at construction, so
+* a new backend method is routed with no change here. A name on no backend does
+* not exist. A backend without the method is skipped. A method added to a backend
+* after construction is not routed.
+*
+* Each call is attempted on the backends that have the method. If one throws a
+* value `is_failover_safe` accepts, the same call is retried on the next with
+* the same arguments. Anything else propagates at once. When every backend fails
+* over, the last thrown value is rethrown unchanged, even if it is not an `Error`.
+*
+* **Warning:** a failed call is replayed on the next backend, so a non-idempotent
+* command (`honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails
+* mid-flight, after a backend may have partly applied it, can be double-executed,
+* or executed more than once across a longer chain. This is the accepted tradeoff
+* of per-command failover. Callers that need exactly-once semantics gate dispatch
+* with a health check or call a backend directly.
+*
+* `BluetoothUnconfirmedCommand` is the exception. The command may already have
+* executed, so it propagates at once on any backend in the chain, is never
+* replayed, and never reaches `on_result`.
+*
+* The health check gates the first backend only: when it is false the primary is
+* skipped and the call routes to the rest. There is deliberately no per-backend
+* health matrix.
+*
+* Plain attributes are not routed; read them from `primary` or `backends`. A
+* backend's connection lifecycle is not proxied either.
+*
+* TS `private` methods exist at run time, so they are installed too: the types
+* hide them. `#private` members are unreachable, which keeps a signing key off
+* the router as it is off the backend.
+*/
+var Router = class {
+	backends;
+	#health;
+	#on_result;
+	#logger;
+	constructor(backends, options = {}) {
+		if (backends.length < 2) throw new TypeError("A router needs a primary and a secondary backend.");
+		this.backends = Object.freeze([...backends]);
+		this.#health = options.health;
+		this.#on_result = options.on_result;
+		this.#logger = options.logger;
+		const targets = /* @__PURE__ */ new Map();
+		for (const backend of backends) for (const name of methodNames(backend)) targets.set(name, [...targets.get(name) ?? [], backend]);
+		for (const [name, having] of targets) {
+			if (name in this) continue;
+			Object.defineProperty(this, name, { value: (...args) => this.#dispatch(name, having, args) });
+		}
+	}
+	/** The first backend, tried first when healthy. */
+	get primary() {
+		return this.backends[0];
+	}
+	/** The second backend, tried when the primary is unhealthy or fails. */
+	get secondary() {
+		return this.backends[1];
+	}
+	/** Resolve the health check. With none configured this reports `true`. */
+	async is_healthy() {
+		const health = this.#health;
+		if (health == null) return true;
+		if (typeof health === "boolean") return health;
+		return Boolean(await health());
+	}
+	/** The `key=value` log field naming a backend. */
+	_backend_field(backend) {
+		return `backend=${backend.constructor?.name ?? "Object"}`;
+	}
+	/** `name` on the first backend that has it, for a plain attribute getter. */
+	_first_attribute(name) {
+		return this.backends.find((candidate) => name in candidate)?.[name];
+	}
+	async #dispatch(name, targets, args) {
+		let start = 0;
+		if (this.#health != null && targets.length > 1 && targets[0] === this.backends[0] && !await this.is_healthy()) start = 1;
+		let last;
+		for (const backend of targets.slice(start)) {
+			const field = this._backend_field(backend);
+			let result;
+			try {
+				result = await backend[name](...args);
+			} catch (error) {
+				if (is_unconfirmed(error)) {
+					this.#logger?.debug(`command=${name} ${field} result=unconfirmed error=${errorText(error)}`);
+					throw error;
+				}
+				last = error;
+				this.#logger?.debug(`command=${name} ${field} result=error error=${errorText(error)}`);
+				if (!(this.#on_result ? await this.#on_result(error, backend, name) : is_failover_safe(error))) throw error;
+				continue;
+			}
+			this.#logger?.debug(`command=${name} ${field} result=success`);
+			await this.#on_result?.(null, backend, name);
+			return result;
+		}
+		throw last;
+	}
+};
+var VehicleRouterBase = class extends Router {
+	/** The VIN of the first backend that has one. */
+	get vin() {
+		return this._first_attribute("vin");
+	}
+};
+const VehicleRouter = VehicleRouterBase;
+export { FAILOVER_SAFE_ERRORS, Router, VehicleRouter, is_failover_safe };