ts-watches

Features

Device Support

Data Parsing

Data Export

Cloud Integrations

Training Analysis

Workout Tools

Real-time Data

Developer Experience

Direct Garmin Bluetooth

import { connectGarminBluetooth, garminFileIdentity } from 'ts-watches/garmin-bluetooth'
import { decodeGarminHealthFile } from 'ts-watches/fit'

// bluetooth is the native Craft host; selectedId comes from explicit scanning/pairing.
const client = await connectGarminBluetooth(bluetooth, selectedId)
try {
  await client.sync({
    seen: entry => savedFiles.has(garminFileIdentity(entry)),
    async onFile(file) {
      // Persist the complete verified file before acknowledging this callback.
      await saveOriginal(file)
      const health = decodeGarminHealthFile(file.bytes, athleteTimeZone)
      await importHealth(health)
    },
  })
}
finally {
  await client.close()
}

Install

bun install ts-watches

Quick Start

import { createGarminDriver } from 'ts-watches'

const driver = createGarminDriver()

// Detect connected devices
const devices = await driver.detectDevices()
console.log('Found devices:', devices)

// Download data from a device
if (devices.length > 0) {
  const result = await driver.downloadData(devices[0], {
    outputDir: './my-watch-data',
    includeActivities: true,
    includeMonitoring: true,
  })

  console.log(`Downloaded ${result.activities.length} activities`)
  console.log(`Downloaded ${result.monitoring.size} days of monitoring data`)
}

Usage Examples

Parse FIT Files

import { createGarminDriver } from 'ts-watches'

const driver = createGarminDriver()
const activity = await driver.parseActivityFile('/path/to/activity.fit')

console.log(`${activity.sport}: ${(activity.totalDistance / 1000).toFixed(2)}km`)
console.log(`Duration: ${Math.floor(activity.totalTime / 60)} minutes`)
console.log(`Avg HR: ${activity.avgHeartRate} bpm`)

Export to GPX

import { activityToGpx, activityToTcx, activityToCsv } from 'ts-watches'

// Export activity to GPX
const gpx = activityToGpx(activity)
await Bun.write('activity.gpx', gpx)

// Export to TCX for Strava upload
const tcx = activityToTcx(activity)
await Bun.write('activity.tcx', tcx)

// Export to CSV for analysis
const csv = activityToCsv(activity)
await Bun.write('activity.csv', csv)

Training Analysis

import { calculateTSS, ZoneCalculator, RacePredictor } from 'ts-watches'

// Calculate Training Stress Score
const tss = calculateTSS(activity, { ftp: 250 })

// Analyze zones
const zones = new ZoneCalculator({ maxHR: 185, restingHR: 50, ftp: 250 })
const zoneAnalysis = zones.analyzeActivity(activity)

// Predict race times
const predictor = new RacePredictor()
const predictions = predictor.predictFromPerformance(5000, 20 * 60) // 5K in 20min
console.log(`Predicted marathon: ${predictions.marathon}`)

Cloud Integration

import { GarminActivityApiClient, GarminConnectClient, StravaClient } from 'ts-watches'

// Garmin Activity API (official, OAuth 2.0 PKCE, push notifications).
// The athlete approves on Garmin's own site and can revoke at any time.
const garmin = new GarminActivityApiClient({
  clientId: process.env.GARMIN_CLIENT_ID!,
  clientSecret: process.env.GARMIN_CLIENT_SECRET!,
  redirectUri: 'https://example.com/garmin/callback',
})

const { verifier, challenge } = createPkcePair()
const url = garmin.buildAuthorizationUrl({ state, challenge }) // send the athlete here
const tokens = await garmin.exchangeCode(code, verifier) // on the callback
const userId = await garmin.getUserId(tokens.accessToken) // the key push notifications carry

// Garmin Connect (unofficial; needs the athlete's password, breaks under 2FA)
const legacy = new GarminConnectClient()
await legacy.login('[email protected]', 'password')
const activities = await legacy.getActivities(new Date('2024-01-01'))
const { bytes, filename } = await legacy.downloadOriginalActivity(activityId) // "Export Original" zip, in memory
// Structured workouts onto the watch: into the library, then onto a day
const { workoutId } = await legacy.createWorkout(workout) // Connect's workout JSON
const { workoutScheduleId } = await legacy.scheduleWorkout(workoutId, '2026-10-20')
await legacy.deleteWorkout(workoutId) // a 404 counts as done

// Strava
const strava = new StravaClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
})
const authUrl = strava.getAuthorizationUrl('http://localhost:3000/callback')

Build Workouts

import { WorkoutBuilder, workoutTemplates } from 'ts-watches'

// Use a template
const intervals = workoutTemplates.vo2maxIntervals({ ftp: 250 })

// Or build custom workout
const workout = new WorkoutBuilder('Custom Threshold')
  .warmup({ duration: 600, targetPower: { min: 100, max: 150 } })
  .interval({ duration: 1200, targetPower: { min: 240, max: 260 } })
  .recovery({ duration: 300, targetPower: { min: 100, max: 130 } })
  .repeat(4)
  .cooldown({ duration: 600, targetPower: { min: 100, max: 130 } })
  .build()

Real-time Data

import { createLiveTracking, createBleScanner } from 'ts-watches'

// Live tracking
const tracker = createLiveTracking({
  updateInterval: 5000,
  onUpdate: (session) => console.log(`Distance: ${session.totalDistance}m`),
})

tracker.start('Morning Run')
tracker.updatePosition({ lat: 37.7749, lng: -122.4194, altitude: 10 })

// BLE sensors
const ble = createBleScanner()
await ble.startScanning()
ble.on('data', (device, data) => {
  if (data.type === 'heart_rate') {
    console.log(`HR: ${data.data.heartRate} bpm`)
  }
})

CLI

# Detect connected watches
watch detect

# Download all data from connected watch
watch download

# Download to specific directory
watch download --output ./my-data

# Download only activities from the last week
watch download --activities --since 2024-01-01

# Parse a single FIT file
watch parse /path/to/activity.fit

# Parse and output as JSON
watch parse /path/to/activity.fit --format json

# Watch for device connection and auto-download
watch watch

Supported Data Types

Activities

Health Metrics

Training Metrics

Device Setup

Garmin

Polar

Apple Watch

API Reference

Testing

bun test

Changelog

Contributing

Community

Postcardware

Sponsors

License