@aneuhold/core-ts-api-lib 3.0.39 → 3.0.41

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 🔖 [3.0.41] (2026-07-23)
+
+### ✅ Added
+
+- Added `APIService.setOnAuthExpired()` and `GCloudAPIService.setOnAuthExpired()` to register a callback that fires when a session cannot be recovered from a 401, so consumers can clear stored tokens and prompt re-login.
+- Added the `OnAuthExpiredCallback` and `OnTokensRefreshedCallback` types to `AuthRefreshToken.ts`.
+
+### 🩹 Fixed
+
+- Fixed 401 handling in `GCloudAPIService` so a request with no refresh token, a failed token refresh, or a post-refresh retry that is still a 401 all report expired auth instead of silently returning the unauthorized response.
+
+## 🔖 [3.0.40] (2026-06-19)
+
+### 🏗️ Changed
+
+- Updated `@aneuhold/core-ts-db-lib` to `^5.0.10` and `@aneuhold/core-ts-lib` to `^2.4.6`.
+
 ## 🔖 [3.0.39] (2026-06-12)
 
 ### 🏗️ Changed
@@ -433,6 +450,8 @@ No direct code changes; version bump for compatibility.
 - Updated workflow permissions to allow repository write access
 
 <!-- Link References -->
+[3.0.41]: https://github.com/aneuhold/ts-libs/compare/core-ts-api-lib-v3.0.40...core-ts-api-lib-v3.0.41
+[3.0.40]: https://github.com/aneuhold/ts-libs/compare/core-ts-api-lib-v3.0.39...core-ts-api-lib-v3.0.40
 [3.0.39]: https://github.com/aneuhold/ts-libs/compare/core-ts-api-lib-v3.0.38...core-ts-api-lib-v3.0.39
 [3.0.38]: https://github.com/aneuhold/ts-libs/compare/core-ts-api-lib-v3.0.37...core-ts-api-lib-v3.0.38
 [3.0.37]: https://github.com/aneuhold/ts-libs/compare/core-ts-api-lib-v3.0.36...core-ts-api-lib-v3.0.37

package/lib/services/APIService/API.service.d.ts

@@ -1,6 +1,7 @@
 import type { AdminInput, AdminOutput } from '../../types/Admin.js';
 import type { APIResponse } from '../../types/APIResponse.js';
 import type { AuthDeleteAccountOutput } from '../../types/AuthDeleteAccount.js';
+import type { OnAuthExpiredCallback, OnTokensRefreshedCallback } from '../../types/AuthRefreshToken.js';
 import type { AuthValidateUserInput, AuthValidateUserOutput } from '../../types/AuthValidateUser.js';
 import type { ProjectDashboardInput, ProjectDashboardOutput } from '../../types/project/dashboard/ProjectDashboard.js';
 import type { ProjectWorkoutPrimaryInput, ProjectWorkoutPrimaryOutput } from '../../types/project/workout/ProjectWorkout.js';
