@cloudsignal/pwa-sdk 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -21,6 +21,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `initialize()` now auto-calls `registerInstallation()` when PWA is detected as installed
 - Prevents duplicate registrations using localStorage tracking
 
+### Documentation
+
+- **Type Corrections**: Fixed `registration.registrationId`, `InstallationState` object type, `queueOfflineRequest` signature, `processOfflineQueue` return type
+- **Prerequisites Section**: Added environment variable configuration guide
+- **Service Worker Setup**: Added root placement guidance, scope configuration, Workbox/Serwist coexistence patterns
+- **Framework Integrations**: Added Next.js App Router guide with dynamic imports, Supabase Auth integration
+- **Event Documentation**: Complete event list with handler signatures
+- **Troubleshooting**: Service worker, permission, iOS, and token/auth issues
+- **Production Checklist**: Pre-deployment verification steps
+- **Migration Guides**: From Firebase Cloud Messaging and OneSignal
+
 ### Backend Support
 
 - `/api/v1/registration/install-only` endpoint now supports JWT authentication

package/README.md

@@ -12,6 +12,12 @@ 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.2.3 Features
+- **Auto Installation Tracking** - Automatically registers PWA installations with backend when detected
+- `registerInstallation()` method for manual installation tracking
+- `isInstallationRegistered()` / `getInstallationId()` helper methods
+- `install:registered` event for installation tracking
+
 ### v1.2.0 Features
 - **JWT Authentication** - User-linked registrations via JWT tokens (Supabase, Firebase, Auth0, Clerk)
 - **Dual Auth Mode** - HMAC for anonymous users, JWT for authenticated users
@@ -44,6 +50,24 @@ npm install @cloudsignal/pwa-sdk
 <script src="https://cdn.cloudsignal.io/cloudsignal-pwa.v1.0.0.js"></script>
 ```
 
+## Prerequisites
+
+### Environment Variables
+
+Set up your environment variables before using the SDK:
+
+```bash
+# .env.local (Next.js) or .env
+NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID=your-org-uuid
+NEXT_PUBLIC_CLOUDSIGNAL_SERVICE_ID=your-service-uuid
+NEXT_PUBLIC_CLOUDSIGNAL_ORG_SECRET=your-secret-key  # For HMAC mode only
+```
+
+**Where to get these values:**
+1. **Organization ID** - From CloudSignal dashboard → Organization Settings
+2. **Service ID** - From CloudSignal dashboard → PWA Services → Your Service
+3. **Organization Secret** - From CloudSignal dashboard → API Keys (for HMAC mode)
+
 ## Quick Start
 
 ### Basic Usage
@@ -65,8 +89,9 @@ await pwa.initialize()
 const deviceInfo = pwa.getDeviceInfo()
 console.log('Device:', deviceInfo.deviceModel, deviceInfo.browser)
 
-// Check installation state
-if (pwa.canInstall()) {
+// Check installation state - returns InstallationState object
+const installState = pwa.getInstallationState()
+if (installState.canBeInstalled && !installState.isInstalled) {
   await pwa.showInstallPrompt()
 }
 
@@ -74,6 +99,11 @@ if (pwa.canInstall()) {
 const registration = await pwa.registerForPush({
   userEmail: 'user@example.com'
 })
+
+// Access registration ID (note: registrationId, not id)
+if (registration) {
+  console.log('Registered with ID:', registration.registrationId)
+}
 ```
 
 ### CDN Usage
@@ -183,11 +213,28 @@ pwa.canInstall(): boolean
 // Check if PWA is already installed
 pwa.isInstalled(): boolean
 
-// Get installation state
+// Get installation state (full details)
 pwa.getInstallationState(): InstallationState
+// Returns: {
+//   isInstalled: boolean,
+//   canBeInstalled: boolean,
+//   needsManualInstall: boolean,
+//   showManualInstructions: boolean,
+//   installSteps: string[],
+//   displayMode: 'browser' | 'standalone' | 'minimal-ui' | 'fullscreen'
+// }
 
 // Get install steps for current platform
 pwa.getInstallSteps(): string[]
