dphelper 3.5.5 → 3.7.2

package/docs/markdown/audio.md

@@ -0,0 +1,113 @@
+# audio
+
+Audio playback utilities for managing sound effects and background music in web applications.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `play` | Plays an audio file or removes all audio elements | `dphelper.audio.play('notification.mp3', '/sounds/')` |
+
+## Description
+
+Simple audio management for web applications:
+- **Play Sound** - Load and play audio files with optional looping
+- **Stop All** - Remove all dpHelper audio elements from the DOM
+- **Multiple Sounds** - Play different sounds simultaneously (each gets unique ID)
+
+## Usage Examples
+
+### Playing Sound Effects
+
+```javascript
+// Play a simple notification sound
+dphelper.audio.play('notification.mp3');
+
+// Play with custom path
+dphelper.audio.play('click.mp3', '/assets/sounds/');
+
+// Loop background music
+dphelper.audio.play('music.mp3', '/assets/audio/', true);
+```
+
+### Stopping Audio
+
+```javascript
+// Stop all dpHelper audio elements
+dphelper.audio.play();
+
+// This removes all audio tags created by dphelper.audio
+```
+
+### Complete Example
+
+```javascript
+// Sound manager class
+class SoundManager {
+  constructor(soundPath = '/sounds/') {
+    this.path = soundPath;
+    this.enabled = true;
+  }
+
+  playSound(name, loop = false) {
+    if (!this.enabled) return;
+    dphelper.audio.play(name, this.path, loop);
+  }
+
+  stopAll() {
+    dphelper.audio.play(); // No args = remove all
+  }
+
+  toggle(enabled) {
+    this.enabled = enabled;
+    if (!enabled) this.stopAll();
+  }
+}
+
+// Usage
+const sounds = new SoundManager('/assets/sounds/');
+
+// Play various sounds
+sounds.playSound('click.mp3');
+sounds.playSound('notification.mp3');
+sounds.playSound('background.mp3', true); // Loop
+
+// Mute all
+sounds.toggle(false);
+
+// Unmute
+sounds.toggle(true);
+```
+
+### UI Sound Effects
+
+```javascript
+// Add sounds to UI interactions
+document.querySelectorAll('button').forEach(btn => {
+  btn.addEventListener('click', () => {
+    dphelper.audio.play('click.mp3', '/sounds/');
+  });
+});
+
+// Form submission
+document.querySelector('form').addEventListener('submit', () => {
+  dphelper.audio.play('success.mp3', '/sounds/');
+});
+
+// Error handling
+function showError() {
+  dphelper.audio.play('error.mp3', '/sounds/');
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20240924
+- **Last Modified:** 20240924
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/avoid.md

@@ -0,0 +1,53 @@
+# avoid
+
+Utilities for preventing caching issues in web applications.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `cache` | Appends cache-busting query parameter to URL | `dphelper.avoid.cache('/api/data')` |
+
+## Description
+
+Prevents browser caching issues:
+- **Cache Busting** - Add unique query params to URLs
+
+## Usage Examples
+
+### Cache Busting
+
+```javascript
+// Add unique query parameter to prevent caching
+const url = '/api/users';
+const uncachedUrl = dphelper.avoid.cache(url);
+console.log(uncachedUrl); // "/api/users?t=abc123xyz"
+
+// Useful for:
+// - API calls that need fresh data
+// - Dynamic content
+// - Debugging (force reload)
+dphelper.avoid.cache('/api/latest-data');
+```
+
+### Using with Fetch
+
+```javascript
+// Fetch with cache busting
+async function fetchFresh(url) {
+  const response = await fetch(dphelper.avoid.cache(url));
+  return response.json();
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/biometric.md

@@ -0,0 +1,338 @@
+# biometric
+
+WebAuthn and biometric authentication utilities for secure passwordless login using fingerprint, face recognition, and hardware security keys.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `isAvailable` | Check if WebAuthn is available | `dphelper.biometric.isAvailable()` |
+| `getWebAuthnSupport` | Get detailed support info | `dphelper.biometric.getWebAuthnSupport()` |
+| `isSensorAvailable` | Check specific sensor (fingerprint/face/iris) | `await dphelper.biometric.isSensorAvailable('fingerprint')` |
+| `register` | Register new credential | `await dphelper.biometric.register('user123', 'example.com')` |
+| `authenticate` | Authenticate with credential | `await dphelper.biometric.authenticate('user123', 'example.com')` |
+| `getCredential` | Get stored credential by ID | `dphelper.biometric.getCredential(credentialId)` |
+| `deleteCredential` | Delete stored credential | `dphelper.biometric.deleteCredential(credentialId)` |
+| `listCredentials` | List all stored credentials | `dphelper.biometric.listCredentials()` |
+
+## Description
+
+Secure biometric authentication module providing:
+- **WebAuthn/FIDO2** - Industry-standard passwordless authentication
+- **Platform Authenticators** - Fingerprint, Face ID, Windows Hello
+- **Cross-platform** - Works with hardware security keys (YubiKey, etc.)
+- **Credential Management** - Store, retrieve, and delete credentials
+- **Sensor Detection** - Check availability of specific biometric types
+
+## Usage Examples
+
+### Checking Availability
+
+```javascript
+// Simple availability check
+if (dphelper.biometric.isAvailable()) {
+  console.log('Biometric authentication is available!');
+} else {
+  console.log('Biometric auth not supported');
+}
+
+// Get detailed support information
+const support = dphelper.biometric.getWebAuthnSupport();
+console.log(support);
+// {
+//   supported: true,
+//   platformAuthenticator: true,
+//   hybridTransport: false,
+//   uvToken: false
+// }
+
+// Check specific sensor
+const hasFingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
+const hasFace = await dphelper.biometric.isSensorAvailable('face');
+console.log('Fingerprint:', hasFingerprint, 'Face:', hasFace);
+```
+
+### Registration (Enrolling a Credential)
+
+```javascript
+// Register a new biometric credential
+async function registerUser(userId) {
+  if (!dphelper.biometric.isAvailable()) {
+    return { success: false, error: 'WebAuthn not supported' };
+  }
+
+  const result = await dphelper.biometric.register(
+    userId,           // User ID
+    'example.com',   // Relying Party ID (your domain)
+    'My App',        // Relying Party Name
+    'john@example.com' // Display name
+  );
+
+  if (result.success) {
+    console.log('Registered! Credential ID:', result.credentialId);
+    // Store credentialId in your database for this user
+  } else {
+    console.error('Registration failed:', result.error);
+  }
+
+  return result;
+}
+
+// Usage
+const result = await registerUser('user_123');
+```
+
+### Authentication (Login)
+
+```javascript
+// Authenticate with stored credential
+async function loginUser(userId, credentialId) {
+  if (!dphelper.biometric.isAvailable()) {
+    return { success: false, error: 'WebAuthn not supported' };
+  }
+
+  const result = await dphelper.biometric.authenticate(
+    userId,           // User ID
+    'example.com',   // Relying Party ID
+    credentialId     // Optional: specific credential to use
+  );
+
+  if (result.success) {
+    console.log('Authentication successful!');
+  } else {
+    console.error('Authentication failed:', result.error);
+  }
+
+  return result;
+}
+
+// Usage - login with known credential
+const result = await loginUser('user_123', 'stored_credential_id');
+```
+
+### Credential Management
+
+```javascript
+// List all stored credentials
+const credentials = dphelper.biometric.listCredentials();
+console.log('Stored credentials:', credentials);
+
+// Get a specific credential
+const cred = dphelper.biometric.getCredential('credential_id_123');
+console.log('Credential:', cred);
+
+// Delete a credential
+const deleted = dphelper.biometric.deleteCredential('credential_id_123');
+console.log('Deleted:', deleted);
+
+// After deletion
+console.log('Remaining:', dphelper.biometric.listCredentials());
+```
+
+## Advanced Usage
+
+### Complete Authentication System
+
+```javascript
+class BiometricAuth {
+  constructor(rpId, rpName) {
+    this.rpId = rpId;
+    this.rpName = rpName;
+    this.available = dphelper.biometric.isAvailable();
+  }
+
+  async checkSupport() {
+    if (!this.available) {
+      return { supported: false, reason: 'WebAuthn not supported' };
+    }
+
+    const support = dphelper.biometric.getWebAuthnSupport();
+    const fingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
+    const face = await dphelper.biometric.isSensorAvailable('face');
+
+    return {
+      supported: true,
+      platformAuthenticator: support.platformAuthenticator,
+      fingerprint,
+      face
+    };
+  }
+
+  async register(userId, userName) {
+    if (!this.available) {
+      throw new Error('Biometric authentication not available');
+    }
+
+    const result = await dphelper.biometric.register(
+      userId,
+      this.rpId,
+      this.rpName,
+      userName
+    );
+
+    if (result.success) {
+      // In production: save credentialId to your backend
+      console.log('Biometric registered:', result.credentialId);
+    }
+
+    return result;
+  }
+
+  async login(userId, credentialId) {
+    if (!this.available) {
+      throw new Error('Biometric authentication not available');
+    }
+
+    return await dphelper.biometric.authenticate(
+      userId,
+      this.rpId,
+      credentialId
+    );
+  }
+
+  getStoredCredentials() {
+    return dphelper.biometric.listCredentials();
+  }
+
+  removeCredential(credentialId) {
+    return dphelper.biometric.deleteCredential(credentialId);
+  }
+}
+
+// Usage
+const auth = new BiometricAuth('example.com', 'My Application');
+
+// Check if biometric is available
+const support = await auth.checkSupport();
+if (support.supported) {
+  console.log('Biometric types available:', support);
+}
+
+// Register new user
+await auth.register('user_123', 'john@example.com');
+
+// Login
+const loginResult = await auth.login('user_123');
+if (loginResult.success) {
+  console.log('Logged in with biometric!');
+}
+```
+
+### Passwordless Login Flow
+
+```javascript
+// Frontend: Initiate passwordless login
+async function initiatePasswordlessLogin() {
+  // 1. Check if biometric is available
+  if (!dphelper.biometric.isAvailable()) {
+    alert('Please use a supported browser');
+    return;
+  }
+
+  // 2. Get available credentials for this user
+  const credentials = dphelper.biometric.listCredentials();
+
+  if (credentials.length === 0) {
+    // No credentials - prompt to register
+    const register = confirm('No biometric credentials found. Register now?');
+    if (register) {
+      await registerNewUser();
+    }
+    return;
+  }
+
+  // 3. Attempt authentication with any stored credential
+  for (const credId of credentials) {
+    const result = await dphelper.biometric.authenticate(
+      'current_user',
+      window.location.hostname,
+      credId
+    );
+
+    if (result.success) {
+      // 4. Verify with server
+      await verifyWithServer(credId);
+      return;
+    }
+  }
+
+  console.log('All credentials failed');
+}
+
+// Server verification (pseudo-code)
+async function verifyWithServer(credentialId) {
+  const response = await fetch('/api/auth/verify', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ credentialId })
+  });
+
+  if (response.ok) {
+    const { token } = await response.json();
+    localStorage.setItem('auth_token', token);
+    window.location.href = '/dashboard';
+  }
+}
+```
+
+### Progressive Registration
+
+```javascript
+// Offer biometric as an option during existing login
+async function offerBiometricUpgrade(userId, userName) {
+  const support = await dphelper.biometric.checkSupport();
+
+  if (!support.supported) {
+    console.log('Biometric not available on this device');
+    return;
+  }
+
+  // Show modal or prompt
+  const shouldRegister = confirm(
+    `Enable ${support.fingerprint ? 'fingerprint' : 'biometric'} login for faster access?`
+  );
+
+  if (shouldRegister) {
+    const result = await dphelper.biometric.register(
+      userId,
+      window.location.hostname,
+      'My App',
+      userName
+    );
+
+    if (result.success) {
+      // Save credential to user account
+      await saveCredentialToUser(userId, result.credentialId);
+      alert('Biometric authentication enabled!');
+    } else {
+      alert('Registration failed: ' + result.error);
+    }
+  }
+}
+```
+
+## Security Notes
+
+### WebAuthn Security Features
+- **Public-key cryptography** - Uses asymmetric keys, never transmitted
+- **User presence** - Requires user action (touch/face) to authenticate
+- **Platform binding** - Credentials bound to specific device
+- **Phishing resistance** - Relying Party ID must match exactly
+
+### Best Practices
+- Always verify authentication on the server side
+- Store credential IDs in your database, not the credentials themselves
+- Support multiple credentials per user (different devices)
+- Provide fallback for unsupported browsers
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20260313
+- **Last Modified:** 20260313
+- **Environment:** Client-side only (browser with WebAuthn support)
+
+---
+
+*Automatically generated document*

package/docs/markdown/browser.md

@@ -0,0 +1,203 @@
+# browser
+
+Complete browser navigation and state management utilities with connection monitoring and HTTP status handling.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `state` | Pushes a new state to browser history without reload | `dphelper.browser.state(state, title, url)` |
+| `forw` | Moves forward in browser history by n steps | `dphelper.browser.forw(1)` |
+| `back` | Moves backward in browser history by n steps | `dphelper.browser.back(1)` |
+| `reload` | Reloads the current page | `dphelper.browser.reload()` |
+| `href` | Navigates to a specific URL | `dphelper.browser.href('https://example.com')` |
+| `offLine` | Displays an offline message overlay when connection is lost | `dphelper.browser.offLine('Custom offline message')` |
+| `zoom` | Returns the current browser zoom level as percentage | `dphelper.browser.zoom()` |
+| `status` | Returns human-readable description of HTTP status codes | `dphelper.browser.status(404)` |
+| `interlock` | Detects and monitors other active tabs of the same app | `dphelper.browser.interlock((count) => console.log(count))` |
+
+## Description
+
+Comprehensive browser management tool that provides:
+- **History Navigation** - Push state, go forward/back, reload
+- **URL Management** - Navigate to specific URLs
+- **Connection Monitoring** - Detect online/offline status
+- **Display Information** - Get zoom level, HTTP status descriptions
+- **Multi-tab Detection** - Monitor concurrent tab usage
+
+## Usage Examples
+
+### Changing URL Without Reload (SPA Routing)
+
+```javascript
+// Add a new history entry without page reload
+dphelper.browser.state({ page: 'dashboard', userId: 123 }, 'Dashboard', '/dashboard');
+
+// The browser's back button will now work
+window.addEventListener('popstate', (event) => {
+  console.log('Navigated to:', event.state);
+});
+```
+
+### Programmatic Navigation
+
+```javascript
+// Navigate to a specific URL
+dphelper.browser.href('/search?q=javascript');
+
+// Navigate to external site
+dphelper.browser.href('https://google.com');
+
+// Go forward 2 pages in history
+dphelper.browser.forw(2);
+
+// Go back 1 page in history
+dphelper.browser.back(1);
+
+// Reload the page
+dphelper.browser.reload();
+```
+
+### Offline Detection Overlay
+
+```javascript
+// Show default offline message
+dphelper.browser.offLine();
+
+// Show custom offline message (text is sanitized for security)
+dphelper.browser.offLine('⚠️ Connection Lost. Please check your internet.');
+
+// The overlay appears automatically when offline
+// and disappears when connection is restored
+```
+
+### Get Browser Zoom Level
+
+```javascript
+const zoom = dphelper.browser.zoom();
+console.log(zoom); // 100 (or 150, 200, etc. depending on zoom)
+
+// Responsive design based on zoom
+if (zoom > 100) {
+  document.body.classList.add('zoomed-in');
+}
+```
+
+### HTTP Status Code Descriptions
+
+```javascript
+// Get description for common status codes
+console.log(dphelper.browser.status(200)); // "200 OK"
+console.log(dphelper.browser.status(201)); // "201 Created"
+console.log(dphelper.browser.status(301)); // "301 Moved Permanently"
+console.log(dphelper.browser.status(400)); // "400 Bad Request"
+console.log(dphelper.browser.status(401)); // "401 Unauthorized"
+console.log(dphelper.browser.status(403)); // "403 Forbidden"
+console.log(dphelper.browser.status(404)); // "404 Not Found"
+console.log(dphelper.browser.status(500)); // "500 Internal Server Error"
+
+// Display user-friendly error messages
+function handleApiError(statusCode) {
+  const message = dphelper.browser.status(statusCode);
+  alert(`Error: ${message}`);
+}
+```
+
+### Multi-Tab Synchronization
+
+```javascript
+// Monitor active tabs of your application
+dphelper.browser.interlock((tabCount) => {
+  console.log(`Active tabs: ${tabCount}`);
+
+  if (tabCount > 1) {
+    // Warn user about multiple tabs
+    showNotification('This app is open in multiple tabs. Changes may conflict.');
+  }
+});
+
+// Use BroadcastChannel for real-time sync between tabs
+const channel = new BroadcastChannel('app_sync');
+channel.postMessage({ type: 'UPDATE', data: 'new value' });
+```
+
+## Advanced Usage
+
+### Complete SPA Navigation Handler
+
+```javascript
+class Router {
+  constructor() {
+    this.routes = {};
+
+    // Handle browser back/forward
+    window.addEventListener('popstate', (e) => {
+      this.navigate(window.location.pathname, false);
+    });
+  }
+
+  addRoute(path, handler) {
+    this.routes[path] = handler;
+  }
+
+  navigate(path, addToHistory = true) {
+    const handler = this.routes[path];
+    if (handler) {
+      if (addToHistory) {
+        dphelper.browser.state({ path }, 'App', path);
+      }
+      handler();
+    }
+  }
+}
+
+// Usage
+const router = new Router();
+router.addRoute('/', () => renderHome());
+router.addRoute('/about', () => renderAbout());
+router.addRoute('/dashboard', () => renderDashboard());
+```
+
+### Connection Status Manager
+
+```javascript
+class ConnectionManager {
+  constructor() {
+    this.isOnline = navigator.onLine;
+    this.listeners = [];
+
+    window.addEventListener('online', () => {
+      this.isOnline = true;
+      this.notifyListeners();
+    });
+
+    window.addEventListener('offline', () => {
+      this.isOnline = false;
+      this.notifyListeners();
+    });
+
+    // Show offline overlay
+    dphelper.browser.offLine('🔌 You are offline. Some features are disabled.');
+  }
+
+  onStatusChange(callback) {
+    this.listeners.push(callback);
+  }
+
+  notifyListeners() {
+    this.listeners.forEach(cb => cb(this.isOnline));
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*