ts-watches 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,307 @@
+// ============================================================================
+// Configuration Types
+// ============================================================================
+export declare interface WatchConfig {
+  verbose: boolean
+  outputDir: string
+  watchPaths: string[]
+}
+// ============================================================================
+// Device Types
+// ============================================================================
+export declare interface WatchDevice {
+  name: string
+  path: string
+  type: 'garmin' | 'apple' | 'samsung' | 'fitbit' | 'wahoo' | 'coros' | 'polar' | 'suunto' | 'unknown'
+  serial?: string
+  model?: string
+  firmware?: string
+}
+export declare interface GarminDevice extends WatchDevice {
+  type: 'garmin'
+  unitId?: string
+  partNumber?: string
+  isGarminExpress?: boolean
+  garminExpressPath?: string
+}
+// ============================================================================
+// FIT File Types (Garmin's Flexible and Interoperable Data Transfer protocol)
+// ============================================================================
+export declare interface FitFileHeader {
+  headerSize: number
+  protocolVersion: number
+  profileVersion: number
+  dataSize: number
+  dataType: string
+  crc?: number
+}
+export declare interface FitField {
+  fieldDefNum: number
+  size: number
+  baseType: number
+}
+export declare interface FitDefinitionMessage {
+  reserved: number
+  arch: 'little' | 'big'
+  globalMsgNum: number
+  numFields: number
+  fields: FitField[]
+}
+export declare interface FitDataMessage {
+  globalMsgNum: number
+  fields: Map<number, unknown>
+}
+export declare interface FitRecord {
+  type: 'definition' | 'data'
+  localMsgType: number
+  message: FitDefinitionMessage | FitDataMessage
+}
+export declare interface GeoPosition {
+  lat: number
+  lng: number
+  altitude?: number
+}
+export declare interface HeartRateZone {
+  zone: number
+  min: number
+  max: number
+  timeInZone: number
+}
+export declare interface ActivityLap {
+  startTime: Date
+  endTime: Date
+  totalElapsedTime: number
+  totalTimerTime: number
+  totalDistance: number
+  totalCalories: number
+  avgHeartRate?: number
+  maxHeartRate?: number
+  avgSpeed?: number
+  maxSpeed?: number
+  avgCadence?: number
+  maxCadence?: number
+  avgPower?: number
+  maxPower?: number
+  totalAscent?: number
+  totalDescent?: number
+  startPosition?: GeoPosition
+  endPosition?: GeoPosition
+}
+export declare interface ActivityRecord {
+  timestamp: Date
+  position?: GeoPosition
+  heartRate?: number
+  cadence?: number
+  speed?: number
+  power?: number
+  altitude?: number
+  distance?: number
+  temperature?: number
+  grade?: number
+  calories?: number
+}
+export declare interface Activity {
+  id: string
+  name?: string
+  sport: SportType
+  subSport?: SubSportType
+  startTime: Date
+  endTime: Date
+  totalElapsedTime: number
+  totalTimerTime: number
+  totalDistance: number
+  totalCalories: number
+  avgHeartRate?: number
+  maxHeartRate?: number
+  avgSpeed?: number
+  maxSpeed?: number
+  avgCadence?: number
+  maxCadence?: number
+  avgPower?: number
+  maxPower?: number
+  normalizedPower?: number
+  totalAscent?: number
+  totalDescent?: number
+  trainingStressScore?: number
+  intensityFactor?: number
+  heartRateZones?: HeartRateZone[]
+  laps: ActivityLap[]
+  records: ActivityRecord[]
+  source: 'garmin' | 'manual' | 'import'
+  rawFilePath?: string
+}
+// ============================================================================
+// Health & Monitoring Types
+// ============================================================================
+export declare interface DailyHeartRate {
+  date: Date
+  restingHeartRate?: number
+  minHeartRate?: number
+  maxHeartRate?: number
+  avgHeartRate?: number
+  samples: Array<{
+    timestamp: Date
+    heartRate: number
+  }>
+}
+export declare interface SleepStage {
+  stage: 'awake' | 'light' | 'deep' | 'rem'
+  startTime: Date
+  endTime: Date
+}
+export declare interface SleepData {
+  date: Date
+  startTime: Date
+  endTime: Date
+  totalSleepTime: number
+  deepSleepTime: number
+  lightSleepTime: number
+  remSleepTime: number
+  awakeTime: number
+  sleepScore?: number
+  stages: SleepStage[]
+  avgHeartRate?: number
+  avgSpO2?: number
+  avgRespirationRate?: number
+}
+export declare interface StressData {
+  date: Date
+  avgStressLevel: number
+  maxStressLevel: number
+  restStressDuration: number
+  lowStressDuration: number
+  mediumStressDuration: number
+  highStressDuration: number
+  samples: Array<{
+    timestamp: Date
+    stressLevel: number
+  }>
+}
+export declare interface BodyBattery {
+  date: Date
+  startLevel: number
+  endLevel: number
+  chargedValue: number
+  drainedValue: number
+  samples: Array<{
+    timestamp: Date
+    level: number
+  }>
+}
+export declare interface DailySteps {
+  date: Date
+  totalSteps: number
+  goal: number
+  distance: number
+  calories: number
+  activeMinutes: number
+  floorsClimbed?: number
+}
+export declare interface SpO2Data {
+  date: Date
+  avgSpO2: number
+  minSpO2: number
+  maxSpO2: number
+  samples: Array<{
+    timestamp: Date
+    spO2: number
+  }>
+}
+export declare interface RespirationData {
+  date: Date
+  avgRespirationRate: number
+  minRespirationRate: number
+  maxRespirationRate: number
+  samples: Array<{
+    timestamp: Date
+    respirationRate: number
+  }>
+}
+export declare interface HRVData {
+  date: Date
+  weeklyAverage?: number
+  lastNightAverage?: number
+  status?: 'low' | 'unbalanced' | 'balanced' | 'high'
+  baseline?: number
+  samples: Array<{
+    timestamp: Date
+    hrv: number
+  }>
+}
+export declare interface WeightData {
+  date: Date
+  weight: number
+  bmi?: number
+  bodyFatPercentage?: number
+  bodyWater?: number
+  boneMass?: number
+  muscleMass?: number
+  visceralFat?: number
+  metabolicAge?: number
+}
+// ============================================================================
+// Aggregate Types
+// ============================================================================
+export declare interface MonitoringData {
+  heartRate?: DailyHeartRate
+  sleep?: SleepData
+  stress?: StressData
+  bodyBattery?: BodyBattery
+  steps?: DailySteps
+  spO2?: SpO2Data
+  respiration?: RespirationData
+  hrv?: HRVData
+}
+export declare interface DownloadResult {
+  device: WatchDevice
+  activities: Activity[]
+  monitoring: Map<string, MonitoringData>
+  rawFiles: string[]
+  errors: Error[]
+}
+// ============================================================================
+// Driver Interface
+// ============================================================================
+export declare interface WatchDriver {
+  readonly name: string
+  readonly type: WatchDevice['type']
+  detectDevices(): Promise<WatchDevice[]>
+  downloadData(device: WatchDevice, options?: DownloadOptions): Promise<DownloadResult>
+  parseActivityFile(filePath: string): Promise<Activity | null>
+  parseMonitoringFile(filePath: string): Promise<MonitoringData>
+}
+export declare interface DownloadOptions {
+  outputDir?: string
+  includeActivities?: boolean
+  includeMonitoring?: boolean
+  since?: Date
+  until?: Date
+  copyRawFiles?: boolean
+}
+export type WatchOptions = Partial<WatchConfig>;
+// ============================================================================
+// Activity Types
+// ============================================================================
+export type SportType = | 'running'
+  | 'cycling'
+  | 'swimming'
+  | 'hiking'
+  | 'walking'
+  | 'strength_training'
+  | 'cardio'
+  | 'yoga'
+  | 'other'
+  | 'generic';
+export type SubSportType = | 'generic'
+  | 'treadmill'
+  | 'street'
+  | 'trail'
+  | 'track'
+  | 'spin'
+  | 'indoor_cycling'
+  | 'road'
+  | 'mountain'
+  | 'gravel'
+  | 'lap_swimming'
+  | 'open_water'
+  | 'other';

package/dist/workouts/builder.d.ts

@@ -0,0 +1,184 @@
+import type { SportType } from '../types';
+/**
+ * Create a new workout builder
+ */
+export declare function createWorkout(name: string, sport: SportType): WorkoutBuilder;
+/**
+ * Format workout duration for display
+ */
+export declare function formatWorkoutDuration(duration: WorkoutDuration): string;
+/**
+ * Format workout target for display
+ */
+export declare function formatWorkoutTarget(workoutTarget: WorkoutTarget): string;
+/**
+ * Helper functions for common durations
+ * @defaultValue
+ * ```ts
+ * {
+ *   time: (seconds: number) => WorkoutDuration,
+ *   minutes: (minutes: number) => WorkoutDuration,
+ *   distance: (meters: number) => WorkoutDuration,
+ *   km: (km: number) => WorkoutDuration,
+ *   miles: (miles: number) => WorkoutDuration,
+ *   calories: (cal: number) => WorkoutDuration,
+ *   open: () => WorkoutDuration,
+ *   lapButton: () => WorkoutDuration,
+ *   untilHrBelow: (hr: number) => WorkoutDuration,
+ *   untilHrAbove: (hr: number) => WorkoutDuration
+ * }
+ * ```
+ */
+export declare const duration: {
+  time: (seconds: number) => WorkoutDuration;
+  minutes: (minutes: number) => WorkoutDuration;
+  distance: (meters: number) => WorkoutDuration;
+  km: (km: number) => WorkoutDuration;
+  miles: (miles: number) => WorkoutDuration;
+  calories: (cal: number) => WorkoutDuration;
+  open: () => WorkoutDuration;
+  lapButton: () => WorkoutDuration;
+  untilHrBelow: (hr: number) => WorkoutDuration;
+  untilHrAbove: (hr: number) => WorkoutDuration
+};
+/**
+ * Helper functions for common targets
+ * @defaultValue
+ * ```ts
+ * {
+ *   open: () => WorkoutTarget,
+ *   hrZone: (zone: number) => WorkoutTarget,
+ *   hrRange: (low: number, high: number) => WorkoutTarget,
+ *   hr: (bpm: number) => WorkoutTarget,
+ *   powerZone: (zone: number) => WorkoutTarget,
+ *   powerRange: (low: number, high: number) => WorkoutTarget,
+ *   power: (watts: number) => WorkoutTarget,
+ *   paceZone: (zone: number) => WorkoutTarget,
+ *   paceRange: (slowSecPerKm: number, fastSecPerKm: number) => WorkoutTarget,
+ *   pace: (secPerKm: number) => WorkoutTarget,
+ *   cadence: (spm: number) => WorkoutTarget,
+ *   cadenceRange: (low: number, high: number) => WorkoutTarget
+ * }
+ * ```
+ */
+export declare const target: {
+  open: () => WorkoutTarget;
+  hrZone: (zone: number) => WorkoutTarget;
+  hrRange: (low: number, high: number) => WorkoutTarget;
+  hr: (bpm: number) => WorkoutTarget;
+  powerZone: (zone: number) => WorkoutTarget;
+  powerRange: (low: number, high: number) => WorkoutTarget;
+  power: (watts: number) => WorkoutTarget;
+  paceZone: (zone: number) => WorkoutTarget;
+  paceRange: (slowSecPerKm: number, fastSecPerKm: number) => WorkoutTarget;
+  pace: (secPerKm: number) => WorkoutTarget;
+  cadence: (spm: number) => WorkoutTarget;
+  cadenceRange: (low: number, high: number) => WorkoutTarget
+};
+/**
+ * Common workout templates
+ * @defaultValue
+ * ```ts
+ * {
+ *   fiveByOneK: () => Workout,
+ *   thirtyThirty: (sets?: number) => Workout,
+ *   tempoRun: (tempoMinutes?: number) => Workout,
+ *   sweetSpot: (intervals?: number, minutes?: number) => Workout,
+ *   vo2maxIntervals: () => Workout
+ * }
+ * ```
+ */
+export declare const workoutTemplates: {
+  /**
+   * Classic 5x1km intervals for running
+   */
+  fiveByOneK: () => Workout;
+  /**
+   * 30/30 intervals
+   */
+  thirtyThirty: (sets?: number) => Workout;
+  /**
+   * Tempo run
+   */
+  tempoRun: (tempoMinutes?: number) => Workout;
+  /**
+   * Cycling sweet spot
+   */
+  sweetSpot: (intervals?: number, minutes?: number) => Workout;
+  /**
+   * VO2max intervals for cycling
+   */
+  vo2maxIntervals: () => Workout
+};
+export declare interface WorkoutTarget {
+  type: WorkoutTargetType
+  value?: number
+  low?: number
+  high?: number
+  zone?: number
+}
+export declare interface WorkoutDuration {
+  type: WorkoutDurationType
+  value?: number
+}
+export declare interface WorkoutStep {
+  type: WorkoutStepType
+  name?: string
+  notes?: string
+  duration: WorkoutDuration
+  target: WorkoutTarget
+  secondaryTarget?: WorkoutTarget
+}
+export declare interface WorkoutRepeatGroup {
+  type: 'repeat'
+  repeatCount: number
+  steps: WorkoutStep[]
+}
+export declare interface Workout {
+  id?: string
+  name: string
+  sport: SportType
+  description?: string
+  steps: (WorkoutStep | WorkoutRepeatGroup)[]
+  estimatedDuration?: number
+  estimatedDistance?: number
+  createdAt?: Date
+  updatedAt?: Date
+}
+export type WorkoutStepType = | 'warmup'
+  | 'cooldown'
+  | 'interval'
+  | 'recovery'
+  | 'rest'
+  | 'active'
+  | 'repeat';
+export type WorkoutTargetType = | 'open'
+  | 'heart_rate_zone'
+  | 'heart_rate'
+  | 'power_zone'
+  | 'power'
+  | 'pace_zone'
+  | 'pace'
+  | 'cadence'
+  | 'speed';
+export type WorkoutDurationType = | 'time'
+  | 'distance'
+  | 'calories'
+  | 'open'
+  | 'lap_button'
+  | 'heart_rate_less_than'
+  | 'heart_rate_greater_than'
+  | 'power_less_than'
+  | 'power_greater_than';
+export declare class WorkoutBuilder {
+  constructor(name: string, sport: SportType);
+  setDescription(description: string): this;
+  warmup(duration: WorkoutDuration, target?: WorkoutTarget): this;
+  cooldown(duration: WorkoutDuration, target?: WorkoutTarget): this;
+  interval(duration: WorkoutDuration, target: WorkoutTarget, name?: string): this;
+  recovery(duration: WorkoutDuration, target?: WorkoutTarget): this;
+  rest(duration: WorkoutDuration): this;
+  active(duration: WorkoutDuration, target: WorkoutTarget, name?: string): this;
+  repeat(count: number, builderFn: (builder: WorkoutBuilder) => void): this;
+  build(): Workout;
+}

