@geolonia/geonicdb-sdk 0.18.1 → 0.19.1

package/geonicdb.d.ts

@@ -406,6 +406,104 @@ declare class EventEmitter {
 	protected emit<K extends keyof GeonicDBEventMap>(event: K, data?: GeonicDBEventMap[K]): void;
 	protected emit(event: string, data?: unknown): void;
 }
+/**
+ * Copyright (c) 2026 Geolonia Inc.
+ * Released under the MIT License. See src/sdk/LICENSE for details.
+ */
+/**
+ * Web Push (VAPID) notification helpers (#3014 / #3060).
+ *
+ * Pure conversion functions between the browser Push API and the
+ * NGSIv2 `notification.webpush` / NGSI-LD `endpoint.webpush` shapes
+ * documented in docs/SUBSCRIPTIONS.md. These do not touch the network —
+ * see `GeonicDB.getWebPushVapidKey()` / `subscribeWebPush()` /
+ * `unsubscribeWebPush()` in `./index` for the browser-facing API.
+ */
+/** `PushSubscription.toJSON().keys` shape (RFC 8291). */
+export interface WebPushKeys {
+	p256dh: string;
+	auth: string;
+}
+/** RFC 8030 delivery options, shared by both NGSI protocol shapes. */
+export interface WebPushDeliveryOptions {
+	/** Push message TTL in seconds. */
+	ttl?: number;
+	urgency?: "very-low" | "low" | "normal" | "high";
+	topic?: string;
+}
+/** 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;
+}
+/**
+ * Accepted by all conversion functions: either a `PushSubscription.toJSON()`
+ * plain-object shape (`{ endpoint, keys: { p256dh, auth } }`), or a native
+ * `PushSubscription` instance, which has no `keys` property and exposes the
+ * raw key material via `getKey()` instead (RFC 8291).
+ */
+export interface WebPushSubscriptionLike {
+	endpoint?: string;
+	keys?: Partial<WebPushKeys>;
+	getKey?: (name: "p256dh" | "auth") => ArrayBuffer | null;
+}
+/**
+ * Convert a browser `PushSubscription` (or its `.toJSON()` output) into the
+ * NGSIv2 `notification.webpush` shape (#3014).
+ *
+ * @example
+ * ```ts
+ * const subscription = await db.subscribeWebPush();
+ * const webpush = toNgsiv2WebPushNotification(subscription, { ttl: 86400 });
+ * await db.request('POST', '/v2/subscriptions', {
+ *   description: 'Web Push notification',
+ *   subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+ *   notification: { webpush },
+ * });
+ * ```
+ */
+export declare function toNgsiv2WebPushNotification(subscription: WebPushSubscriptionLike, options?: WebPushDeliveryOptions): {
+	url: string;
+	keys: WebPushKeys;
+} & WebPushDeliveryOptions;
+/**
+ * Convert a browser `PushSubscription` (or its `.toJSON()` output) into the
+ * NGSI-LD `endpoint.webpush` shape (#3014, GeonicDB extension). The
+ * returned object is meant to be spread into `notification.endpoint`
+ * alongside `uri`.
+ *
+ * @example
+ * ```ts
+ * const subscription = await db.subscribeWebPush();
+ * const { uri, webpush } = toNgsiLdWebPushEndpoint(subscription);
+ * await db.request('POST', '/ngsi-ld/v1/subscriptions', {
+ *   type: 'Subscription',
+ *   entities: [{ type: 'Sensor' }],
+ *   notification: { endpoint: { uri, accept: 'application/json', webpush } },
+ * });
+ * ```
+ */
+export declare function toNgsiLdWebPushEndpoint(subscription: WebPushSubscriptionLike, options?: WebPushDeliveryOptions): {
+	uri: string;
+	webpush: {
+		keys: WebPushKeys;
+	} & WebPushDeliveryOptions;
+};
+/**
+ * Convert a base64url-encoded VAPID public key (as returned by
+ * `GET /.well-known/webpush-vapid-key`) into the `Uint8Array` expected by
+ * `PushManager.subscribe({ applicationServerKey })`.
+ */
+export declare function urlBase64ToUint8Array(base64Url: string): Uint8Array<ArrayBuffer>;
 /**
  * Copyright (c) 2026 Geolonia Inc.
  * Released under the MIT License. See src/sdk/LICENSE for details.
@@ -695,6 +793,50 @@ export 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>;
 }
 /**
  * 汎用クエリ文字列ビルダ。`undefined` / `null` は省略、`boolean` は

package/geonicdb.iife.js

@@ -35,7 +35,10 @@ var GeonicDBModule = (() => {
     TemporaryPasswordExpiredError: () => TemporaryPasswordExpiredError,
     ValidationError: () => ValidationError,
     buildPathWithParams: () => buildPathWithParams,
-    default: () => index_default
+    default: () => index_default,
+    toNgsiLdWebPushEndpoint: () => toNgsiLdWebPushEndpoint,
+    toNgsiv2WebPushNotification: () => toNgsiv2WebPushNotification,
+    urlBase64ToUint8Array: () => urlBase64ToUint8Array
   });
 
   // src/sdk/events.ts
@@ -91,6 +94,7 @@ var GeonicDBModule = (() => {
   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 GeonicDBModule = (() => {
         });
       }
     }
+    /** The base URL requests are sent against (trailing slash already stripped). */
+    get baseUrl() {
+      return this._baseUrl;
+    }
     /**
      * True when running unauthenticated.
      *
@@ -1728,6 +1736,61 @@ var GeonicDBModule = (() => {
     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 GeonicDBModule = (() => {
     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") {