handhold-sdk 1.0.0

package/README.md

@@ -0,0 +1,427 @@
+# Hand Hold SDK
+
+**Context-aware, in-app help system with visual UI guidance.**
+
+The Hand Hold SDK provides intelligent, contextual help for web applications by:
+- Automatically inferring user intents from page UI elements
+- Searching a knowledge base for relevant guidance
+- Highlighting specific UI elements users should interact with
+- Tracking multi-page workflows with persistent session state
+
+## Features
+
+- 🎯 **Intent Detection** - Rule-based intent extraction from buttons, links, and interactive elements
+- 📚 **Knowledge Base Integration** - RAG-powered search for relevant help articles
+- 🎨 **Visual Guidance** - Element highlighting with arrows, tooltips, and overlay dimming
+- 🔄 **Multi-Page Tracking** - Session persistence across page navigations
+- 💬 **Conversational Fallback** - LLM-powered intent extraction for free-text queries
+- 🌙 **Theme Support** - Light and dark modes
+- ⚡ **Zero Configuration** - Works across any frontend framework
+
+## Installation
+
+### NPM
+
+```bash
+npm install handhold-sdk
+```
+
+### CDN
+
+```html
+<!-- Production (minified) -->
+<script src="https://cdn.handhold.com/v1/handhold.min.js"></script>
+
+<!-- Development (unminified with source maps) -->
+<script src="https://cdn.handhold.com/v1/handhold.js"></script>
+```
+
+### Auto-Initialization (CDN)
+
+```html
+<script 
+  src="https://cdn.handhold.com/v1/handhold.min.js"
+  data-handhold-api-key="your-api-key"
+  data-handhold-base-url="https://api.yourserver.com"
+  data-handhold-theme="light"
+  data-handhold-position="bottom-right"
+  data-handhold-debug="false">
+</script>
+```
+
+## Quick Start
+
+### ES Module
+
+```javascript
+import HandHold from 'handhold-sdk';
+
+await HandHold.init({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.yourserver.com',
+  theme: 'light',
+  position: 'bottom-right'
+});
+```
+
+### Script Tag
+
+```html
+<script src="handhold.min.js"></script>
+<script>
+  HandHold.init({
+    apiKey: 'your-api-key',
+    baseUrl: 'https://api.yourserver.com'
+  }).then(() => {
+    console.log('Hand Hold ready!');
+  });
+</script>
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | **required** | API key for authentication |
+| `baseUrl` | string | **required** | Backend API base URL |
+| `theme` | string | `'light'` | UI theme: `'light'` or `'dark'` |
+| `position` | string | `'bottom-right'` | Widget position: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |
+| `primaryColor` | string | `'#2196F3'` | Primary accent color (hex) |
+| `zIndex` | number | `999999` | Z-index for overlays |
+| `minHighlightConfidence` | number | `0.85` | Minimum confidence to highlight elements (0-1) |
+| `sessionInactivityTimeout` | number | `600000` | Session timeout in ms (default: 10 min) |
+| `enableMultiPageTracking` | boolean | `true` | Enable cross-page session tracking |
+| `showHelpButton` | boolean | `true` | Show floating help button |
+| `maxIntents` | number | `6` | Maximum intents to display |
+| `apiTimeout` | number | `30000` | API request timeout in ms |
+| `retryAttempts` | number | `3` | Number of retry attempts for API calls |
+| `debug` | boolean | `false` | Enable debug logging |
+| `logLevel` | string | `'warn'` | Log level: `'error'`, `'warn'`, `'info'`, `'debug'` |
+
+## API Reference
+
+### Initialization
+
+```javascript
+await HandHold.init(options);
+```
+
+Initialize the SDK with configuration options. Must be called before using any other methods.
+
+### Widget Control
+
+```javascript
+// Open the help widget
+HandHold.open();
+
+// Close the help widget
+HandHold.close();
+
+// Toggle the help widget
+HandHold.toggle();
+```
+
+### Programmatic Guidance
+
+```javascript
+// Start guidance for a specific intent
+await HandHold.startGuidance('approve_payroll');
+
+// Get available intents for current page
+const intents = HandHold.getIntents();
+// Returns: [{ key: 'approve_payroll', label: 'Approve Payroll', confidence: 0.95 }, ...]
+```
+
+### Session Management
+
+```javascript
+// Check if there's an active session
+const hasSession = HandHold.hasActiveSession();
+
+// Get the active session
+const session = HandHold.getActiveSession();
+
+// Get session progress (0-100)
+const progress = HandHold.getProgress();
+```
+
+### Events
+
+```javascript
+// Subscribe to events
+const unsubscribe = HandHold.on('handhold:completed', (data) => {
+  console.log('User completed guidance for:', data.intent);
+});
+
+// Unsubscribe
+unsubscribe();
+// or
+HandHold.off('handhold:completed', handler);
+```
+
+#### Available Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `handhold:ready` | - | SDK initialized |
+| `handhold:completed` | `{ intent }` | User completed all steps |
+| `handhold:closed` | `{ intent }` | User closed guidance |
+| `help:open` | - | Help widget opened |
+| `intent:selected` | `intent` | User selected an intent |
+| `step:done` | - | User marked step as done |
+| `navigation:changed` | `{ route, previousRoute }` | Page navigation detected |
+
+### Cleanup
+
+```javascript
+// Destroy the SDK instance
+HandHold.destroy();
+```
+
+### Utility Methods
+
+```javascript
+// Get SDK version
+HandHold.getVersion(); // '1.0.0'
+
+// Check if initialized
+HandHold.isInitialized(); // true/false
+```
+
+## UI Element Detection
+
+The SDK automatically detects interactive UI elements using:
+
+1. **Stable Selectors** (preferred): `data-testid` attributes
+2. **ARIA Labels**: `aria-label` attributes
+3. **Element IDs**: Unique `id` attributes
+4. **Text Content**: Button/link text
+
+### Best Practices for UI Elements
+
+```html
+<!-- Recommended: Use data-testid for stable selectors -->
+<button data-testid="approve-payroll">Approve Payroll</button>
+
+<!-- Also works: ARIA labels -->
+<button aria-label="Approve payroll for current period">Approve</button>
+
+<!-- Falls back to: Text content -->
+<button>Approve Payroll</button>
+```
+
+## Intent Extraction
+
+Intents are automatically extracted from UI elements using action verbs:
+
+| Verb | Canonical | Example UI Text |
+|------|-----------|-----------------|
+| approve, confirm, accept | `approve` | "Approve Payroll" → `approve_payroll` |
+| create, add, new | `create` | "Add Employee" → `create_employee` |
+| download, export | `download` | "Download Report" → `download_report` |
+| run, execute, process | `run` | "Run Payroll" → `run_payroll` |
+| view, see, show | `view` | "View Details" → `view_details` |
+
+## Multi-Page Tracking
+
+The SDK tracks user progress across page navigations:
+
+1. **Session Persistence**: Sessions are stored in `sessionStorage`
+2. **Element Re-matching**: UI elements are re-matched on new pages
+3. **Flow Detection**: SDK detects if navigation is within the same workflow
+
+```javascript
+// Enable multi-page tracking (default: true)
+HandHold.init({
+  enableMultiPageTracking: true,
+  sessionInactivityTimeout: 600000 // 10 minutes
+});
+```
+
+## Styling & Theming
+
+### CSS Variables
+
+The SDK injects CSS variables for customization:
+
+```css
+:root {
+  --handhold-primary: #2196F3;
+  --handhold-background: #ffffff;
+  --handhold-text: #212121;
+  --handhold-text-secondary: #666666;
+  --handhold-border: #e0e0e0;
+  --handhold-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+  --handhold-z-index: 999999;
+}
+```
+
+### Dark Theme
+
+```javascript
+HandHold.init({
+  theme: 'dark'
+});
+```
+
+### Custom Colors
+
+```javascript
+HandHold.init({
+  primaryColor: '#4CAF50' // Green
+});
+```
+
+## Backend Integration
+
+The SDK communicates with a backend server via REST API:
+
+### Required Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/intents/infer` | POST | Validate/cache intents |
+| `/api/v1/intents/extract` | POST | LLM intent extraction |
+| `/api/v1/guidance` | POST | Get step-by-step guidance |
+| `/api/v1/guidance/match-element` | POST | Re-match elements |
+| `/api/v1/guidance/sessions/update` | POST | Update session status |
+| `/api/v1/kb/search` | GET | Search knowledge base |
+
+### Authentication
+
+All requests include the API key:
+
+```
+Authorization: Bearer <api_key>
+```
+
+## Error Handling
+
+The SDK handles errors gracefully:
+
+- **Network Errors**: Retry with exponential backoff
+- **API Errors**: Display user-friendly messages
+- **Element Not Found**: Fall back to text-only guidance
+- **Session Expired**: Prompt user to start new session
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 75+
+- Safari 13+
+- Edge 80+
+
+## Advanced Usage
+
+### Custom Integration
+
+```javascript
+import { 
+  Config,
+  PageObserver,
+  IntentExtractor,
+  UICoach,
+  EventBus 
+} from 'handhold-sdk';
+
+// Use individual components
+const observer = new PageObserver(config);
+observer.observe();
+
+const pageContext = observer.scanPage();
+const intents = IntentExtractor.extract(pageContext.ui_elements, pageContext.route);
+```
+
+### Event-Driven Architecture
+
+```javascript
+import { EventBus } from 'handhold-sdk';
+
+// Subscribe to internal events
+EventBus.on('page:changed', (data) => {
+  console.log('Page changed:', data.route);
+});
+
+EventBus.on('intent:selected', (intent) => {
+  analytics.track('help_intent_selected', { intent: intent.key });
+});
+```
+
+## File Structure
+
+```
+sdk/
+├── src/
+│   ├── api/
+│   │   └── APIClient.js          # Backend communication
+│   ├── core/
+│   │   └── Config.js             # Configuration management
+│   ├── intent/
+│   │   ├── ActionVerbMap.js      # Action verb taxonomy
+│   │   └── IntentExtractor.js    # Rule-based intent extraction
+│   ├── observers/
+│   │   ├── ElementScanner.js     # UI element scanning
+│   │   ├── NavigationObserver.js # Route change detection
+│   │   └── PageObserver.js       # Main page observer
+│   ├── session/
+│   │   ├── SessionManager.js     # Session lifecycle
+│   │   └── SessionStorage.js     # Storage wrapper
+│   ├── ui/
+│   │   ├── HelpWidget.js         # Main widget UI
+│   │   └── UICoach.js            # Element highlighting
+│   ├── utils/
+│   │   ├── domUtils.js           # DOM utilities
+│   │   ├── eventBus.js           # Event system
+│   │   ├── Logger.js             # Logging
+│   │   └── stringUtils.js        # String processing
+│   ├── HandHold.js               # Main orchestrator
+│   └── index.js                  # Entry point
+├── dist/
+│   ├── handhold.js               # Development build
+│   └── handhold.min.js           # Production build
+├── examples/
+│   └── basic.html                # Demo page
+├── package.json
+├── webpack.config.js
+└── README.md
+```
+
+## Development
+
+### Building
+
+```bash
+# Install dependencies
+npm install
+
+# Development build
+npm run build:dev
+
+# Production build
+npm run build
+
+# Watch mode
+npm run watch
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## License
+
+MIT © Hand Hold Team
+
+## Support
+
+- Documentation: https://docs.handhold.com
+- Issues: https://github.com/handhold/sdk/issues
+- Email: support@handhold.com