bitcoincash-oauth-client 0.1.1 → 0.2.2

package/dist/index.mjs

@@ -5,11 +5,103 @@
  */
 import { instantiateSecp256k1, generatePrivateKey, CashAddressNetworkPrefix, encodeCashAddress, CashAddressType } from '@bitauth/libauth';
 
+/**
+ * Custom error classes for Bitcoin Cash OAuth Client
+ * Provides specific error types for better error handling
+ */
+
+/**
+ * Base OAuth Error class
+ */
+class OAuthError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} code - Error code
+   * @param {number|null} statusCode - HTTP status code (if applicable)
+   */
+  constructor(message, code, statusCode = null) {
+    super(message);
+    this.name = 'OAuthError';
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Network-related errors (connection issues, timeouts, etc.)
+ */
+class NetworkError extends OAuthError {
+  /**
+   * @param {string} message - Error message
+   * @param {Error|null} originalError - Original error that caused this
+   */
+  constructor(message, originalError = null) {
+    super(message, 'NETWORK_ERROR');
+    this.name = 'NetworkError';
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Authentication-related errors (invalid credentials, unauthorized access)
+ */
+class AuthenticationError extends OAuthError {
+  /**
+   * @param {string} message - Error message
+   * @param {number} statusCode - HTTP status code
+   * @param {string} code - Error code
+   */
+  constructor(message, statusCode, code = 'AUTHENTICATION_ERROR') {
+    super(message, code, statusCode);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Token has expired
+ */
+class TokenExpiredError extends AuthenticationError {
+  /**
+   * @param {string} [message='Token has expired'] - Error message
+   */
+  constructor(message = 'Token has expired') {
+    super(message, 401, 'TOKEN_EXPIRED');
+    this.name = 'TokenExpiredError';
+  }
+}
+
+/**
+ * User not found error
+ */
+class UserNotFoundError extends AuthenticationError {
+  /**
+   * @param {string} [message='User not found'] - Error message
+   */
+  constructor(message = 'User not found') {
+    super(message, 404, 'USER_NOT_FOUND');
+    this.name = 'UserNotFoundError';
+  }
+}
+
+/**
+ * Invalid token error
+ */
+class InvalidTokenError extends AuthenticationError {
+  /**
+   * @param {string} [message='Invalid token'] - Error message
+   */
+  constructor(message = 'Invalid token') {
+    super(message, 401, 'INVALID_TOKEN');
+    this.name = 'InvalidTokenError';
+  }
+}
+
 /**
  * Environment utilities for cross-platform crypto operations
  * Handles browser vs Node.js differences
  */
 
+
 let cryptoModule = null;
 
 /**
@@ -32,6 +124,25 @@ async function getNodeCrypto() {
   }
 }
 
+/**
+ * Check if running in Capacitor environment
+ * @returns {boolean}
+ */
+function isCapacitor() {
+  return typeof window !== 'undefined' && 
+         window.Capacitor !== undefined &&
+         window.Capacitor.isNative === true;
+}
+
+/**
+ * Check if running in hybrid app environment (Capacitor, Cordova, etc.)
+ * @returns {boolean}
+ */
+function isHybridApp() {
+  return isCapacitor() || 
+         (typeof window !== 'undefined' && window.cordova !== undefined);
+}
+
 /**
  * Generate secure random bytes (cross-platform)
  * @param {number} length - Number of bytes to generate
@@ -90,15 +201,45 @@ async function ripemd160(data) {
 
 /**
  * Get fetch implementation for current environment
+ * @param {Function|null} userProvidedFetch - User-provided fetch implementation
  * @returns {Function} Fetch implementation
+ * @throws {NetworkError} If no fetch implementation is available
  */
-function getFetch() {
+function getFetch(userProvidedFetch = null) {
+  // Always prefer user-provided fetch
+  if (userProvidedFetch) {
+    return userProvidedFetch;
+  }
+  
+  // Check if we're in a Capacitor environment
+  if (isCapacitor()) {
+    throw new NetworkError(
+      'Capacitor environment detected. ' +
+      'Please provide a custom fetch implementation via options.fetch. ' +
+      'Example: new BitcoinCashOAuthClient({ fetch: axiosFetch })'
+    );
+  }
+  
+  // Check for hybrid app environments (Cordova, etc.)
+  if (isHybridApp() && !isCapacitor()) {
+    console.warn(
+      '[bitcoincash-oauth-client] Hybrid app environment detected. ' +
+      'Consider providing a custom fetch implementation via options.fetch ' +
+      'for better compatibility.'
+    );
+  }
+  
   // Use global fetch if available (browser or Node.js 18+)
   if (typeof fetch !== 'undefined') {
-    return fetch;
+    // Bind to globalThis to avoid Window issues in some environments
+    return fetch.bind(globalThis);
   }
   
-  throw new Error('No fetch implementation available. For Node.js < 18, install node-fetch and pass it as an option.');
+  throw new NetworkError(
+    'No fetch implementation available. ' +
+    'For Node.js < 18, install node-fetch and pass it as an option: ' +
+    'new BitcoinCashOAuthClient({ fetch: fetchImplementation })'
+  );
 }
 
 /**
@@ -113,7 +254,7 @@ function getFetch() {
  * @typedef {Object} Keypair
  * @property {string} privateKey - Hex-encoded private key
  * @property {string} publicKey - Hex-encoded compressed public key
- * @property {string} address - Bitcoin Cash address
+ * @property {string} bitcoincash_address - Bitcoin Cash address
  */
 
 /**
@@ -122,6 +263,11 @@ function getFetch() {
  * @property {string} [network="mainnet"] - Network type ("mainnet" or "testnet")
  * @property {SecureStorage} [secureStorage] - Storage interface for tokens
  * @property {Function} [fetch] - Custom fetch implementation (optional)
+ * @property {string} [tokenKey="oauth_token"] - Key for storing access token
+ * @property {string} [refreshTokenKey="oauth_refresh_token"] - Key for storing refresh token
+ * @property {boolean} [autoRefresh=true] - Enable automatic token refresh
+ * @property {number} [refreshThreshold=300] - Seconds before expiry to trigger refresh (default: 5 minutes)
+ * @property {boolean} [debug=false] - Enable debug logging
  */
 
 /**
@@ -137,6 +283,7 @@ function getFetch() {
  * @property {string} refresh_token - Refresh token
  * @property {number} expires_in - Token expiration in seconds
  * @property {string} token_type - Token type (e.g., "bearer")
+ * @property {string[]} [scopes] - Granted scopes
  */
 
 /**
@@ -152,8 +299,41 @@ class BitcoinCashOAuthClient {
     this.serverUrl = options.serverUrl || "http://localhost:8000";
     this.network = options.network || "mainnet";
     this.secureStorage = options.secureStorage || null;
-    this.fetchImpl = options.fetch || getFetch();
+    this.fetchImpl = options.fetch || getFetch(options.fetch);
     this.secp256k1 = null;
+    
+    // Token storage keys
+    this.tokenKey = options.tokenKey || "oauth_token";
+    this.refreshTokenKey = options.refreshTokenKey || "oauth_refresh_token";
+    
+    // Auto-refresh settings
+    this.autoRefresh = options.autoRefresh !== false; // default true
+    this.refreshThreshold = options.refreshThreshold || 300; // 5 minutes before expiry
+    this.tokenExpiry = null;
+    this.refreshPromise = null;
+    this.refreshTimer = null;
+    
+    // Debug mode
+    this.debug = options.debug || false;
+    
+    // Store auth params for refresh
+    this._authParams = null;
+  }
+
+  /**
+   * Log debug messages
+   * @private
+   * @param {string} message - Message to log
+   * @param {*} [data] - Optional data to log
+   */
+  _log(message, data = null) {
+    if (this.debug) {
+      if (data !== null) {
+        console.log(`[bitcoincash-oauth-client] ${message}`, data);
+      } else {
+        console.log(`[bitcoincash-oauth-client] ${message}`);
+      }
+    }
   }
 
   /**
@@ -188,12 +368,14 @@ class BitcoinCashOAuthClient {
     const publicKeyBytes = this.secp256k1.derivePublicKeyCompressed(privateKeyBytes);
     
     // Convert to address
-    const address = await this.publicKeyToCashAddress(publicKeyBytes);
+    const bitcoincash_address = await this.publicKeyToCashAddress(publicKeyBytes);
+    
+    this._log('Generated new keypair', { bitcoincash_address });
 
     return {
       privateKey: this.bytesToHex(privateKeyBytes),
       publicKey: this.bytesToHex(publicKeyBytes),
-      address,
+      bitcoincash_address,
     };
   }
 
@@ -247,29 +429,62 @@ class BitcoinCashOAuthClient {
   }
 
   /**
-   * Register a new user with the server
-   * @param {string} address - Bitcoin Cash address
-   * @param {string} [userId] - Optional user-provided ID
+   * Register a new user with the server (signature required)
+   * @param {string} bitcoincash_address - Bitcoin Cash address
+   * @param {string} privateKeyHex - Private key for signing (hex-encoded)
+   * @param {string} publicKeyHex - Public key for signature verification (hex-encoded)
+   * @param {string} userId - User-provided ID (required)
+   * @param {number} [timestamp] - Optional Unix timestamp (defaults to now)
+   * @param {string} [domain] - Optional domain for message binding
    * @returns {Promise<Object>} Registration result with assigned userId
+   * @throws {NetworkError} If network request fails
+   * @throws {AuthenticationError} If registration fails
    */
-  async register(address, userId = null) {
-    const response = await this.fetchImpl(`${this.serverUrl}/auth/register`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        address,
-        user_id: userId,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Registration failed: ${response.status} ${response.statusText} - ${error}`);
+  async register(bitcoincash_address, privateKeyHex, publicKeyHex, userId, timestamp = null, domain = null) {
+    try {
+      const ts = timestamp || Math.floor(Date.now() / 1000);
+      const host = domain || this._getDefaultDomain();
+      const message = this.createAuthMessage(userId, ts, host);
+      const signature = await this.signAuthMessage(message, privateKeyHex);
+
+      this._log('Registering user', { bitcoincash_address, userId, domain: host });
+
+      const response = await this.fetchImpl(`${this.serverUrl}/auth/register`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          bitcoincash_address,
+          user_id: userId,
+          timestamp: ts,
+          domain: host,
+          public_key: publicKeyHex,
+          signature: signature,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+
+        if (response.status === 404) {
+          throw new UserNotFoundError(errorData.detail || 'User not found');
+        }
+
+        throw new AuthenticationError(
+          errorData.detail || `Registration failed: ${response.statusText}`,
+          response.status
+        );
+      }
+
+      this._log('User registered successfully', { bitcoincash_address, userId });
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OAuthError) {
+        throw error;
+      }
+      throw new NetworkError(`Network error during registration: ${error.message}`, error);
     }
-
-    return await response.json();
   }
 
   /**
@@ -314,38 +529,196 @@ class BitcoinCashOAuthClient {
    * @param {number} [timestamp] - Optional timestamp
    * @param {string} [domain] - Optional domain for message binding
    * @returns {Promise<AuthenticationResult>} Authentication result with access_token
+   * @throws {NetworkError} If network request fails
+   * @throws {AuthenticationError} If authentication fails
    */
   async authenticate(userId, privateKeyHex, publicKeyHex, timestamp = null, domain = null) {
+    this._log('Starting authentication', { userId, domain });
+    
     const ts = timestamp || Math.floor(Date.now() / 1000);
     const message = this.createAuthMessage(userId, ts, domain);
+    
+    this._log('Authentication message created', message);
+    
     const signature = await this.signAuthMessage(message, privateKeyHex);
+    
+    this._log('Message signed successfully');
+
+    try {
+      const response = await this.fetchImpl(`${this.serverUrl}/auth/token`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          user_id: userId,
+          timestamp: ts,
+          public_key: publicKeyHex,
+          signature: signature,
+          domain: domain || this._getDefaultDomain(), // Include domain in payload
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        
+        if (response.status === 401) {
+          throw new TokenExpiredError(errorData.detail || 'Authentication failed: invalid credentials');
+        }
+        if (response.status === 404) {
+          throw new UserNotFoundError(errorData.detail || 'User not found');
+        }
+        
+        throw new AuthenticationError(
+          errorData.detail || `Authentication failed: ${response.statusText}`,
+          response.status
+        );
+      }
+
+      const result = await response.json();
+      
+      this._log('Authentication successful', { 
+        expires_in: result.expires_in,
+        token_type: result.token_type 
+      });
+      
+      // Store tokens if secure storage is available
+      if (this.secureStorage) {
+        if (result.access_token) {
+          this.secureStorage.setItem(this.tokenKey, result.access_token);
+        }
+        if (result.refresh_token) {
+          this.secureStorage.setItem(this.refreshTokenKey, result.refresh_token);
+        }
+      }
+
+      // Track token expiry and schedule refresh
+      if (result.expires_in) {
+        this.tokenExpiry = Date.now() + (result.expires_in * 1000);
+        
+        // Store auth params for refresh
+        this._authParams = { userId, privateKeyHex, publicKeyHex, domain };
+        
+        if (this.autoRefresh) {
+          this._scheduleRefresh();
+        }
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof OAuthError) {
+        throw error;
+      }
+      throw new NetworkError(`Network error during authentication: ${error.message}`, error);
+    }
+  }
 
-    const response = await this.fetchImpl(`${this.serverUrl}/auth/token`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        user_id: userId,
-        timestamp: ts,
-        public_key: publicKeyHex,
-        signature: signature,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Authentication failed: ${response.status} ${response.statusText} - ${error}`);
+  /**
+   * Get default domain for authentication
+   * @private
+   * @returns {string}
+   */
+  _getDefaultDomain() {
+    if (typeof window !== 'undefined' && window?.location?.host) {
+      return window.location.host;
     }
+    return 'oauth';
+  }
 
-    const result = await response.json();
+  /**
+   * Schedule automatic token refresh
+   * @private
+   */
+  _scheduleRefresh() {
+    // Clear any existing timer
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+
+    const refreshTime = this.tokenExpiry - (this.refreshThreshold * 1000) - Date.now();
     
-    // Store token if secure storage is available
-    if (this.secureStorage && result.access_token) {
-      this.secureStorage.setItem("oauth_token", result.access_token);
+    if (refreshTime > 0) {
+      this._log(`Scheduling token refresh in ${Math.floor(refreshTime / 1000)} seconds`);
+      
+      this.refreshTimer = setTimeout(() => {
+        this._performRefresh();
+      }, refreshTime);
+    } else {
+      this._log('Token expires too soon, refreshing immediately');
+      this._performRefresh();
     }
+  }
 
-    return result;
+  /**
+   * Perform token refresh
+   * @private
+   */
+  async _performRefresh() {
+    if (!this._authParams) {
+      this._log('No auth params available for refresh');
+      return;
+    }
+
+    const { userId, privateKeyHex, publicKeyHex, domain } = this._authParams;
+    
+    try {
+      await this.refreshAccessToken(userId, privateKeyHex, publicKeyHex, domain);
+      this._log('Token refreshed automatically');
+    } catch (error) {
+      this._log('Automatic token refresh failed', error.message);
+      // Clear stored tokens on refresh failure
+      if (this.secureStorage) {
+        this.secureStorage.removeItem(this.tokenKey);
+        this.secureStorage.removeItem(this.refreshTokenKey);
+      }
+    }
+  }
+
+  /**
+   * Refresh access token with automatic retry on expiration
+   * @param {string} userId
+   * @param {string} privateKeyHex
+   * @param {string} publicKeyHex
+   * @param {string} [domain]
+   * @returns {Promise<AuthenticationResult>}
+   * @throws {AuthenticationError} If refresh fails
+   */
+  async refreshAccessToken(userId, privateKeyHex, publicKeyHex, domain = null) {
+    // Prevent concurrent refresh attempts
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+
+    this.refreshPromise = this._doRefresh(userId, privateKeyHex, publicKeyHex, domain);
+    
+    try {
+      const result = await this.refreshPromise;
+      return result;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+
+  /**
+   * Internal refresh implementation
+   * @private
+   */
+  async _doRefresh(userId, privateKeyHex, publicKeyHex, domain) {
+    this._log('Refreshing access token');
+    
+    // Use refresh token if available, otherwise re-authenticate
+    const refreshToken = this.getRefreshToken();
+    
+    if (refreshToken) {
+      try {
+        return await this.refreshToken(refreshToken);
+      } catch (error) {
+        this._log('Refresh token failed, falling back to re-authentication');
+      }
+    }
+    
+    // Fall back to full re-authentication
+    return await this.authenticate(userId, privateKeyHex, publicKeyHex, null, domain);
   }
 
   /**
@@ -354,92 +727,244 @@ class BitcoinCashOAuthClient {
    */
   getToken() {
     if (this.secureStorage) {
-      return this.secureStorage.getItem("oauth_token");
+      return this.secureStorage.getItem(this.tokenKey);
     }
     return null;
   }
 
   /**
-   * Make authenticated request
-   * @param {string} endpoint - API endpoint (relative to serverUrl)
-   * @param {Object} [options] - Fetch options
-   * @returns {Promise<Response>}
+   * Get stored refresh token
+   * @returns {string|null}
+   */
+  getRefreshToken() {
+    if (this.secureStorage) {
+      return this.secureStorage.getItem(this.refreshTokenKey);
+    }
+    return null;
+  }
+
+  /**
+   * Validate if the current token is still valid
+   * @param {boolean} [serverCheck=false] - If true, validates with the server; if false, only checks local expiry
+   * @returns {Promise<boolean>}
    */
-  async authenticatedRequest(endpoint, options = {}) {
+  async isTokenValid(serverCheck = false) {
     const token = this.getToken();
     
     if (!token) {
-      throw new Error("No authentication token available");
+      this._log('Token validation: no token stored');
+      return false;
+    }
+
+    // Local expiry check
+    if (this.tokenExpiry && Date.now() >= this.tokenExpiry) {
+      this._log('Token validation: token expired locally');
+      return false;
+    }
+
+    // Server validation (optional)
+    if (serverCheck) {
+      try {
+        this._log('Token validation: checking with server');
+        const response = await this.fetchImpl(`${this.serverUrl}/auth/verify`, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${token}`,
+            "Content-Type": "application/json"
+          }
+        });
+        
+        const isValid = response.ok;
+        this._log('Token validation: server check result', isValid);
+        return isValid;
+      } catch (error) {
+        this._log('Token validation: server check failed', error.message);
+        return false;
+      }
     }
 
-    const headers = {
-      "Authorization": `Bearer ${token}`,
-      ...options.headers,
+    return true;
+  }
+
+  /**
+   * Make authenticated request with automatic retry on token expiration
+   * @param {string} endpoint - API endpoint (relative to serverUrl)
+   * @param {Object} [options] - Fetch options
+   * @param {Object} [authParams] - Parameters to re-authenticate if needed
+   * @param {string} authParams.userId - User ID
+   * @param {string} authParams.privateKeyHex - Private key in hex
+   * @param {string} authParams.publicKeyHex - Public key in hex
+   * @param {string} [authParams.domain] - Domain for authentication
+   * @returns {Promise<Response>}
+   * @throws {AuthenticationError} If no token available and no auth params provided
+   */
+  async authenticatedRequest(endpoint, options = {}, authParams = null) {
+    const makeRequest = async () => {
+      const token = this.getToken();
+      if (!token) {
+        throw new AuthenticationError('No authentication token available', 401, 'NO_TOKEN');
+      }
+
+      const headers = {
+        "Authorization": `Bearer ${token}`,
+        ...options.headers,
+      };
+
+      return this.fetchImpl(`${this.serverUrl}${endpoint}`, {
+        ...options,
+        headers,
+      });
     };
 
-    return this.fetchImpl(`${this.serverUrl}${endpoint}`, {
-      ...options,
-      headers,
-    });
+    let response = await makeRequest();
+
+    // If token expired and auth params provided, re-authenticate and retry
+    if (response.status === 401 && authParams) {
+      this._log('Token expired, re-authenticating...');
+      
+      await this.authenticate(
+        authParams.userId,
+        authParams.privateKeyHex,
+        authParams.publicKeyHex,
+        null,
+        authParams.domain
+      );
+
+      // Retry the request with new token
+      response = await makeRequest();
+    }
+
+    return response;
   }
 
   /**
-   * Refresh access token
+   * Refresh access token using refresh token
    * @param {string} refreshToken
    * @returns {Promise<AuthenticationResult>}
+   * @throws {NetworkError} If network request fails
+   * @throws {AuthenticationError} If refresh fails
    */
   async refreshToken(refreshToken) {
-    const response = await this.fetchImpl(`${this.serverUrl}/auth/refresh`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        refresh_token: refreshToken,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Token refresh failed: ${response.status} ${response.statusText} - ${error}`);
+    try {
+      const response = await this.fetchImpl(`${this.serverUrl}/auth/refresh`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          refresh_token: refreshToken,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        
+        if (response.status === 401) {
+          throw new InvalidTokenError(errorData.detail || 'Invalid or expired refresh token');
+        }
+        
+        throw new AuthenticationError(
+          errorData.detail || `Token refresh failed: ${response.statusText}`,
+          response.status
+        );
+      }
+
+      const result = await response.json();
+      
+      this._log('Token refreshed successfully');
+      
+      // Update stored tokens
+      if (this.secureStorage) {
+        if (result.access_token) {
+          this.secureStorage.setItem(this.tokenKey, result.access_token);
+        }
+        if (result.refresh_token) {
+          this.secureStorage.setItem(this.refreshTokenKey, result.refresh_token);
+        }
+      }
+
+      // Update expiry and reschedule refresh
+      if (result.expires_in) {
+        this.tokenExpiry = Date.now() + (result.expires_in * 1000);
+        
+        if (this.autoRefresh) {
+          this._scheduleRefresh();
+        }
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof OAuthError) {
+        throw error;
+      }
+      throw new NetworkError(`Network error during token refresh: ${error.message}`, error);
     }
-
-    const result = await response.json();
-    
-    if (this.secureStorage && result.access_token) {
-      this.secureStorage.setItem("oauth_token", result.access_token);
-    }
-
-    return result;
   }
 
   /**
    * Revoke token
    * @param {string} token
    * @returns {Promise<Object>}
+   * @throws {NetworkError} If network request fails
    */
   async revokeToken(token) {
-    const response = await this.fetchImpl(`${this.serverUrl}/auth/revoke`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        token,
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`Token revocation failed: ${response.status} ${response.statusText} - ${error}`);
+    try {
+      // Clear any pending refresh
+      if (this.refreshTimer) {
+        clearTimeout(this.refreshTimer);
+        this.refreshTimer = null;
+      }
+      
+      const response = await this.fetchImpl(`${this.serverUrl}/auth/revoke`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          token,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new AuthenticationError(
+          errorData.detail || `Token revocation failed: ${response.statusText}`,
+          response.status
+        );
+      }
+
+      this._log('Token revoked successfully');
+
+      // Clear stored tokens
+      if (this.secureStorage) {
+        this.secureStorage.removeItem(this.tokenKey);
+        this.secureStorage.removeItem(this.refreshTokenKey);
+      }
+
+      this.tokenExpiry = null;
+      this._authParams = null;
+
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OAuthError) {
+        throw error;
+      }
+      throw new NetworkError(`Network error during token revocation: ${error.message}`, error);
     }
+  }
 
-    if (this.secureStorage) {
-      this.secureStorage.removeItem("oauth_token");
+  /**
+   * Clean up resources (clear timers, etc.)
+   * Call this when the client is no longer needed
+   */
+  destroy() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
     }
-
-    return await response.json();
+    this._authParams = null;
+    this._log('Client destroyed');
   }
 }
 
-export { BitcoinCashOAuthClient, BitcoinCashOAuthClient as default };
+export { AuthenticationError, BitcoinCashOAuthClient, InvalidTokenError, NetworkError, OAuthError, TokenExpiredError, UserNotFoundError, BitcoinCashOAuthClient as default };