Class: SheetAPITokenManager

SheetAPITokenManager(config)

The SheetAPITokenManager class is responsible for managing OAuth2 authentication tokens required to access the Google Sheets API. It supports both access tokens and refresh tokens, automatically refreshing expired tokens and providing callbacks for token updates.

Constructor

new SheetAPITokenManager(config)

Creates a new SheetAPITokenManager instance with comprehensive OAuth2 configuration. This constructor initializes the token manager with all necessary OAuth2 credentials and configuration options. It validates that required parameters are provided and sets up the internal state for token management operations.
Parameters:
Name Type Description
config Object Complete configuration object for OAuth2 setup
Properties
Name Type Attributes Default Description
clientId string Google OAuth2 Client ID obtained from Google Cloud Console. This is the public identifier for your OAuth2 application. Required for all OAuth2 operations.
clientSecret string Google OAuth2 Client Secret obtained from Google Cloud Console. This is the private key for your OAuth2 application. Keep this secure and never expose in client-side code. Required for token refresh operations.
refreshToken string Long-lived OAuth2 refresh token obtained during initial authorization. This token allows indefinite access renewal without user interaction. Store securely and never expose in client-side code. Required for automatic token refresh.
accessToken string <optional>
 null Current valid OAuth2 access token. If provided, will be used until expiration. Optional - will be obtained via refresh if not provided.
expiryTime number <optional>
 0 Timestamp (milliseconds since epoch) when the current access token expires. Used to determine if token refresh is needed. Optional - defaults to 0 (expired).
onTokenUpdate function <optional>
 null Callback function invoked whenever tokens are refreshed. Receives an object with accessToken and expiryTime properties. Useful for persisting tokens to localStorage, database, etc. Optional - no callback if not provided.
debug boolean <optional>
 false Enables detailed debug logging for troubleshooting. When true, logs all token operations, API calls, and state changes. Optional - defaults to false for production use.
Source:
Throws:
  • When required OAuth2 credentials are missing
    Type
    Error
  • When token refresh fails after retries
    Type
    Error
Examples
// Basic usage with refresh token
const tokenManager = new SheetAPITokenManager({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  refreshToken: 'your-refresh-token',
  onTokenUpdate: (tokens) => {
    console.log('Tokens updated:', tokens);
    // Save tokens to localStorage or database
  },
  debug: true
});

// Get a valid access token
const token = await tokenManager.getAccessToken();
// Usage with existing access token
const tokenManager = new SheetAPITokenManager({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  refreshToken: 'your-refresh-token',
  accessToken: 'existing-access-token',
  expiryTime: Date.now() + 3600000, // Expires in 1 hour
  debug: false
});

Methods

isTokenValid() → {boolean}

Check if current access token is still valid. Performs a comprehensive validation of the current access token to determine if it can be used for API calls without requiring a refresh. This method implements a proactive refresh strategy by considering tokens "expired" 60 seconds before their actual expiry time to account for network latency and processing delays.
Source:
Returns:
True if the token is valid and can be used for API calls, false if the token is missing, expired, or about to expire.
Type
boolean
Example
// Check token validity before making API calls
if (tokenManager.isTokenValid()) {
  console.log('Token is valid, proceeding with API call');
  // Make API call with current token
} else {
  console.log('Token needs refresh');
  // Token will be refreshed automatically by getAccessToken()
}