Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

4.9 KB
Raw Blame
// Vitals for the Pulse "Heartbeat" card: summary numbers derived from the same
// dense per-day counts the heatmap draws (GET /today/activity/daily — every
// calendar day present, oldest → newest, the last entry is today, UTC).
// Kept dependency-free so `node --test` can import it directly.

/** One day of activity; structurally the same as `DailyActivityCount` in api.ts. */
export interface ActivityDay {
  date: string; // YYYY-MM-DD (UTC)
  count: number;
}

/** Days per side of the "recent vs prior" comparison when the window allows. */
export const TREND_WINDOW_DAYS = 30;

export type TrendDirection = "up" | "down" | "flat" | "new" | "none";

export interface HeartbeatTrend {
  /** Days in each half of the comparison (≤ TREND_WINDOW_DAYS). */
  windowDays: number;
  current: number;
  prior: number;
  /** Rounded % change vs prior; null when prior is 0 (no baseline). */
  pct: number | null;
  direction: TrendDirection;
}

export interface HeartbeatVitals {
  /**
   * Consecutive active days ending today — or ending yesterday when nothing has
   * fired yet today, so the streak doesn't read as broken first thing.
   */
  currentStreak: { days: number; throughToday: boolean };
  longestStreak: number;
  total: number;
  activeDays: number;
  /** Mean count over active days, 1 decimal; null when there were none. */
  avgPerActiveDay: number | null;
  /** Highest-count day (most recent wins a tie); null when every day is 0. */
  busiestDay: ActivityDay | null;
  trend: HeartbeatTrend;
}

function sum(days: ActivityDay[]): number {
  return days.reduce((n, d) => n + d.count, 0);
}

function currentStreak(days: ActivityDay[]): HeartbeatVitals["currentStreak"] {
  let end = days.length - 1;
  const throughToday = end >= 0 && days[end].count > 0;
  if (!throughToday) end -= 1; // today idle so far: count back from yesterday
  let n = 0;
  for (let i = end; i >= 0 && days[i].count > 0; i--) n++;
  return { days: n, throughToday };
}

// Compares complete days only: today is still in progress, so counting it
// would make a perfectly steady rhythm read as "down" every (UTC) morning.
function trend(days: ActivityDay[]): HeartbeatTrend {
  const complete = days.slice(0, -1);
  const windowDays = Math.min(TREND_WINDOW_DAYS, Math.floor(complete.length / 2));
  const current = windowDays > 0 ? sum(complete.slice(-windowDays)) : 0;
  const prior = windowDays > 0 ? sum(complete.slice(-2 * windowDays, -windowDays)) : 0;
  if (prior === 0) {
    return { windowDays, current, prior, pct: null, direction: current > 0 ? "new" : "none" };
  }
  const pct = Math.round(((current - prior) / prior) * 100);
  const direction: TrendDirection = pct > 0 ? "up" : pct < 0 ? "down" : "flat";
  return { windowDays, current, prior, pct, direction };
}

export function deriveVitals(days: ActivityDay[]): HeartbeatVitals {
  let total = 0;
  let activeDays = 0;
  let longest = 0;
  let run = 0;
  let busiest: ActivityDay | null = null;

  for (const day of days) {
    total += day.count;
    if (day.count > 0) {
      activeDays++;
      run++;
      longest = Math.max(longest, run);
      // `>=` so a later day with the same count wins the tie.
      if (busiest === null || day.count >= busiest.count) busiest = day;
    } else {
      run = 0;
    }
  }

  return {
    currentStreak: currentStreak(days),
    longestStreak: longest,
    total,
    activeDays,
    avgPerActiveDay: activeDays > 0 ? Math.round((total / activeDays) * 10) / 10 : null,
    busiestDay: busiest,
    trend: trend(days),
  };
}

/** "Tue, Sep 9" for a YYYY-MM-DD date, formatted in UTC to match the buckets. */
export function formatVitalDate(date: string): string {
  return new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    weekday: "short",
    month: "short",
    day: "numeric",
    timeZone: "UTC",
  });
}

/** Display text for a trend: "▲ 18%", "▼ 12%", "flat", "new", or "—". */
export function formatTrend(t: HeartbeatTrend): string {
  switch (t.direction) {
    case "up":
      return `▲ ${t.pct}%`;
    case "down":
      return `▼ ${Math.abs(t.pct ?? 0)}%`;
    case "flat":
      return "flat";
    case "new":
      return "new";
    case "none":
      return "—";
  }
}

/**
 * The "Next beat" tile's value: how long until the soonest pending action
 * fires. A run time that has already passed (the scheduler picks it up on its
 * next tick) reads "Due now", never "0m ago"; a future one reads "in 12m",
 * "in 3h" or "in 2d". Empty for an unparseable time so the caller can fall
 * back.
 */
export function formatNextBeat(runAt: string, now: number = Date.now()): string {
  const at = new Date(runAt).getTime();
  if (!Number.isFinite(at)) return "";
  const deltaMs = at - now;
  if (deltaMs < 60_000) return "Due now";
  const mins = Math.round(deltaMs / 60_000);
  if (mins < 60) return `in ${mins}m`;
  const hours = Math.round(deltaMs / 3_600_000);
  if (hours < 48) return `in ${hours}h`;
  return `in ${Math.round(deltaMs / 86_400_000)}d`;
}