tesla-fleet-api 0.2.0 → 0.3.0

package/src/energy.ts

@@ -5,151 +5,213 @@ import { SiteInfoResponse } from "./types/site_info.js";
 
 // Energy Class
 export default class Energy {
-    parent: TeslaFleetApi;
+  parent: TeslaFleetApi;
 
-    constructor(parent: TeslaFleetApi) {
-        this.parent = parent;
-    }
+  constructor(parent: TeslaFleetApi) {
+    this.parent = parent;
+  }
 
-    /**
-     * Create an Energy class for a specific site.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @returns `EnergySpecific` class
-     */
-    specific(energy_site_id: number): EnergySpecific {
-        return new EnergySpecific(this, energy_site_id);
-    }
+  /**
+   * Create an Energy class for a specific site.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @returns `EnergySpecific` class
+   */
+  specific(energy_site_id: number): EnergySpecific {
+    return new EnergySpecific(this, energy_site_id);
+  }
 
-    /**
-     * Adjust the site's backup reserve.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.ID field of an energy site from /api/1/products endpoint.
-     * @param backup_reserve_percent The desired backup reserve percent.
-     * @returns
-     */
-    async backup(energy_site_id: number, backup_reserve_percent: number): Promise<Record<string, any>> {
-        return this.parent._request("POST", `api/1/energy_sites/${energy_site_id}/backup`, null, { backup_reserve_percent });
-    }
+  /**
+   * Adjust the site's backup reserve.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.ID field of an energy site from /api/1/products endpoint.
+   * @param backup_reserve_percent The desired backup reserve percent.
+   * @returns
+   */
+  async backup(
+    energy_site_id: number,
+    backup_reserve_percent: number,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "POST",
+      `api/1/energy_sites/${energy_site_id}/backup`,
+      null,
+      { backup_reserve_percent },
+    );
+  }
 
-    /**
-     * Returns the backup (off-grid) event history of the site in duration of seconds.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-     * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
-     * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
-     * @returns
-     */
-    async backup_history(
-        energy_site_id: number,
-        kind: string,
-        start_date: string,
-        end_date: string,
-        period: string,
-        time_zone: string
-    ): Promise<Record<string, any>> {
-        return this.parent._request("GET", `api/1/energy_sites/${energy_site_id}/calendar_history`, null, { kind, start_date, end_date, period, time_zone });
-    }
+  /**
+   * Returns the backup (off-grid) event history of the site in duration of seconds.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
+   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
+   * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
+   * @returns
+   */
+  async backup_history(
+    energy_site_id: number,
+    kind: string,
+    start_date: string,
+    end_date: string,
+    period: string,
+    time_zone: string,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "GET",
+      `api/1/energy_sites/${energy_site_id}/calendar_history`,
+      null,
+      { kind, start_date, end_date, period, time_zone },
+    );
+  }
 
-    /**
-     * Returns the charging history of a wall connector.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-     * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
-     * @returns
-     */
-    async charge_history(energy_site_id: number, kind: string, start_date: string, end_date: string, time_zone: string): Promise<Record<string, any>> {
-        return this.parent._request("GET", `api/1/energy_sites/${energy_site_id}/telemetry_history`, null, { kind, start_date, end_date, time_zone });
-    }
+  /**
+   * Returns the charging history of a wall connector.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
+   * @param start_date Start date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
+   * @returns
+   */
+  async charge_history(
+    energy_site_id: number,
+    kind: string,
+    start_date: string,
+    end_date: string,
+    time_zone: string,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "GET",
+      `api/1/energy_sites/${energy_site_id}/telemetry_history`,
+      null,
+      { kind, start_date, end_date, time_zone },
+    );
+  }
 
