Add BYD vehicle telemetry exporter

Go port of the read path of pybyd 0.0.75 (the client behind
jkaberg/hass-byd-vehicle): the bangcle white-box AES envelope, the
signing/checkcode layer, login, vehicle list, and realtime readings.

Scraping runs on a cron schedule rather than per Prometheus request
because each reading wakes the car's T-Box and drains the traction
battery; /metrics serves the last result.

Every numeric field of the realtime payload becomes a gauge, so the
exporter does not need a hand-maintained field list that goes stale
when BYD changes the payload.

Tests pin the wire format against pybyd byte-for-byte and drive the
client end to end against a fake cloud that speaks the real protocol.

Co-Authored-By: Claude Opus 5 <[email protected]>

internal/jsonv/jsonv.go

@@ -0,0 +1,54 @@
+// Package jsonv coerces values out of BYD's loosely typed JSON.
+//
+// The same field arrives as a JSON number in one response and a quoted string
+// in the next, and absent fields arrive as null rather than being omitted, so
+// every read goes through here rather than through a type assertion.
+package jsonv
+
+import (
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+)
+
+// Str renders a value as a string, mapping nil to "" rather than "<nil>".
+func Str(v any) string {
+	switch t := v.(type) {
+	case nil:
+		return ""
+	case string:
+		return t
+	case float64:
+		// JSON has no integers, so ids and codes arrive as float64. Exponent
+		// notation would corrupt them ("1.23456789e+09" as a user id), so
+		// integral values are rendered as integers.
+		if t == math.Trunc(t) && math.Abs(t) < 1e15 {
+			return strconv.FormatInt(int64(t), 10)
+		}
+		return strconv.FormatFloat(t, 'g', -1, 64)
+	case bool:
+		return strconv.FormatBool(t)
+	default:
+		return fmt.Sprint(v)
+	}
+}
+
+// Num coerces a value to a float. It reports false for anything that is not a
+// number, a bool, or a string holding a number.
+func Num(v any) (float64, bool) {
+	switch t := v.(type) {
+	case float64:
+		return t, true
+	case bool:
+		if t {
+			return 1, true
+		}
+		return 0, true
+	case string:
+		f, err := strconv.ParseFloat(strings.TrimSpace(t), 64)
+		return f, err == nil
+	default:
+		return 0, false
+	}
+}

internal/jsonv/jsonv_test.go

@@ -0,0 +1,74 @@
+package jsonv
+
+import (
+	"encoding/json"
+	"math"
+	"testing"
+)
+
+func TestStr(t *testing.T) {
+	tests := []struct {
+		in   any
+		want string
+	}{
+		{nil, ""},
+		{"abc", "abc"},
+		{float64(42), "42"},
+		{float64(13.5), "13.5"},
+		{true, "true"},
+		{[]any{1}, "[1]"},
+	}
+	for _, tt := range tests {
+		if got := Str(tt.in); got != tt.want {
+			t.Errorf("Str(%v) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+}
+
+// TestStrOnDecodedJSON is the case that matters: userId comes back as a JSON
+// number, and formatting it as "42" rather than "4.2e+01" is what makes it
+// usable as an identifier in later requests.
+func TestStrOnDecodedJSON(t *testing.T) {
+	var v map[string]any
+	if err := json.Unmarshal([]byte(`{"userId":1234567890}`), &v); err != nil {
+		t.Fatal(err)
+	}
+	if got, want := Str(v["userId"]), "1234567890"; got != want {
+		t.Errorf("Str(userId) = %q, want %q", got, want)
+	}
+}
+
+func TestNum(t *testing.T) {
+	tests := []struct {
+		in     any
+		want   float64
+		wantOK bool
+	}{
+		{float64(82), 82, true},
+		{"82", 82, true},
+		{" 13.5 ", 13.5, true},
+		{true, 1, true},
+		{false, 0, true},
+		{"", 0, false},
+		{"abc", 0, false},
+		{nil, 0, false},
+		{map[string]any{}, 0, false},
+		{[]any{}, 0, false},
+	}
+	for _, tt := range tests {
+		got, ok := Num(tt.in)
+		if ok != tt.wantOK || (ok && got != tt.want) {
+			t.Errorf("Num(%#v) = (%v, %v), want (%v, %v)", tt.in, got, ok, tt.want, tt.wantOK)
+		}
+	}
+}
+
+func TestNumRejectsNonFinite(t *testing.T) {
+	// A NaN or Inf would render as an invalid metric value, so it is better to
+	// know which way these go.
+	for _, s := range []string{"NaN", "Inf", "+Inf"} {
+		if v, ok := Num(s); ok && !math.IsNaN(v) && !math.IsInf(v, 0) {
+			t.Errorf("Num(%q) = %v, expected NaN/Inf or a rejection", s, v)
+		}
+	}
+}