suunto-api-wrapper 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,511 @@
+type RequestBody = NonNullable<RequestInit["body"]>;
+type QueryValue = string | number | boolean | null | undefined;
+type Query = Record<string, QueryValue | QueryValue[]>;
+interface HttpClientOptions {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    retries?: number;
+    retryBackoffMs?: number;
+    fetch?: typeof fetch;
+    beforeRequest?: (ctx: RequestContext) => void | RequestContext | Promise<void | RequestContext>;
+}
+interface RequestContext {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: RequestBody | null;
+}
+interface RequestOptions {
+    query?: Query;
+    headers?: Record<string, string>;
+    json?: unknown;
+    body?: RequestBody | null;
+    timeoutMs?: number;
+    retries?: number;
+    signal?: AbortSignal;
+}
+interface HttpResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly method: string;
+    readonly body: unknown;
+    constructor(message: string, init: {
+        status: number;
+        url: string;
+        method: string;
+        body: unknown;
+    });
+}
+
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly retryBackoffMs;
+    private readonly fetchImpl;
+    private readonly beforeRequest?;
+    constructor(options?: HttpClientOptions);
+    get<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    delete<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    post<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    put<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    patch<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    private attempt;
+    private toResult;
+    private backoff;
+    private buildUrl;
+}
+
+declare function generateXtotp(email: string, now?: number): string;
+declare function secondsUntilRollover(now?: number): number;
+
+interface LoginOptions {
+    email: string;
+    password: string;
+    version?: string;
+    userAgent?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+interface LoginResponse {
+    sessionkey?: string;
+    [key: string]: unknown;
+}
+
+declare const SPORTS_TRACKER_API = "https://api.sports-tracker.com";
+declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36";
+declare function login(options: LoginOptions): Promise<LoginResponse>;
+declare function sessionTokenFrom(response: LoginResponse): string | undefined;
+
+interface GetWorkoutsParams {
+    limit?: number;
+    sortonst?: boolean;
+}
+interface GetOwnWorkoutsParams {
+    since?: number;
+    offset?: number;
+    limit?: number;
+}
+/** GPS coordinate: x = longitude, y = latitude. */
+interface Position {
+    x: number;
+    y: number;
+}
+interface Cadence {
+    max: number;
+    avg: number;
+}
+interface HrData {
+    workoutMaxHR: number;
+    workoutAvgHR: number;
+    userMaxHR: number;
+    avg: number;
+    hrmax: number;
+    max: number;
+}
+interface Gear {
+    manufacturer: string;
+    name: string;
+    displayName: string;
+    serialNumber: string;
+    softwareVersion: string;
+    hardwareVersion: string;
+    productType: string;
+}
+interface HeartRateRecovery {
+    comparisonLevel: string;
+    drop: number;
+    level: string;
+}
+interface TssEntry {
+    calculationMethod: string;
+    trainingStressScore: number;
+    intensityFactor: number | null;
+    normalizedPower: number | null;
+    averageGradeAdjustedPace: number | null;
+}
+interface RouteRanking {
+    originalRanking: number;
+    originalNumberOfWorkouts: number;
+}
+interface Rankings {
+    totalTimeOnRouteRanking: RouteRanking;
+}
+interface ActivityCounts {
+    timeCategory: number;
+    currentCount: number;
+    previousCount: number | null;
+    firstInCount: number | null;
+    activityCount: number | null;
+    activityTypeCount: number | null;
+}
+interface CumulativeAchievement {
+    description: number;
+    activityCounts: ActivityCounts;
+}
+interface PersonalBestAchievement {
+    timeCategory: number;
+    valueCategory: number;
+    since: string | null;
+}
+interface ClientCalculatedAchievements {
+    cumulativeAchievements: CumulativeAchievement[];
+    personalBestAchievements: PersonalBestAchievement[];
+}
+interface WorkoutComment {
+    key: string;
+    timestamp: number;
+    username: string;
+    realname: string;
+    profilePictureUrl: string | null;
+    comment: string;
+}
+interface WorkoutReaction {
+    utfCode: string;
+    count: number;
+    userReacted: boolean;
+}
+interface IntensityZone {
+    totalTime: number;
+    lowerLimit: number;
+}
+interface IntensityZones {
+    zone1: IntensityZone;
+    zone2: IntensityZone;
+    zone3: IntensityZone;
+    zone4: IntensityZone;
+    zone5: IntensityZone;
+}
+interface FitnessExtension {
+    type: "FitnessExtension";
+    maxHeartRate: number | null;
+    vo2Max: number | null;
+    estimatedVo2Max: number | null;
+    fitnessAge: number | null;
+}
+interface IntensityExtension {
+    type: "IntensityExtension";
+    zones: {
+        heartRate: IntensityZones | null;
+        speed: IntensityZones | null;
+        power: IntensityZones | null;
+    };
+    physiologicalThresholds: unknown | null;
+    overallIntensity: unknown | null;
+}
+interface SummaryExtension {
+    type: "SummaryExtension";
+    avgSpeed: number | null;
+    avgPower: number | null;
+    maxPower: number | null;
+    avgVerticalOscillation: number | null;
+    avgStrideLength: number | null;
+    avgGroundContactTime: number | null;
+    avgCadence: number | null;
+    maxCadence: number | null;
+    ascent: number | null;
+    descent: number | null;
+    ascentTime: number | null;
+    descentTime: number | null;
+    pte: number | null;
+    peakEpoc: number | null;
+    performanceLevel: number | null;
+    recoveryTime: number | null;
+    weather: unknown | null;
+    minTemperature: number | null;
+    avgTemperature: number | null;
+    maxTemperature: number | null;
+    workoutType: unknown | null;
+    /** 1–5 rating, or null if not set. */
+    feeling: number | null;
+    tags: unknown | null;
+    gear: Gear | null;
+    additionalGears: unknown | null;
+    exerciseId: string;
+    apps: unknown[];
+    repetitionCount: number | null;
+    lacticThHr: number | null;
+    avgAscentSpeed: number | null;
+    maxAscentSpeed: number | null;
+    avgDescentSpeed: number | null;
+    maxDescentSpeed: number | null;
+    avgDistancePerStroke: number | null;
+    fatConsumption: number | null;
+    carbohydrateConsumption: number | null;
+    avgLeftGroundContactBalance: number | null;
+    avgRightGroundContactBalance: number | null;
+    lacticThPace: number | null;
+    avgFlightTime: number | null;
+    avgContactTimeRatio: number | null;
+    teamSportId: unknown | null;
+    heartRateRecovery: HeartRateRecovery | null;
+    finalEndurance: unknown | null;
+    minimumEndurance: unknown | null;
+    curEnduranceDistance: unknown | null;
+    minEnduranceDistance: unknown | null;
+    enduranceValid: unknown | null;
+}
+/** Present on outdoor workouts that have weather data. */
+interface WeatherExtension {
+    type: "WeatherExtension";
+    weatherIcon: string;
+    temperature: number;
+    windSpeed: number;
+    windDirection: number;
+    humidity: number;
+}
+/** Present only on pool-swimming workouts (activityId 21). */
+interface SwimmingHeaderExtension {
+    type: "SwimmingHeaderExtension";
+    avgSwolf: number;
+    avgStrokeRate: number;
+    poolLength: number;
+    breaststrokeGlideTime: number | null;
+    ventilationFrequency: number | null;
+    avgFreestyleBreathAngle: number | null;
+    maxFreestyleBreathAngle: number | null;
+    freestyleGlideAngle: number | null;
+    avgBreaststrokeBreathAngle: number | null;
+    maxBreaststrokeBreathAngle: number | null;
+    freestyleDuration: number | null;
+    breaststrokeDuration: number | null;
+    otherStylesDuration: number | null;
+    freestylePercent: number | null;
+    breaststrokePercent: number | null;
+    otherStylesPercent: number | null;
+    breaststrokeHeadAngle: number | null;
+}
+type WorkoutExtension = FitnessExtension | IntensityExtension | SummaryExtension | WeatherExtension | SwimmingHeaderExtension;
+interface Workout {
+    username: string;
+    sharingFlags: number;
+    /** Suunto activity type ID (e.g. 2 = cycling, 11 = trail running, 21 = pool swim, 36 = gym, 99 = other). */
+    activityId: number;
+    key: string;
+    startTime: number;
+    stopTime: number;
+    totalTime: number;
+    estimatedFloorsClimbed: number;
+    totalDistance: number;
+    totalAscent: number;
+    totalDescent: number;
+    startPosition: Position;
+    stopPosition: Position;
+    centerPosition: Position;
+    maxSpeed: number;
+    /** Encoded polyline string. Absent on indoor/GPS-less workouts. */
+    polyline?: string;
+    stepCount: number;
+    recoveryTime: number;
+    cumulativeRecoveryTime: number;
+    rankings: Rankings;
+    extensions: WorkoutExtension[];
+    /** Absent on pool-swimming workouts. */
+    minAltitude?: number;
+    /** Absent on pool-swimming workouts. */
+    maxAltitude?: number;
+    isManuallyAdded: boolean;
+    tss: TssEntry;
+    tssList: TssEntry[];
+    suuntoTags: string[];
+    clientCalculatedAchievements: ClientCalculatedAchievements;
+    workoutKey: string;
+    visibilityFacebook: boolean;
+    visibilityTwitter: boolean;
+    viewCount: number;
+    visibilityGroups: boolean;
+    pictureCount: number;
+    commentCount: number;
+    reactionCount: number;
+    created: number;
+    timeInZone0: number;
+    timeInZone1: number;
+    timeInZone2: number;
+    timeInZone3: number;
+    timeInZone4: number;
+    timeInZone5: number;
+    visibilityExplore: boolean;
+    avgPace: number;
+    visibilityFriends: boolean;
+    energyConsumption: number;
+    avgSpeed: number;
+    hrdata: HrData;
+    cadence: Cadence;
+    timeOffsetInMinutes: number;
+    lastModified: number;
+    /** Only present when commentCount > 0. */
+    comments?: WorkoutComment[];
+    /** Only present when reactionCount > 0. */
+    reactions?: WorkoutReaction[];
+}
+interface WorkoutsResponse {
+    error: string | null;
+    payload: Workout[];
+    metadata: {
+        workoutcount: string;
+        until: string;
+    };
+}
+
+declare function getWorkouts(client: HttpClient, username: string, params?: GetWorkoutsParams): Promise<WorkoutsResponse>;
+declare function getOwnWorkouts(client: HttpClient, params?: GetOwnWorkoutsParams): Promise<WorkoutsResponse>;
+/** Workout endpoints, bound to an {@link HttpClient}. Accessed via `suunto.workouts`. */
+declare class WorkoutsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** The authenticated user's own workouts. */
+    own(params?: GetOwnWorkoutsParams): Promise<WorkoutsResponse>;
+    /** A given user's public workouts. */
+    public(username: string, params?: GetWorkoutsParams): Promise<WorkoutsResponse>;
+}
+
+interface UserProfile {
+    username: string;
+    createdDate: number;
+    lastModified: number;
+    lastLogin: number;
+    realName: string;
+    /** ISO 3166-1 alpha-2 country code. */
+    country: string;
+    gender: string;
+    uuid: string;
+    blocked: boolean;
+    showLocale: boolean;
+    followersCount: number;
+    followingCount: number;
+    currentBlobStorageLocation: string;
+    defaultBinaryStorageLocation: string;
+}
+interface UserProfileResponse {
+    error: string | null;
+    payload: UserProfile;
+    metadata: {
+        ts: string;
+    };
+}
+/** User shape returned by the search endpoint (differs slightly from {@link UserProfile}). */
+interface SearchUser {
+    username: string;
+    createdDate: number;
+    lastModified: number;
+    lastLogin: number;
+    realName: string;
+    /** ISO 3166-1 country code. Mostly alpha-2, but legacy records may use alpha-3 (e.g. "FRA"). */
+    country?: string;
+    city?: string;
+    gender: string;
+    uuid: string;
+    imageKey?: string;
+    profileImageUrl?: string;
+    showLocale: boolean;
+    defaultBinaryStorageLocation: string;
+    currentBlobStorageLocation: string;
+    key: string;
+}
+interface UserSearchResult {
+    /** Relationship to the searching user, e.g. "STRANGER". */
+    connection: string;
+    user: SearchUser;
+    workout: unknown | null;
+}
+interface UserSearchResponse {
+    error: string | null;
+    payload: UserSearchResult[];
+    metadata: {
+        ts: string;
+    };
+}
+
+/**
+ * Fetch a user's public profile by username. Unauthenticated — no session
+ * required.
+ */
+declare function getUserByName(client: HttpClient, username: string): Promise<UserProfileResponse>;
+/** Search for users by name/username. */
+declare function searchUsers(client: HttpClient, searchTerms: string): Promise<UserSearchResponse>;
+/** User endpoints, bound to an {@link HttpClient}. Accessed via `suunto.users`. */
+declare class UsersResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** A user's public profile, by username. */
+    byName(username: string): Promise<UserProfileResponse>;
+    /** Search for users by name/username. */
+    search(searchTerms: string): Promise<UserSearchResponse>;
+}
+
+interface GetLatestGearParams {
+    /** Include all gear types, not just the default. Default: true. */
+    allTypes?: boolean;
+}
+interface GearSummary {
+    serialNumber: string;
+    displayName: string;
+    productType: string;
+}
+interface GearResponse {
+    error: string | null;
+    payload: GearSummary[];
+    metadata: {
+        ts: string;
+    };
+}
+
+/** A user's latest gear. */
+declare function getLatestGear(client: HttpClient, username: string, params?: GetLatestGearParams): Promise<GearResponse>;
+/** Gear endpoints, bound to an {@link HttpClient}. Accessed via `suunto.gear`. */
+declare class GearResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** A user's latest (?) gear. */
+    latest(username: string, params?: GetLatestGearParams): Promise<GearResponse>;
+}
+
+interface SuuntoClientOptions extends Omit<HttpClientOptions, "beforeRequest"> {
+    /**
+     * Account email. Drives the `x-totp` header. Omit it (e.g. via
+     * {@link SuuntoClient.unauthenticated}) to use only unauthenticated endpoints
+     * such as `users.byName`.
+     */
+    email?: string;
+    /** Session key from login — sent as the `Sttauthorization` header. */
+    sessionKey?: string;
+    userAgent?: string;
+}
+/**
+ * The main entry point. Owns the authenticated {@link HttpClient} and exposes
+ * the API grouped by resource.
+ *
+ * @example
+ * ```ts
+ * const suunto = await SuuntoClient.login({ email, password });
+ * const workouts = await suunto.workouts.own({ limit: 5 });
+ * ```
+ */
+declare class SuuntoClient {
+    /** The underlying HTTP client, for advanced or not-yet-wrapped endpoints. */
+    readonly http: HttpClient;
+    /** Session key in use, if the client was authenticated. */
+    readonly sessionKey?: string;
+    readonly workouts: WorkoutsResource;
+    readonly users: UsersResource;
+    readonly gear: GearResource;
+    constructor(options: SuuntoClientOptions);
+    /** Log in with email/password and return an authenticated client. */
+    static login(options: LoginOptions & Omit<SuuntoClientOptions, "email" | "sessionKey">): Promise<SuuntoClient>;
+    /**
+     * Create a client with no credentials, for unauthenticated endpoints only
+     * (e.g. {@link UsersResource.byName}). No `x-totp` or session header is sent.
+     */
+    static unauthenticated(options?: Omit<SuuntoClientOptions, "email" | "sessionKey">): SuuntoClient;
+}
+
+export { type ActivityCounts, type Cadence, type ClientCalculatedAchievements, type CumulativeAchievement, DEFAULT_USER_AGENT, type FitnessExtension, type Gear, GearResource, type GearResponse, type GearSummary, type GetLatestGearParams, type GetOwnWorkoutsParams, type GetWorkoutsParams, type HeartRateRecovery, type HrData, HttpClient, type HttpClientOptions, HttpError, type HttpResponse, type IntensityExtension, type IntensityZone, type IntensityZones, type LoginOptions, type LoginResponse, type PersonalBestAchievement, type Position, type Query, type Rankings, type RequestBody, type RequestContext, type RequestOptions, type RouteRanking, SPORTS_TRACKER_API, type SearchUser, type SummaryExtension, SuuntoClient, type SuuntoClientOptions, type SwimmingHeaderExtension, type TssEntry, type UserProfile, type UserProfileResponse, type UserSearchResponse, type UserSearchResult, UsersResource, type WeatherExtension, type Workout, type WorkoutComment, type WorkoutExtension, type WorkoutReaction, WorkoutsResource, type WorkoutsResponse, generateXtotp, getLatestGear, getOwnWorkouts, getUserByName, getWorkouts, login, searchUsers, secondsUntilRollover, sessionTokenFrom };