+
+// Register installation with backend (v1.2.3)
+await pwa.registerInstallation(): Promise<{ registrationId: string } | null>
+
+// Check if installation is registered (v1.2.3)
+pwa.isInstallationRegistered(): boolean
+
+// Get installation registration ID (v1.2.3)
+pwa.getInstallationId(): string | null
 ```
 
 ### Push Notifications
@@ -273,13 +320,27 @@ pwa.getWakeLockState(): WakeLockState
 
 ```typescript
 // Queue a request for later (when offline)
-await pwa.queueOfflineRequest(url, method, body?, headers?): Promise<string | null>
+// Signature: queueRequest(url, method, options)
+await pwa.queueOfflineRequest(
+  url: string,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+  options?: {
+    headers?: Record<string, string>,
+    body?: string,
+    requestType?: 'registration' | 'heartbeat' | 'analytics' | 'preferences' | 'unregister' | 'custom',
+    priority?: number,
+    maxRetries?: number,
+    metadata?: Record<string, any>
+  }
+): Promise<number | null>  // Returns queue ID or null
 
-// Process queued requests
-await pwa.processOfflineQueue(): Promise<QueueProcessResult>
+// Process queued requests - returns array of results
+await pwa.processOfflineQueue(): Promise<QueueProcessResult[]>
+// QueueProcessResult: { id: number, success: boolean, statusCode?: number, error?: string, shouldRetry: boolean }
 
 // Get queue statistics
 await pwa.getOfflineQueueStats(): Promise<OfflineQueueStats>
+// OfflineQueueStats: { totalQueued: number, byType: Record<string, number>, oldestRequest?: number, newestRequest?: number }
 
 // Clear all queued requests
 await pwa.clearOfflineQueue(): Promise<void>
@@ -323,40 +384,75 @@ 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 |
-| `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) |
-| `auth:tokenUpdated` | JWT token updated/upgraded (v1.2.0) |
-| `network:online` | Network came online |
-| `network:offline` | Network went offline |
-| `sw:registered` | Service worker registered |
-| `sw:updated` | Service worker updated |
+**Installation Events:**
+- `install:available` - Install prompt is available. Handler: `(data: { platforms: string[] }) => void`
+- `install:accepted` - User accepted install. Handler: `(data: { outcome: 'accepted', platform?: string }) => void`
+- `install:dismissed` - User dismissed install. Handler: `(data: { outcome: 'dismissed' }) => void`
+- `install:completed` - PWA was installed
+- `install:registered` - PWA installation registered with backend (v1.2.3). Handler: `(data: { registrationId: string }) => void`
+- `install:error` - Installation error occurred
+
+**Push Notification Events:**
+- `push:registered` - Push registration successful. Handler: `(data: { registrationId: string, endpoint: string }) => void`
+- `push:unregistered` - Push unregistration successful
+- `push:updated` - Push registration updated
+- `push:error` - Push operation failed. Handler: `(data: { error: Error }) => void`
+- `push:received` - Push notification received. Handler: `(data: { payload: NotificationPayload, timestamp: number }) => void`
+- `push:clicked` - Notification clicked. Handler: `(data: { action?: string, data?: any, url?: string }) => void`
+
+**Permission Events:**
+- `permission:granted` - Notification permission granted
+- `permission:denied` - Notification permission denied
+- `permission:prompt` - Permission prompt shown
+
+**Service Worker Events:**
+- `sw:registered` - Service worker registered
+- `sw:updated` - Service worker updated
+- `sw:error` - Service worker error
+- `sw:activated` - Service worker activated
+
+**Config Events:**
+- `config:loaded` - Service config downloaded. Handler: `(data: { config: PWAServiceConfig }) => void`
+- `config:error` - Config download failed
+
+**Heartbeat Events:**
+- `heartbeat:started` - Heartbeat started
+- `heartbeat:stopped` - Heartbeat stopped
+- `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)
+
+**Network Events:**
+- `network:online` - Network came online
+- `network:offline` - Network went offline
+
+**Wake Lock Events (v1.1.0):**
+- `wakeLock:acquired` - Screen wake lock acquired
+- `wakeLock:released` - Screen wake lock released
+- `wakeLock:error` - Wake lock operation failed
+
+**Offline Queue Events (v1.1.0):**
+- `offlineQueue:queued` - Request added to offline queue
+- `offlineQueue:processed` - Queued request processed
+- `offlineQueue:flushed` - All queued requests processed
+
+**iOS Banner Events (v1.1.0):**
+- `iosBanner:shown` - iOS install banner shown
+- `iosBanner:dismissed` - iOS install banner dismissed
+- `iosBanner:installClicked` - User clicked install on iOS banner
+
+**Authentication Events (v1.2.0):**
+- `auth:tokenUpdated` - JWT token updated/upgraded
+
+**State Events:**
+- `state:changed` - SDK state changed
 
 ## Service Worker Setup
 
