@flow-js/garmin-connect 1.6.5 → 1.6.7

package/dist/garmin/GarminConnect.js

@@ -1,15 +1,4 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -84,7 +73,6 @@ var HttpClient_1 = require("../common/HttpClient");
 var utils_1 = require("../utils");
 var UrlClass_1 = require("./UrlClass");
 var types_1 = require("./types");
-var Running_1 = __importDefault(require("./workouts/Running"));
 var DateUtils_1 = require("./common/DateUtils");
 var WeightUtils_1 = require("./common/WeightUtils");
 var HydrationUtils_1 = require("./common/HydrationUtils");
@@ -114,6 +102,12 @@ var GarminConnect = /** @class */ (function () {
         this._userHash = undefined;
         this.listeners = {};
     }
+    /**
+     * Login to Garmin Connect with provided credentials or those set during construction
+     * @param username - Optional username to override the one in credentials
+     * @param password - Optional password to override the one in credentials
+     * @returns The GarminConnect instance for chaining
+     */
     GarminConnect.prototype.login = function (username, password) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -131,6 +125,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Exports OAuth tokens to files in the specified directory
+     * @param dirPath - Directory path where token files will be saved
+     */
     GarminConnect.prototype.exportTokenToFile = function (dirPath) {
         if (!(0, utils_1.checkIsDirectory)(dirPath)) {
             (0, utils_1.createDirectory)(dirPath);
@@ -143,6 +141,11 @@ var GarminConnect = /** @class */ (function () {
             (0, utils_1.writeToFile)(path.join(dirPath, 'oauth2_token.json'), JSON.stringify(this.client.oauth2Token));
         }
     };
+    /**
+     * Loads OAuth tokens from files in the specified directory
+     * @param dirPath - Directory path where token files are stored
+     * @throws Error if directory not found
+     */
     GarminConnect.prototype.loadTokenByFile = function (dirPath) {
         if (!(0, utils_1.checkIsDirectory)(dirPath)) {
             throw new Error('loadTokenByFile: Directory not found: ' + dirPath);
@@ -154,6 +157,11 @@ var GarminConnect = /** @class */ (function () {
         var oauth2 = JSON.parse(oauth2Data);
         this.client.oauth2Token = oauth2;
     };
+    /**
+     * Exports OAuth tokens as an object
+     * @returns Object containing OAuth1 and OAuth2 tokens
+     * @throws Error if tokens are not found
+     */
     GarminConnect.prototype.exportToken = function () {
         if (!this.client.oauth1Token || !this.client.oauth2Token) {
             throw new Error('exportToken: Token not found');
@@ -163,11 +171,19 @@ var GarminConnect = /** @class */ (function () {
             oauth2: this.client.oauth2Token
         };
     };
-    // from db or localstorage etc
+    /**
+     * Loads OAuth tokens from provided token objects (e.g., from DB or localStorage)
+     * @param oauth1 - OAuth1 token object
+     * @param oauth2 - OAuth2 token object
+     */
     GarminConnect.prototype.loadToken = function (oauth1, oauth2) {
         this.client.oauth1Token = oauth1;
         this.client.oauth2Token = oauth2;
     };
+    /**
+     * Retrieves the user's settings from Garmin Connect
+     * @returns User settings data
+     */
     GarminConnect.prototype.getUserSettings = function () {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -175,6 +191,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves the user's social profile from Garmin Connect
+     * @returns User's social profile data
+     */
     GarminConnect.prototype.getUserProfile = function () {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -182,6 +202,14 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves a list of activities matching the specified criteria
+     * @param start - Optional starting index for pagination
+     * @param limit - Optional limit for pagination
+     * @param activityType - Optional activity type filter
+     * @param subActivityType - Optional activity subtype filter
+     * @returns Array of activities matching the criteria
+     */
     GarminConnect.prototype.getActivities = function (start, limit, activityType, subActivityType) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -191,6 +219,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves a specific activity by its ID
+     * @param activity - Object containing activityId
+     * @returns Details of the specified activity
+     * @throws Error if activityId is missing
+     */
     GarminConnect.prototype.getActivity = function (activity) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -200,6 +234,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Counts lifetime activities
+     * @returns Activity statistics including counts by type
+     */
     GarminConnect.prototype.countActivities = function () {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -214,6 +252,23 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Download activity original data file
+     *
+     * Use the activityId to download the original activity data. Usually this is supplied as a .zip file.
+     *
+     * @example
+     * ```js
+     * const [activity] = await GCClient.getActivities(0, 1);
+     * // Directory path is optional and defaults to the current working directory.
+     * // Downloads filename will be supplied by Garmin.
+     * GCClient.downloadOriginalActivityData(activity, './some/path/that/exists');
+     * ```
+     *
+     * @param activity - with activityId
+     * @param dir - directory to save the file
+     * @param type - 'zip' | 'gpx' | 'tcx' | 'kml' (default: 'zip')
+     */
     GarminConnect.prototype.downloadOriginalActivityData = function (activity, dir, type) {
         if (type === void 0) { type = 'zip'; }
         return __awaiter(this, void 0, void 0, function () {
@@ -259,6 +314,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Uploads an activity file
+     * @param file
+     * @param format - 'fit' | 'gpx' | 'tcx'
+     */
     GarminConnect.prototype.uploadActivity = function (file, format) {
         var _a;
         if (format === void 0) { format = 'fit'; }
@@ -286,6 +346,18 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Deletes an activity by activityId
+     * @param activity - with activityId
+     * @returns void
+     *
+     * @example
+     * ```js
+     * const activities = await GCClient.getActivities(0, 1);
+     * const activity = activities[0];
+     * await GCClient.deleteActivity(activity);
+     * ```
+     */
     GarminConnect.prototype.deleteActivity = function (activity) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -301,6 +373,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Gets the list of workouts
+     * @param start
+     * @param limit
+     */
     GarminConnect.prototype.getWorkouts = function (start, limit) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -313,6 +390,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Gets the workout detail by workoutId
+     * @param workout
+     * @returns workout detail - IWorkoutDetail
+     */
     GarminConnect.prototype.getWorkoutDetail = function (workout) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -322,6 +404,33 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Creates a new workout
+     *
+     * Use workoutBuilder to create the workout object. See the example in the examples/example-workout.js for more complex workouts.
+     *
+     * @param workout - workout detail
+     * @returns Response from the workout creation operation
+     *
+     * @example
+     * ```js
+     * const wb = new WorkoutBuilder(
+     *     WorkoutType.Running,
+     *     'Workout running ' + new Date().toISOString()
+     * );
+     *
+     * wb.addStep(
+     *     new Step(
+     *         StepType.Run,
+     *         TimeDuration.fromSeconds(45),
+     *         new NoTarget(),
+     *         'Comment for the step: Run for 45 seconds'
+     *     )
+     * );
+     *
+     * GCClient.createWorkout(wb.build());
+     * ```
+     */
     GarminConnect.prototype.createWorkout = function (workout) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -329,48 +438,17 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
-    GarminConnect.prototype.addWorkout = function (workout) {
-        return __awaiter(this, void 0, void 0, function () {
-            var data, newWorkout;
-            return __generator(this, function (_a) {
-                if (!workout)
-                    throw new Error('Missing workout');
-                if (workout instanceof Running_1.default) {
-                    if (workout.isValid()) {
-                        data = __assign({}, workout.toJson());
-                        if (!data.description) {
-                            data.description = 'Added by garmin-connect for Node.js';
-                        }
-                        return [2 /*return*/, this.client.post(this.url.WORKOUT(), data)];
-                    }
-                }
-                newWorkout = lodash_1.default.omit(workout, [
-                    'workoutId',
-                    'ownerId',
-                    'updatedDate',
-                    'createdDate',
-                    'author'
-                ]);
-                if (!newWorkout.description) {
-                    newWorkout.description = 'Added by garmin-connect for Node.js';
-                }
-                // console.log('addWorkout - newWorkout:', newWorkout)
-                return [2 /*return*/, this.client.post(this.url.WORKOUT(), newWorkout)];
-            });
-        });
-    };
-    GarminConnect.prototype.addRunningWorkout = function (name, meters, description) {
-        return __awaiter(this, void 0, void 0, function () {
-            var running;
-            return __generator(this, function (_a) {
-                running = new Running_1.default();
-                running.name = name;
-                running.distance = meters;
-                running.description = description;
-                return [2 /*return*/, this.addWorkout(running)];
-            });
-        });
-    };
+    /**
+     * Deletes a workout by workoutId
+     * @param workout - with workoutId
+     *
+     * @example
+     * ```js
+     * const workouts = await GCClient.getWorkouts();
+     * const id = workouts[0].workoutId;
+     * GCClient.deleteWorkout({ workoutId: id });
+     * ```
+     */
     GarminConnect.prototype.deleteWorkout = function (workout) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -382,8 +460,18 @@ var GarminConnect = /** @class */ (function () {
     };
     /**
      * Schedule a workout by workoutId to a specific date
+     *
+     * To add a workout to your calendar, provide the workout id and the date to schedule it on.
+     *
      * @param workout - with workoutId
-     * @param scheduleDate - 'YYYY-MM-DD'
+     * @param scheduleDate - 'YYYY-MM-DD' format date string
+     *
+     * @example
+     * ```js
+     * const workouts = await GCClient.getWorkouts();
+     * const id = workouts[0].workoutId;
+     * GCClient.scheduleWorkout({ workoutId: id }, new Date('2025-12-01'));
+     * ```
      */
     GarminConnect.prototype.scheduleWorkout = function (workout, scheduleDate) {
         return __awaiter(this, void 0, void 0, function () {
@@ -392,6 +480,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves step count for a specific date
+     * @param date - The date to get step count for, defaults to current date
+     * @returns Total step count for the specified date
+     * @throws Error if steps data not found for the date
+     */
     GarminConnect.prototype.getSteps = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -415,6 +509,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves sleep data for a specific date
+     * @param date - The date to get sleep data for, defaults to current date
+     * @returns Sleep data for the specified date
+     * @throws Error if sleep data is invalid or empty
+     */
     GarminConnect.prototype.getSleepData = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -439,6 +539,21 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Calculates sleep duration for a specific date
+     *
+     * Retrieves hours and minutes slept for a given date.
+     *
+     * @param date - The date to get sleep duration for, defaults to current date
+     * @returns Object with hours and minutes of sleep
+     * @throws Error if sleep data is missing or invalid
+     *
+     * @example
+     * ```js
+     * const detailedSleep = await GCClient.getSleepDuration(new Date('2020-03-24'));
+     * console.log(`Hours: ${detailedSleep.hours}, Minutes: ${detailedSleep.minutes}`);
+     * ```
+     */
     GarminConnect.prototype.getSleepDuration = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -471,6 +586,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves weight data for a specific date
+     * @param date - The date to get weight data for, defaults to current date
+     * @returns Weight data for the specified date
+     * @throws Error if weight data is invalid or empty
+     */
     GarminConnect.prototype.getDailyWeightData = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -495,6 +616,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves weight data in pounds for a specific date
+     * @param date - The date to get weight data for, defaults to current date
+     * @returns Weight in pounds for the specified date
+     * @throws Error if valid weight data not found for the date
+     */
     GarminConnect.prototype.getDailyWeightInPounds = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -516,6 +643,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves hydration data in fluid ounces for a specific date
+     * @param date - The date to get hydration data for, defaults to current date
+     * @returns Hydration value in fluid ounces for the specified date
+     * @throws Error if hydration data is invalid or empty
+     */
     GarminConnect.prototype.getDailyHydration = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -540,6 +673,14 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Updates weight data for a specific date
+     * @param date - The date for the weight data, defaults to current date
+     * @param lbs - Weight value in pounds
+     * @param timezone - Timezone string for correct timestamp conversion
+     * @returns Response from the weight update operation
+     * @throws Error if update fails
+     */
     GarminConnect.prototype.updateWeight = function (date, lbs, timezone) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -565,6 +706,13 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Updates hydration log with fluid ounces for a specific date
+     * @param date - The date for the hydration data, defaults to current date
+     * @param valueInOz - Hydration value in fluid ounces
+     * @returns Response from the hydration update operation
+     * @throws Error if update fails
+     */
     GarminConnect.prototype.updateHydrationLogOunces = function (date, valueInOz) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -596,6 +744,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves golf summary data
+     * @returns Summary of golf activities
+     * @throws Error if golf summary data is invalid or empty
+     */
     GarminConnect.prototype.getGolfSummary = function () {
         return __awaiter(this, void 0, void 0, function () {
             var golfSummary, error_7;
@@ -618,6 +771,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves golf scorecard for a specific round
+     * @param scorecardId - ID of the scorecard to retrieve
+     * @returns Golf scorecard data
+     * @throws Error if golf scorecard data is invalid or empty
+     */
     GarminConnect.prototype.getGolfScorecard = function (scorecardId) {
         return __awaiter(this, void 0, void 0, function () {
             var golfScorecard, error_8;
@@ -640,6 +799,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves heart rate data for a specific date
+     * @param date - The date to get heart rate data for, defaults to current date
+     * @returns Heart rate data for the specified date
+     * @throws Error if the operation fails
+     */
     GarminConnect.prototype.getHeartRate = function (date) {
         if (date === void 0) { date = new Date(); }
         return __awaiter(this, void 0, void 0, function () {
@@ -715,6 +880,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves all workouts
+     * @returns List of workouts
+     */
     GarminConnect.prototype.workouts = function () {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -722,6 +891,14 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Imports GPX file content
+     *
+     * @example ./examples/example-gpx-file.js
+     * @param fileName - Name of the GPX file
+     * @param fileContent - Content of the GPX file as string
+     * @returns Response from the GPX import operation
+     */
     GarminConnect.prototype.importGpx = function (fileName, fileContent) {
         return __awaiter(this, void 0, void 0, function () {
             var form;
@@ -744,6 +921,17 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Creates a course from GPX data
+     * You can get geoPoints and coursePoints from the imported GPX file response.
+     *
+     * @example ./examples/example-gpx-file.js
+     * @param activityType - Type of activity for the course
+     * @param courseName - Name of the course
+     * @param geoPoints - Array of geographical points making up the course
+     * @param coursePoints - Optional array of course points (waypoints)
+     * @returns Response from the course creation operation
+     */
     GarminConnect.prototype.createCourse = function (activityType, courseName, geoPoints, coursePoints) {
         if (coursePoints === void 0) { coursePoints = []; }
         return __awaiter(this, void 0, void 0, function () {
@@ -755,6 +943,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Lists all courses
+     * @returns List of courses
+     */
     GarminConnect.prototype.listCourses = function () {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -762,6 +954,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Exports a course as GPX file content
+     * @param courseId - ID of the course to export
+     * @returns GPX file content as string
+     */
     GarminConnect.prototype.exportCourseAsGpx = function (courseId) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -771,6 +968,10 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves calendar events for a specific year.
+     * @param year {number} - The year for which to retrieve calendar events.
+     */
     GarminConnect.prototype.getYearCalendarEvents = function (year) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -778,6 +979,11 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves calendar events for a specific month and year.
+     * @param year {number} - The year for which to retrieve calendar events.
+     * @param month {number} - The month (0-11) for which to retrieve calendar events.
+     */
     GarminConnect.prototype.getMonthCalendarEvents = function (year, month) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -785,6 +991,13 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Retrieves calendar events for a specific week containing the given date.
+     * @param year {number} - The year of the date.
+     * @param month {number} - The month (0-11) of the date.
+     * @param day {number} - The day of the first day of the week.
+     * @param firstDayOfWeek {number} - Optional first day of the week, default is 1
+     */
     GarminConnect.prototype.getWeekCalendarEvents = function (year, month, day, firstDayOfWeek) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -792,6 +1005,36 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Renames an activity with the given activityId to the newName.
+     * @param activityId
+     * @param newName
+     */
+    GarminConnect.prototype.renameActivity = function (activityId, newName) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!activityId)
+                            throw new Error('Missing activityId');
+                        if (!newName)
+                            throw new Error('Missing newName');
+                        return [4 /*yield*/, this.client.put(this.url.ACTIVITY_BY_ID(activityId), {
+                                activityName: newName
+                            })];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Performs a GET request to the specified URL
+     * @param url - URL to send the request to
+     * @param data - Optional query parameters or request configuration
+     * @returns Response data of type T
+     */
     GarminConnect.prototype.get = function (url, data) {
         return __awaiter(this, void 0, void 0, function () {
             var response;
@@ -805,6 +1048,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Performs a POST request to the specified URL
+     * @param url - URL to send the request to
+     * @param data - Data to send in the request body
+     * @returns Response data of type T
+     */
     GarminConnect.prototype.post = function (url, data) {
         return __awaiter(this, void 0, void 0, function () {
             var response;
@@ -818,6 +1067,12 @@ var GarminConnect = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Performs a PUT request to the specified URL
+     * @param url - URL to send the request to
+     * @param data - Data to send in the request body
+     * @returns Response data of type T
+     */
     GarminConnect.prototype.put = function (url, data) {
         return __awaiter(this, void 0, void 0, function () {
             var response;