hae-vault 0.1.0

package/src/cli/trends.ts

@@ -0,0 +1,103 @@
+import { Command } from 'commander';
+import { openDb } from '../db/schema.js';
+
+function fmt1(n: number): string {
+  return n.toFixed(1);
+}
+
+function fmtInt(n: number): string {
+  return Math.round(n).toLocaleString();
+}
+
+function arrow(values: number[]): string {
+  if (values.length < 2) return '→';
+  const half = Math.floor(values.length / 2);
+  const firstHalfAvg = values.slice(0, half).reduce((a, b) => a + b, 0) / half;
+  const secondHalfAvg = values.slice(half).reduce((a, b) => a + b, 0) / (values.length - half);
+  const delta = secondHalfAvg - firstHalfAvg;
+  if (Math.abs(delta) < 0.01 * Math.abs(firstHalfAvg || 1)) return '→';
+  return delta > 0 ? '↑' : '↓';
+}
+
+interface MetricTrendRow { date: string; avg_qty: number }
+
+function metricTrend(
+  db: ReturnType<typeof openDb>,
+  metricName: string,
+  since: string
+): { values: number[]; avg: number; min: number; max: number } | null {
+  const rows = db.prepare(
+    `SELECT date, AVG(qty) as avg_qty FROM metrics
+     WHERE metric = ? AND date >= ? AND qty IS NOT NULL
+     GROUP BY date ORDER BY date ASC`
+  ).all(metricName, since) as MetricTrendRow[];
+  if (rows.length === 0) return null;
+  const values = rows.map(r => r.avg_qty);
+  const avg = values.reduce((a, b) => a + b, 0) / values.length;
+  return { values, avg, min: Math.min(...values), max: Math.max(...values) };
+}
+
+function sleepTrend(
+  db: ReturnType<typeof openDb>,
+  since: string
+): { values: number[]; avg: number; min: number; max: number } | null {
+  const rows = db.prepare(
+    `SELECT asleep_h FROM sleep WHERE date >= ? AND asleep_h IS NOT NULL ORDER BY date ASC`
+  ).all(since) as { asleep_h: number }[];
+  if (rows.length === 0) return null;
+  const values = rows.map(r => r.asleep_h);
+  const avg = values.reduce((a, b) => a + b, 0) / values.length;
+  return { values, avg, min: Math.min(...values), max: Math.max(...values) };
+}
+
+export const trendsCommand = new Command('trends')
+  .description('Multi-metric trend analysis with averages, ranges, and direction arrows')
+  .option('--days <n>', 'Days of history', '7')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const db = openDb();
+    const days = parseInt(opts.days, 10);
+    const since = new Date();
+    since.setDate(since.getDate() - days);
+    const sinceStr = since.toISOString().slice(0, 10);
+
+    const steps = metricTrend(db, 'step_count', sinceStr);
+    const restingHR = metricTrend(db, 'resting_heart_rate', sinceStr);
+    const hrv = metricTrend(db, 'heart_rate_variability_sdnn', sinceStr);
+    const activeCal = metricTrend(db, 'active_energy_burned', sinceStr);
+    const sleep = sleepTrend(db, sinceStr);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ days, steps, restingHR, hrv, activeCal, sleep }, null, 2));
+      return;
+    }
+
+    const lines: string[] = [];
+    lines.push(`📊 ${days}-Day Trends`);
+    lines.push('');
+
+    function row(
+      emoji: string,
+      label: string,
+      data: { values: number[]; avg: number; min: number; max: number } | null,
+      unit: string,
+      round: boolean
+    ): void {
+      if (!data) return;
+      const dir = arrow(data.values);
+      const fmt = round ? fmtInt : fmt1;
+      lines.push(`${emoji} ${label}: ${fmt(data.avg)} avg (${fmt(data.min)}–${fmt(data.max)}) ${dir}`);
+    }
+
+    row('👟', 'Steps', steps, '', true);
+    row('💓', 'Resting HR', restingHR, 'bpm', true);
+    row('🧠', 'HRV', hrv, 'ms', true);
+    row('😴', 'Sleep', sleep, 'h', false);
+    row('🔥', 'Active Cal', activeCal, 'kcal', true);
+
+    if (lines.length === 2) {
+      lines.push('   No trend data available');
+    }
+
+    console.log(lines.join('\n'));
+  });

