@geolonia/geonicdb-sdk 0.18.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geolonia/geonicdb-sdk",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "GeonicDB JavaScript SDK — NGSI-LD Context Broker client for browser and Node.js",
   "main": "geonicdb.cjs",
   "module": "geonicdb.mjs",
@@ -47,7 +47,7 @@
   ],
   "peerDependencies": {
     "react": "^18 || ^19",
-    "@geolonia/embed": "^1.0.0"
+    "@geolonia/embed": "^1.0.0 || ^5.0.0"
   },
   "peerDependenciesMeta": {
     "react": {

package/react/index.d.ts

@@ -408,6 +408,20 @@ declare class EventEmitter {
 	protected emit<K extends keyof GeonicDBEventMap>(event: K, data?: GeonicDBEventMap[K]): void;
 	protected emit(event: string, data?: unknown): void;
 }
+/** Options for `GeonicDB.subscribeWebPush()`. */
+export interface WebPushSubscribeOptions {
+	/**
+	 * VAPID public key (base64url). Auto-fetched from
+	 * `GET /.well-known/webpush-vapid-key` when omitted.
+	 */
+	applicationServerKey?: string;
+	/**
+	 * Service worker registration to subscribe through. Defaults to
+	 * `navigator.serviceWorker.ready` — the caller must have already
+	 * registered a service worker (e.g. `navigator.serviceWorker.register('/sw.js')`).
+	 */
+	serviceWorkerRegistration?: ServiceWorkerRegistration;
+}
 declare class GeonicDB extends EventEmitter {
 	private _auth;
 	private _ws;
@@ -594,6 +608,50 @@ declare class GeonicDB extends EventEmitter {
 	isConnected(): boolean;
 	/** Subscribe to entity events (can be called before or after connect). */
 	subscribe(options?: SubscribeOptions): void;
+	/**
+	 * 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`).
+	 */
+	getWebPushVapidKey(): Promise<string>;
+	/**
+	 * 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) },
+	 * });
+	 * ```
+	 */
+	subscribeWebPush(options?: WebPushSubscribeOptions): Promise<PushSubscription>;
+	/**
+	 * 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.
+	 */
+	unsubscribeWebPush(registration?: ServiceWorkerRegistration): Promise<boolean>;
 }
 /**
  * NGSI-LD and GeoJSON types for the ./react subpath.