suunto-api-wrapper 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# suunto-api-wrapper
+
+A small, typed TypeScript client for the **Suunto app API** (which is served by
+the Sports Tracker backend at `api.sports-tracker.com`).
+
+It handles the annoying parts and exposes the endpoints as
+typed, resource‑grouped methods:
+
+```ts
+const suunto = await SuuntoClient.login({ email, password });
+
+const workouts = await suunto.workouts.own({ limit: 10 });
+const profile  = await suunto.users.byName("someuser");
+const gear     = await suunto.gear.latest("someuser");
+```
+
+No runtime dependencies — it's built on Node's native `fetch`.
+
+---
+
+## ⚠️ Disclaimer
+
+This is an **unofficial** library. It is **not affiliated with, endorsed by, or
+supported by Suunto or Sports Tracker** in any way.
+
+- It talks to an **undocumented API** that can change or break without
+  notice.
+- Use it **only with your own account and your own data**, at your own risk as it may break Suunto or Sports Tracker TOS. Be
+  respectful of the service: don't hammer the API or use it for scraping/abuse.
+
+If Suunto or Sports Tracker request it, this project will comply.
+
+---
+
+## Installation
+
+This package isn't published to npm yet. Install it from source:
+
+```bash
+git clone <this-repo> suunto-api-wrapper
+cd suunto-api-wrapper
+npm install
+npm run build      # emits ESM + CJS + .d.ts into dist/
+```
+
+Then consume it from another project (e.g. via a local path or `npm link`):
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "suunto-api-wrapper": "file:../suunto-api-wrapper"
+  }
+}
+```
+
+The package ships both **ESM** and **CommonJS** builds with full type
+declarations, so `import` and `require` both work:
+
+```ts
+import { SuuntoClient } from "suunto-api-wrapper";       // ESM
+const { SuuntoClient } = require("suunto-api-wrapper");  // CJS
+```
+
+---
+
+## Usage
+
+### Authenticating
+
+`SuuntoClient.login` performs the email/password login, stores the returned
+session key, and returns a ready‑to‑use client. Every request it makes is authed.
+
+```ts
+import { SuuntoClient } from "suunto-api-wrapper";
+
+const suunto = await SuuntoClient.login({
+  email: "you@example.com",
+  password: "your-password",
+});
+
+console.log(suunto.sessionKey); // the active session key
+```
+
+### Resource namespaces
+
+The client groups endpoints by resource. Each call returns the parsed JSON
+payload, typed to the real API response shape (an envelope of
+`{ error, payload, metadata }`).
+
+| Namespace          | Method                         | Endpoint                                  |
+| ------------------ | ------------------------------ | ----------------------------------------- |
+| `suunto.workouts`  | `.own(params?)`                | your own workouts                         |
+|                    | `.public(username, params?)`   | a user's public workouts                  |
+| `suunto.users`     | `.byName(username)`            | a user's public profile                   |
+|                    | `.search(terms)`               | search for users                          |
+| `suunto.gear`      | `.latest(username, params?)`   | a user's latest gear                      |
+
+```ts
+// Workouts
+const own         = await suunto.workouts.own({ limit: 20, offset: 0, since: 0 });
+const publicItems = await suunto.workouts.public("someuser", { limit: 40 });
+
+// Users
+const profile = await suunto.users.byName("someuser");
+const matches = await suunto.users.search("john");
+
+// Gear
+const gear = await suunto.gear.latest("someuser", { allTypes: true });
+```
+
+The response payloads are fully typed. For example, workout `extensions` are a
+discriminated union you can narrow on:
+
+```ts
+for (const w of own.payload) {
+  for (const ext of w.extensions) {
+    if (ext.type === "WeatherExtension") {
+      console.log(ext.temperature, ext.humidity); // typed!
+    }
+  }
+}
+```
+
+### Unauthenticated access
+
+Some endpoints (like fetching a public profile) don't require login. Use the
+`unauthenticated()` factory to create a client that sends **no** credentials:
+
+```ts
+const guest = SuuntoClient.unauthenticated();
+const profile = await guest.users.byName("someuser");
+```
+
+### Escape hatch: the raw HTTP client
+
+For endpoints not yet wrapped, reach the underlying HTTP client directly. It
+already carries the auth headers, retries, and timeouts:
+
+```ts
+const res = await suunto.http.get("/apiserver/v1/some/other/endpoint", {
+  query: { foo: "bar" },
+});
+console.log(res.status, res.data);
+```
+
+---
+
+## Development
+
+```bash
+npm run build       # bundle to dist/ (ESM + CJS + types) with tsup
+npm run dev         # rebuild on change (tsup --watch)
+npm run typecheck   # tsc --noEmit
+npm test            # run the vitest suite once
+npm run test:watch  # vitest in watch mode
+```
+
+---
+
+## License
+
+ISC.

package/dist/index.d.mts

@@ -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 };