tesla-fleet-api 0.4.0 → 0.6.0

package/dist/energyparsers.cjs

@@ -0,0 +1,118 @@
+const require_const = require("./const.cjs");
+const require_exceptions = require("./exceptions.cjs");
+// src/energyparsers.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The first present key's value. Tests presence, so a legal falsy value is never read as missing. */
+function field(payload, ...keys) {
+	for (const key of keys) if (Object.hasOwn(payload, key)) return payload[key];
+	return null;
+}
+/**
+* Type a raw value against an enum. A recognized number or member name
+* (case-insensitive) becomes the member's number. A present but unrecognized
+* value stays as received, because only an absent field means `null`.
+*/
+function normalizeEnum(members, value) {
+	if (typeof value === "string") {
+		const name = value.trim().toUpperCase();
+		return Object.hasOwn(members, name) ? members[name] : value;
+	}
+	return value;
+}
+function parseClient(payload) {
+	const roles = field(payload, "roles");
+	return {
+		public_key: field(payload, "public_key", "publicKey"),
+		state: normalizeEnum(require_const.AuthorizedClientState, field(payload, "state", "authorized_client_state")),
+		roles: Array.isArray(roles) ? roles.map((role) => normalizeEnum(require_const.AuthorizationRole, role)) : null,
+		verification: normalizeEnum(require_const.AuthorizedVerificationType, field(payload, "verification")),
+		raw: payload
+	};
+}
+function authorizedClientsList(payload) {
+	if (payload === null || payload === void 0) throw new require_exceptions.InvalidResponse("authorized_clients response body was null");
+	if (Array.isArray(payload)) return payload;
+	if (!isRecord(payload)) throw new require_exceptions.InvalidResponse(String(payload));
+	const value = field(isRecord(payload.response) ? payload.response : payload, "authorized_clients", "clients");
+	if (!Array.isArray(value)) throw new require_exceptions.InvalidResponse(payload);
+	return value;
+}
+/**
+* Parse a raw `list_authorized_clients` reply: a bare list,
+* `{response: {authorized_clients: [...]}}` or `{response: {clients: [...]}}`.
+* @throws InvalidResponse for a null body or any other shape.
+*/
+function parse_authorized_clients(payload) {
+	return {
+		clients: authorizedClientsList(payload).filter(isRecord).map(parseClient),
+		raw: payload
+	};
+}
+const OCTET = "(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])";
+const DOTTED_QUAD = new RegExp(`^${OCTET}\\.${OCTET}\\.${OCTET}\\.${OCTET}$`);
+/**
+* Decode a `networking_status` ipv4 field. The live API serves a strict dotted
+* quad; the big-endian uint32 form is accepted too. `0.0.0.0` and
+* `255.255.255.255` are never a usable host, in either form. Anything else
+* decodes to `null`, so one bad field cannot fail the lookup.
+*/
+function decodeIpv4(value) {
+	if (typeof value === "number") {
+		if (!Number.isInteger(value) || value <= 0 || value >= 4294967295) return null;
+		return [
+			value >>> 24,
+			value >>> 16 & 255,
+			value >>> 8 & 255,
+			value & 255
+		].join(".");
+	}
+	if (typeof value === "string" && DOTTED_QUAD.test(value) && value !== "0.0.0.0" && value !== "255.255.255.255") return value;
+	return null;
+}
+/**
+* Whether `address` is a dotted-quad IPv4 address in a private range (RFC 1918) or
+* the link-local range: the only places a gateway's LAN address can be. Anything
+* else, including a hostname or a `host:port`, is not.
+*/
+function is_lan_address(address) {
+	if (!DOTTED_QUAD.test(address)) return false;
+	const [first, second] = address.split(".").map(Number);
+	return first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 169 && second === 254;
+}
+function interfaceAddress(networkInterface) {
+	if (!isRecord(networkInterface)) return null;
+	const ipv4 = networkInterface.ipv4_config;
+	return isRecord(ipv4) ? decodeIpv4(ipv4.address) : null;
+}
+function networkingStatusBody(payload) {
+	if (payload === null || payload === void 0) throw new require_exceptions.InvalidResponse("networking_status response body was null");
+	if (!isRecord(payload)) throw new require_exceptions.InvalidResponse(String(payload));
+	if (!Object.hasOwn(payload, "response")) return payload;
+	if (!isRecord(payload.response)) throw new require_exceptions.InvalidResponse(payload);
+	return payload.response;
+}
+/**
+* Pick the gateway's LAN IPv4 address from a `networking_status` reply, with or
+* without the `response` envelope. Considers `eth` and `wifi` only, never `gsm`:
+* an interface with `active_route` wins, then the first with any decodable address.
+* @returns The address, or `null` when a well-formed reply has no usable interface.
+* @throws InvalidResponse for a null body or a reply of another shape.
+*/
+function parse_gateway_address(body) {
+	const status = networkingStatusBody(body);
+	const interfaces = [status.eth, status.wifi];
+	for (const networkInterface of interfaces) if (isRecord(networkInterface) && networkInterface.active_route) {
+		const address = interfaceAddress(networkInterface);
+		if (address !== null) return address;
+	}
+	for (const networkInterface of interfaces) {
+		const address = interfaceAddress(networkInterface);
+		if (address !== null) return address;
+	}
+	return null;
+}
+exports.is_lan_address = is_lan_address;
+exports.parse_authorized_clients = parse_authorized_clients;
+exports.parse_gateway_address = parse_gateway_address;

