@cloudsignal/pwa-sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,9 +1,10 @@
 # CloudSignal PWA SDK
 
-Progressive Web App SDK for CloudSignal platform with push notifications, installation management, and comprehensive device tracking.
+Progressive Web App SDK for CloudSignal platform with push notifications, installation management, comprehensive device tracking, offline resilience, and notification analytics.
 
 ## Features
 
+### Core Features
 - **PWA Installation** - Automatic install prompt handling with iOS manual instructions
 - **Push Notifications** - Web Push Protocol with VAPID authentication
 - **Device Detection** - 35+ device/browser/OS detection fields
@@ -11,6 +12,14 @@ Progressive Web App SDK for CloudSignal platform with push notifications, instal
 - **Service Worker** - Badge management, notification history, offline support
 - **TypeScript** - Full type definitions included
 
+### v1.1.0 Features
+- **Screen Wake Lock** - Prevent screen sleep during critical operations
+- **Offline Request Queue** - IndexedDB-backed queue with auto-retry when online
+- **iOS Install Banner** - Beautiful modal guiding iOS Safari users to install
+- **Network-Aware Heartbeat** - Auto-adjusts based on connection quality (4G/3G/2G)
+- **Battery-Aware Heartbeat** - Pauses when battery <15% to save power
+- **Notification Analytics** - Track displayed/clicked/dismissed events
+
 ## Installation
 
 ### npm
@@ -170,6 +179,61 @@ pwa.startHeartbeat(): void
 
 // Stop heartbeat
 pwa.stopHeartbeat(): void
+
+// Get current interval (may vary with network conditions)
+pwa.getHeartbeatInterval(): number
+
+// Get network connection info
+pwa.getNetworkInfo(): NetworkConnectionInfo
+
+// Get battery info (if available)
+await pwa.getBatteryInfo(): Promise<BatteryInfo | null>
+```
+
+### Screen Wake Lock (v1.1.0)
+
+```typescript
+// Request screen wake lock (prevents screen from sleeping)
+await pwa.requestWakeLock(): Promise<boolean>
+
+// Release wake lock
+pwa.releaseWakeLock(): void
+
+// Get current state
+pwa.getWakeLockState(): WakeLockState
+// Returns: { isSupported: boolean, isActive: boolean }
+```
+
+### Offline Request Queue (v1.1.0)
+
+```typescript
+// Queue a request for later (when offline)
+await pwa.queueOfflineRequest(url, method, body?, headers?): Promise<string | null>
+
+// Process queued requests
+await pwa.processOfflineQueue(): Promise<QueueProcessResult>
+
+// Get queue statistics
+await pwa.getOfflineQueueStats(): Promise<OfflineQueueStats>
+
+// Clear all queued requests
+await pwa.clearOfflineQueue(): Promise<void>
+```
+
+### iOS Install Banner (v1.1.0)
+
+```typescript
+// Show iOS install guidance banner
+pwa.showIOSInstallBanner(): void
+
+// Hide banner
+pwa.hideIOSInstallBanner(): void
+
+// Check if previously dismissed
+pwa.wasIOSBannerDismissed(): boolean
+
+// Reset dismissal state
+pwa.resetIOSBannerDismissal(): void
 ```
 
 ### Badge Management
@@ -208,6 +272,18 @@ pwa.off(event: PWAEvent, handler: (data) => void): void
 | `config:error` | Config download failed |
 | `heartbeat:sent` | Heartbeat sent successfully |
 | `heartbeat:error` | Heartbeat failed |
+| `heartbeat:intervalChanged` | Heartbeat interval adjusted (v1.1.0) |
+| `heartbeat:pausedForBattery` | Heartbeat paused due to low battery (v1.1.0) |
+| `heartbeat:resumedFromBattery` | Heartbeat resumed (v1.1.0) |
+| `wakeLock:acquired` | Screen wake lock acquired (v1.1.0) |
+| `wakeLock:released` | Screen wake lock released (v1.1.0) |
+| `wakeLock:error` | Wake lock operation failed (v1.1.0) |
+| `offlineQueue:queued` | Request added to offline queue (v1.1.0) |
+| `offlineQueue:processed` | Queued request processed (v1.1.0) |
+| `offlineQueue:flushed` | All queued requests processed (v1.1.0) |
+| `iosBanner:shown` | iOS install banner shown (v1.1.0) |
+| `iosBanner:dismissed` | iOS install banner dismissed (v1.1.0) |
+| `iosBanner:installClicked` | User clicked install on iOS banner (v1.1.0) |
 | `network:online` | Network came online |
 | `network:offline` | Network went offline |
 | `sw:registered` | Service worker registered |
@@ -374,10 +450,59 @@ import {
   DeviceInfo,
   InstallationState,
   Registration,
-  PWAEvent
+  PWAEvent,
+  // v1.1.0 types
+  WakeLockState,
+  WakeLockConfig,
+  OfflineQueueConfig,
+  IOSInstallBannerConfig,
+  NetworkConnectionInfo,
+  BatteryInfo,
+  QueueProcessResult,
+  OfflineQueueStats,
 } from '@cloudsignal/pwa-sdk'
 ```
 
+## v1.1.0 Configuration
+
+```javascript
+const pwa = new CloudSignalPWA({
+  organizationId: 'your-org-uuid',
+  organizationSecret: 'your-secret-key',
+  serviceId: 'your-service-uuid',
+  
+  // Wake Lock (prevents screen sleep)
+  wakeLock: {
+    enabled: true,
+    autoRequest: false,  // Request manually when needed
+    reacquireOnVisibility: true,
+  },
+  
+  // Offline Queue (stores failed requests)
+  offlineQueue: {
+    enabled: true,
+    maxQueueSize: 100,
+    maxAgeTTLHours: 24,
+    autoProcessOnOnline: true,
+  },
+  
+  // iOS Install Banner
+  iosInstallBanner: {
+    enabled: true,
+    appName: 'My PWA',
+    showOnFirstVisit: true,
+    showDelay: 3000,
+    dismissRememberDays: 7,
+  },
+  
+  // Notification Analytics
+  notificationAnalytics: {
+    enabled: true,
+    endpoint: 'https://api.example.com/analytics',  // Optional custom endpoint
+  },
+})
+```
+
 ## License
 
-MIT License - Copyright (c) 2024 CloudSignal
+MIT License - Copyright (c) 2024-2025 CloudSignal