package/dist/workouts/course.d.ts

@@ -0,0 +1,74 @@
+import type { GeoPosition, Activity } from '../types';
+/**
+ * Create a new course builder
+ */
+export declare function createCourse(name: string, sport?: Course['sport']): CourseBuilder;
+/**
+ * Export course to GPX format
+ */
+export declare function courseToGpx(course: Course): string;
+/**
+ * Export course to TCX course format
+ */
+export declare function courseToTcx(course: Course): string;
+export declare interface CoursePoint {
+  position: GeoPosition
+  distance: number
+  name?: string
+  type?: CoursePointType
+  notes?: string
+}
+export declare interface Course {
+  id?: string
+  name: string
+  description?: string
+  sport: 'running' | 'cycling' | 'hiking' | 'walking'
+  trackPoints: GeoPosition[]
+  coursePoints: CoursePoint[]
+  totalDistance: number
+  totalAscent: number
+  totalDescent: number
+  createdAt?: Date
+  updatedAt?: Date
+}
+export type CoursePointType = | 'generic'
+  | 'summit'
+  | 'valley'
+  | 'water'
+  | 'food'
+  | 'danger'
+  | 'left'
+  | 'right'
+  | 'straight'
+  | 'first_aid'
+  | 'fourth_category'
+  | 'third_category'
+  | 'second_category'
+  | 'first_category'
+  | 'hors_category'
+  | 'sprint';
+export declare class CourseBuilder {
+  constructor(name: string, sport?: Course['sport']);
+  setDescription(description: string): this;
+  setSport(sport: Course['sport']): this;
+  addPoint(lat: number, lng: number, altitude?: number): this;
+  addPoints(points: Array<{
+    lat: number
+    lng: number
+    altitude?: number
+  }>): this;
+  addCoursePoint(lat: number, lng: number, type: CoursePointType, name?: string, notes?: string): this;
+  addWaterStation(lat: number, lng: number, name?: string): this;
+  addFoodStation(lat: number, lng: number, name?: string): this;
+  addTurn(lat: number, lng: number, direction: 'left' | 'right' | 'straight', notes?: string): this;
+  addClimbCategory(lat: number, lng: number, category: 1 | 2 | 3 | 4 | 'hors', name?: string): this;
+  addSprint(lat: number, lng: number, name?: string): this;
+  addSummit(lat: number, lng: number, name?: string): this;
+  fromActivity(activity: Activity): this;
+  fromGeoJson(geoJson: {
+    type: string
+    coordinates: number[][]
+  }): this;
+  reverse(): this;
+  build(): Course;
+}