+**IMPORTANT:** The service worker MUST be placed at your app's root (e.g., `/service-worker.js` or `/public/service-worker.js`) to ensure correct scope. Service workers can only control pages within their scope.
+
 Copy the service worker to your app's root directory:
 
 ```bash
@@ -370,6 +466,43 @@ Or download from CDN:
 curl -o public/service-worker.js https://cdn.cloudsignal.io/service-worker.v1.0.0.js
 ```
 
+### Custom Service Worker Path
+
+If you need a different path or filename:
+
+```javascript
+const pwa = new CloudSignalPWA({
+  // ...other config
+  serviceWorker: {
+    path: '/sw.js',  // Custom path
+    scope: '/',       // Must match or be parent of your app routes
+    autoRegister: true,
+    updateBehavior: 'auto'  // 'prompt' | 'auto' | 'manual'
+  }
+})
+```
+
+### Workbox/Serwist Compatibility
+
+**IMPORTANT:** CloudSignal's service worker is **not compatible** with Workbox, Serwist, or other PWA service worker libraries. You must use one or the other.
+
+**Why?** CloudSignal's service worker handles:
+- Push notification reception and display
+- Dynamic manifest downloading and caching
+- Notification click routing
+- Badge management
+- Offline notification history
+
+These features require full control of the service worker lifecycle.
+
+**If you're currently using Workbox/Serwist:**
+1. Remove the existing service worker library (`@serwist/next`, `next-pwa`, `workbox-webpack-plugin`, etc.)
+2. Use CloudSignal's service worker instead
+3. If you need precaching, consider using the browser's native Cache API in your application code
+
+**If you need features from Workbox (like precaching):**
+Open an issue on GitHub - we may add these capabilities to the CloudSignal service worker in future versions.
+
 ## PWA Manifest
 
 Create a `manifest.json` in your app's root:
@@ -437,7 +570,197 @@ info.isOnline        // true/false
 info.connectionType  // '4g', '3g', '2g', 'unknown'
 ```
 
-## Example: React Integration
+## Framework Integration Examples
+
+### Next.js (App Router)
+
+**IMPORTANT:** The SDK uses browser APIs and must be loaded client-side only.
+
+```tsx
+// components/CloudSignalProvider.tsx
+'use client'
+
+import { useEffect, useState, createContext, useContext, ReactNode } from 'react'
+import type { CloudSignalPWA as CloudSignalPWAType } from '@cloudsignal/pwa-sdk'
+
+type PWAContextType = {
+  pwa: CloudSignalPWAType | null
+  isInitialized: boolean
+  canInstall: boolean
+  isRegistered: boolean
+}
+
+const PWAContext = createContext<PWAContextType>({
+  pwa: null,
+  isInitialized: false,
+  canInstall: false,
+  isRegistered: false
+})
+
+export function CloudSignalProvider({ children }: { children: ReactNode }) {
+  const [pwa, setPwa] = useState<CloudSignalPWAType | null>(null)
+  const [isInitialized, setIsInitialized] = useState(false)
+  const [canInstall, setCanInstall] = useState(false)
+  const [isRegistered, setIsRegistered] = useState(false)
+
+  useEffect(() => {
+    // Dynamic import - required for Next.js App Router
+    const initPWA = async () => {
+      try {
+        const { CloudSignalPWA } = await import('@cloudsignal/pwa-sdk')
+        
+        const instance = new CloudSignalPWA({
+          organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID!,
+          organizationSecret: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_SECRET!,
+          serviceId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_SERVICE_ID!,
+          debug: process.env.NODE_ENV === 'development'
+        })
+
+        await instance.initialize()
+        
+        setPwa(instance)
+        setIsInitialized(true)
+        setCanInstall(instance.canInstall())
+        setIsRegistered(instance.isRegistered())
+
+        // Set up event listeners
+        instance.on('install:available', () => setCanInstall(true))
+        instance.on('install:completed', () => setCanInstall(false))
+        instance.on('push:registered', () => setIsRegistered(true))
+        instance.on('push:unregistered', () => setIsRegistered(false))
+      } catch (error) {
+        console.error('Failed to initialize CloudSignal PWA:', error)
+      }
+    }
+
+    initPWA()
+  }, [])
+
+  return (
+    <PWAContext.Provider value={{ pwa, isInitialized, canInstall, isRegistered }}>
+      {children}
+    </PWAContext.Provider>
+  )
+}
+
+export const usePWA = () => useContext(PWAContext)
+```
+
+```tsx
+// app/layout.tsx
+import { CloudSignalProvider } from '@/components/CloudSignalProvider'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <CloudSignalProvider>
+          {children}
+        </CloudSignalProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+```tsx
+// components/InstallButton.tsx
+'use client'
+
+import { usePWA } from './CloudSignalProvider'
+
+export function InstallButton() {
+  const { pwa, canInstall } = usePWA()
+
+  if (!canInstall) return null
+
+  const handleInstall = async () => {
+    const result = await pwa?.showInstallPrompt()
+    if (result?.accepted) {
+      console.log('App installed!')
+    }
+  }
+
+  return <button onClick={handleInstall}>Install App</button>
+}
+```
+
+### Next.js with Supabase Auth
+
+```tsx
+// components/CloudSignalSupabaseProvider.tsx
+'use client'
+
+import { useEffect, useState, createContext, useContext, ReactNode } from 'react'
+import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
+import type { CloudSignalPWA as CloudSignalPWAType } from '@cloudsignal/pwa-sdk'
+
+const supabase = createClientComponentClient()
+
+type PWAContextType = {
+  pwa: CloudSignalPWAType | null
+  isInitialized: boolean
+}
+
+const PWAContext = createContext<PWAContextType>({ pwa: null, isInitialized: false })
+
+export function CloudSignalSupabaseProvider({ children }: { children: ReactNode }) {
+  const [pwa, setPwa] = useState<CloudSignalPWAType | null>(null)
+  const [isInitialized, setIsInitialized] = useState(false)
+
+  useEffect(() => {
+    let instance: CloudSignalPWAType | null = null
+
+    const initPWA = async () => {
+      const { CloudSignalPWA } = await import('@cloudsignal/pwa-sdk')
+      const { data: { session } } = await supabase.auth.getSession()
+
+      instance = new CloudSignalPWA({
+        organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID!,
+        serviceId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_SERVICE_ID!,
+        // Use JWT if user is logged in, fall back to HMAC
+        userToken: session?.access_token,
+        organizationSecret: !session ? process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_SECRET : undefined,
+        onTokenExpired: async () => {
+          const { data } = await supabase.auth.refreshSession()
+          return data.session?.access_token || ''
+        }
+      })
+
+      await instance.initialize()
+      setPwa(instance)
+      setIsInitialized(true)
+    }
+
+    initPWA()
+
+    // Listen for auth changes to update token
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      async (event, session) => {
+        if (instance && session?.access_token) {
+          instance.setUserToken(session.access_token)
+          // Re-register to link to user
+          await instance.registerForPush()
+        }
+      }
+    )
+
+    return () => {
+      subscription.unsubscribe()
+    }
+  }, [])
+
+  return (
+    <PWAContext.Provider value={{ pwa, isInitialized }}>
+      {children}
+    </PWAContext.Provider>
+  )
+}
+
+export const usePWA = () => useContext(PWAContext)
+```
+
+### React (Create React App / Vite)
 
 ```jsx
 import { useEffect, useState } from 'react'
@@ -569,6 +892,147 @@ const pwa = new CloudSignalPWA({
 })
 ```
 
+## Troubleshooting
+
+### Service Worker Issues
+
+**Problem:** Service worker not registering
+```
+DOMException: Failed to register a ServiceWorker
+```
+
+**Solutions:**
+1. Ensure service worker is at root path (`/service-worker.js`)
+2. Check HTTPS is enabled (required except on localhost)
+3. Verify service worker path in config matches actual file location
+4. Check browser console for detailed error
+
+**Problem:** Push notifications not received after service worker update
+
+**Solution:** The SDK handles this automatically with `updateBehavior: 'auto'`. If using manual mode, call `pwa.getServiceWorkerManager().update()` after deploy.
+
+### Permission Issues
+
+**Problem:** Permission prompt never appears
+
+**Causes:**
+1. User previously denied permission (check `pwa.getDeviceInfo().notificationPermission`)
+2. Site not served over HTTPS
+3. Browser settings blocking notifications globally
+
+**Solution for denied permission:**
+```javascript
+const deviceInfo = pwa.getDeviceInfo()
+if (deviceInfo.notificationPermission === 'denied') {
+  // Guide user to browser settings
+  alert('Please enable notifications in your browser settings')
+}
+```
+
+### iOS-Specific Issues
+
+**Problem:** Install prompt not showing on iOS Safari
+
+**Explanation:** iOS Safari doesn't support the Web App Install Banner API. Use the iOS Install Banner feature:
+```javascript
+const pwa = new CloudSignalPWA({
+  // ...config
+  iosInstallBanner: {
+    enabled: true,
+    appName: 'My App',
+    showOnFirstVisit: true
+  }
+})
+```
+
+**Problem:** Push notifications not working on iOS
+
+**Requirements:**
+- iOS 16.4+
+- PWA must be installed to home screen
+- User must grant permission after installation
+
+### Token/Auth Issues
+
+**Problem:** 401 errors after token expires
+
+**Solution:** Implement `onTokenExpired` callback:
+```javascript
+const pwa = new CloudSignalPWA({
+  // ...config
+  onTokenExpired: async () => {
+    // Your token refresh logic
+    const newToken = await refreshMyToken()
+    return newToken
+  }
+})
+```
+
+**Problem:** Registration not linked to user after login
+
+**Solution:** Call `setUserToken()` followed by `registerForPush()`:
+```javascript
+pwa.setUserToken(newJWT)
+await pwa.registerForPush()  // Re-registers with user identity
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+```javascript
+const pwa = new CloudSignalPWA({
+  // ...config
+  debug: true  // Logs all SDK operations to console
+})
+```
+
+## Production Checklist
+
+Before deploying to production, verify:
+
+- [ ] **HTTPS enabled** - Required for service workers and push notifications
+- [ ] **Service worker at root** - `/service-worker.js` or `/public/service-worker.js`
+- [ ] **Manifest.json configured** - Icons, name, start_url, display mode
+- [ ] **Environment variables set** - Organization ID, Service ID, Secret/JWT config
+- [ ] **VAPID keys configured** - In CloudSignal dashboard
+- [ ] **Test on target devices** - iOS Safari, Chrome, Firefox, Edge
+- [ ] **Test install flow** - Both automatic prompt and iOS manual instructions
+- [ ] **Test push notifications** - Send test notification from dashboard
+- [ ] **Test offline behavior** - Verify offline queue and reconnection
+- [ ] **Token refresh tested** - If using JWT, verify refresh flow works
+- [ ] **Error handling** - Graceful degradation when features unavailable
+
+## Migration from Other Services
+
+### From Firebase Cloud Messaging (FCM)
+
+CloudSignal uses Web Push directly (not FCM). Key differences:
+- No Firebase SDK dependency
+- VAPID keys instead of FCM server key
+- Direct Web Push Protocol
+
+```javascript
+// Before (FCM)
+import { getMessaging, getToken } from 'firebase/messaging'
+const token = await getToken(messaging, { vapidKey: '...' })
+
+// After (CloudSignal)
+import { CloudSignalPWA } from '@cloudsignal/pwa-sdk'
+const registration = await pwa.registerForPush()
+```
+
+### From OneSignal
+
+Remove OneSignal SDK and replace with CloudSignal:
+```javascript
+// Before
+OneSignal.push(['init', { appId: '...' }])
+
+// After
+const pwa = new CloudSignalPWA({ organizationId: '...', serviceId: '...' })
+await pwa.initialize()
+```
+
 ## License
 
 MIT License - Copyright (c) 2024-2025 CloudSignal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudsignal/pwa-sdk",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "CloudSignal PWA SDK - Progressive Web App features with push notifications, JWT/HMAC authentication, installation management, device tracking, offline queue, wake lock, and notification analytics",
   "main": "dist/index.cjs",
   "module": "dist/index.js",