@dlwiest/ts-tonal-client 0.3.1 → 0.4.0

package/README.md

@@ -441,6 +441,48 @@ if (volumeScores && volumeScores.length >= 2) {
 }
 ```
 
+### Strength Scores
+
+Tonal's headline Strength Score, per body region. This is a different metric from the weekly
+`Functional Strength Score` returned by `getGoalMetrics()` — that one measures goal progress
+for a week, this one is the score the Tonal app shows you.
+
+```typescript
+// Current score for each region
+const scores = await client.getCurrentStrengthScores()
+for (const score of scores) {
+  // The Overall row is synthesized: bodyRegionDisplay is empty, familyActivity is absent,
+  // workoutActivityId is an all-zero uuid, and updatedAt is a zero date. Fall back to
+  // strengthBodyRegion for a label, and do not render its updatedAt.
+  const label = score.bodyRegionDisplay || score.strengthBodyRegion
+  console.log(`${label}: ${score.score}`)
+}
+// One row per region: Upper Body, Core, Lower Body, Overall
+
+// Per-workout history. Defaults to the whole account.
+const history = await client.getStrengthScoreHistory()
+console.log(`${history.length} scored activities`)
+console.log(history[0]) // { upper, lower, core, overall, activityTime, workoutActivityId, ... }
+```
+
+**`days` is a calendar-day lookback, not a row count.** The underlying API parameter is named
+`limit`, but it selects a time window: a value smaller than the gap since your last workout
+returns an **empty array**, not "no results found". Passing `30` on an account last used
+90 days ago yields nothing.
+
+```typescript
+await client.getStrengthScoreHistory(365)   // activities in the last 365 days
+await client.getStrengthScoreHistory('all') // explicit; same as the default
+```
+
+The default `'all'` derives the window from your account creation date, so it stays correct as
+the account ages rather than relying on a large magic number. If `createdAt` is missing,
+unparseable, or in the future it throws `TonalClientError` rather than guessing — pass an
+explicit `days` in that case.
+
+Each history entry carries `workoutActivityId`, which makes this the only complete way to
+enumerate an account's activities: the list endpoints are capped at 50 records each.
+
 ### Movements
 
 ```typescript

package/dist/index.cjs

