@dainprotocol/oauth2-token-manager 0.1.0 → 0.1.2

package/README.md

@@ -1,19 +1,25 @@
 # OAuth2 Token Manager
 
-A powerful, storage-agnostic OAuth2 token management library built for scalable multi-system architectures. This library provides comprehensive token lifecycle management with pluggable storage adapters, built-in security features, and support for multiple OAuth2 providers.
+A simple OAuth2 token management library for Node.js. Store and manage OAuth2 tokens with automatic refresh, multiple providers, and pluggable storage.
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Concepts](#-core-concepts)
+- [API Reference](#-api-reference)
+- [Storage Adapters](#-storage-adapters)
+- [Examples](#-examples)
 
 ## 🚀 Features
 
-- **🔌 Storage Agnostic**: Use any storage backend (In-Memory, PostgreSQL, or build your own adapter)
-- **🏢 Multi-System Support**: Manage tokens across multiple applications/systems
-- **🔐 Advanced Security**: PKCE support, state validation, token encryption
-- **⚡ High Performance**: Efficient token validation, caching, and refresh strategies
-- **🔄 Auto-Refresh**: Automatic token refresh with configurable buffers
-- **👤 User Management**: Comprehensive user lifecycle with email/external ID support
-- **📧 Profile Integration**: Automatic profile fetching from OAuth providers
-- **🎯 Flexible Scoping**: Fine-grained permission management
-- **💡 Developer Friendly**: Both context-managed and granular APIs
-- **🧪 Fully Tested**: Comprehensive test coverage with Vitest
+- **Simple Storage**: Tokens stored by provider + email (unique constraint)
+- **Auto Refresh**: Tokens refresh automatically when expired
+- **Multiple Providers**: Google, GitHub, Microsoft, Facebook, and custom providers
+- **Profile Fetching**: Get user profiles during OAuth callback
+- **Pluggable Storage**: In-memory, PostgreSQL, Drizzle, or custom adapters
+- **Type Safe**: Full TypeScript support
 
 ## 📦 Installation
 
@@ -24,763 +30,367 @@ npm install @dainprotocol/oauth2-token-manager
 ### Storage Adapters
 
 ```bash
-# PostgreSQL adapter
+# PostgreSQL adapter (TypeORM based)
 npm install @dainprotocol/oauth2-storage-postgres
-```
-
-## 🚀 Quick Start
-
-### Simple Setup
-
-```typescript
-import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
 
-// Quick setup for common use cases
-const oauth = await OAuth2Client.quickSetup('MyApp', {
-  google: {
-    clientId: 'your-google-client-id',
-    clientSecret: 'your-google-client-secret',
-    authorizationUrl: 'https://accounts.google.com/o/oauth2/auth',
-    tokenUrl: 'https://oauth2.googleapis.com/token',
-    redirectUri: 'http://localhost:3000/auth/callback',
-    scopes: ['profile', 'email'],
-  },
-  github: {
-    clientId: 'your-github-client-id',
-    clientSecret: 'your-github-client-secret',
-    authorizationUrl: 'https://github.com/login/oauth/authorize',
-    tokenUrl: 'https://github.com/login/oauth/access_token',
-    redirectUri: 'http://localhost:3000/auth/callback',
-    scopes: ['user:email'],
-  },
-});
-
-// Create or get a user
-const user = await oauth.getOrCreateUser({
-  email: 'user@example.com',
-  metadata: { role: 'user' },
-});
-
-// Start OAuth flow
-const { url, state } = await oauth.authorize({
-  provider: 'google',
-  scopes: ['profile', 'email'],
-});
-
-// Handle callback
-const result = await oauth.handleCallback(code, state);
-console.log('User authenticated:', result.userId);
+# Drizzle adapter (supports PostgreSQL, MySQL, SQLite)
+npm install @dainprotocol/oauth2-storage-drizzle
 ```
 
-### Advanced Setup with Custom Storage
+## 🚀 Quick Start
 
 ```typescript
 import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
-import { PostgresStorageFactory } from '@dainprotocol/oauth2-storage-postgres';
-
-// Custom storage adapter
-const storage = await PostgresStorageFactory.create({
-  host: 'localhost',
-  port: 5432,
-  username: 'oauth2_user',
-  password: 'secure_password',
-  database: 'oauth2_db',
-});
 
+// Initialize with provider configurations
 const oauth = new OAuth2Client({
-  storage,
   providers: {
     google: {
-      /* config */
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+      tokenUrl: 'https://oauth2.googleapis.com/token',
+      redirectUri: 'http://localhost:3000/auth/google/callback',
+      scopes: ['profile', 'email'],
+      profileUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
     },
     github: {
-      /* config */
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      authorizationUrl: 'https://github.com/login/oauth/authorize',
+      tokenUrl: 'https://github.com/login/oauth/access_token',
+      redirectUri: 'http://localhost:3000/auth/github/callback',
+      scopes: ['user:email'],
+      profileUrl: 'https://api.github.com/user',
     },
   },
 });
 
-// Create system and scopes
-const system = await oauth.createSystem('MyApp');
-const scope = await oauth.createScope('api-access', {
-  type: 'access',
-  permissions: ['read:profile', 'write:data'],
-  isolated: true,
+// Start OAuth flow
+const { url, state } = await oauth.authorize({
+  provider: 'google',
+  userId: 'user123',
+  email: 'user@example.com',
+  scopes: ['profile', 'email'],
 });
-```
 
-## 🏗️ Architecture
+// Redirect user to authorization URL
+res.redirect(url);
 
-### Core Components
+// Handle OAuth callback
+const { token, profile } = await oauth.handleCallback(code, state);
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     OAuth2Client                            │
-│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
-│  │  Context API    │    │      Granular API              │ │
-│  │  (Simplified)   │    │  (Full Control)                │ │
-│  └─────────────────┘    └─────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              │               │               │
-    ┌─────────▼────────┐ ┌───▼────────┐ ┌───▼─────────┐
-    │   Providers      │ │  Storage   │ │   Profile   │
-    │   (OAuth2)       │ │  Adapter   │ │  Fetchers   │
-    └──────────────────┘ └────────────┘ └─────────────┘
+// Use the token
+const accessToken = await oauth.getAccessToken('google', 'user@example.com');
 ```
 
-### Data Model & Token Hierarchy
+## 🔑 Core Concepts
 
-**Important**: Users can have multiple tokens for the same provider within the same scope. This allows for scenarios like different email accounts or token refresh cycles.
+### How It Works
 
-```typescript
-// Systems: Top-level applications/services
-interface System {
-  id: string;
-  name: string;
-  description?: string;
-  scopes: Scope[];
-  metadata?: Record<string, any>;
-}
-
-// Scopes: Permission boundaries within systems
-interface Scope {
-  id: string;
-  systemId: string;
-  name: string;
-  type: 'authentication' | 'access' | 'custom';
-  permissions: string[];
-  isolated: boolean; // Whether tokens are isolated to this scope
-}
-
-// Users: Identity within a system
-interface User {
-  id: string;
-  systemId: string;
-  metadata?: Record<string, any>;
-}
-
-// User Tokens: OAuth2 tokens tied to user/system/scope/provider
-// A user can have MULTIPLE tokens for the same provider/scope combination
-interface UserToken {
-  id: string;
-  userId: string;
-  systemId: string;
-  scopeId: string;
-  provider: string;
-  token: OAuth2Token;
-}
-```
-
-### Token Hierarchy Rules
-
-1. **One User** belongs to **One System**
-2. **One User** can have tokens in **Multiple Scopes** within their system
-3. **One User** in **One Scope** can have tokens from **Multiple Providers**
-4. **One User** in **One Scope** from **One Provider** can have **Multiple Tokens**
-5. **Email Uniqueness**: For the same provider, a user cannot have multiple tokens with the same email (validated via profile fetcher)
-6. **Cross-Provider Emails**: The same email can exist across different providers
+1. **One token per provider/email**: Each email can have one token per OAuth provider
+2. **Automatic override**: Saving a token with same provider + email replaces the old one
+3. **Auto refresh**: Expired tokens refresh automatically when you request them
+4. **Simple storage**: Just provider (string), userId (string), and email (string)
 
 ## 📚 API Reference
 
 ### OAuth2Client
 
-The main client class providing both context-managed and granular APIs.
-
-#### Context-Managed API (Recommended)
+The main class for managing OAuth2 tokens.
 
 ```typescript
-// System management
-await oauth.createSystem('MyApp');
-await oauth.useSystem(systemId);
-
-// User management
-const user = await oauth.getOrCreateUser({ email: 'user@example.com' });
-await oauth.useUser(userId);
+const oauth = new OAuth2Client({
+  storage?: StorageAdapter,  // Optional, defaults to in-memory
+  providers?: {              // OAuth provider configurations
+    [name: string]: OAuth2Config
+  }
+});
+```
 
-// Authorization flow
-const { url, state } = await oauth.authorize({ provider: 'google' });
-const result = await oauth.handleCallback(code, state);
+### Methods
 
-// Token operations (uses current context + default scope)
-// Note: When multiple tokens exist, these methods use the first (most recent) token
-const accessToken = await oauth.getAccessToken('google');
-const validToken = await oauth.ensureValidToken('google');
+#### 🔐 OAuth Flow
 
-// Get all user tokens with auto-refresh (for current user)
-const userTokens = await oauth.getUserTokens();
+##### `authorize(options)`
 
-// Get all valid tokens for a specific user
-const allTokens = await oauth.getAllValidTokensForUser(userId);
-// Returns: { provider: string; scopeId: string; token: OAuth2Token; userToken: UserToken }[]
+Start OAuth2 authorization flow.
 
-// Revoke tokens (uses current context)
-await oauth.revokeTokens('google'); // Revokes for current user/scope/provider
+```typescript
+const { url, state } = await oauth.authorize({
+  provider: 'google',
+  userId: 'user123',
+  email: 'user@example.com',
+  scopes?: ['profile', 'email'],  // Optional
+  usePKCE?: true,                  // Optional
+  metadata?: { source: 'signup' }  // Optional
+});
+// Redirect user to `url`
 ```
 
-#### Granular API (Advanced)
+##### `handleCallback(code, state)`
 
-The granular API provides full control over the token hierarchy:
+Handle OAuth2 callback and save tokens.
 
 ```typescript
-// === User-Centric Token Queries (Primary Key: User) ===
-
-// Get ALL tokens for a user across all scopes/providers
-const userTokens = await oauth.granular.getTokensByUser(userId);
-
-// Get tokens for user in specific scope (across all providers)
-const scopeTokens = await oauth.granular.getTokensByUserAndScope(userId, scopeId);
-
-// Get tokens for user with specific provider (across all scopes)
-const providerTokens = await oauth.granular.getTokensByUserAndProvider(userId, 'google');
-
-// Get tokens for user/scope/provider combination (can be multiple!)
-const specificTokens = await oauth.granular.getTokensByUserScopeProvider(userId, scopeId, 'google');
-
-// === Cross-User Queries (System/Scope Level) ===
-
-// Get all tokens in a scope across all users
-const scopeAllTokens = await oauth.granular.getTokensByScope(systemId, scopeId);
-
-// Get all tokens for a provider across all users in system
-const providerAllTokens = await oauth.granular.getTokensByProvider(systemId, 'google');
-
-// Get all tokens in a system
-const systemTokens = await oauth.granular.getTokensBySystem(systemId);
-
-// === Email-Based Queries ===
-
-// Find tokens by email (cross-user, cross-provider)
-const emailTokens = await oauth.granular.findTokensByEmail('user@example.com', systemId);
-
-// Find tokens by email in specific scope
-const emailScopeTokens = await oauth.granular.findTokensByEmailAndScope(
-  'user@example.com',
-  systemId,
-  scopeId,
-);
-
-// Find tokens by email for specific provider
-const emailProviderTokens = await oauth.granular.findTokensByEmailAndProvider(
-  'user@example.com',
-  systemId,
-  'google',
-);
-
-// Find specific token by email/scope/provider (returns single token or null)
-const specificToken = await oauth.granular.findTokenByEmailScopeProvider(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-);
-
-// === Token Operations ===
+const { token, profile } = await oauth.handleCallback(code, state);
+// token: { id, provider, userId, email, token, metadata, ... }
+// profile: { id, email, name, picture, raw } or undefined
+```
 
-// Get valid token for user (auto-refresh, takes first if multiple exist)
-const validToken = await oauth.granular.getValidTokenForUser(userId, scopeId, 'google');
+#### 🔑 Token Management
 
-// Get access token for user (convenience method)
-const accessToken = await oauth.granular.getAccessTokenForUser(userId, scopeId, 'google');
+##### `getAccessToken(provider, email, options?)`
 
-// Save new token for user
-const savedToken = await oauth.granular.saveTokenForUser(
-  userId,
-  systemId,
-  scopeId,
-  'google',
-  'user@example.com',
-  oauthToken,
-);
+Get access token string (auto-refreshes if expired).
 
-// === Token Management ===
-
-// Delete tokens by different criteria
-await oauth.granular.deleteTokensByUser(userId); // All tokens for user
-await oauth.granular.deleteTokensByUserAndScope(userId, scopeId); // User's tokens in scope
-await oauth.granular.deleteTokensByUserAndProvider(userId, 'google'); // User's tokens for provider
+```typescript
+const accessToken = await oauth.getAccessToken('google', 'user@example.com');
+// Returns: "ya29.a0AfH6SMBx..."
 ```
 
-### Storage Adapters
+##### `getValidToken(provider, email, options?)`
 
-#### Built-in Memory Adapter
+Get full token object (auto-refreshes if expired).
 
 ```typescript
-import { InMemoryStorageAdapter } from '@dainprotocol/oauth2-token-manager';
-
-const storage = new InMemoryStorageAdapter();
-const oauth = new OAuth2Client({ storage });
+const token = await oauth.getValidToken('google', 'user@example.com');
+// Returns: { accessToken, refreshToken, expiresAt, tokenType, scope, ... }
 ```
 
-#### PostgreSQL Adapter
+#### 🔍 Token Queries
 
-```typescript
-import { PostgresStorageFactory } from '@dainprotocol/oauth2-storage-postgres';
-
-const storage = await PostgresStorageFactory.create({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT || '5432'),
-  username: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-  ssl: process.env.NODE_ENV === 'production',
-});
-```
+##### `getTokensByUserId(userId)`
 
-#### Custom Storage Adapter
+Get all tokens for a user.
 
 ```typescript
-import { StorageAdapter } from '@dainprotocol/oauth2-token-manager';
-
-class MyCustomAdapter implements StorageAdapter {
-  async createSystem(system) {
-    /* implement */
-  }
-  async getSystem(id) {
-    /* implement */
-  }
-  // ... implement all required methods
-}
+const tokens = await oauth.getTokensByUserId('user123');
+// Returns: StoredToken[]
 ```
 
-### Provider Configuration
+##### `getTokensByEmail(email)`
 
-#### Google OAuth2
+Get all tokens for an email.
 
 ```typescript
-{
-  google: {
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    authorizationUrl: 'https://accounts.google.com/o/oauth2/auth',
-    tokenUrl: 'https://oauth2.googleapis.com/token',
-    redirectUri: 'http://localhost:3000/auth/callback',
-    scopes: ['profile', 'email'],
-    profileUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
-    usePKCE: true, // Recommended for security
-  }
-}
-```
-
-#### GitHub OAuth2
-
-```typescript
-{
-  github: {
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    authorizationUrl: 'https://github.com/login/oauth/authorize',
-    tokenUrl: 'https://github.com/login/oauth/access_token',
-    redirectUri: 'http://localhost:3000/auth/callback',
-    scopes: ['user:email'],
-    profileUrl: 'https://api.github.com/user',
-  }
-}
+const tokens = await oauth.getTokensByEmail('user@example.com');
+// Returns: StoredToken[]
 ```
 
-#### Generic Provider
+#### 🗑️ Token Cleanup
 
-```typescript
-{
-  custom: {
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    authorizationUrl: 'https://provider.com/oauth/authorize',
-    tokenUrl: 'https://provider.com/oauth/token',
-    redirectUri: 'http://localhost:3000/auth/callback',
-    scopes: ['read', 'write'],
-    profileUrl: 'https://provider.com/api/user',
-    additionalParams: {
-      audience: 'api.example.com'
-    },
-    responseRootKey: 'data' // For nested responses
-  }
-}
-```
+##### `deleteToken(provider, email)`
 
-#### Google OAuth2 with Offline Access
+Delete a specific token.
 
 ```typescript
-const oauth = new OAuth2Client({
-  providers: {
-    google: {
-      clientId: 'your-client-id',
-      clientSecret: 'your-client-secret',
-      redirectUri: 'http://localhost:3000/auth/callback',
-      scopes: ['profile', 'email'],
-      // Override default offline access parameters
-      extraAuthParams: {
-        access_type: 'offline',     // Request refresh token
-        prompt: 'consent',          // Force consent screen
-        include_granted_scopes: 'true'  // Include previously granted scopes
-      }
-    }
-  }
-});
-
-// The library automatically handles refresh tokens
-const token = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 5  // Refresh 5 minutes before expiry
-});
+const deleted = await oauth.deleteToken('google', 'user@example.com');
+// Returns: boolean
 ```
 
-#### Customizing Authorization Parameters
+##### `cleanupExpiredTokens()`
 
-Each provider supports customization through `extraAuthParams` and `additionalParams`:
+Delete all expired tokens.
 
 ```typescript
-{
-  google: {
-    // ... other config ...
-    extraAuthParams: {
-      access_type: 'offline',    // For refresh tokens
-      prompt: 'select_account',  // Force account selection
-      hd: 'yourdomain.com'      // Limit to specific Google Workspace domain
-    }
-  },
-  microsoft: {
-    // ... other config ...
-    extraAuthParams: {
-      prompt: 'select_account',
-      domain_hint: 'yourdomain.com'
-    }
-  }
-}
+const count = await oauth.cleanupExpiredTokens();
+// Returns: number of deleted tokens
 ```
 
-Available parameters for Google OAuth2:
-- `access_type`: 'online' (default) or 'offline' (for refresh tokens)
-- `prompt`: 'none', 'consent', 'select_account'
-- `include_granted_scopes`: 'true' or 'false'
-- `login_hint`: User's email address
-- `hd`: Google Workspace domain restriction
-
-## 🔧 Advanced Features
+##### `cleanupExpiredStates()`
 
-### Token Auto-Refresh
+Delete expired authorization states (older than 10 minutes).
 
 ```typescript
-const accessToken = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 5, // Refresh 5 minutes before expiry
-  expirationBuffer: 30, // Consider expired 30 seconds early
-});
+const count = await oauth.cleanupExpiredStates();
+// Returns: number of deleted states
 ```
 
-### Profile-Based Token Management
+#### ⚙️ Provider Management
 
-```typescript
-const result = await oauth.handleCallback(code, state, {
-  profileOptions: {
-    checkProfileEmail: true, // Fetch and check email conflicts
-    replaceConflictingTokens: true, // Replace existing tokens with same email
-    mergeUserData: true, // Merge profile data into user metadata
-  },
-});
-```
+##### `registerProvider(name, config)`
 
-### Email-Based Operations
+Register a new OAuth provider.
 
 ```typescript
