@geolonia/geonicdb-sdk 0.19.2 → 0.20.0

package/geonicdb.d.ts

@@ -410,15 +410,6 @@ declare class EventEmitter {
  * 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;
@@ -445,6 +436,68 @@ 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;
+}
+/**
+ * Build the default localStorage key for a Web Push GeonicDB subscription id
+ * (`baseUrl` + `tenant` + `protocol` only — not principal). Exported so callers
+ * can append user/filter suffixes for shared-browser isolation (#3097) or clear
+ * the persisted id.
+ */
+export declare function buildWebPushSubscriptionStorageKey(baseUrl: string, tenant: string, protocol: WebPushRegisterProtocol): string;
 /**
  * Accepted by all conversion functions: either a `PushSubscription.toJSON()`
  * plain-object shape (`{ endpoint, keys: { p256dh, auth } }`), or a native
@@ -462,6 +515,14 @@ export interface WebPushSubscriptionLike {
  *
  * @example
  * ```ts
+ * // Prefer the idempotent high-level helper (#3092):
+ * await db.registerWebPushSubscription({
+ *   protocol: 'ngsiv2',
+ *   subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+ *   ttl: 86400,
+ * });
+ *
+ * // Or convert manually:
  * const subscription = await db.subscribeWebPush();
  * const webpush = toNgsiv2WebPushNotification(subscription, { ttl: 86400 });
  * await db.request('POST', '/v2/subscriptions', {
@@ -483,6 +544,13 @@ export declare function toNgsiv2WebPushNotification(subscription: WebPushSubscri
  *
  * @example
  * ```ts
+ * await db.registerWebPushSubscription({
+ *   protocol: 'ngsi-ld',
+ *   entities: [{ type: 'Sensor' }],
+ *   watchedAttributes: ['value'],
+ * });
+ *
+ * // Or convert manually:
  * const subscription = await db.subscribeWebPush();
  * const { uri, webpush } = toNgsiLdWebPushEndpoint(subscription);
  * await db.request('POST', '/ngsi-ld/v1/subscriptions', {
@@ -584,6 +652,15 @@ export declare class RateLimitError extends GeonicDBError {
 	readonly retryAfter: number;
 	constructor(message?: string, retryAfter?: number);
 }
+/**
+ * 507 — Storage quota exceeded (subscriptions / entities / registrations /
+ * temporal data points beyond the plan's grace ceiling). Callers typically
+ * surface a "try again later" toast rather than treating this as a permanent
+ * failure (#3092).
+ */
+export declare class QuotaExceededError extends GeonicDBError {
+	constructor(message?: string);
+}
 /** Network error (fetch failed, DNS resolution, timeout). */
 export declare class NetworkError extends GeonicDBError {
 	constructor(message?: string);
@@ -610,6 +687,12 @@ export declare class NetworkError extends GeonicDBError {
 export 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.
@@ -812,9 +895,13 @@ export 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).
@@ -822,19 +909,54 @@ export 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>;
 }

package/geonicdb.iife.js

