trainbud 0.5.0

package/dist/utils/logger.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import pino from "pino";
+import { appConfig } from "../config.js";
+import { restrictExistingFile } from "./secretFile.js";
+let loggerInstance = null;
+/**
+ * pino.transport() runs pino-pretty in a worker thread, and a live worker keeps
+ * the Node event loop open. Nothing here ever closes the logger, so a process
+ * whose only remaining handle was the transport -- `node --test`, a CI step,
+ * any short-lived command -- would sometimes finish all its work and then hang
+ * until something killed it. It was intermittent because it depended on whether
+ * the worker had wound down on its own by the time the last test ended.
+ *
+ * Colour and column alignment are only worth anything on an attached terminal.
+ * Everywhere else, write plain NDJSON straight to fd 2 with no worker at all.
+ */
+function prettyStderrStream() {
+    if (!process.stderr.isTTY) {
+        return pino.destination(2);
+    }
+    return pino.transport({
+        target: "pino-pretty",
+        options: {
+            colorize: true,
+            translateTime: "SYS:standard",
+            destination: 2,
+        },
+    });
+}
+/**
+ * Shared options, and the reason this file has any.
+ *
+ * pino applies its built-in Error serializer to the key `err` and to nothing
+ * else. This codebase logs `{ error }` in twenty places and `{ err }` in three,
+ * and an Error has no enumerable own properties -- so twenty of those wrote
+ * literally `"error":{}` to the log file. The server's error log recorded that
+ * something failed and never once recorded why.
+ *
+ * Found by reading the log after "History catch-up failed" and discovering the
+ * cause had been thrown away by the line that was supposed to preserve it. That
+ * is the same fault as the rest of this release: a diagnostic that names
+ * nothing. Both keys are now serialized, so neither spelling loses the message
+ * or the stack.
+ */
+function baseOptions() {
+    return {
+        level: process.env.LOG_LEVEL ?? "info",
+        serializers: {
+            err: pino.stdSerializers.err,
+            error: pino.stdSerializers.err,
+        },
+    };
+}
+function createStderrLogger() {
+    return pino(baseOptions(), prettyStderrStream());
+}
+function createFileLogger(logPath) {
+    const directory = path.dirname(logPath);
+    fs.mkdirSync(directory, { recursive: true });
+    // The log records every request path and, on this machine, still contains an
+    // API key written before the query string was redacted. pino creates the file
+    // at the process umask, which is 0644 on a default install.
+    if (!fs.existsSync(logPath)) {
+        fs.writeFileSync(logPath, "", { mode: 0o600 });
+    }
+    restrictExistingFile(logPath);
+    return pino(baseOptions(), pino.multistream([
+        {
+            stream: pino.destination({
+                dest: logPath,
+                sync: false,
+                mkdir: true,
+            }),
+        },
+        {
+            stream: prettyStderrStream(),
+        },
+    ]));
+}
+function getLogger() {
+    if (!loggerInstance) {
+        loggerInstance = createStderrLogger();
+    }
+    return loggerInstance;
+}
+export function configureLogger(logPath = appConfig.logPath) {
+    loggerInstance = createFileLogger(logPath);
+}
+export const logger = new Proxy({}, {
+    get(_target, property, receiver) {
+        const instance = getLogger();
+        const value = Reflect.get(instance, property, receiver);
+        return typeof value === "function" ? value.bind(instance) : value;
+    },
+});
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,IAAI,cAAc,GAAkB,IAAI,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB;IACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE;YACP,QAAQ,EAAE,IAAI;YACd,aAAa,EAAE,cAAc;YAC7B,WAAW,EAAE,CAAC;SACf;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,WAAW;IAClB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;QACtC,WAAW,EAAE;YACX,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG;YAC5B,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG;SAC/B;KACF,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB;IACzB,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,6EAA6E;IAC7E,8EAA8E;IAC9E,4DAA4D;IAC5D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAE9B,OAAO,IAAI,CACT,WAAW,EAAE,EACb,IAAI,CAAC,WAAW,CAAC;QACf;YACE,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC;gBACvB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,KAAK;gBACX,KAAK,EAAE,IAAI;aACZ,CAAC;SACH;QACD;YACE,MAAM,EAAE,kBAAkB,EAAE;SAC7B;KACF,CAAC,CACH,CAAC;AACJ,CAAC;AAED,SAAS,SAAS;IAChB,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,cAAc,GAAG,kBAAkB,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO;IACzD,cAAc,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAW,IAAI,KAAK,CAAC,EAAY,EAAE;IACpD,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ;QAC7B,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACxD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,CAAC;CACF,CAAC,CAAC"}

