tesla-fleet-api 0.2.2 → 0.4.0

package/dist/signing/session.cjs

@@ -0,0 +1,112 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+let crypto = require("crypto");
+crypto = require_runtime.__toESM(crypto, 1);
+let _teslemetry_tesla_protocol_command_signatures = require("@teslemetry/tesla-protocol/command/signatures");
+// src/signing/session.ts
+/**
+* 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.
+*/
+var Session = class {
+	deriveSharedKey;
+	domain;
+	counter = 0;
+	epoch;
+	delta;
+	sharedKey;
+	hmacKey;
+	sessionInfoKey;
+	publicKey;
+	/** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
+	lastAuthenticatedClockTime;
+	queue = Promise.resolve();
+	constructor(domain, deriveSharedKey) {
+		this.deriveSharedKey = deriveSharedKey;
+		this.domain = domain;
+	}
+	/** Whether the handshake has completed and commands can be signed. */
+	get ready() {
+		return this.epoch !== void 0 && this.hmacKey !== void 0 && this.delta !== void 0;
+	}
+	/**
+	* 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) {
+		const sharedKey = this.deriveSharedKey(vehiclePublicKey);
+		return {
+			sharedKey,
+			hmacKey: crypto.default.createHmac("sha256", sharedKey).update("authenticated command").digest(),
+			sessionInfoKey: crypto.default.createHmac("sha256", sharedKey).update("session info").digest()
+		};
+	}
+	/**
+	* 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, keys) {
+		const incomingEpoch = Buffer.from(sessionInfo.epoch);
+		const sameEpoch = this.epoch !== void 0 && this.epoch.equals(incomingEpoch);
+		if (sameEpoch && this.lastAuthenticatedClockTime !== void 0 && 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() / 1e3) - 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() {
+		if (!this.ready || !this.epoch || this.delta === void 0) throw new Error("Session is not ready: perform the handshake first.");
+		this.counter++;
+		return _teslemetry_tesla_protocol_command_signatures.HMACPersonalizedSignatureData.create({
+			epoch: this.epoch,
+			counter: this.counter,
+			expiresAt: Math.floor(Date.now() / 1e3) - 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(fn) {
+		const previous = this.queue;
+		let release;
+		this.queue = new Promise((resolve) => {
+			release = resolve;
+		});
+		await previous.catch(() => void 0);
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+};
+exports.Session = Session;

package/dist/signing/session.d.cts

@@ -0,0 +1,69 @@
+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 declare class Session {
+  private readonly deriveSharedKey;
+  readonly domain: Domain;
+  counter: number;
+  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?;
+  private queue;
+  constructor(domain: Domain, deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer);
+  /** Whether the handshake has completed and commands can be signed. */
+  get ready(): boolean;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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.
+   */
+  withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+}

package/dist/signing/session.d.mts

@@ -0,0 +1,69 @@
+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 declare class Session {
+  private readonly deriveSharedKey;
+  readonly domain: Domain;
+  counter: number;
+  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?;
+  private queue;
+  constructor(domain: Domain, deriveSharedKey: (vehiclePublicKey: Buffer) => Buffer);
+  /** Whether the handshake has completed and commands can be signed. */
+  get ready(): boolean;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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.
+   */
+  withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+}

package/dist/signing/session.mjs

