fix: handle token refresh race condition in serverless environments

When concurrent requests trigger token refresh simultaneously across
different isolates (e.g., Val Town, Deno Deploy), the second request
would fail with 'Refresh token replayed' error.

Now gracefully handles this by:
- Detecting the 'replayed' error from OAuth servers
- Waiting briefly for the other process to save
- Re-reading the session from storage to get fresh tokens

Also adds:
- errorDescription field on TokenExchangeError
- Proper JSON parsing of OAuth error responses

CHANGELOG.md

···
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.2] - 2025-11-27
+
+### Fixed
+
+- **Token refresh race condition in serverless environments**: When concurrent requests
+  trigger token refresh simultaneously across different isolates (e.g., Val Town, Deno Deploy),
+  the second request would fail with "Refresh token replayed" error. Now gracefully handles
+  this by re-reading the session from storage after detecting the replay error.
+
+### Added
+
+- **`errorDescription` field on `TokenExchangeError`**: OAuth `error_description` is now
+  exposed as a separate field for better error handling and logging
+- **OAuth error response parsing**: Token exchange errors now properly parse JSON error
+  responses from OAuth servers, extracting `error` and `error_description` fields
+
+### Improved
+
+- Better error classification for token refresh failures
+- More informative error messages when OAuth operations fail
+
 ## [4.0.1] - 2025-01-15
 
 ### Fixed

README.md

···
 ## See Also
 
 - **[@tijs/atproto-oauth-hono](https://jsr.io/@tijs/atproto-oauth-hono)**: High-level Hono integration built on top of this client.
-

deno.json

···
 {
   "name": "@tijs/oauth-client-deno",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "AT Protocol OAuth client for Deno - handle-focused alternative to @atproto/oauth-client-node with Web Crypto API compatibility",
   "license": "MIT",
   "repository": {

src/client.ts

···
       } catch (error) {
         this.logger.error("Token refresh failed", { did, error });
 
+        // Check for token replay error (concurrent refresh in another isolate)
+        if (this.isTokenReplayedError(error)) {
+          this.logger.info("Token replay detected, fetching updated session from storage", { did });
+
+          // Wait briefly for the other process to save
+          await this.sleep(200);
+
+          // Re-read session from storage (the other process should have saved new tokens)
+          const updatedSessionData = await this.storage.get<SessionData>(`session:${did}`);
+          if (updatedSessionData) {
+            const updatedSession = Session.fromJSON(updatedSessionData);
+            if (!updatedSession.isExpired) {
+              this.logger.info("Retrieved refreshed session from storage after replay detection", {
+                did,
+              });
+              return updatedSession;
+            }
+          }
+
+          // Could not recover - throw the original error
+          this.logger.error("Could not recover from token replay - no valid session in storage", {
+            did,
+          });
+        }
+
         // Classify the error based on type
         if (error instanceof TokenExchangeError) {
           // Already a TokenExchangeError, check for specific grant errors
···
 
   private extractAuthServer(authorizationEndpoint: string): string {
     return authorizationEndpoint.replace(/\/oauth\/authorize$/, "");
+  }
+
+  /**
+   * Check if an error is a token replay error from concurrent refresh attempts.
+   * This happens in serverless environments where multiple isolates may try to
+   * refresh the same token simultaneously.
+   */
+  private isTokenReplayedError(error: unknown): boolean {
+    if (error instanceof TokenExchangeError) {
+      if (error.errorCode !== "invalid_grant") return false;
+      // Check both the message and errorDescription for "replayed"
+      const message = error.message.toLowerCase();
+      const description = error.errorDescription?.toLowerCase() || "";
+      return message.includes("replayed") || description.includes("replayed");
+    }
+    return false;
+  }
+
+  /**
+   * Sleep for a specified duration.
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
   private async pushAuthorizationRequest(

src/errors.ts

···
  *     if (error.errorCode) {
  *       console.log("OAuth error code:", error.errorCode);
  *     }
+ *     if (error.errorDescription) {
+ *       console.log("OAuth error description:", error.errorDescription);
+ *     }
  *   }
  * }
  * ```
···
 export class TokenExchangeError extends OAuthError {
   /** OAuth error code from the server (e.g., "invalid_grant") */
   public readonly errorCode?: string;
+
+  /** OAuth error_description from the server (e.g., "Refresh token replayed") */
+  public readonly errorDescription?: string;
 
   /**
    * Create a new token exchange error.
···
    * @param message - Error message describing what went wrong
    * @param errorCode - Optional OAuth error code from the server
    * @param cause - Optional underlying error that caused the token exchange failure
+   * @param errorDescription - Optional OAuth error_description from the server
    */
-  constructor(message: string, errorCode?: string, cause?: Error) {
+  constructor(message: string, errorCode?: string, cause?: Error, errorDescription?: string) {
     super(`Token exchange failed: ${message}`, cause);
     this.name = "TokenExchangeError";
     if (errorCode) {
       this.errorCode = errorCode;
+    }
+    if (errorDescription) {
+      this.errorDescription = errorDescription;
     }
   }
 }

src/token-exchange.ts

···
   );
 
   if (!response.ok) {
-    const error = await response.text();
-    logger.error("Token exchange failed", { status: response.status, error });
-    throw new TokenExchangeError(error);
+    const errorText = await response.text();
+    logger.error("Token exchange failed", { status: response.status, error: errorText });
+
+    // Try to parse OAuth error response (JSON format)
+    try {
+      const errorJson = JSON.parse(errorText);
+      throw new TokenExchangeError(
+        errorJson.error_description || errorJson.error || errorText,
+        errorJson.error, // e.g., "invalid_client", "invalid_grant"
+        undefined, // cause
+        errorJson.error_description, // errorDescription
+      );
+    } catch (parseError) {
+      if (parseError instanceof TokenExchangeError) throw parseError;
+      throw new TokenExchangeError(errorText);
+    }
   }
 
   logger.info("Token exchange successful");
···
     );
 
     if (!response.ok) {
-      const error = await response.text();
-      logger.error("Token refresh failed", { status: response.status, error });
-      throw new TokenExchangeError(`Token refresh failed: ${error}`);
+      const errorText = await response.text();
+      logger.error("Token refresh failed", { status: response.status, error: errorText });
+
+      // Try to parse OAuth error response (JSON format)
+      try {
+        const errorJson = JSON.parse(errorText);
+        throw new TokenExchangeError(
+          `Token refresh failed: ${errorJson.error_description || errorJson.error || errorText}`,
+          errorJson.error, // e.g., "invalid_grant"
+          undefined, // cause
+          errorJson.error_description, // errorDescription
+        );
+      } catch (parseError) {
+        // If it's already our error, re-throw it
+        if (parseError instanceof TokenExchangeError) throw parseError;
+        // Otherwise, throw with raw text
+        throw new TokenExchangeError(`Token refresh failed: ${errorText}`);
+      }
     }
 
     const tokens = await response.json();