@dlwiest/ts-tonal-client 0.2.0 → 0.3.0

package/README.md

@@ -52,6 +52,34 @@ const workouts = await client.getUserWorkouts()
 console.log(`You have ${workouts.length} workouts`)
 ```
 
+### Client setup
+
+`TonalClient.create()` accepts credentials and an optional movement cache directory:
+
+```typescript
+TonalClient.create(credentials: {
+  username: string,
+  password: string,
+  cacheDir?: string,
+}): 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.
+
+Pass `cacheDir` to store the movement cache somewhere else:
+
+```typescript
+const client = await TonalClient.create({
+  username: 'your_email@example.com',
+  password: 'your_password',
+  cacheDir: '/path/to/cache',
+})
+```
+
+### Cache invalidation
+
+`TonalClient.invalidateUserInfo(): void` clears the cached user profile. Call `client.invalidateUserInfo()` before the next `getUserInfo()` request to fetch fresh data.
+
 ## Examples
 
 To run the example scripts, first create a `.env` file:
@@ -67,6 +95,9 @@ Then try the examples:
 # See all your workouts
 npm run example:user-workouts
 
+# Search for workouts by name
+npm run example:workout:name "Upper Body"
+
 # Get your user info
 npm run example:user
 
@@ -150,9 +181,16 @@ console.log(`You have ${dailyLifts.length} daily lifts`)
 // Get daily lifts with specific timezone
 const dailyLiftsEST = await client.getDailyLifts('America/New_York')
 
-// Get specific workout details  
+// Get specific workout details
 const workout = await client.getWorkoutById('workout-uuid')
 
+// Search for workouts by name (case-insensitive partial match)
+const workouts = await client.getUserWorkouts(0, 50)
+const matches = workouts.filter(w =>
+  w.title.toLowerCase().includes('upper body')
+)
+console.log(`Found ${matches.length} matching workouts`)
+
 // Get shared workout
 const sharedWorkout = await client.getWorkoutByShareUrl('https://share.tonal.com/workout/...')
 