@@ -518,6 +518,16 @@ class UserService {
     async getCurrentStreak(userId) {
         return this.httpClient.request(`/users/${userId}/streaks/current`);
     }
+    async getCurrentStrengthScores(userId) {
+        return this.httpClient.request(`/users/${userId}/strength-scores/current`);
+    }
+    async getStrengthScoreHistory(userId, days) {
+        if (!Number.isSafeInteger(days) || days <= 0) {
+            throw new TonalClientError('Strength score history days must be a positive safe integer');
+        }
+        // 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 getActivitySummaries(userId) {
         return this.httpClient.request(`/users/${userId}/activity-summaries`);
     }
@@ -623,6 +633,34 @@ class TonalClient {
         const userInfo = await this.getUserInfo();
         return this.userService.getCurrentStreak(userInfo.id);
     }
+    async getCurrentStrengthScores() {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getCurrentStrengthScores(userInfo.id);
+    }
+    async getStrengthScoreHistory(days = 'all') {
+        if (days !== 'all' && (!Number.isSafeInteger(days) || days <= 0)) {
+            throw new TonalClientError('Strength score history days must be a positive safe integer');
+        }
+        const userInfo = await this.getUserInfo();
+        let lookbackDays;
+        if (days === 'all') {
+            const createdAt = userInfo.createdAt;
+            const createdAtMs = typeof createdAt === 'string' ? Date.parse(createdAt) : Number.NaN;
+            const now = Date.now();
+            if (!Number.isFinite(createdAtMs) || createdAtMs > now) {
+                throw new TonalClientError('Cannot derive all strength score history from user createdAt; pass explicit days');
+            }
+            // +2 covers the account-creation calendar day and the server's midnight-boundary
+            // ambiguity; over-fetching before account creation is harmless. The Math.max floor is
+            // belt-and-braces only -- the future-createdAt rejection above already guarantees a
+            // non-negative difference, so this expression is always >= 2.
+            lookbackDays = Math.max(1, Math.ceil((now - createdAtMs) / 86400000) + 2);
+        }
+        else {
+            lookbackDays = days;
+        }
+        return this.userService.getStrengthScoreHistory(userInfo.id, lookbackDays);
+    }
     async getActivitySummaries() {
         const userInfo = await this.getUserInfo();
         return this.userService.getActivitySummaries(userInfo.id);

package/dist/index.d.ts

@@ -373,6 +373,30 @@ interface TonalCurrentStreak {
     maxStreakStartDate: string;
     updatedByActivityId: string;
 }
+type TonalStrengthBodyRegion = 'Upper Body' | 'Core' | 'Lower Body' | 'Overall' | string;
+interface TonalStrengthScore {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    userId: string;
+    workoutActivityId: string;
+    strengthBodyRegion: TonalStrengthBodyRegion;
+    bodyRegionDisplay: string;
+    score: number;
+    current: boolean;
+    familyActivity?: unknown[];
+}
+interface TonalStrengthScoreHistoryEntry {
+    id: string;
+    userId: string;
+    workoutActivityId: string;
+    upper: number;
+    lower: number;
+    core: number;
+    overall: number;
+    activityTime: string;
+}
+type TonalStrengthScoreHistoryLookback = number | 'all';
 interface TonalActivitySummary {
     id: string;
     deletedAt: string | null;
@@ -661,6 +685,8 @@ declare class TonalClient {
     getUserSettings(): Promise<TonalUserSettings>;
     getDailyMetrics(days?: number): Promise<TonalDailyMetrics[]>;
     getCurrentStreak(): Promise<TonalCurrentStreak>;
+    getCurrentStrengthScores(): Promise<TonalStrengthScore[]>;
+    getStrengthScoreHistory(days?: TonalStrengthScoreHistoryLookback): Promise<TonalStrengthScoreHistoryEntry[]>;
     getActivitySummaries(): Promise<TonalActivitySummary[]>;
     getUserStatistics(): Promise<TonalUserStatistics>;
     getAchievementStats(): Promise<TonalAchievementStats>;
@@ -680,4 +706,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, 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, TonalWorkoutCreateRequest, TonalWorkoutEstimateResponse, TonalWorkoutEstimateSet, TonalWorkoutSummaryData, TonalWorkoutUpdateRequest, WorkoutPublishState, WorkoutSet, TonalClient as default };

package/dist/index.esm.js

@@ -514,6 +514,16 @@ class UserService {
     async getCurrentStreak(userId) {
         return this.httpClient.request(`/users/${userId}/streaks/current`);
     }
+    async getCurrentStrengthScores(userId) {
+        return this.httpClient.request(`/users/${userId}/strength-scores/current`);
+    }
+    async getStrengthScoreHistory(userId, days) {
+        if (!Number.isSafeInteger(days) || days <= 0) {
+            throw new TonalClientError('Strength score history days must be a positive safe integer');
+        }
+        // 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 getActivitySummaries(userId) {
         return this.httpClient.request(`/users/${userId}/activity-summaries`);
     }
@@ -619,6 +629,34 @@ class TonalClient {
         const userInfo = await this.getUserInfo();
         return this.userService.getCurrentStreak(userInfo.id);
     }
+    async getCurrentStrengthScores() {
+        const userInfo = await this.getUserInfo();
+        return this.userService.getCurrentStrengthScores(userInfo.id);
+    }
+    async getStrengthScoreHistory(days = 'all') {
+        if (days !== 'all' && (!Number.isSafeInteger(days) || days <= 0)) {
+            throw new TonalClientError('Strength score history days must be a positive safe integer');
+        }
+        const userInfo = await this.getUserInfo();
+        let lookbackDays;
+        if (days === 'all') {
+            const createdAt = userInfo.createdAt;
+            const createdAtMs = typeof createdAt === 'string' ? Date.parse(createdAt) : Number.NaN;
+            const now = Date.now();
+            if (!Number.isFinite(createdAtMs) || createdAtMs > now) {
+                throw new TonalClientError('Cannot derive all strength score history from user createdAt; pass explicit days');
+            }
+            // +2 covers the account-creation calendar day and the server's midnight-boundary
+            // ambiguity; over-fetching before account creation is harmless. The Math.max floor is
+            // belt-and-braces only -- the future-createdAt rejection above already guarantees a
+            // non-negative difference, so this expression is always >= 2.
+            lookbackDays = Math.max(1, Math.ceil((now - createdAtMs) / 86400000) + 2);
+        }
+        else {
+            lookbackDays = days;
+        }
+        return this.userService.getStrengthScoreHistory(userInfo.id, lookbackDays);
+    }
     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.3.1",
+  "version": "0.4.0",
   "description": "TypeScript client for Tonal API",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",