@@ -0,0 +1,110 @@
+import crypto from "crypto";
+import { HMACPersonalizedSignatureData } from "@teslemetry/tesla-protocol/command/signatures";
+// src/signing/session.ts
+/**
+* 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.
+*/
+var Session = class {
+	deriveSharedKey;
+	domain;
+	counter = 0;
+	epoch;
+	delta;
+	sharedKey;
+	hmacKey;
+	sessionInfoKey;
+	publicKey;
+	/** Clock time of the last *authenticated* SessionInfo committed for the current epoch, guarding against replay/rollback. */
+	lastAuthenticatedClockTime;
+	queue = Promise.resolve();
+	constructor(domain, deriveSharedKey) {
+		this.deriveSharedKey = deriveSharedKey;
+		this.domain = domain;
+	}
+	/** Whether the handshake has completed and commands can be signed. */
+	get ready() {
+		return this.epoch !== void 0 && this.hmacKey !== void 0 && this.delta !== void 0;
+	}
+	/**
+	* 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) {
+		const sharedKey = this.deriveSharedKey(vehiclePublicKey);
+		return {
+			sharedKey,
+			hmacKey: crypto.createHmac("sha256", sharedKey).update("authenticated command").digest(),
+			sessionInfoKey: crypto.createHmac("sha256", sharedKey).update("session info").digest()
+		};
+	}
+	/**
+	* 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, keys) {
+		const incomingEpoch = Buffer.from(sessionInfo.epoch);
+		const sameEpoch = this.epoch !== void 0 && this.epoch.equals(incomingEpoch);
+		if (sameEpoch && this.lastAuthenticatedClockTime !== void 0 && 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() / 1e3) - 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() {
+		if (!this.ready || !this.epoch || this.delta === void 0) 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() / 1e3) - 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(fn) {
+		const previous = this.queue;
+		let release;
+		this.queue = new Promise((resolve) => {
+			release = resolve;
+		});
+		await previous.catch(() => void 0);
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+};
+export { Session };

package/dist/tariff.cjs

@@ -0,0 +1,292 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/tariff.ts
+const MINUTES_PER_DAY = 1440;
+function formatParts(date, timeZone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23"
+	}).formatToParts(date);
+	const out = {};
+	for (const p of parts) out[p.type] = Number(p.value);
+	return out;
+}
+/** Tesla weekday (Mon=0..Sun=6) for a calendar date, via JS Date.getUTCDay() (Sun=0..Sat=6). */
+function dowFromDate(year, month, day) {
+	return (new Date(Date.UTC(year, month - 1, day)).getUTCDay() + 6) % 7;
+}
+function getWallClock(now, timeZone) {
+	const { year, month, day, hour, minute } = formatParts(now, timeZone);
+	return {
+		year,
+		month,
+		day,
+		dow: dowFromDate(year, month, day),
+		minuteOfDay: hour * 60 + minute
+	};
+}
+/**
+* Converts a target site-local wall-clock (year/month/day/hour/minute in `timeZone`) to the UTC
+* instant it represents. Iterates because the zone's UTC offset at the target instant is itself
+* what we're solving for (DST) - 3 rounds converges for any real-world offset change.
+*/
+function wallClockToUtcMillis(year, month, day, hour, minute, timeZone) {
+	const target = Date.UTC(year, month - 1, day, hour, minute);
+	let guess = target;
+	for (let i = 0; i < 3; i++) {
+		const p = formatParts(new Date(guess), timeZone);
+		const next = target - (Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - guess);
+		if (next === guess) break;
+		guess = next;
+	}
+	return guess;
+}
+/**
+* Adds `deltaMinutes` of wall-clock time (not elapsed real time) to a wall-clock reading, staying
+* in pure calendar arithmetic throughout - no `timeZone`/`Intl` round trip, so this is safe to use
+* for "what day/weekday is N minutes from now" even across a DST transition, where a real-time-ms
+* shift and a wall-clock-minutes shift land on different calendar days.
+*/
+function wallClockAt(wallClock, deltaMinutes) {
+	const naive = new Date(Date.UTC(wallClock.year, wallClock.month - 1, wallClock.day, 0, wallClock.minuteOfDay + deltaMinutes));
+	const year = naive.getUTCFullYear();
+	const month = naive.getUTCMonth() + 1;
+	const day = naive.getUTCDate();
+	const minuteOfDay = naive.getUTCHours() * 60 + naive.getUTCMinutes();
+	return {
+		year,
+		month,
+		day,
+		dow: dowFromDate(year, month, day),
+		minuteOfDay
+	};
+}
+function dowInRange(d, fromDow, toDow) {
+	return fromDow <= toDow ? d >= fromDow && d <= toDow : d >= fromDow || d <= toDow;
+}
+function seasonContains(season, month, day) {
+	if (!season?.tou_periods) return false;
+	const fromMonth = season.fromMonth ?? 1;
+	const fromDay = season.fromDay ?? 1;
+	const toMonth = season.toMonth ?? 12;
+	const toDay = season.toDay ?? 31;
+	const from = fromMonth * 100 + fromDay;
+	const to = toMonth * 100 + toDay;
+	const cur = month * 100 + day;
+	return from <= to ? cur >= from && cur <= to : cur >= from || cur <= to;
+}
+function findSeason(seasons, month, day) {
+	if (!seasons) return null;
+	for (const [name, season] of Object.entries(seasons)) if (seasonContains(season, month, day)) return {
+		name,
+		season
+	};
+	return null;
+}
+/**
+* Expands a season's `tou_periods` into the windows active on one specific calendar day (given
+* as a Tesla weekday, Mon=0..Sun=6). A period whose `fromDayOfWeek..toDayOfWeek` includes `dow`
+* contributes its own window (clamped to this day, `endMin` capped at 1440 if it crosses
+* midnight); a period that crosses midnight and includes *yesterday* also contributes its
+* early-morning continuation here, `trueStartMin` carrying its real (pre-midnight) start so a
+* currently-active continuation can still report an accurate `currentStart`.
+*/
+function dayPeriods(touPeriods, dow) {
+	const segments = [];
+	const prevDow = (dow + 6) % 7;
+	for (const [periodName, def] of Object.entries(touPeriods)) for (const window of def.periods ?? []) {
+		const fromDow = window.fromDayOfWeek ?? 0;
+		const toDow = window.toDayOfWeek ?? 6;
+		const fromMin = (window.fromHour ?? 0) * 60 + (window.fromMinute ?? 0);
+		const toMin = (window.toHour ?? 0) * 60 + (window.toMinute ?? 0);
+		const crossesMidnight = toMin <= fromMin;
+		if (dowInRange(dow, fromDow, toDow)) {
+			const endMin = crossesMidnight ? MINUTES_PER_DAY : toMin;
+			if (endMin > fromMin) segments.push({
+				periodName,
+				startMin: fromMin,
+				endMin,
+				trueStartMin: fromMin
+			});
+		}
+		if (crossesMidnight && toMin > 0 && dowInRange(prevDow, fromDow, toDow)) segments.push({
+			periodName,
+			startMin: 0,
+			endMin: toMin,
+			trueStartMin: fromMin - MINUTES_PER_DAY
+		});
+	}
+	return segments;
+}
+function lookupPrice(charges, seasonName, periodName) {
+	if (!charges) return null;
+	const seasonRates = charges[seasonName]?.rates ?? charges["ALL"]?.rates;
+	if (!seasonRates) return null;
+	const value = Object.prototype.hasOwnProperty.call(seasonRates, periodName) ? seasonRates[periodName] : seasonRates["ALL"];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+const EMPTY_RATE = {
+	price: null,
+	periodName: null,
+	seasonName: null
+};
+/**
+* Resolves one grid's (buy's, or sell's) state at `wallClock`: the active period if any, and the
+* next boundary regardless of whether a period is currently active - a sparse tariff's gap still
+* has a "next change" (the gap's own end) and a "since" (the gap's own start), just like an active
+* period does (its own end and start).
+*/
+function scheduleAt(seasons, wallClock) {
+	const matched = findSeason(seasons, wallClock.month, wallClock.day);
+	if (!matched) return null;
+	const todaySegs = dayPeriods(matched.season.tou_periods, wallClock.dow);
+	const current = todaySegs.find((s) => s.startMin <= wallClock.minuteOfDay && wallClock.minuteOfDay < s.endMin) ?? null;
+	const laterTodayStarts = todaySegs.filter((s) => s.startMin > wallClock.minuteOfDay).map((s) => s.startMin);
+	let nextMin = current ? current.endMin : null;
+	if (laterTodayStarts.length > 0) nextMin = nextMin === null ? Math.min(...laterTodayStarts) : Math.min(nextMin, Math.min(...laterTodayStarts));
+	else if (nextMin === null || nextMin >= MINUTES_PER_DAY) {
+		const tomorrowWallClock = wallClockAt(wallClock, MINUTES_PER_DAY - wallClock.minuteOfDay);
+		const tomorrowMatched = findSeason(seasons, tomorrowWallClock.month, tomorrowWallClock.day);
+		const tomorrowSegs = tomorrowMatched ? dayPeriods(tomorrowMatched.season.tou_periods, tomorrowWallClock.dow) : [];
+		const continuation = current && tomorrowMatched?.name === matched.name ? tomorrowSegs.find((s) => s.startMin === 0 && s.periodName === current.periodName) : void 0;
+		if (continuation) nextMin = MINUTES_PER_DAY + continuation.endMin;
+		else if (tomorrowSegs.length > 0) {
+			const tomorrowFirst = MINUTES_PER_DAY + Math.min(...tomorrowSegs.map((s) => s.startMin));
+			nextMin = nextMin === null ? tomorrowFirst : Math.min(nextMin, tomorrowFirst);
+		}
+	}
+	let sinceMin;
+	if (current) sinceMin = current.trueStartMin;
+	else {
+		const earlierTodayEnds = todaySegs.filter((s) => s.endMin <= wallClock.minuteOfDay).map((s) => s.endMin);
+		if (earlierTodayEnds.length > 0) sinceMin = Math.max(...earlierTodayEnds);
+		else {
+			const yesterdayWallClock = wallClockAt(wallClock, -1440);
+			const yesterdayMatched = findSeason(seasons, yesterdayWallClock.month, yesterdayWallClock.day);
+			const yesterdaySegs = yesterdayMatched ? dayPeriods(yesterdayMatched.season.tou_periods, yesterdayWallClock.dow) : [];
+			sinceMin = yesterdaySegs.length > 0 ? Math.max(...yesterdaySegs.map((s) => s.endMin)) - MINUTES_PER_DAY : null;
+		}
+	}
+	return {
+		seasonName: matched.name,
+		current,
+		nextChangeGM: nextMin === null ? null : nextMin - wallClock.minuteOfDay,
+		sinceGM: sinceMin === null ? null : sinceMin - wallClock.minuteOfDay
+	};
+}
+/** Walks one calendar day at a time across the horizon, re-resolving the season fresh on each day (via pure wall-clock arithmetic, not elapsed-ms/DST-sensitive arithmetic) so a horizon crossing a season boundary re-prices and re-labels correctly. */
+function collectSegments(seasons, wallClock, horizonMinutes) {
+	const segments = [];
+	let dayStartGM = -wallClock.minuteOfDay;
+	while (dayStartGM < horizonMinutes) {
+		const dayWallClock = wallClockAt(wallClock, dayStartGM);
+		const matched = findSeason(seasons, dayWallClock.month, dayWallClock.day);
+		if (matched) for (const seg of dayPeriods(matched.season.tou_periods, dayWallClock.dow)) {
+			const startGM = dayStartGM + seg.startMin;
+			const endGM = dayStartGM + seg.endMin;
+			if (endGM > 0 && startGM < horizonMinutes) segments.push({
+				startGM,
+				endGM,
+				periodName: seg.periodName,
+				seasonName: matched.name
+			});
+		}
+		dayStartGM += MINUTES_PER_DAY;
+	}
+	segments.sort((a, b) => a.startGM - b.startGM);
+	const merged = [];
+	for (const seg of segments) {
+		const last = merged[merged.length - 1];
+		if (last && last.endGM === seg.startGM && last.periodName === seg.periodName && last.seasonName === seg.seasonName) last.endGM = seg.endGM;
+		else merged.push({ ...seg });
+	}
+	return merged;
+}
+function buildUpcoming(buySeasons, buyCharges, sellSeasons, sellCharges, hasSell, wallClock, horizonMinutes, toDate) {
+	const buySegs = collectSegments(buySeasons, wallClock, horizonMinutes);
+	const sellSegs = hasSell ? collectSegments(sellSeasons, wallClock, horizonMinutes) : [];
+	const boundaries = /* @__PURE__ */ new Set([0, horizonMinutes]);
+	const addBoundary = (gm) => {
+		if (gm > 0 && gm < horizonMinutes) boundaries.add(gm);
+	};
+	for (const s of buySegs) {
+		addBoundary(s.startGM);
+		addBoundary(s.endGM);
+	}
+	for (const s of sellSegs) {
+		addBoundary(s.startGM);
+		addBoundary(s.endGM);
+	}
+	const sorted = [...boundaries].sort((a, b) => a - b);
+	const periods = [];
+	for (let i = 0; i < sorted.length - 1; i++) {
+		const segStart = sorted[i];
+		const segEnd = sorted[i + 1];
+		if (segStart === segEnd) continue;
+		const buyAt = buySegs.find((s) => s.startGM <= segStart && segStart < s.endGM);
+		const sellAt = sellSegs.find((s) => s.startGM <= segStart && segStart < s.endGM);
+		periods.push({
+			start: toDate(segStart),
+			end: toDate(segEnd),
+			buy: buyAt ? {
+				price: lookupPrice(buyCharges, buyAt.seasonName, buyAt.periodName),
+				periodName: buyAt.periodName,
+				seasonName: buyAt.seasonName
+			} : EMPTY_RATE,
+			sell: sellAt ? {
+				price: lookupPrice(sellCharges, sellAt.seasonName, sellAt.periodName),
+				periodName: sellAt.periodName,
+				seasonName: sellAt.seasonName
+			} : EMPTY_RATE
+		});
+	}
+	return periods;
+}
+/**
+* Resolves the current buy/sell time-of-use rate for a Tariff V2 object at a given instant.
+* `tariff` carries no timezone; the caller must supply the site's IANA zone (e.g. from
+* `site_info.installation_time_zone`) so wall-clock period boundaries match correctly.
+*/
+function getTariffPeriods(tariff, now, opts) {
+	if (!tariff?.seasons || !tariff?.energy_charges) return null;
+	if (!opts?.timeZone) throw new Error("getTariffPeriods requires opts.timeZone");
+	const timeZone = opts.timeZone;
+	const wallClock = getWallClock(now, timeZone);
+	const buySchedule = scheduleAt(tariff.seasons, wallClock);
+	if (!buySchedule?.current) return null;
+	const sellSeasons = tariff.sell_tariff?.seasons ?? tariff.seasons;
+	const sellSchedule = tariff.sell_tariff ? scheduleAt(sellSeasons, wallClock) : null;
+	const buyRate = {
+		price: lookupPrice(tariff.energy_charges, buySchedule.seasonName, buySchedule.current.periodName),
+		periodName: buySchedule.current.periodName,
+		seasonName: buySchedule.seasonName
+	};
+	const sellRate = sellSchedule?.current ? {
+		price: lookupPrice(tariff.sell_tariff.energy_charges, sellSchedule.seasonName, sellSchedule.current.periodName),
+		periodName: sellSchedule.current.periodName,
+		seasonName: sellSchedule.seasonName
+	} : EMPTY_RATE;
+	const toDate = (gm) => {
+		const target = wallClockAt(wallClock, gm);
+		const hour = Math.floor(target.minuteOfDay / 60);
+		const minute = target.minuteOfDay % 60;
+		return new Date(wallClockToUtcMillis(target.year, target.month, target.day, hour, minute, timeZone));
+	};
+	const nextChangeGM = sellSchedule?.nextChangeGM != null ? Math.min(buySchedule.nextChangeGM, sellSchedule.nextChangeGM) : buySchedule.nextChangeGM;
+	const resolution = {
+		buy: buyRate,
+		sell: sellRate,
+		currentStart: toDate(sellSchedule?.sinceGM != null ? Math.max(buySchedule.sinceGM, sellSchedule.sinceGM) : buySchedule.sinceGM),
+		nextChange: toDate(nextChangeGM),
+		currency: typeof tariff.currency === "string" ? tariff.currency : null,
+		upcoming: null
+	};
+	if (opts.horizonHours) resolution.upcoming = buildUpcoming(tariff.seasons, tariff.energy_charges, sellSeasons, tariff.sell_tariff?.energy_charges, !!tariff.sell_tariff, wallClock, opts.horizonHours * 60, toDate);
+	return resolution;
+}
+exports.getTariffPeriods = getTariffPeriods;