-    /**
-     * Returns the energy measurements of the site, aggregated to the requested period.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
-     * @param start_dateStart date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
-     * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
-     * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
-     * @returns
-     */
-    async energy_history(
-        energy_site_id: number,
-        kind: string,
-        start_date: string,
-        end_date: string,
-        period: string,
-        time_zone: string
-    ): Promise<Record<string, any>> {
-        return this.parent._request("GET", `api/1/energy_sites/${energy_site_id}/calendar_history`, null, { kind, start_date, end_date, period, time_zone });
-    }
+  /**
+   * Returns the energy measurements of the site, aggregated to the requested period.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param kind The kind of history to be requested. 'backup', 'charge', 'energy' are all supported.
+   * @param start_dateStart date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param end_date End date of the window to retrieve backup events in RFC3339 format. i.e. 2023-01-01T00:00:00-08:00
+   * @param period Period of the window to retrieve backup events. This can be day, week, month, year, lifetime and should align with the window requested.
+   * @param time_zone Timezone of the requested window in IANA name format. i.e. 'America/Los_Angeles'
+   * @returns
+   */
+  async energy_history(
+    energy_site_id: number,
+    kind: string,
+    start_date: string,
+    end_date: string,
+    period: string,
+    time_zone: string,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "GET",
+      `api/1/energy_sites/${energy_site_id}/calendar_history`,
+      null,
+      { kind, start_date, end_date, period, time_zone },
+    );
+  }
 
-    /**
-     * Allow/disallow charging from the grid and exporting energy to the grid.
-     * @param energy_site_id
-     * @param disallow_charge_from_grid_with_solar_installed The desired behavior towards importing from the grid. Charging from the grid is disabled when set to true and enabled when set to false.
-     * @param customer_preferred_export_rule The desired behavior for grid exporting. The available options are battery_ok, pv_only, and never.
-     * @returns
-     */
-    async grid_import_export(
-        energy_site_id: number,
-        disallow_charge_from_grid_with_solar_installed: boolean | null = null,
-        customer_preferred_export_rule: string | null = null
-    ): Promise<Record<string, any>> {
-        return this.parent._request("POST", `api/1/energy_sites/${energy_site_id}/grid_import_export`, null, {
-            disallow_charge_from_grid_with_solar_installed,
-            customer_preferred_export_rule,
-        });
-    }
+  /**
+   * Allow/disallow charging from the grid and exporting energy to the grid.
+   * @param energy_site_id
+   * @param disallow_charge_from_grid_with_solar_installed The desired behavior towards importing from the grid. Charging from the grid is disabled when set to true and enabled when set to false.
+   * @param customer_preferred_export_rule The desired behavior for grid exporting. The available options are battery_ok, pv_only, and never.
+   * @returns
+   */
+  async grid_import_export(
+    energy_site_id: number,
+    disallow_charge_from_grid_with_solar_installed: boolean | null = null,
+    customer_preferred_export_rule: string | null = null,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "POST",
+      `api/1/energy_sites/${energy_site_id}/grid_import_export`,
+      null,
+      {
+        disallow_charge_from_grid_with_solar_installed,
+        customer_preferred_export_rule,
+      },
+    );
+  }
 
-    /**
-     * Returns the live status of the site (power, state of energy, grid status, storm mode).
-     * @param energy_site_id
-     * @returns
-     */
-    async live_status(energy_site_id: number): Promise<LiveStatusResponse> {
-        return this.parent._request("GET", `api/1/energy_sites/${energy_site_id}/live_status`).then(({response}) => response);
-    }
+  /**
+   * Returns the live status of the site (power, state of energy, grid status, storm mode).
+   * @param energy_site_id
+   * @returns
+   */
+  async live_status(energy_site_id: number): Promise<LiveStatusResponse> {
+    return this.parent
+      ._request("GET", `api/1/energy_sites/${energy_site_id}/live_status`)
+      .then(({ response }) => response);
+  }
 
-    /**
-     * Adjust the site's off-grid vehicle charging backup reserve.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param off_grid_vehicle_charging_reserve_percent The desired off grid vehicle charging reserve percent.
-     * @returns
-     */
-    async off_grid_vehicle_charging_reserve(energy_site_id: number, off_grid_vehicle_charging_reserve_percent: number): Promise<Record<string, any>> {
-        return this.parent._request("POST", `api/1/energy_sites/${energy_site_id}/off_grid_vehicle_charging_reserve`, null, {
-            off_grid_vehicle_charging_reserve_percent,
-        });
-    }
+  /**
+   * Adjust the site's off-grid vehicle charging backup reserve.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param off_grid_vehicle_charging_reserve_percent The desired off grid vehicle charging reserve percent.
+   * @returns
+   */
+  async off_grid_vehicle_charging_reserve(
+    energy_site_id: number,
+    off_grid_vehicle_charging_reserve_percent: number,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "POST",
+      `api/1/energy_sites/${energy_site_id}/off_grid_vehicle_charging_reserve`,
+      null,
+      {
+        off_grid_vehicle_charging_reserve_percent,
+      },
+    );
+  }
 
