@cloudsignal/pwa-sdk 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,74 @@ 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.2.0] - 2025-01-17
+
+### Added
+
+- **JWT Authentication** - User-linked registrations via JWT tokens from identity providers
+- **Dual Auth Mode** - Support both HMAC (anonymous) and JWT (authenticated) authentication
+- `userToken` config option for JWT tokens (Supabase, Firebase, Auth0, Clerk, custom OIDC)
+- `onTokenExpired` callback for automatic token refresh on 401 errors
+- `setUserToken()` method to upgrade from anonymous to authenticated registration
+- `getAuthMode()` method to check current auth mode ('hmac' | 'jwt')
+- `auth:tokenUpdated` event emitted when auth token is updated/upgraded
+- Full TypeScript types for JWT auth utilities
+
+### Changed
+
+- All API calls now support both HMAC signature and JWT Bearer token authentication
+- Registration API extracts user_id and user_email from JWT claims when in JWT mode
+
+### Use Case
+
+Enables smart notification routing - send in-app notifications when users are online (MQTT connected) and web push when offline by linking registrations to authenticated user identities.
+
+## [1.1.1] - 2025-01-17
+
+### Added
+
+- **Vitest Test Framework** - Comprehensive unit test suite with jsdom environment
+- **DeviceDetector Tests** - 16 tests covering device/browser/OS detection
+- **WakeLockManager Tests** - 16 tests covering screen wake lock functionality
+- **i18n Translation Tests** - 18 tests covering all 20 supported languages
+- **Fingerprint Tests** - 7 tests covering unique device fingerprint generation
+- `test:coverage` script for code coverage reporting
+- Total: 57 unit tests passing
+
+## [1.1.0] - 2025-01-17
+
+### Added
+
+- **Screen Wake Lock** - Prevent screen sleep during critical operations (WakeLockManager)
+- **Offline Request Queue** - IndexedDB-backed queue with exponential backoff retry (OfflineQueueManager)
+- **iOS Install Banner** - Beautiful modal guiding iOS Safari users to install (IOSInstallBanner)
+- **20-Language i18n** - Auto-detects browser language for iOS banner
+  - Supported: en, es, fr, de, it, pt, nl, ru, zh, ja, ko, ar, he, hi, tr, pl, sv, da, no, fi
+- **Network-Aware Heartbeat** - Auto-adjusts interval based on connection type (4G=30s, 3G=60s, 2G=120s)
+- **Battery-Aware Heartbeat** - Pauses heartbeat when battery <15% and not charging
+- **Notification Analytics** - Track displayed/clicked/dismissed events in service worker
+- **Save Data Respect** - Reduces heartbeat frequency when user has Save Data enabled
+
+### New Config Options
+
+- `wakeLock` - Screen wake lock configuration
+- `offlineQueue` - Offline request queue settings
+- `iosInstallBanner` - iOS install banner customization
+- `notificationAnalytics` - Analytics tracking settings
+
+### New Events
+
+- `wakeLock:acquired`, `wakeLock:released`, `wakeLock:error`
+- `offlineQueue:queued`, `offlineQueue:processed`, `offlineQueue:flushed`
+- `iosBanner:shown`, `iosBanner:dismissed`, `iosBanner:installClicked`
+- `heartbeat:intervalChanged`, `heartbeat:pausedForBattery`, `heartbeat:resumedFromBattery`
+
+### Browser Support Notes
+
+- Wake Lock: All modern browsers as of March 2025
+- Battery API: Chromium-based browsers only
+- Network Information API: Chromium-based browsers (graceful fallback)
+
 ## [1.0.0] - 2025-01-14
 
 ### Added

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.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
+- **Smart Notification Routing** - Enable in-app vs web push based on user online status
+- **Token Refresh** - Automatic retry on 401 with `onTokenExpired` callback
+
 ### v1.1.0 Features
 - **Screen Wake Lock** - Prevent screen sleep during critical operations
 - **Offline Request Queue** - IndexedDB-backed queue with auto-retry when online
@@ -87,6 +93,50 @@ pwa.initialize().then(() => {
 </script>
 ```
 
+### JWT Authentication (v1.2.0)
+
+For authenticated user registrations, use JWT instead of HMAC:
+
+```javascript
+import { CloudSignalPWA } from '@cloudsignal/pwa-sdk'
+import { supabase } from './supabase' // Your Supabase client
+
+const pwa = new CloudSignalPWA({
+  organizationId: 'your-org-uuid',
+  userToken: (await supabase.auth.getSession()).data.session?.access_token,
+  serviceId: 'your-service-uuid',
+  onTokenExpired: async () => {
+    // Refresh token when 401 received
+    const { data } = await supabase.auth.refreshSession()
+    return data.session?.access_token || ''
+  }
+})
+
+await pwa.initialize()
+
+// Registration will be linked to the authenticated user
+const registration = await pwa.registerForPush()
+```
+
+**Upgrading from Anonymous to Authenticated:**
+
+```javascript
+// Start with HMAC (anonymous)
+const pwa = new CloudSignalPWA({
+  organizationId: 'your-org-uuid',
+  organizationSecret: 'your-secret-key',
+  serviceId: 'your-service-uuid'
+})
+
+await pwa.initialize()
+await pwa.registerForPush() // Anonymous registration
+
+// Later, when user logs in:
+const userToken = await getUserJWT()
+pwa.setUserToken(userToken)
+await pwa.registerForPush() // Re-register with user identity
+```
+
 ## API Reference
 
 ### Constructor
@@ -100,13 +150,17 @@ new CloudSignalPWA(config: PWAConfig)
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `organizationId` | string | Yes | CloudSignal organization UUID |
-| `organizationSecret` | string | Yes | Organization secret key |
+| `organizationSecret` | string | No* | Organization secret key (HMAC mode) |
+| `userToken` | string | No* | JWT token from identity provider |
+| `onTokenExpired` | function | No | Callback to refresh JWT on 401 |
 | `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 |
 
+*Either `organizationSecret` or `userToken` must be provided
+
 ### Initialization
 
 ```typescript
@@ -190,6 +244,17 @@ pwa.getNetworkInfo(): NetworkConnectionInfo
 await pwa.getBatteryInfo(): Promise<BatteryInfo | null>
 ```
 
+### Authentication (v1.2.0)
+
+```typescript
+// Get current authentication mode
+pwa.getAuthMode(): 'hmac' | 'jwt'
+
+// Set/upgrade JWT token (for authenticated users)
+pwa.setUserToken(token: string): void
+// After calling setUserToken, call registerForPush() again to link registration to user
+```
+
 ### Screen Wake Lock (v1.1.0)
 
 ```typescript
@@ -284,6 +349,7 @@ pwa.off(event: PWAEvent, handler: (data) => void): void
 | `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 |

package/dist/chunk-IMM7VF4N.js

@@ -0,0 +1,97 @@
+/**
+ * CloudSignal PWA SDK v1.0.0
+ * https://cloudsignal.io
+ * MIT License
+ */
+
+// src/utils/hmac.ts
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toBase64(buffer) {
+  return btoa(String.fromCharCode(...new Uint8Array(buffer)));
+}
+async function generateHMACSignature(secret, organizationId, timestamp, method, url, body = "") {
+  const encoder = new TextEncoder();
+  let path;
+  let query;
+  try {
+    const urlObj = url.startsWith("http") ? new URL(url) : new URL(url, "https://pwa.cloudsignal.app");
+    path = urlObj.pathname;
+    query = urlObj.search ? urlObj.search.slice(1) : "";
+  } catch {
+    const queryIndex = url.indexOf("?");
+    if (queryIndex > -1) {
+      path = url.slice(0, queryIndex);
+      query = url.slice(queryIndex + 1);
+    } else {
+      path = url;
+      query = "";
+    }
+  }
+  const canonicalParts = [
+    method.toUpperCase(),
+    path,
+    query,
+    organizationId,
+    timestamp
+  ];
+  if (body && body.length > 0) {
+    const bodyHashBuffer = await crypto.subtle.digest("SHA-256", encoder.encode(body));
+    const bodyHashHex = toHex(bodyHashBuffer);
+    canonicalParts.push(bodyHashHex);
+  }
+  const canonicalString = canonicalParts.join("\n");
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(canonicalString));
+  return toBase64(signature);
+}
+async function generateAuthHeaders(organizationId, organizationSecret, method, url, body) {
+  const timestamp = Math.floor(Date.now() / 1e3).toString();
+  const signature = await generateHMACSignature(
+    organizationSecret,
+    organizationId,
+    timestamp,
+    method,
+    url,
+    body || ""
+  );
+  return {
+    "X-CloudSignal-Organization-ID": organizationId,
+    "X-CloudSignal-Timestamp": timestamp,
+    "X-CloudSignal-Signature": signature,
+    "Content-Type": "application/json"
+  };
+}
+async function makeAuthenticatedRequest(organizationId, organizationSecret, method, url, body) {
+  const bodyStr = body ? JSON.stringify(body) : void 0;
+  const headers = await generateAuthHeaders(
+    organizationId,
+    organizationSecret,
+    method,
+    url,
+    bodyStr
+  );
+  const options = {
+    method,
+    headers
+  };
+  if (bodyStr) {
+    options.body = bodyStr;
+  }
+  return fetch(url, options);
+}
+function isValidUUID(value) {
+  if (!value || typeof value !== "string") return false;
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+export { generateAuthHeaders, generateHMACSignature, isValidUUID, makeAuthenticatedRequest };
+//# sourceMappingURL=chunk-IMM7VF4N.js.map
+//# sourceMappingURL=chunk-IMM7VF4N.js.map

package/dist/chunk-IMM7VF4N.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/hmac.ts"],"names":[],"mappings":"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","file":"chunk-IMM7VF4N.js","sourcesContent":["/**\n * HMAC Authentication Utilities\n * Implements CloudSignal's HMAC signature scheme for API authentication\n */\n\n/**\n * Convert ArrayBuffer to hex string\n */\nfunction toHex(buffer: ArrayBuffer): string {\n  return Array.from(new Uint8Array(buffer))\n    .map(b => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/**\n * Convert ArrayBuffer to base64 string\n */\nfunction toBase64(buffer: ArrayBuffer): string {\n  return btoa(String.fromCharCode(...new Uint8Array(buffer)))\n}\n\n/**\n * Generate HMAC signature for CloudSignal API requests\n * \n * @param secret - Organization secret key\n * @param organizationId - Organization UUID\n * @param timestamp - Unix timestamp string\n * @param method - HTTP method (GET, POST, etc.)\n * @param url - Full URL or path\n * @param body - Request body (optional)\n * @returns Base64-encoded HMAC signature\n */\nexport async function generateHMACSignature(\n  secret: string,\n  organizationId: string,\n  timestamp: string,\n  method: string,\n  url: string,\n  body: string = ''\n): Promise<string> {\n  const encoder = new TextEncoder()\n\n  // Parse URL to extract path and query\n  let path: string\n  let query: string\n\n  try {\n    const urlObj = url.startsWith('http')\n      ? new URL(url)\n      : new URL(url, 'https://pwa.cloudsignal.app')\n    path = urlObj.pathname\n    query = urlObj.search ? urlObj.search.slice(1) : ''\n  } catch {\n    // Fallback for simple paths\n    const queryIndex = url.indexOf('?')\n    if (queryIndex > -1) {\n      path = url.slice(0, queryIndex)\n      query = url.slice(queryIndex + 1)\n    } else {\n      path = url\n      query = ''\n    }\n  }\n\n  // Build canonical string parts\n  const canonicalParts = [\n    method.toUpperCase(),\n    path,\n    query,\n    organizationId,\n    timestamp,\n  ]\n\n  // Add body hash if body is present\n  if (body && body.length > 0) {\n    const bodyHashBuffer = await crypto.subtle.digest('SHA-256', encoder.encode(body))\n    const bodyHashHex = toHex(bodyHashBuffer)\n    canonicalParts.push(bodyHashHex)\n  }\n\n  // Join parts with newlines\n  const canonicalString = canonicalParts.join('\\n')\n\n  // Import secret as HMAC key\n  const key = await crypto.subtle.importKey(\n    'raw',\n    encoder.encode(secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign']\n  )\n\n  // Sign the canonical string\n  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(canonicalString))\n\n  return toBase64(signature)\n}\n\n/**\n * Generate authentication headers for CloudSignal API requests\n * \n * @param organizationId - Organization UUID\n * @param organizationSecret - Organization secret key\n * @param method - HTTP method\n * @param url - Request URL\n * @param body - Request body (optional)\n * @returns Headers object with authentication headers\n */\nexport async function generateAuthHeaders(\n  organizationId: string,\n  organizationSecret: string,\n  method: string,\n  url: string,\n  body?: string\n): Promise<Record<string, string>> {\n  const timestamp = Math.floor(Date.now() / 1000).toString()\n  \n  const signature = await generateHMACSignature(\n    organizationSecret,\n    organizationId,\n    timestamp,\n    method,\n    url,\n    body || ''\n  )\n\n  return {\n    'X-CloudSignal-Organization-ID': organizationId,\n    'X-CloudSignal-Timestamp': timestamp,\n    'X-CloudSignal-Signature': signature,\n    'Content-Type': 'application/json',\n  }\n}\n\n/**\n * Make an authenticated request to CloudSignal API\n * \n * @param organizationId - Organization UUID\n * @param organizationSecret - Organization secret key\n * @param method - HTTP method\n * @param url - Request URL\n * @param body - Request body (optional)\n * @returns Fetch Response\n */\nexport async function makeAuthenticatedRequest(\n  organizationId: string,\n  organizationSecret: string,\n  method: string,\n  url: string,\n  body?: Record<string, any>\n): Promise<Response> {\n  const bodyStr = body ? JSON.stringify(body) : undefined\n  \n  const headers = await generateAuthHeaders(\n    organizationId,\n    organizationSecret,\n    method,\n    url,\n    bodyStr\n  )\n\n  const options: RequestInit = {\n    method,\n    headers,\n  }\n\n  if (bodyStr) {\n    options.body = bodyStr\n  }\n\n  return fetch(url, options)\n}\n\n/**\n * Validate UUID format\n * \n * @param value - String to validate\n * @returns Whether the string is a valid UUID\n */\nexport function isValidUUID(value: string | null | undefined): boolean {\n  if (!value || typeof value !== 'string') return false\n  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)\n}\n"]}

package/dist/hmac-LWLR6F7Z.js

@@ -0,0 +1,3 @@
+export { generateAuthHeaders, generateHMACSignature, isValidUUID, makeAuthenticatedRequest } from './chunk-IMM7VF4N.js';
+//# sourceMappingURL=hmac-LWLR6F7Z.js.map
+//# sourceMappingURL=hmac-LWLR6F7Z.js.map

package/dist/hmac-LWLR6F7Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"hmac-LWLR6F7Z.js"}