@@ -31,10 +31,12 @@ var GeonicDBModule = (() => {
     NetworkError: () => NetworkError,
     NotFoundError: () => NotFoundError,
     PasswordResetRequiredError: () => PasswordResetRequiredError,
+    QuotaExceededError: () => QuotaExceededError,
     RateLimitError: () => RateLimitError,
     TemporaryPasswordExpiredError: () => TemporaryPasswordExpiredError,
     ValidationError: () => ValidationError,
     buildPathWithParams: () => buildPathWithParams,
+    buildWebPushSubscriptionStorageKey: () => buildWebPushSubscriptionStorageKey,
     default: () => index_default,
     toNgsiLdWebPushEndpoint: () => toNgsiLdWebPushEndpoint,
     toNgsiv2WebPushNotification: () => toNgsiv2WebPushNotification,
@@ -95,6 +97,7 @@ var GeonicDBModule = (() => {
   var SDK_CACHE_IDB_STORE = "responses";
   var SDK_CACHE_IDB_VERSION = 1;
   var WEBPUSH_VAPID_KEY_PATH = "/.well-known/webpush-vapid-key";
+  var WEBPUSH_SUBSCRIPTION_ID_STORAGE_PREFIX = "geonicdb:webpush:subscriptionId";
 
   // src/sdk/dpop.ts
   var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
@@ -362,6 +365,12 @@ var GeonicDBModule = (() => {
       this.retryAfter = retryAfter;
     }
   };
+  var QuotaExceededError = class extends GeonicDBError {
+    constructor(message = "Quota exceeded") {
+      super(message, 507);
+      this.name = "QuotaExceededError";
+    }
+  };
   var NetworkError = class extends GeonicDBError {
     constructor(message = "Network error") {
       super(message, 0);
@@ -383,6 +392,8 @@ var GeonicDBModule = (() => {
         return new ValidationError(message);
       case 429:
         return new RateLimitError(message);
+      case 507:
+        return new QuotaExceededError(message);
       default:
         return new GeonicDBError(message, status);
     }
@@ -648,6 +659,10 @@ var GeonicDBModule = (() => {
     get baseUrl() {
       return this._baseUrl;
     }
+    /** Fiware-Service / NGSILD-Tenant value configured at construction time. */
+    get tenant() {
+      return this._tenant;
+    }
     /**
      * True when running unauthenticated.
      *
@@ -1737,6 +1752,9 @@ var GeonicDBModule = (() => {
   }
 
   // src/sdk/webpush.ts
+  function buildWebPushSubscriptionStorageKey(baseUrl, tenant, protocol) {
+    return WEBPUSH_SUBSCRIPTION_ID_STORAGE_PREFIX + ":" + encodeURIComponent(baseUrl) + ":" + encodeURIComponent(tenant) + ":" + protocol;
+  }
   function arrayBufferToBase64Url(buf) {
     const bytes = new Uint8Array(buf);
     let binary = "";
@@ -1797,6 +1815,12 @@ var GeonicDBModule = (() => {
       super();
       __publicField(this, "_auth");
       __publicField(this, "_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.
+       */
+      __publicField(this, "_webPushRegisterInflight", /* @__PURE__ */ new Map());
       /**
        * Legacy callback for token refresh events.
        * Prefer `db.on('tokenRefresh', callback)` for new code.
@@ -2269,9 +2293,13 @@ var GeonicDBModule = (() => {
      * — 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).
@@ -2279,11 +2307,9 @@ var GeonicDBModule = (() => {
      * @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) },
      * });
      * ```
      */
@@ -2303,10 +2329,121 @@ var GeonicDBModule = (() => {
       }
       return registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey });
     }
+    /**
+     * 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;
+     * }
+     * ```
+     */
+    async registerWebPushSubscription(options) {
+      if (!options || options.protocol !== "ngsiv2" && options.protocol !== "ngsi-ld") {
+        throw new GeonicDBError(
+          "registerWebPushSubscription() requires protocol: 'ngsiv2' | 'ngsi-ld'"
+        );
+      }
+      if (options.protocol === "ngsiv2" && !options.subject?.entities?.length) {
+        throw new GeonicDBError(
+          "registerWebPushSubscription({ protocol: 'ngsiv2' }) requires subject.entities"
+        );
+      }
+      if (options.protocol === "ngsi-ld" && !options.entities?.length) {
+        throw new GeonicDBError(
+          "registerWebPushSubscription({ protocol: 'ngsi-ld' }) requires entities"
+        );
+      }
+      const storageKey = options.storageKey ?? buildWebPushSubscriptionStorageKey(
+        this._auth.baseUrl,
+        this._auth.tenant,
+        options.protocol
+      );
+      assertWebPushSubscriptionStorageWritable(storageKey);
+      const inflight = this._webPushRegisterInflight.get(storageKey);
+      if (inflight) return inflight;
+      const run = this._registerWebPushSubscriptionBody(options, storageKey).finally(() => {
+        if (this._webPushRegisterInflight.get(storageKey) === run) {
+          this._webPushRegisterInflight.delete(storageKey);
+        }
+      });
+      this._webPushRegisterInflight.set(storageKey, run);
+      return run;
+    }
+    async _registerWebPushSubscriptionBody(options, storageKey) {
+      const pushSubscription = await this.subscribeWebPush({
+        applicationServerKey: options.applicationServerKey,
+        serviceWorkerRegistration: options.serviceWorkerRegistration
+      });
+      const delivery = {
+        ...options.ttl !== void 0 && { ttl: options.ttl },
+        ...options.urgency !== void 0 && { urgency: options.urgency },
+        ...options.topic !== void 0 && { topic: options.topic }
+      };
+      const savedId = readWebPushSubscriptionId(storageKey);
+      if (savedId) {
+        const collectionPath = webPushSubscriptionCollectionPath(options.protocol);
+        const itemPath = `${collectionPath}/${encodeURIComponent(savedId)}`;
+        try {
+          const existing = await this.request("GET", itemPath);
+          const storedEndpoint = readStoredWebPushEndpoint(options.protocol, existing);
+          if (storedEndpoint && storedEndpoint !== pushSubscription.endpoint) {
+            await this.request(
+              "PATCH",
+              itemPath,
+              buildWebPushPatchBody(options.protocol, pushSubscription, delivery)
+            );
+          }
+          return { subscriptionId: savedId, created: false };
+        } catch (err) {
+          if (!(err instanceof NotFoundError)) throw err;
+          clearWebPushSubscriptionId(storageKey);
+        }
+      }
+      const createPath = webPushSubscriptionCollectionPath(options.protocol);
+      const body = buildWebPushCreateBody(options, pushSubscription, delivery);
+      const res = await this.requestRaw("POST", createPath, body);
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw createErrorFromResponse(res.status, e, "Request failed: " + res.status);
+      }
+      const subscriptionId = subscriptionIdFromLocation(
+        res.headers.get("Location"),
+        options.protocol
+      );
+      writeWebPushSubscriptionId(storageKey, subscriptionId);
+      return { subscriptionId, created: true };
+    }
     /**
      * 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.
      */
     async unsubscribeWebPush(registration) {
       if (typeof navigator === "undefined" || !navigator.serviceWorker) return false;
@@ -2345,6 +2482,126 @@ var GeonicDBModule = (() => {
     const qs = sp.toString();
     return qs ? `${path}?${qs}` : path;
   }
+  function webPushSubscriptionCollectionPath(protocol) {
+    return protocol === "ngsiv2" ? "/v2/subscriptions" : "/ngsi-ld/v1/subscriptions";
+  }
+  function subscriptionIdFromLocation(location, protocol) {
+    if (!location) {
+      throw new GeonicDBError("Missing Location header after Web Push subscription create");
+    }
+    const marker = protocol === "ngsiv2" ? "/v2/subscriptions/" : "/ngsi-ld/v1/subscriptions/";
+    const idx = location.indexOf(marker);
+    const raw = idx >= 0 ? location.slice(idx + marker.length) : location.split("/").pop() || "";
+    const id = decodeURIComponent(raw.split("?")[0].split("#")[0]);
+    if (!id) {
+      throw new GeonicDBError("Could not parse subscription id from Location: " + location);
+    }
+    return id;
+  }
+  function readStoredWebPushEndpoint(protocol, body) {
+    const notification = body.notification;
+    if (!notification) return void 0;
+    if (protocol === "ngsiv2") {
+      const webpush = notification.webpush;
+      return webpush?.url;
+    }
+    const endpoint = notification.endpoint;
+    return endpoint?.uri;
+  }
+  function buildWebPushCreateBody(options, pushSubscription, delivery) {
+    const description = options.description ?? "Web Push notification";
+    if (options.protocol === "ngsiv2") {
+      return {
+        description,
+        subject: options.subject,
+        notification: {
+          webpush: toNgsiv2WebPushNotification(pushSubscription, delivery)
+        }
+      };
+    }
+    const { uri, webpush } = toNgsiLdWebPushEndpoint(pushSubscription, delivery);
+    return {
+      type: "Subscription",
+      description,
+      entities: options.entities,
+      ...options.watchedAttributes && { watchedAttributes: options.watchedAttributes },
+      ...options.q && { q: options.q },
+      notification: {
+        endpoint: { uri, accept: "application/json", protocol: "webpush", webpush }
+      }
+    };
+  }
+  function buildWebPushPatchBody(protocol, pushSubscription, delivery) {
+    if (protocol === "ngsiv2") {
+      return {
+        notification: {
+          webpush: toNgsiv2WebPushNotification(pushSubscription, delivery)
+        }
+      };
+    }
+    const { uri, webpush } = toNgsiLdWebPushEndpoint(pushSubscription, delivery);
+    return {
+      notification: {
+        endpoint: { uri, accept: "application/json", protocol: "webpush", webpush }
+      }
+    };
+  }
+  function readWebPushSubscriptionId(storageKey) {
+    try {
+      if (typeof localStorage === "undefined") return null;
+      return localStorage.getItem(storageKey);
+    } catch {
+      return null;
+    }
+  }
+  function writeWebPushSubscriptionId(storageKey, subscriptionId) {
+    try {
+      if (typeof localStorage === "undefined") {
+        throw new GeonicDBError(
+          "registerWebPushSubscription() requires localStorage for idempotent registration"
+        );
+      }
+      localStorage.setItem(storageKey, subscriptionId);
+    } catch (err) {
+      if (err instanceof GeonicDBError) throw err;
+      throw new GeonicDBError(
+        "registerWebPushSubscription() could not persist subscription id to localStorage"
+      );
+    }
+  }
+  function assertWebPushSubscriptionStorageWritable(storageKey) {
+    const probeKey = storageKey + "::__writable__";
+    try {
+      if (typeof localStorage === "undefined") {
+        throw new GeonicDBError(
+          "registerWebPushSubscription() requires localStorage for idempotent registration"
+        );
+      }
+      localStorage.setItem(probeKey, "1");
+      if (localStorage.getItem(probeKey) !== "1") {
+        throw new GeonicDBError(
+          "registerWebPushSubscription() could not persist subscription id to localStorage"
+        );
+      }
+      localStorage.removeItem(probeKey);
+    } catch (err) {
+      try {
+        if (typeof localStorage !== "undefined") localStorage.removeItem(probeKey);
+      } catch {
+      }
+      if (err instanceof GeonicDBError) throw err;
+      throw new GeonicDBError(
+        "registerWebPushSubscription() could not persist subscription id to localStorage"
+      );
+    }
+  }
+  function clearWebPushSubscriptionId(storageKey) {
+    try {
+      if (typeof localStorage === "undefined") return;
+      localStorage.removeItem(storageKey);
+    } catch {
+    }
+  }
   return __toCommonJS(index_exports);
 })();
 if(typeof window!=="undefined"){window.GeonicDB=GeonicDBModule.GeonicDB||GeonicDBModule.default}