@dlwiest/ts-tonal-client 0.5.0 → 0.6.0

package/README.md

@@ -3,20 +3,53 @@
 [![npm version](https://badge.fury.io/js/@dlwiest%2Fts-tonal-client.svg)](https://badge.fury.io/js/@dlwiest%2Fts-tonal-client)
 [![npm downloads](https://img.shields.io/npm/dm/@dlwiest/ts-tonal-client.svg)](https://www.npmjs.com/package/@dlwiest/ts-tonal-client)
 
-A comprehensive TypeScript client for accessing Tonal's API. This library provides a robust interface to retrieve workout data, user information, movements, and more from your Tonal account.
-
-## Features
-
-- 🏋️ **Complete Workout Management** - Get, create, estimate, and share workouts including daily lifts
-- 👤 **User Management** - Access user info, goals, and preferences  
-- 💪 **Movement Database** - Browse all available Tonal movements
-- 🎯 **Muscle Readiness Tracking** - Monitor recovery status for all muscle groups
-- 📋 **Program Details** - Get comprehensive information about training programs
-- 🎯 **Target Score Tracking** - Get weekly fitness targets and progress ranges for all metrics
-- 📈 **Metric Score Analysis** - Track actual performance vs targets with comprehensive analytics
-- 🛡️ **Enterprise-Grade Reliability** - Built-in error handling, retries, and timeouts
-- 📝 **Full TypeScript Support** - Comprehensive types for all API responses
-- 🔄 **Smart Token Management** - Automatic authentication and token refresh
+A TypeScript client for working with data from a Tonal account. It wraps
+authentication, workout and movement APIs, completed performance data, recovery
+metrics, programs, goals, and personal health-data exports in a typed interface.
+
+> [!IMPORTANT]
+> This is an unofficial community project. It is not affiliated with or
+> supported by Tonal, and the private APIs it uses may change without notice.
+
+## Product Overview
+
+The client is meant for personal tools, data exports, and applications that need
+more Tonal detail than a general fitness integration may provide. In particular,
+it can retrieve performed set data—movements, reps, weight, volume, training
+modes, timing, and estimated one-rep max—and combine it with workout summaries,
+muscle readiness, and lifetime totals.
+
+One intended workflow is to create a privacy-conscious JSON snapshot and upload
+it to an AI assistant such as ChatGPT for personal health analysis. This is a
+file-based bridge, not a live or automatic ChatGPT connection: generate a new
+export whenever the assistant needs current Tonal data.
+
+## Product Features
+
+| Area | Current capabilities |
+| --- | --- |
+| Authentication | Sign in with Tonal account credentials and automatically manage access-token refresh |
+| Workout library | List, retrieve, create, update, delete, share, and estimate workouts; retrieve Daily Lifts |
+| Completed performance | Retrieve activity summaries, paginated workout history, and individual workout details including performed sets, reps, weights, volume, timing, training modes, and estimated one-rep max |
+| Movements and programs | Browse Tonal movements and muscle groups and retrieve detailed training programs |
+| Training and recovery | Retrieve daily metrics, streaks, muscle readiness, weekly targets, and actual metric scores |
+| History and achievements | Retrieve lifetime statistics, achievement progress, earned achievements, and home-calendar recommendations |
+| Health data export | Produce date-filtered JSON with aggregate totals, optional recovery and lifetime data, and optional set-level workout details |
+| Developer experience | TypeScript response types, request validation, retries, timeouts, movement caching, and runnable examples |
+
+## Current Limitations
+
+- Tonal does not publish or guarantee the private APIs used by this project.
+- Authentication currently requires Tonal account credentials; never commit a
+  populated `.env` file or include credentials in an export.
+- Health exports are point-in-time files. They do not continuously synchronize
+  Tonal with ChatGPT or another health service.
+- Detailed exports fetch paginated workout activity data, so large account
+  histories may require additional requests and take longer.
+- Tonal reports average resistance per cable. The export preserves that value
+  and derives effective average resistance from Tonal's total on-machine volume
+  divided by completed reps, correctly accounting for dual-cable movements such
+  as straight-bar lifts.
 
 ## Installation
 
@@ -165,8 +198,111 @@ npm run example:target-scores
 
 # Get actual performance scores vs targets with comprehensive analytics
 npm run example:metric-scores
+
+# Export workout summaries for personal health analysis
+npm run example:health-export
+
+# Export complete Tonal history and all available health metrics
+npm run example:complete-health-export
 ```
 
+## Health Data Export
+
+Create a JSON-ready export containing workout summaries, aggregate totals, current
+muscle readiness, and lifetime statistics:
+
+```typescript
+import { writeFile } from 'node:fs/promises'
+
+const exportData = await client.getHealthExport({
+  startDate: '2026-01-01',
+  limit: 100,
+  includeSetDetails: true,
+})
+
+await writeFile(
+  'tonal-health-export.json',
+  JSON.stringify(exportData, null, 2)
+)
+```
+
+Run `npm run example:health-export` to write a compact export of the 50 most
+recent Tonal workouts to `tonal-health-export.json`. The example atomically
+replaces the file with owner-only permissions and refuses symbolic-link
+destinations.
+
+The export intentionally excludes profile details, account identifiers, device
+identifiers, application versions, and authentication data. It still contains
+private health and workout information, so store and share it carefully.
+
+Available options:
+
+- `startDate` and `endDate`: include activities within an ISO-8601 range;
+  date-only values use each workout's local calendar day
+- `limit`: include at most this many activities, newest first
+- `includeMuscleReadiness`: include current readiness data (default: `true`)
+- `includeLifetimeStatistics`: include lifetime aggregate data (default: `true`)
+- `includeExternalActivities`: include workouts imported into Tonal from another
+  service (default: `false`, preventing duplication with Apple Health data)
+- `includeSetDetails`: fetch performed sets, reps, weights, movement names, and
+  one-rep-max estimates from paginated workout activity data (default: `false`)
+
+Set details keep Tonal's reported per-cable values in
+`averageResistancePerCablePounds` and
+`estimatedOneRepMaxPerCablePounds`. Arithmetic derived from total volume and
+completed reps is separated under `derivedEstimates`, with
+`averageResistancePounds` and `oneRepMaxPounds` explicitly documented as
+estimates rather than measured values. `totalVolumePounds` uses Tonal's
+`totalOnMachineVolume`, which reconciles with the completed workout's total
+volume.
+
+Detailed completed workouts are also available directly:
+
+```typescript
+// Get a page of completed activities with performed set data
+const activities = await client.getWorkoutActivities(0, 100)
+
+// Get every activity, with duplicate-page and page-cap safety checks
+const completeHistory = await client.getAllWorkoutActivities()
+
+// Get one completed activity by its activity ID
+const activity = await client.getWorkoutActivityById('activity-uuid')
+console.log(activity.workoutSetActivity)
+
+// Get the summary returned for one activity
+const summary = await client.getFormattedWorkoutSummary('activity-uuid')
+
+// Get summaries in bounded request batches
+const summaries = await client.getFormattedWorkoutSummaries(
+  completeHistory.map(item => item.id),
+  5
+)
+```
+
+### Complete History Export
+
+Run `npm run example:complete-health-export` to retrieve every paginated Tonal
+workout from the beginning of the account history. The resulting
+`tonal-complete-health-export.json` includes raw set-performance metrics,
+formatted workout and movement summaries, full daily metrics for the covered
+period, strength-score history, weekly targets and scores, current readiness,
+streaks, lifetime statistics, achievements, and reference definitions.
+
+The complete export is structured as JSON for analysis tools such as ChatGPT.
+It includes a data dictionary explaining units and Tonal's per-cable resistance
+convention. Account, device, application, subscription, and authentication
+identifiers and user weight are removed recursively. The JSON is compacted to
+reduce upload size and text-token usage without dropping allowed data. The file
+still contains highly private health information and is atomically replaced
+with owner-only permissions.
+
+The script also atomically recreates a private `tonal-chatgpt-export` directory
+containing `overview-and-metrics.json` and one `workouts-YYYY.json` file for
+each year in the history, so files from an older export cannot survive a rerun.
+Upload every file listed by `overview-and-metrics.json` together. The split
+bundle contains the same information but keeps each text file smaller and
+easier for ChatGPT to analyze completely.
+
 ## API Reference
 
 ### Workouts

package/dist/index.cjs

@@ -77,43 +77,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() {
@@ -611,6 +622,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`);
     }
@@ -640,6 +674,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);
@@ -749,6 +1048,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);
@@ -780,6 +1113,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);
@@ -811,4 +1227,5 @@ class TonalClient {
 
 exports.TonalClient = TonalClient;
 exports.TonalClientError = TonalClientError;
+exports.buildHealthExport = buildHealthExport;
 exports.default = TonalClient;