-    /**
-     * Set the site's mode.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param default_real_mode The desired operation mode. Use autonomous for time-based control and self_consumption for self-powered mode.
-     * @returns
-     */
-    async operation(energy_site_id: number, default_real_mode: string): Promise<Record<string, any>> {
-        return this.parent._request("POST", `api/1/energy_sites/${energy_site_id}/operation`, null, { default_real_mode });
-    }
+  /**
+   * Set the site's mode.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param default_real_mode The desired operation mode. Use autonomous for time-based control and self_consumption for self-powered mode.
+   * @returns
+   */
+  async operation(
+    energy_site_id: number,
+    default_real_mode: string,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "POST",
+      `api/1/energy_sites/${energy_site_id}/operation`,
+      null,
+      { default_real_mode },
+    );
+  }
 
-    /**
-     * Returns information about the site. Things like assets (has solar, etc), settings (backup reserve, etc), and features (storm_mode_capable, etc).
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @returns
-     */
-    async site_info(energy_site_id: number): Promise<SiteInfoResponse> {
-        return this.parent._request("GET", `api/1/energy_sites/${energy_site_id}/site_info`).then(({response}) => response);
-    }
+  /**
+   * Returns information about the site. Things like assets (has solar, etc), settings (backup reserve, etc), and features (storm_mode_capable, etc).
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @returns
+   */
+  async site_info(energy_site_id: number): Promise<SiteInfoResponse> {
+    return this.parent
+      ._request("GET", `api/1/energy_sites/${energy_site_id}/site_info`)
+      .then(({ response }) => response);
+  }
 
-    /**
-     * Update storm watch participation.
-     * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
-     * @param enabled The storm mode participation value to set.
-     * @returns
-     */
-    async storm_mode(energy_site_id: number, enabled: boolean): Promise<Record<string, any>> {
-        return this.parent._request("POST", `api/1/energy_sites/${energy_site_id}/storm_mode`, null, { enabled });
-    }
+  /**
+   * Update storm watch participation.
+   * @param energy_site_id ID field of an energy site from /api/1/products endpoint.
+   * @param enabled The storm mode participation value to set.
+   * @returns
+   */
+  async storm_mode(
+    energy_site_id: number,
+    enabled: boolean,
+  ): Promise<Record<string, any>> {
+    return this.parent._request(
+      "POST",
+      `api/1/energy_sites/${energy_site_id}/storm_mode`,
+      null,
+      { enabled },
+    );
+  }
 }

package/src/index.ts

@@ -1,9 +1,21 @@
+import Commands from "./commands.js";
 import Energy from "./energy.js";
 import EnergySpecific from "./energyspecific.js";
 import TeslaFleetApi from "./teslafleetapi.js";
 import Teslemetry from "./teslemetry.js";
 import Tessie from "./tessie.js";
 import Vehicle from "./vehicle.js";
+import VehicleSigned from "./vehiclesigned.js";
 import VehicleSpecific from "./vehiclespecific.js";
 
-export { Energy, EnergySpecific, TeslaFleetApi, Teslemetry, Tessie, Vehicle, VehicleSpecific };
+export { Commands, Energy, EnergySpecific, TeslaFleetApi, Teslemetry, Tessie, Vehicle, VehicleSigned, VehicleSpecific };
+export { Session } from "./signing/session.js";
+export {
+    SignedCommandError,
+    NotOnVehicleWhitelistError,
+    SignedCommandFaultError,
+    RetryableSignedCommandFaultError,
+} from "./signing/errors.js";
+export { getTariffPeriods } from "./tariff.js";
+export { Models } from "./types/vehicle.js";
+export type { TariffRate, TariffPeriod, TariffResolution } from "./tariff.js";

package/src/signing/crypto.ts

