Read spending from zenmoney in the poller, answer it from facts (#125)

The trust boundary is zenmoney, not maven — they already hold his bank sessions. So the poller reads /v8/diff/ and writes totals as facts(kind=env, source=poll:zenmoney); core reads those back when he asks and never sees the token. internal/zenmoney sums transactions per currency over a window, skipping tombstoned rows and transfers between his own accounts, and refuses to encode a summary built from zero transactions. That refusal is the whole design: a failed or empty read writes nothing and leaves the last good total alone, because a zero recited as fact is worse than silence. No currency conversion either — a figure he can check against his bank beats one he cannot. Off unless configured, and the token is read from a FILE rather than a flag so it never lands in `ps`, in docker-compose.yml, or in shell history. Nothing about the money is search input, no tick rule reads the keys, and the log lines name keys, never figures. The live-credential half is BLOCKED: there is no zenmoney account or token here, so everything is verified against a recorded diff fixture.
2026-08-01 02:50:27 +04:00
parent bf6ccf9aea
commit da647e87d0
13 changed files with 1163 additions and 3 deletions
@@ -9,6 +9,12 @@
 // Two sources, each its own provenance (the loop's rules trust source):
 //   - netdata  → poll:netdata      resource alarms (disk/mem/cert/temp)
 //   - kuma     → poll:uptimekuma   service up/down (the source of truth for it)
+//   - zenmoney → poll:zenmoney     spending/income totals (Vikunja #125)
+//
+// The zenmoney source is why the token lives HERE and not in core: the poller
+// already owns every other third-party credential, it holds no store key, and
+// core never needs to know an account exists to answer a question about a fact
+// the poller wrote. It is off unless -zenmoney-token-file is given.
 //
 // Netdata needs no auth over the wg-fronted net. Kuma's /metrics needs an API
 // key (basic-auth); without -kuma the whole kuma path is skipped (netdata-only
@@ -37,6 +43,7 @@ import (
 	"time"

 	"github.com/kami/maven/internal/ipc"
+	"github.com/kami/maven/internal/zenmoney"
 )

 func main() {
@@ -52,6 +59,9 @@ func run(args []string) error {
 	netdataURL := fs.String("netdata", "http://127.0.0.1:19999", "netdata base URL ('' to disable)")
 	kumaURL := fs.String("kuma", "", "uptime-kuma metrics URL, e.g. http://127.0.0.1:3001/metrics ('' to disable)")
 	kumaKey := fs.String("kuma-key", "", "uptime-kuma API key (basic-auth username)")
+	zenTokenFile := fs.String("zenmoney-token-file", "", "file holding the zenmoney API token ('' disables money tracking)")
+	zenURL := fs.String("zenmoney-url", zenmoney.DefaultBaseURL, "zenmoney API base URL (tests/self-hosted proxies)")
+	zenInterval := fs.Duration("zenmoney-interval", time.Hour, "how often to read zenmoney (money does not move every minute)")
 	wgIface := fs.String("wg", "", "wireguard interface for the presence signal, e.g. wg0 or 'all' ('' to disable)")
 	wgCmd := fs.String("wg-cmd", "wg", "wg binary (use e.g. 'sudo wg' if the poller lacks CAP_NET_ADMIN)")
 	interval := fs.Duration("interval", 60*time.Second, "poll cadence")
@@ -62,8 +72,24 @@ func run(args []string) error {
 	if *socket == "" {
 		return fmt.Errorf("-socket is required")
 	}
-	if *netdataURL == "" && *kumaURL == "" && *wgIface == "" {
-		return fmt.Errorf("nothing to poll: set -netdata, -kuma and/or -wg")
+	if *netdataURL == "" && *kumaURL == "" && *wgIface == "" && *zenTokenFile == "" {
+		return fmt.Errorf("nothing to poll: set -netdata, -kuma, -wg and/or -zenmoney-token-file")
+	}
+
+	// The token is read from a file, never taken as a flag value: an argv token
+	// is visible in `ps` to every user on the box and lands in the compose file
+	// and the shell history. Read once at start — a rotated token means a
+	// restart, which is cheaper than re-reading his credential every hour.
+	var zen *zenmoney.Client
+	if *zenTokenFile != "" {
+		raw, err := os.ReadFile(*zenTokenFile)
+		if err != nil {
+			return fmt.Errorf("read zenmoney token: %w", err)
+		}
+		zen, err = zenmoney.New(strings.TrimSpace(string(raw)), *zenURL, *timeout*3)
+		if err != nil {
+			return err
+		}
 	}

 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
@@ -83,9 +109,13 @@ func run(args []string) error {
 		kumaKey:    *kumaKey,
 		wgIface:    *wgIface,
 		wgCmd:      *wgCmd,
+		zen:        zen,
+		zenEvery:   *zenInterval,
 	}

-	log.Printf("mavpoll: polling every %s (netdata=%q kuma=%q wg=%q)", *interval, *netdataURL, *kumaURL, *wgIface)
+	// The token is never logged, not even its length.
+	log.Printf("mavpoll: polling every %s (netdata=%q kuma=%q wg=%q zenmoney=%v every %s)",
+		*interval, *netdataURL, *kumaURL, *wgIface, zen != nil, *zenInterval)
 	p.pollOnce(ctx) // fire immediately; don't idle a full interval on start
 	t := time.NewTicker(*interval)
 	defer t.Stop()
@@ -108,6 +138,12 @@ type poller struct {
 	kumaKey    string
 	wgIface    string
 	wgCmd      string
+
+	// zen is nil unless a token file was configured — money tracking is a
+	// capability, off by default like weather and telegram.
+	zen      *zenmoney.Client
+	zenEvery time.Duration
+	zenLast  time.Time
 }

 // pollOnce — one sweep of both sources. A failure in one source logs and does
@@ -129,6 +165,66 @@ func (p *poller) pollOnce(ctx context.Context) {
 			log.Printf("mavpoll: wg: %v", err)
 		}
 	}
+	// Money on its own, much slower cadence: a bank feed that updates hourly
+	// polled every minute is 60 pointless reads of his financial history.
+	if p.zen != nil && now.Sub(p.zenLast) >= p.zenEvery {
+		p.zenLast = now
+		if err := p.pollZenmoney(ctx, now); err != nil {
+			log.Printf("mavpoll: zenmoney: %v", err)
+		}
+	}
+}
+
+// ---- zenmoney: spending/income totals → money facts ------------------------
+
+// pollZenmoney reads today's and this month's totals and writes them as
+// facts(kind=env, source=poll:zenmoney) (Vikunja #125).
+//
+// Two properties this function exists to hold:
+//
+//   - An empty or failed read writes NOTHING. zenmoney.Summary.Value() refuses
+//     to encode a summary built from zero transactions, so a poller that cannot
+//     reach the API leaves the last good fact in place rather than overwriting
+//     it with a zero Maven would then recite as fact.
+//   - Nothing about the money leaves the box except the diff request itself, to
+//     the service that already holds his bank sessions. The totals are written
+//     to the store and read back only when he asks; they are never search input
+//     and no tick rule fires on them.
+//
+// Both windows are read from one diff call each. Two calls an hour against an
+// API whose whole job is this is not worth caching.
+// moneyWindow — one fact key and the period it covers.
+type moneyWindow struct {
+	key      string
+	from, to time.Time
+}
+
+func (p *poller) pollZenmoney(ctx context.Context, now time.Time) error {
+	dFrom, dTo := zenmoney.DayWindow(now)
+	mFrom, mTo := zenmoney.MonthWindow(now)
+	windows := []moneyWindow{
+		{zenmoney.KeySpentToday, dFrom, dTo},
+		{zenmoney.KeySpentMonth, mFrom, mTo},
+	}
+	var firstErr error
+	for _, w := range windows {
+		sum, err := p.zen.Since(ctx, w.from, w.to)
+		if err != nil {
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+		val, ok := sum.Value()
+		if !ok {
+			// Nothing read. Silence, not a zero.
+			continue
+		}
+		if err := p.writeIfChangedRaw(ctx, w.key, zenmoney.Source, val, now); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
 }

 // ---- wireguard: latest handshake → presence signal -------------------------
@@ -301,6 +397,31 @@ func (p *poller) writeIfChanged(ctx context.Context, key, source, val string, no
 	return nil
 }

+// writeIfChangedRaw is writeIfChanged for values that are already JSON (the
+// money facts store an object, not a string). Kept separate rather than
+// generalising writeIfChanged, because the string-valued env facts encoding
+// their own value is the convention the rules rely on.
+//
+// The log line names the key and the source, never the figures: mavpoll's log
+// is not the place his spending ends up.
+func (p *poller) writeIfChangedRaw(ctx context.Context, key, source, jsonVal string, now time.Time) error {
+	prev, err := p.core.LatestFactBySource(ctx, key, source)
+	switch {
+	case err == nil && prev.Value == jsonVal:
+		return nil
+	case err != nil && err != ipc.ErrNoFact && !isNoFact(err):
+		return fmt.Errorf("read %s: %w", key, err)
+	}
+	if _, err := p.core.WriteFact(ctx, ipc.WriteFactReq{
+		Ts: now, Kind: "env", Key: key, Value: jsonVal,
+		Source: source, Confidence: 1.0,
+	}); err != nil {
+		return fmt.Errorf("write %s: %w", key, err)
+	}
+	log.Printf("mavpoll: %s updated (%s)", key, source)
+	return nil
+}
+
 // isNoFact — ErrNoFact rehydrated over the wire is wrapped (fmt.Errorf %w), so
 // errors.Is is the right check; keep a helper so the switch above reads clean.
 func isNoFact(err error) bool {
@@ -1,8 +1,17 @@
 package main

 import (
+	"context"
 	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
 	"testing"
+	"time"
+
+	"github.com/kami/maven/internal/ipc"
+	"github.com/kami/maven/internal/zenmoney"
 )

 func TestMaxSeverity(t *testing.T) {
@@ -62,3 +71,120 @@ func TestParseMaxHandshake(t *testing.T) {
 		}
 	}
 }
+
+// ---- zenmoney (Vikunja #125) ----------------------------------------------
+
+// factCore records the facts the poller wrote and answers "no fact yet".
+type factCore struct {
+	ipc.UnimplementedCoreAPI
+
+	written []ipc.WriteFactReq
+	prev    map[string]string
+}
+
+func (c *factCore) LatestFactBySource(_ context.Context, key, source string) (ipc.Fact, error) {
+	if v, ok := c.prev[key+"|"+source]; ok {
+		return ipc.Fact{Key: key, Source: source, Value: v}, nil
+	}
+	return ipc.Fact{}, ipc.ErrNoFact
+}
+
+func (c *factCore) WriteFact(_ context.Context, req ipc.WriteFactReq) (int64, error) {
+	c.written = append(c.written, req)
+	return int64(len(c.written)), nil
+}
+
+func zenFixtureServer(t *testing.T, body []byte, status int) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if status != http.StatusOK {
+			w.WriteHeader(status)
+			return
+		}
+		w.Write(body)
+	}))
+}
+
+func TestPollZenmoneyWritesMoneyFacts(t *testing.T) {
+	body, err := os.ReadFile("../../internal/zenmoney/testdata/diff.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	srv := zenFixtureServer(t, body, http.StatusOK)
+	defer srv.Close()
+	zen, err := zenmoney.New("tok", srv.URL, time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	core := &factCore{}
+	p := &poller{core: core, zen: zen}
+	now := time.Date(2026, 8, 1, 21, 0, 0, 0, time.UTC)
+	if err := p.pollZenmoney(context.Background(), now); err != nil {
+		t.Fatal(err)
+	}
+	if len(core.written) != 2 {
+		t.Fatalf("wrote %d facts, want today + month", len(core.written))
+	}
+	for _, f := range core.written {
+		if f.Kind != "env" || f.Source != zenmoney.Source {
+			t.Errorf("fact = %+v, want kind=env source=%s", f, zenmoney.Source)
+		}
+		if _, err := zenmoney.ParseFactValue(f.Value); err != nil {
+			t.Errorf("fact value %q does not decode: %v", f.Value, err)
+		}
+	}
+}
+
+// A read that returns nothing for the window writes NOTHING. Silence, not a
+// zero: an invented 0 would be recited back to him as fact.
+func TestPollZenmoneyWritesNothingWhenEmpty(t *testing.T) {
+	srv := zenFixtureServer(t, []byte(`{"serverTimestamp":1,"instrument":[],"transaction":[]}`), http.StatusOK)
+	defer srv.Close()
+	zen, _ := zenmoney.New("tok", srv.URL, time.Second)
+	core := &factCore{}
+	p := &poller{core: core, zen: zen}
+	if err := p.pollZenmoney(context.Background(), time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if len(core.written) != 0 {
+		t.Errorf("wrote %+v, want no fact at all", core.written)
+	}
+}
+
+// An API failure must not overwrite the last good total either.
+func TestPollZenmoneyFailureWritesNothing(t *testing.T) {
+	srv := zenFixtureServer(t, nil, http.StatusUnauthorized)
+	defer srv.Close()
+	zen, _ := zenmoney.New("bad", srv.URL, time.Second)
+	core := &factCore{}
+	p := &poller{core: core, zen: zen}
+	if err := p.pollZenmoney(context.Background(), time.Now()); err == nil {
+		t.Error("want the 401 reported")
+	}
+	if len(core.written) != 0 {
+		t.Errorf("wrote %+v on a failed read", core.written)
+	}
+}
+
+// Unchanged totals do not churn the facts table.
+func TestWriteIfChangedRawSkipsUnchanged(t *testing.T) {
+	core := &factCore{prev: map[string]string{
+		zenmoney.KeySpentToday + "|" + zenmoney.Source: `{"count":1}`,
+	}}
+	p := &poller{core: core}
+	if err := p.writeIfChangedRaw(context.Background(), zenmoney.KeySpentToday, zenmoney.Source, `{"count":1}`, time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if len(core.written) != 0 {
+		t.Errorf("wrote %+v for an unchanged value", core.written)
+	}
+}
+
+// Money tracking is off unless configured: no token file, no zenmoney client,
+// and the poller still refuses to start with nothing at all to poll.
+func TestRunRequiresSomethingToPoll(t *testing.T) {
+	err := run([]string{"-socket", "/tmp/nope.sock", "-netdata", "", "-kuma", "", "-wg", ""})
+	if err == nil || !strings.Contains(err.Error(), "nothing to poll") {
+		t.Errorf("err = %v, want a 'nothing to poll' refusal", err)
+	}
+}