@cloudsignal/pwa-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-14
+
+### Added
+
+- Initial release of CloudSignal PWA SDK
+- **PWAClient** - Main SDK entry point with event-driven architecture
+- **DeviceDetector** - Comprehensive device/browser/OS detection (35+ fields)
+- **ServiceWorkerManager** - Service worker registration and update handling
+- **InstallationManager** - PWA install prompt with iOS manual instructions
+- **PushNotificationManager** - Web Push with VAPID authentication
+- **HeartbeatManager** - Online status tracking with configurable intervals
+- **Service Worker** - Push handling, badge management, notification history
+- Full TypeScript support with exported types
+- Multi-format builds: ESM, CommonJS, IIFE (browser)
+- HMAC authentication for backend API calls
+- Device fingerprinting for unique device identification
+- IndexedDB storage for notification history
+- Network status monitoring (online/offline events)
+
+### Features
+
+- Automatic install prompt capture and management
+- iOS 16.4+ Safari push notification support
+- App badge management via Badge API
+- Configurable heartbeat intervals
+- Debug mode for development
+- Event system for all PWA lifecycle events
+
+### Browser Support
+
+- Chrome 80+
+- Edge 80+
+- Firefox 78+
+- Safari 16.4+ (iOS and macOS)
+- Samsung Internet 13+

package/README.md

