@flow-js/garmin-connect 1.6.6 → 1.6.7

package/dist/garmin/GarminConnect.d.ts

@@ -1,6 +1,5 @@
 import { HttpClient } from '../common/HttpClient';
 import { ExportFileTypeValue, GarminDomain, GCGearId, ICountActivities, IGarminTokens, IOauth1Token, IOauth2Token, ISocialProfile, IUserSettings, IWorkout, IWorkoutDetail, ListCoursesResponse, UploadFileTypeTypeValue } from './types';
-import Running from './workouts/Running';
 import { SleepData } from './types/sleep';
 import { ActivitySubType, ActivityType, GCActivityId, IActivity } from './types/activity';
 import { GearData } from './types/gear';
@@ -27,56 +26,274 @@ export default class GarminConnect {
     private listeners;
     private url;
     constructor(credentials?: GCCredentials | undefined, domain?: GarminDomain);
+    /**
+     * 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
+     */
     login(username?: string, password?: string): Promise<GarminConnect>;
+    /**
+     * Exports OAuth tokens to files in the specified directory
+     * @param dirPath - Directory path where token files will be saved
+     */
     exportTokenToFile(dirPath: string): void;
+    /**
+     * Loads OAuth tokens from files in the specified directory
+     * @param dirPath - Directory path where token files are stored
+     * @throws Error if directory not found
+     */
     loadTokenByFile(dirPath: string): void;
+    /**
+     * Exports OAuth tokens as an object
+     * @returns Object containing OAuth1 and OAuth2 tokens
+     * @throws Error if tokens are not found
+     */
     exportToken(): IGarminTokens;
+    /**
+     * Loads OAuth tokens from provided token objects (e.g., from DB or localStorage)
+     * @param oauth1 - OAuth1 token object
+     * @param oauth2 - OAuth2 token object
+     */
     loadToken(oauth1: IOauth1Token, oauth2: IOauth2Token): void;
+    /**
+     * Retrieves the user's settings from Garmin Connect
+     * @returns User settings data
+     */
     getUserSettings(): Promise<IUserSettings>;
+    /**
+     * Retrieves the user's social profile from Garmin Connect
+     * @returns User's social profile data
+     */
     getUserProfile(): Promise<ISocialProfile>;
+    /**
+     * 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
+     */
     getActivities(start?: number, limit?: number, activityType?: ActivityType, subActivityType?: ActivitySubType): Promise<IActivity[]>;
+    /**
+     * Retrieves a specific activity by its ID
+     * @param activity - Object containing activityId
+     * @returns Details of the specified activity
+     * @throws Error if activityId is missing
+     */
     getActivity(activity: {
         activityId: GCActivityId;
     }): Promise<IActivity>;
+    /**
+     * Counts lifetime activities
+     * @returns Activity statistics including counts by type
+     */
     countActivities(): Promise<ICountActivities>;
+    /**
+     * 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')
+     */
     downloadOriginalActivityData(activity: {
         activityId: GCActivityId;
     }, dir: string, type?: ExportFileTypeValue): Promise<void>;
+    /**
+     * Uploads an activity file
+     * @param file
+     * @param format - 'fit' | 'gpx' | 'tcx'
+     */
     uploadActivity(file: string, format?: UploadFileTypeTypeValue): Promise<unknown>;
+    /**
+     * 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);
+     * ```
+     */
     deleteActivity(activity: {
         activityId: GCActivityId;
     }): Promise<void>;
+    /**
+     * Gets the list of workouts
+     * @param start
+     * @param limit
+     */
     getWorkouts(start: number, limit: number): Promise<IWorkout[]>;
+    /**
+     * Gets the workout detail by workoutId
+     * @param workout
+     * @returns workout detail - IWorkoutDetail
+     */
     getWorkoutDetail(workout: {
         workoutId: string;
     }): Promise<IWorkoutDetail>;
+    /**
+     * 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());
+     * ```
+     */
     createWorkout(workout: IWorkoutDetail): Promise<Workout>;
-    addWorkout(workout: IWorkoutDetail | Running): Promise<IWorkoutDetail>;
-    addRunningWorkout(name: string, meters: number, description: string): Promise<IWorkoutDetail>;
+    /**
+     * 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 });
+     * ```
+     */
     deleteWorkout(workout: {
         workoutId: string;
     }): Promise<unknown>;
     /**
      * 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'));
+     * ```
      */
     scheduleWorkout(workout: {
         workoutId: string;
     }, scheduleDate: string): Promise<unknown>;
+    /**
+     * 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
+     */
     getSteps(date?: Date): Promise<number>;
+    /**
+     * 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
+     */
     getSleepData(date?: Date): Promise<SleepData>;
+    /**
+     * 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}`);
+     * ```
+     */
     getSleepDuration(date?: Date): Promise<{
         hours: number;
         minutes: number;
     }>;
+    /**
+     * 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
+     */
     getDailyWeightData(date?: Date): Promise<WeightData>;
+    /**
+     * 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
+     */
     getDailyWeightInPounds(date?: Date): Promise<number>;
+    /**
+     * 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
+     */
     getDailyHydration(date?: Date): Promise<number>;
+    /**
+     * 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
+     */
     updateWeight(date: Date | undefined, lbs: number, timezone: string): Promise<UpdateWeight>;
+    /**
+     * 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
+     */
     updateHydrationLogOunces(date: Date | undefined, valueInOz: number): Promise<WaterIntake>;
+    /**
+     * Retrieves golf summary data
+     * @returns Summary of golf activities
+     * @throws Error if golf summary data is invalid or empty
+     */
     getGolfSummary(): Promise<GolfSummary>;
+    /**
+     * 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
+     */
     getGolfScorecard(scorecardId: number): Promise<GolfScorecard>;
+    /**
+     * 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
+     */
     getHeartRate(date?: Date): Promise<HeartRate>;
     /**
      * Returns the gear data for the user.
@@ -102,10 +319,42 @@ export default class GarminConnect {
      * @return GearData - the unlinked gear item data
      */
     unlinkGearFromActivity(activityId: GCActivityId, gearId: GCGearId): Promise<GearData>;
+    /**
+     * Retrieves all workouts
+     * @returns List of workouts
+     */
     workouts(): Promise<Workout[]>;
+    /**
+     * 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
+     */
     importGpx(fileName: string, fileContent: string): Promise<ImportedGpxResponse>;
+    /**
+     * 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
+     */
     createCourse(activityType: GpxActivityType, courseName: string, geoPoints: GeoPoint[], coursePoints?: CoursePoint[]): Promise<unknown>;
+    /**
+     * Lists all courses
+     * @returns List of courses
+     */
     listCourses(): Promise<ListCoursesResponse>;
+    /**
+     * Exports a course as GPX file content
+     * @param courseId - ID of the course to export
+     * @returns GPX file content as string
+     */
     exportCourseAsGpx(courseId: number): Promise<string>;
     /**
      * Retrieves calendar events for a specific year.
@@ -132,7 +381,25 @@ export default class GarminConnect {
      * @param newName
      */
     renameActivity(activityId: GCActivityId, newName: string): Promise<void>;
+    /**
+     * 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
+     */
     get<T>(url: string, data?: any): Promise<T>;
+    /**
+     * 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
+     */
     post<T>(url: string, data: any): Promise<T>;
+    /**
+     * 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
+     */
     put<T>(url: string, data: any): Promise<T>;
 }