@dlwiest/ts-tonal-client 0.5.0 → 0.6.0

package/dist/index.esm.js

@@ -73,43 +73,54 @@ class AuthManager {
         this.tokenExpiresAt = this.getTokenExpiresAt(tokenData.id_token, expiresInDeadline);
         return this.idToken;
     }
+    // `expiresInDeadline` may be NaN: OAuthTokenResponse declares `expires_in` as required,
+    // but that same interface declared `refresh_token` required until Auth0 was observed
+    // omitting it, so the field is not trustworthy. A NaN deadline must never reach
+    // `tokenExpiresAt` -- `isTokenValid()` compares against it and would return false
+    // forever, refreshing on every single call.
     getTokenExpiresAt(idToken, expiresInDeadline) {
+        const expiresInUsable = Number.isFinite(expiresInDeadline);
+        // Neither source usable: a short finite window beats NaN, which would spin the
+        // refresh grant on every request and invite Auth0 rate limiting.
+        const noInfoFallback = expiresInUsable ? expiresInDeadline : Date.now() + 10 * 60 * 1000;
         try {
             if (!idToken) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const segments = idToken.split('.');
             if (segments.length !== 3) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const payloadSegment = segments[1];
             if (!/^[A-Za-z0-9_-]+$/.test(payloadSegment)) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const payloadBuffer = Buffer.from(payloadSegment, 'base64url');
             if (payloadBuffer.toString('base64url') !== payloadSegment) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const payload = JSON.parse(payloadBuffer.toString('utf8'));
             if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const exp = 'exp' in payload ? payload.exp : undefined;
             if (typeof exp !== 'number' || !Number.isFinite(exp) || exp <= 0) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             const expDeadline = exp * 1000;
             // ID tokens are hour-lived; ten years rejects nonsensical dates without affecting real tokens.
             const latestReasonableExpiry = Date.now() + 10 * 365 * 24 * 60 * 60 * 1000;
             if (!Number.isFinite(expDeadline) || expDeadline > latestReasonableExpiry) {
-                return expiresInDeadline;
+                return noInfoFallback;
             }
             // Auth0's expires_in (measured at 24h) describes the access token, while
             // we send the ID token (measured at 10h), so its own exp must cap the deadline.
-            return Math.min(expDeadline, expiresInDeadline);
+            // When expires_in is unusable the exp claim stands alone rather than being
+            // discarded by Math.min(valid, NaN) === NaN.
+            return expiresInUsable ? Math.min(expDeadline, expiresInDeadline) : expDeadline;
         }
         catch {
-            return expiresInDeadline;
+            return noInfoFallback;
         }
     }
     invalidateToken() {
@@ -607,6 +618,29 @@ class UserService {
     async getActivitySummaries(userId) {
         return this.httpClient.request(`/users/${userId}/activity-summaries`);
     }
+    async getWorkoutActivities(userId, offset = 0, limit = 100) {
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new TonalClientError('Offset must be a non-negative integer');
+        }
+        if (!Number.isInteger(limit) || limit <= 0 || limit > 100) {
+            throw new TonalClientError('Limit must be an integer between 1 and 100');
+        }
+        // Verified live: this endpoint uses pg-* headers, unlike /user-workouts.
+        return this.httpClient.request(`/users/${userId}/workout-activities`, {
+            method: 'GET',
+            headers: {
+                'pg-offset': offset.toString(),
+                'pg-limit': limit.toString(),
+            },
+        });
+    }
+    async getFormattedWorkoutSummary(userId, activityId) {
+        const canonicalActivityId = activityId.trim();
+        if (!canonicalActivityId) {
+            throw new TonalClientError('Workout activity ID is required');
+        }
+        return this.httpClient.request(`/users/${userId}/workout-summaries/${encodeURIComponent(canonicalActivityId)}`);
+    }
     async getUserStatistics(userId) {
         return this.httpClient.request(`/users/${userId}/statistics`);
     }
@@ -636,6 +670,271 @@ class UserService {
     }
 }
 