@@ -0,0 +1,29 @@
+import crypto from "crypto";
+
+const CURVE = "prime256v1"; // NIST P-256, matches the vehicle-command protocol.
+
+/** Derive the uncompressed public key point for a raw P-256 private scalar. */
+export function publicKeyFor(privateKey: Buffer): Buffer {
+    const ecdh = crypto.createECDH(CURVE);
+    ecdh.setPrivateKey(privateKey);
+    return ecdh.getPublicKey();
+}
+
+/**
+ * Derive the 16-byte signed-command shared key: ECDH(ourPrivate, vehiclePublic),
+ * then SHA-1 truncated to 16 bytes - matching the vehicle-command protocol
+ * (not a general-purpose KDF, do not reuse this for anything else).
+ */
+export function deriveSharedKey(privateKey: Buffer, vehiclePublicKey: Buffer): Buffer {
+    const ecdh = crypto.createECDH(CURVE);
+    ecdh.setPrivateKey(privateKey);
+    const secret = ecdh.computeSecret(vehiclePublicKey);
+    return crypto.createHash("sha1").update(secret).digest().subarray(0, 16);
+}
+
+/** Big-endian uint32, as used throughout the signed-command metadata tags. */
+export function uint32BE(value: number): Buffer {
+    const buffer = Buffer.alloc(4);
+    buffer.writeUInt32BE(value >>> 0, 0);
+    return buffer;
+}

package/src/signing/errors.ts

@@ -0,0 +1,50 @@
+import { MessageFaultE, messageFaultEToJSON } from "@teslemetry/tesla-protocol/command/universal_message";
+
+/**
+ * Base class for every error raised by the signed-command layer.
+ */
+export class SignedCommandError extends Error {}
+
+/**
+ * The vehicle rejected the session handshake because this key has not been
+ * paired with it (added via the Tesla app / NFC card).
+ */
+export class NotOnVehicleWhitelistError extends SignedCommandError {
+    constructor() {
+        super(
+            "This public key is not on the vehicle's key whitelist. Pair it with the vehicle first.",
+        );
+    }
+}
+
+/**
+ * The vehicle rejected a signed command with a `MessageFaultE` other than
+ * `MESSAGEFAULT_ERROR_NONE`.
+ */
+export class SignedCommandFaultError extends SignedCommandError {
+    fault: MessageFaultE;
+
+    constructor(fault: MessageFaultE) {
+        super(`Vehicle rejected signed command: ${messageFaultEToJSON(fault)}`);
+        this.fault = fault;
+    }
+}
+
+/**
+ * A `SignedCommandFaultError` whose fault the vehicle resolves by handing back
+ * fresh session info (epoch/counter drift) - `_command` retries these,
+ * bounded, by re-signing against the updated session before giving up.
+ */
+export class RetryableSignedCommandFaultError extends SignedCommandFaultError {}
+
+export function createFaultError(
+    fault: MessageFaultE,
+): SignedCommandFaultError {
+    if (
+        fault === MessageFaultE.MESSAGEFAULT_ERROR_INCORRECT_EPOCH ||
+        fault === MessageFaultE.MESSAGEFAULT_ERROR_INVALID_TOKEN_OR_COUNTER
+    ) {
+        return new RetryableSignedCommandFaultError(fault);
+    }
+    return new SignedCommandFaultError(fault);
+}

package/src/signing/session.ts