@@ -45,7 +46,16 @@ export default class APIService {
      *
      * @param callback - The callback receiving the new accessToken and refreshTokenString.
      */
-    static setOnTokensRefreshed(callback: ((accessToken: string, refreshTokenString: string) => void) | null): void;
+    static setOnTokensRefreshed(callback: OnTokensRefreshedCallback | null): void;
+    /**
+     * Registers a callback that is invoked when the session cannot be recovered
+     * on a 401 (no refresh token, refresh failed, or the retry is still 401). The
+     * stored tokens are cleared before the callback fires, so use this to clear
+     * the consumer's own copy of them and prompt the user to log in again.
+     *
+     * @param callback - The callback invoked when auth has expired.
+     */
+    static setOnAuthExpired(callback: OnAuthExpiredCallback | null): void;
     /**
      * Calls the dashboard API and returns the result.
      *

package/lib/services/APIService/API.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"API.service.d.ts","sourceRoot":"","sources":["../../../src/services/APIService/API.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,+CAA+C,CAAC;AAGvD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B;;;;;;OAMG;WACU,YAAY,CACvB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;OAGG;WACU,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAItD;;;OAGG;WACU,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAI3E;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CACzB,QAAQ,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAC3E,IAAI;IAIP;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;;OAIG;WACU,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAI/E;;;;OAIG;WACU,cAAc,CACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAIpD;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM;IAIjC;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM;CAGlC"}
+{"version":3,"file":"API.service.d.ts","sourceRoot":"","sources":["../../../src/services/APIService/API.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,+CAA+C,CAAC;AAGvD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B;;;;;;OAMG;WACU,YAAY,CACvB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;OAGG;WACU,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAItD;;;OAGG;WACU,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAI3E;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAI7E;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI;IAIrE;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;;OAIG;WACU,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAI/E;;;;OAIG;WACU,cAAc,CACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAIpD;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM;IAIjC;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM;CAGlC"}

package/lib/services/APIService/API.service.js

@@ -53,6 +53,17 @@ export default class APIService {
     static setOnTokensRefreshed(callback) {
         GCloudAPIService.setOnTokensRefreshed(callback);
     }
+    /**
+     * Registers a callback that is invoked when the session cannot be recovered
+     * on a 401 (no refresh token, refresh failed, or the retry is still 401). The
+     * stored tokens are cleared before the callback fires, so use this to clear
+     * the consumer's own copy of them and prompt the user to log in again.
+     *
+     * @param callback - The callback invoked when auth has expired.
+     */
+    static setOnAuthExpired(callback) {
+        GCloudAPIService.setOnAuthExpired(callback);
+    }
     /**
      * Calls the dashboard API and returns the result.
      *

package/lib/services/APIService/API.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"API.service.js","sourceRoot":"","sources":["../../../src/services/APIService/API.service.ts"],"names":[],"mappings":"AAeA,OAAO,gBAAgB,MAAM,0CAA0C,CAAC;AAExE;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CACvB,KAA4B;QAE5B,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM;QACjB,OAAO,gBAAgB,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,aAAa;QACxB,OAAO,gBAAgB,CAAC,iBAAiB,EAAE,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAa;QACjC,gBAAgB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,gBAAgB,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CACzB,QAA4E;QAE5E,gBAAgB,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAC3B,KAA4B;QAE5B,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,KAAiB;QACzC,OAAO,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,KAAiC;QAEjC,OAAO,gBAAgB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,gBAAgB,CAAC,MAAM,EAAE,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAW;QAC1B,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,gBAAgB,CAAC,UAAU,CAAC;IACrC,CAAC;CACF"}
+{"version":3,"file":"API.service.js","sourceRoot":"","sources":["../../../src/services/APIService/API.service.ts"],"names":[],"mappings":"AAmBA,OAAO,gBAAgB,MAAM,0CAA0C,CAAC;AAExE;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CACvB,KAA4B;QAE5B,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM;QACjB,OAAO,gBAAgB,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,aAAa;QACxB,OAAO,gBAAgB,CAAC,iBAAiB,EAAE,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAa;QACjC,gBAAgB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,gBAAgB,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,QAA0C;QACpE,gBAAgB,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAsC;QAC5D,gBAAgB,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAC3B,KAA4B;QAE5B,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,KAAiB;QACzC,OAAO,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,KAAiC;QAEjC,OAAO,gBAAgB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,gBAAgB,CAAC,MAAM,EAAE,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAW;QAC1B,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,gBAAgB,CAAC,UAAU,CAAC;IACrC,CAAC;CACF"}

package/lib/services/APIService/API.service.ts

@@ -1,6 +1,10 @@
 import type { AdminInput, AdminOutput } from '../../types/Admin.js';
 import type { APIResponse } from '../../types/APIResponse.js';
 import type { AuthDeleteAccountOutput } from '../../types/AuthDeleteAccount.js';
+import type {
+  OnAuthExpiredCallback,
+  OnTokensRefreshedCallback
+} from '../../types/AuthRefreshToken.js';
 import type {
   AuthValidateUserInput,
   AuthValidateUserOutput
@@ -73,12 +77,22 @@ export default class APIService {
    *
    * @param callback - The callback receiving the new accessToken and refreshTokenString.
    */
-  static setOnTokensRefreshed(
-    callback: ((accessToken: string, refreshTokenString: string) => void) | null
-  ): void {
+  static setOnTokensRefreshed(callback: OnTokensRefreshedCallback | null): void {
     GCloudAPIService.setOnTokensRefreshed(callback);
   }
 
+  /**
+   * Registers a callback that is invoked when the session cannot be recovered
+   * on a 401 (no refresh token, refresh failed, or the retry is still 401). The
+   * stored tokens are cleared before the callback fires, so use this to clear
+   * the consumer's own copy of them and prompt the user to log in again.
+   *
+   * @param callback - The callback invoked when auth has expired.
+   */
+  static setOnAuthExpired(callback: OnAuthExpiredCallback | null): void {
+    GCloudAPIService.setOnAuthExpired(callback);
+  }
+
   /**
    * Calls the dashboard API and returns the result.
    *

package/lib/services/GCloudAPIService/GCloudAPI.service.d.ts

@@ -1,14 +1,10 @@
 import type { AdminInput, AdminOutput } from '../../types/Admin.js';
 import type { APIResponse } from '../../types/APIResponse.js';
 import type { AuthDeleteAccountOutput } from '../../types/AuthDeleteAccount.js';
+import type { OnAuthExpiredCallback, OnTokensRefreshedCallback } from '../../types/AuthRefreshToken.js';
 import type { AuthValidateUserInput, AuthValidateUserOutput } from '../../types/AuthValidateUser.js';
 import type { ProjectDashboardInput, ProjectDashboardOutput } from '../../types/project/dashboard/ProjectDashboard.js';
 import type { ProjectWorkoutPrimaryInput, ProjectWorkoutPrimaryOutput } from '../../types/project/workout/ProjectWorkout.js';
-/**
- * Callback invoked after tokens are successfully refreshed. The frontend
- * should use this to persist the new tokens (e.g. to localStorage).
- */
-type OnTokensRefreshedCallback = (accessToken: string, refreshTokenString: string) => void;
 /**
  * A service for interacting with the Google Cloud API service for personal projects.
  */
@@ -48,6 +44,15 @@ export default class GCloudAPIService {
      * @param callback - The callback receiving the new accessToken and refreshTokenString.
      */
     static setOnTokensRefreshed(callback: OnTokensRefreshedCallback | null): void;
+    /**
+     * Registers a callback that is invoked when the session cannot be recovered
+     * on a 401 (no refresh token, refresh failed, or the post-refresh retry is
+     * still 401). The stored tokens are cleared before the callback fires, so use
+     * this to clear the consumer's own copy of them and prompt re-login.
+     *
+     * @param callback - The callback invoked when auth has expired.
+     */
+    static setOnAuthExpired(callback: OnAuthExpiredCallback | null): void;
     /**
      * Calls the auth validateUser endpoint.
      *
@@ -83,5 +88,4 @@ export default class GCloudAPIService {
      */
     static projectWorkout(input: ProjectWorkoutPrimaryInput): Promise<APIResponse<ProjectWorkoutPrimaryOutput>>;
 }
-export {};
 //# sourceMappingURL=GCloudAPI.service.d.ts.map

package/lib/services/GCloudAPIService/GCloudAPI.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GCloudAPI.service.d.ts","sourceRoot":"","sources":["../../../src/services/GCloudAPIService/GCloudAPI.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,+CAA+C,CAAC;AAEvD;;;GAGG;AACH,KAAK,yBAAyB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;AAE3F;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;;IACnC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAmC;IAcrE;;;;OAIG;IACH,MAAM,CAAC,MAAM,IAAI,MAAM;IAIvB;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAI7E;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;OAGG;WACU,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAa1D;;;OAGG;WACU,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAO/E;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;;OAIG;WACU,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAIxE;;;;OAIG;WACU,cAAc,CACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;CA6IrD"}
+{"version":3,"file":"GCloudAPI.service.d.ts","sourceRoot":"","sources":["../../../src/services/GCloudAPIService/GCloudAPI.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAGV,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,+CAA+C,CAAC;AAEvD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;;IACnC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAmC;IAkBrE;;;;OAIG;IACH,MAAM,CAAC,MAAM,IAAI,MAAM;IAIvB;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAI7E;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI;IAIrE;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;OAGG;WACU,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAa1D;;;OAGG;WACU,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAO/E;;;;OAIG;WACU,gBAAgB,CAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAI/C;;;;OAIG;WACU,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAIxE;;;;OAIG;WACU,cAAc,CACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;CAyKrD"}

package/lib/services/GCloudAPIService/GCloudAPI.service.js

@@ -12,6 +12,8 @@ export default class GCloudAPIService {
     static #accessToken;
     static #refreshTokenString;
     static #onTokensRefreshed = null;
+    static #onAuthExpired = null;
+    static #refreshPromise = null;
     /**
      * Gets the current URL of the Google Cloud API.
      *
@@ -55,6 +57,17 @@ export default class GCloudAPIService {
     static setOnTokensRefreshed(callback) {
         this.#onTokensRefreshed = callback;
     }
+    /**
+     * Registers a callback that is invoked when the session cannot be recovered
+     * on a 401 (no refresh token, refresh failed, or the post-refresh retry is
+     * still 401). The stored tokens are cleared before the callback fires, so use
+     * this to clear the consumer's own copy of them and prompt re-login.
+     *
+     * @param callback - The callback invoked when auth has expired.
+     */
+    static setOnAuthExpired(callback) {
+        this.#onAuthExpired = callback;
+    }
     /**
      * Calls the auth validateUser endpoint.
      *
@@ -110,28 +123,55 @@ export default class GCloudAPIService {
     /**
      * Makes a call to the API. On a 401 response, automatically attempts to
      * refresh the access token using the stored refresh token. If refresh
-     * succeeds, the original request is retried once.
+     * succeeds, the original request is retried once. When the session cannot be
+     * recovered, the stored tokens are cleared and the {@link #onAuthExpired}
+     * callback fires.
      *
      * @param urlPath - The path to the endpoint.
      * @param input - The input to the endpoint.
      */
     static async #call(urlPath, input) {
-        const { response, decoded } = await this.#fetchAndDecode(urlPath, input);
-        if (response.status === 401 && this.#refreshTokenString) {
-            const refreshed = await this.#tryRefreshTokens();
-            if (refreshed) {
-                const retry = await this.#fetchAndDecode(urlPath, input);
-                return retry.decoded;
-            }
+        let { response, decoded } = await this.#fetchAndDecode(urlPath, input);
+        // On a 401, try once to recover by refreshing the tokens and retrying.
+        // #tryRefreshTokens returns false when there is no refresh token to use.
+        if (response.status === 401 && (await this.#tryRefreshTokens())) {
+            // Fancy destructure into pre-existing variables
+            ({ response, decoded } = await this.#fetchAndDecode(urlPath, input));
+        }
+        // Still a 401 after any recovery attempt means the session cannot be
+        // recovered, so drop the dead tokens and notify the frontend to prompt
+        // re-login.
+        if (response.status === 401) {
+            this.#accessToken = undefined;
+            this.#refreshTokenString = undefined;
+            this.#onAuthExpired?.();
         }
         return decoded;
     }
     /**
-     * Attempts to refresh the access token using the stored refresh token.
-     * On success, updates the stored tokens and notifies via the
-     * {@link #onTokensRefreshed} callback.
+     * Attempts to refresh the access token, sharing one in-flight refresh across
+     * concurrent callers. Refresh tokens rotate server-side, so parallel
+     * refreshes sent with the same token would invalidate each other and drop the
+     * session.
      */
     static async #tryRefreshTokens() {
+        // Set the refreshPromise only if it is currently null, otherwise we continue.
+        this.#refreshPromise ??= this.#performTokenRefresh();
+        try {
+            return await this.#refreshPromise;
+        }
+        finally {
+            // Cleared once settled so the next 401 starts a fresh attempt rather than
+            // reusing a stale result.
+            this.#refreshPromise = null;
+        }
+    }
+    /**
+     * Exchanges the stored refresh token for a new token pair. On success,
+     * updates the stored tokens and notifies via the {@link #onTokensRefreshed}
+     * callback.
+     */
+    static async #performTokenRefresh() {
         if (!this.#refreshTokenString) {
             return false;
         }

package/lib/services/GCloudAPIService/GCloudAPI.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"GCloudAPI.service.js","sourceRoot":"","sources":["../../../src/services/GCloudAPIService/GCloudAPI.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GCloudAPI.service.js","sourceRoot":"","sources":["../../../src/services/GCloudAPIService/GCloudAPI.service.ts"],"names":[],"mappings":"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"}

package/lib/services/GCloudAPIService/GCloudAPI.service.ts

@@ -7,7 +7,9 @@ import type {
 } from '../../types/AuthDeleteAccount.js';
 import type {
   AuthRefreshTokenInput,
-  AuthRefreshTokenOutput
+  AuthRefreshTokenOutput,
+  OnAuthExpiredCallback,
+  OnTokensRefreshedCallback
 } from '../../types/AuthRefreshToken.js';
 import type {
   AuthValidateUserInput,
@@ -22,12 +24,6 @@ import type {
   ProjectWorkoutPrimaryOutput
 } from '../../types/project/workout/ProjectWorkout.js';
 
-/**
- * Callback invoked after tokens are successfully refreshed. The frontend
- * should use this to persist the new tokens (e.g. to localStorage).
- */
-type OnTokensRefreshedCallback = (accessToken: string, refreshTokenString: string) => void;
-
 /**
  * A service for interacting with the Google Cloud API service for personal projects.
  */
@@ -46,6 +42,10 @@ export default class GCloudAPIService {
 
   static #onTokensRefreshed: OnTokensRefreshedCallback | null = null;
 
+  static #onAuthExpired: OnAuthExpiredCallback | null = null;
+
+  static #refreshPromise: Promise<boolean> | null = null;
+
   /**
    * Gets the current URL of the Google Cloud API.
    *
@@ -94,6 +94,18 @@ export default class GCloudAPIService {
     this.#onTokensRefreshed = callback;
   }
 
+  /**
+   * Registers a callback that is invoked when the session cannot be recovered
+   * on a 401 (no refresh token, refresh failed, or the post-refresh retry is
+   * still 401). The stored tokens are cleared before the callback fires, so use
+   * this to clear the consumer's own copy of them and prompt re-login.
+   *
+   * @param callback - The callback invoked when auth has expired.
+   */
+  static setOnAuthExpired(callback: OnAuthExpiredCallback | null): void {
+    this.#onAuthExpired = callback;
+  }
+
   /**
    * Calls the auth validateUser endpoint.
    *
@@ -170,7 +182,9 @@ export default class GCloudAPIService {
   /**
    * Makes a call to the API. On a 401 response, automatically attempts to
    * refresh the access token using the stored refresh token. If refresh
-   * succeeds, the original request is retried once.
+   * succeeds, the original request is retried once. When the session cannot be
+   * recovered, the stored tokens are cleared and the {@link #onAuthExpired}
+   * callback fires.
    *
    * @param urlPath - The path to the endpoint.
    * @param input - The input to the endpoint.
@@ -179,25 +193,51 @@ export default class GCloudAPIService {
     urlPath: string,
     input: TInput
   ): Promise<APIResponse<TOutput>> {
-    const { response, decoded } = await this.#fetchAndDecode<TInput, TOutput>(urlPath, input);
+    let { response, decoded } = await this.#fetchAndDecode<TInput, TOutput>(urlPath, input);
 
-    if (response.status === 401 && this.#refreshTokenString) {
-      const refreshed = await this.#tryRefreshTokens();
-      if (refreshed) {
-        const retry = await this.#fetchAndDecode<TInput, TOutput>(urlPath, input);
-        return retry.decoded;
-      }
+    // On a 401, try once to recover by refreshing the tokens and retrying.
+    // #tryRefreshTokens returns false when there is no refresh token to use.
+    if (response.status === 401 && (await this.#tryRefreshTokens())) {
+      // Fancy destructure into pre-existing variables
+      ({ response, decoded } = await this.#fetchAndDecode<TInput, TOutput>(urlPath, input));
+    }
+
+    // Still a 401 after any recovery attempt means the session cannot be
+    // recovered, so drop the dead tokens and notify the frontend to prompt
+    // re-login.
+    if (response.status === 401) {
+      this.#accessToken = undefined;
+      this.#refreshTokenString = undefined;
+      this.#onAuthExpired?.();
     }
 
     return decoded;
   }
 
   /**
-   * Attempts to refresh the access token using the stored refresh token.
-   * On success, updates the stored tokens and notifies via the
-   * {@link #onTokensRefreshed} callback.
+   * Attempts to refresh the access token, sharing one in-flight refresh across
+   * concurrent callers. Refresh tokens rotate server-side, so parallel
+   * refreshes sent with the same token would invalidate each other and drop the
+   * session.
    */
   static async #tryRefreshTokens(): Promise<boolean> {
+    // Set the refreshPromise only if it is currently null, otherwise we continue.
+    this.#refreshPromise ??= this.#performTokenRefresh();
+    try {
+      return await this.#refreshPromise;
+    } finally {
+      // Cleared once settled so the next 401 starts a fresh attempt rather than
+      // reusing a stale result.
+      this.#refreshPromise = null;
+    }
+  }
+
+  /**
+   * Exchanges the stored refresh token for a new token pair. On success,
+   * updates the stored tokens and notifies via the {@link #onTokensRefreshed}
+   * callback.
+   */
+  static async #performTokenRefresh(): Promise<boolean> {
     if (!this.#refreshTokenString) {
       return false;
     }

package/lib/types/AuthRefreshToken.d.ts

@@ -14,4 +14,13 @@ export interface AuthRefreshTokenOutput {
     /** New raw refresh token string (rotation — old one is deleted). */
     refreshTokenString: string;
 }
+/**
+ * Callback invoked after tokens are successfully refreshed.
+ */
+export type OnTokensRefreshedCallback = (accessToken: string, refreshTokenString: string) => void;
+/**
+ * Callback invoked when a session can no longer be recovered because the access
+ * token is expired and the refresh token is missing or invalid.
+ */
+export type OnAuthExpiredCallback = () => void;
 //# sourceMappingURL=AuthRefreshToken.d.ts.map

package/lib/types/AuthRefreshToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthRefreshToken.d.ts","sourceRoot":"","sources":["../../src/types/AuthRefreshToken.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"AuthRefreshToken.d.ts","sourceRoot":"","sources":["../../src/types/AuthRefreshToken.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;AAElG;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,IAAI,CAAC"}

package/lib/types/AuthRefreshToken.ts

@@ -15,3 +15,14 @@ export interface AuthRefreshTokenOutput {
   /** New raw refresh token string (rotation — old one is deleted). */
   refreshTokenString: string;
 }
+
+/**
+ * Callback invoked after tokens are successfully refreshed.
+ */
+export type OnTokensRefreshedCallback = (accessToken: string, refreshTokenString: string) => void;
+
+/**
+ * Callback invoked when a session can no longer be recovered because the access
+ * token is expired and the refresh token is missing or invalid.
+ */
+export type OnAuthExpiredCallback = () => void;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@aneuhold/core-ts-api-lib",
   "author": "Anton G. Neuhold Jr.",
   "license": "MIT",
-  "version": "3.0.39",
+  "version": "3.0.41",
   "description": "A library for interacting with the backend and defining the backend API for personal projects.",
   "packageManager": "pnpm@10.25.0",
   "type": "module",
@@ -72,12 +72,12 @@
     "TypeScript"
   ],
   "dependencies": {
-    "@aneuhold/core-ts-db-lib": "^5.0.9",
-    "@aneuhold/core-ts-lib": "^2.4.5",
+    "@aneuhold/core-ts-db-lib": "^5.0.10",
+    "@aneuhold/core-ts-lib": "^2.4.6",
     "bson": "^7.0.0"
   },
   "devDependencies": {
-    "@aneuhold/local-npm-registry": "^0.2.33",
+    "@aneuhold/local-npm-registry": "^0.2.34",
     "@aneuhold/main-scripts": "^2.9.5",
     "@types/node": "^25.0.2",
     "eslint": "^9.39.2",