package/dist/utils/secretFile.d.ts

@@ -0,0 +1,15 @@
+export declare function writeSecretFile(filePath: string, contents: string): void;
+/**
+ * Tighten a file this process did not write itself.
+ *
+ * `.trainbud/app.db` is created by better-sqlite3, not by writeSecretFile, so it
+ * missed the hardening the other three credential files got -- and it holds the
+ * Anthropic API key the dashboard saves, in the clear, in a table. It landed
+ * 0644 like every other SQLite file, readable by every account on the machine.
+ *
+ * Silent on failure on purpose: a database that cannot be chmod'ed is still a
+ * working database, and refusing to start over a permission bit would be a
+ * worse outcome than the bit.
+ */
+export declare function restrictExistingFile(filePath: string): void;
+//# sourceMappingURL=secretFile.d.ts.map

package/dist/utils/secretFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretFile.d.ts","sourceRoot":"","sources":["../../src/utils/secretFile.ts"],"names":[],"mappings":"AAkBA,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAS3D"}

package/dist/utils/secretFile.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+// SECTION: Secret files on disk
+//
+// Three files this server writes are credentials in the clear: `.env` (the
+// Connect password and the API key), `.trainbud/session.json` (live OAuth
+// tokens for the Connect account) and the MCP client config (the same Connect
+// password, written into an editor's config directory). All three were written
+// with writeFileSync's default mode, so on Linux and macOS they landed as 0644
+// and every other account on the machine could read them.
+//
+// The chmod is not redundant: writeFileSync applies `mode` when it creates a
+// file, not when it truncates an existing one, so a file written by an earlier
+// version keeps its old permissions forever without it.
+const OWNER_ONLY = 0o600;
+export function writeSecretFile(filePath, contents) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, contents, { encoding: "utf8", mode: OWNER_ONLY });
+    // Windows has no POSIX bits and chmod there is a no-op at best.
+    if (process.platform !== "win32") {
+        fs.chmodSync(filePath, OWNER_ONLY);
+    }
+}
+/**
+ * Tighten a file this process did not write itself.
+ *
+ * `.trainbud/app.db` is created by better-sqlite3, not by writeSecretFile, so it
+ * missed the hardening the other three credential files got -- and it holds the
+ * Anthropic API key the dashboard saves, in the clear, in a table. It landed
+ * 0644 like every other SQLite file, readable by every account on the machine.
+ *
+ * Silent on failure on purpose: a database that cannot be chmod'ed is still a
+ * working database, and refusing to start over a permission bit would be a
+ * worse outcome than the bit.
+ */
+export function restrictExistingFile(filePath) {
+    if (process.platform === "win32") {
+        return;
+    }
+    try {
+        fs.chmodSync(filePath, OWNER_ONLY);
+    }
+    catch {
+        // Nothing useful to do: the data still works, the bits do not.
+    }
+}
+//# sourceMappingURL=secretFile.js.map

package/dist/utils/secretFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretFile.js","sourceRoot":"","sources":["../../src/utils/secretFile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,0DAA0D;AAC1D,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,wDAAwD;AAExD,MAAM,UAAU,GAAG,KAAK,CAAC;AAEzB,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,QAAgB;IAChE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAE7E,gEAAgE;IAChE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC"}

package/dist/utils/stdio.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Send every console method that defaults to stdout to stderr instead.
+ *
+ * Idempotent: calling it twice must not capture the already-redirected
+ * functions as the originals, or `restoreStdout` would restore the redirect and
+ * make it permanent.
+ */
+export declare function protectStdout(): void;
+export declare function restoreStdout(): void;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/utils/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/utils/stdio.ts"],"names":[],"mappings":"AAgCA;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAYpC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAapC"}

package/dist/utils/stdio.js

