@createlex/onetapforms-sdk 1.1.4 → 1.2.0

package/README.md

@@ -1,259 +1,320 @@
 # @createlex/onetapforms-sdk
 
-OneTapForms SDK for secure, biometric-authenticated form completion. This SDK enables websites to offer instant form completion through Face ID/Touch ID authentication on iOS devices.
+OneTapForms SDK for secure, biometric-authenticated form completion. Enable instant form completion through Face ID/Touch ID authentication on iOS devices.
 
-## 🆓 Free for Developers
+## Quick Start (30 seconds)
 
-**The SDK is completely free to use!** There are no fees, usage limits, or restrictions for developers integrating OneTapForms into their websites.
+Choose the installation method that matches your skill level:
 
-### Why Developers Love OneTapForms
+### Option 1: Script Tag (Easiest - No Build Tools Required)
 
-Integrating OneTapForms benefits your business directly:
+Perfect for HTML websites, WordPress, or any site where you can add a script tag:
 
-- ⚡ **Faster Form Completion** - Users fill forms in seconds instead of minutes
-- 📈 **Higher Conversion Rates** - Reduce form abandonment with one-tap completion
-- 🎯 **Better User Experience** - Eliminate typing errors and friction
-- 🔒 **Verified Data** - Receive pre-verified, accurate user information
-- 💰 **No Cost to You** - Free SDK, zero integration fees
+```html
+<!-- 1. Add the script to your page -->
+<script src="https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js"></script>
 
-**Encourage your users to download the OneTapForms app** - it helps them complete your forms faster, which means more completed applications, signups, and conversions for you!
+<!-- 2. Add a button with data attributes -->
+<button
+  data-onetapforms
+  data-client-id="YOUR_CLIENT_ID"
+  data-purpose="Complete your profile"
+  data-bundles="basic,contact">
+  Fill with OneTapForms
+</button>
 
-Revenue comes from end users who subscribe to the OneTapForms service ($9-29/month) to securely store their profile data. Your users pay for the convenience, not you.
+<!-- 3. Handle the result -->
+<script>
+document.querySelector('[data-onetapforms]')
+  .addEventListener('onetapforms:complete', function(e) {
+    console.log('Token:', e.detail.token);
+    // Send token to your server to get user data
+  });
+</script>
+```
+
+That's it! The SDK automatically shows a QR modal when the button is clicked.
 
-## Installation
+### Option 2: npm Install (For React, Vue, Next.js, etc.)
 
 ```bash
 npm install @createlex/onetapforms-sdk
 ```
 
-## Quick Start
-
-### 1. Initialize the SDK
-
 ```javascript
 import { OneTapForms } from '@createlex/onetapforms-sdk';
 
-const onetapforms = new OneTapForms({
-  clientId: 'your_client_id',
-  apiUrl: 'https://api.createlex.com',
-  debug: true // Enable console logging
+const onetap = new OneTapForms({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET'
 });
-```
-
-### 2. Create a Request
 
-```javascript
-await onetapforms.request({
-  schemaId: 'job_application',
-  purpose: 'Job application at YourCompany',
-  returnUrl: 'https://yoursite.com/apply/callback',
+await onetap.request({
+  purpose: 'Job Application',
   bundles: ['basic', 'contact'],
-
-  // Called when QR code is ready (desktop users)
-  onQRReady: (qrDataUrl) => {
-    document.getElementById('qr-code').src = qrDataUrl;
+  onQRReady: (qrUrl) => {
+    // Show QR code to user
+    document.getElementById('qr').src = qrUrl;
   },
-
-  // Called when user approves the request
-  onComplete: ({ token, requestId }) => {
-    // Exchange token for user data on your server
-    exchangeTokenForData(token);
-  },
-
-  // Called if an error occurs
-  onError: (error) => {
-    console.error('OneTapForms error:', error);
+  onComplete: ({ token }) => {
+    // Exchange token for data on your server
+    fetch('/api/exchange', {
+      method: 'POST',
+      body: JSON.stringify({ token })
+    });
   }
 });
 ```
 
-### 2.5. Encourage App Downloads (Optional but Recommended)
+---
 
-Help users discover OneTapForms to get faster form completion:
+## Free for Developers
 
