@dlwiest/ts-tonal-client 0.4.0 → 0.5.1

package/README.md

@@ -54,7 +54,7 @@ console.log(`You have ${workouts.length} workouts`)
 
 ### Client setup
 
-`TonalClient.create()` accepts credentials and an optional movement cache directory:
+`TonalClient.create()` accepts credentials and an optional cache directory:
 
 ```typescript
 TonalClient.create(credentials: {
@@ -64,9 +64,9 @@ TonalClient.create(credentials: {
 }): Promise<TonalClient>
 ```
 
-Without `cacheDir`, movement data is cached in `$XDG_CACHE_HOME/ts-tonal-client` when `XDG_CACHE_HOME` is set. Otherwise, the cache lives at `~/.cache/ts-tonal-client`. The directory is created on the first successful cache write, not when the client is created.
+Without `cacheDir`, cached movements and completed workout activities are stored in `$XDG_CACHE_HOME/ts-tonal-client` when `XDG_CACHE_HOME` is set. Otherwise, the cache lives at `~/.cache/ts-tonal-client`. The directory is created on the first successful cache write, not when the client is created.
 
-Pass `cacheDir` to store the movement cache somewhere else:
+Pass `cacheDir` to store both caches somewhere else:
 
 ```typescript
 const client = await TonalClient.create({
@@ -78,7 +78,9 @@ const client = await TonalClient.create({
 
 ### Cache invalidation
 
-`TonalClient.invalidateUserInfo(): void` clears the cached user profile. Call `client.invalidateUserInfo()` before the next `getUserInfo()` request to fetch fresh data.
+`await client.invalidateMovementsCache()` clears the movements cache only. It does not clear cached workout activities.
+
+`client.invalidateUserInfo()` clears the in-memory user profile. Call it before the next `getUserInfo()` request to fetch fresh data.
 
 ## Examples
 
@@ -222,6 +224,86 @@ const updatedWorkout = await client.updateWorkout({
 await client.deleteWorkout('workout-uuid')
 ```
 
