v3.0.0: Add typed error handling for session restoration

- BREAKING: restore() now throws typed errors instead of returning null
- Add SessionNotFoundError, RefreshTokenExpiredError, RefreshTokenRevokedError, NetworkError
- Add comprehensive error logging throughout session restoration and token refresh
- Improve error visibility and classification for better debugging

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).
 
+## [3.0.0] - 2025-01-11
+
+### Changed
+
+- **BREAKING**: `restore()` method now throws typed errors instead of returning `null` on failure
+  - Throws `SessionNotFoundError` when session doesn't exist in storage
+  - Throws `RefreshTokenExpiredError` when refresh token has expired
+  - Throws `RefreshTokenRevokedError` when refresh token has been revoked
+  - Throws `NetworkError` for transient network failures
+  - Throws `TokenExchangeError` for other token refresh failures
+  - Throws `SessionError` for unexpected session restoration failures
+
+### Added
+
+- **New Error Types**: Added specific error classes for better error handling and debugging
+  - `SessionNotFoundError`: Session not found in storage
+  - `RefreshTokenExpiredError`: Refresh token has expired
+  - `RefreshTokenRevokedError`: Refresh token has been revoked
+  - `NetworkError`: Network-related failures (retryable)
+- **Detailed Error Logging**: Added comprehensive logging throughout session restoration and token refresh flows
+  - Logs session lookup attempts
+  - Logs token refresh operations
+  - Logs all error conditions with context
+
+### Improved
+
+- **Error Visibility**: Session restoration failures now provide detailed error information instead of silent null returns
+- **Error Classification**: Automatic classification of token exchange errors into specific error types
+- **Debugging**: Enhanced logging makes it easier to diagnose OAuth session issues in production
+
+### Migration Guide
+
+Applications using `restore()` must now handle errors instead of checking for `null`:
+
+**Before (v2.x):**
+```typescript
+const session = await client.restore("session-id");
+if (!session) {
+  // Handle failure - but why did it fail?
+  console.log("Session not found");
+}
+```
+
+**After (v3.x):**
+```typescript
+try {
+  const session = await client.restore("session-id");
+  // Use session
+} catch (error) {
+  if (error instanceof SessionNotFoundError) {
+    // User needs to log in again
+  } else if (error instanceof RefreshTokenExpiredError) {
+    // Refresh token expired - re-authenticate required
+  } else if (error instanceof NetworkError) {
+    // Temporary network issue - retry may help
+  }
+}
+```
+
 ## [2.1.0] - 2025-01-17
 
 ### Added

deno.json

···
 {
   "name": "@tijs/oauth-client-deno",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "AT Protocol OAuth client for Deno - handle-focused alternative to @atproto/oauth-client-node with Web Crypto API compatibility",
   "license": "MIT",
   "repository": {
···
     "exactOptionalPropertyTypes": true,
     "noImplicitOverride": false
   }
-}
+}

src/client.ts

···
   AuthorizationError,
   InvalidHandleError,
   InvalidStateError,
+  NetworkError,
   OAuthError,
+  RefreshTokenExpiredError,
+  RefreshTokenRevokedError,
+  SessionError,
+  SessionNotFoundError,
   TokenExchangeError,
 } from "./errors.ts";
 import { createDefaultResolver, discoverOAuthEndpointsFromPDS } from "./resolvers.ts";