package/dist/energyparsers.d.cts

@@ -0,0 +1,39 @@
+type Json = Record<string, unknown>;
+/** A value typed against an enum: its number, or as received when unrecognized, or `null` when absent. */
+export type EnumValue = number | string | null;
+/**
+ * One entry from a `list_authorized_clients` reply. Tesla has not published this
+ * schema, so anything else on an entry is available through `raw`.
+ */
+export type AuthorizedClient = {
+  public_key: string | null;
+  state: EnumValue;
+  roles: EnumValue[] | null;
+  verification: EnumValue;
+  raw: Json;
+};
+/**
+ * A parsed `list_authorized_clients` reply. A null body or an unknown shape
+ * raises `InvalidResponse` rather than reading as "no clients": the endpoint
+ * intermittently answers HTTP 200 with a null body. A genuinely empty list
+ * parses to `clients: []`.
+ */
+export type AuthorizedClients = {
+  clients: AuthorizedClient[];
+  raw: unknown;
+};
+/**
+ * Parse a raw `list_authorized_clients` reply: a bare list,
+ * `{response: {authorized_clients: [...]}}` or `{response: {clients: [...]}}`.
+ * @throws InvalidResponse for a null body or any other shape.
+ */
+export declare function parse_authorized_clients(payload: unknown): AuthorizedClients;
+/**
+ * Pick the gateway's LAN IPv4 address from a `networking_status` reply, with or
+ * without the `response` envelope. Considers `eth` and `wifi` only, never `gsm`:
+ * an interface with `active_route` wins, then the first with any decodable address.
+ * @returns The address, or `null` when a well-formed reply has no usable interface.
+ * @throws InvalidResponse for a null body or a reply of another shape.
+ */
+export declare function parse_gateway_address(body: unknown): string | null;
+export {};

package/dist/energyparsers.d.mts

@@ -0,0 +1,39 @@
+type Json = Record<string, unknown>;
+/** A value typed against an enum: its number, or as received when unrecognized, or `null` when absent. */
+export type EnumValue = number | string | null;
+/**
+ * One entry from a `list_authorized_clients` reply. Tesla has not published this
+ * schema, so anything else on an entry is available through `raw`.
+ */
+export type AuthorizedClient = {
+  public_key: string | null;
+  state: EnumValue;
+  roles: EnumValue[] | null;
+  verification: EnumValue;
+  raw: Json;
+};
+/**
+ * A parsed `list_authorized_clients` reply. A null body or an unknown shape
+ * raises `InvalidResponse` rather than reading as "no clients": the endpoint
+ * intermittently answers HTTP 200 with a null body. A genuinely empty list
+ * parses to `clients: []`.
+ */
+export type AuthorizedClients = {
+  clients: AuthorizedClient[];
+  raw: unknown;
+};
+/**
+ * Parse a raw `list_authorized_clients` reply: a bare list,
+ * `{response: {authorized_clients: [...]}}` or `{response: {clients: [...]}}`.
+ * @throws InvalidResponse for a null body or any other shape.
+ */
+export declare function parse_authorized_clients(payload: unknown): AuthorizedClients;
+/**
+ * Pick the gateway's LAN IPv4 address from a `networking_status` reply, with or
+ * without the `response` envelope. Considers `eth` and `wifi` only, never `gsm`:
+ * an interface with `active_route` wins, then the first with any decodable address.
+ * @returns The address, or `null` when a well-formed reply has no usable interface.
+ * @throws InvalidResponse for a null body or a reply of another shape.
+ */
+export declare function parse_gateway_address(body: unknown): string | null;
+export {};

package/dist/energyparsers.mjs