package/src/cli/watch.ts

@@ -0,0 +1,111 @@
+import { Command } from 'commander';
+import { readdirSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import type Database from 'better-sqlite3';
+import { openDb } from '../db/schema.js';
+import { ingest } from '../server/ingest.js';
+import { hasBeenImported, logImport } from '../db/importLog.js';
+import { extractPayloadFromZip } from '../util/zip.js';
+import { config } from '../config.js';
+import type { HaePayload } from '../types/hae.js';
+
+const HAE_PATTERN = /^HealthAutoExport.*\.(zip|json)$/i;
+
+function sha256(buf: Buffer): string {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+function loadBuf(buf: Buffer, filename: string): HaePayload | null {
+  if (filename.toLowerCase().endsWith('.zip')) {
+    return extractPayloadFromZip(buf);
+  }
+  try {
+    const p = JSON.parse(buf.toString('utf-8')) as HaePayload;
+    return p?.data ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface TickResult {
+  tick: string;
+  dir: string;
+  found: number;
+  imported: number;
+  skipped: number;
+}
+
+export function tick(db: Database.Database, watchDir: string, target: string): TickResult {
+  const now = new Date().toISOString();
+  let found = 0, imported = 0, skipped = 0;
+
+  let files: string[];
+  try {
+    files = readdirSync(watchDir).filter(f => HAE_PATTERN.test(f));
+  } catch (err) {
+    console.error(JSON.stringify({ error: `Cannot read watch dir: ${String(err)}` }));
+    return { tick: now, dir: watchDir, found, imported, skipped };
+  }
+
+  found = files.length;
+
+  for (const filename of files) {
+    const filepath = join(watchDir, filename);
+    let buf: Buffer;
+    try {
+      buf = readFileSync(filepath);
+    } catch {
+      skipped++;
+      continue;
+    }
+
+    const hash = sha256(buf);
+    if (hasBeenImported(db, hash)) {
+      skipped++;
+      continue;
+    }
+
+    const payload = loadBuf(buf, filename);
+    if (!payload) {
+      skipped++;
+      continue;
+    }
+
+    const result = ingest(db, payload, {
+      target,
+      sessionId: null,
+      automationName: 'watch',
+      automationPeriod: 'manual',
+    });
+
+    logImport(db, filepath, hash, result);
+    console.log(JSON.stringify({ imported: filename, target, ...result }));
+    imported++;
+  }
+
+  const summary: TickResult = { tick: now, dir: watchDir, found, imported, skipped };
+  console.log(JSON.stringify(summary));
+  return summary;
+}
+
+export const watchCommand = new Command('watch')
+  .description('Poll a directory for new HAE exports and auto-import them')
+  .option('--dir <path>', 'Directory to watch', config.watchDir)
+  .option('--interval <seconds>', 'Poll interval in seconds', String(config.watchInterval))
+  .option('--target <name>', 'Target name', config.target)
+  .action((opts) => {
+    const watchDir: string | undefined = opts.dir;
+    if (!watchDir) {
+      console.error(JSON.stringify({ error: 'Watch directory required: use --dir or set HVAULT_WATCH_DIR' }));
+      process.exit(1);
+    }
+
+    const intervalMs = Number(opts.interval) * 1000;
+    const db = openDb(config.dbPath);
+
+    console.log(JSON.stringify({ watching: watchDir, intervalSeconds: Number(opts.interval), target: opts.target }));
+
+    tick(db, watchDir, opts.target);
+    setInterval(() => tick(db, watchDir, opts.target), intervalMs);
+  });

package/src/cli/workouts.ts

@@ -0,0 +1,19 @@
+import { Command } from 'commander';
+import { openDb } from '../db/schema.js';
+
+export const workoutsCommand = new Command('workouts')
+  .description('Query workouts')
+  .option('--days <n>', 'Last N days', '30')
+  .option('--pretty', 'Pretty-print JSON', false)
+  .action((opts) => {
+    const db = openDb();
+    const since = new Date();
+    since.setDate(since.getDate() - parseInt(opts.days, 10));
+    const rows = db.prepare(`
+      SELECT ts, date, name, duration_s, calories_kj, distance, distance_unit, avg_hr, max_hr, target
+      FROM workouts
+      WHERE date >= ?
+      ORDER BY ts ASC
+    `).all(since.toISOString().slice(0, 10));
+    console.log(opts.pretty ? JSON.stringify(rows, null, 2) : JSON.stringify(rows));
+  });

package/src/config.ts

@@ -0,0 +1,28 @@
+import { config as dotenvLoad } from 'dotenv';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function expandTilde(p: string): string {
+  if (p === '~' || p.startsWith('~/')) {
+    return homedir() + p.slice(1);
+  }
+  return p;
+}
+
+// Load .env: HVAULT_ENV_FILE env var overrides; fallback to CWD .env
+const envFile = process.env.HVAULT_ENV_FILE ?? join(process.cwd(), '.env');
+if (existsSync(envFile)) {
+  dotenvLoad({ path: envFile });
+}
+
+const DEFAULT_DB_PATH = join(homedir(), '.hae-vault', 'health.db');
+
+export const config = {
+  dbPath:        expandTilde(process.env.HVAULT_DB_PATH ?? DEFAULT_DB_PATH),
+  port:          Number(process.env.HVAULT_PORT ?? 4242),
+  token:         process.env.HVAULT_TOKEN,
+  watchDir:      process.env.HVAULT_WATCH_DIR ? expandTilde(process.env.HVAULT_WATCH_DIR) : undefined,
+  watchInterval: Number(process.env.HVAULT_WATCH_INTERVAL ?? 60),
+  target:        process.env.HVAULT_TARGET ?? 'default',
+} as const;

package/src/db/importLog.ts

@@ -0,0 +1,18 @@
+import type Database from 'better-sqlite3';
+import type { IngestResult } from '../server/ingest.js';
+
+export function hasBeenImported(db: Database.Database, hash: string): boolean {
+  return db.prepare('SELECT id FROM import_log WHERE file_hash = ?').get(hash) !== undefined;
+}
+
+export function logImport(
+  db: Database.Database,
+  filename: string,
+  hash: string,
+  result: IngestResult,
+): void {
+  db.prepare(`
+    INSERT OR IGNORE INTO import_log (filename, file_hash, imported_at, metrics_added, sleep_added, workouts_added)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(filename, hash, new Date().toISOString(), result.metricsAdded, result.sleepAdded, result.workoutsAdded);
+}

package/src/db/metrics.ts

@@ -0,0 +1,15 @@
+import type Database from 'better-sqlite3';
+import type { NormalizedMetric } from '../parse/metrics.js';
+
+export function upsertMetrics(db: Database.Database, rows: NormalizedMetric[]): void {
+  const stmt = db.prepare(`
+    INSERT OR REPLACE INTO metrics
+      (ts, date, metric, qty, min, avg, max, units, source, target, meta, session_id)
+    VALUES
+      (@ts, @date, @metric, @qty, @min, @avg, @max, @units, @source, @target, @meta, @session_id)
+  `);
+  const insertMany = db.transaction((rows: NormalizedMetric[]) => {
+    for (const row of rows) stmt.run(row);
+  });
+  insertMany(rows);
+}

package/src/db/schema.ts

@@ -0,0 +1,105 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const DEFAULT_DB_PATH = join(homedir(), '.hae-vault', 'health.db');
+
+export function openDb(dbPath = DEFAULT_DB_PATH): Database.Database {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS metrics (
+      id         INTEGER PRIMARY KEY,
+      ts         TEXT NOT NULL,
+      date       TEXT NOT NULL,
+      metric     TEXT NOT NULL,
+      qty        REAL,
+      min        REAL,
+      avg        REAL,
+      max        REAL,
+      units      TEXT,
+      source     TEXT,
+      target     TEXT,
+      meta       TEXT,
+      session_id TEXT,
+      UNIQUE(ts, metric, source, target)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_metrics_date   ON metrics(date);
+    CREATE INDEX IF NOT EXISTS idx_metrics_metric ON metrics(metric);
+
+    CREATE TABLE IF NOT EXISTS sleep (
+      id            INTEGER PRIMARY KEY,
+      date          TEXT NOT NULL,
+      sleep_start   TEXT,
+      sleep_end     TEXT,
+      in_bed_start  TEXT,
+      in_bed_end    TEXT,
+      core_h        REAL,
+      deep_h        REAL,
+      rem_h         REAL,
+      awake_h       REAL,
+      asleep_h      REAL,
+      in_bed_h      REAL,
+      schema_ver    TEXT,
+      source        TEXT,
+      target        TEXT,
+      meta          TEXT,
+      session_id    TEXT,
+      UNIQUE(date, source, target)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sleep_date ON sleep(date);
+
+    CREATE TABLE IF NOT EXISTS workouts (
+      id            INTEGER PRIMARY KEY,
+      ts            TEXT NOT NULL,
+      date          TEXT NOT NULL,
+      name          TEXT NOT NULL,
+      duration_s    INTEGER,
+      calories_kj   REAL,
+      distance      REAL,
+      distance_unit TEXT,
+      avg_hr        REAL,
+      max_hr        REAL,
+      target        TEXT,
+      meta          TEXT,
+      session_id    TEXT,
+      UNIQUE(ts, name, target)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workouts_date ON workouts(date);
+
+    CREATE TABLE IF NOT EXISTS sync_log (
+      id                INTEGER PRIMARY KEY,
+      received_at       TEXT NOT NULL,
+      target            TEXT,
+      session_id        TEXT,
+      metrics_count     INTEGER,
+      workouts_count    INTEGER,
+      automation_name   TEXT,
+      automation_period TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS import_log (
+      id             INTEGER PRIMARY KEY,
+      filename       TEXT NOT NULL,
+      file_hash      TEXT NOT NULL UNIQUE,
+      imported_at    TEXT NOT NULL,
+      metrics_added  INTEGER,
+      sleep_added    INTEGER,
+      workouts_added INTEGER
+    );
+  `);
+
+  return db;
+}
+
+export function closeDb(db: Database.Database): void {
+  db.close();
+}

package/src/db/sleep.ts

@@ -0,0 +1,15 @@
+import type Database from 'better-sqlite3';
+import type { NormalizedSleep } from '../parse/sleep.js';
+
+export function upsertSleep(db: Database.Database, row: NormalizedSleep): void {
+  db.prepare(`
+    INSERT OR REPLACE INTO sleep
+      (date, sleep_start, sleep_end, in_bed_start, in_bed_end,
+       core_h, deep_h, rem_h, awake_h, asleep_h, in_bed_h,
+       schema_ver, source, target, meta, session_id)
+    VALUES
+      (@date, @sleep_start, @sleep_end, @in_bed_start, @in_bed_end,
+       @core_h, @deep_h, @rem_h, @awake_h, @asleep_h, @in_bed_h,
+       @schema_ver, @source, @target, @meta, @session_id)
+  `).run(row);
+}

package/src/db/workouts.ts

@@ -0,0 +1,13 @@
+import type Database from 'better-sqlite3';
+import type { NormalizedWorkout } from '../parse/workouts.js';
+
+export function upsertWorkout(db: Database.Database, row: NormalizedWorkout): void {
+  db.prepare(`
+    INSERT OR REPLACE INTO workouts
+      (ts, date, name, duration_s, calories_kj, distance, distance_unit,
+       avg_hr, max_hr, target, meta, session_id)
+    VALUES
+      (@ts, @date, @name, @duration_s, @calories_kj, @distance, @distance_unit,
+       @avg_hr, @max_hr, @target, @meta, @session_id)
+  `).run(row);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import './config.js';  // load dotenv before any command runs
+import { program } from './cli/index.js';
+program.parse();

package/src/parse/metrics.ts

@@ -0,0 +1,50 @@
+import { parseHaeTime, toIso, toDateStr } from './time.js';
+import type { MetricData, RawDatapoint } from '../types/hae.js';
+
+export interface NormalizedMetric {
+  ts: string;
+  date: string;
+  metric: string;
+  qty: number | null;
+  min: number | null;
+  avg: number | null;
+  max: number | null;
+  units: string;
+  source: string | null;
+  target: string;
+  meta: string | null;
+  session_id: string | null;
+}
+
+export function parseMetric(m: MetricData, target: string, sessionId: string | null): NormalizedMetric[] {
+  if (m.name === 'sleep_analysis') return [];
+
+  return (m.data as RawDatapoint[]).map((dp) => {
+    const d = parseHaeTime(dp.date);
+    const isHeartRate = dp.Min !== undefined || dp.Avg !== undefined || dp.Max !== undefined;
+    const isBloodPressure = dp.systolic !== undefined || dp.diastolic !== undefined;
+
+    let qty: number | null = null;
+    let min: number | null = null;
+    let avg: number | null = null;
+    let max: number | null = null;
+    let meta: string | null = null;
+
+    if (isHeartRate) {
+      min = dp.Min ?? null;
+      avg = dp.Avg ?? null;
+      max = dp.Max ?? null;
+    } else if (isBloodPressure) {
+      meta = JSON.stringify({ systolic: dp.systolic, diastolic: dp.diastolic });
+    } else {
+      qty = dp.qty ?? null;
+    }
+
+    return {
+      ts: toIso(d), date: toDateStr(d),
+      metric: m.name, qty, min, avg, max,
+      units: m.units, source: dp.source ?? null,
+      target, meta, session_id: sessionId,
+    };
+  });
+}

package/src/parse/sleep.ts

@@ -0,0 +1,82 @@
+import { parseHaeTime, toIso, toDateStr } from './time.js';
+import type { SleepDatapoint, SleepAnalysisRaw, AggregatedSleepV2, AggregatedSleepV1 } from '../types/hae.js';
+
+export type SleepVariant = 'detailed' | 'aggregated_v2' | 'aggregated_v1';
+
+export interface NormalizedSleep {
+  date: string;
+  sleep_start: string | null;
+  sleep_end: string | null;
+  in_bed_start: string | null;
+  in_bed_end: string | null;
+  core_h: number | null;
+  deep_h: number | null;
+  rem_h: number | null;
+  awake_h: number | null;
+  asleep_h: number | null;
+  in_bed_h: number | null;
+  schema_ver: SleepVariant;
+  source: string | null;
+  target: string;
+  meta: string | null;
+  session_id: string | null;
+}
+
+export function detectSleepVariant(dp: SleepDatapoint): SleepVariant {
+  if ('startDate' in dp) return 'detailed';
+  if ('core' in dp) return 'aggregated_v2';
+  return 'aggregated_v1';
+}
+
+export function normalizeSleep(dp: SleepDatapoint, target: string, sessionId: string | null): NormalizedSleep {
+  const variant = detectSleepVariant(dp);
+
+  if (variant === 'detailed') {
+    const raw = dp as SleepAnalysisRaw;
+    const start = parseHaeTime(raw.startDate);
+    return {
+      date: toDateStr(start),
+      sleep_start: toIso(start),
+      sleep_end: toIso(parseHaeTime(raw.endDate)),
+      in_bed_start: null, in_bed_end: null,
+      core_h: null, deep_h: null, rem_h: null, awake_h: null, asleep_h: null, in_bed_h: null,
+      schema_ver: 'detailed',
+      source: raw.source,
+      target,
+      meta: JSON.stringify(dp),
+      session_id: sessionId,
+    };
+  }
+
+  if (variant === 'aggregated_v2') {
+    const v2 = dp as AggregatedSleepV2;
+    const sleepStart = parseHaeTime(v2.sleepStart);
+    return {
+      date: toDateStr(sleepStart),
+      sleep_start: toIso(sleepStart),
+      sleep_end: toIso(parseHaeTime(v2.sleepEnd)),
+      in_bed_start: null, in_bed_end: null,
+      core_h: v2.core, deep_h: v2.deep, rem_h: v2.rem, awake_h: v2.awake,
+      asleep_h: v2.asleep, in_bed_h: v2.inBed,
+      schema_ver: 'aggregated_v2',
+      source: v2.source,
+      target, meta: null, session_id: sessionId,
+    };
+  }
+
+  // aggregated_v1
+  const v1 = dp as AggregatedSleepV1;
+  const sleepStart = parseHaeTime(v1.sleepStart);
+  return {
+    date: toDateStr(sleepStart),
+    sleep_start: toIso(sleepStart),
+    sleep_end: toIso(parseHaeTime(v1.sleepEnd)),
+    in_bed_start: v1.inBedStart ? toIso(parseHaeTime(v1.inBedStart)) : null,
+    in_bed_end: v1.inBedEnd ? toIso(parseHaeTime(v1.inBedEnd)) : null,
+    core_h: null, deep_h: null, rem_h: null, awake_h: null,
+    asleep_h: v1.asleep, in_bed_h: v1.inBed,
+    schema_ver: 'aggregated_v1',
+    source: v1.sleepSource ?? null,
+    target, meta: null, session_id: sessionId,
+  };
+}

package/src/parse/time.ts

@@ -0,0 +1,43 @@
+// HAE outputs 5 different timestamp formats depending on iPhone locale.
+
+function parse24h(date: string, h: string, m: string, s: string, tz: string): Date {
+  const tzFormatted = `${tz.slice(0, 3)}:${tz.slice(3)}`;
+  return new Date(`${date}T${h}:${m}:${s}${tzFormatted}`);
+}
+
+function parse12h(date: string, h: string, m: string, s: string, ampm: string, tz: string): Date {
+  let hour = parseInt(h, 10);
+  const isAm = ampm.toLowerCase() === 'am';
+  if (isAm && hour === 12) hour = 0;
+  if (!isAm && hour !== 12) hour += 12;
+  const hh = String(hour).padStart(2, '0');
+  const tzFormatted = `${tz.slice(0, 3)}:${tz.slice(3)}`;
+  return new Date(`${date}T${hh}:${m}:${s}${tzFormatted}`);
+}
+
+export function parseHaeTime(s: string): Date {
+  // Try 24-hour format: "2026-01-15 14:30:00 +0000"
+  const m24 = s.match(/^(\d{4}-\d{2}-\d{2}) (\d{2}):(\d{2}):(\d{2}) ([+-]\d{4})$/);
+  if (m24) {
+    const d = parse24h(m24[1], m24[2], m24[3], m24[4], m24[5]);
+    if (!isNaN(d.getTime())) return d;
+  }
+
+  // Try 12-hour format (space or narrow non-breaking space \u202f before AM/PM)
+  // "2026-01-15 2:30:00 PM +0000" or "2026-01-15 2:30:00\u202fPM +0000"
+  const m12 = s.match(/^(\d{4}-\d{2}-\d{2}) (\d{1,2}):(\d{2}):(\d{2})[\u202f ]([APap][Mm]) ([+-]\d{4})$/);
+  if (m12) {
+    const d = parse12h(m12[1], m12[2], m12[3], m12[4], m12[5], m12[6]);
+    if (!isNaN(d.getTime())) return d;
+  }
+
+  throw new Error(`Failed to parse HAE timestamp: "${s}"`);
+}
+
+export function toIso(d: Date): string {
+  return d.toISOString();
+}
+
+export function toDateStr(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}

package/src/parse/workouts.ts

@@ -0,0 +1,42 @@
+import { parseHaeTime, toIso, toDateStr } from './time.js';
+import type { WorkoutData } from '../types/hae.js';
+
+export interface NormalizedWorkout {
+  ts: string;
+  date: string;
+  name: string;
+  duration_s: number | null;
+  calories_kj: number | null;
+  distance: number | null;
+  distance_unit: string | null;
+  avg_hr: number | null;
+  max_hr: number | null;
+  target: string;
+  meta: string;
+  session_id: string | null;
+}
+
+export function parseWorkout(w: WorkoutData, target: string, sessionId: string | null): NormalizedWorkout {
+  const start = parseHaeTime(w.start);
+  const end = parseHaeTime(w.end);
+  const duration_s = Math.round((end.getTime() - start.getTime()) / 1000);
+
+  const hrValues = (w.heartRateData ?? []).map((h) => h.qty).filter((v): v is number => typeof v === 'number');
+  const avg_hr = hrValues.length > 0 ? hrValues.reduce((a, b) => a + b, 0) / hrValues.length : null;
+  const max_hr = hrValues.length > 0 ? Math.max(...hrValues) : null;
+
+  return {
+    ts: toIso(start),
+    date: toDateStr(start),
+    name: w.name,
+    duration_s,
+    calories_kj: w.activeEnergyBurned?.qty ?? null,
+    distance: w.distance?.qty ?? null,
+    distance_unit: w.distance?.units ?? null,
+    avg_hr,
+    max_hr,
+    target,
+    meta: JSON.stringify(w),
+    session_id: sessionId,
+  };
+}