-```javascript
-// Show download prompt if user doesn't have the app
-if (!onetapforms.isAppLikelyInstalled()) {
-  onetapforms.showDownloadPrompt({
-    title: 'Complete Forms Faster!',
-    message: 'Download OneTapForms to fill this form in seconds with Face ID/Touch ID.',
-    buttonText: 'Download App'
-  });
-}
+**The SDK is completely free!** No fees, usage limits, or restrictions.
 
-// Or add a download button to your UI
-const downloadUrl = onetapforms.getAppDownloadUrl();
-// <a href={downloadUrl}>Download OneTapForms App</a>
-```
+- **Faster Form Completion** - Users fill forms in seconds
+- **Higher Conversion Rates** - Reduce form abandonment
+- **Better UX** - No typing errors
+- **Verified Data** - Pre-verified user information
+- **Zero Cost** - Free SDK, free integration
 
-### 3. Handle Mobile Redirect Callback
+Revenue comes from end users who subscribe to OneTapForms ($9-29/month) to store their data securely.
 
-If using redirect mode on mobile, handle the callback:
+---
 
-```javascript
-// On your callback page
-const result = onetapforms.handleCallback();
-if (result) {
-  const { token, requestId } = result;
-  // Exchange token for user data on your server
-  exchangeTokenForData(token);
-}
-```
+## Widget Mode Reference (Script Tag)
 
-### 4. Exchange Token for Data (Server-Side)
+### Data Attributes
 
-**Important:** Always exchange tokens server-side to protect your API key.
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-onetapforms` | Yes | Marks element as OneTapForms trigger |
+| `data-client-id` | Yes | Your client ID |
+| `data-client-secret` | No | Your client secret |
+| `data-purpose` | No | Purpose shown to user (default: "Complete form") |
+| `data-bundles` | No | Comma-separated bundles (default: "basic") |
+| `data-form-id` | No | Auto-inject token into this form |
+| `data-api-url` | No | Custom API URL |
+
+### Events
+
+Listen for these custom events on your button/element:
 
 ```javascript
-// Node.js example (server-side)
-const response = await fetch('https://api.createlex.com/api/onetapforms/exchange', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-API-Key': 'your_api_key'
-  },
-  body: JSON.stringify({ token })
+// Success - user approved the request
+element.addEventListener('onetapforms:complete', (e) => {
+  const { token, requestId } = e.detail;
+  // Send token to your server
 });
 
-const { data } = await response.json();
-// Use the user data to fill your form
+// Error - something went wrong
+element.addEventListener('onetapforms:error', (e) => {
+  const { error } = e.detail;
+  console.error('Failed:', error.message);
+});
 ```
 
-## API Reference
+### Auto-Inject Token into Form
 
-### `OneTapForms(config)`
+Use `data-form-id` to automatically add the token to a form:
 
-Creates a new OneTapForms instance.
+```html
+<form id="myForm" method="POST" action="/submit">
+  <input type="text" name="email" placeholder="Email">
 
-**Parameters:**
-- `config.clientId` (string, required): Your client ID
-- `config.clientSecret` (string, optional): Your client secret (recommended for authenticated requests)
-- `config.apiUrl` (string, optional): API URL (defaults to `https://api.createlex.com`)
-- `config.apiKey` (string, optional): API key for legacy auth (defaults to `clientId`)
-- `config.debug` (boolean, optional): Enable debug logging (defaults to `false`)
+  <button
+    type="button"
+    data-onetapforms
+    data-client-id="YOUR_ID"
+    data-form-id="myForm">
+    Autofill with OneTapForms
+  </button>
 
-### `request(options)`
+  <button type="submit">Submit</button>
+</form>
 
