@geolonia/geonicdb-sdk 0.19.2 → 0.19.3

package/README.md

@@ -374,32 +374,43 @@ await db.connect();
 | `cacheMiss` | `CacheEvent` | Cache miss — fresh response fetched from origin |
 | `cacheInvalidated` | `CacheEvent` | Cache entry dropped via explicit `clearCache()`. WebSocket entity events do **not** trigger cache invalidation — see "Client-side Cache & Polling" |
 
-## Web Push Notifications (#3014 / #3060)
+## Web Push Notifications (#3014 / #3060 / #3092)
 
 GeonicDB supports browser Web Push (VAPID) as a third NGSI subscription notification protocol
 (alongside HTTP webhook and MQTT — see [SUBSCRIPTIONS.md](https://github.com/geolonia/geonicdb/blob/main/docs/SUBSCRIPTIONS.md#web-push-3014)
-for the full API contract). The SDK wraps the browser Push API and the NGSI payload shape so you
-don't have to.
+for the full API contract). Prefer the idempotent helper that covers both the browser Push API
+and the GeonicDB subscription create:
 
 ```javascript
-// 1. Register a service worker in your app's origin.
-await navigator.serviceWorker.register('/sw.js');
-
-// 2. Subscribe — VAPID public key is auto-fetched from the deployment's discovery endpoint.
-const subscription = await db.subscribeWebPush();
+import GeonicDB, { QuotaExceededError } from '@geolonia/geonicdb-sdk';
 
-// 3. Create the NGSI subscription with the converted payload.
-import { toNgsiv2WebPushNotification } from '@geolonia/geonicdb-sdk';
+await navigator.serviceWorker.register('/sw.js');
 
-await db.request('POST', '/v2/subscriptions', {
-  description: 'Web Push notification',
-  subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
-  notification: { webpush: toNgsiv2WebPushNotification(subscription, { ttl: 86400 }) },
-});
+try {
+  const { subscriptionId, created } = await db.registerWebPushSubscription({
+    protocol: 'ngsiv2', // required — no default ('ngsi-ld' also supported)
+    subject: { entities: [{ type: 'Sensor' }], condition: { attrs: ['value'] } },
+    ttl: 86400,
+  });
+} catch (err) {
+  if (err instanceof QuotaExceededError) {
+    // 507 — subscription quota grace ceiling; retry later
+  }
+  throw err;
+}
 ```
 
-For NGSI-LD, use `toNgsiLdWebPushEndpoint(subscription)` instead, which returns `{ uri, webpush }`
-to spread into `notification.endpoint`.
+Calling `registerWebPushSubscription()` again reuses the id stored in `localStorage` when the
+broker still has that subscription (`GET` → 200) and does not `POST`. After a VAPID key rotation
+that changes the push endpoint, it `PATCH`es `notification.webpush` / `endpoint.webpush` instead
+of creating a new subscription. The default key is `baseUrl` + `tenant` + `protocol`; for shared
+browsers or multiple distinct filters, pass `storageKey` that still includes that scope (e.g.
+append `:${userId}:${filterId}` to `buildWebPushSubscriptionStorageKey(...)`). Concurrent calls with the same
+key share one in-flight Promise. HTTP 507 (`QuotaExceededError`) requires deleting unused
+subscriptions or changing the plan — waiting alone will not clear the quota.
+
+Low-level helpers remain available: `subscribeWebPush()` + `toNgsiv2WebPushNotification()` /
+`toNgsiLdWebPushEndpoint()` + `request('POST', ...)`.
 
 `sw.js` receives the raw NGSI notification body in the `push` event:
 
@@ -414,13 +425,15 @@ self.addEventListener('push', (event) => {
 Calling `subscribeWebPush()` again on an already-subscribed registration returns the existing
 `PushSubscription` as-is if it still matches the current VAPID public key. If the deployment
 rotated its VAPID keys, the stale subscription is unsubscribed and replaced with a fresh one
-signed by the new key. Call `await db.unsubscribeWebPush()` to unsubscribe.
+signed by the new key. Call `await db.unsubscribeWebPush()` to unsubscribe the browser side.
 
 | Method | Returns | Description |
 |--------|---------|--------------|
 | `getWebPushVapidKey()` | `Promise<string>` | Fetch the deployment's VAPID public key (unauthenticated discovery endpoint) |
-| `subscribeWebPush(options?)` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()`. Browser-only — throws in Node.js |
+| `subscribeWebPush(options?)` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()`. Browser-only — does not create a GeonicDB subscription |
+| `registerWebPushSubscription(options)` | `Promise<{ subscriptionId, created }>` | Idempotent browser + GeonicDB registration (#3092). `protocol` required. 507 → `QuotaExceededError` |
 | `unsubscribeWebPush(registration?)` | `Promise<boolean>` | Unsubscribe; `false` if there was no active subscription |
+| `buildWebPushSubscriptionStorageKey(baseUrl, tenant, protocol)` | `string` | Default `localStorage` key used for idempotency |
 
 ## Client-side Cache & Polling
 
@@ -692,8 +705,10 @@ handle.stop();
 | Method | Parameters | Returns | Description |
 |--------|-----------|---------|-------------|
 | `getWebPushVapidKey()` | — | `Promise<string>` | Fetch the deployment's VAPID public key |
-| `subscribeWebPush(options?)` | `WebPushSubscribeOptions` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()` |
+| `subscribeWebPush(options?)` | `WebPushSubscribeOptions` | `Promise<PushSubscription>` | Subscribe via `PushManager.subscribe()` (browser only; no GeonicDB registration) |
+| `registerWebPushSubscription(options)` | `RegisterWebPushSubscriptionOptions` | `Promise<RegisterWebPushSubscriptionResult>` | Idempotent browser + GeonicDB registration (#3092). `protocol` required |
 | `unsubscribeWebPush(registration?)` | `ServiceWorkerRegistration` | `Promise<boolean>` | Unsubscribe from Web Push |
+| `buildWebPushSubscriptionStorageKey(...)` | `baseUrl, tenant, protocol` | `string` | Default localStorage key for idempotency |
 
 #### `WebPushSubscribeOptions`
 
@@ -745,6 +760,7 @@ try {
 | `ConflictError` | 409 | Entity already exists |
 | `ValidationError` | 422 | Bad request payload |
 | `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
+| `QuotaExceededError` | 507 | Storage / subscription quota exceeded (beyond plan grace ceiling) |
 | `NetworkError` | — | Fetch failure, DNS error, timeout |
 
 ### Which request failed (`request`)

package/geonicdb.cjs

@@ -30,10 +30,12 @@ __export(index_exports, {
   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 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;
@@ -362,6 +365,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);
@@ -383,6 +392,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);
   }
@@ -648,6 +659,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.
    *
@@ -1737,6 +1752,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 = "";
@@ -1797,6 +1815,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.
@@ -2269,9 +2293,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).
@@ -2279,11 +2307,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) },
    * });
    * ```
    */
@@ -2303,10 +2329,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;
@@ -2345,4 +2482,124 @@ 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 {
+  }
+}
 //# sourceMappingURL=geonicdb.cjs.map