@humanmark/sdk-js
Version:
Browser-native JavaScript SDK for Humanmark human verification challenges
190 lines (141 loc) • 7.5 kB
Markdown
<img src="./LogoWordmarkLightBG.svg" width="300" alt="Humanmark Logo">
# Humanmark JavaScript SDK
A browser-native JavaScript SDK for integrating Humanmark human verification challenges into web applications. Complete documentation can be found at https://humanmark.dev.
> **Beta Notice:** Humanmark SDK is currently in beta. While the API is stable, minor changes may occur before the 1.0 release. To get started, email sales@humanmark.io for API credentials.
## What is Humanmark?
Humanmark is a privacy-first human verification service that helps protect your applications from automation and automated abuse. Unlike traditional CAPTCHAs, Humanmark provides a seamless verification experience through mobile app integration - users simply tap a button on their phone to prove they're human.
This SDK enables you to integrate Humanmark verification into your web applications with just a few lines of code. When verification is needed, users see a QR code (on desktop) or a button (on mobile) that connects to the Humanmark mobile app for instant, frictionless verification.
## Why Humanmark?
- **Real Privacy** - We verify users are human, not who they are. No behavior tracking, no personal data collection, no profiles.
- **Actually Works** - CAPTCHAs don't work anymore. AI solves them faster than humans. Humanmark uses device security that AI can't fake.
- **User Friendly** - No puzzles to solve or distorted text to decipher. Just a quick tap using their phone's built-in security.
- **Developer Friendly** - Simple integration, comprehensive TypeScript support, and no complex backend infrastructure needed.
## Features
- **Zero Backend Dependencies** - Pure browser JavaScript with no Node.js requirements
- **Secure Architecture** - Pre-created challenge tokens prevent API secret exposure in client code
- **TypeScript Native** - Full type definitions with strict mode for enhanced developer experience
- **Universal Compatibility** - ESM, UMD, and IIFE bundles for any JavaScript environment
- **Mobile Optimized** - Automatic device detection with native app deep linking
- **Privacy by Design** - No user data collection, no cookies, no tracking
- **Minimal Footprint** - ~21KB gzipped with lazy loading and code splitting for optimal performance
- **Theme Flexibility** - Dark, light, and auto themes that respect system preferences
## Prerequisites
- **HTTPS Required** - The SDK requires your site to be served over HTTPS for security
- **Modern Browser** - See [Browser Support](#browser-support) section for minimum versions
- **API Credentials** - Currently in beta, email sales@humanmark.io to get started
## Installation
### NPM
```bash
npm install @humanmark/sdk-js
```
### CDN
Use our pre-built bundles from a CDN with Subresource Integrity (SRI) for security. The SRI hashes shown below are automatically updated for each published version:
```html
<!-- Browser bundle (IIFE) -->
<script
src="https://cdn.jsdelivr.net/npm/@humanmark/sdk-js@1.0.2/dist/browser/index.js"
integrity="sha384-0X+O8B+znBFKudTV6ZldU8DdDPyqttKh1MfLeDizFcPjgItGj3X1TSQHaoUxbUA6"
crossorigin="anonymous">
</script>
<!-- Or UMD bundle -->
<script
src="https://cdn.jsdelivr.net/npm/@humanmark/sdk-js@1.0.2/dist/umd/index.js"
integrity="sha384-orJMcRxyJ5CKKjVY47b3lIpy9jeCGLQdwgBu7uz3k3DDDJPQzrdj112JM3xBUhtu"
crossorigin="anonymous">
</script>
```
## Quick Start
The SDK requires a pre-created challenge token from your backend:
```javascript
// 1. Get challenge token from your backend
const response = await fetch('/api/create-challenge');
const { challengeToken } = await response.json();
// 2. Initialize the SDK
const sdk = new HumanmarkSdk({
apiKey: 'your-api-key',
challengeToken: challengeToken
});
// 3. Start verification
try {
const receipt = await sdk.verify();
// Send receipt to your backend for verification
console.log('Receipt:', receipt);
} catch (error) {
if (error.code === 'USER_CANCELLED') {
console.log('User cancelled verification');
} else {
console.error('Verification failed:', error);
}
}
```
### Backend Integration
Your backend should create challenge tokens using your API key and secret. For complete integration examples, see our [Getting Started Guide](https://humanmark.dev/getting-started).
```javascript
// Backend example (Node.js)
app.post('/api/create-challenge', async (req, res) => {
const response = await fetch('https://humanmark.io/api/v1/challenge/create', {
method: 'POST',
headers: {
'hm-api-key': API_KEY,
'hm-api-secret': API_SECRET,
'Content-Type': 'application/json'
},
body: JSON.stringify({ domain: 'your-domain.com' })
});
const { token } = await response.json();
res.json({ challengeToken: token });
});
```
## Configuration Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `apiKey` | string | Yes | Your Humanmark API key |
| `challengeToken` | string | Yes | Pre-created challenge token from your backend |
| `baseUrl` | string | No | Base URL for API requests (default: 'https://humanmark.io') |
| `theme` | 'light' \| 'dark' \| 'auto' | No | Modal theme (default: 'auto'). 'auto' follows system preference |
For a complete API reference, visit [https://humanmark.dev/api](https://humanmark.dev/api).
## Error Handling
The SDK provides specific error codes to help handle different scenarios:
```javascript
import { HumanmarkSdk, ErrorCode, isHumanmarkError } from '@humanmark/sdk-js';
try {
const receipt = await sdk.verify();
} catch (error) {
// Handle specific error codes
if (isHumanmarkError(error)) {
switch (error.code) {
case ErrorCode.USER_CANCELLED:
console.log('User cancelled verification');
return;
case ErrorCode.CHALLENGE_EXPIRED:
console.error('Challenge expired. Please try again.');
break;
default:
console.error(`Verification failed: ${error.message}`);
}
}
}
```
## Browser Support
- Chrome 80+
- Firefox 78+
- Safari 13.1+
- Edge 80+
## Security
The SDK implements defense-in-depth security principles to protect your application and users:
**Token-Based Architecture** - The SDK requires pre-created challenge tokens from your backend, ensuring API secrets never leave your server. This prevents credential exposure in client-side code.
**Content Security Policy (CSP) Compliance** - No use of `eval()`, `innerHTML`, or other dynamic code execution. The SDK works seamlessly with strict CSP policies.
**Network Security** - All API communications require HTTPS. The SDK includes built-in timeout protection and validates all server responses.
**Subresource Integrity (SRI)** - When using CDN delivery, SRI hashes are automatically generated for each release to prevent tampering.
**DOM Isolation** - All styles are scoped to prevent CSS conflicts. The SDK makes minimal DOM modifications and properly cleans up all elements and event listeners.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- Documentation: https://humanmark.dev
- GitHub: https://github.com/humanmark/sdk-js
- Email: support@humanmark.io
- Security issues: security@humanmark.io