suunto-api-wrapper 1.1.2 → 1.2.2

package/README.md

@@ -1,9 +1,16 @@
 # suunto-api-wrapper
 
 [![npm version](https://img.shields.io/npm/v/suunto-api-wrapper.svg)](https://www.npmjs.com/package/suunto-api-wrapper)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Marius-Ar_suunto-api-wrapper&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Marius-Ar_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`).
+A small, typed TypeScript client for the **Suunto mobile app API** the same
+backend the Suunto phone app talks to (served by Sports Tracker at
+`api.sports-tracker.com`).
+
+**No Suunto apizone / developer account required.** This library does **not**
+use Suunto's official partner API at `apizone.suunto.com`, so there are no
+OAuth client IDs, no app registration, and no developer approval to deal with.
+You authenticate with the same email + password you use in the Suunto app.
 
 It handles the annoying parts and exposes the endpoints as
 typed, resource‑grouped methods:
@@ -82,6 +89,9 @@ payload, typed to the real API response shape (an envelope of
 | ------------------ | ------------------------------ | ----------------------------------------- |
 | `suunto.workouts`  | `.own(params?)`                | your own workouts                         |
 |                    | `.public(username, params?)`   | a user's public workouts                  |
+|                    | `.byKey(username, key, params?)` | a single workout (public, or your own when authed) |
+|                    | `.stats(username)`             | aggregated workout stats per activity     |
+|                    | `.within(box)`                 | public workouts inside a lat/lng bounding box |
 | `suunto.users`     | `.byName(username)`            | a user's public profile                   |
 |                    | `.search(terms)`               | search for users                          |
 | `suunto.gear`      | `.latest(username, params?)`   | a user's latest gear                      |
@@ -90,6 +100,11 @@ payload, typed to the real API response shape (an envelope of
 // Workouts
 const own         = await suunto.workouts.own({ limit: 20, offset: 0, since: 0 });
 const publicItems = await suunto.workouts.public("someuser", { limit: 40 });
+const single      = await suunto.workouts.byKey("someuser", "workoutKey123");
+const stats       = await suunto.workouts.stats("someuser");
+const nearby      = await suunto.workouts.within({
+  lowerLat: 45.70, lowerLng: 4.75, upperLat: 45.85, upperLng: 4.95, limit: 50,
+});
 
 // Users
 const profile = await suunto.users.byName("someuser");
@@ -120,6 +135,7 @@ Some endpoints (like fetching a public profile) don't require login. Use the
 ```ts
 const guest = SuuntoClient.unauthenticated();
 const profile = await guest.users.byName("someuser");
+const stats   = await guest.workouts.stats("someuser");
 ```
 
 ### Escape hatch: the raw HTTP client

package/dist/index.d.mts

@@ -86,6 +86,68 @@ declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15
 declare function login(options: LoginOptions): Promise<LoginResponse>;
 declare function sessionTokenFrom(response: LoginResponse): string | undefined;
 
+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;
+    /** Absent on some legacy accounts. */
+    realName?: string;
+    /** Free-form profile bio. */
+    description?: 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;
+    coverImageKey?: string;
+    coverImageUrl?: 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;
+    };
+}
+
 interface GetWorkoutsParams {
     limit?: number;
     sortonst?: boolean;
@@ -95,6 +157,166 @@ interface GetOwnWorkoutsParams {
     offset?: number;
     limit?: number;
 }
+/** Bounding-box query for {@link getWorkoutsWithin}. All coords in decimal degrees. */
+interface GetWorkoutsWithinParams {
+    /** South latitude of the bounding box. */
+    lowerLat: number;
+    /** West longitude of the bounding box. */
+    lowerLng: number;
+    /** North latitude of the bounding box. */
+    upperLat: number;
+    /** East longitude of the bounding box. */
+    upperLng: number;
+    /** Max results. Defaults to 50. */
+    limit?: number;
+}
+/** Suunto activity type IDs returned by the API as `activityId` / `_id`. */
+declare enum SuuntoActivityType {
+    WALKING = 0,
+    RUNNING = 1,
+    CYCLING = 2,
+    CROSS_COUNTRY_SKIING = 3,
+    OTHER_1 = 4,
+    OTHER_2 = 5,
+    OTHER_3 = 6,
+    OTHER_4 = 7,
+    OTHER_5 = 8,
+    OTHER_6 = 9,
+    MOUNTAIN_BIKING = 10,
+    HIKING = 11,
+    ROLLER_SKATING = 12,
+    DOWNHILL_SKIING = 13,
+    PADDLING = 14,
+    ROWING = 15,
+    GOLF = 16,
+    INDOOR = 17,
+    PARKOUR = 18,
+    BALLGAMES = 19,
+    OUTDOOR_GYM = 20,
+    SWIMMING = 21,
+    TRAIL_RUNNING = 22,
+    GYM = 23,
+    NORDIC_WALKING = 24,
+    HORSEBACK_RIDING = 25,
+    MOTOR_SPORTS = 26,
+    SKATEBOARDING = 27,
+    WATER_SPORTS = 28,
+    CLIMBING = 29,
+    SNOWBOARDING = 30,
+    SKI_TOURING = 31,
+    FITNESS_CLASS = 32,
+    SOCCER = 33,
+    TENNIS = 34,
+    BASKETBALL = 35,
+    BADMINTON = 36,
+    BASEBALL = 37,
+    VOLLEYBALL = 38,
+    AMERICAN_FOOTBALL = 39,
+    TABLE_TENNIS = 40,
+    RACQUETBALL = 41,
+    SQUASH = 42,
+    FLOORBALL = 43,
+    HANDBALL = 44,
+    SOFTBALL = 45,
+    BOWLING = 46,
+    CRICKET = 47,
+    RUGBY = 48,
+    ICE_SKATING = 49,
+    ICE_HOCKEY = 50,
+    YOGA = 51,
+    INDOOR_CYCLING = 52,
+    TREADMILL = 53,
+    CROSSFIT = 54,
+    CROSSTRAINER = 55,
+    ROLLER_SKIING = 56,
+    INDOOR_ROWING = 57,
+    STRETCHING = 58,
+    TRACK_AND_FIELD = 59,
+    ORIENTEERING = 60,
+    SUP = 61,
+    COMBAT_SPORTS = 62,
+    KETTLEBELL = 63,
+    DANCING = 64,
+    SNOWSHOEING = 65,
+    FRISBEE_GOLF = 66,
+    FUTSAL = 67,
+    MULTISPORT = 68,
+    AEROBICS = 69,
+    TREKKING = 70,
+    SAILING = 71,
+    KAYAKING = 72,
+    CIRCUIT_TRAINING = 73,
+    TRIATHLON = 74,
+    PADEL = 75,
+    CHEERLEADING = 76,
+    BOXING = 77,
+    SCUBADIVING = 78,
+    FREEDIVING = 79,
+    ADVENTURE_RACING = 80,
+    GYMNASTICS = 81,
+    CANOEING = 82,
+    MOUNTAINEERING = 83,
+    TELEMARKSKIING = 84,
+    OPENWATER_SWIMMING = 85,
+    WINDSURFING = 86,
+    KITESURFING_KITING = 87,
+    PARAGLIDING = 88,
+    SNORKELING = 90,
+    SURFING = 91,
+    SWIMRUN = 92,
+    DUATHLON = 93,
+    AQUATHLON = 94,
+    OBSTACLE_RACING = 95,
+    FISHING = 96,
+    HUNTING = 97,
+    GRAVEL_CYCLING = 99,
+    MERMAIDING = 100,
+    SPEARFISHING = 101,
+    JUMP_ROPE = 102,
+    TRACK_RUNNING = 103,
+    CALISTHENICS = 104,
+    E_BIKING = 105,
+    E_MTB = 106,
+    BACKCOUNTRY_SKIING = 107,
+    WHEELCHAIR = 108,
+    HAND_CYCLING = 109,
+    SPLIT_BOARDING = 110,
+    BIATHLON = 111,
+    MEDITATION = 112,
+    FIELD_HOCKEY = 113,
+    CYCLOCROSS = 114,
+    VERTICAL_RUN = 115,
+    SKI_MOUNTAINEERING = 116,
+    SKATE_SKIING = 117,
+    CLASSIC_SKIING = 118,
+    CHORES = 119,
+    PILATES = 120,
+    NEW_YOGA = 121
+}
+/** Valid values for the `extensions` query param on the single-workout endpoint. */
+declare enum WorkoutExtensionName {
+    Dive = "DiveExtension",
+    JumpRope = "JumpRopeExtension",
+    Summary = "SummaryExtension",
+    Swimming = "SwimmingExtension",
+    Weather = "WeatherExtension",
+    Workout = "WorkoutExtension",
+    CompetitionHeader = "CompetitionHeaderExtension"
+}
+/** Valid values for the `additionalData` query param on the single-workout endpoint. */
+declare enum WorkoutAdditionalData {
+    Achievements = "achievements",
+    Photos = "photos",
+    Videos = "videos",
+    Comments = "comments",
+    UserReacted = "user_reacted"
+}
+interface GetWorkoutParams {
+    /** Extensions to include in the response. Defaults to `[Summary, CompetitionHeader]`. */
+    extensions?: WorkoutExtensionName[];
+    /** Extra data blocks to include. Defaults to all five values. */
+    additionalData?: WorkoutAdditionalData[];
+}
 /** GPS coordinate: x = longitude, y = latitude. */
 interface Position {
     x: number;
@@ -288,8 +510,7 @@ type WorkoutExtension = FitnessExtension | IntensityExtension | SummaryExtension
 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;
+    activityId: SuuntoActivityType;
     key: string;
     startTime: number;
     stopTime: number;
@@ -317,7 +538,8 @@ interface Workout {
     tss: TssEntry;
     tssList: TssEntry[];
     suuntoTags: string[];
-    clientCalculatedAchievements: ClientCalculatedAchievements;
+    /** Absent on some workouts (e.g. when the user has no achievements yet). */
+    clientCalculatedAchievements?: ClientCalculatedAchievements;
     workoutKey: string;
     visibilityFacebook: boolean;
     visibilityTwitter: boolean;
@@ -346,6 +568,16 @@ interface Workout {
     comments?: WorkoutComment[];
     /** Only present when reactionCount > 0. */
     reactions?: WorkoutReaction[];
+    /** Owner's display name. Returned on feed-style endpoints (e.g. `within`). */
+    fullname?: string;
+    /** Owner's profile picture URL. Returned on feed-style endpoints. */
+    userPhoto?: string;
+    /** Owner's cover photo URL. Returned on feed-style endpoints. */
+    coverPhoto?: string;
+    /** Free-text achievement labels (e.g. "Fastest time on this route"). */
+    achievements?: string[];
+    /** Average power, watts. Mirrors `SummaryExtension.avgPower` on feed responses. */
+    avgPower?: number;
 }
 interface WorkoutsResponse {
     error: string | null;
@@ -355,76 +587,99 @@ interface WorkoutsResponse {
         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 WorkoutResponse {
+    error: string | null;
+    payload: Workout;
+    metadata: Record<string, unknown>;
 }
-
-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;
+/** Single item from the {@link getWorkoutsWithin} feed: owner + workout. */
+interface WorkoutsWithinItem {
+    user: SearchUser;
+    workout: Workout;
 }
-interface UserProfileResponse {
+interface WorkoutsWithinResponse {
     error: string | null;
-    payload: UserProfile;
+    payload: WorkoutsWithinItem[];
     metadata: {
-        ts: string;
+        workoutcount: 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;
+/** Aggregated totals for a single activity type. */
+interface WorkoutStatsEntry {
+    /** Suunto activity type ID this entry aggregates. */
+    _id: SuuntoActivityType;
+    /** Metres. */
+    totalDistance: number;
+    /** Seconds. */
+    totalTime: number;
+    /** Kilocalories. */
+    energyConsumption: number;
+    /** Number of workouts of this activity. */
+    numberOfWorkouts: number;
+    /** Metres. Only meaningful for dives. */
+    maxDepth: number;
+}
+interface WorkoutStats {
+    /** Sum of distances across all activities, in metres. */
+    totalDistanceSum: number;
+    /** Sum of times across all activities, in seconds. */
+    totalTimeSum: number;
+    /** Sum of energy consumption across all activities, in kilocalories. */
+    totalEnergyConsumptionSum: number;
+    /** Total workout count across all activities. */
+    totalNumberOfWorkoutsSum: number;
+    /** Number of distinct days that have at least one workout. */
+    totalDays: number;
+    /**
+     * Per-activity aggregates, restricted to a curated set of activity types
+     * (the ones the official UI surfaces as headline cards).
+     */
+    allStats: WorkoutStatsEntry[];
+    /** Per-activity aggregates covering every activity type the user has recorded. */
+    allActualStats: WorkoutStatsEntry[];
 }
-interface UserSearchResponse {
+interface WorkoutStatsResponse {
     error: string | null;
-    payload: UserSearchResult[];
+    payload: WorkoutStats;
     metadata: {
         ts: string;
     };
 }
 
+declare function getWorkouts(client: HttpClient, username: string, params?: GetWorkoutsParams): Promise<WorkoutsResponse>;
+declare function getOwnWorkouts(client: HttpClient, params?: GetOwnWorkoutsParams): Promise<WorkoutsResponse>;
+/**
+ * Public workouts whose center position falls inside the given geographic
+ * bounding box. Used by the "explore nearby" map view. Unauthenticated.
+ */
+declare function getWorkoutsWithin(client: HttpClient, params: GetWorkoutsWithinParams): Promise<WorkoutsWithinResponse>;
+/**
+ * Aggregated workout stats per activity for a user. Unauthenticated — no
+ * session required.
+ */
+declare function getWorkoutStats(client: HttpClient, username: string): Promise<WorkoutStatsResponse>;
+/** 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>;
+    /**
+     * A single workout by username and workout key. Works for any public workout
+     * and, when the client is authenticated as the owner, for private ones too.
+     */
+    byKey(username: string, workoutKey: string, params?: GetWorkoutParams): Promise<WorkoutResponse>;
+    /**
+     * Aggregated workout stats per activity for the given user. Works
+     * unauthenticated.
+     */
+    stats(username: string): Promise<WorkoutStatsResponse>;
+    /** Public workouts whose center falls inside a geographic bounding box. */
+    within(params: GetWorkoutsWithinParams): Promise<WorkoutsWithinResponse>;
+}
+
 /**
  * Fetch a user's public profile by username. Unauthenticated — no session
  * required.
@@ -508,4 +763,4 @@ declare class SuuntoClient {
     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 };
+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 GetWorkoutsWithinParams, 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, SuuntoActivityType, 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, type WorkoutStats, type WorkoutStatsEntry, type WorkoutStatsResponse, WorkoutsResource, type WorkoutsResponse, type WorkoutsWithinItem, type WorkoutsWithinResponse, generateXtotp, getLatestGear, getOwnWorkouts, getUserByName, getWorkoutStats, getWorkouts, getWorkoutsWithin, login, searchUsers, secondsUntilRollover, sessionTokenFrom };