···
       try {
         const sessionData = await this.storage.get<SessionData>(`session:${sessionId}`);
         if (!sessionData) {
-          return null;
+          console.log(`Session not found in storage: ${sessionId}`);
+          throw new SessionNotFoundError(sessionId);
         }
 
         const session = Session.fromJSON(sessionData);
 
         // Auto-refresh if needed
         if (session.isExpired) {
-          const refreshedSession = await this.refresh(session);
-          await this.storage.set(`session:${sessionId}`, refreshedSession.toJSON());
-          return refreshedSession;
+          console.log(`Session expired, attempting token refresh for: ${sessionId}`);
+          try {
+            const refreshedSession = await this.refresh(session);
+            await this.storage.set(`session:${sessionId}`, refreshedSession.toJSON());
+            console.log(`Token refresh successful for: ${sessionId}`);
+            return refreshedSession;
+          } catch (error) {
+            console.error(`Token refresh failed for ${sessionId}:`, error);
+            // Re-throw with proper error classification
+            if (error instanceof TokenExchangeError) {
+              // Check for specific refresh token error responses
+              if (error.errorCode === "invalid_grant") {
+                throw new RefreshTokenExpiredError(error);
+              }
+              throw error;
+            }
+            if (error instanceof NetworkError) {
+              throw error;
+            }
+            // Wrap unknown errors as generic token exchange errors
+            throw new TokenExchangeError(
+              "Token refresh failed",
+              undefined,
+              error as Error,
+            );
+          }
         }
 
         return session;
-      } catch {
-        return null;
+      } catch (error) {
+        // Log all errors for debugging
+        console.error(`Session restoration failed for ${sessionId}:`, error);
+
+        // Re-throw typed errors as-is
+        if (
+          error instanceof SessionNotFoundError ||
+          error instanceof RefreshTokenExpiredError ||
+          error instanceof RefreshTokenRevokedError ||
+          error instanceof NetworkError ||
+          error instanceof TokenExchangeError
+        ) {
+          throw error;
+        }
+
+        // Wrap unexpected errors
+        throw new SessionError(
+          `Failed to restore session: ${sessionId}`,
+          error as Error,
+        );
       } finally {
         // Always cleanup the lock when done
         this.refreshLocks.delete(sessionId);
···
    * ```
    */
   async refresh(session: Session): Promise<Session> {
+    console.log(`Refreshing tokens for session with DID: ${session.did}`);
+
     try {
+      // Discover OAuth endpoints from PDS
       const oauthEndpoints = await discoverOAuthEndpointsFromPDS(session.pdsUrl);
+      console.log(`Token endpoint discovered: ${oauthEndpoints.tokenEndpoint}`);
+
       const refreshedTokens = await this.refreshTokens(
         oauthEndpoints.tokenEndpoint,
         session.refreshToken,
···
 
       // Update session with new tokens
       session.updateTokens(refreshedTokens);
+      console.log(`Token refresh successful for DID: ${session.did}`);
       return session;
     } catch (error) {
+      console.error(`Token refresh failed for DID ${session.did}:`, error);
+
+      // Classify the error based on type
+      if (error instanceof TokenExchangeError) {
+        // Already a TokenExchangeError, check for specific grant errors
+        if (error.errorCode === "invalid_grant") {
+          throw new RefreshTokenExpiredError(error);
+        }
+        throw error;
+      }
+
+      // Check for network-related errors
+      if (error instanceof Error) {
+        const errorMessage = error.message.toLowerCase();
+        if (
+          errorMessage.includes("network") ||
+          errorMessage.includes("timeout") ||
+          errorMessage.includes("connection") ||
+          errorMessage.includes("fetch")
+        ) {
+          throw new NetworkError("Failed to reach token endpoint", error);
+        }
+      }
+
+      // Default to generic token exchange error
       throw new TokenExchangeError("Token refresh failed", undefined, error as Error);
     }
   }

src/errors.ts

···
     this.name = "AuthorizationError";
   }
 }
+
+/**
+ * Thrown when a session cannot be found in storage.
+ *
+ * This error occurs during session restoration when the requested session
+ * ID does not exist in storage, indicating the user needs to re-authenticate.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const session = await client.restore("unknown-session-id");
+ * } catch (error) {
+ *   if (error instanceof SessionNotFoundError) {
+ *     console.log("Session expired or doesn't exist - please log in again");
+ *   }
+ * }
+ * ```
+ */
+export class SessionNotFoundError extends SessionError {
+  /**
+   * Create a new session not found error.
+   *
+   * @param sessionId - The session ID that was not found
+   */
+  constructor(sessionId: string) {
+    super(`Session not found: ${sessionId}`);
+    this.name = "SessionNotFoundError";
+  }
+}
+
+/**
+ * Thrown when a refresh token has expired and cannot be used.
+ *
+ * Refresh tokens have a limited lifetime. This error occurs when attempting
+ * to use an expired refresh token, requiring the user to re-authenticate.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const session = await client.restore("session-id");
+ * } catch (error) {
+ *   if (error instanceof RefreshTokenExpiredError) {
+ *     console.log("Refresh token expired - please log in again");
+ *   }
+ * }
+ * ```
+ */
+export class RefreshTokenExpiredError extends TokenExchangeError {
+  /**
+   * Create a new refresh token expired error.
+   *
+   * @param cause - Optional underlying error from the token endpoint
+   */
+  constructor(cause?: Error) {
+    super("Refresh token has expired", "invalid_grant", cause);
+    this.name = "RefreshTokenExpiredError";
+  }
+}
+
+/**
+ * Thrown when a refresh token has been revoked by the authorization server.
+ *
+ * This error occurs when attempting to use a refresh token that has been
+ * explicitly revoked, requiring the user to re-authenticate.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const session = await client.restore("session-id");
+ * } catch (error) {
+ *   if (error instanceof RefreshTokenRevokedError) {
+ *     console.log("Access has been revoked - please log in again");
+ *   }
+ * }
+ * ```
+ */
+export class RefreshTokenRevokedError extends TokenExchangeError {
+  /**
+   * Create a new refresh token revoked error.
+   *
+   * @param cause - Optional underlying error from the token endpoint
+   */
+  constructor(cause?: Error) {
+    super("Refresh token has been revoked", "invalid_grant", cause);
+    this.name = "RefreshTokenRevokedError";
+  }
+}
+
+/**
+ * Thrown when network operations fail during OAuth operations.
+ *
+ * This error indicates a transient network failure that may be retryable,
+ * such as connection timeouts, DNS failures, or network unavailability.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const session = await client.restore("session-id");
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.log("Network error - retrying may help:", error.message);
+ *   }
+ * }
+ * ```
+ */
+export class NetworkError extends OAuthError {
+  /**
+   * Create a new network error.
+   *
+   * @param message - Error message describing the network failure
+   * @param cause - Optional underlying error from the network operation
+   */
+  constructor(message: string, cause?: Error) {
+    super(`Network error: ${message}`, cause);
+    this.name = "NetworkError";
+  }
+}