@@ -0,0 +1,132 @@
+import crypto from "crypto";
+import { Domain } from "@teslemetry/tesla-protocol/command/universal_message";
+import {
+    HMACPersonalizedSignatureData,
+    SessionInfo,
+} from "@teslemetry/tesla-protocol/command/signatures";
+
+/** Key material derived (but not yet trusted/committed) for a candidate vehicle public key. */
+export interface SessionKeys {
+    sharedKey: Buffer;
+    hmacKey: Buffer;
+    sessionInfoKey: Buffer;
+}
+
+/**
+ * Per-domain (VCSEC / Infotainment) signed-command session: tracks the
+ * anti-replay counter/epoch handed out by the vehicle's handshake reply and
+ * the HMAC keys derived from it.
+ *
+ * Deriving key material (`keysFor`) is split from committing it (`commit`)
+ * because the caller must authenticate a `SessionInfo` reply - by verifying
+ * its `session_info_tag` against the very keys derived here - *before*
+ * trusting anything in it, including the vehicle public key the shared key
+ * itself is derived from. See `Commands.validateAndUpdateSession`.
+ *
+ * A `Session` is not itself thread-safe; `withLock` serializes the
+ * message-build step (which mutates `counter`) so concurrent commands on the
+ * same domain cannot race on the same counter value.
+ */
+export class Session {
+    readonly domain: Domain;
+    counter: number = 0;
+    epoch?: Buffer;
+    delta?: number;
+    sharedKey?: Buffer;
+    hmacKey?: Buffer;
+    sessionInfoKey?: Buffer;
+    publicKey?: Buffer;
+
+    /** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
+    private lastAuthenticatedClockTime?: number;
+    private queue: Promise<void> = Promise.resolve();
+
+    constructor(
+        domain: Domain,
+        private readonly deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer,
+    ) {
+        this.domain = domain;
+    }
+
+    /** Whether the handshake has completed and commands can be signed. */
+    get ready(): boolean {
+        return this.epoch !== undefined && this.hmacKey !== undefined && this.delta !== undefined;
+    }
+
+    /**
+     * Derive the shared key and its two HMAC sub-keys for a candidate vehicle
+     * public key, without touching any session state. Pure and side-effect
+     * free so a caller can verify authenticity first and discard the result
+     * if verification fails.
+     */
+    keysFor(vehiclePublicKey: Buffer): SessionKeys {
+        const sharedKey = this.deriveSharedKey(vehiclePublicKey);
+        const hmacKey = crypto.createHmac("sha256", sharedKey).update("authenticated command").digest();
+        const sessionInfoKey = crypto.createHmac("sha256", sharedKey).update("session info").digest();
+        return { sharedKey, hmacKey, sessionInfoKey };
+    }
+
+    /**
+     * Commit an already-authenticated `SessionInfo` plus the `keysFor` result
+     * derived from its public key. Per the vehicle-command protocol, the
+     * anti-replay counter must never roll back within the same epoch, and a
+     * clock time that regresses within the same epoch marks the reply as
+     * stale/replayed - returns `false` (without mutating any state) in that
+     * case so the caller can reject it.
+     */
+    commit(sessionInfo: SessionInfo, keys: SessionKeys): boolean {
+        const incomingEpoch = Buffer.from(sessionInfo.epoch);
+        const sameEpoch = this.epoch !== undefined && this.epoch.equals(incomingEpoch);
+
+        if (sameEpoch && this.lastAuthenticatedClockTime !== undefined && sessionInfo.clockTime < this.lastAuthenticatedClockTime) {
+            return false;
+        }
+
+        this.counter = sameEpoch ? Math.max(this.counter, sessionInfo.counter) : sessionInfo.counter;
+        this.epoch = incomingEpoch;
+        this.delta = Math.floor(Date.now() / 1000) - sessionInfo.clockTime;
+        this.lastAuthenticatedClockTime = sessionInfo.clockTime;
+        this.publicKey = Buffer.from(sessionInfo.publicKey);
+        this.sharedKey = keys.sharedKey;
+        this.hmacKey = keys.hmacKey;
+        this.sessionInfoKey = keys.sessionInfoKey;
+        return true;
+    }
+
+    /**
+     * Advance the anti-replay counter and return fresh signature metadata for
+     * an HMAC-personalized command. The command expires 10 seconds from now,
+     * corrected for clock drift against the vehicle (`delta`).
+     */
+    hmacPersonalized(): HMACPersonalizedSignatureData {
+        if (!this.ready || !this.epoch || this.delta === undefined) {
+            throw new Error("Session is not ready: perform the handshake first.");
+        }
+        this.counter++;
+        return HMACPersonalizedSignatureData.create({
+            epoch: this.epoch,
+            counter: this.counter,
+            expiresAt: Math.floor(Date.now() / 1000) - this.delta + 10,
+        });
+    }
+
+    /**
+     * Run `fn` with exclusive access to this session, queuing behind any
+     * in-flight caller. Held only for as long as `fn` takes - callers should
+     * keep it scoped to the synchronous message-build step, not a full
+     * network round trip.
+     */
+    async withLock<T>(fn: () => T | Promise<T>): Promise<T> {
+        const previous = this.queue;
+        let release!: () => void;
+        this.queue = new Promise<void>((resolve) => {
+            release = resolve;
+        });
+        await previous.catch((): void => undefined);
+        try {
+            return await fn();
+        } finally {
+            release();
+        }
+    }
+}