@geolonia/geonicdb-sdk 0.19.1 → 0.19.3

package/geonicdb.mjs

@@ -56,6 +56,7 @@ 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";
+var WEBPUSH_SUBSCRIPTION_ID_STORAGE_PREFIX = "geonicdb:webpush:subscriptionId";
 
 // src/sdk/dpop.ts
 var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
@@ -323,6 +324,12 @@ var RateLimitError = class extends GeonicDBError {
     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);
@@ -344,6 +351,8 @@ function createErrorFromResponse(status, body, fallbackMessage) {
       return new ValidationError(message);
     case 429:
       return new RateLimitError(message);
+    case 507:
+      return new QuotaExceededError(message);
     default:
       return new GeonicDBError(message, status);
   }
@@ -609,6 +618,10 @@ var _AuthManager = class _AuthManager {
   get baseUrl() {
     return this._baseUrl;
   }
+  /** Fiware-Service / NGSILD-Tenant value configured at construction time. */
+  get tenant() {
+    return this._tenant;
+  }
   /**
    * True when running unauthenticated.
    *
@@ -1698,6 +1711,9 @@ function createCachePersistence() {
 }
 
 // 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 = "";
@@ -1758,6 +1774,12 @@ var GeonicDB = class extends EventEmitter {
     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.
@@ -2230,9 +2252,13 @@ var GeonicDB = class 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).
@@ -2240,11 +2266,9 @@ var GeonicDB = class 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) },
    * });
    * ```
    */
@@ -2264,10 +2288,121 @@ var GeonicDB = class extends EventEmitter {
     }
     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;
@@ -2306,6 +2441,126 @@ function buildPathWithParams(path, params) {
   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 {
+  }
+}
 export {
   AuthenticationError,
   AuthorizationError,
@@ -2315,10 +2570,12 @@ export {
   NetworkError,
   NotFoundError,
   PasswordResetRequiredError,
+  QuotaExceededError,
   RateLimitError,
   TemporaryPasswordExpiredError,
   ValidationError,
   buildPathWithParams,
+  buildWebPushSubscriptionStorageKey,
   index_default as default,
   toNgsiLdWebPushEndpoint,
   toNgsiv2WebPushNotification,