-// Get all valid tokens for an email across all providers in a system
-// Note: This returns an array since one email can have tokens from multiple providers
-const emailTokens = await oauth.getAllValidTokensForEmail('user@example.com', systemId);
-// Returns: { provider: string; scopeId: string; token: OAuth2Token; userToken: UserToken }[]
-
-// Get specific token by email (returns single token or null)
-// This enforces the email uniqueness rule within provider/scope
-const token = await oauth.getTokenForEmail('user@example.com', systemId, scopeId, 'google');
-
-// Get valid token for email with auto-refresh
-const validToken = await oauth.getValidTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-  { autoRefresh: true },
-);
-
-// Get access token for email
-const accessToken = await oauth.getAccessTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-);
-
-// Execute with valid token for email
-await oauth.withValidTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-  async (accessToken) => {
-    console.log('Using token for email:', accessToken);
-  },
-);
-
-// Check if email has token for specific provider/scope
-const hasToken = await oauth.hasTokenForEmail('user@example.com', systemId, scopeId, 'google');
-
-// Revoke tokens for email
-await oauth.revokeTokensForEmail('user@example.com', systemId, scopeId, 'google');
+oauth.registerProvider('custom', {
+  clientId: 'xxx',
+  clientSecret: 'xxx',
+  authorizationUrl: 'https://provider.com/oauth/authorize',
+  tokenUrl: 'https://provider.com/oauth/token',
+  redirectUri: 'http://localhost:3000/callback',
+  scopes: ['read'],
+  profileUrl?: 'https://provider.com/api/user',  // Optional
+  usePKCE?: true,                                 // Optional
+});
 ```
 
-### User-Centric Operations (Stateless)
+### Types
 
-For backend APIs where you have explicit user IDs:
+#### OAuth2Config
 
 ```typescript
