@alapandas03/token-refresher/README.md

A service for handling API requests with token refresh capabilities

# @alapandas03/token-refresher

A lightweight, customizable service for handling API requests with automatic token refresh capabilities. Perfect for applications requiring JWT or OAuth2 token management.

## Features

-  Automatic token refresh on 401 errors
-  Smart request queuing during token refresh to prevent token race conditions
-  Configurable token storage (localStorage, sessionStorage, or custom storage)
-  Support for all HTTP methods (GET, POST, PUT, DELETE)
-  Fully customizable refresh token endpoint
-  Works in both browser and Node.js environments
-  Built on top of Axios for reliable HTTP requests

## Installation

```bash
npm install @alapandas03/token-refresher
```

## Quick Start

```javascript
const TokenRefresher = require('@alapandas03/token-refresher');

const api = new TokenRefresher({
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh'
});

// Example usage
async function fetchUserProfile() {
    try {
        const response = await api.get('/user/profile');
        return response.data;
    } catch (error) {
        console.error('Error:', error);
    }
}
```

## Advanced Usage

### 1. Custom Token Storage

You can customize where and how tokens are stored by providing custom functions:

```javascript
const api = new TokenRefresher({
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh',
    // Custom token management functions
    getAccessToken: () => sessionStorage.getItem('my-access-token'),
    getRefreshToken: () => sessionStorage.getItem('my-refresh-token'),
    setAccessToken: (token) => sessionStorage.setItem('my-access-token', token),
    clearTokens: () => {
        sessionStorage.removeItem('my-access-token');
        sessionStorage.removeItem('my-refresh-token');
    }
});
```

### 2. Handling Failed Token Refresh

The service automatically handles token refresh failures:
- Clears existing tokens
- Rejects all queued requests
- Throws an error that you can catch to redirect to login

```javascript
try {
    const response = await api.get('/protected-endpoint');
    return response.data;
} catch (error) {
    if (error.response?.status === 401) {
        // Token refresh failed, redirect to login
        window.location.href = '/login';
    }
}
```

### 3. Making Authenticated Requests

```javascript
// GET request
const getData = await api.get('/endpoint');

// POST request with data
const postData = await api.post('/endpoint', {
    key: 'value'
});

// PUT request
const putData = await api.put('/endpoint', {
    key: 'updated value'
});

// DELETE request
const deleteData = await api.delete('/endpoint');
```

### 4. Configuration Options

```javascript
const api = new TokenRefresher({
    // Required options
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh',

    // Optional token management (defaults to localStorage)
    getAccessToken: () => customStorage.getToken(),
    getRefreshToken: () => customStorage.getRefreshToken(),
    setAccessToken: (token) => customStorage.setToken(token),
    clearTokens: () => customStorage.clear(),

    // Additional axios config options
    timeout: 5000,
    headers: {
        'Custom-Header': 'value'
    }
});
```

## Common Use Cases

1. **Single Page Applications (SPA)**
   - Automatic token refresh without interrupting user experience
   - Queued requests continue automatically after token refresh

2. **Mobile-First Applications**
   - Efficient token management for intermittent connections
   - Customizable storage for mobile-specific requirements

3. **Microservices Architecture**
   - Consistent token management across multiple service calls
   - Centralized refresh token handling

4. **OAuth2 Implementations**
   - Perfect for handling OAuth2 access/refresh token flows
   - Automatic token refresh on expiration

## Error Handling

The service handles various scenarios:

```javascript
try {
    const response = await api.get('/endpoint');
    // Success handling
} catch (error) {
    if (error.response) {
        // Server responded with error status
        console.error('Server Error:', error.response.status);
    } else if (error.request) {
        // Request was made but no response
        console.error('Network Error');
    } else {
        // Error in request configuration
        console.error('Request Error:', error.message);
    }
}
```

## Best Practices

1. **Token Storage**
   - Use secure storage methods (HttpOnly cookies for refresh tokens)
   - Consider using sessionStorage for access tokens in browsers

2. **Error Handling**
   - Implement proper error boundaries
   - Handle token refresh failures gracefully

3. **Security**
   - Never store sensitive tokens in localStorage
   - Implement proper CSRF protection

## License

MIT

## Contributing

Contributions welcome! Please read the contributing guidelines before making a pull request.