-Creates a form completion request.
+<!-- Token is automatically added as: -->
+<!-- <input type="hidden" name="onetapforms_token" value="..."> -->
+```
 
-**Parameters:**
-- `options.schemaId` (string, required): Schema ID identifying the form structure
-- `options.purpose` (string, required): Purpose description shown to the user
-- `options.returnUrl` (string, required): URL to redirect to after completion
-- `options.bundles` (string[], optional): Data bundles to request
-- `options.fields` (string[], optional): Specific fields to request
-- `options.mode` ('auto' | 'redirect' | 'qr', optional): Request mode (defaults to 'auto')
-- `options.metadata` (object, optional): Additional metadata
-- `options.customization` (object, optional): Customization options
-  - `customization.companyName` (string, optional)
-  - `customization.logoUrl` (string, optional)
-- `options.onComplete` (function, optional): Callback when request is completed
-- `options.onError` (function, optional): Callback when an error occurs
-- `options.onQRReady` (function, optional): Callback when QR code is ready
+### Complete HTML Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Job Application</title>
+</head>
+<body>
+  <h1>Apply Now</h1>
+
+  <form id="applicationForm" action="/apply" method="POST">
+    <input name="name" placeholder="Full Name">
+    <input name="email" placeholder="Email">
+    <input name="phone" placeholder="Phone">
+
+    <button
+      type="button"
+      data-onetapforms
+      data-client-id="your_client_id"
+      data-purpose="Job application at ACME Corp"
+      data-bundles="basic,contact"
+      data-form-id="applicationForm"
+      style="background: #007AFF; color: white; padding: 12px 24px; border: none; border-radius: 8px; cursor: pointer;">
+      Fill with OneTapForms
+    </button>
+
+    <button type="submit">Submit Application</button>
+  </form>
+
+  <script src="https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js"></script>
+  <script>
+    document.querySelector('[data-onetapforms]').addEventListener('onetapforms:complete', function(e) {
+      alert('Form ready! Token received.');
+      // Token is auto-injected into the form - submit when ready
+    });
+  </script>
+</body>
+</html>
+```
 
-**Returns:** `Promise<void>`
+---
 
-### `handleCallback()`
+## npm API Reference
 
-Handles callback from redirect flow. Call this when user returns to your site with token in URL.
+### Constructor
 
-**Returns:** `{ token: string, requestId: string } | null`
+```javascript
+import { OneTapForms } from '@createlex/onetapforms-sdk';
 
-### `cancelPolling()`
+const onetap = new OneTapForms({
+  clientId: 'your_client_id',       // Required
+  clientSecret: 'your_secret',      // Recommended
+  apiUrl: 'https://api.createlex.com', // Optional
+  debug: true                       // Optional: enable logging
+});
+```
 
-Cancels active polling (useful for cleanup).
+### request(options)
 
-### `exchangeToken(token)`
+Create a form completion request.
 
-Exchanges token for user data. **Note:** This should be called server-side, not in the browser.
+```javascript
+await onetap.request({
+  // Content
+  purpose: 'Complete your profile',   // Required
+  bundles: ['basic', 'contact'],      // Optional
+  fields: ['name', 'email'],          // Optional
+
+  // Mode
+  mode: 'auto',                       // 'auto' | 'qr' | 'redirect'
+  returnUrl: 'https://...',           // For redirect mode
+
+  // Callbacks
+  onQRReady: (qrDataUrl) => {},       // QR code ready (desktop)
+  onComplete: ({ token }) => {},      // User approved
+  onError: (error) => {}              // Error occurred
+});
+```
 
-**Parameters:**
-- `token` (string, required): Exchange token
+### handleCallback()
 
-**Returns:** `Promise<any>` - User data object
+Handle redirect flow callback (mobile):
 
-### `getAppDownloadUrl()`
+```javascript
+const result = onetap.handleCallback();
+if (result) {
+  const { token, requestId } = result;
+  // Exchange token on server
+}
+```
 
-Returns the App Store URL for downloading the OneTapForms app. Use this to encourage users to download the app.
+### cancelPolling()
 
-**Returns:** `string` - App Store URL
+Cancel active polling (cleanup):
 
-### `showDownloadPrompt(options?)`
+```javascript
+onetap.cancelPolling();
+```
 
-Shows a modal prompt encouraging users to download the OneTapForms app. This helps developers get faster form completion and better conversion rates.
+### showDownloadPrompt(options)
 
-**Parameters:**
-- `options.title` (string, optional): Custom title for the prompt
-- `options.message` (string, optional): Custom message
-- `options.buttonText` (string, optional): Custom button text
-- `options.onDismiss` (function, optional): Callback when user dismisses the prompt
+Encourage app downloads:
 