-// Get access token for specific user/scope/provider
-// Note: Takes the first (most recent) token if multiple exist
-const accessToken = await oauth.getAccessTokenForUser(userId, systemId, scopeId, 'google', {
-  autoRefresh: true,
-});
-
-// Execute with valid token for specific user
-await oauth.withValidTokenForUser(userId, systemId, scopeId, 'google', async (accessToken) => {
-  // Make API calls with the token
-  return apiResponse;
-});
-
-// Get all valid tokens for a user with auto-refresh
-const userTokens = await oauth.getAllValidTokensForUser(userId, {
-  autoRefresh: true,
-  refreshBuffer: 5, // Refresh 5 minutes before expiry
-});
-
-// Check if user has tokens for specific provider/scope
-const hasToken = await oauth.hasTokenForUser(userId, systemId, scopeId, 'google');
-
-// Get user token entity (includes metadata)
-const userToken = await oauth.getUserTokenForUser(userId, systemId, scopeId, 'google');
-
-// Revoke specific tokens
-await oauth.revokeTokensForUser(userId, systemId, scopeId, 'google');
+interface OAuth2Config {
+  clientId: string;
+  clientSecret?: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  redirectUri: string;
+  scopes: string[];
+  profileUrl?: string;
+  usePKCE?: boolean;
+  extraAuthParams?: Record<string, string>;
+}
 ```
 
-### PKCE Support
+#### StoredToken
 
 ```typescript
-// Enable PKCE for enhanced security
-const { url, state } = await oauth.authorize({
-  provider: 'google',
-  usePKCE: true, // Enables PKCE flow
-});
+interface StoredToken {
+  id: string;
+  provider: string;
+  userId: string;
+  email: string;
+  token: OAuth2Token;
+  metadata?: Record<string, any>;
+  createdAt: Date;
+  updatedAt: Date;
+}
 ```
 
-### Token Validation
+#### OAuth2Token
 
 ```typescript
-// Check if token is expired
-const isExpired = oauth.isTokenExpired(token, {
-  expirationBuffer: 60, // Consider expired 60 seconds early
-});
-
-// Ensure valid token (auto-refresh if needed)
-const validToken = await oauth.ensureValidToken('google');
+interface OAuth2Token {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: Date;
+  tokenType: string;
+  scope?: string;
+}
 ```
 
-## 🔒 Security Features
-
-### State Management
+## 🔌 Storage Adapters
 
-- Cryptographically secure state generation
-- Automatic state validation and cleanup
-- Configurable state expiration
+### In-Memory (Default)
 
-### PKCE (Proof Key for Code Exchange)
-
-- Built-in PKCE support for public clients
-- Automatic code verifier generation
-- Enhanced security for mobile and SPA applications
-
-### Token Encryption
-
-- Secure token storage with optional encryption
-- Configurable seal keys for sensitive data
-- Protection against token theft
-
-### Email Validation
-
-- Automatic email conflict detection
-- Profile-based user validation
-- Cross-provider email consistency
-
-## 🧪 Testing
-
-The library includes comprehensive tests using Vitest:
-
-```bash
-# Run tests
-npm test
-
-# Run tests with UI
-npm run test:ui
-
-# Run tests with coverage
-npm run test:coverage
-
-# Watch mode
-npm run test:watch
+```typescript
+const oauth = new OAuth2Client(); // Uses in-memory storage
 ```
 
-## 🏢 Multi-System Examples
-
-### SaaS Platform with Multiple Apps
+### PostgreSQL
 
 ```typescript
-// Create systems for different applications
-const crmSystem = await oauth.createSystem('CRM App');
-const analyticsSystem = await oauth.createSystem('Analytics Dashboard');
-
-// Create scopes for different access levels
-await oauth.useSystem(crmSystem.id);
-const readScope = await oauth.createScope('read-only', {
-  type: 'access',
-  permissions: ['read:contacts', 'read:deals'],
-  isolated: true,
-});
+import { PostgresStorageAdapter } from '@dainprotocol/oauth2-storage-postgres';
 
-const adminScope = await oauth.createScope('admin', {
-  type: 'access',
-  permissions: ['*'],
-  isolated: true,
+const storage = new PostgresStorageAdapter({
+  host: 'localhost',
+  port: 5432,
+  username: 'user',
+  password: 'password',
+  database: 'oauth_tokens',
 });
 
-// Users can have different permissions per system
-const user = await oauth.getOrCreateUser({ email: 'user@company.com' });
-
-// Authorize for specific system/scope
-const { url } = await oauth.authorize({
-  provider: 'google',
-  scopes: ['profile', 'email'],
-});
+const oauth = new OAuth2Client({ storage });
 ```
 
-### Multi-Tenant Application
+### Drizzle ORM
 
 ```typescript
-// Each tenant gets their own system
-const tenantSystem = await oauth.createSystem(`Tenant-${tenantId}`);
-
-// Tenant-specific user management
-await oauth.useSystem(tenantSystem.id);
-const tenantUser = await oauth.getOrCreateUser({
-  email: userEmail,
-  metadata: { tenantId, role: 'admin' },
-});
+import { DrizzleStorageAdapter } from '@dainprotocol/oauth2-storage-drizzle';
+import { drizzle } from 'drizzle-orm/postgres-js';
 
-// Tenant-isolated tokens
-const tokens = await oauth.granular.getTokensBySystem(tenantSystem.id);
+const db = drizzle(/* your db config */);
+const storage = new DrizzleStorageAdapter(db, { dialect: 'postgres' });
+const oauth = new OAuth2Client({ storage });
 ```
 
-## 🚀 Production Deployment
+## 📝 Examples
 
-### Environment Configuration
+### Express.js Integration
 
 ```typescript
+import express from 'express';
+import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
+
+const app = express();
 const oauth = new OAuth2Client({
-  storage: await PostgresStorageFactory.create({
-    host: process.env.DB_HOST,
-    port: parseInt(process.env.DB_PORT || '5432'),
-    username: process.env.DB_USER,
-    password: process.env.DB_PASSWORD,
-    database: process.env.DB_NAME,
-    ssl: {
-      rejectUnauthorized: process.env.NODE_ENV === 'production',
-    },
-    poolSize: 20,
-    logging: process.env.NODE_ENV === 'development',
-  }),
-  sealKey: process.env.OAUTH2_SEAL_KEY, // For token encryption
   providers: {
     google: {
       clientId: process.env.GOOGLE_CLIENT_ID,
       clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-      redirectUri: process.env.GOOGLE_REDIRECT_URI,
-      // ... other config
+      authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+      tokenUrl: 'https://oauth2.googleapis.com/token',
+      redirectUri: 'http://localhost:3000/auth/google/callback',
+      scopes: ['profile', 'email'],
     },
   },
 });
-```
 
-### Performance Optimization
+// Start OAuth flow
+app.get('/auth/:provider', async (req, res) => {
+  const { url, state } = await oauth.authorize({
+    provider: req.params.provider,
+    userId: req.user.id,
+    email: req.user.email,
+  });
+
+  req.session.oauthState = state;
+  res.redirect(url);
+});
 
-```typescript
-// Use token caching for high-traffic scenarios
-const accessToken = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 10, // Refresh early to avoid expiry
+// Handle callback
+app.get('/auth/:provider/callback', async (req, res) => {
+  const { code } = req.query;
+  const { token, profile } = await oauth.handleCallback(code, req.session.oauthState);
+  res.json({ success: true, profile });
 });
 
-// Batch operations for efficiency
-const allTokens = await oauth.getAllValidTokensForUser(userId);
+// Use tokens
+app.get('/api/data', async (req, res) => {
+  const accessToken = await oauth.getAccessToken('google', req.user.email);
+  // Use accessToken for API calls...
+});
+```
+
+### Scheduled Cleanup
 
-// Clean up expired states regularly
+```typescript
+// Clean up expired tokens daily
 setInterval(
   async () => {
-    await oauth.cleanup(10 * 60 * 1000); // 10 minutes
+    const tokens = await oauth.cleanupExpiredTokens();
+    const states = await oauth.cleanupExpiredStates();
+    console.log(`Cleaned up ${tokens} tokens and ${states} states`);
   },
-  5 * 60 * 1000,
-); // Every 5 minutes
+  24 * 60 * 60 * 1000,
+);
 ```
 
