@geolonia/geonicdb-sdk 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geolonia/geonicdb-sdk",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "GeonicDB JavaScript SDK — NGSI-LD Context Broker client for browser and Node.js",
   "main": "geonicdb.cjs",
   "module": "geonicdb.mjs",

package/react/index.d.ts

@@ -408,6 +408,13 @@ declare class EventEmitter {
 	protected emit<K extends keyof GeonicDBEventMap>(event: K, data?: GeonicDBEventMap[K]): void;
 	protected emit(event: string, data?: unknown): void;
 }
+/** 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 {
 	/**
@@ -422,9 +429,70 @@ export interface WebPushSubscribeOptions {
 	 */
 	serviceWorkerRegistration?: ServiceWorkerRegistration;
 }
+/** Which NGSI protocol `registerWebPushSubscription()` should talk to (#3092). */
+export type WebPushRegisterProtocol = "ngsiv2" | "ngsi-ld";
+/** Entity selector shared by NGSIv2 `subject.entities` and NGSI-LD `entities`. */
+export interface WebPushRegisterEntitySelector {
+	id?: string;
+	idPattern?: string;
+	type?: string;
+}
+/** NGSIv2 subscription `subject` accepted by `registerWebPushSubscription()`. */
+export interface WebPushRegisterNgsiv2Subject {
+	entities: WebPushRegisterEntitySelector[];
+	condition?: {
+		attrs?: string[];
+		expression?: string;
+	};
+}
+/**
+ * Result of `GeonicDB.registerWebPushSubscription()` (#3092).
+ * `created` is `true` only when a new GeonicDB subscription was POSTed;
+ * reuse (and VAPID-rotation PATCH) returns `created: false`.
+ */
+export interface RegisterWebPushSubscriptionResult {
+	subscriptionId: string;
+	created: boolean;
+}
+/**
+ * Options for `GeonicDB.registerWebPushSubscription()` (#3092).
+ *
+ * `protocol` is required with no default — the SDK already exposes separate
+ * NGSIv2 / NGSI-LD converters, and an implicit default would silently register
+ * against the wrong API.
+ */
+export interface RegisterWebPushSubscriptionOptions extends WebPushSubscribeOptions, WebPushDeliveryOptions {
+	protocol: WebPushRegisterProtocol;
+	/** Subscription description. Defaults to `'Web Push notification'`. */
+	description?: string;
+	/** Required when `protocol` is `'ngsiv2'`. */
+	subject?: WebPushRegisterNgsiv2Subject;
+	/** Required when `protocol` is `'ngsi-ld'`. */
+	entities?: WebPushRegisterEntitySelector[];
+	/** NGSI-LD `watchedAttributes` (ignored for NGSIv2 — use `subject.condition.attrs`). */
+	watchedAttributes?: string[];
+	/** NGSI-LD `q` filter (ignored for NGSIv2). */
+	q?: string;
+	/**
+	 * Override the localStorage key used for idempotency. Default is
+	 * `buildWebPushSubscriptionStorageKey(baseUrl, tenant, protocol)` — it does
+	 * **not** include login principal. On a shared browser (kiosk, shared profile)
+	 * or when registering multiple distinct filters from the same origin, pass a
+	 * key that still includes that default scope plus app-managed suffixes
+	 * (e.g. `` `${buildWebPushSubscriptionStorageKey(...)}:${userId}:${filterId}` ``).
+	 * See docs/SDK.md → Web Push (#3097).
+	 */
+	storageKey?: string;
+}
 declare class GeonicDB extends EventEmitter {
 	private _auth;
 	private _ws;
+	/**
+	 * In-flight `registerWebPushSubscription()` calls keyed by storageKey (#3092).
+	 * Concurrent callers with the same key share one Promise so a race cannot
+	 * POST two subscriptions before the first id is persisted.
+	 */
+	private _webPushRegisterInflight;
 	/**
 	 * Legacy callback for token refresh events.
 	 * Prefer `db.on('tokenRefresh', callback)` for new code.
@@ -627,9 +695,13 @@ declare class GeonicDB extends EventEmitter {
 	 * — 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', ...)`.
+	 * is given) and calls `PushManager.subscribe()`.
+	 *
+	 * This method only covers the browser Push API. To also create (or reuse)
+	 * the GeonicDB subscription idempotently, prefer
+	 * `registerWebPushSubscription()` (#3092). For a manual flow, convert the
+	 * result with `toNgsiv2WebPushNotification()` / `toNgsiLdWebPushEndpoint()`
+	 * and `request('POST', ...)`.
 	 *
 	 * Browser-only — throws in environments without Service Worker + Push API
 	 * support (e.g. Node.js).
@@ -637,19 +709,54 @@ declare class GeonicDB extends EventEmitter {
 	 * @example
 	 * ```ts
 	 * await navigator.serviceWorker.register('/sw.js');
-	 * const subscription = await db.subscribeWebPush();
-	 * await db.request('POST', '/v2/subscriptions', {
-	 *   description: 'Web Push notification',
+	 * const { subscriptionId, created } = await db.registerWebPushSubscription({
+	 *   protocol: 'ngsiv2',
 	 *   subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
-	 *   notification: { webpush: toNgsiv2WebPushNotification(subscription) },
 	 * });
 	 * ```
 	 */
 	subscribeWebPush(options?: WebPushSubscribeOptions): Promise<PushSubscription>;
+	/**
+	 * Idempotently register a GeonicDB subscription that delivers via Web Push (#3092).
+	 *
+	 * 1. Calls `subscribeWebPush()` for the browser PushSubscription.
+	 * 2. Looks up a previously saved subscription id in `localStorage`.
+	 * 3. If that id still exists on the broker (`GET` → 200), returns it without
+	 *    `POST`ing. When the push endpoint changed (e.g. VAPID key rotation),
+	 *    `PATCH`es only `notification.webpush` / `endpoint.webpush` so a new
+	 *    subscription is not created (avoids burning the subscription quota).
+	 * 4. Otherwise `POST`s a new subscription and persists its id.
+	 *
+	 * `protocol` is required — there is no default. A 507 from the broker is
+	 * thrown as `QuotaExceededError`.
+	 *
+	 * @example
+	 * ```ts
+	 * import { QuotaExceededError } from '@geolonia/geonicdb-sdk';
+	 *
+	 * try {
+	 *   const { subscriptionId, created } = await db.registerWebPushSubscription({
+	 *     protocol: 'ngsiv2',
+	 *     subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+	 *   });
+	 * } catch (err) {
+	 *   if (err instanceof QuotaExceededError) {
+	 *     // plan grace ceiling — delete unused subscriptions or change plan, then retry
+	 *   }
+	 *   throw err;
+	 * }
+	 * ```
+	 */
+	registerWebPushSubscription(options: RegisterWebPushSubscriptionOptions): Promise<RegisterWebPushSubscriptionResult>;
+	private _registerWebPushSubscriptionBody;
 	/**
 	 * 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.
+	 *
+	 * Does not delete the GeonicDB subscription document — clear the
+	 * persisted id (see `buildWebPushSubscriptionStorageKey`) and
+	 * `DELETE` the subscription separately if needed.
 	 */
 	unsubscribeWebPush(registration?: ServiceWorkerRegistration): Promise<boolean>;
 }