tesla-fleet-api 0.4.0 → 0.5.0

package/dist/funnel.cjs

@@ -0,0 +1,297 @@
+const require_log = require("./log.cjs");
+let _teslemetry_tesla_protocol_command_vcsec = require("@teslemetry/tesla-protocol/command/vcsec");
+// src/funnel.ts
+/**
+* A canonical routable field, valued to match its public signal name. A compound
+* signal is split into one path per facet, because a broadcast and a
+* `vehicle_data` result each expose individual leaves.
+*/
+const FieldPath = Object.freeze({
+	LOCKED: "Locked",
+	CHARGE_PORT_DOOR_OPEN: "ChargePortDoorOpen",
+	DOOR_STATE_TRUNK_FRONT: "DoorState.TrunkFront"
+});
+function noop() {}
+/**
+* Funnels observations from every attached publisher into one listener set.
+*
+* Many to one: a listener registered for a field receives what any publisher
+* reports for it, in arrival order. There is no source selection, ranking, or
+* health model here, and detaching or silencing a publisher produces no value of
+* its own. The only arbitration, dropping older observations and skipping
+* unchanged values, is hard-coded.
+*/
+var ObservationFunnel = class {
+	#publishers = [];
+	#listeners = /* @__PURE__ */ new Map();
+	#demandObservers = [];
+	#observed = /* @__PURE__ */ new Map();
+	#logger;
+	constructor(options = {}) {
+		this.#logger = options.logger;
+	}
+	/** Attach `publisher` and return its detach closure. */
+	attach(publisher) {
+		const attached = {
+			publisher,
+			detach: noop
+		};
+		this.#publishers.push(attached);
+		attached.detach = publisher.attach(this);
+		const active = this.#activePaths(publisher);
+		if (active.size > 0) publisher.request(active);
+		return () => {
+			const index = this.#publishers.indexOf(attached);
+			if (index === -1) return;
+			this.#publishers.splice(index, 1);
+			const stillActive = this.#activePaths(publisher);
+			if (stillActive.size > 0) publisher.release(stillActive);
+			attached.detach();
+		};
+	}
+	#activePaths(publisher) {
+		return new Set([...publisher.paths].filter((path) => this.#listeners.get(path)?.length));
+	}
+	/** Accept one observation from any publisher and fan it out. */
+	publish(observation) {
+		const { path } = observation;
+		const previous = this.#observed.get(path);
+		if (previous !== void 0 && observation.observed_at < previous.observed_at) return;
+		this.#observed.set(path, observation);
+		if (previous !== void 0 && previous.value === observation.value) return;
+		for (const callback of [...this.#listeners.get(path) ?? []]) {
+			if (this.#observed.get(path) !== observation) return;
+			this.#dispatch(callback, observation.value);
+		}
+	}
+	/**
+	* The last value observed for `path`. Null means there is no reading: either
+	* nothing has ever been observed, or a source reported the field as unavailable.
+	*/
+	value(path) {
+		return this.#observed.get(path)?.value ?? null;
+	}
+	/**
+	* Register a listener for `path`, called on each changed value. The first
+	* listener for a path activates it on every capable publisher; the last one
+	* to leave releases it. Registration dispatches nothing: the value standing at
+	* that moment is `value()`.
+	*/
+	listen(path, callback) {
+		let listeners = this.#listeners.get(path);
+		if (listeners === void 0) {
+			listeners = [];
+			this.#listeners.set(path, listeners);
+		}
+		const registered = listeners;
+		registered.push(callback);
+		if (registered.length === 1) this.#forCapable(path, (publisher, paths) => publisher.request(paths));
+		this.#notifyDemand();
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			registered.splice(registered.indexOf(callback), 1);
+			if (registered.length === 0) this.#forCapable(path, (publisher, paths) => publisher.release(paths));
+			this.#notifyDemand();
+		};
+	}
+	#forCapable(path, action) {
+		const paths = /* @__PURE__ */ new Set([path]);
+		for (const { publisher } of [...this.#publishers]) if (publisher.paths.has(path)) action(publisher, paths);
+	}
+	/**
+	* Observe whether any of `paths` has at least one live listener. Derived from
+	* the activation counts the funnel already keeps. It reports; it never starts
+	* work of its own.
+	*/
+	listen_demand(paths, callback) {
+		const observer = {
+			paths,
+			callback,
+			active: this.#demand(paths)
+		};
+		this.#demandObservers.push(observer);
+		this.#dispatch(callback, observer.active);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const index = this.#demandObservers.indexOf(observer);
+			if (index !== -1) this.#demandObservers.splice(index, 1);
+		};
+	}
+	#demand(paths) {
+		return [...paths].some((path) => this.#listeners.get(path)?.length);
+	}
+	#notifyDemand() {
+		for (const observer of [...this.#demandObservers]) {
+			const active = this.#demand(observer.paths);
+			if (active !== observer.active) {
+				observer.active = active;
+				this.#dispatch(observer.callback, active);
+			}
+		}
+	}
+	/** A listener's error stays with that listener: the rest still hear the value. */
+	#dispatch(callback, value) {
+		try {
+			callback(value);
+		} catch (error) {
+			this.#logger?.debug(`observation funnel listener callback failed error=${require_log.errorText(error)}`);
+		}
+	}
+};
+const LOCK_STATES = /* @__PURE__ */ new Map([
+	[_teslemetry_tesla_protocol_command_vcsec.VehicleLockStateE.VEHICLELOCKSTATE_LOCKED, true],
+	[_teslemetry_tesla_protocol_command_vcsec.VehicleLockStateE.VEHICLELOCKSTATE_UNLOCKED, false],
+	[_teslemetry_tesla_protocol_command_vcsec.VehicleLockStateE.VEHICLELOCKSTATE_INTERNAL_LOCKED, true],
+	[_teslemetry_tesla_protocol_command_vcsec.VehicleLockStateE.VEHICLELOCKSTATE_SELECTIVE_UNLOCKED, false]
+]);
+const CLOSURE_STATES = /* @__PURE__ */ new Map([
+	[_teslemetry_tesla_protocol_command_vcsec.ClosureStateE.CLOSURESTATE_CLOSED, false],
+	[_teslemetry_tesla_protocol_command_vcsec.ClosureStateE.CLOSURESTATE_OPEN, true],
+	[_teslemetry_tesla_protocol_command_vcsec.ClosureStateE.CLOSURESTATE_AJAR, true],
+	[_teslemetry_tesla_protocol_command_vcsec.ClosureStateE.CLOSURESTATE_OPENING, true],
+	[_teslemetry_tesla_protocol_command_vcsec.ClosureStateE.CLOSURESTATE_CLOSING, true]
+]);
+/** `paths` of a passive publisher: every field. */
+const ALL_PATHS = new Set(Object.values(FieldPath));
+const monotonicSeconds = () => performance.now() / 1e3;
+const ABSENT = Symbol("absent");
+function isMapping(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A present leaf, or `ABSENT`: a missing key is not a null reading. */
+function leaf(section, key) {
+	return isMapping(section) && Object.hasOwn(section, key) ? section[key] : ABSENT;
+}
+/** A value usable as a reading: a boolean, or null for an explicit "unavailable". */
+function isReading(value) {
+	return value === null || typeof value === "boolean";
+}
+/**
+* A source whose readings are handed to it as arguments. It holds no client,
+* session, endpoint, or callable able to obtain one, so nothing here can originate
+* a request, and activation subscribes to nothing.
+*/
+var SuppliedPublisher = class {
+	#clock;
+	#sink = null;
+	constructor(options = {}) {
+		this.#clock = options.clock ?? monotonicSeconds;
+	}
+	get paths() {
+		return ALL_PATHS;
+	}
+	attach(sink) {
+		this.#sink = sink;
+		return () => {
+			this.#sink = null;
+		};
+	}
+	request(_paths) {}
+	release(_paths) {}
+	_publish(input, observed_at) {
+		const observations = this._translate(input, observed_at ?? this.#clock());
+		const sink = this.#sink;
+		if (sink !== null) for (const observation of observations) sink.publish(observation);
+		return observations;
+	}
+};
+/** Translates a caller-supplied `vehicle_data` result into observations. */
+var VehicleDataResultPublisher = class extends SuppliedPublisher {
+	/** Translate a supplied result and feed the audited leaves to the sink. */
+	publish_result(result, options = {}) {
+		return this._publish(result, options.observed_at);
+	}
+	_translate(result, observed_at) {
+		const response = leaf(result, "response");
+		const payload = isMapping(response) ? response : result;
+		const vehicle_state = leaf(payload, "vehicle_state");
+		const charge_state = leaf(payload, "charge_state");
+		const observations = [];
+		const locked = leaf(vehicle_state, "locked");
+		if (isReading(locked)) observations.push({
+			path: FieldPath.LOCKED,
+			value: locked,
+			observed_at
+		});
+		const charge_port = leaf(charge_state, "charge_port_door_open");
+		if (isReading(charge_port)) observations.push({
+			path: FieldPath.CHARGE_PORT_DOOR_OPEN,
+			value: charge_port,
+			observed_at
+		});
+		const front_trunk = leaf(vehicle_state, "ft");
+		if (front_trunk === null) observations.push({
+			path: FieldPath.DOOR_STATE_TRUNK_FRONT,
+			value: null,
+			observed_at
+		});
+		else if (front_trunk === 0 || front_trunk === 1) observations.push({
+			path: FieldPath.DOOR_STATE_TRUNK_FRONT,
+			value: front_trunk === 1,
+			observed_at
+		});
+		return observations;
+	}
+};
+/**
+* `"true"` and `"false"` become real booleans; anything else passes through. Some
+* vehicles stream a boolean signal as that literal string even when the stream
+* prefers typed values.
+*/
+function coerceStreamBool(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	return value;
+}
+/**
+* Translates a caller-supplied Teslemetry stream signal update into observations.
+* The update is keyed by signal name the way a stream push is (`Locked`,
+* `ChargePortDoorOpen`, `DoorState` with a nested `TrunkFront`). `@teslemetry/api`
+* owns the stream client; the two meet here.
+*/
+var TeslemetryStreamPublisher = class extends SuppliedPublisher {
+	/** Translate a supplied stream signal update and feed it to the sink. */
+	publish_update(data, options = {}) {
+		return this._publish(data, options.observed_at);
+	}
+	_translate(data, observed_at) {
+		const observations = [];
+		const locked = coerceStreamBool(leaf(data, "Locked"));
+		if (isReading(locked)) observations.push({
+			path: FieldPath.LOCKED,
+			value: locked,
+			observed_at
+		});
+		const charge_port = coerceStreamBool(leaf(data, "ChargePortDoorOpen"));
+		if (isReading(charge_port)) observations.push({
+			path: FieldPath.CHARGE_PORT_DOOR_OPEN,
+			value: charge_port,
+			observed_at
+		});
+		const door_state = leaf(data, "DoorState");
+		if (door_state === null) observations.push({
+			path: FieldPath.DOOR_STATE_TRUNK_FRONT,
+			value: null,
+			observed_at
+		});
+		else if (isMapping(door_state)) {
+			const trunk_front = coerceStreamBool(leaf(door_state, "TrunkFront"));
+			if (isReading(trunk_front)) observations.push({
+				path: FieldPath.DOOR_STATE_TRUNK_FRONT,
+				value: trunk_front,
+				observed_at
+			});
+		}
+		return observations;
+	}
+};
+exports.CLOSURE_STATES = CLOSURE_STATES;
+exports.FieldPath = FieldPath;
+exports.LOCK_STATES = LOCK_STATES;
+exports.ObservationFunnel = ObservationFunnel;
+exports.TeslemetryStreamPublisher = TeslemetryStreamPublisher;
+exports.VehicleDataResultPublisher = VehicleDataResultPublisher;

package/dist/funnel.d.cts

@@ -0,0 +1,118 @@
+import { Logger } from "./log.cjs";
+export type Unsubscribe = () => void;
+/** Seconds off a monotonic clock. */
+export type Clock = () => number;
+/** A reading, or null for a source reporting the field itself as unavailable. */
+export type Value = boolean | null;
+/**
+ * A canonical routable field, valued to match its public signal name. A compound
+ * signal is split into one path per facet, because a broadcast and a
+ * `vehicle_data` result each expose individual leaves.
+ */
+export declare const FieldPath: Readonly<{
+  readonly LOCKED: "Locked";
+  readonly CHARGE_PORT_DOOR_OPEN: "ChargePortDoorOpen";
+  readonly DOOR_STATE_TRUNK_FRONT: "DoorState.TrunkFront";
+}>;
+export type FieldPath = (typeof FieldPath)[keyof typeof FieldPath];
+/** One timestamped value for one field. */
+export interface Observation {
+  readonly path: FieldPath;
+  readonly value: Value;
+  /**
+   * Seconds off one monotonic clock shared by every publisher on a funnel;
+   * observations from different sources are ordered against each other.
+   */
+  readonly observed_at: number;
+}
+/** The handle a publisher is given to feed the funnel. */
+export interface ObservationSink {
+  publish(observation: Observation): void;
+}
+/** A source of observations for one or more canonical fields. */
+export interface Publisher {
+  readonly paths: ReadonlySet<FieldPath>;
+  attach(sink: ObservationSink): Unsubscribe;
+  /** Begin supplying `paths`: subscription accounting, not a data request. */
+  request(paths: ReadonlySet<FieldPath>): void;
+  /** Stop supplying `paths`. */
+  release(paths: ReadonlySet<FieldPath>): void;
+}
+/**
+ * Funnels observations from every attached publisher into one listener set.
+ *
+ * Many to one: a listener registered for a field receives what any publisher
+ * reports for it, in arrival order. There is no source selection, ranking, or
+ * health model here, and detaching or silencing a publisher produces no value of
+ * its own. The only arbitration, dropping older observations and skipping
+ * unchanged values, is hard-coded.
+ */
+export declare class ObservationFunnel implements ObservationSink {
+  #private;
+  constructor(options?: {
+    logger?: Logger;
+  });
+  /** Attach `publisher` and return its detach closure. */
+  attach(publisher: Publisher): Unsubscribe;
+  /** Accept one observation from any publisher and fan it out. */
+  publish(observation: Observation): void;
+  /**
+   * The last value observed for `path`. Null means there is no reading: either
+   * nothing has ever been observed, or a source reported the field as unavailable.
+   */
+  value(path: FieldPath): Value;
+  /**
+   * Register a listener for `path`, called on each changed value. The first
+   * listener for a path activates it on every capable publisher; the last one
+   * to leave releases it. Registration dispatches nothing: the value standing at
+   * that moment is `value()`.
+   */
+  listen(path: FieldPath, callback: (value: Value) => void): Unsubscribe;
+  /**
+   * Observe whether any of `paths` has at least one live listener. Derived from
+   * the activation counts the funnel already keeps. It reports; it never starts
+   * work of its own.
+   */
+  listen_demand(paths: ReadonlySet<FieldPath>, callback: (active: boolean) => void): Unsubscribe;
+}
+export declare const LOCK_STATES: ReadonlyMap<number, boolean>;
+export declare const CLOSURE_STATES: ReadonlyMap<number, boolean>;
+/**
+ * A source whose readings are handed to it as arguments. It holds no client,
+ * session, endpoint, or callable able to obtain one, so nothing here can originate
+ * a request, and activation subscribes to nothing.
+ */
+declare abstract class SuppliedPublisher<Input> implements Publisher {
+  #private;
+  constructor(options?: {
+    clock?: Clock;
+  });
+  get paths(): ReadonlySet<FieldPath>;
+  attach(sink: ObservationSink): Unsubscribe;
+  request(_paths: ReadonlySet<FieldPath>): void;
+  release(_paths: ReadonlySet<FieldPath>): void;
+  protected _publish(input: Input, observed_at: number | undefined): readonly Observation[];
+  protected abstract _translate(input: Input, observed_at: number): Observation[];
+}
+/** Translates a caller-supplied `vehicle_data` result into observations. */
+export declare class VehicleDataResultPublisher extends SuppliedPublisher<unknown> {
+  /** Translate a supplied result and feed the audited leaves to the sink. */
+  publish_result(result: unknown, options?: {
+    observed_at?: number;
+  }): readonly Observation[];
+  protected _translate(result: unknown, observed_at: number): Observation[];
+}
+/**
+ * Translates a caller-supplied Teslemetry stream signal update into observations.
+ * The update is keyed by signal name the way a stream push is (`Locked`,
+ * `ChargePortDoorOpen`, `DoorState` with a nested `TrunkFront`). `@teslemetry/api`
+ * owns the stream client; the two meet here.
+ */
+export declare class TeslemetryStreamPublisher extends SuppliedPublisher<unknown> {
+  /** Translate a supplied stream signal update and feed it to the sink. */
+  publish_update(data: unknown, options?: {
+    observed_at?: number;
+  }): readonly Observation[];
+  protected _translate(data: unknown, observed_at: number): Observation[];
+}
+export {};

package/dist/funnel.d.mts

@@ -0,0 +1,118 @@
+import { Logger } from "./log.mjs";
+export type Unsubscribe = () => void;
+/** Seconds off a monotonic clock. */
+export type Clock = () => number;
+/** A reading, or null for a source reporting the field itself as unavailable. */
+export type Value = boolean | null;
+/**
+ * A canonical routable field, valued to match its public signal name. A compound
+ * signal is split into one path per facet, because a broadcast and a
+ * `vehicle_data` result each expose individual leaves.
+ */
+export declare const FieldPath: Readonly<{
+  readonly LOCKED: "Locked";
+  readonly CHARGE_PORT_DOOR_OPEN: "ChargePortDoorOpen";
+  readonly DOOR_STATE_TRUNK_FRONT: "DoorState.TrunkFront";
+}>;
+export type FieldPath = (typeof FieldPath)[keyof typeof FieldPath];
+/** One timestamped value for one field. */
+export interface Observation {
+  readonly path: FieldPath;
+  readonly value: Value;
+  /**
+   * Seconds off one monotonic clock shared by every publisher on a funnel;
+   * observations from different sources are ordered against each other.
+   */
+  readonly observed_at: number;
+}
+/** The handle a publisher is given to feed the funnel. */
+export interface ObservationSink {
+  publish(observation: Observation): void;
+}
+/** A source of observations for one or more canonical fields. */
+export interface Publisher {
+  readonly paths: ReadonlySet<FieldPath>;
+  attach(sink: ObservationSink): Unsubscribe;
+  /** Begin supplying `paths`: subscription accounting, not a data request. */
+  request(paths: ReadonlySet<FieldPath>): void;
+  /** Stop supplying `paths`. */
+  release(paths: ReadonlySet<FieldPath>): void;
+}
+/**
+ * Funnels observations from every attached publisher into one listener set.
+ *
+ * Many to one: a listener registered for a field receives what any publisher
+ * reports for it, in arrival order. There is no source selection, ranking, or
+ * health model here, and detaching or silencing a publisher produces no value of
+ * its own. The only arbitration, dropping older observations and skipping
+ * unchanged values, is hard-coded.
+ */
+export declare class ObservationFunnel implements ObservationSink {
+  #private;
+  constructor(options?: {
+    logger?: Logger;
+  });
+  /** Attach `publisher` and return its detach closure. */
+  attach(publisher: Publisher): Unsubscribe;
+  /** Accept one observation from any publisher and fan it out. */
+  publish(observation: Observation): void;
+  /**
+   * The last value observed for `path`. Null means there is no reading: either
+   * nothing has ever been observed, or a source reported the field as unavailable.
+   */
+  value(path: FieldPath): Value;
+  /**
+   * Register a listener for `path`, called on each changed value. The first
+   * listener for a path activates it on every capable publisher; the last one
+   * to leave releases it. Registration dispatches nothing: the value standing at
+   * that moment is `value()`.
+   */
+  listen(path: FieldPath, callback: (value: Value) => void): Unsubscribe;
+  /**
+   * Observe whether any of `paths` has at least one live listener. Derived from
+   * the activation counts the funnel already keeps. It reports; it never starts
+   * work of its own.
+   */
+  listen_demand(paths: ReadonlySet<FieldPath>, callback: (active: boolean) => void): Unsubscribe;
+}
+export declare const LOCK_STATES: ReadonlyMap<number, boolean>;
+export declare const CLOSURE_STATES: ReadonlyMap<number, boolean>;
+/**
+ * A source whose readings are handed to it as arguments. It holds no client,
+ * session, endpoint, or callable able to obtain one, so nothing here can originate
+ * a request, and activation subscribes to nothing.
+ */
+declare abstract class SuppliedPublisher<Input> implements Publisher {
+  #private;
+  constructor(options?: {
+    clock?: Clock;
+  });
+  get paths(): ReadonlySet<FieldPath>;
+  attach(sink: ObservationSink): Unsubscribe;
+  request(_paths: ReadonlySet<FieldPath>): void;
+  release(_paths: ReadonlySet<FieldPath>): void;
+  protected _publish(input: Input, observed_at: number | undefined): readonly Observation[];
+  protected abstract _translate(input: Input, observed_at: number): Observation[];
+}
+/** Translates a caller-supplied `vehicle_data` result into observations. */
+export declare class VehicleDataResultPublisher extends SuppliedPublisher<unknown> {
+  /** Translate a supplied result and feed the audited leaves to the sink. */
+  publish_result(result: unknown, options?: {
+    observed_at?: number;
+  }): readonly Observation[];
+  protected _translate(result: unknown, observed_at: number): Observation[];
+}
+/**
+ * Translates a caller-supplied Teslemetry stream signal update into observations.
+ * The update is keyed by signal name the way a stream push is (`Locked`,
+ * `ChargePortDoorOpen`, `DoorState` with a nested `TrunkFront`). `@teslemetry/api`
+ * owns the stream client; the two meet here.
+ */
+export declare class TeslemetryStreamPublisher extends SuppliedPublisher<unknown> {
+  /** Translate a supplied stream signal update and feed it to the sink. */
+  publish_update(data: unknown, options?: {
+    observed_at?: number;
+  }): readonly Observation[];
+  protected _translate(data: unknown, observed_at: number): Observation[];
+}
+export {};