@@ -0,0 +1,70 @@
+// SECTION: Claiming stdout for the MCP protocol
+//
+// `trainbud start` runs StdioServerTransport on stdout. Every byte on that
+// stream has to be JSON-RPC, and `console.log` writes to stdout.
+//
+// garmin-connect does this, at HttpClient.js:354:
+//
+//     console.log('login page title:', title);
+//
+// so any re-login inside a tool call injects two lines of English into the
+// middle of the protocol stream and the client -- Claude Desktop, Cursor, the
+// product's primary surface -- loses the session. The user sees the AI lose
+// access to their data, which in this release has now had three distinct
+// causes.
+//
+// `withQuietUpstreamErrors` in garmin/client.ts already existed for exactly
+// this hazard and covered `console.error` only, scoped to the login call.
+// Adding `console.log` beside it would have been the same fix in the same
+// shape a fourth time, and it would still leave every other dependency, and
+// every future one, able to reach stdout. A transport cannot be correct because
+// today's libraries happen to be polite.
+//
+// So stdout is claimed for the lifetime of the process instead. `console.*`
+// goes to stderr, where the logger already writes and where a person can still
+// read it; the transport keeps writing to `process.stdout` directly, untouched.
+const REDIRECTED = ["log", "info", "debug", "dir"];
+let original = null;
+/**
+ * Send every console method that defaults to stdout to stderr instead.
+ *
+ * Idempotent: calling it twice must not capture the already-redirected
+ * functions as the originals, or `restoreStdout` would restore the redirect and
+ * make it permanent.
+ */
+export function protectStdout() {
+    if (original) {
+        return;
+    }
+    original = {};
+    for (const method of REDIRECTED) {
+        original[method] = console[method].bind(console);
+        console[method] = (...args) => {
+            process.stderr.write(`${args.map(formatArgument).join(" ")}\n`);
+        };
+    }
+}
+export function restoreStdout() {
+    if (!original) {
+        return;
+    }
+    for (const method of REDIRECTED) {
+        const restored = original[method];
+        if (restored) {
+            console[method] = restored;
+        }
+    }
+    original = null;
+}
+function formatArgument(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=stdio.js.map

package/dist/utils/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/utils/stdio.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,2EAA2E;AAC3E,iEAAiE;AACjE,EAAE;AACF,kDAAkD;AAClD,EAAE;AACF,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,UAAU;AACV,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAC1E,4EAA4E;AAC5E,gFAAgF;AAChF,yCAAyC;AACzC,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAIhF,MAAM,UAAU,GAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAEpE,IAAI,QAAQ,GAAwE,IAAI,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,QAAQ,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAiC,CAAC;QACjF,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAe,EAAQ,EAAE;YAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClE,CAAC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,MAAM,CAAC,GAAG,QAA8B,CAAC;QACnD,CAAC;IACH,CAAC;IAED,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const packageVersion: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,cAAc,QAAc,CAAC"}

package/dist/version.js

@@ -0,0 +1,7 @@
+import path from "node:path";
+import { readJsonFile } from "./utils/jsonFile.js";
+import { fileURLToPath } from "node:url";
+const packageJsonPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const pkg = readJsonFile(packageJsonPath);
+export const packageVersion = pkg.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAC/B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,EACJ,cAAc,CACf,CAAC;AAEF,MAAM,GAAG,GAAG,YAAY,CAAsB,eAAe,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC,OAAO,CAAC"}

package/dist/watchApi.d.ts

@@ -0,0 +1,264 @@
+import { DateTime } from "luxon";
+import { type MetricState } from "./profile.js";
+import { type WeekReview } from "./detect/week.js";
+import { type RaceCountdown } from "./detect/countdown.js";
+import { type ContextEntry } from "./history/context.js";
+import type { Finding } from "./detect/findings.js";
+import type { HeartRatePayload, LatestActivityPayload, RecoveryPayload, SleepPayload, StressPayload, Vo2MaxPayload } from "./tools/payloads.js";
+export interface WatchRecovery {
+    score: number;
+    label: string;
+}
+export interface WatchSleep {
+    hours: number;
+    score: number | null;
+    label: string;
+}
+export interface WatchActivity {
+    name: string;
+    /**
+     * Kilometres, always. Kept unconditionally metric because a build already on
+     * someone's wrist reads this field and would silently relabel miles as km:
+     * fields may be added here, never redefined.
+     */
+    distance_km: number | null;
+    /**
+     * The same distance already written in the user's own units, e.g. "3.11 mi".
+     * Added rather than converting the field above, for the reason given there.
+     * A watch too old to know about it goes on drawing kilometres, which is what
+     * it has always drawn.
+     */
+    distance_display: string | null;
+    duration_min: number | null;
+    avg_hr: number | null;
+    date: string;
+}
+export interface WatchHeartRate {
+    resting: number;
+    max: number | null;
+}
+export interface WatchDailyOverview {
+    recovery: number | null;
+    sleep_h: number | null;
+    stress: number | null;
+    vo2max: number | null;
+}
+export interface WatchStress {
+    avg: number;
+    label: string;
+}
+export interface WatchVo2Max {
+    value: number;
+    trend: string;
+}
+/**
+ * The watch gets the sentence, not the numbers to build one. It cannot wrap
+ * arbitrary text well -- a fixed-font activity name already clips on a 390 px
+ * round screen -- so the detail paragraph and the raw values stay on the server.
+ */
+export interface WatchFinding {
+    kind: string;
+    severity: string;
+    headline: string;
+}
+export interface WatchCoverage {
+    days: number;
+    ready: boolean;
+    /** Newest date the store holds any measurement for, or null when empty. */
+    throughDate: string | null;
+    /**
+     * How many days old that is. `ready` is false once this passes the grace
+     * period: a store that stopped three weeks ago has plenty of days and nothing
+     * recent to compare, and "nothing stands out" would be a claim about a day
+     * that was never recorded.
+     */
+    staleDays: number;
+}
+/**
+ * The week, compressed to what a 208 px screen can hold.
+ *
+ * Deliberately a handful of scalars rather than the whole WeekReview: the watch
+ * response is parsed on the device, a body Connect IQ cannot hold comes back as
+ * -402 NETWORK_RESPONSE_TOO_LARGE, and every field here has to be drawn by hand
+ * anyway. The full review stays on the server, where `get_week_review` and the
+ * dashboard can render it in as much detail as they like.
+ */
+export interface WatchWeek {
+    sessions: number;
+    previous_sessions: number;
+    moving_minutes: number;
+    /** TRIMP this week against last week, as a whole-number percentage. */
+    load_delta_pct: number | null;
+    sleep_debt_h: number | null;
+    /** This person's own habitual night, in hours. Not eight. */
+    sleep_habitual_h: number | null;
+    sleep_consistency: "steady" | "variable" | "erratic" | "unknown";
+    /** Where the acute:chronic ratio lands if next week repeats this one. */
+    forecast_ratio: number | null;
+    forecast_verdict: "spike_ahead" | "detraining_ahead" | "on_track" | "unknown";
+    ready: boolean;
+    headline: string;
+}
+export interface WatchRace {
+    text: string;
+    days_away: number;
+    phase: "race_week" | "taper" | "build" | "far_out";
+}
+/**
+ * What each metric means, already decided.
+ *
+ * The watch used to grade these itself: `recoveryColor`, `sleepColor`,
+ * `stressColor` and `heartRateColor` were four copies of four thresholds in
+ * Monkey C, so the wrist and the browser could disagree about whether the same
+ * score was good, and nothing reconciled them. Personalising the bands would
+ * have made that disagreement permanent -- the watch has no idea what the user
+ * set in the dashboard, and shipping the numbers to it would mean two
+ * implementations of the same comparison, one of which is in a language with
+ * no tests.
+ *
+ * So the server grades, and the watch colours. `unknown` is a real answer and
+ * has to survive to the screen: an unworn watch is not a recovery score of
+ * zero, and a card that renders an absence in red has invented a measurement.
+ */
+export interface WatchStates {
+    recovery: MetricState;
+    sleep: MetricState;
+    stress: MetricState;
+    resting_hr: MetricState;
+}
+/**
+ * How this user wants the app to look, resolved for a client that cannot ask.
+ *
+ * `cards` is the visible carousel in the user's order, by id. The watch walks
+ * this list instead of its own compiled-in constants, so hiding a card or
+ * moving one happens in the dashboard and is live on the next fetch -- no
+ * Connect IQ settings sync, no store update.
+ */
+export interface WatchDisplay {
+    name: string | null;
+    units: "metric" | "imperial";
+    cards: string[];
+}
+/**
+ * The worst thing standing out right now, as one number the watch can badge.
+ *
+ * Findings are already on the payload, but reading them means parsing an array
+ * on a device where that costs memory, and the glance view has room for a dot
+ * and nothing else.
+ */
+export interface WatchAlert {
+    level: "none" | "notice" | "warn";
+    count: number;
+}
+/**
+ * Whether an Ask would be refused before the watch spends a round trip finding
+ * out.
+ *
+ * `exceeded` is only ever true when the user set a cap themselves; there is no
+ * default ceiling. `incomplete` says the total behind that decision is a floor
+ * rather than a total, because some calls could not be priced.
+ */
+export interface WatchBudget {
+    exceeded: boolean;
+    incomplete: boolean;
+}
+export interface WatchSummary {
+    daily_overview: WatchDailyOverview;
+    recovery: WatchRecovery | null;
+    sleep: WatchSleep | null;
+    activity: WatchActivity | null;
+    stress: WatchStress | null;
+    vo2max: WatchVo2Max | null;
+    heart_rate: WatchHeartRate | null;
+    findings: WatchFinding[];
+    coverage: WatchCoverage;
+    /** This week against last week. Null on a server too old to compute it. */
+    week: WatchWeek | null;
+    /** The next race on record, or null when nothing is on the calendar. */
+    race: WatchRace | null;
+    /**
+     * The five Ask prompts for today. The watch reads these instead of the
+     * hardcoded strings in strings.xml, so the menu asks about what actually
+     * happened rather than the same five questions every day.
+     */
+    prompts: string[];
+    ai_insight: string | null;
+    /**
+     * Whether an AI key is configured at all, from either the dashboard or the
+     * environment.
+     *
+     * ai_insight being null does not answer that question: it is also null when
+     * a key exists and the call failed, and when today's insight has simply not
+     * been generated yet. The watch drew one "AI unavailable" screen for all
+     * three, which told the user nothing they could act on -- the same fault the
+     * single "Pairing failed" message had. With this flag the watch can say
+     * "AI is not set up" and name the dashboard.
+     */
+    ai_configured: boolean;
+    /** Each metric already graded against this user's own bands. */
+    states: WatchStates;
+    /** Name, units and the visible carousel, in the user's order. */
+    display: WatchDisplay;
+    /** The worst finding right now, as one badge-able level. */
+    alert: WatchAlert;
+    /** Whether the user's own AI spending cap would refuse an Ask. */
+    budget: WatchBudget;
+    updated_at: string;
+}
+export declare function toWatchRecovery(payload: RecoveryPayload | null): WatchRecovery | null;
+export declare function toWatchSleep(payload: SleepPayload | null): WatchSleep | null;
+export declare function toWatchActivity(payload: LatestActivityPayload | null): WatchActivity | null;
+export declare function toWatchStress(payload: StressPayload | null): WatchStress | null;
+export declare function toWatchVo2Max(payload: Vo2MaxPayload | null): WatchVo2Max | null;
+export declare function toWatchHeartRate(payload: HeartRatePayload | null): WatchHeartRate | null;
+export declare function toWatchFindings(findings: Finding[]): WatchFinding[];
+export interface WatchSummaryParts {
+    recovery: RecoveryPayload | null;
+    sleep: SleepPayload | null;
+    activity: LatestActivityPayload | null;
+    stress: StressPayload | null;
+    vo2max: Vo2MaxPayload | null;
+    heartRate: HeartRatePayload | null;
+    findings: Finding[];
+    coverage: WatchCoverage;
+    context: ContextEntry[];
+    week: WeekReview | null;
+    race: RaceCountdown | null;
+    updatedAt: string;
+    aiConfigured: boolean;
+    /**
+     * Distance from this person's own resting-HR median, or null when there is
+     * not yet enough history to have one. Null and zero are different answers
+     * and the grading has to be able to tell them apart.
+     */
+    restingHrDeltaBpm: number | null;
+}
+/**
+ * The worst severity among the findings, and how many there are.
+ *
+ * `info` deliberately does not raise the level above `none`: an informational
+ * finding is worth a line on the Today card and is not worth a badge on a
+ * watch face.
+ */
+export declare function toWatchAlert(findings: Finding[]): WatchAlert;
+export declare function toWatchWeek(review: WeekReview | null): WatchWeek | null;
+export declare function toWatchRace(race: RaceCountdown | null): WatchRace | null;
+export declare function buildWatchSummaryFrom(parts: WatchSummaryParts): Omit<WatchSummary, "ai_insight">;
+/**
+ * Drop a card the watch would draw as current when it is not.
+ *
+ * The test is the age of the NEWEST day in the card, whatever its source --
+ * not whether the store was involved. Two reasons that is the right question:
+ *
+ *   * A partly stored answer whose recent days came off the wire is current
+ *     where it matters, because every card's headline figure (`nights[0]`,
+ *     `days[0]`) is the newest day.
+ *   * The cache could already serve a day-old reading as "current resting HR"
+ *     before any of this existed. One rule covers both.
+ *
+ * With a healthy connection the newest day is today or yesterday, so this is a
+ * no-op in the normal case.
+ */
+export declare function freshEnoughForWatch<T>(payload: T | null, newestDate: (payload: T) => string | null | undefined, today?: DateTime, graceDays?: number): T | null;
+export declare function buildWatchSummary(): Promise<WatchSummary>;
+//# sourceMappingURL=watchApi.d.ts.map

package/dist/watchApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchApi.d.ts","sourceRoot":"","sources":["../src/watchApi.ts"],"names":[],"mappings":"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"}