		@@ -1,10 +0,15 @@
		# Reclaim Identity
		# Reclaim Identity JS SDK

		Reclaim Identity is a JavaScript library for integrating Reclaim Protocol authentication into browser applications. It provides a simple interface for handling user authentication, including sign-in, sign-out, and monitoring authentication state changes.
		Reclaim Identity is a JavaScript SDK that provides seamless integration with Reclaim Protocol's authentication system. The SDK manages OAuth 2.0 flows, popup windows, token management, and user session handling.

		## Features

		- Simple API for authentication operations
		- Event-based auth state changes
		- Secure token handling
		- Simple OAuth 2.0 authentication flow
		- Popup-based authentication
		- Secure token management with httpOnly cookies
		- Event-based state management
		- CSRF protection
		- Session handling
		- AMD module support
		- Singleton pattern implementation

		@@ -16,3 +21,3 @@ ## Installation
		```bash
		npm install reclaim-identity-js
		npm install @reclaim/identity-js
		```
		@@ -22,14 +27,8 @@

		You can use Identity Js directly from a CDN via a script tag:
		Include directly via CDN:

		```html
		<script src="https://unpkg.com/reclaim-identity-js@1.0.4/dist/reclaimAuth.min.js"></script>
		<script src="https://unpkg.com/@reclaim/identity-js@latest"></script>
		```

		Or, if you prefer jsDelivr:

		```html
		<script src="https://cdn.jsdelivr.net/npm/reclaim-identity-js@1.0.4/dist/reclaimAuth.min.js"></script>
		```

		## Usage
		@@ -39,29 +38,28 @@

		```html
		<script src="https://unpkg.com/reclaim-identity-js@1.0.4/dist/reclaimAuth.min.js"></script>
		<script>
		const clientId = 'your-client-id';
		const redirectUri = 'your-redirect-uri';
		const reclaimAuth = getReclaimAuth(clientId, redirectUri);
		</script>
		```javascript
		const clientId = 'your-client-id';
		const redirectUri = 'your-redirect-uri';
		const reclaimAuth = getReclaimAuth(clientId, redirectUri);
		```

		### Sign In
		### Authentication

		```javascript
		// Sign In
		reclaimAuth.signIn()
		.then(user => {
		console.log('Signed in user:', user);
		console.log('Signed in:', user);
		})
		.catch(error => {
		console.error('Sign in error:', error);
		if (error.message.includes('popup')) {
		console.error('Popup was blocked');
		} else {
		console.error('Authentication error:', error);
		}
		});
		```

		### Sign Out

		```javascript
		// Sign Out
		reclaimAuth.signOut()
		.then(() => {
		console.log('User signed out successfully');
		console.log('Signed out successfully');
		})
		@@ -71,28 +69,20 @@ .catch(error => {
		});
		```

		### Get Current User

		```javascript
		// Get Current User
		const user = reclaimAuth.getCurrentUser();
		if (user) {
		console.log('Current user:', user);
		} else {
		console.log('No user is currently signed in');
		}
		```

		### Listen for Auth State Changes

		```javascript
		reclaimAuth.onAuthStateChanged(user => {
		// Listen for Auth State Changes
		const unsubscribe = reclaimAuth.onAuthStateChanged(user => {
		if (user) {
		console.log('User is signed in:', user);
		console.log('User state changed:', user);
		} else {
		console.log('User is signed out');
		console.log('User signed out');
		}
		});

		// Clean up listener when done
		unsubscribe();
		```

		## Browser Example
		### Complete Browser Example

		@@ -105,43 +95,45 @@ ```html
		<meta name="viewport" content="width=device-width, initial-scale=1.0">
		<title>ReclaimAuth Demo</title>
		<title>Reclaim Identity Demo</title>
		</head>
		<body>
		<h1>ReclaimAuth Demo</h1>
		<button id="signInButton">Sign In</button>
		<button id="signOutButton">Sign Out</button>
		<div id="userInfo"></div>
		<div>
		<button id="signInBtn">Sign In</button>
		<button id="signOutBtn">Sign Out</button>
		<div id="userInfo"></div>
		</div>

		<script src="https://unpkg.com/reclaim-identity-js@1.0.4/dist/reclaimAuth.min.js"></script>
		<script src="https://unpkg.com/@reclaim/identity-js@latest"></script>
		<script>
		const clientId = 'your-client-id';
		const redirectUri = 'your-redirect-uri';
		const reclaimAuth = getReclaimAuth(clientId, redirectUri);
		const auth = getReclaimAuth(
		'your-client-id',
		'your-redirect-uri'
		);

		document.getElementById('signInButton').addEventListener('click', () => {
		reclaimAuth.signIn()
		.then(user => {
		console.log('Signed in user:', user);
		document.getElementById('userInfo').textContent = JSON.stringify(user);
		})
		.catch(error => {
		console.error('Sign in error:', error);
		});
		// Handle Auth State Changes
		auth.onAuthStateChanged(user => {
		const userInfo = document.getElementById('userInfo');
		if (user) {
		userInfo.textContent = JSON.stringify(user, null, 2);
		} else {
		userInfo.textContent = 'No user signed in';
		}
		});

		document.getElementById('signOutButton').addEventListener('click', () => {
		reclaimAuth.signOut()
		.then(() => {
		console.log('User signed out successfully');
		document.getElementById('userInfo').textContent = 'No user signed in';
		})
		.catch(error => {
		console.error('Sign out error:', error);
		});
		// Sign In Handler
		document.getElementById('signInBtn').addEventListener('click', async () => {
		try {
		const user = await auth.signIn();
		console.log('Signed in successfully:', user);
		} catch (error) {
		console.error('Sign in failed:', error);
		}
		});

		reclaimAuth.onAuthStateChanged(user => {
		if (user) {
		console.log('User is signed in:', user);
		} else {
		console.log('User is signed out');
		// Sign Out Handler
		document.getElementById('signOutBtn').addEventListener('click', async () => {
		try {
		await auth.signOut();
		console.log('Signed out successfully');
		} catch (error) {
		console.error('Sign out failed:', error);
		}
		@@ -154,27 +146,163 @@ });

		## Important Notes
		## API Reference

		- Always keep your `clientId` and `redirectUri` secure and never expose them in client-side code in production environments.
		- The library uses the `fetch` API, which is natively available in modern browsers.
		### getReclaimAuth(clientId: string, redirectUri: string)

		## Building from Source
		Returns a singleton instance of the ReclaimAuth class. Both parameters are required for initial setup.

		If you want to build the library from source:
		### auth.signIn(): Promise<User>

		1. Clone the repository
		2. Install dependencies: `npm install`
		3. Build the library: `npm run build`
		Initiates the authentication flow by opening a popup window. Returns a promise that resolves with the user data.

		This will create a `dist/reclaimAuth.min.js` file that can be used in browser environments.
		### auth.signOut(): Promise<void>

		## License
		Signs out the current user and clears authentication state.

		This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
		### auth.getCurrentUser(): User \| null

		## Contributing
		Returns the currently authenticated user or null if not authenticated.

		Contributions are welcome! Please feel free to submit a Pull Request.
		### auth.onAuthStateChanged(callback: (user: User \| null) => void): () => void

		Subscribes to authentication state changes. Returns an unsubscribe function.

		## Configuration

		The SDK uses the following defaults:

		```javascript
		{
		apiBaseUrl: 'https://identity.reclaimprotocol.org',
		env: 'production',
		popupWidth: 600,
		popupHeight: 600
		}
		```

		## Security Features

		- CSRF protection using state parameter
		- Secure cookie handling
		- Origin validation for popup messages
		- Cross-window communication security
		- Credentials included in API requests

		## Browser Compatibility

		The SDK requires browsers with support for:
		- Web Crypto API for secure random values
		- Fetch API for network requests
		- PostMessage API for popup communication
		- ES6+ features (can be polyfilled)
		- Cookies

		## Error Handling

		Common error scenarios:

		```javascript
		try {
		await auth.signIn();
		} catch (error) {
		switch (true) {
		case error.message.includes('popup'):
		// Handle popup blocked
		break;
		case error.message.includes('code'):
		// Handle authorization code error
		break;
		case error.message.includes('token'):
		// Handle token exchange error
		break;
		default:
		// Handle other errors
		}
		}
		```

		## Advanced Usage

		### Custom Event Handling

		```javascript
		class AuthenticationManager {
		constructor() {
		this.auth = getReclaimAuth(clientId, redirectUri);
		this.setupAuthListeners();
		}

		setupAuthListeners() {
		this.unsubscribe = this.auth.onAuthStateChanged(user => {
		if (user) {
		this.handleSignedIn(user);
		} else {
		this.handleSignedOut();
		}
		});
		}

		async handleSignedIn(user) {
		// Handle successful sign in
		}

		async handleSignedOut() {
		// Handle sign out
		}

		cleanup() {
		// Clean up listeners
		this.unsubscribe();
		}
		}
		```

		## Best Practices

		1. Error Handling
		- Always implement proper error handling for authentication operations
		- Handle popup blocking scenarios
		- Implement proper cleanup for event listeners

		2. Security
		- Use HTTPS in production
		- Store client credentials securely
		- Implement proper CORS settings
		- Validate authentication state consistently

		3. User Experience
		- Handle loading states during authentication
		- Provide clear feedback for authentication errors
		- Implement proper session management
		- Handle page refreshes gracefully

		## Troubleshooting

		Common issues and solutions:

		1. Popup Blocked
		- Ensure signIn is called in response to user action
		- Check browser popup settings

		2. Authentication Failures
		- Verify clientId and redirectUri
		- Check network requests
		- Verify cookie settings

		3. Security Errors
		- Check origin settings
		- Verify CORS configuration
		- Validate SSL certificates

		## Support

		If you encounter any issues or have questions, please email dwik@creatoros.co
		For issues, questions, or feature requests:
		- Email: dwik@creatoros.co
		- Documentation: [Reclaim Protocol Docs]

		## License

		MIT License - see LICENSE for details

		## Contributing

		Contributions are welcome! Please read our contributing guidelines for details.

reclaim-identity-js - npm Package Compare versions

Improved metrics