@@ -0,0 +1,116 @@
+import { AuthorizationRole, AuthorizedClientState, AuthorizedVerificationType } from "./const.mjs";
+import { InvalidResponse } from "./exceptions.mjs";
+// src/energyparsers.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The first present key's value. Tests presence, so a legal falsy value is never read as missing. */
+function field(payload, ...keys) {
+	for (const key of keys) if (Object.hasOwn(payload, key)) return payload[key];
+	return null;
+}
+/**
+* Type a raw value against an enum. A recognized number or member name
+* (case-insensitive) becomes the member's number. A present but unrecognized
+* value stays as received, because only an absent field means `null`.
+*/
+function normalizeEnum(members, value) {
+	if (typeof value === "string") {
+		const name = value.trim().toUpperCase();
+		return Object.hasOwn(members, name) ? members[name] : value;
+	}
+	return value;
+}
+function parseClient(payload) {
+	const roles = field(payload, "roles");
+	return {
+		public_key: field(payload, "public_key", "publicKey"),
+		state: normalizeEnum(AuthorizedClientState, field(payload, "state", "authorized_client_state")),
+		roles: Array.isArray(roles) ? roles.map((role) => normalizeEnum(AuthorizationRole, role)) : null,
+		verification: normalizeEnum(AuthorizedVerificationType, field(payload, "verification")),
+		raw: payload
+	};
+}
+function authorizedClientsList(payload) {
+	if (payload === null || payload === void 0) throw new InvalidResponse("authorized_clients response body was null");
+	if (Array.isArray(payload)) return payload;
+	if (!isRecord(payload)) throw new InvalidResponse(String(payload));
+	const value = field(isRecord(payload.response) ? payload.response : payload, "authorized_clients", "clients");
+	if (!Array.isArray(value)) throw new InvalidResponse(payload);
+	return value;
+}
+/**
+* Parse a raw `list_authorized_clients` reply: a bare list,
+* `{response: {authorized_clients: [...]}}` or `{response: {clients: [...]}}`.
+* @throws InvalidResponse for a null body or any other shape.
+*/
+function parse_authorized_clients(payload) {
+	return {
+		clients: authorizedClientsList(payload).filter(isRecord).map(parseClient),
+		raw: payload
+	};
+}
+const OCTET = "(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])";
+const DOTTED_QUAD = new RegExp(`^${OCTET}\\.${OCTET}\\.${OCTET}\\.${OCTET}$`);
+/**
+* Decode a `networking_status` ipv4 field. The live API serves a strict dotted
+* quad; the big-endian uint32 form is accepted too. `0.0.0.0` and
+* `255.255.255.255` are never a usable host, in either form. Anything else
+* decodes to `null`, so one bad field cannot fail the lookup.
+*/
+function decodeIpv4(value) {
+	if (typeof value === "number") {
+		if (!Number.isInteger(value) || value <= 0 || value >= 4294967295) return null;
+		return [
+			value >>> 24,
+			value >>> 16 & 255,
+			value >>> 8 & 255,
+			value & 255
+		].join(".");
+	}
+	if (typeof value === "string" && DOTTED_QUAD.test(value) && value !== "0.0.0.0" && value !== "255.255.255.255") return value;
+	return null;
+}
+/**
+* Whether `address` is a dotted-quad IPv4 address in a private range (RFC 1918) or
+* the link-local range: the only places a gateway's LAN address can be. Anything
+* else, including a hostname or a `host:port`, is not.
+*/
+function is_lan_address(address) {
+	if (!DOTTED_QUAD.test(address)) return false;
+	const [first, second] = address.split(".").map(Number);
+	return first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 169 && second === 254;
+}
+function interfaceAddress(networkInterface) {
+	if (!isRecord(networkInterface)) return null;
+	const ipv4 = networkInterface.ipv4_config;
+	return isRecord(ipv4) ? decodeIpv4(ipv4.address) : null;
+}
+function networkingStatusBody(payload) {
+	if (payload === null || payload === void 0) throw new InvalidResponse("networking_status response body was null");
+	if (!isRecord(payload)) throw new InvalidResponse(String(payload));
+	if (!Object.hasOwn(payload, "response")) return payload;
+	if (!isRecord(payload.response)) throw new InvalidResponse(payload);
+	return payload.response;
+}
+/**
+* Pick the gateway's LAN IPv4 address from a `networking_status` reply, with or
+* without the `response` envelope. Considers `eth` and `wifi` only, never `gsm`:
+* an interface with `active_route` wins, then the first with any decodable address.
+* @returns The address, or `null` when a well-formed reply has no usable interface.
+* @throws InvalidResponse for a null body or a reply of another shape.
+*/
+function parse_gateway_address(body) {
+	const status = networkingStatusBody(body);
+	const interfaces = [status.eth, status.wifi];
+	for (const networkInterface of interfaces) if (isRecord(networkInterface) && networkInterface.active_route) {
+		const address = interfaceAddress(networkInterface);
+		if (address !== null) return address;
+	}
+	for (const networkInterface of interfaces) {
+		const address = interfaceAddress(networkInterface);
+		if (address !== null) return address;
+	}
+	return null;
+}
+export { is_lan_address, parse_authorized_clients, parse_gateway_address };