trainerroad-cli 0.1.0 → 0.1.1

package/README.md

@@ -16,26 +16,33 @@ CLI to fetch TrainerRoad data for your account, including:
 
 ## Install
 
-### From GitHub
+### Run without install (npx)
 
 ```bash
-npx --yes github:quinnsprouse/trainerroad-cli help
+npx --yes trainerroad-cli help
 ```
 
-### Local development
+### Global install
 
 ```bash
-git clone https://github.com/quinnsprouse/trainerroad-cli.git
-cd trainerroad-cli
-npm install
-npm exec --yes trainerroad-cli -- help
+npm install -g trainerroad-cli
+trainerroad-cli help
 ```
 
-### Global
+### Local project install
 
 ```bash
-npm install -g github:quinnsprouse/trainerroad-cli
-trainerroad-cli help
+npm install trainerroad-cli
+npx trainerroad-cli help
+```
+
+### Local development (from source)
+
+```bash
+git clone https://github.com/quinnsprouse/trainerroad-cli.git
+cd trainerroad-cli
+npm install
+npm run help
 ```
 
 ## Quickstart
@@ -56,6 +63,7 @@ trainerroad-cli past --days 30 --json
 trainerroad-cli plan --view current --json
 trainerroad-cli levels --json
 trainerroad-cli ftp --json