package/dist/workouts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './builder';
+export * from './course';
+export * from './training-plan';

package/dist/workouts/training-plan.d.ts

@@ -0,0 +1,77 @@
+import type { SportType } from '../types';
+import type { Workout } from './builder';
+/**
+ * Generate a marathon training plan
+ */
+export declare function generateMarathonPlan(config: MarathonPlanConfig): TrainingPlan;
+/**
+ * Generate a 5K training plan
+ */
+export declare function generate5kPlan(config: FiveKPlanConfig): TrainingPlan;
+/**
+ * Export training plan to iCal format
+ */
+export declare function planToIcal(plan: TrainingPlan): string;
+export declare function createTrainingPlan(config: TrainingPlanConfig): TrainingPlanBuilder;
+export declare interface TrainingWeek {
+  weekNumber: number
+  phase: TrainingPhase
+  description?: string
+  workouts: ScheduledWorkout[]
+  targetTSS?: number
+  targetDistance?: number
+  targetDuration?: number
+}
+export declare interface ScheduledWorkout {
+  dayOfWeek: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  workout: Workout
+  notes?: string
+}
+export declare interface TrainingPlan {
+  id?: string
+  name: string
+  description?: string
+  sport: SportType
+  goalRace?: {
+    name: string
+    date: Date
+    distance: number
+  }
+  weeks: TrainingWeek[]
+  startDate: Date
+  endDate: Date
+  createdAt?: Date
+  updatedAt?: Date
+}
+export declare interface TrainingPlanConfig {
+  name: string
+  sport: SportType
+  goalRaceDate: Date
+  goalRaceDistance: number
+  currentFitness: 'beginner' | 'intermediate' | 'advanced'
+  weeklyHours: number
+  longRunDay?: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  restDays?: Array<0 | 1 | 2 | 3 | 4 | 5 | 6>
+}
+export declare interface MarathonPlanConfig {
+  raceDate: Date
+  name?: string
+  currentWeeklyMileage: number
+  fitness: 'beginner' | 'intermediate' | 'advanced'
+}
+export declare interface FiveKPlanConfig {
+  raceDate: Date
+  name?: string
+  fitness: 'beginner' | 'intermediate' | 'advanced'
+}
+export type TrainingPhase = | 'base'
+  | 'build'
+  | 'peak'
+  | 'taper'
+  | 'recovery';
+export declare class TrainingPlanBuilder {
+  constructor(config: TrainingPlanConfig);
+  addWeek(week: TrainingWeek): this;
+  setDescription(description: string): this;
+  build(): TrainingPlan;
+}