Skip to main content

API Reference

This section contains the auto-generated API reference for @wellpipe/core.

TypeDoc Integration

Once TypeDoc is configured, this section will be automatically generated from JSDoc comments in the source code. For now, this is a manual reference.

Interfaces​

TokenProvider​

Manages OAuth tokens for health provider APIs.

interface TokenProvider {
  /**
   * Get the current access token.
   * May trigger a refresh if the token is expired.
   */
  getAccessToken(): Promise<string>;

  /**
   * Get the refresh token, if available.
   */
  getRefreshToken(): Promise<string | undefined>;

  /**
   * Update stored tokens after a refresh or new authentication.
   * @param accessToken - New access token
   * @param refreshToken - New refresh token (optional)
   * @param expiresAt - Token expiration time (optional)
   */
  updateTokens(
    accessToken: string,
    refreshToken?: string,
    expiresAt?: Date
  ): Promise<void>;

  /**
   * Check if the current access token is expired.
   */
  isExpired(): Promise<boolean>;
}

HealthProvider​

Common interface for health data providers.

interface HealthProvider {
  /**
   * Provider identifier (e.g., 'whoop', 'oura').
   */
  readonly name: string;

  /**
   * Get sleep data for a date range.
   */
  getSleep(startDate: string, endDate: string): Promise<SleepData[]>;

  /**
   * Get recovery data for a date range.
   */
  getRecovery(startDate: string, endDate: string): Promise<RecoveryData[]>;

  /**
   * Get workout data for a date range.
   */
  getWorkouts(startDate: string, endDate: string): Promise<WorkoutData[]>;
}

Types​

SleepData​

Normalized sleep data structure.

interface SleepData {
  id: string;
  providerId: string;
  start: string;  // ISO 8601 datetime
  end: string;    // ISO 8601 datetime
  durationMs: number;
  isNap: boolean;
  score?: number;  // 0-100
  stages?: SleepStages;
  metrics?: {
    efficiency?: number;
    respiratoryRate?: number;
  };
}

interface SleepStages {
  lightMs: number;
  deepMs: number;
  remMs: number;
  awakeMs: number;
}

RecoveryData​

Normalized recovery data structure.

interface RecoveryData {
  id: string;
  providerId: string;
  date: string;  // YYYY-MM-DD
  score?: number;  // 0-100
  metrics?: {
    hrv?: number;
    restingHeartRate?: number;
    spo2?: number;
    skinTemp?: number;
  };
}

WorkoutData​

Normalized workout data structure.

interface WorkoutData {
  id: string;
  providerId: string;
  start: string;  // ISO 8601 datetime
  end: string;    // ISO 8601 datetime
  durationMs: number;
  sportType: string;
  strain?: number;
  metrics?: {
    averageHeartRate?: number;
    maxHeartRate?: number;
    calories?: number;
    distance?: number;
  };
}

Usage​

Installing​

npm install @wellpipe/core

Importing​

import {
  TokenProvider,
  HealthProvider,
  SleepData,
  RecoveryData,
  WorkoutData,
} from '@wellpipe/core';

Implementing TokenProvider​

import { TokenProvider } from '@wellpipe/core';

class MyTokenProvider implements TokenProvider {
  private accessToken: string;
  private refreshToken?: string;
  private expiresAt?: Date;

  async getAccessToken(): Promise<string> {
    if (await this.isExpired()) {
      await this.refresh();
    }
    return this.accessToken;
  }

  async getRefreshToken(): Promise<string | undefined> {
    return this.refreshToken;
  }

  async updateTokens(
    accessToken: string,
    refreshToken?: string,
    expiresAt?: Date
  ): Promise<void> {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
    this.expiresAt = expiresAt;
  }

  async isExpired(): Promise<boolean> {
    if (!this.expiresAt) return false;
    return new Date() >= this.expiresAt;
  }

  private async refresh(): Promise<void> {
    // Implement token refresh logic
  }
}

Source​

View the source code on GitHub: