@dainprotocol/oauth2-token-manager 0.1.1 → 0.1.4

package/README.md

@@ -1,39 +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)
-- [Granular API (Advanced)](#-granular-api-advanced)
-  - [Context-Aware Resolution](#context-aware-resolution)
-  - [User Management](#user-management)
-  - [Token Operations](#token-operations)
-  - [Bulk Operations](#bulk-operations)
-  - [System & Scope Management](#system--scope-management)
-- [Architecture](#-architecture)
+- [Core Concepts](#-core-concepts)
 - [API Reference](#-api-reference)
-- [Storage Adapters](#storage-adapters)
-- [Provider Configuration](#provider-configuration)
-- [Advanced Features](#-advanced-features)
+- [Storage Adapters](#-storage-adapters)
 - [Examples](#-examples)
-- [Production Deployment](#-production-deployment)
 
 ## 🚀 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
-- **🎨 Default Configuration**: Automatic default system and scope creation
-- **💡 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
 
@@ -44,7 +30,7 @@ npm install @dainprotocol/oauth2-token-manager
 ### Storage Adapters
 
 ```bash
-# PostgreSQL adapter
+# PostgreSQL adapter (TypeORM based)
 npm install @dainprotocol/oauth2-storage-postgres
 
 # Drizzle adapter (supports PostgreSQL, MySQL, SQLite)
@@ -53,814 +39,358 @@ npm install @dainprotocol/oauth2-storage-drizzle
 
 ## 🚀 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'],
+// Initialize with provider configurations
+const oauth = new OAuth2Client({
+  providers: {
+    google: {
+      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: {
+      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 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);
-
-// === NEW: Simplified Granular API (V2) ===
-// Access tokens without specifying system/scope IDs
-const accessToken = await oauth.granularV2.getAccessToken({
+  userId: 'user123',
   email: 'user@example.com',
-  provider: 'google',
+  scopes: ['profile', 'email'],
 });
-```
-
-## 🎯 Granular API (Advanced)
-
-The granular API (`oauth.granularV2`) provides full control over the token hierarchy with intelligent system and scope resolution. It's the recommended way to interact with tokens when you need fine-grained control.
-
-### Context-Aware Resolution
 
-The API follows this priority order for resolving system and scope:
+// Redirect user to authorization URL
+res.redirect(url);
 
-1. **Explicit parameters** - If you provide systemId/scopeId in the method call, those are used
-2. **Context from OAuth2Client** - If not provided, it checks the current context (useSystem/setDefaultScope)
-3. **Default system/scope** - If no context is set, it falls back to the default system and scope
+// Handle OAuth callback
+const { token, profile } = await oauth.handleCallback(code, state);
 
-```typescript
-// === Context-Aware Usage ===
-
-// Set context in main client
-await oauth.useSystem('production-system');
-oauth.setDefaultScope('api-access');
-
-// Granular V2 will now use this context automatically
-const user = await oauth.granularV2.getOrCreateUser({
-  email: 'user@example.com',
-  options: { metadata: { role: 'user' } },
-  // No need to specify systemId - uses 'production-system' from context
-});
-
-// Token operations use the context scope
-const token = await oauth.granularV2.getAccessToken({
-  email: 'user@example.com',
-  provider: 'google',
-  // No need to specify scopeId - uses 'api-access' from context
-});
-
-// Override with explicit parameters when needed
-const differentToken = await oauth.granularV2.getAccessToken({
-  email: 'user@example.com',
-  provider: 'google',
-  systemId: 'another-system', // This takes precedence
-  scopeId: 'different-scope', // This takes precedence
-});
+// Use the token
+const accessToken = await oauth.getAccessToken('google', 'user@example.com');
 ```
 
-### User Management
+## 🔑 Core Concepts
 
-```typescript
-// Create or get users with optional system specification
-const user = await oauth.granularV2.getOrCreateUser({
-  email: 'user@example.com',
-  options: { metadata: { role: 'admin' } },
-  // systemId is optional - uses context or defaults
-});
+### How It Works
 
-// Find users by various criteria
-const userByEmail = await oauth.granularV2.findUserByEmail({
-  email: 'user@example.com',
-});
+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)
 
-const userByExternalId = await oauth.granularV2.findUserByExternalId({
-  externalId: 'external-123',
-});
+## 📚 API Reference
 
-// Get all users in a system
-const systemUsers = await oauth.granularV2.getUsersBySystem();
-// Or specify a different system
-const otherSystemUsers = await oauth.granularV2.getUsersBySystem('other-system-id');
-```
+### OAuth2Client
 
-### Token Operations
+The main class for managing OAuth2 tokens.
 
 ```typescript
-// Save new tokens
-const savedToken = await oauth.granularV2.saveToken({
-  userId: user.id,
-  provider: 'google',
-  email: 'user@example.com',
-  token: oauthToken,
-  // systemId and scopeId are optional
-});
-
-// Query tokens with flexible parameters
-const userTokens = await oauth.granularV2.getTokens({
-  userId: user.id,
-});
-
-const providerTokens = await oauth.granularV2.getTokens({
-  userId: user.id,
-  provider: 'google',
-});
-
-const emailTokens = await oauth.granularV2.getTokens({
-  email: 'user@example.com',
-  // systemId resolved from context or defaults
-});
-
-// Get valid tokens with auto-refresh
-const validToken = await oauth.granularV2.getValidToken({
-  email: 'user@example.com',
-  provider: 'google',
-  options: {
-    autoRefresh: true,
-    refreshBuffer: 5, // Refresh 5 minutes before expiry
-  },
-});
-
-// Get access token directly
-const accessToken = await oauth.granularV2.getAccessToken({
-  userId: user.id,
-  provider: 'google',
+const oauth = new OAuth2Client({
+  storage?: StorageAdapter,  // Optional, defaults to in-memory
+  providers?: {              // OAuth provider configurations
+    [name: string]: OAuth2Config
+  }
 });
-
-// Execute with valid token
-await oauth.granularV2.withValidToken(
-  {
-    email: 'user@example.com',
-    provider: 'google',
-  },
-  async (accessToken) => {
-    // Make API calls with the token
-    const response = await fetch('https://api.example.com/data', {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    });
-    return response.json();
-  },
-);
 ```
 
-### Bulk Operations
+### Methods
 
-```typescript
-// Get all valid tokens for a user
-const allUserTokens = await oauth.granularV2.getAllValidTokens({
-  userId: user.id,
-  options: { autoRefresh: true },
-});
+#### 🔐 OAuth Flow
 
-// Get all valid tokens for an email
-const allEmailTokens = await oauth.granularV2.getAllValidTokens({
-  email: 'user@example.com',
-});
+##### `authorize(options)`
 
-// Filter by provider
-const googleTokens = await oauth.granularV2.getAllValidTokens({
-  email: 'user@example.com',
-  provider: 'google',
-});
+Start OAuth2 authorization flow.
 
-// Check token existence
-const hasToken = await oauth.granularV2.hasToken({
-  email: 'user@example.com',
+```typescript
+const { url, state } = await oauth.authorize({
   provider: 'google',
-});
-
-// Delete tokens
-await oauth.granularV2.deleteTokens({
+  userId: 'user123',
   email: 'user@example.com',
-  provider: 'google',
-});
-
-// Delete all tokens for a user
-await oauth.granularV2.deleteTokens({
-  userId: user.id,
+  scopes?: ['profile', 'email'],  // Optional
+  usePKCE?: true,                  // Optional
+  metadata?: { source: 'signup' }  // Optional
 });
+// Redirect user to `url`
 ```
 
-### System & Scope Management
+##### `handleCallback(code, state)`
 
-```typescript
-// Get current defaults
-const defaultSystem = await oauth.granularV2.getSystem();
-const defaultScope = await oauth.granularV2.getScope();
-
-// Create new scope in current/default system
-const newScope = await oauth.granularV2.createScope({
-  name: 'api-access',
-  type: 'access',
-  permissions: ['read', 'write'],
-  isolated: true,
-});
-
-// Create scope in specific system
-const anotherScope = await oauth.granularV2.createScope({
-  systemId: 'specific-system-id',
-  name: 'admin-access',
-  type: 'access',
-  permissions: ['*'],
-});
+Handle OAuth2 callback and save tokens.
 
-// Get all scopes in current system
-const scopes = await oauth.granularV2.getScopesBySystem();
-
-// Initialize defaults explicitly if needed
-const { system, scope } = await oauth.granularV2.ensureDefaults();
+```typescript
+const { token, profile } = await oauth.handleCallback(code, state);
+// token: { id, provider, userId, email, token, metadata, ... }
+// profile: { id, email, name, picture, raw } or undefined
 ```
 
-### Why Use Granular API?
-
-The granular API is ideal for:
-
-- **Single-system applications** - Simplified usage with automatic defaults
-- **Multi-tenant applications** - Easy context switching between systems
-- **Backend services** - Stateless operations with explicit parameters
-- **Complex token management** - Full control over token lifecycle
-- **Gradual migration** - Start simple, add complexity as needed
+#### 🔑 Token Management
 
-## 🏗️ Architecture
+##### `getAccessToken(provider, email, options?)`
 
-### Core Components
+Get access token string (auto-refreshes if expired).
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     OAuth2Client                            │
-│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
-│  │  Context API    │    │    Granular API V2             │ │
-│  │  (Simplified)   │    │  (Full Control + Smart)        │ │
-│  └─────────────────┘    └─────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              │               │               │
-    ┌─────────▼────────┐ ┌───▼────────┐ ┌───▼─────────┐
-    │   Providers      │ │  Storage   │ │   Profile   │
-    │   (OAuth2)       │ │  Adapter   │ │  Fetchers   │
-    └──────────────────┘ └────────────┘ └─────────────┘
+```typescript
+const accessToken = await oauth.getAccessToken('google', 'user@example.com');
+// Returns: "ya29.a0AfH6SMBx..."
 ```
 
-### Data Model & Token Hierarchy
+##### `getValidToken(provider, email, options?)`
 
-**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.
+Get full token object (auto-refreshes if expired).
 
 ```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;
-}
+const token = await oauth.getValidToken('google', 'user@example.com');
+// Returns: { accessToken, refreshToken, expiresAt, tokenType, scope, ... }
 ```
 
-### Token Hierarchy Rules
+#### 🔍 Token Queries
 
-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
+##### `getTokensByUserId(userId)`
 
-### Default System and Scope
-
-The library provides automatic initialization of a default system and scope for simplified usage:
+Get all tokens for a user.
 
 ```typescript
-import {
-  DEFAULT_SYSTEM_NAME,
-  DEFAULT_SCOPE_NAME,
-  initializeDefaults,
-} from '@dainprotocol/oauth2-token-manager';
-
-// Automatic initialization
-const oauth = new OAuth2Client({
-  providers: {
-    /* ... */
-  },
-});
-
-// If no system/scope is set, they will be automatically initialized on first use
-const { url, state } = await oauth.authorize({ provider: 'google' });
-
-// Or manually initialize defaults
-await oauth.initializeDefaults();
-
-// Check if defaults exist
-const defaultSystem = await oauth.getDefaultSystem();
-const defaultScope = await oauth.getDefaultScope();
-
-// Default constants
-console.log(DEFAULT_SYSTEM_NAME); // 'oauth2-token-manager-default-system'
-console.log(DEFAULT_SCOPE_NAME); // 'oauth2-token-manager-default-scope'
+const tokens = await oauth.getTokensByUserId('user123');
+// Returns: StoredToken[]
 ```
 
-The default system and scope are created with:
+##### `getTokensByEmail(email)`
 
-- **System**: Name-based identification, includes metadata `{ isDefault: true }`
-- **Scope**: Type 'access', permissions ['read', 'write'], not isolated
+Get all tokens for an email.
 
-## 📚 API Reference
+```typescript
+const tokens = await oauth.getTokensByEmail('user@example.com');
+// Returns: StoredToken[]
+```
 
-### OAuth2Client
+#### 🗑️ Token Cleanup
 
-The main client class providing both context-managed and granular APIs.
+##### `deleteToken(provider, email)`
 
-#### Context-Managed API (Recommended for Simple Use Cases)
+Delete a specific token.
 
 ```typescript
-// System management
-await oauth.createSystem('MyApp');
-await oauth.getOrCreateSystem('MyApp'); // Idempotent - returns existing if found
-await oauth.useSystem(systemId);
-
-// Scope management
-await oauth.createScope('api-access');
-await oauth.getOrCreateScope('api-access'); // Idempotent - returns existing if found
-
-// Default system/scope (automatic initialization)
-await oauth.initializeDefaults(); // Creates default system and scope if they don't exist
-const defaultSystem = await oauth.getDefaultSystem();
-const defaultScope = await oauth.getDefaultScope();
-
-// User management
-const user = await oauth.getOrCreateUser({ email: 'user@example.com' });
-await oauth.useUser(userId);
-
-// Authorization flow
-const { url, state } = await oauth.authorize({ provider: 'google' });
-const result = await oauth.handleCallback(code, state);
-
-// 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');
-
-// Get all user tokens with auto-refresh (for current user)
-const userTokens = await oauth.getUserTokens();
-
-// Get all valid tokens for a specific user
-const allTokens = await oauth.getAllValidTokensForUser(userId);
-// Returns: { provider: string; scopeId: string; token: OAuth2Token; userToken: UserToken }[]
-
-// Revoke tokens (uses current context)
-await oauth.revokeTokens('google'); // Revokes for current user/scope/provider
+const deleted = await oauth.deleteToken('google', 'user@example.com');
+// Returns: boolean
 ```
 
-### Storage Adapters
+##### `cleanupExpiredTokens()`
 
-#### Built-in Memory Adapter
+Delete all expired tokens.
 
 ```typescript
-import { InMemoryStorageAdapter } from '@dainprotocol/oauth2-token-manager';
-
-const storage = new InMemoryStorageAdapter();
-const oauth = new OAuth2Client({ storage });
+const count = await oauth.cleanupExpiredTokens();
+// Returns: number of deleted tokens
 ```
 
-#### PostgreSQL Adapter
+##### `cleanupExpiredStates()`
 
-```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',
-});
-```
-
-#### Drizzle Adapter (Multi-Database)
+Delete expired authorization states (older than 10 minutes).
 
 ```typescript
-import { DrizzleStorageFactory } from '@dainprotocol/oauth2-storage-drizzle';
-
-// PostgreSQL
-const pgStorage = await DrizzleStorageFactory.create({
-  type: 'postgresql',
-  config: {
-    host: 'localhost',
-    port: 5432,
-    user: 'oauth2_user',
-    password: 'password',
-    database: 'oauth2_db',
-  },
-});
-
-// MySQL
-const mysqlStorage = await DrizzleStorageFactory.create({
-  type: 'mysql',
-  config: {
-    host: 'localhost',
-    port: 3306,
-    user: 'oauth2_user',
-    password: 'password',
-    database: 'oauth2_db',
-  },
-});
-
-// SQLite
-const sqliteStorage = await DrizzleStorageFactory.create({
-  type: 'sqlite',
-  config: {
-    filename: './oauth2.db',
-  },
-});
+const count = await oauth.cleanupExpiredStates();
+// Returns: number of deleted states
 ```
 
-#### Custom Storage Adapter
+#### ⚙️ Provider Management
 
-```typescript
-import { StorageAdapter } from '@dainprotocol/oauth2-token-manager';
+##### `registerProvider(name, config)`
 
-class MyCustomAdapter implements StorageAdapter {
-  // System operations
-  async createSystem(system) {
-    /* implement */
-  }
-  async getOrCreateSystem(system) {
-    // Find by name, create if not exists
-    /* implement */
-  }
-  async getSystem(id) {
-    /* implement */
-  }
+Register a new OAuth provider.
 
-  // Scope operations
-  async createScope(scope) {
-    /* implement */
-  }
-  async getOrCreateScope(scope) {
-    // Find by systemId + name, create if not exists
-    /* implement */
-  }
-
-  // User operations
-  async getOrCreateUser(input) {
-    // Find by email or externalId, create if not exists
-    /* implement */
-  }
-
-  // ... implement all required methods
-}
+```typescript
+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
+});
 ```
 
-### Provider Configuration
+### Types
 
-#### Google OAuth2
+#### OAuth2Config
 
 ```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
-  }
+interface OAuth2Config {
+  clientId: string;
+  clientSecret?: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  redirectUri: string;
+  scopes: string[];
+  profileUrl?: string;
+  usePKCE?: boolean;
+  extraAuthParams?: Record<string, string>;
 }
 ```
 
-#### GitHub OAuth2
+#### StoredToken
 
 ```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',
-  }
+interface StoredToken {
+  id: string;
+  provider: string;
+  userId: string;
+  email: string;
+  token: OAuth2Token;
+  metadata?: Record<string, any>;
+  createdAt: Date;
+  updatedAt: Date;
 }
 ```
 
-#### Generic Provider
+#### OAuth2Token
 
 ```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
-  }
+interface OAuth2Token {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: Date;
+  tokenType: string;
+  scope?: string;
 }
 ```
 
-## 🔧 Advanced Features
+## 🔌 Storage Adapters
 
-### Token Auto-Refresh
+### In-Memory (Default)
 
 ```typescript
-const accessToken = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 10, // Refresh early to avoid expiry
-  expirationBuffer: 30, // Consider expired 30 seconds early
-});
+const oauth = new OAuth2Client(); // Uses in-memory storage
 ```
 
-### Profile-Based Token Management
+### PostgreSQL
 
 ```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
-  },
-});
-```
-
-### PKCE Support
-
-```typescript
-// Enable PKCE for enhanced security
-const { url, state } = await oauth.authorize({
-  provider: 'google',
-  usePKCE: true, // Enables PKCE flow
-});
-```
-
-### Token Validation
-
-```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');
-```
-
-## 🏢 Examples
+import { PostgresStorageAdapter } from '@dainprotocol/oauth2-storage-postgres';
 
-### Multi-Tenant Application
-
-```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' },
+const storage = new PostgresStorageAdapter({
+  host: 'localhost',
+  port: 5432,
+  username: 'user',
+  password: 'password',
+  database: 'oauth_tokens',
 });
 
-// Tenant-isolated tokens
-const tokens = await oauth.granularV2.getTokens({ systemId: tenantSystem.id });
+const oauth = new OAuth2Client({ storage });
 ```
 
-### SaaS Platform with Multiple Apps
+### Drizzle ORM
 
 ```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,
-});
-
-const adminScope = await oauth.createScope('admin', {
-  type: 'access',
-  permissions: ['*'],
-  isolated: true,
-});
+import { DrizzleStorageAdapter } from '@dainprotocol/oauth2-storage-drizzle';
+import { drizzle } from 'drizzle-orm/postgres-js';
 
-// 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 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,
+  });
 
-```typescript
-// Use token caching for high-traffic scenarios
-const accessToken = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 10, // Refresh early to avoid expiry
+  req.session.oauthState = state;
+  res.redirect(url);
 });
 
-// Batch operations for efficiency
-const allTokens = await oauth.getAllValidTokensForUser(userId);
+// 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 });
+});
 
-// Clean up expired states regularly
-setInterval(
-  async () => {
-    await oauth.cleanup(10 * 60 * 1000); // 10 minutes
-  },
-  5 * 60 * 1000,
-); // Every 5 minutes
+// Use tokens
+app.get('/api/data', async (req, res) => {
+  const accessToken = await oauth.getAccessToken('google', req.user.email);
+  // Use accessToken for API calls...
+});
 ```
 
-### Error Handling
+### Scheduled Cleanup
 
 ```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
-  }
-}
-```
-
-## 🔒 Security Features
-
-### State Management
-
-- Cryptographically secure state generation
-- Automatic state validation and cleanup
-- Configurable state expiration
-
-### 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
+// Clean up expired tokens daily
+setInterval(
+  async () => {
+    const tokens = await oauth.cleanupExpiredTokens();
+    const states = await oauth.cleanupExpiredStates();
+    console.log(`Cleaned up ${tokens} tokens and ${states} states`);
+  },
+  24 * 60 * 60 * 1000,
+);
 ```
 
-## 🤝 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
+### Multiple Providers
 
-# Run tests
-npm test
+```typescript
+// User can connect multiple OAuth accounts
+const providers = ['google', 'github', 'microsoft'];
 
-# Build the project
-npm run build
+for (const provider of providers) {
+  const { url, state } = await oauth.authorize({
+    provider,
+    userId: 'user123',
+    email: 'user@example.com',
+  });
+  // Handle each provider...
+}
 
-# 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/dainprotocol/oauth2-token-manager#readme)
-- 🐛 [Issue Tracker](https://github.com/dainprotocol/oauth2-token-manager/issues)
-- 💬 [Discussions](https://github.com/dainprotocol/oauth2-token-manager/discussions)
+MIT © Dain Protocol