+trainerroad-cli today --tz America/New_York --json
 ```
 
 3. Discover all commands
@@ -80,6 +88,7 @@ Use `--target <username>` and/or `--public` for public mode queries.
 - `--jsonl`: one record per line
 - `--fields a,b,c`: project record fields
 - `--records-only`: lighter record payloads
+- `--tz <IANA timezone>`: localize day boundaries/timestamps (defaults to `TR_TIMEZONE` or system timezone)
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {

package/src/cli.mjs

@@ -33,6 +33,16 @@ import { commandPowerRanking, commandPowerRecords } from "./commands/power.mjs";
 import { commandTimeline } from "./commands/timeline.mjs";
 import { commandWeightHistory } from "./commands/weight-history.mjs";
 import { commandFuture, commandPast, commandToday } from "./commands/workouts.mjs";
+import {
+  formatDateTimeInTimeZone,
+  isoDateShiftInTimeZone,
+  normalizeTimeZone,
+  parseApiDateTime,
+  summarizeActivityTimeWindow,
+  toDateOnlyInTimeZone,
+} from "./lib/timezone.mjs";
+
+let ACTIVE_TIME_ZONE = normalizeTimeZone();
 
 function printGlobalHelp() {
   console.log("trainerroad-cli (unofficial)");
@@ -53,6 +63,7 @@ function printGlobalHelp() {
   console.log("Examples:");
   console.log("  node src/cli.mjs login --username quinnsprouse --password-stdin");
   console.log("  node src/cli.mjs future --days 30 --details --json");
+  console.log("  node src/cli.mjs today --tz America/New_York --json");
   console.log("  node src/cli.mjs future --from 2026-03-01 --to 2026-03-31 --min-tss 60 --fields id,title,tss --jsonl");
   console.log("  node src/cli.mjs timeline --target quinnsprouse --public --json");
   console.log("  node src/cli.mjs ftp --target quinnsprouse --public --json");
@@ -179,6 +190,7 @@ function printCommandHelp(command, flags = {}) {
       command,
       summary: def.summary,
       usage: def.usage,
+      timezoneOption: "--tz <IANA timezone> (defaults to TR_TIMEZONE or system timezone)",
       supportsAgentFilters: FILTERABLE_COMMANDS.has(command),
       agentFilterOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_FILTER_OPTIONS : [],
       agentOutputOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_OUTPUT_OPTIONS : [],
@@ -194,6 +206,9 @@ function printCommandHelp(command, flags = {}) {
   console.log("");
   console.log("Usage:");
   for (const line of def.usage) console.log(`  ${line}`);
+  console.log("");
+  console.log("Timezone:");
+  console.log("  --tz <IANA timezone> Override local-day bucketing (defaults: TR_TIMEZONE or system timezone).");
   if (FILTERABLE_COMMANDS.has(command)) {
     console.log("");
     console.log("Agent filters:");
@@ -234,9 +249,7 @@ function parseArgs(argv) {
 }
 
 function isoDateShift(days) {
-  const date = new Date();
-  date.setUTCDate(date.getUTCDate() + days);
-  return date.toISOString().slice(0, 10);
+  return isoDateShiftInTimeZone(days, ACTIVE_TIME_ZONE);
 }
 
 function toIsoDateFromPlanned(item) {
@@ -244,8 +257,26 @@ function toIsoDateFromPlanned(item) {
 }
 
 function toIsoDate(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
+  if (typeof value === "string" && value.length >= 10 && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    return value.slice(0, 10);
+  }
+  return (
+    toDateOnlyInTimeZone(value, ACTIVE_TIME_ZONE, { assumeUtcForOffsetlessDateTime: true }) ??
+    new Date(value).toISOString().slice(0, 10)
+  );
+}
+
+function formatDateTime(value) {
+  return (
+    formatDateTimeInTimeZone(value, ACTIVE_TIME_ZONE, { assumeUtcForOffsetlessDateTime: true }) ??
+    String(value ?? "")
+  );
+}
+
+function summarizeActivityTime(started, durationInSeconds) {
+  return summarizeActivityTimeWindow(started, durationInSeconds, ACTIVE_TIME_ZONE, {
+    assumeUtcForOffsetlessDateTime: true,
+  });
 }
 
 function normalizeDateOnlyInput(value, fallback) {
@@ -292,8 +323,10 @@ function normalizeFtpHistory(raw) {
       const valueRaw = item?.value ?? item?.Value ?? null;
       const value = Number(valueRaw);
       if (!dateRaw || !Number.isFinite(value)) return null;
+      const parsedDate = parseApiDateTime(dateRaw, { assumeUtcForOffsetlessDateTime: true });
+      if (!parsedDate) return null;
       return {
-        date: new Date(dateRaw).toISOString(),
+        date: parsedDate.toISOString(),
         dateOnly: toIsoDate(dateRaw),
         value,
       };
@@ -328,9 +361,11 @@ function normalizeFitnessThresholds(raw) {
       const valueRaw = item?.value ?? item?.Value ?? null;
       const value = Number(valueRaw);
       if (!dateRaw || !Number.isFinite(value)) return null;
+      const parsedDate = parseApiDateTime(dateRaw, { assumeUtcForOffsetlessDateTime: true });
+      if (!parsedDate) return null;
       return {
         id: item?.id ?? item?.Id ?? null,
-        date: new Date(dateRaw).toISOString(),
+        date: parsedDate.toISOString(),
         dateOnly: toIsoDate(dateRaw),
         value,
         isApplied: Boolean(item?.isApplied ?? item?.IsApplied),
@@ -397,9 +432,21 @@ async function readPasswordFromStdin() {
   return Buffer.concat(chunks).toString("utf8").trim();
 }
 
+function withTimeZoneMeta(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return payload;
+  if (payload.timeZone != null) return payload;
+  return { ...payload, timeZone: ACTIVE_TIME_ZONE };
+}
+
 async function writeOutput(payload, flags, textRenderer = null) {
+  const payloadWithTimeZone = withTimeZoneMeta(payload);
+
   if (flags.jsonl) {
-    const records = Array.isArray(payload?.records) ? payload.records : Array.isArray(payload) ? payload : [];
+    const records = Array.isArray(payloadWithTimeZone?.records)
+      ? payloadWithTimeZone.records
+      : Array.isArray(payloadWithTimeZone)
+        ? payloadWithTimeZone
+        : [];
     const content = records.map((item) => JSON.stringify(item)).join("\n");
     if (flags.output) {
       await fs.writeFile(flags.output, `${content}${content ? "\n" : ""}`, "utf8");
@@ -410,9 +457,11 @@ async function writeOutput(payload, flags, textRenderer = null) {
     return;
   }
 
-  if (flags.json || typeof payload !== "string") {
+  if (flags.json || typeof payloadWithTimeZone !== "string") {
     const content =
-      typeof payload === "string" ? payload : `${JSON.stringify(payload, null, 2)}\n`;
+      typeof payloadWithTimeZone === "string"
+        ? payloadWithTimeZone
+        : `${JSON.stringify(payloadWithTimeZone, null, 2)}\n`;
     if (flags.output) {
       await fs.writeFile(flags.output, content, "utf8");
       console.log(`Wrote JSON to ${flags.output}`);
@@ -422,7 +471,7 @@ async function writeOutput(payload, flags, textRenderer = null) {
     return;
   }
 
-  const text = textRenderer ? textRenderer(payload) : String(payload);
+  const text = textRenderer ? textRenderer(payloadWithTimeZone) : String(payloadWithTimeZone);
   if (flags.output) {
     await fs.writeFile(flags.output, `${text}\n`, "utf8");
     console.log(`Wrote text to ${flags.output}`);
@@ -532,6 +581,9 @@ async function main() {
     process.exit(1);
   }
 
+  ACTIVE_TIME_ZONE = normalizeTimeZone(flags.tz ?? null);
+  process.env.TR_TIMEZONE = ACTIVE_TIME_ZONE;
+
   if (command === "help") {
     if (positionals[0]) {
       process.exit(printCommandHelp(positionals[0], flags));
@@ -550,6 +602,7 @@ async function main() {
   }
 
   const commandDeps = {
+    timeZone: ACTIVE_TIME_ZONE,
     resolveQueryContext,
     requirePrivateContext,
     applyAgentRecordFilters,
@@ -562,11 +615,14 @@ async function main() {
     normalizeDateOnlyInput,
     isoDateShift,
     filterFuturePlanned,
-    filterPastActivities,
+    filterPastActivities: (activities, fromDateIso, toDateIso) =>
+      filterPastActivities(activities, fromDateIso, toDateIso, ACTIVE_TIME_ZONE),
     sortByDateAsc,
     sortByDateDesc,
     toIsoDateFromPlanned,
     toIsoDate,
+    formatDateTime,
+    summarizeActivityTime,
     withClient,
     readPasswordFromStdin,
     normalizeFtpHistory,
@@ -667,6 +723,9 @@ main().catch((error) => {
   if (message.includes('Invalid date "')) {
     console.error("Tip: expected date format is YYYY-MM-DD");
   }
+  if (message.includes('Invalid timezone "')) {
+    console.error("Tip: use an IANA timezone like America/New_York.");
+  }
   console.error('Run "trainerroad-cli help" or "trainerroad-cli help <command>" for usage.');
 
   if (process.env.TR_CLI_DEBUG === "1" && error?.stack) {

package/src/commands/discovery.mjs

@@ -30,6 +30,7 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       "node src/cli.mjs capabilities --json",
       "node src/cli.mjs whoami --json",
       "node src/cli.mjs future --days 30 --json",
+      "node src/cli.mjs today --tz America/New_York --json",
       "node src/cli.mjs help future --json",
     ],
     commandCount: commandEntries.length,
@@ -152,6 +153,11 @@ export async function commandCapabilities(flags, deps) {
       outputOptions: AGENT_OUTPUT_OPTIONS,
     },
     outputModes: ["text", "json", "jsonl"],
+    timezone: {
+      flag: "--tz <IANA timezone>",
+      environment: "TR_TIMEZONE",
+      example: "America/New_York",
+    },
   };
 
   await writeOutput(payload, flags, () => {
@@ -160,6 +166,7 @@ export async function commandCapabilities(flags, deps) {
       "- Private mode (authenticated): full timeline + workout details.",
       "- Public mode (unauthenticated): day-level TSS/ride/planned signals + FTP history.",
       "- Commands support both via automatic mode selection and --target/--public flags.",
+      "- Timezone-aware date bucketing: use --tz or TR_TIMEZONE for local-day accuracy.",
     ].join("\n");
   });
 }

package/src/commands/workouts.mjs

@@ -1,3 +1,17 @@
+function addLocalTimeSummary(record, summarizeActivityTime) {
+  if (!record || typeof record !== "object" || typeof summarizeActivityTime !== "function") {
+    return record;
+  }
+  const summary = summarizeActivityTime(record.started, record.durationInSeconds);
+  if (!summary) return record;
+  return { ...record, ...summary };
+}
+
+function addLocalTimeSummaryList(records, summarizeActivityTime) {
+  const rows = Array.isArray(records) ? records : [];
+  return rows.map((record) => addLocalTimeSummary(record, summarizeActivityTime));
+}
+
 export async function commandFuture(flags, deps) {
   const {
     requireNumber,
@@ -130,6 +144,7 @@ export async function commandPast(flags, deps) {
     writeOutput,
     hasAgentRecordTransforms,
     sortByDateDesc,
+    summarizeActivityTime,
   } = deps;
 
   const days = requireNumber(flags.days, 60);
@@ -144,7 +159,8 @@ export async function commandPast(flags, deps) {
   if (context.mode === "private") {
     const filtered = filterPastActivities(context.timeline.activities, fromDate, toDate).slice(0, limit);
     if (!flags.details) {
-      const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(filtered, flags);
+      const recordsWithLocalTime = addLocalTimeSummaryList(filtered, summarizeActivityTime);
+      const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(recordsWithLocalTime, flags);
       const payload = {
         mode: "private",
         generatedAt: new Date().toISOString(),
@@ -165,7 +181,10 @@ export async function commandPast(flags, deps) {
             return lines.join("\n");
           }
           for (const item of value.records) {
-            lines.push(`- ${item.started} id=${item.id} type=${item.type} tss=${item.tss}`);
+            const overnightLabel = item.crossesMidnightLocal ? " | overnight=true" : "";
+            lines.push(
+              `- ${item.startedAtLocal ?? item.started} id=${item.id} type=${item.type} tss=${item.tss}${overnightLabel}`,
+            );
           }
           return lines.join("\n");
         });
@@ -190,7 +209,11 @@ export async function commandPast(flags, deps) {
       ...item,
       personalRecordCount: Array.isArray(personalRecords[item.id]) ? personalRecords[item.id].length : 0,
     }));
-    const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(detailRecords, flags);
+    const detailRecordsWithLocalTime = addLocalTimeSummaryList(detailRecords, summarizeActivityTime);
+    const { records: filteredRecords, filterSummary } = applyAgentRecordFilters(
+      detailRecordsWithLocalTime,
+      flags,
+    );
     const payload = {
       mode: "private",
       generatedAt: new Date().toISOString(),
@@ -215,8 +238,9 @@ export async function commandPast(flags, deps) {
           return lines.join("\n");
         }
         for (const item of value.records) {
+          const overnightLabel = item.crossesMidnightLocal ? " | overnight=true" : "";
           lines.push(
-            `- ${new Date(item.started).toISOString()} ${item.name} | id=${item.id} | tss=${item.tss} | duration=${item.durationInSeconds}s | prs=${item.personalRecordCount}`,
+            `- ${item.startedAtLocal ?? item.started} ${item.name} | id=${item.id} | tss=${item.tss} | duration=${item.durationInSeconds}s | prs=${item.personalRecordCount}${overnightLabel}`,
           );
         }
         return lines.join("\n");
@@ -286,6 +310,7 @@ export async function commandToday(flags, deps) {
     writeOutput,
     hasAgentRecordTransforms,
     toIsoDateFromPlanned,
+    summarizeActivityTime,
   } = deps;
 
   const today = normalizeDateOnlyInput(flags.date, isoDateShift(0));
@@ -316,9 +341,10 @@ export async function commandToday(flags, deps) {
       );
     }
 
+    const completedWithLocalTime = addLocalTimeSummaryList(activityRecords, summarizeActivityTime);
     const records = [
       ...plannedRecords.map((item) => ({ recordType: "planned", ...item })),
-      ...activityRecords.map((item) => ({
+      ...completedWithLocalTime.map((item) => ({
         recordType: "completed",
         ...item,
         personalRecordCount: Array.isArray(personalRecords[item.id]) ? personalRecords[item.id].length : 0,
@@ -333,9 +359,9 @@ export async function commandToday(flags, deps) {
       query: { date: today, details: Boolean(flags.details) },
       filters: filterSummary,
       member: { memberId: context.memberInfo.memberId, username: context.memberInfo.username },
-      counts: { planned: plannedRecords.length, completed: activityRecords.length },
+      counts: { planned: plannedRecords.length, completed: completedWithLocalTime.length },
       planned: plannedRecords,
-      completed: activityRecords,
+      completed: completedWithLocalTime,
       personalRecords,
       count: filteredRecords.length,
       records: filteredRecords,
@@ -372,9 +398,15 @@ export async function commandToday(flags, deps) {
         for (const item of value.completed) {
           if (flags.details) {
             const prs = Array.isArray(value.personalRecords[item.id]) ? value.personalRecords[item.id].length : 0;
-            lines.push(`- completed ${new Date(item.started).toISOString()} ${item.name} | tss=${item.tss} | prs=${prs}`);
+            const overnightLabel = item.crossesMidnightLocal ? " | overnight=true" : "";
+            lines.push(
+              `- completed ${item.startedAtLocal ?? item.started} ${item.name} | tss=${item.tss} | prs=${prs}${overnightLabel}`,
+            );
           } else {
-            lines.push(`- completed ${item.started} id=${item.id} type=${item.type} tss=${item.tss}`);
+            const overnightLabel = item.crossesMidnightLocal ? " | overnight=true" : "";
+            lines.push(
+              `- completed ${item.startedAtLocal ?? item.started} id=${item.id} type=${item.type} tss=${item.tss}${overnightLabel}`,
+            );
           }
         }
         return lines.join("\n");

package/src/lib/agent-filters.mjs

@@ -1,6 +1,13 @@
+import { normalizeTimeZone, toDateOnlyInTimeZone } from "./timezone.mjs";
+
 function toIsoDate(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
+  if (typeof value === "string" && value.length >= 10 && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    return value.slice(0, 10);
+  }
+  return (
+    toDateOnlyInTimeZone(value, normalizeTimeZone(), { assumeUtcForOffsetlessDateTime: true }) ??
+    new Date(value).toISOString().slice(0, 10)
+  );
 }
 
 function toIsoDateFromPlannedRecord(record) {

package/src/lib/command-manifest.mjs

@@ -115,7 +115,8 @@ export const PROJECT_NOTICE = "Unofficial tool. Not affiliated with or endorsed
 
 export const GLOBAL_NOTES = [
   PROJECT_NOTICE,
-  "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE",
+  "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE, TR_TIMEZONE",
+  "Timezone: --tz <IANA timezone> (for example America/New_York).",
   "Output modes: default JSON, --json, --jsonl, --output <path>",
   "Session file default: .trainerroad/session.json",
   "Private mode: authenticated cookie session + full workout endpoints.",
@@ -161,8 +162,7 @@ function trimFlagPrefix(flag) {
 
 function mergeFlagGroups(...groups) {
   return new Set(
-    groups
-      .flat()
+    [...groups.flat(), "tz"]
       .map((flag) => trimFlagPrefix(flag))
       .filter(Boolean),
   );

package/src/lib/planning-normalizers.mjs

@@ -1,3 +1,5 @@
+import { normalizeTimeZone, toDateOnlyInTimeZone } from "./timezone.mjs";
+
 const PROGRESSION_ZONE_META = {
   33: { zoneKey: "endurance", zoneLabel: "Endurance", sortOrder: 1 },
   16: { zoneKey: "tempo", zoneLabel: "Tempo", sortOrder: 2 },
@@ -20,8 +22,13 @@ function toIsoDateFromPlanned(item) {
 }
 
 export function toIsoDate(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
+  if (typeof value === "string" && value.length >= 10 && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    return value.slice(0, 10);
+  }
+  return (
+    toDateOnlyInTimeZone(value, normalizeTimeZone(), { assumeUtcForOffsetlessDateTime: true }) ??
+    new Date(value).toISOString().slice(0, 10)
+  );
 }
 
 function toIsoDateFromCalendarDate(dateValue) {

package/src/lib/timezone.mjs

@@ -0,0 +1,187 @@
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME_WITH_OFFSET_PATTERN = /(Z|[+\-]\d{2}:\d{2})$/i;
+
+function isFiniteDate(date) {
+  return date instanceof Date && Number.isFinite(date.getTime());
+}
+
+function pickPart(parts, type) {
+  const found = parts.find((part) => part.type === type);
+  return found ? found.value : null;
+}
+
+function toDateTimeParts(date, timeZone) {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+    timeZoneName: "shortOffset",
+  });
+  return formatter.formatToParts(date);
+}
+
+function toDateOnlyParts(date, timeZone) {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+  return formatter.formatToParts(date);
+}
+
+export function normalizeTimeZone(value = null, fallback = null) {
+  const fromArg = typeof value === "string" ? value.trim() : "";
+  const fromEnv = typeof process.env.TR_TIMEZONE === "string" ? process.env.TR_TIMEZONE.trim() : "";
+  const fromIntl = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const candidate = fromArg || fromEnv || fallback || fromIntl || "UTC";
+
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: candidate });
+    return candidate;
+  } catch {
+    throw new Error(`Invalid timezone "${candidate}". Use an IANA timezone like "America/New_York".`);
+  }
+}
+
+export function parseApiDateTime(value, { assumeUtcForOffsetlessDateTime = true } = {}) {
+  if (value == null) return null;
+
+  if (value instanceof Date) {
+    return isFiniteDate(value) ? new Date(value.getTime()) : null;
+  }
+
+  if (typeof value === "number") {
+    const parsed = new Date(value);
+    return isFiniteDate(parsed) ? parsed : null;
+  }
+
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw) return null;
+
+  if (DATE_ONLY_PATTERN.test(raw)) {
+    const parsedDateOnly = new Date(`${raw}T00:00:00Z`);
+    return isFiniteDate(parsedDateOnly) ? parsedDateOnly : null;
+  }
+
+  let normalized = raw;
+  if (
+    assumeUtcForOffsetlessDateTime &&
+    /^\d{4}-\d{2}-\d{2}T/.test(raw) &&
+    !DATE_TIME_WITH_OFFSET_PATTERN.test(raw)
+  ) {
+    normalized = `${raw}Z`;
+  }
+
+  const parsed = new Date(normalized);
+  return isFiniteDate(parsed) ? parsed : null;
+}
+
+export function toDateOnlyInTimeZone(
+  value,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  if (typeof value === "string" && DATE_ONLY_PATTERN.test(value.trim())) {
+    return value.trim();
+  }
+
+  const parsed = parseApiDateTime(value, { assumeUtcForOffsetlessDateTime });
+  if (!parsed) return null;
+
+  const parts = toDateOnlyParts(parsed, normalizeTimeZone(timeZone));
+  const year = pickPart(parts, "year");
+  const month = pickPart(parts, "month");
+  const day = pickPart(parts, "day");
+  if (!year || !month || !day) return null;
+  return `${year}-${month}-${day}`;
+}
+
+export function formatDateTimeInTimeZone(
+  value,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  const parsed = parseApiDateTime(value, { assumeUtcForOffsetlessDateTime });
+  if (!parsed) return null;
+
+  const parts = toDateTimeParts(parsed, normalizeTimeZone(timeZone));
+  const year = pickPart(parts, "year");
+  const month = pickPart(parts, "month");
+  const day = pickPart(parts, "day");
+  const hour = pickPart(parts, "hour");
+  const minute = pickPart(parts, "minute");
+  const second = pickPart(parts, "second");
+  const timeZoneName = pickPart(parts, "timeZoneName");
+  if (!year || !month || !day || !hour || !minute || !second) return null;
+
+  const suffix = timeZoneName ? ` ${timeZoneName}` : "";
+  return `${year}-${month}-${day}T${hour}:${minute}:${second}${suffix}`;
+}
+
+export function shiftDateOnly(dateOnly, days) {
+  const parsed = parseApiDateTime(dateOnly, { assumeUtcForOffsetlessDateTime: false });
+  if (!parsed) return null;
+  parsed.setUTCDate(parsed.getUTCDate() + Number(days));
+  return parsed.toISOString().slice(0, 10);
+}
+
+export function dateOnlyNowInTimeZone(timeZone) {
+  return toDateOnlyInTimeZone(new Date(), normalizeTimeZone(timeZone), {
+    assumeUtcForOffsetlessDateTime: false,
+  });
+}
+
+export function isoDateShiftInTimeZone(days, timeZone) {
+  const today = dateOnlyNowInTimeZone(timeZone);
+  return shiftDateOnly(today, days);
+}
+
+export function summarizeActivityTimeWindow(
+  started,
+  durationInSeconds,
+  timeZone,
+  { assumeUtcForOffsetlessDateTime = true } = {},
+) {
+  const startDate = parseApiDateTime(started, { assumeUtcForOffsetlessDateTime });
+  if (!startDate) return null;
+
+  const duration =
+    durationInSeconds != null && Number.isFinite(Number(durationInSeconds))
+      ? Number(durationInSeconds)
+      : null;
+  const endDate = duration != null ? new Date(startDate.getTime() + duration * 1000) : null;
+  const normalizedTimeZone = normalizeTimeZone(timeZone);
+
+  const startedDateOnly = toDateOnlyInTimeZone(startDate, normalizedTimeZone, {
+    assumeUtcForOffsetlessDateTime: false,
+  });
+  const endedDateOnly = endDate
+    ? toDateOnlyInTimeZone(endDate, normalizedTimeZone, {
+      assumeUtcForOffsetlessDateTime: false,
+    })
+    : null;
+
+  return {
+    startedAtUtc: startDate.toISOString(),
+    startedAtLocal: formatDateTimeInTimeZone(startDate, normalizedTimeZone, {
+      assumeUtcForOffsetlessDateTime: false,
+    }),
+    endedAtUtc: endDate ? endDate.toISOString() : null,
+    endedAtLocal: endDate
+      ? formatDateTimeInTimeZone(endDate, normalizedTimeZone, {
+        assumeUtcForOffsetlessDateTime: false,
+      })
+      : null,
+    localDate: startedDateOnly,
+    endLocalDate: endedDateOnly,
+    crossesMidnightLocal:
+      Boolean(startedDateOnly) && Boolean(endedDateOnly) && startedDateOnly !== endedDateOnly,
+  };
+}

package/src/trainerroad-client.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { normalizeTimeZone, toDateOnlyInTimeZone } from "./lib/timezone.mjs";
 
 const BASE_URL = "https://www.trainerroad.com";
 const APP_URL = `${BASE_URL}/app`;
@@ -11,11 +12,6 @@ function ensureLeadingSlash(value) {
   return value;
 }
 
-function toIsoDateOnly(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
-}
-
 function plannedDateToIso(item) {
   const year = String(item.date?.year ?? "").padStart(4, "0");
   const month = String(item.date?.month ?? "").padStart(2, "0");
@@ -38,10 +34,14 @@ export function filterFuturePlanned(plannedActivities, fromDateIso, toDateIso =
   });
 }
 
-export function filterPastActivities(activities, fromDateIso = null, toDateIso = null) {
+export function filterPastActivities(activities, fromDateIso = null, toDateIso = null, timeZone = null) {
+  const resolvedTimeZone = normalizeTimeZone(timeZone);
   return activities
     .filter((item) => {
-      const startedDate = toIsoDateOnly(item.started);
+      const startedDate = toDateOnlyInTimeZone(item.started, resolvedTimeZone, {
+        assumeUtcForOffsetlessDateTime: true,
+      });
+      if (!startedDate) return false;
       if (fromDateIso && startedDate < fromDateIso) return false;
       if (toDateIso && startedDate > toDateIso) return false;
       return true;