@supalytics/cli 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supalytics/cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "CLI for Supalytics web analytics",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -474,3 +474,270 @@ export async function deleteAnnotation(
     throw new Error(error.message || error.error || `HTTP ${response.status}`);
   }
 }
+
+// Journeys API types
+export interface VisitorListRow {
+  visitor_id: string;
+  country: string;
+  browser: string;
+  os: string;
+  device: string;
+  pageview_count: number;
+  session_count: number;
+  event_count: number;
+  total_revenue_cents: number;
+  first_seen: string; // "2024-01-15 10:30:45"
+  last_seen: string;
+  first_referrer: string; // "google.com" or "Direct"
+  entry_page: string; // "/pricing"
+  latest_revenue_date: string;
+  revenue_event_count: number;
+}
+
+export interface VisitorTimelineAction {
+  timestamp: string; // "2024-01-15 10:30:45"
+  type: "pageview" | "event" | "revenue" | "auto";
+  session_id: string;
+  url_path?: string;
+  referrer?: string;
+  utm_source?: string;
+  is_entry_page?: number; // 1 or 0
+  scroll_depth?: number;
+  event_name?: string;
+  event_properties?: string; // JSON string
+  transaction_id?: string;
+  amount_cents?: number;
+  currency?: string;
+  revenue_event?: string;
+  country?: string;
+  browser?: string;
+  os?: string;
+  device?: string;
+}
+
+export interface VisitorStats {
+  visitor_id: string;
+  first_seen: string;
+  last_seen: string;
+  total_sessions: number;
+  total_pageviews: number;
+  total_events: number;
+  total_revenue_cents: number;
+  latest_revenue_event?: string;
+  latest_revenue_amount?: number;
+  latest_revenue_date?: string;
+  avg_scroll_depth: number;
+  avg_session_duration_seconds: number;
+  country: string;
+  region: string;
+  city: string;
+  browser: string;
+  os: string;
+  device: string;
+  entry_page: string;
+  source: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+}
+
+export interface VisitorFilters {
+  pageviews_gt?: number;
+  pageviews_lt?: number;
+  pageviews_eq?: number;
+  sessions_gt?: number;
+  sessions_lt?: number;
+  sessions_eq?: number;
+  events_gt?: number;
+  events_lt?: number;
+  events_eq?: number;
+  revenue_gt?: number; // cents
+  revenue_lt?: number;
+  revenue_eq?: number;
+  first_time_conversion?: boolean;
+}
+
+export interface JourneysListRequest {
+  date_range?: string | [string, string];
+  filters?: [string, string, string][];
+  pageviews_gt?: number;
+  pageviews_lt?: number;
+  pageviews_eq?: number;
+  sessions_gt?: number;
+  sessions_lt?: number;
+  sessions_eq?: number;
+  events_gt?: number;
+  events_lt?: number;
+  events_eq?: number;
+  revenue_gt?: number;
+  revenue_lt?: number;
+  revenue_eq?: number;
+  first_purchase?: boolean;
+  has_revenue?: boolean;
+  sort_by?: string;
+  sort_order?: "asc" | "desc";
+  limit?: number;
+  offset?: number;
+  timezone?: string;
+  is_dev?: boolean;
+}
+
+export interface JourneysListResponse {
+  data: VisitorListRow[];
+  meta: {
+    domain: string;
+    date_range: [string, string];
+    timezone: string;
+    query_ms: number;
+  };
+  pagination: {
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    total?: number;
+  };
+}
+
+export interface JourneyTimelineRequest {
+  visitor_id: string;
+  date_range?: string | [string, string];
+  include_auto_events?: boolean;
+  limit?: number;
+  offset?: number;
+  timezone?: string;
+  is_dev?: boolean;
+}
+
+export interface JourneyTimelineResponse {
+  data: VisitorTimelineAction[];
+  meta: {
+    domain: string;
+    visitor_id: string;
+    date_range: [string, string];
+    timezone: string;
+    query_ms: number;
+  };
+  pagination: {
+    limit: number;
+    offset: number;
+    has_more: boolean;
+  };
+}
+
+export interface JourneyStatsResponse {
+  data: VisitorStats;
+  meta: {
+    domain: string;
+    visitor_id: string;
+    query_ms: number;
+  };
+}
+
+/**
+ * List visitor journeys with filters
+ */
+export async function listJourneys(
+  site: string,
+  request: JourneysListRequest
+): Promise<JourneysListResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login` to authenticate."
+      );
+    }
+    throw new Error(
+      `Not authenticated or site '${site}' not found. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const response = await fetch(`${API_BASE}/v1/journeys/list`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...request, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get timeline for a specific visitor
+ */
+export async function getJourneyTimeline(
+  site: string,
+  request: JourneyTimelineRequest
+): Promise<JourneyTimelineResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/journeys/timeline`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...request, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get stats for a specific visitor
+ */
+export async function getJourneyStats(
+  site: string,
+  visitorId: string,
+  isDev: boolean = false
+): Promise<JourneyStatsResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/journeys/stats`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ visitor_id: visitorId, is_dev: isDev, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Format revenue in cents to dollars
+ */
+export function formatRevenue(cents: number, currency: string = "USD"): string {
+  const dollars = cents / 100;
+  return `$${dollars.toFixed(2)}${currency !== "USD" ? ` ${currency}` : ""}`;
+}

package/src/commands/journeys.ts

@@ -0,0 +1,470 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import {
+  listJourneys,
+  getJourneyTimeline,
+  getJourneyStats,
+  formatRevenue,
+  type VisitorTimelineAction,
+} from "../api";
+import { getDefaultSite } from "../config";
+import {
+  table,
+  parsePeriod,
+  formatDate,
+  formatTimelineDate,
+  formatTime,
+  formatSessionDuration,
+  type TableColumn,
+} from "../ui";
+
+const journeysDescription = `View visitor journeys and individual visitor details.
+
+Examples:
+  # List all visitors (last 30 days)
+  supalytics journeys
+
+  # Only paying customers
+  supalytics journeys --customers
+
+  # High-value visitors (5+ pageviews, $50+ revenue)
+  supalytics journeys --min-pageviews 5 --min-revenue 5000
+
+  # Filter by country
+  supalytics journeys -f "country:is:US"
+
+  # Sort by revenue
+  supalytics journeys --sort-by revenue --customers
+
+  # View specific visitor journey
+  supalytics journeys abc123xyz
+
+  # JSON output
+  supalytics journeys --json`;
+
+export const journeysCommand = new Command("journeys")
+  .description(journeysDescription)
+  .argument("[visitor-id]", "Visitor ID to view details")
+  .option("-s, --site <site>", "Site to query")
+  .option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+  .option("--start <date>", "Start date (YYYY-MM-DD)")
+  .option("--end <date>", "End date (YYYY-MM-DD)")
+  .option("-f, --filter <filters...>", "Page-level filters (field:operator:value)")
+  .option("--min-pageviews <n>", "Minimum pageviews", parseInt)
+  .option("--max-pageviews <n>", "Maximum pageviews", parseInt)
+  .option("--min-sessions <n>", "Minimum sessions", parseInt)
+  .option("--max-sessions <n>", "Maximum sessions", parseInt)
+  .option("--min-revenue <cents>", "Minimum revenue (cents)", parseInt)
+  .option("--max-revenue <cents>", "Maximum revenue (cents)", parseInt)
+  .option("--customers", "Only visitors with revenue")
+  .option("--first-purchase", "Only first-time purchases")
+  .option("--sort-by <field>", "Sort by: last_seen, first_seen, pageviews, sessions, revenue, latest_revenue", "last_seen")
+  .option("--sort-order <order>", "Sort order: asc, desc", "desc")
+  .option("-l, --limit <n>", "Results per page (max 100)", "50")
+  .option("--offset <n>", "Pagination offset", "0")
+    .option("--json", "Output as JSON")
+  .option("-t, --test", "Test mode: query localhost data")
+  .action(async (visitorId, options) => {
+    const site = options.site || (await getDefaultSite());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    const dateRange = options.start && options.end
+      ? [options.start, options.end] as [string, string]
+      : parsePeriod(options.period);
+
+    try {
+      // If visitor ID provided, show visitor details
+      if (visitorId) {
+        await showVisitorDetails(site, visitorId, dateRange, options);
+        return;
+      }
+
+      // Otherwise, list all visitors
+      await listVisitors(site, dateRange, options);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// LIST VISITORS
+// ============================================================================
+
+async function listVisitors(
+  site: string,
+  dateRange: string | [string, string],
+  options: Record<string, unknown>
+) {
+  // Parse filters
+  const filters = options.filter
+    ? (options.filter as string[]).map((f: string) => {
+        const parts = f.split(":");
+        if (parts.length < 3) {
+          console.error(chalk.red(`Invalid filter format: ${f}. Use 'field:operator:value'`));
+          process.exit(1);
+        }
+        const [field, operator, ...valueParts] = parts;
+        return [field, operator, valueParts.join(":")] as [string, string, string];
+      })
+    : undefined;
+
+  const response = await listJourneys(site, {
+    date_range: dateRange,
+    filters,
+    pageviews_gt: options.minPageviews as number | undefined,
+    pageviews_lt: options.maxPageviews as number | undefined,
+    sessions_gt: options.minSessions as number | undefined,
+    sessions_lt: options.maxSessions as number | undefined,
+    revenue_gt: options.minRevenue as number | undefined,
+    revenue_lt: options.maxRevenue as number | undefined,
+    first_purchase: options.firstPurchase as boolean | undefined,
+    has_revenue: options.customers as boolean | undefined,
+    sort_by: options.sortBy as string,
+    sort_order: options.sortOrder as "asc" | "desc",
+    limit: parseInt(options.limit as string),
+    offset: parseInt(options.offset as string),
+    is_dev: (options.test as boolean) || false,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+
+  const [startDate, endDate] = response.meta.date_range;
+
+  console.log();
+  console.log(chalk.bold("VISITOR JOURNEYS"), chalk.dim(`${startDate.split(" ")[0]} → ${endDate.split(" ")[0]}`));
+  console.log();
+
+  if (response.data.length === 0) {
+    console.log(chalk.dim("  No visitors found"));
+    return;
+  }
+
+  const columns: TableColumn[] = [
+    {
+      key: "visitor_id",
+      label: "Visitor ID",
+      align: "left",
+      width: 36,
+      format: (v) => chalk.cyan(String(v)),
+    },
+    {
+      key: "country",
+      label: "Country",
+      align: "left",
+      width: 7,
+    },
+    {
+      key: "device",
+      label: "Device",
+      align: "left",
+      width: 8,
+    },
+    {
+      key: "first_referrer",
+      label: "Source",
+      align: "left",
+      width: 18,
+      format: (v) => {
+        const source = String(v || "Direct");
+        return source.length > 18 ? source.slice(0, 15) + "..." : source;
+      },
+    },
+    {
+      key: "entry_page",
+      label: "Entry Page",
+      align: "left",
+      width: 20,
+      format: (v) => {
+        const page = String(v || "/");
+        return page.length > 20 ? page.slice(0, 17) + "..." : page;
+      },
+    },
+    {
+      key: "pageview_count",
+      label: "Views",
+      align: "right",
+    },
+    {
+      key: "session_count",
+      label: "Sessions",
+      align: "right",
+    },
+    {
+      key: "total_revenue_cents",
+      label: "Revenue",
+      align: "right",
+      format: (v) => {
+        const cents = Number(v);
+        return cents > 0 ? formatRevenue(cents) : chalk.dim("$0");
+      },
+    },
+    {
+      key: "first_seen",
+      label: "First Seen",
+      align: "left",
+      width: 18,
+      format: (v) => formatDate(String(v)),
+    },
+    {
+      key: "last_seen",
+      label: "Last Seen",
+      align: "left",
+      width: 18,
+      format: (v) => formatDate(String(v)),
+    },
+  ];
+
+  console.log(table(response.data, columns, { showHeader: true }));
+  console.log();
+
+  // Pagination info
+  const { total, has_more, limit, offset } = response.pagination;
+  if (total !== undefined) {
+    console.log(chalk.dim(`  ${response.data.length} visitors shown (${total} total)`));
+  } else {
+    console.log(chalk.dim(`  ${response.data.length} visitors shown`));
+  }
+
+  if (has_more) {
+    console.log(chalk.dim(`  Use --offset ${offset + limit} for next page`));
+  }
+  console.log();
+}
+
+// ============================================================================
+// SHOW VISITOR DETAILS
+// ============================================================================
+
+async function showVisitorDetails(
+  site: string,
+  visitorId: string,
+  dateRange: string | [string, string],
+  options: Record<string, unknown>
+) {
+  // Fetch both stats and timeline
+  const [statsResponse, timelineResponse] = await Promise.all([
+    getJourneyStats(site, visitorId, (options.test as boolean) || false),
+    getJourneyTimeline(site, {
+      visitor_id: visitorId,
+      date_range: dateRange,
+      include_auto_events: true,
+      limit: parseInt(options.limit as string),
+      offset: parseInt(options.offset as string),
+      is_dev: (options.test as boolean) || false,
+    }),
+  ]);
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      stats: statsResponse,
+      timeline: timelineResponse,
+    }, null, 2));
+    return;
+  }
+
+  const stats = statsResponse.data;
+  const timeline = timelineResponse.data;
+
+  console.log();
+  console.log(chalk.bold(`VISITOR: ${chalk.cyan(visitorId)}`));
+  console.log();
+
+  // Stats section
+  console.log(chalk.bold("STATS"));
+  console.log(`  First Seen:         ${formatDate(stats.first_seen)}`);
+  console.log(`  Last Seen:          ${formatDate(stats.last_seen)}`);
+  console.log(`  Total Sessions:     ${stats.total_sessions}`);
+  console.log(`  Total Pageviews:    ${stats.total_pageviews}`);
+  console.log(`  Total Events:       ${stats.total_events}`);
+  console.log(`  Total Revenue:      ${stats.total_revenue_cents > 0 ? formatRevenue(stats.total_revenue_cents) : chalk.dim("$0")}`);
+  console.log(`  Avg Scroll Depth:   ${stats.avg_scroll_depth.toFixed(0)}%`);
+  console.log(`  Avg Session:        ${formatSessionDuration(stats.avg_session_duration_seconds)}`);
+  console.log();
+  console.log(`  Location:           ${[stats.city, stats.region, stats.country].filter(Boolean).join(", ")}`);
+  console.log(`  Device:             ${stats.device} • ${stats.browser} • ${stats.os}`);
+  console.log(`  Source:             ${stats.source}`);
+  console.log(`  Entry Page:         ${stats.entry_page}`);
+  if (stats.utm_campaign) {
+    console.log(`  UTM Campaign:       ${stats.utm_campaign}`);
+  }
+  console.log();
+
+  // Timeline section
+  console.log(chalk.bold("TIMELINE"));
+  console.log();
+
+  if (timeline.length === 0) {
+    console.log(chalk.dim("  No timeline data"));
+    console.log();
+    return;
+  }
+
+  // Group timeline by date and session
+  const grouped = groupTimeline(timeline);
+
+  for (const dateGroup of grouped) {
+    console.log(chalk.dim(`  ▼ ${dateGroup.date}`));
+
+    for (const session of dateGroup.sessions) {
+      if (session.isGrouped) {
+        console.log(chalk.dim(`    Session ${session.sessionNumber}`));
+      }
+
+      for (const action of session.actions) {
+        console.log(formatTimelineAction(action));
+      }
+    }
+
+    console.log();
+  }
+
+  // Pagination info
+  if (timelineResponse.pagination.has_more) {
+    console.log(chalk.dim(`  ${timeline.length} items shown • Use --offset ${timelineResponse.pagination.offset + timelineResponse.pagination.limit} for more`));
+    console.log();
+  }
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+interface TimelineSession {
+  sessionNumber: number;
+  sessionId: string;
+  isGrouped: boolean;
+  actions: VisitorTimelineAction[];
+}
+
+interface TimelineDateGroup {
+  date: string;
+  sessions: TimelineSession[];
+}
+
+function groupTimeline(timeline: VisitorTimelineAction[]): TimelineDateGroup[] {
+  const dateGroups = new Map<string, VisitorTimelineAction[]>();
+
+  // Group by date
+  for (const action of timeline) {
+    const date = formatTimelineDate(action.timestamp);
+    if (!dateGroups.has(date)) {
+      dateGroups.set(date, []);
+    }
+    dateGroups.get(date)!.push(action);
+  }
+
+  // Convert to array and group by session within each date
+  const result: TimelineDateGroup[] = [];
+
+  for (const [date, actions] of dateGroups) {
+    const sessionGroups = new Map<string, VisitorTimelineAction[]>();
+    const nonSessionActions: VisitorTimelineAction[] = [];
+
+    for (const action of actions) {
+      if (action.type === "pageview" && action.session_id) {
+        if (!sessionGroups.has(action.session_id)) {
+          sessionGroups.set(action.session_id, []);
+        }
+        sessionGroups.get(action.session_id)!.push(action);
+      } else {
+        nonSessionActions.push(action);
+      }
+    }
+
+    const sessions: TimelineSession[] = [];
+    let sessionNumber = 1;
+
+    // Add session-grouped actions
+    for (const [sessionId, sessionActions] of sessionGroups) {
+      sessions.push({
+        sessionNumber: sessionNumber++,
+        sessionId,
+        isGrouped: true,
+        actions: sessionActions,
+      });
+    }
+
+    // Add non-session actions
+    if (nonSessionActions.length > 0) {
+      sessions.push({
+        sessionNumber: 0,
+        sessionId: "",
+        isGrouped: false,
+        actions: nonSessionActions,
+      });
+    }
+
+    result.push({ date, sessions });
+  }
+
+  return result;
+}
+
+function formatTimelineAction(action: VisitorTimelineAction): string {
+  const time = formatTime(action.timestamp);
+  const indent = "    ";
+
+  if (action.type === "pageview") {
+    const url = action.url_path || "/";
+    const badges: string[] = [];
+
+    if (action.is_entry_page === 1) {
+      badges.push(chalk.dim("[Entry]"));
+    }
+
+    if (action.referrer) {
+      badges.push(chalk.dim(`[${action.referrer}]`));
+    }
+
+    if (action.utm_source) {
+      badges.push(chalk.dim(`[utm: ${action.utm_source}]`));
+    }
+
+    if (action.scroll_depth !== undefined && action.scroll_depth !== null) {
+      badges.push(chalk.dim(`Scroll: ${action.scroll_depth}%`));
+    }
+
+    const badgeStr = badges.length > 0 ? " " + badges.join(" ") : "";
+
+    return `${indent}${chalk.dim(time)}  ${chalk.bold("PAGEVIEW")}   ${chalk.cyan(url)}${badgeStr}`;
+  }
+
+  if (action.type === "event" || action.type === "auto") {
+    const eventName = action.event_name || "unknown";
+    const label = action.type === "auto" ? "AUTO" : "EVENT";
+    let propsStr = "";
+
+    if (action.event_properties) {
+      try {
+        const props = JSON.parse(action.event_properties);
+        const pairs = Object.entries(props)
+          .slice(0, 2)
+          .map(([k, v]) => `${k}: ${v}`)
+          .join(", ");
+        propsStr = chalk.dim(` { ${pairs} }`);
+      } catch {
+        // Ignore parse errors
+      }
+    }
+
+    return `${indent}${chalk.dim(time)}  ${chalk.bold(label.padEnd(9))}  ${eventName}${propsStr}`;
+  }
+
+  if (action.type === "revenue") {
+    const amount = action.amount_cents ? formatRevenue(action.amount_cents, action.currency) : "$0";
+    const revenueType = action.revenue_event || "payment";
+    const txn = action.transaction_id ? chalk.dim(` (txn: ${action.transaction_id.slice(0, 12)})`) : "";
+
+    return `${indent}${chalk.dim(time)}  ${chalk.bold("REVENUE")}    ${revenueType.padEnd(15)} ${amount}${txn}`;
+  }
+
+  return `${indent}${chalk.dim(time)}  ${action.type}`;
+}

package/src/index.ts

@@ -14,6 +14,7 @@ import { eventsCommand } from "./commands/events";
 import { realtimeCommand } from "./commands/realtime";
 import { completionsCommand } from "./commands/completions";
 import { annotationsCommand } from "./commands/annotations";
+import { journeysCommand } from "./commands/journeys";
 import { initCommand } from "./commands/init";
 import { updateCommand } from "./commands/update";
 
@@ -93,6 +94,7 @@ program.addCommand(countriesCommand);
 program.addCommand(trendCommand);
 program.addCommand(queryCommand);
 program.addCommand(eventsCommand);
+program.addCommand(journeysCommand);
 program.addCommand(realtimeCommand);
 program.addCommand(annotationsCommand);
 program.addCommand(completionsCommand);

package/src/ui.ts

@@ -188,3 +188,72 @@ export function table(
 
   return lines.join("\n");
 }
+
+/**
+ * Format a date for display
+ */
+export function formatDate(dateStr: string): string {
+  const date = new Date(dateStr.replace(" ", "T") + "Z");
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffHours = diffMs / (1000 * 60 * 60);
+
+  if (diffHours < 1) {
+    const mins = Math.floor(diffMs / (1000 * 60));
+    return `${mins} minute${mins !== 1 ? "s" : ""} ago`;
+  }
+
+  if (diffHours < 24) {
+    const hours = Math.floor(diffHours);
+    return `${hours} hour${hours !== 1 ? "s" : ""} ago`;
+  }
+
+  // Format as "Jan 15, 10:30am"
+  const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const month = months[date.getMonth()];
+  const day = date.getDate();
+  const hour = date.getHours();
+  const minute = date.getMinutes();
+  const ampm = hour >= 12 ? "pm" : "am";
+  const displayHour = hour % 12 || 12;
+  const displayMinute = minute.toString().padStart(2, "0");
+
+  return `${month} ${day}, ${displayHour}:${displayMinute}${ampm}`;
+}
+
+/**
+ * Format a date as full date for timeline headers
+ */
+export function formatTimelineDate(dateStr: string): string {
+  const date = new Date(dateStr.replace(" ", "T") + "Z");
+  const months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+  return `${months[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
+}
+
+/**
+ * Format time only (HH:MM:SS)
+ */
+export function formatTime(dateStr: string): string {
+  const date = new Date(dateStr.replace(" ", "T") + "Z");
+  const hour = date.getHours().toString().padStart(2, "0");
+  const minute = date.getMinutes().toString().padStart(2, "0");
+  const second = date.getSeconds().toString().padStart(2, "0");
+  return `${hour}:${minute}:${second}`;
+}
+
+/**
+ * Format session duration
+ */
+export function formatSessionDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.round(seconds % 60);
+  if (mins < 60) {
+    return `${mins}m ${secs}s`;
+  }
+  const hours = Math.floor(mins / 60);
+  const remainingMins = mins % 60;
+  return `${hours}h ${remainingMins}m`;
+}