@@ -425,6 +463,7 @@ const chestMovements = movements.filter(m =>
 - `npm run example:goals` - Show available goals
 - `npm run example:user-workouts` - List your workouts
 - `npm run example:workout:id <id>` - Get specific workout
+- `npm run example:workout:name <name>` - Search for workouts by name
 - `npm run example:workout:share <url>` - Get shared workout
 - `npm run example:estimate` - Estimate workout duration
 - `npm run example:create-workout` - Create a new workout

package/dist/{index.js → index.cjs}

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var fs = require('fs');
+var os = require('os');
 var path = require('path');
 
 class TonalClientError extends Error {
@@ -19,9 +20,11 @@ class AuthManager {
         this.idToken = '';
         this.refreshToken = '';
         this.tokenExpiresAt = 0;
-        this.isRefreshing = false;
+        this.authPromise = null;
+        this.refreshPromise = null;
         this.authUrl = 'https://tonal.auth0.com/oauth/token';
         this.clientId = 'ERCyexW-xoVG_Yy3RDe-eV4xsOnRHP6L';
+        this.authTimeout = 30000;
         this.username = username;
         this.password = password;
     }
@@ -29,6 +32,18 @@ class AuthManager {
         if (this.isTokenValid()) {
             return this.idToken;
         }
+        const activeAuth = this.authPromise ?? this.authenticateWithPassword();
+        this.authPromise = activeAuth;
+        try {
+            return await activeAuth;
+        }
+        finally {
+            if (this.authPromise === activeAuth) {
+                this.authPromise = null;
+            }
+        }
+    }
+    async authenticateWithPassword() {
         const response = await fetch(this.authUrl, {
             method: 'POST',
             headers: {
@@ -41,6 +56,7 @@ class AuthManager {
                 grant_type: 'password',
                 scope: 'offline_access',
             }),
+            signal: AbortSignal.timeout(this.authTimeout),
         });
         if (!response.ok) {
             const errorText = await response.text();
@@ -55,69 +71,69 @@ class AuthManager {
         }
         const tokenData = await response.json();
         this.idToken = tokenData.id_token;
-        this.refreshToken = tokenData.refresh_token;
+        this.refreshToken = tokenData.refresh_token ?? '';
         this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
         return this.idToken;
     }
+    invalidateToken() {
+        this.tokenExpiresAt = 0;
+    }
     async getValidToken() {
         if (this.isTokenValid()) {
             return this.idToken;
         }
-        if (this.refreshToken) {
-            if (!this.isRefreshing) {
-                await this.refreshTokens();
-            }
-            else {
-                // Wait for ongoing refresh to complete
-                while (this.isRefreshing) {
-                    await new Promise(resolve => setTimeout(resolve, 100));
-                }
-            }
-            if (this.isTokenValid()) {
-                return this.idToken;
+        if (!this.refreshToken) {
+            return this.authenticate();
+        }
+        const activeRefresh = this.refreshPromise ?? this.refreshTokens();
+        this.refreshPromise = activeRefresh;
+        try {
+            await activeRefresh;
+        }
+        catch {
+            return this.authenticate();
+        }
+        finally {
+            if (this.refreshPromise === activeRefresh) {
+                this.refreshPromise = null;
             }
         }
-        throw new TonalClientError('Token expired and refresh failed. Call authenticate() first.');
+        if (this.isTokenValid()) {
+            return this.idToken;
+        }
+        return this.authenticate();
     }
     isTokenValid() {
         return !!this.idToken && Date.now() < this.tokenExpiresAt - 60000; // 1 minute buffer
     }
     async refreshTokens() {
-        if (this.isRefreshing) {
-            return; // Prevent concurrent refresh attempts
-        }
-        this.isRefreshing = true;
-        try {
-            const response = await fetch(this.authUrl, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify({
-                    client_id: this.clientId,
-                    grant_type: 'refresh_token',
-                    refresh_token: this.refreshToken,
-                }),
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                let errorData;
-                try {
-                    errorData = JSON.parse(errorText);
-                }
-                catch {
-                    errorData = { error: errorText };
-                }
-                throw new TonalClientError(errorData.error_description || errorData.error || 'Token refresh failed', response.status, errorData);
+        const response = await fetch(this.authUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                grant_type: 'refresh_token',
+                refresh_token: this.refreshToken,
+            }),
+            signal: AbortSignal.timeout(this.authTimeout),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorData;
+            try {
+                errorData = JSON.parse(errorText);
             }
-            const tokenData = await response.json();
-            this.idToken = tokenData.id_token;
-            this.refreshToken = tokenData.refresh_token;
-            this.tokenExpiresAt = Date.now() + (tokenData.expires_in * 1000);
-        }
-        finally {
-            this.isRefreshing = false;
+            catch {
+                errorData = { error: errorText };
+            }
+            throw new TonalClientError(errorData.error_description || errorData.error || 'Token refresh failed', response.status, errorData);
         }
+        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);
     }
 }
 
@@ -133,10 +149,11 @@ class HttpClient {
         return this.makeRequestWithRetry(url, options, expectsBody);
     }
     async makeRequest(url, options = {}, expectsBody = true) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
+        let timeoutId;
         try {
             const token = await this.authManager.getValidToken();
+            const controller = new AbortController();
+            timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
             const response = await fetch(url, {
                 ...options,
                 headers: {
@@ -147,6 +164,7 @@ class HttpClient {
                 signal: controller.signal,
             });
             clearTimeout(timeoutId);
+            timeoutId = undefined;
             if (!response.ok) {
                 const errorText = await response.text();
                 let errorData;
@@ -173,28 +191,35 @@ class HttpClient {
             if (error instanceof Error && error.name === 'AbortError') {
                 throw new TonalClientError('Request timeout', undefined, error);
             }
-            throw new TonalClientError('Request failed', undefined, error);
+            throw new TonalClientError(error instanceof Error ? error.message : 'Request failed', undefined, error);
         }
     }
     async makeRequestWithRetry(url, options = {}, expectsBody = true) {
         let lastError;
+        const canRetry = (options.method ?? 'GET').toUpperCase() === 'GET';
         for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
             try {
                 return await this.makeRequest(url, options, expectsBody);
             }
             catch (error) {
                 lastError = error instanceof TonalClientError ? error : new TonalClientError('Unknown error', undefined, error);
-                // If it's an auth error on first attempt, try to refresh token and retry once
-                if (attempt === 1 && lastError.statusCode && (lastError.statusCode === 401 || lastError.statusCode === 403)) {
+                // If it's an auth error on first attempt, invalidate the token and retry once
+                if (attempt === 1 && (lastError.statusCode === 401 || lastError.statusCode === 403)) {
                     try {
-                        await this.authManager.getValidToken(); // This will refresh if needed
-                        continue; // Retry the request with the new token
+                        this.authManager.invalidateToken();
+                        await this.authManager.getValidToken();
+                        continue;
                     }
-                    catch (refreshError) {
+                    catch {
                         // If refresh fails, continue with normal retry logic
                     }
                 }
-                if (attempt === this.maxRetries || (lastError.statusCode && lastError.statusCode < 500)) {
+                const isAbort = lastError.originalError instanceof Error &&
+                    lastError.originalError.name === 'AbortError';
+                if (attempt === this.maxRetries ||
+                    !canRetry ||
+                    (lastError.statusCode !== undefined && lastError.statusCode < 500) ||
+                    (lastError.statusCode === undefined && !isAbort)) {
                     throw lastError;
                 }
                 const delay = Math.pow(2, attempt - 1) * 1000;
@@ -223,6 +248,9 @@ class WorkoutService {
     }
     async getDailyLifts(userInfo, timeZone) {
         const device = userInfo.recentMobileDevice;
+        if (!device) {
+            throw new TonalClientError('Recent mobile device information is unavailable; daily lifts require a mobile device');
+        }
         const userAgent = device.platform === 'ios'
             ? `Tonal/3004226 CFNetwork/3860.100.1 Darwin/${device.osVersion}`
             : `Tonal/${device.appVersion}`;
@@ -259,8 +287,8 @@ class WorkoutService {
         if (!shareUrl?.trim()) {
             throw new TonalClientError('Share URL is required');
         }
-        const urlPattern = /https:\/\/share\.tonal\.com\/workout\/([a-f0-9-]+)/;
-        const match = shareUrl.match(urlPattern);
+        const urlPattern = /^https:\/\/share\.tonal\.com\/workout\/([a-fA-F0-9-]+)(?:[?#]\S*)?$/;
+        const match = shareUrl.trim().match(urlPattern);
         if (!match) {
             throw new TonalClientError('Invalid share URL format. Expected: https://share.tonal.com/workout/{id}');
         }
@@ -305,9 +333,16 @@ class WorkoutService {
         if (!workoutData.sets?.length) {
             throw new TonalClientError('At least one set is required');
         }
+        // Tonal's PUT behavior is unverified. Omitting an absent shortDescription is equivalent
+        // under full-replace semantics and avoids an unintended clear under merge semantics;
+        // an explicit empty string intentionally clears it. `!= null` also covers null, which
+        // sibling response fields are known to return despite their non-optional types.
         const requestBody = {
             id: workoutData.id,
             title: workoutData.title,
+            ...(workoutData.shortDescription != null
+                ? { shortDescription: workoutData.shortDescription }
+                : {}),
             description: workoutData.description || '',
             coachId: workoutData.coachId || '00000000-0000-0000-0000-000000000000',
             sets: workoutData.sets,
@@ -331,10 +366,11 @@ class WorkoutService {
 }
 
 class CacheManager {
-    constructor(cacheDir = '.cache', defaultTTL = 24 * 60 * 60 * 1000) {
+    constructor(cacheDir = process.env.XDG_CACHE_HOME
+        ? path.join(process.env.XDG_CACHE_HOME, 'ts-tonal-client')
+        : path.join(os.homedir(), '.cache', 'ts-tonal-client'), defaultTTL = 24 * 60 * 60 * 1000) {
         this.cacheDir = cacheDir;
         this.defaultTTL = defaultTTL;
-        this.ensureCacheDir();
     }
     ensureCacheDir() {
         if (!fs.existsSync(this.cacheDir)) {
@@ -355,8 +391,7 @@ class CacheManager {
             const cachedAt = new Date(entry.cachedAt).getTime();
             const now = Date.now();
             const age = now - cachedAt;
-            if (age > entry.ttl) {
-                // Cache expired
+            if (!Number.isFinite(cachedAt) || typeof entry.ttl !== 'number' || age > entry.ttl) {
                 return null;
             }
             return entry.data;
@@ -368,12 +403,15 @@ class CacheManager {
     }
     async set(key, data, ttl) {
         const cachePath = this.getCachePath(key);
+        this.ensureCacheDir();
         const entry = {
             cachedAt: new Date().toISOString(),
             ttl: ttl || this.defaultTTL,
             data,
         };
-        fs.writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        const tempPath = `${cachePath}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(entry, null, 2), 'utf-8');
+        fs.renameSync(tempPath, cachePath);
     }
     async invalidate(key) {
         const cachePath = this.getCachePath(key);
@@ -383,7 +421,7 @@ class CacheManager {
     }
     async clear() {
         if (fs.existsSync(this.cacheDir)) {
-            const files = fs.readdirSync(this.cacheDir);
+            const files = fs.readdirSync(this.cacheDir).filter(file => file.endsWith('.json') || file.endsWith('.json.tmp'));
             for (const file of files) {
                 fs.unlinkSync(path.join(this.cacheDir, file));
             }
@@ -392,9 +430,9 @@ class CacheManager {
 }
 
 class MovementService {
-    constructor(httpClient) {
+    constructor(httpClient, cacheDir) {
         this.httpClient = httpClient;
-        this.cacheManager = new CacheManager();
+        this.cacheManager = new CacheManager(cacheDir);
     }
     async getMovements(useCache = true) {
         if (useCache) {
@@ -404,7 +442,12 @@ class MovementService {
             }
         }
         const movements = await this.httpClient.request('/movements');
-        await this.cacheManager.set('movements', movements);
+        try {
+            await this.cacheManager.set('movements', movements);
+        }
+        catch {
+            // Cache writes are best-effort and must not hide a successful API response.
+        }
         return movements;
     }
     async invalidateMovementsCache() {
@@ -508,15 +551,15 @@ class UserService {
 }
 
 class TonalClient {
-    constructor(username, password) {
+    constructor(username, password, cacheDir) {
         this.authManager = new AuthManager(username, password);
         this.httpClient = new HttpClient(this.authManager);
         this.workoutService = new WorkoutService(this.httpClient);
-        this.movementService = new MovementService(this.httpClient);
+        this.movementService = new MovementService(this.httpClient, cacheDir);
         this.userService = new UserService(this.httpClient);
     }
     static async create(credentials) {
-        const client = new TonalClient(credentials.username, credentials.password);
+        const client = new TonalClient(credentials.username, credentials.password, credentials.cacheDir);
         await client.authManager.authenticate();
         return client;
     }
@@ -529,7 +572,32 @@ class TonalClient {
     }
     // User operations
     async getUserInfo() {
-        return this.userService.getUserInfo();
+        if (this.userInfo) {
+            return this.userInfo;
+        }
+        let request = this.userInfoPromise;
+        if (!request) {
+            request = this.userService.getUserInfo();
+            this.userInfoPromise = request;
+        }
+        try {
+            const userInfo = await request;
+            if (this.userInfoPromise === request) {
+                this.userInfo = userInfo;
+                this.userInfoPromise = undefined;
+            }
+            return userInfo;
+        }
+        catch (error) {
+            if (this.userInfoPromise === request) {
+                this.userInfoPromise = undefined;
+            }
+            throw error;
+        }
+    }
+    invalidateUserInfo() {
+        this.userInfo = undefined;
+        this.userInfoPromise = undefined;
     }
     async getGoals() {
         return this.userService.getGoals();

package/dist/index.d.ts

@@ -11,7 +11,7 @@ declare class TonalClientError extends Error {
 interface OAuthTokenResponse {
     access_token: string;
     id_token: string;
-    refresh_token: string;
+    refresh_token?: string;
     scope: string;
     token_type: string;
     expires_in: number;
@@ -55,7 +55,8 @@ interface WorkoutSet {
     workoutId: string;
     blockStart: boolean;
     movementId: string;
-    prescribedReps: number;
+    prescribedReps?: number;
+    prescribedDuration?: number;
     repetition: number;
     repetitionTotal: number;
     blockNumber: number;
@@ -88,7 +89,7 @@ interface TonalWorkout {
     productionCode: string;
     assetId: string;
     coachId: string;
-    sets: WorkoutSet[];
+    sets: WorkoutSet[] | null;
     duration: number;
     publishState: WorkoutPublishState;
     programId: string | null;
@@ -96,7 +97,7 @@ interface TonalWorkout {
     groupIds: string[];
     targetArea: string;
     tags: string[] | null;
-    bodyRegions: MuscleGroup[];
+    bodyRegions: MuscleGroup[] | null;
     goalIds: string[] | null;
     trainingEffectGoals: string[];
     disableModification: boolean;
@@ -112,7 +113,7 @@ interface TonalWorkout {
     recoveryWeight: boolean;
     supportedDevices: string[] | null;
     featureGroupIds: string[] | null;
-    movementIds: string[];
+    movementIds: string[] | null;
     accessories?: string[];
     muscleGroupsForExclusion: MuscleGroup[] | null;
     playbackType: string;
@@ -161,6 +162,7 @@ interface TonalWorkoutCreateRequest {
 interface TonalWorkoutUpdateRequest {
     id: string;
     title: string;
+    shortDescription?: string;
     description?: string;
     coachId: string;
     sets: TonalWorkoutEstimateSet[];
@@ -209,7 +211,7 @@ interface TonalProgram {
     programWorkouts: TonalProgramWorkout[];
     nonComparableWorkouts: boolean;
     mobileFriendly: boolean;
-    supportedDevices: string[];
+    supportedDevices: string[] | null;
     featureGroupIds: string[] | null;
     excludeFromCoachHighlights: boolean;
     trainingEffectGoals: TonalProgramTrainingEffectGoal[];
@@ -614,7 +616,7 @@ interface TonalUserInfo {
     isGuestAccount: boolean;
     isDemoAccount: boolean;
     watchedSafetyVideo: boolean;
-    recentMobileDevice: TonalUserDevice;
+    recentMobileDevice: TonalUserDevice | null;
     emailVerified: boolean;
     username: string;
     workoutsPerWeek: number;
@@ -640,14 +642,18 @@ declare class TonalClient {
     private workoutService;
     private movementService;
     private userService;
+    private userInfo?;
+    private userInfoPromise?;
     private constructor();
     static create(credentials: {
         username: string;
         password: string;
+        cacheDir?: string;
     }): Promise<TonalClient>;
     getMovements(useCache?: boolean): Promise<TonalMovement[]>;
     invalidateMovementsCache(): Promise<void>;
     getUserInfo(): Promise<TonalUserInfo>;
+    invalidateUserInfo(): void;
     getGoals(): Promise<TonalGoal[]>;
     getTrainingEffectGoals(): Promise<TonalTrainingEffectGoalsResponse>;
     getTrainingTypes(): Promise<TonalTrainingType[]>;