Skip to main content

@wellpipe/core

The core package contains shared interfaces, types, and utilities used across all Wellpipe packages. It defines the contracts that providers must implement and the normalized data structures they return.

Installation​

npm install @wellpipe/core

Package Philosophy​

Minimal Dependencies​

@wellpipe/core has exactly one runtime dependency: Zod. This is intentional:

  • Zod provides runtime validation for API responses
  • No other dependencies means smaller bundle sizes
  • Reduces version conflicts across the ecosystem

Provider Independence​

The core package defines interfaces that any health data provider can implement. This enables:

  • Consistent data structures across WHOOP, Oura, Garmin, etc.
  • Swappable providers without changing consumer code
  • Type-safe development with full IntelliSense

What's Included​

Interfaces​

InterfacePurpose
TokenProviderOAuth token management contract
HealthProviderHealth data access contract

Types​

TypePurpose
SleepDataNormalized sleep session data
RecoveryDataNormalized recovery/readiness data
WorkoutDataNormalized workout/activity data
SleepStagesSleep stage breakdown

Zod Schemas​

Each type has a corresponding Zod schema for runtime validation:

import { SleepDataSchema, RecoveryDataSchema } from '@wellpipe/core';

// Validate API response
const validated = SleepDataSchema.parse(apiResponse);

Usage Example​

import type { HealthProvider, SleepData } from '@wellpipe/core';

class MyProvider implements HealthProvider {
  readonly name = 'my-provider';

  async getSleep(startDate: string, endDate: string): Promise<SleepData[]> {
    const response = await this.fetchFromApi('/sleep', { startDate, endDate });
    return this.normalizeSleepData(response);
  }

  async getRecovery(startDate: string, endDate: string): Promise<RecoveryData[]> {
    // Implementation
  }

  async getWorkouts(startDate: string, endDate: string): Promise<WorkoutData[]> {
    // Implementation
  }
}

Source Code​

The package source is available on GitHub: