@geolonia/geonicdb-sdk 0.18.1 → 0.19.0

package/README.md

@@ -374,6 +374,54 @@ await db.connect();
 | `cacheMiss` | `CacheEvent` | Cache miss — fresh response fetched from origin |
 | `cacheInvalidated` | `CacheEvent` | Cache entry dropped via explicit `clearCache()`. WebSocket entity events do **not** trigger cache invalidation — see "Client-side Cache & Polling" |
 
+## Web Push Notifications (#3014 / #3060)
+
+GeonicDB supports browser Web Push (VAPID) as a third NGSI subscription notification protocol
+(alongside HTTP webhook and MQTT — see [SUBSCRIPTIONS.md](https://github.com/geolonia/geonicdb/blob/main/docs/SUBSCRIPTIONS.md#web-push-3014)
+for the full API contract). The SDK wraps the browser Push API and the NGSI payload shape so you
+don't have to.
+
+```javascript
+// 1. Register a service worker in your app's origin.
+await navigator.serviceWorker.register('/sw.js');
+
+// 2. Subscribe — VAPID public key is auto-fetched from the deployment's discovery endpoint.
+const subscription = await db.subscribeWebPush();
+
+// 3. Create the NGSI subscription with the converted payload.
+import { toNgsiv2WebPushNotification } from '@geolonia/geonicdb-sdk';
+
+await db.request('POST', '/v2/subscriptions', {
+  description: 'Web Push notification',
+  subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+  notification: { webpush: toNgsiv2WebPushNotification(subscription, { ttl: 86400 }) },
+});
+```
+
+For NGSI-LD, use `toNgsiLdWebPushEndpoint(subscription)` instead, which returns `{ uri, webpush }`
+to spread into `notification.endpoint`.
+
+`sw.js` receives the raw NGSI notification body in the `push` event:
+
+```javascript
+// sw.js
+self.addEventListener('push', (event) => {
+  const payload = event.data.json();
+  event.waitUntil(self.registration.showNotification('GeonicDB', { body: JSON.stringify(payload) }));
+});
+```
+
+Calling `subscribeWebPush()` again on an already-subscribed registration returns the existing
+`PushSubscription` as-is if it still matches the current VAPID public key. If the deployment
+rotated its VAPID keys, the stale subscription is unsubscribed and replaced with a fresh one
+signed by the new key. Call `await db.unsubscribeWebPush()` to unsubscribe.
+
+| Method | Returns | Description |
+|--------|---------|--------------|
+| `getWebPushVapidKey()` | `Promise<string>` | Fetch the deployment's VAPID public key (unauthenticated discovery endpoint) |
+| `subscribeWebPush(options?)` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()`. Browser-only — throws in Node.js |
+| `unsubscribeWebPush(registration?)` | `Promise<boolean>` | Unsubscribe; `false` if there was no active subscription |
+
 ## Client-side Cache & Polling
 
 The SDK includes an in-memory cache that handles `ETag` / `If-None-Match`
@@ -639,6 +687,21 @@ handle.stop();
 | `on(event, listener)` | `string, Function` | `this` | Register an event listener |
 | `off(event, listener)` | `string, Function` | `this` | Remove an event listener |
 
+### Web Push
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getWebPushVapidKey()` | — | `Promise<string>` | Fetch the deployment's VAPID public key |
+| `subscribeWebPush(options?)` | `WebPushSubscribeOptions` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()` |
+| `unsubscribeWebPush(registration?)` | `ServiceWorkerRegistration` | `Promise<boolean>` | Unsubscribe from Web Push |
+
+#### `WebPushSubscribeOptions`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `applicationServerKey` | `string` | VAPID public key (base64url). Auto-fetched via `getWebPushVapidKey()` when omitted |
+| `serviceWorkerRegistration` | `ServiceWorkerRegistration` | Registration to subscribe through. Defaults to `navigator.serviceWorker.ready` |
+
 ## Error Handling
 
 All async methods throw typed errors extending `GeonicDBError`. Use `instanceof` to distinguish error types.

package/geonicdb.cjs

@@ -34,7 +34,10 @@ __export(index_exports, {
   TemporaryPasswordExpiredError: () => TemporaryPasswordExpiredError,
   ValidationError: () => ValidationError,
   buildPathWithParams: () => buildPathWithParams,
-  default: () => index_default
+  default: () => index_default,
+  toNgsiLdWebPushEndpoint: () => toNgsiLdWebPushEndpoint,
+  toNgsiv2WebPushNotification: () => toNgsiv2WebPushNotification,
+  urlBase64ToUint8Array: () => urlBase64ToUint8Array
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -91,6 +94,7 @@ var DPOP_IDB_VERSION = 1;
 var SDK_CACHE_IDB_NAME = "geonicdb-sdk-cache";
 var SDK_CACHE_IDB_STORE = "responses";
 var SDK_CACHE_IDB_VERSION = 1;
+var WEBPUSH_VAPID_KEY_PATH = "/.well-known/webpush-vapid-key";
 
 // src/sdk/dpop.ts
 var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
@@ -640,6 +644,10 @@ var _AuthManager = class _AuthManager {
       });
     }
   }
+  /** The base URL requests are sent against (trailing slash already stripped). */
+  get baseUrl() {
+    return this._baseUrl;
+  }
   /**
    * True when running unauthenticated.
    *
@@ -1728,6 +1736,61 @@ function createCachePersistence() {
   return cachePersistenceSupported ? new IdbCachePersistence() : null;
 }
 
+// src/sdk/webpush.ts
+function arrayBufferToBase64Url(buf) {
+  const bytes = new Uint8Array(buf);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function extractKeys(subscription) {
+  const endpoint = subscription.endpoint;
+  let p256dh = subscription.keys?.p256dh;
+  let auth = subscription.keys?.auth;
+  if ((!p256dh || !auth) && typeof subscription.getKey === "function") {
+    const p256dhBuf = subscription.getKey("p256dh");
+    const authBuf = subscription.getKey("auth");
+    if (!p256dh && p256dhBuf) p256dh = arrayBufferToBase64Url(p256dhBuf);
+    if (!auth && authBuf) auth = arrayBufferToBase64Url(authBuf);
+  }
+  if (!endpoint || !p256dh || !auth) {
+    throw new Error(
+      "Invalid PushSubscription: endpoint, keys.p256dh, and keys.auth are all required"
+    );
+  }
+  return { endpoint, keys: { p256dh, auth } };
+}
+function toNgsiv2WebPushNotification(subscription, options) {
+  const { endpoint, keys } = extractKeys(subscription);
+  return { url: endpoint, keys, ...options };
+}
+function toNgsiLdWebPushEndpoint(subscription, options) {
+  const { endpoint, keys } = extractKeys(subscription);
+  return { uri: endpoint, webpush: { keys, ...options } };
+}
+function urlBase64ToUint8Array(base64Url) {
+  const padding = "=".repeat((4 - base64Url.length % 4) % 4);
+  const base64 = (base64Url + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(base64);
+  const output = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) {
+    output[i] = raw.charCodeAt(i);
+  }
+  return output;
+}
+function matchesApplicationServerKey(subscription, desiredKey) {
+  const existingKey = subscription.options?.applicationServerKey;
+  if (!existingKey) return true;
+  const existingBytes = new Uint8Array(existingKey);
+  if (existingBytes.length !== desiredKey.length) return false;
+  for (let i = 0; i < existingBytes.length; i++) {
+    if (existingBytes[i] !== desiredKey[i]) return false;
+  }
+  return true;
+}
+
 // src/sdk/index.ts
 var GeonicDB = class extends EventEmitter {
   constructor(options) {
@@ -2174,6 +2237,84 @@ var GeonicDB = class extends EventEmitter {
   subscribe(options) {
     this._ws.subscribe(options);
   }
+  // --- Web Push (#3014 / #3060) ---
+  /**
+   * Fetch the deployment's VAPID public key for Web Push subscriptions.
+   *
+   * Hits the unauthenticated discovery endpoint
+   * `GET /.well-known/webpush-vapid-key` directly (not via `request()`) —
+   * it needs no login/API key and predates any session setup. Throws
+   * `GeonicDBError` with `statusCode: 503` if the deployment has no VAPID
+   * keys configured (503 has no dedicated error class — see
+   * `createErrorFromResponse()` in `./errors`).
+   */
+  async getWebPushVapidKey() {
+    const res = await fetch(this._auth.baseUrl + WEBPUSH_VAPID_KEY_PATH);
+    if (!res.ok) {
+      const e = await res.json().catch(() => ({}));
+      throw createErrorFromResponse(
+        res.status,
+        e,
+        "Failed to fetch Web Push VAPID key: " + res.status
+      );
+    }
+    const body = await res.json();
+    return body.publicKey;
+  }
+  /**
+   * Subscribe the current browser to Web Push notifications (#3014).
+   *
+   * Reuses an existing subscription on the service worker registration if
+   * one is already active *and* still matches the resolved VAPID public key
+   * — otherwise (e.g. after the deployment rotated its VAPID keys) it
+   * unsubscribes the stale one and re-subscribes with the current key.
+   * Fetches the deployment's VAPID public key (unless `applicationServerKey`
+   * is given) and calls `PushManager.subscribe()`. Convert the result with
+   * `toNgsiv2WebPushNotification()` / `toNgsiLdWebPushEndpoint()` and create
+   * the NGSI subscription with `request('POST', ...)`.
+   *
+   * Browser-only — throws in environments without Service Worker + Push API
+   * support (e.g. Node.js).
+   *
+   * @example
+   * ```ts
+   * await navigator.serviceWorker.register('/sw.js');
+   * const subscription = await db.subscribeWebPush();
+   * await db.request('POST', '/v2/subscriptions', {
+   *   description: 'Web Push notification',
+   *   subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+   *   notification: { webpush: toNgsiv2WebPushNotification(subscription) },
+   * });
+   * ```
+   */
+  async subscribeWebPush(options) {
+    if (typeof navigator === "undefined" || !navigator.serviceWorker || typeof window === "undefined" || !window.PushManager) {
+      throw new Error(
+        "subscribeWebPush() requires a browser with Service Worker + Push API support"
+      );
+    }
+    const registration = options?.serviceWorkerRegistration ?? await navigator.serviceWorker.ready;
+    const publicKey = options?.applicationServerKey ?? await this.getWebPushVapidKey();
+    const applicationServerKey = urlBase64ToUint8Array(publicKey);
+    const existing = await registration.pushManager.getSubscription();
+    if (existing) {
+      if (matchesApplicationServerKey(existing, applicationServerKey)) return existing;
+      await existing.unsubscribe();
+    }
+    return registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey });
+  }
+  /**
+   * Unsubscribe the current browser from Web Push notifications, if
+   * subscribed. Returns `false` (no-op) when there is no active
+   * subscription or the environment has no Service Worker support.
+   */
+  async unsubscribeWebPush(registration) {
+    if (typeof navigator === "undefined" || !navigator.serviceWorker) return false;
+    const reg = registration ?? await navigator.serviceWorker.ready;
+    const existing = await reg.pushManager.getSubscription();
+    if (!existing) return false;
+    return existing.unsubscribe();
+  }
 };
 var index_default = GeonicDB;
 if (typeof window !== "undefined") {