-### Error Handling
+### Multiple Providers
 
 ```typescript
-try {
-  const token = await oauth.getAccessToken('google');
-} catch (error) {
-  if (error.message.includes('Token expired')) {
-    // Handle token expiry
-    const { url } = await oauth.authorize({ provider: 'google' });
-    // Redirect to re-authorization
-  } else if (error.message.includes('Provider not found')) {
-    // Handle missing provider
-  }
+// User can connect multiple OAuth accounts
+const providers = ['google', 'github', 'microsoft'];
+
+for (const provider of providers) {
+  const { url, state } = await oauth.authorize({
+    provider,
+    userId: 'user123',
+    email: 'user@example.com',
+  });
+  // Handle each provider...
 }
-```
 
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Development Setup
-
-```bash
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Run tests
-npm test
-
-# Build the project
-npm run build
-
-# Lint and format
-npm run lint:fix
-npm run format
+// Get all connected accounts
+const tokens = await oauth.getTokensByUserId('user123');
+console.log(
+  'Connected accounts:',
+  tokens.map((t) => t.provider),
+);
 ```
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙋‍♂️ Support
-
-- 📚 [Documentation](https://github.com/blureffect/oauth2-token-manager#readme)
-- 🐛 [Issue Tracker](https://github.com/blureffect/oauth2-token-manager/issues)
-- 💬 [Discussions](https://github.com/blureffect/oauth2-token-manager/discussions)
-
-## 🏆 Credits
-
-Created with ❤️ by [Blureffect](https://blureffect.co)
+MIT © Dain Protocol