+function parseDate(value, fieldName, endOfDay = false) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const calendarDateMatch = typeof value === 'string'
+        ? /^(\d{4})-(\d{2})-(\d{2})(?:$|T)/.exec(value)
+        : null;
+    if (calendarDateMatch !== null) {
+        const year = Number(calendarDateMatch[1]);
+        const month = Number(calendarDateMatch[2]);
+        const day = Number(calendarDateMatch[3]);
+        const roundTrip = new Date(0);
+        roundTrip.setUTCHours(0, 0, 0, 0);
+        roundTrip.setUTCFullYear(year, month - 1, day);
+        if (roundTrip.getUTCFullYear() !== year ||
+            roundTrip.getUTCMonth() !== month - 1 ||
+            roundTrip.getUTCDate() !== day) {
+            throw new TonalClientError(`${fieldName} must be a valid ISO-8601 date or timestamp`);
+        }
+    }
+    const timestamp = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (Number.isNaN(timestamp)) {
+        throw new TonalClientError(`${fieldName} must be a valid ISO-8601 date or timestamp`);
+    }
+    const isDateOnly = typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value);
+    return {
+        timestamp: endOfDay && isDateOnly ? timestamp + 24 * 60 * 60 * 1000 - 1 : timestamp,
+        localDate: isDateOnly ? value : undefined,
+    };
+}
+function getActivityLocalDate(activity) {
+    const localTimestampDate = /^(\d{4}-\d{2}-\d{2})T/.exec(activity.localTimestamp)?.[1];
+    try {
+        const parts = new Intl.DateTimeFormat('en-US', {
+            timeZone: activity.timeZone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        }).formatToParts(new Date(activity.timestamp));
+        const partValues = Object.fromEntries(parts.map(part => [part.type, part.value]));
+        if (partValues.year && partValues.month && partValues.day) {
+            return `${partValues.year}-${partValues.month}-${partValues.day}`;
+        }
+    }
+    catch {
+        // Fall back to Tonal's local timestamp when a historical time zone is unavailable.
+    }
+    return localTimestampDate;
+}
+function mapSetActivity(set, movement) {
+    const totalVolume = set.totalOnMachineVolume ?? set.volume;
+    const estimatedAverageResistance = set.repCount !== undefined &&
+        set.repCount > 0 &&
+        totalVolume !== undefined &&
+        totalVolume > 0
+        ? totalVolume / set.repCount
+        : undefined;
+    const estimatedOneRepMax = set.oneRepMax !== undefined &&
+        set.avgWeight !== undefined &&
+        set.avgWeight > 0 &&
+        estimatedAverageResistance !== undefined
+        ? set.oneRepMax * (estimatedAverageResistance / set.avgWeight)
+        : undefined;
+    const derivedEstimates = estimatedAverageResistance !== undefined || estimatedOneRepMax !== undefined
+        ? {
+            averageResistancePounds: estimatedAverageResistance,
+            oneRepMaxPounds: estimatedOneRepMax,
+        }
+        : undefined;
+    return {
+        setActivityId: set.id,
+        movementId: set.movementId,
+        movementName: movement?.name,
+        muscleGroups: movement?.muscleGroups,
+        accessory: movement?.onMachineInfo?.accessory,
+        bilateral: movement?.isBilateral,
+        twoSided: movement?.isTwoSided,
+        beginTime: set.beginTime,
+        endTime: set.endTime,
+        durationSeconds: set.duration,
+        prescribedReps: set.prescribedReps ?? undefined,
+        prescribedDurationSeconds: set.prescribedDuration ?? undefined,
+        completedReps: set.repCount,
+        repsInReserve: set.repsInReserve ?? undefined,
+        repetition: set.repetition ?? undefined,
+        repetitionTotal: set.repetitionTotal ?? undefined,
+        sideNumber: set.sideNumber ?? undefined,
+        movementSide: set.movementSide,
+        averageResistancePerCablePounds: set.avgWeight,
+        baseResistancePerCablePounds: set.baseWeight ?? undefined,
+        minimumResistancePerCablePounds: set.minWeight,
+        maximumResistancePerCablePounds: set.maxWeight,
+        totalVolumePounds: totalVolume,
+        estimatedOneRepMaxPerCablePounds: set.oneRepMax,
+        derivedEstimates,
+        rangeOfMotionInches: set.romLengthIn,
+        maxConcentricPowerWatts: set.maxConPower,
+        warmUp: set.warmUp,
+        spotter: set.spotter ?? undefined,
+        eccentric: set.eccentric,
+        chains: set.chains,
+        flex: set.flex,
+    };
+}
+function mapActivity(activity, detail, movements = new Map()) {
+    const exported = {
+        activityId: activity.id,
+        workoutId: activity.workoutId,
+        source: activity.activityType === 'Internal' ? 'tonal' : 'external',
+        name: activity.name,
+        timestamp: activity.timestamp,
+        localTimestamp: activity.localTimestamp,
+        timeZone: activity.timeZone,
+        targetArea: activity.targetArea,
+        workoutType: activity.workoutType,
+        level: activity.level,
+        durationSeconds: activity.duration,
+        timeUnderTensionSeconds: activity.timeUnderTension,
+        totalReps: activity.totalReps,
+        totalVolumePounds: activity.totalVolume,
+        totalWorkKilojoules: activity.totalWork,
+        completed: activity.completed,
+        guided: activity.isGuidedWorkout,
+        inProgram: activity.isInProgram,
+        baselineWorkout: activity.isBaselineWorkout,
+    };
+    if (detail !== undefined) {
+        exported.totalSets = detail.totalSets;
+        exported.activeDurationSeconds = detail.activeDuration ?? undefined;
+        exported.restDurationSeconds = detail.restDuration ?? undefined;
+        exported.percentCompleted = detail.percentCompleted ?? undefined;
+        exported.sets = (detail.workoutSetActivity ?? []).map(set => mapSetActivity(set, movements.get(set.movementId)));
+    }
+    return exported;
+}
+function sanitizeMuscleReadiness(readiness) {
+    return {
+        Chest: readiness.Chest,
+        Shoulders: readiness.Shoulders,
+        Back: readiness.Back,
+        Triceps: readiness.Triceps,
+        Biceps: readiness.Biceps,
+        Abs: readiness.Abs,
+        Obliques: readiness.Obliques,
+        Quads: readiness.Quads,
+        Glutes: readiness.Glutes,
+        Hamstrings: readiness.Hamstrings,
+        Calves: readiness.Calves,
+    };
+}
+function sanitizeLifetimeStatistics(statistics) {
+    return {
+        volume: {
+            total: statistics.volume.total,
+            maxVolumeInWorkout: statistics.volume.maxVolumeInWorkout,
+            maxVolumeInAWeek: statistics.volume.maxVolumeInAWeek,
+            avgVolumePerWorkout: statistics.volume.avgVolumePerWorkout,
+            avgVolumePerWeek: statistics.volume.avgVolumePerWeek,
+        },
+        workouts: {
+            total: statistics.workouts.total,
+            maxWorkoutDuration: statistics.workouts.maxWorkoutDuration,
+            avgWorkoutDuration: statistics.workouts.avgWorkoutDuration,
+            totalDuration: statistics.workouts.totalDuration,
+            totalTimeUnderTension: statistics.workouts.totalTimeUnderTension,
+            maxWorkoutsPerWeek: statistics.workouts.maxWorkoutsPerWeek,
+            avgWorkoutsPerWeek: statistics.workouts.avgWorkoutsPerWeek,
+            totalFreeliftWorkouts: statistics.workouts.totalFreeliftWorkouts,
+            totalCustomWorkouts: statistics.workouts.totalCustomWorkouts,
+        },
+        movements: {
+            total: statistics.movements.total,
+            movementIds: statistics.movements.movementIds.filter(movementId => typeof movementId === 'string'),
+        },
+        programs: {
+            total: statistics.programs.total,
+            totalProgramVolume: statistics.programs.totalProgramVolume,
+            totalProgramWorkouts: statistics.programs.totalProgramWorkouts,
+            totalDuration: statistics.programs.totalDuration,
+            programSummaries: null,
+        },
+    };
+}
+/**
+ * Build a compact, privacy-conscious health export from Tonal API data.
+ *
+ * The export intentionally excludes profile details, account identifiers,
+ * device identifiers, application versions, and authentication data.
+ */
+function buildHealthExport(source, options = {}, exportedAt = new Date()) {
+    const startTimestamp = parseDate(options.startDate, 'startDate');
+    const endTimestamp = parseDate(options.endDate, 'endDate', true);
+    if (startTimestamp !== undefined &&
+        endTimestamp !== undefined &&
+        (startTimestamp.localDate === undefined) ===
+            (endTimestamp.localDate === undefined) &&
+        startTimestamp.timestamp > endTimestamp.timestamp) {
+        throw new TonalClientError('startDate must be before or equal to endDate');
+    }
+    if (options.limit !== undefined &&
+        (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new TonalClientError('limit must be a positive integer');
+    }
+    const details = new Map((source.activityDetails ?? []).map(detail => [detail.id, detail]));
+    const movements = new Map((source.movements ?? []).map(movement => [movement.id, movement]));
+    const activities = source.activities
+        .filter(activity => {
+        const timestamp = Date.parse(activity.timestamp);
+        const localDate = startTimestamp?.localDate !== undefined || endTimestamp?.localDate !== undefined
+            ? getActivityLocalDate(activity)
+            : undefined;
+        const afterStart = startTimestamp === undefined ||
+            (startTimestamp.localDate !== undefined
+                ? localDate !== undefined && localDate >= startTimestamp.localDate
+                : timestamp >= startTimestamp.timestamp);
+        const beforeEnd = endTimestamp === undefined ||
+            (endTimestamp.localDate !== undefined
+                ? localDate !== undefined && localDate <= endTimestamp.localDate
+                : timestamp <= endTimestamp.timestamp);
+        return ((options.includeExternalActivities === true ||
+            activity.activityType === 'Internal') &&
+            !Number.isNaN(timestamp) &&
+            afterStart &&
+            beforeEnd);
+    })
+        .sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp))
+        .slice(0, options.limit)
+        .map(activity => mapActivity(activity, details.get(activity.id), movements));
+    const summary = activities.reduce((totals, activity) => ({
+        workoutCount: totals.workoutCount + 1,
+        completedWorkoutCount: totals.completedWorkoutCount + (activity.completed ? 1 : 0),
+        totalDurationSeconds: totals.totalDurationSeconds + activity.durationSeconds,
+        totalTimeUnderTensionSeconds: totals.totalTimeUnderTensionSeconds + activity.timeUnderTensionSeconds,
+        totalReps: totals.totalReps + activity.totalReps,
+        totalVolumePounds: totals.totalVolumePounds + activity.totalVolumePounds,
+        totalWorkKilojoules: totals.totalWorkKilojoules + activity.totalWorkKilojoules,
+    }), {
+        workoutCount: 0,
+        completedWorkoutCount: 0,
+        totalDurationSeconds: 0,
+        totalTimeUnderTensionSeconds: 0,
+        totalReps: 0,
+        totalVolumePounds: 0,
+        totalWorkKilojoules: 0,
+    });
+    const exportData = {
+        schemaVersion: 1,
+        exportedAt: exportedAt.toISOString(),
+        period: {
+            start: activities.length > 0 ? activities[activities.length - 1].timestamp : null,
+            end: activities.length > 0 ? activities[0].timestamp : null,
+        },
+        summary,
+        activities,
+    };
+    if (source.muscleReadiness !== undefined) {
+        exportData.muscleReadiness = sanitizeMuscleReadiness(source.muscleReadiness);
+    }
+    if (source.lifetimeStatistics !== undefined) {
+        exportData.lifetimeStatistics = sanitizeLifetimeStatistics(source.lifetimeStatistics);
+    }
+    return exportData;
+}
+
+const MAX_WORKOUT_ACTIVITY_PAGES = 1000;
 class TonalClient {
     constructor(username, password, cacheDir) {
         this.authManager = new AuthManager(username, password);
@@ -745,6 +1044,40 @@ class TonalClient {
         const userInfo = await this.getUserInfo();
         return this.userService.getActivitySummaries(userInfo.id);
     }
+    /**
+     * Get a page of completed workout activities including performed set data.
+     */
+    async getWorkoutActivities(offset = 0, limit = 100) {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getWorkoutActivities(userInfo.id, offset, limit);
+    }
+    /** Get every completed Tonal workout activity using paginated requests. */
+    async getAllWorkoutActivities(pageSize = 100) {
+        if (!Number.isInteger(pageSize) || pageSize <= 0 || pageSize > 100) {
+            throw new TonalClientError('Page size must be an integer between 1 and 100');
+        }
+        const activities = [];
+        await this.paginateWorkoutActivities(pageSize, page => {
+            activities.push(...page);
+            return false;
+        });
+        return activities;
+    }
+    async getFormattedWorkoutSummary(activityId) {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getFormattedWorkoutSummary(userInfo.id, activityId);
+    }
+    async getFormattedWorkoutSummaries(activityIds, batchSize = 5) {
+        if (!Number.isInteger(batchSize) || batchSize <= 0) {
+            throw new Error('Batch size must be a positive integer');
+        }
+        const userInfo = await this.getUserInfo();
+        const summaries = [];
+        for (let index = 0; index < activityIds.length; index += batchSize) {
+            summaries.push(...(await Promise.all(activityIds.slice(index, index + batchSize).map(activityId => this.userService.getFormattedWorkoutSummary(userInfo.id, activityId)))));
+        }
+        return summaries;
+    }
     async getUserStatistics() {
         const userInfo = await this.getUserInfo();
         return this.userService.getUserStatistics(userInfo.id);
@@ -776,6 +1109,89 @@ class TonalClient {
         const userInfo = await this.getUserInfo();
         return this.userService.getMetricScores(userInfo.id, startWeek);
     }
+    /**
+     * Create a compact export intended for health analysis and data portability.
+     *
+     * The export excludes profile, device, and authentication details. Activities
+     * can be filtered by date and limited, and optional readiness and lifetime
+     * statistics can be omitted when a smaller data set is preferred.
+     */
+    async getHealthExport(options = {}) {
+        const includeMuscleReadiness = options.includeMuscleReadiness ?? true;
+        const includeLifetimeStatistics = options.includeLifetimeStatistics ?? true;
+        const [activities, muscleReadiness, lifetimeStatistics] = await Promise.all([
+            this.getActivitySummaries(),
+            includeMuscleReadiness ? this.getMuscleReadiness() : Promise.resolve(undefined),
+            includeLifetimeStatistics ? this.getUserStatistics() : Promise.resolve(undefined),
+        ]);
+        const exportedAt = new Date();
+        const initialExport = buildHealthExport({
+            activities,
+            muscleReadiness,
+            lifetimeStatistics,
+        }, options, exportedAt);
+        if (!options.includeSetDetails || initialExport.activities.length === 0) {
+            return initialExport;
+        }
+        const tonalActivityIds = initialExport.activities
+            .filter(activity => activity.source === 'tonal')
+            .map(activity => activity.activityId);
+        if (tonalActivityIds.length === 0) {
+            return initialExport;
+        }
+        const [activityDetails, movements] = await Promise.all([
+            this.getWorkoutActivityDetails(tonalActivityIds),
+            this.getMovements(),
+        ]);
+        return buildHealthExport({
+            activities,
+            muscleReadiness,
+            lifetimeStatistics,
+            activityDetails,
+            movements,
+        }, options, exportedAt);
+    }
+    async paginateWorkoutActivities(pageSize, visitActivities) {
+        const userInfo = await this.getUserInfo();
+        const seenIds = new Set();
+        for (let pageNumber = 0, offset = 0;; pageNumber += 1) {
+            const page = await this.userService.getWorkoutActivities(userInfo.id, offset, pageSize);
+            const newActivities = page.filter(activity => {
+                if (seenIds.has(activity.id)) {
+                    return false;
+                }
+                seenIds.add(activity.id);
+                return true;
+            });
+            if (visitActivities(newActivities) || page.length < pageSize) {
+                return;
+            }
+            if (newActivities.length === 0) {
+                throw new TonalClientError(`Workout activity pagination did not advance at offset ${offset}`);
+            }
+            if (pageNumber + 1 >= MAX_WORKOUT_ACTIVITY_PAGES) {
+                throw new TonalClientError(`Workout activity pagination exceeded the ${MAX_WORKOUT_ACTIVITY_PAGES}-page safety limit`);
+            }
+            const nextOffset = offset + pageSize;
+            if (!Number.isSafeInteger(nextOffset) || nextOffset <= offset) {
+                throw new TonalClientError(`Workout activity pagination could not advance beyond offset ${offset}`);
+            }
+            offset = nextOffset;
+        }
+    }
+    async getWorkoutActivityDetails(activityIds) {
+        const requestedIds = new Set(activityIds);
+        const details = [];
+        await this.paginateWorkoutActivities(100, activities => {
+            for (const activity of activities) {
+                if (requestedIds.delete(activity.id)) {
+                    details.push(activity);
+                }
+            }
+            return requestedIds.size === 0;
+        });
+        return details;
+    }
     // Workout operations
     async getUserWorkouts(offset = 0, limit = 50) {
         return this.workoutService.getUserWorkouts(offset, limit);
@@ -805,4 +1221,4 @@ class TonalClient {
     }
 }
 
-export { TonalClient, TonalClientError, TonalClient as default };
+export { TonalClient, TonalClientError, buildHealthExport, TonalClient as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dlwiest/ts-tonal-client",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript client for Tonal API",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
@@ -52,7 +52,9 @@
     "example:program-by-id": "tsx examples/get-program-by-id.ts",
     "example:target-scores": "tsx examples/get-target-scores.ts",
     "example:metric-scores": "tsx examples/get-metric-scores.ts",
-    "example:workout-activity": "tsx examples/get-workout-activity.ts"
+    "example:workout-activity": "tsx examples/get-workout-activity.ts",
+    "example:health-export": "tsx examples/export-health-data.ts",
+    "example:complete-health-export": "tsx examples/export-complete-health-data.ts"
   },
   "repository": {
     "type": "git",