tesla-fleet-api 0.3.0 → 0.5.0

package/dist/tariff.cjs

@@ -0,0 +1,319 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_exceptions = require("./exceptions.cjs");
+// src/tariff.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Extract the `tariff_content_v2` object from a raw API response.
+*
+* Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+* `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+* `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+* unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+* and `energy_charges`) - checked identically on every path, since a malformed body (including an
+* empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+*/
+function unwrapTariffV2(response) {
+	if (response == null) throw new require_exceptions.InvalidResponse("tariff response body was null");
+	if (!isObject(response)) throw new require_exceptions.InvalidResponse(String(response));
+	let candidate;
+	if ("tariff_content_v2" in response) candidate = response.tariff_content_v2;
+	else if ("response" in response || "tou_settings" in response) {
+		const inner = "response" in response ? response.response : response.tou_settings;
+		candidate = isObject(inner) ? inner.tariff_content_v2 : void 0;
+	} else candidate = response;
+	if (isObject(candidate) && "seasons" in candidate && "energy_charges" in candidate) return candidate;
+	throw new require_exceptions.InvalidResponse(response);
+}
+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;
+exports.unwrapTariffV2 = unwrapTariffV2;

package/dist/tariff.d.cts

@@ -0,0 +1,40 @@
+import { TariffContentV2 } from "./types/site_info.cjs";
+export interface TariffRate {
+  price: number | null;
+  periodName: string | null;
+  seasonName: string | null;
+}
+export interface TariffPeriod {
+  start: Date;
+  end: Date;
+  buy: TariffRate;
+  sell: TariffRate;
+}
+export interface TariffResolution {
+  buy: TariffRate;
+  sell: TariffRate;
+  currentStart: Date;
+  nextChange: Date;
+  currency: string | null;
+  upcoming: TariffPeriod[] | null;
+}
+/**
+ * Extract the `tariff_content_v2` object from a raw API response.
+ *
+ * Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+ * `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+ * `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+ * unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+ * and `energy_charges`) - checked identically on every path, since a malformed body (including an
+ * empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+ */
+export declare function unwrapTariffV2(response: unknown): TariffContentV2;
+/**
+ * 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.
+ */
+export declare function getTariffPeriods(tariff: TariffContentV2, now: Date, opts?: {
+  timeZone: string;
+  horizonHours?: number;
+}): TariffResolution | null;

package/dist/tariff.d.mts

@@ -0,0 +1,40 @@
+import { TariffContentV2 } from "./types/site_info.mjs";
+export interface TariffRate {
+  price: number | null;
+  periodName: string | null;
+  seasonName: string | null;
+}
+export interface TariffPeriod {
+  start: Date;
+  end: Date;
+  buy: TariffRate;
+  sell: TariffRate;
+}
+export interface TariffResolution {
+  buy: TariffRate;
+  sell: TariffRate;
+  currentStart: Date;
+  nextChange: Date;
+  currency: string | null;
+  upcoming: TariffPeriod[] | null;
+}
+/**
+ * Extract the `tariff_content_v2` object from a raw API response.
+ *
+ * Accepts the `site_info` read envelope (`{ response: { tariff_content_v2 } }`), the
+ * `time_of_use_settings` write envelope (`{ tou_settings: { tariff_content_v2 } }`), or the bare
+ * `tariff_content_v2` object itself. Throws {@link InvalidResponse} for a null body, an
+ * unrecognized envelope, or an extracted object without the minimal Tariff V2 shape (`seasons`
+ * and `energy_charges`) - checked identically on every path, since a malformed body (including an
+ * empty `{}` nested under a recognized envelope) is not the same as "no tariff configured".
+ */
+export declare function unwrapTariffV2(response: unknown): TariffContentV2;
+/**
+ * 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.
+ */
+export declare function getTariffPeriods(tariff: TariffContentV2, now: Date, opts?: {
+  timeZone: string;
+  horizonHours?: number;
+}): TariffResolution | null;