+### Performed workout activities
+
+A workout activity is one performed workout session, not a workout template. Get an activity ID from `getActivitySummaries()`, then fetch its detail from `/users/{userId}/workout-activities/{activityId}`:
+
+```typescript
+const summaries = await client.getActivitySummaries()
+const recent = [...summaries]
+  .filter(summary => summary.completed)
+  .sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp))[0]
+
+if (recent) {
+  const activity = await client.getWorkoutActivityById(recent.id)
+  console.log(`${activity.totalSets} sets, ${activity.totalReps} reps`)
+  console.log(`Completed: ${activity.completed === true}`)
+}
+```
+
+The method signature is:
+
+```typescript
+async getWorkoutActivityById(
+  activityId: string,
+  useCache: boolean = true
+): Promise<TonalWorkoutActivity>
+```
+
+Completed activities are immutable, so results with `completed === true` are cached permanently with no TTL. In-progress activities are never cached. Cache keys include both the user and activity IDs, which prevents collisions between accounts. Cache reads and writes are best-effort: a cache failure never fails the API request or hides a successful response. Pass `false` for `useCache` to force a fresh request.
+
+Activity entries use the same `cacheDir` and default cache location described under [Client setup](#client-setup). Permanent entries never expire and nothing evicts them automatically, so the cache grows by one small file for each completed activity viewed. `invalidateMovementsCache()` does not clear these entries.
+
+#### Activity response types
+
+`TonalWorkoutActivity` contains the performed session's IDs, timestamps, duration and aggregate totals, completion state, device metadata, and its set activity records:
+
+```typescript
+interface TonalWorkoutActivity {
+  id: string
+  userId: string
+  workoutId: string
+  workoutType?: string | null
+  beginTime: string
+  endTime?: string | null
+  totalDuration: number
+  activeDuration?: number | null
+  restDuration?: number | null
+  totalMovements?: number | null
+  totalSets: number
+  totalReps: number
+  totalVolume: number
+  totalConcentricWork?: number | null
+  percentCompleted?: number | null
+  completed?: boolean | null
+  workoutSetActivity: TonalWorkoutSetActivity[]
+  contentCard?: unknown
+  deviceId?: string | null
+  timezone?: string | null
+  appVersion?: string | null
+}
+```
+
+Each `TonalWorkoutSetActivity` identifies a movement and includes the performed or prescribed values available for that set:
+
+```typescript
+interface TonalWorkoutSetActivity {
+  movementId: string
+  prescribedReps?: number | null
+  repetition?: number | null
+  repetitionTotal?: number | null
+  weightPercentage?: number | null
+  baseWeight?: number | null
+  eccentricWeight?: number | null
+  chainsWeight?: number | null
+  blockNumber?: number | null
+  blockStart?: boolean | null
+  sideNumber?: number | null
+  setId?: string | null
+  spotter?: boolean | null
+}
+```
+
 ### User Information
 
 ```typescript
@@ -278,14 +360,6 @@ console.log(`Current streak: ${streak.currentStreak} workouts`)
 console.log(`Personal best: ${streak.maxStreak} workouts`)
 console.log(`Progress to personal best: ${Math.round((streak.currentStreak / streak.maxStreak) * 100)}%`)
 
-// Get comprehensive workout activity history
-const activities = await client.getActivitySummaries()
-console.log(`Total workouts completed: ${activities.length}`)
-const totalVolume = activities.reduce((sum, activity) => sum + activity.totalVolume, 0)
-console.log(`Total volume lifted: ${totalVolume.toLocaleString()} lbs`)
-const guidedWorkouts = activities.filter(a => a.isGuidedWorkout).length
-console.log(`Guided vs Free Lift: ${guidedWorkouts}/${activities.length - guidedWorkouts}`)
-
 // Get lifetime statistics and achievements
 const stats = await client.getUserStatistics()
 console.log(`Total volume: ${stats.volume.total.toLocaleString()} lbs over ${stats.workouts.total} workouts`)

package/dist/index.cjs

@@ -5,6 +5,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var fs = require('fs');
 var os = require('os');
 var path = require('path');
+var crypto = require('crypto');
 
 class TonalClientError extends Error {
     constructor(message, statusCode, originalError) {
@@ -72,9 +73,60 @@ class AuthManager {
         const tokenData = await response.json();
         this.idToken = tokenData.id_token;
         this.refreshToken = tokenData.refresh_token ?? '';
-        this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
+        const expiresInDeadline = Date.now() + tokenData.expires_in * 1000;
+        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 noInfoFallback;
+            }
+            const segments = idToken.split('.');
+            if (segments.length !== 3) {
+                return noInfoFallback;
+            }
+            const payloadSegment = segments[1];
+            if (!/^[A-Za-z0-9_-]+$/.test(payloadSegment)) {
+                return noInfoFallback;
+            }
+            const payloadBuffer = Buffer.from(payloadSegment, 'base64url');
+            if (payloadBuffer.toString('base64url') !== payloadSegment) {
+                return noInfoFallback;
+            }
+            const payload = JSON.parse(payloadBuffer.toString('utf8'));
+            if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+                return noInfoFallback;
+            }
+            const exp = 'exp' in payload ? payload.exp : undefined;
+            if (typeof exp !== 'number' || !Number.isFinite(exp) || exp <= 0) {
+                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 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.
+            // 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 noInfoFallback;
+        }
+    }
     invalidateToken() {
         this.tokenExpiresAt = 0;
     }
@@ -133,7 +185,8 @@ class AuthManager {
         const tokenData = await response.json();
         this.idToken = tokenData.id_token;
         this.refreshToken = tokenData.refresh_token ?? this.refreshToken;
-        this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
+        const expiresInDeadline = Date.now() + tokenData.expires_in * 1000;
+        this.tokenExpiresAt = this.getTokenExpiresAt(tokenData.id_token, expiresInDeadline);
     }
 }
 
@@ -391,7 +444,8 @@ class CacheManager {
             const cachedAt = new Date(entry.cachedAt).getTime();
             const now = Date.now();
             const age = now - cachedAt;
-            if (!Number.isFinite(cachedAt) || typeof entry.ttl !== 'number' || age > entry.ttl) {
+            if (!Number.isFinite(cachedAt) ||
+                (entry.ttl !== null && (typeof entry.ttl !== 'number' || age > entry.ttl))) {
                 return null;
             }
             return entry.data;
@@ -402,11 +456,17 @@ class CacheManager {
         }
     }
     async set(key, data, ttl) {
+        this.write(key, data, ttl || this.defaultTTL);
+    }
+    async setPermanent(key, data) {
+        this.write(key, data, null);
+    }
+    write(key, data, ttl) {
         const cachePath = this.getCachePath(key);
         this.ensureCacheDir();
         const entry = {
             cachedAt: new Date().toISOString(),
-            ttl: ttl || this.defaultTTL,
+            ttl,
             data,
         };
         const tempPath = `${cachePath}.tmp`;
@@ -456,8 +516,9 @@ class MovementService {
 }
 
 class UserService {
-    constructor(httpClient) {
+    constructor(httpClient, cacheDir) {
         this.httpClient = httpClient;
+        this.cacheManager = new CacheManager(cacheDir);
     }
     async getUserInfo() {
         return this.httpClient.request('/users/userinfo');
@@ -528,6 +589,36 @@ class UserService {
         // Tonal's "limit" query parameter is a calendar-day window; small values return an empty array.
         return this.httpClient.request(`/users/${userId}/strength-scores/history?limit=${days}`);
     }
+    async getWorkoutActivityById(userId, activityId, useCache = true) {
+        const canonicalActivityId = activityId.trim();
+        if (!canonicalActivityId) {
+            throw new TonalClientError('Workout activity id must not be empty');
+        }
+        const cacheKey = `workout-activity-v1-${crypto.createHash('sha256')
+            .update(`${userId}\0${canonicalActivityId}`)
+            .digest('hex')}`;
+        if (useCache) {
+            try {
+                const cached = await this.cacheManager.get(cacheKey);
+                if (cached !== null) {
+                    return cached;
+                }
+            }
+            catch {
+                // Cache reads are best-effort and must not prevent a fresh request.
+            }
+        }
+        const activity = await this.httpClient.request(`/users/${userId}/workout-activities/${encodeURIComponent(canonicalActivityId)}`);
+        if (activity.completed === true) {
+            try {
+                await this.cacheManager.setPermanent(cacheKey, activity);
+            }
+            catch {
+                // Cache writes are best-effort and must not hide a successful API response.
+            }
+        }
+        return activity;
+    }
     async getActivitySummaries(userId) {
         return this.httpClient.request(`/users/${userId}/activity-summaries`);
     }
@@ -566,7 +657,7 @@ class TonalClient {
         this.httpClient = new HttpClient(this.authManager);
         this.workoutService = new WorkoutService(this.httpClient);
         this.movementService = new MovementService(this.httpClient, cacheDir);
-        this.userService = new UserService(this.httpClient);
+        this.userService = new UserService(this.httpClient, cacheDir);
     }
     static async create(credentials) {
         const client = new TonalClient(credentials.username, credentials.password, credentials.cacheDir);
@@ -661,6 +752,10 @@ class TonalClient {
         }
         return this.userService.getStrengthScoreHistory(userInfo.id, lookbackDays);
     }
+    async getWorkoutActivityById(activityId, useCache = true) {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getWorkoutActivityById(userInfo.id, activityId, useCache);
+    }
     async getActivitySummaries() {
         const userInfo = await this.getUserInfo();
         return this.userService.getActivitySummaries(userInfo.id);

package/dist/index.d.ts

@@ -120,6 +120,44 @@ interface TonalWorkout {
     isImported: boolean;
     createdSource?: unknown | null;
 }
+interface TonalWorkoutSetActivity {
+    movementId: string;
+    prescribedReps?: number | null;
+    repetition?: number | null;
+    repetitionTotal?: number | null;
+    weightPercentage?: number | null;
+    baseWeight?: number | null;
+    eccentricWeight?: number | null;
+    chainsWeight?: number | null;
+    blockNumber?: number | null;
+    blockStart?: boolean | null;
+    sideNumber?: number | null;
+    setId?: string | null;
+    spotter?: boolean | null;
+}
+interface TonalWorkoutActivity {
+    id: string;
+    userId: string;
+    workoutId: string;
+    workoutType?: string | null;
+    beginTime: string;
+    endTime?: string | null;
+    totalDuration: number;
+    activeDuration?: number | null;
+    restDuration?: number | null;
+    totalMovements?: number | null;
+    totalSets: number;
+    totalReps: number;
+    totalVolume: number;
+    totalConcentricWork?: number | null;
+    percentCompleted?: number | null;
+    completed?: boolean | null;
+    workoutSetActivity: TonalWorkoutSetActivity[];
+    contentCard?: unknown;
+    deviceId?: string | null;
+    timezone?: string | null;
+    appVersion?: string | null;
+}
 interface TonalSharedWorkout {
     id: string;
     sharerUserId: string;
@@ -687,6 +725,7 @@ declare class TonalClient {
     getCurrentStreak(): Promise<TonalCurrentStreak>;
     getCurrentStrengthScores(): Promise<TonalStrengthScore[]>;
     getStrengthScoreHistory(days?: TonalStrengthScoreHistoryLookback): Promise<TonalStrengthScoreHistoryEntry[]>;
+    getWorkoutActivityById(activityId: string, useCache?: boolean): Promise<TonalWorkoutActivity>;
     getActivitySummaries(): Promise<TonalActivitySummary[]>;
     getUserStatistics(): Promise<TonalUserStatistics>;
     getAchievementStats(): Promise<TonalAchievementStats>;
@@ -706,4 +745,4 @@ declare class TonalClient {
     deleteWorkout(workoutId: string): Promise<void>;
 }
 
-export { MuscleGroup, OAuthTokenResponse, TonalAchievementCategory, TonalAchievementDefinition, TonalAchievementMilestone, TonalAchievementStats, TonalActivitySummary, TonalApiError, TonalCalendarTile, TonalClient, TonalClientError, TonalCompatibilityStatus, TonalCurrentStreak, TonalDailyMetrics, TonalDailySchedule, TonalDeviceRegistration, TonalEarnedAchievement, TonalGoal, TonalGoalMetric, TonalHomeCalendar, TonalMetricScore, TonalMetricScoresResponse, TonalMovement, TonalMuscleReadiness, TonalMuscleUtilization, TonalProgram, TonalProgramTrainingEffectGoal, TonalProgramWorkout, TonalSharedWorkout, TonalStrengthBodyRegion, TonalStrengthScore, TonalStrengthScoreHistoryEntry, TonalStrengthScoreHistoryLookback, TonalTargetScore, TonalTargetScoresResponse, TonalTrainingEffectGoal, TonalTrainingEffectGoalRelation, TonalTrainingEffectGoalsResponse, TonalTrainingType, TonalUserDevice, TonalUserGoal, TonalUserInfo, TonalUserPermissions, TonalUserSettings, TonalUserStatistics, TonalWorkout, TonalWorkoutCreateRequest, TonalWorkoutEstimateResponse, TonalWorkoutEstimateSet, TonalWorkoutSummaryData, TonalWorkoutUpdateRequest, WorkoutPublishState, WorkoutSet, TonalClient as default };
+export { MuscleGroup, OAuthTokenResponse, TonalAchievementCategory, TonalAchievementDefinition, TonalAchievementMilestone, TonalAchievementStats, TonalActivitySummary, TonalApiError, TonalCalendarTile, TonalClient, TonalClientError, TonalCompatibilityStatus, TonalCurrentStreak, TonalDailyMetrics, TonalDailySchedule, TonalDeviceRegistration, TonalEarnedAchievement, TonalGoal, TonalGoalMetric, TonalHomeCalendar, TonalMetricScore, TonalMetricScoresResponse, TonalMovement, TonalMuscleReadiness, TonalMuscleUtilization, TonalProgram, TonalProgramTrainingEffectGoal, TonalProgramWorkout, TonalSharedWorkout, TonalStrengthBodyRegion, TonalStrengthScore, TonalStrengthScoreHistoryEntry, TonalStrengthScoreHistoryLookback, TonalTargetScore, TonalTargetScoresResponse, TonalTrainingEffectGoal, TonalTrainingEffectGoalRelation, TonalTrainingEffectGoalsResponse, TonalTrainingType, TonalUserDevice, TonalUserGoal, TonalUserInfo, TonalUserPermissions, TonalUserSettings, TonalUserStatistics, TonalWorkout, TonalWorkoutActivity, TonalWorkoutCreateRequest, TonalWorkoutEstimateResponse, TonalWorkoutEstimateSet, TonalWorkoutSetActivity, TonalWorkoutSummaryData, TonalWorkoutUpdateRequest, WorkoutPublishState, WorkoutSet, TonalClient as default };

package/dist/index.esm.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { createHash } from 'crypto';
 
 class TonalClientError extends Error {
     constructor(message, statusCode, originalError) {
@@ -68,9 +69,60 @@ class AuthManager {
         const tokenData = await response.json();
         this.idToken = tokenData.id_token;
         this.refreshToken = tokenData.refresh_token ?? '';
-        this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
+        const expiresInDeadline = Date.now() + tokenData.expires_in * 1000;
+        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 noInfoFallback;
+            }
+            const segments = idToken.split('.');
+            if (segments.length !== 3) {
+                return noInfoFallback;
+            }
+            const payloadSegment = segments[1];
+            if (!/^[A-Za-z0-9_-]+$/.test(payloadSegment)) {
+                return noInfoFallback;
+            }
+            const payloadBuffer = Buffer.from(payloadSegment, 'base64url');
+            if (payloadBuffer.toString('base64url') !== payloadSegment) {
+                return noInfoFallback;
+            }
+            const payload = JSON.parse(payloadBuffer.toString('utf8'));
+            if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+                return noInfoFallback;
+            }
+            const exp = 'exp' in payload ? payload.exp : undefined;
+            if (typeof exp !== 'number' || !Number.isFinite(exp) || exp <= 0) {
+                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 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.
+            // 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 noInfoFallback;
+        }
+    }
     invalidateToken() {
         this.tokenExpiresAt = 0;
     }
@@ -129,7 +181,8 @@ class AuthManager {
         const tokenData = await response.json();
         this.idToken = tokenData.id_token;
         this.refreshToken = tokenData.refresh_token ?? this.refreshToken;
-        this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
+        const expiresInDeadline = Date.now() + tokenData.expires_in * 1000;
+        this.tokenExpiresAt = this.getTokenExpiresAt(tokenData.id_token, expiresInDeadline);
     }
 }
 
@@ -387,7 +440,8 @@ class CacheManager {
             const cachedAt = new Date(entry.cachedAt).getTime();
             const now = Date.now();
             const age = now - cachedAt;
-            if (!Number.isFinite(cachedAt) || typeof entry.ttl !== 'number' || age > entry.ttl) {
+            if (!Number.isFinite(cachedAt) ||
+                (entry.ttl !== null && (typeof entry.ttl !== 'number' || age > entry.ttl))) {
                 return null;
             }
             return entry.data;
@@ -398,11 +452,17 @@ class CacheManager {
         }
     }
     async set(key, data, ttl) {
+        this.write(key, data, ttl || this.defaultTTL);
+    }
+    async setPermanent(key, data) {
+        this.write(key, data, null);
+    }
+    write(key, data, ttl) {
         const cachePath = this.getCachePath(key);
         this.ensureCacheDir();
         const entry = {
             cachedAt: new Date().toISOString(),
-            ttl: ttl || this.defaultTTL,
+            ttl,
             data,
         };
         const tempPath = `${cachePath}.tmp`;
@@ -452,8 +512,9 @@ class MovementService {
 }
 
 class UserService {
-    constructor(httpClient) {
+    constructor(httpClient, cacheDir) {
         this.httpClient = httpClient;
+        this.cacheManager = new CacheManager(cacheDir);
     }
     async getUserInfo() {
         return this.httpClient.request('/users/userinfo');
@@ -524,6 +585,36 @@ class UserService {
         // Tonal's "limit" query parameter is a calendar-day window; small values return an empty array.
         return this.httpClient.request(`/users/${userId}/strength-scores/history?limit=${days}`);
     }
+    async getWorkoutActivityById(userId, activityId, useCache = true) {
+        const canonicalActivityId = activityId.trim();
+        if (!canonicalActivityId) {
+            throw new TonalClientError('Workout activity id must not be empty');
+        }
+        const cacheKey = `workout-activity-v1-${createHash('sha256')
+            .update(`${userId}\0${canonicalActivityId}`)
+            .digest('hex')}`;
+        if (useCache) {
+            try {
+                const cached = await this.cacheManager.get(cacheKey);
+                if (cached !== null) {
+                    return cached;
+                }
+            }
+            catch {
+                // Cache reads are best-effort and must not prevent a fresh request.
+            }
+        }
+        const activity = await this.httpClient.request(`/users/${userId}/workout-activities/${encodeURIComponent(canonicalActivityId)}`);
+        if (activity.completed === true) {
+            try {
+                await this.cacheManager.setPermanent(cacheKey, activity);
+            }
+            catch {
+                // Cache writes are best-effort and must not hide a successful API response.
+            }
+        }
+        return activity;
+    }
     async getActivitySummaries(userId) {
         return this.httpClient.request(`/users/${userId}/activity-summaries`);
     }
@@ -562,7 +653,7 @@ class TonalClient {
         this.httpClient = new HttpClient(this.authManager);
         this.workoutService = new WorkoutService(this.httpClient);
         this.movementService = new MovementService(this.httpClient, cacheDir);
-        this.userService = new UserService(this.httpClient);
+        this.userService = new UserService(this.httpClient, cacheDir);
     }
     static async create(credentials) {
         const client = new TonalClient(credentials.username, credentials.password, credentials.cacheDir);
@@ -657,6 +748,10 @@ class TonalClient {
         }
         return this.userService.getStrengthScoreHistory(userInfo.id, lookbackDays);
     }
+    async getWorkoutActivityById(activityId, useCache = true) {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getWorkoutActivityById(userInfo.id, activityId, useCache);
+    }
     async getActivitySummaries() {
         const userInfo = await this.getUserInfo();
         return this.userService.getActivitySummaries(userInfo.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dlwiest/ts-tonal-client",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "TypeScript client for Tonal API",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
@@ -51,7 +51,8 @@
     "example:muscle-readiness": "tsx examples/get-muscle-readiness.ts",
     "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:metric-scores": "tsx examples/get-metric-scores.ts",
+    "example:workout-activity": "tsx examples/get-workout-activity.ts"
   },
   "repository": {
     "type": "git",