@@ -0,0 +1,383 @@
+# CloudSignal PWA SDK
+
+Progressive Web App SDK for CloudSignal platform with push notifications, installation management, and comprehensive device tracking.
+
+## 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
+- **Heartbeat** - Real-time online status tracking
+- **Service Worker** - Badge management, notification history, offline support
+- **TypeScript** - Full type definitions included
+
+## Installation
+
+### npm
+
+```bash
+npm install @cloudsignal/pwa-sdk
+```
+
+### CDN
+
+```html
+<!-- Latest version -->
+<script src="https://cdn.cloudsignal.io/CloudSignalPWA.js"></script>
+
+<!-- Specific version -->
+<script src="https://cdn.cloudsignal.io/cloudsignal-pwa.v1.0.0.js"></script>
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+import { CloudSignalPWA } from '@cloudsignal/pwa-sdk'
+
+const pwa = new CloudSignalPWA({
+  organizationId: 'your-org-uuid',
+  organizationSecret: 'your-secret-key',
+  serviceId: 'your-service-uuid',
+  debug: true
+})
+
+// Initialize (downloads config, registers service worker)
+await pwa.initialize()
+
+// Get device information
+const deviceInfo = pwa.getDeviceInfo()
+console.log('Device:', deviceInfo.deviceModel, deviceInfo.browser)
+
+// Check installation state
+if (pwa.canInstall()) {
+  await pwa.showInstallPrompt()
+}
+
+// Register for push notifications
+const registration = await pwa.registerForPush({
+  userEmail: 'user@example.com'
+})
+```
+
+### CDN Usage
+
+```html
+<script src="https://cdn.cloudsignal.io/CloudSignalPWA.js"></script>
+<script>
+const pwa = new CloudSignalPWA.CloudSignalPWA({
+  organizationId: 'your-org-uuid',
+  organizationSecret: 'your-secret-key',
+  serviceId: 'your-service-uuid'
+})
+
+pwa.initialize().then(() => {
+  console.log('PWA initialized')
+})
+</script>
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new CloudSignalPWA(config: PWAConfig)
+```
+
+**Config Options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `organizationId` | string | Yes | CloudSignal organization UUID |
+| `organizationSecret` | string | Yes | Organization secret key |
+| `serviceId` | string | Yes | PWA service UUID |
+| `serviceUrl` | string | No | Service URL (default: `https://pwa.cloudsignal.app`) |
+| `debug` | boolean | No | Enable debug logging |
+| `serviceWorker` | object | No | Service worker config |
+| `heartbeat` | object | No | Heartbeat config |
+
+### Initialization
+
+```typescript
+// Initialize the PWA client
+await pwa.initialize(): Promise<InitializeResult>
+
+// Download service configuration
+await pwa.downloadConfig(): Promise<PWAServiceConfig | null>
+```
+
+### Installation
+
+```typescript
+// Show install prompt (Chrome/Edge)
+await pwa.showInstallPrompt(): Promise<InstallResult>
+
+// Check if PWA can be installed
+pwa.canInstall(): boolean
+
+// Check if PWA is already installed
+pwa.isInstalled(): boolean
+
+// Get installation state
+pwa.getInstallationState(): InstallationState
+
+// Get install steps for current platform
+pwa.getInstallSteps(): string[]
+```
+
+### Push Notifications
+
+```typescript
+// Register for push notifications
+await pwa.registerForPush(options?: RegisterOptions): Promise<Registration | null>
+
+// Unregister from push notifications
+await pwa.unregisterFromPush(): Promise<boolean>
+
+// Update notification preferences
+await pwa.updatePreferences(prefs: NotificationPreferences): Promise<boolean>
+
+// Check registration status
+await pwa.checkRegistrationStatus(): Promise<RegistrationStatusResponse | null>
+
+// Request notification permission
+await pwa.requestPermission(): Promise<NotificationPermission>
+
+// Check if registered
+pwa.isRegistered(): boolean
+
+// Get registration ID
+pwa.getRegistrationId(): string | null
+```
+
+### Device Information
+
+```typescript
+// Get comprehensive device info (35+ fields)
+pwa.getDeviceInfo(): DeviceInfo
+
+// Get PWA capabilities
+pwa.getCapabilities(): PWACapabilities
+```
+
+### Heartbeat
+
+```typescript
+// Start heartbeat for online status tracking
+pwa.startHeartbeat(): void
+
+// Stop heartbeat
+pwa.stopHeartbeat(): void
+```
+
+### Badge Management
+
+```typescript
+// Clear app badge
+pwa.clearBadge(): void
+
+// Set app badge count
+pwa.setBadge(count: number): void
+```
+
+### Events
+
+```typescript
+// Subscribe to events
+pwa.on(event: PWAEvent, handler: (data) => void): void
+
+// Unsubscribe from events
+pwa.off(event: PWAEvent, handler: (data) => void): void
+```
+
+**Available Events:**
+
+| Event | Description |
+|-------|-------------|
+| `install:available` | Install prompt is available |
+| `install:accepted` | User accepted install |
+| `install:dismissed` | User dismissed install |
+| `install:completed` | PWA was installed |
+| `push:registered` | Push registration successful |
+| `push:unregistered` | Push unregistration successful |
+| `push:error` | Push operation failed |
+| `permission:denied` | Notification permission denied |
+| `config:loaded` | Service config downloaded |
+| `config:error` | Config download failed |
+| `heartbeat:sent` | Heartbeat sent successfully |
+| `heartbeat:error` | Heartbeat failed |
+| `network:online` | Network came online |
+| `network:offline` | Network went offline |
+| `sw:registered` | Service worker registered |
+| `sw:updated` | Service worker updated |
+
+## Service Worker Setup
+
+Copy the service worker to your app's root directory:
+
+```bash
+# If using npm
+cp node_modules/@cloudsignal/pwa-sdk/dist/service-worker.js public/
+```
+
+Or download from CDN:
+
+```bash
+curl -o public/service-worker.js https://cdn.cloudsignal.io/service-worker.v1.0.0.js
+```
+
+## PWA Manifest
+
+Create a `manifest.json` in your app's root:
+
+```json
+{
+  "name": "Your App Name",
+  "short_name": "App",
+  "start_url": "/",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff",
+  "icons": [
+    {
+      "src": "/icon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ]
+}
+```
+
+Add to your HTML:
+
+```html
+<link rel="manifest" href="/manifest.json">
+```
+
+## Device Information
+
+The SDK detects 35+ device attributes:
+
+```javascript
+const info = pwa.getDeviceInfo()
+
+// Operating System
+info.os           // 'iOS', 'Android', 'Windows', 'macOS', 'Linux'
+info.osVersion    // '17.2', '14.0', 'Windows 10/11'
+
+// Device
+info.deviceType   // 'iPhone', 'iPad', 'Phone', 'Tablet', 'Desktop'
+info.deviceModel  // 'iPhone 15 Pro', 'Samsung Galaxy S24'
+info.isMobile     // true/false
+info.isTablet     // true/false
+info.isDesktop    // true/false
+
+// Browser
+info.browser        // 'Chrome', 'Safari', 'Firefox', 'Edge'
+info.browserVersion // '120.0.6099.43'
+
+// PWA Capabilities
+info.supportLevel          // 'full', 'partial', 'basic', 'none'
+info.hasPushManager        // true/false
+info.hasServiceWorker      // true/false
+info.hasBadgeAPI           // true/false
+info.notificationPermission // 'granted', 'denied', 'default'
+
+// Network
+info.isOnline        // true/false
+info.connectionType  // '4g', '3g', '2g', 'unknown'
+```
+
+## Example: React Integration
+
+```jsx
+import { useEffect, useState } from 'react'
+import { CloudSignalPWA } from '@cloudsignal/pwa-sdk'
+
+const pwa = new CloudSignalPWA({
+  organizationId: process.env.REACT_APP_ORG_ID,
+  organizationSecret: process.env.REACT_APP_ORG_SECRET,
+  serviceId: process.env.REACT_APP_SERVICE_ID
+})
+
+function App() {
+  const [canInstall, setCanInstall] = useState(false)
+  const [isRegistered, setIsRegistered] = useState(false)
+
+  useEffect(() => {
+    pwa.initialize().then(() => {
+      setCanInstall(pwa.canInstall())
+      setIsRegistered(pwa.isRegistered())
+    })
+
+    pwa.on('install:available', () => setCanInstall(true))
+    pwa.on('push:registered', () => setIsRegistered(true))
+  }, [])
+
+  const handleInstall = async () => {
+    const result = await pwa.showInstallPrompt()
+    if (result.accepted) {
+      setCanInstall(false)
+    }
+  }
+
+  const handleEnableNotifications = async () => {
+    const registration = await pwa.registerForPush({
+      userEmail: 'user@example.com'
+    })
+    if (registration) {
+      setIsRegistered(true)
+    }
+  }
+
+  return (
+    <div>
+      {canInstall && (
+        <button onClick={handleInstall}>Install App</button>
+      )}
+      {!isRegistered && (
+        <button onClick={handleEnableNotifications}>
+          Enable Notifications
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+## Browser Support
+
+| Browser | PWA Install | Push Notifications |
+|---------|-------------|-------------------|
+| Chrome | ✅ | ✅ |
+| Edge | ✅ | ✅ |
+| Firefox | ❌ | ✅ |
+| Safari (macOS) | ❌ | ✅ (macOS 13+) |
+| Safari (iOS) | Manual | ✅ (iOS 16.4+) |
+| Samsung Internet | ✅ | ✅ |
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import { 
+  CloudSignalPWA,
+  PWAConfig,
+  DeviceInfo,
+  InstallationState,
+  Registration,
+  PWAEvent
+} from '@cloudsignal/pwa-sdk'
+```
+
+## License
+
+MIT License - Copyright (c) 2024 CloudSignal