-**Example:**
 ```javascript
-// Show download prompt to encourage app downloads
-onetapforms.showDownloadPrompt({
+onetap.showDownloadPrompt({
   title: 'Complete Forms Faster!',
-  message: 'Download OneTapForms to fill forms in seconds with Face ID.',
-  buttonText: 'Download Now',
-  onDismiss: () => console.log('User dismissed prompt')
+  message: 'Download OneTapForms for instant form completion.',
+  buttonText: 'Download App'
 });
 ```
 
-### `isAppLikelyInstalled()`
+### getAppDownloadUrl()
+
+Get App Store URL:
+
+```javascript
+const url = onetap.getAppDownloadUrl();
+// 'https://apps.apple.com/app/onetapforms'
+```
 
-Checks if the user likely has the OneTapForms app installed (iOS device detection).
+---
 
-**Returns:** `boolean` - True if on iOS device
+## Server-Side Token Exchange
 
-## Request Modes
+**Important:** Always exchange tokens server-side to protect your credentials.
 
-### Auto Mode (Default)
-Automatically detects device type and uses appropriate flow:
-- Mobile devices → Redirect flow
-- Desktop devices → QR code flow
+```javascript
+// Node.js example
+const response = await fetch('https://api.createlex.com/api/onetapforms/exchange', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Client-ID': 'your_client_id',
+    'X-Client-Secret': 'your_client_secret'
+  },
+  body: JSON.stringify({ token })
+});
 
-### Redirect Mode
-Forces redirect flow (mobile). Opens OneTapForms app via Universal Link.
+const { data } = await response.json();
+// data contains: { name, email, phone, ... }
+```
 
-### QR Mode
-Forces QR code flow (desktop). Generates QR code for user to scan.
+---
 
-## Client Registration
+## Request Modes
 
-Before using the SDK, you must register as a client:
+| Mode | When to Use | Behavior |
+|------|-------------|----------|
+| `auto` (default) | Most cases | Mobile = redirect, Desktop = QR |
+| `qr` | Desktop only | Shows QR code modal |
+| `redirect` | Mobile only | Opens OneTapForms app |
 
-1. Contact Createlex LLC at info@createlex.com
-2. Provide your company name and allowed callback URLs
-3. Receive your `clientId` and `clientSecret` credentials
+---
 
-**Note:** Client registration is free and only required for security and callback URL validation. There are no fees for developers.
+## Getting Started
 
-## Pricing Model
+1. **Get Credentials**: Email info@createlex.com to receive your `clientId` and `clientSecret` (free)
+2. **Install SDK**: Via script tag or npm
+3. **Add Button**: With data attributes or JavaScript
+4. **Handle Token**: Exchange on your server for user data
 
-- ✅ **SDK is free** - No cost to integrate or use
-- ✅ **No usage limits** - Use as much as you need
-- ✅ **No developer fees** - Zero cost for website owners
-- 💰 **End users pay** - Your users subscribe to OneTapForms service ($9-29/month) to store their data securely
+---
 
-### Win-Win Model
+## CDN URLs
 
-**For Developers:**
-- Free integration with no ongoing costs
-- Faster form completion = more conversions
-- Better UX = happier users
-- Verified data = less errors
+```
+# Latest version (recommended for development)
+https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js
 
-**For End Users:**
-- One-tap form completion
-- Secure biometric authentication
-- Pre-filled verified data
-- Works across all OneTapForms-enabled sites
+# Specific version (recommended for production)
+https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@1.2.0/dist/onetapforms.umd.min.js
 
-**For OneTapForms:**
-- Revenue from user subscriptions
-- Network effects as more sites integrate
+# Unminified (for debugging)
+https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.js
+```
 
-This model creates genuine value for everyone - developers get better results, users get convenience, and OneTapForms grows sustainably.
+---
 
 ## License
 
@@ -261,4 +322,5 @@ MIT - Free to use, modify, and distribute
 
 ## Support
 
-For issues and questions, please visit: https://github.com/createlex/onetapforms-sdk/issues
+- Issues: https://github.com/createlex/onetapforms-sdk/issues
+- Email: info@createlex.com