Skip to main content

@wellpipe/garmin

The Garmin provider package implements the Garmin Connect API integration for Wellpipe. It handles SSO authentication, API communication, data normalization, and provides MCP tools for AI assistants.

Installation​

npm install @wellpipe/garmin

Features​

  • Complete Garmin Connect API integration
  • SSO authentication with MFA support
  • Automatic OAuth2 token refresh using OAuth1 credentials
  • 32 MCP tools for AI assistants
  • Rate limiting and retry logic
  • Multiple token storage backends

Quick Start​

import { GarminClient, GarminTokenProvider, FileTokenStorage } from '@wellpipe/garmin';

// Create storage and token provider
const storage = new FileTokenStorage('~/.garmin');
const tokenProvider = new GarminTokenProvider(storage);

// Initialize the client
const client = new GarminClient(tokenProvider);

// Fetch health data
const sleepData = await client.getSleep(new Date('2024-01-01'));
console.log(sleepData);

Package Structure​

@wellpipe/garmin/
├── src/
│   ├── index.ts           # Package exports
│   ├── client.ts          # GarminClient class
│   ├── sso.ts             # SSO authentication
│   ├── token-provider.ts  # Token management
│   ├── api/               # API wrappers
│   │   ├── sleep.ts
│   │   ├── stats.ts
│   │   ├── hrv.ts
│   │   ├── stress.ts
│   │   ├── body.ts
│   │   ├── activities.ts
│   │   ├── training.ts
│   │   ├── devices.ts
│   │   └── ...
│   ├── tools/             # MCP tool definitions
│   │   ├── sleep.ts       # 3 sleep tools
│   │   ├── health.ts      # 9 health tools
│   │   ├── activities.ts  # 10 activity tools
│   │   └── training.ts    # 10 training tools
│   ├── mcp/               # MCP server
│   │   └── server.ts
│   └── types/             # Type definitions
└── package.json

Authentication​

SSO (Credential-Based)​

The package uses Garmin's SSO system for authentication:

import { login, completeMFALogin } from '@wellpipe/garmin';

// Initial login
const result = await login(email, password);

// Handle MFA if required
if ('needs_mfa' in result) {
  const mfaCode = '123456'; // Get from user
  const tokens = await completeMFALogin(mfaCode, result);
  // tokens.oauth1, tokens.oauth2
} else {
  // Login succeeded without MFA
  // result.oauth1, result.oauth2
}

Token Refresh​

OAuth2 tokens expire but can be refreshed using the long-lived OAuth1 credentials:

import { refreshOAuth2Token, isOAuth2Expired } from '@wellpipe/garmin';

if (isOAuth2Expired(oauth2Token)) {
  const newOAuth2 = await refreshOAuth2Token(oauth1Token);
}

The GarminTokenProvider handles this automatically.

Dependencies​

PackagePurpose
@wellpipe/coreShared interfaces and types
zodRuntime validation

The package has minimal dependencies to keep bundle size small.

API Coverage​

CategoryEndpoints
SleepDaily sleep, sleep stages, SpO2, respiration
Heart RateAll-day HR, resting HR, zones
HRVDaily HRV, status, baseline
StressStress levels, body battery
BodyWeight, composition, hydration
ActivitiesList, details, splits, weather, downloads
TrainingStatus, readiness, VO2 max, race predictions
DevicesDevice list, settings
GoalsActive goals, personal records

Rate Limits​

The Garmin Connect API has undocumented rate limits. The client handles this with:

  • Exponential backoff on 429 responses
  • Automatic retry with delays
  • Request queuing (optional)