@geolonia/geonicdb-sdk 0.2.1 → 0.4.0

package/geonicdb.mjs

@@ -147,13 +147,178 @@ var RECONNECT_MAX_ATTEMPTS = 10;
 var RECONNECT_BASE_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
 var SUB_PROTOCOL = "access_token";
+var SDK_CACHE_MAX_ENTRIES_DEFAULT = 1e3;
+var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
+
+// src/sdk/errors.ts
+var GeonicDBError = class extends Error {
+  constructor(message, statusCode = 0) {
+    super(message);
+    /** HTTP status code (if applicable) */
+    __publicField(this, "statusCode");
+    this.name = "GeonicDBError";
+    this.statusCode = statusCode;
+  }
+};
+var AuthenticationError = class extends GeonicDBError {
+  constructor(message = "Authentication failed") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends GeonicDBError {
+  constructor(message = "Access denied") {
+    super(message, 403);
+    this.name = "AuthorizationError";
+  }
+};
+var NotFoundError = class extends GeonicDBError {
+  constructor(message = "Not found") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ConflictError = class extends GeonicDBError {
+  constructor(message = "Conflict") {
+    super(message, 409);
+    this.name = "ConflictError";
+  }
+};
+var ValidationError = class extends GeonicDBError {
+  constructor(message = "Validation failed") {
+    super(message, 422);
+    this.name = "ValidationError";
+  }
+};
+var RateLimitError = class extends GeonicDBError {
+  constructor(message = "Rate limit exceeded", retryAfter = 1) {
+    super(message, 429);
+    /** Seconds to wait before retrying (from Retry-After header) */
+    __publicField(this, "retryAfter");
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var NetworkError = class extends GeonicDBError {
+  constructor(message = "Network error") {
+    super(message, 0);
+    this.name = "NetworkError";
+  }
+};
+function createErrorFromResponse(status, body, fallbackMessage) {
+  const message = body.detail || body.description || fallbackMessage;
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message);
+    case 403:
+      return new AuthorizationError(message);
+    case 404:
+      return new NotFoundError(message);
+    case 409:
+      return new ConflictError(message);
+    case 422:
+      return new ValidationError(message);
+    case 429:
+      return new RateLimitError(message);
+    default:
+      return new GeonicDBError(message, status);
+  }
+}
+
+// src/sdk/cache.ts
+var SdkCache = class {
+  constructor(maxEntries = SDK_CACHE_MAX_ENTRIES_DEFAULT) {
+    __publicField(this, "_store", /* @__PURE__ */ new Map());
+    __publicField(this, "_maxEntries");
+    if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+      throw new Error(`SdkCache maxEntries must be a positive integer, got ${String(maxEntries)}`);
+    }
+    this._maxEntries = maxEntries;
+  }
+  /** Build a stable cache key. Method is upper-cased so casing differences do not produce duplicate entries. */
+  static keyFor(method, path) {
+    return `${method.toUpperCase()}:${path}`;
+  }
+  /** Returns the entry and bumps it to most-recent position, or `undefined`. */
+  get(key) {
+    const entry = this._store.get(key);
+    if (!entry) return void 0;
+    this._store.delete(key);
+    this._store.set(key, entry);
+    return entry;
+  }
+  /** Insert or replace an entry. Evicts the LRU entry when over capacity. */
+  set(key, entry) {
+    if (this._store.has(key)) {
+      this._store.delete(key);
+    }
+    this._store.set(key, entry);
+    while (this._store.size > this._maxEntries) {
+      const oldest = this._store.keys().next().value;
+      if (oldest === void 0) break;
+      this._store.delete(oldest);
+    }
+  }
+  /** Delete a specific entry. Returns whether anything was removed. */
+  delete(key) {
+    return this._store.delete(key);
+  }
+  /**
+   * Delete every entry whose key matches a predicate. Returns the array of
+   * removed keys so callers can emit `cacheInvalidated` events.
+   */
+  deleteWhere(predicate) {
+    const removed = [];
+    for (const [key, entry] of this._store) {
+      if (predicate(key, entry)) {
+        this._store.delete(key);
+        removed.push(key);
+      }
+    }
+    return removed;
+  }
+  /** Drop everything. */
+  clear() {
+    this._store.clear();
+  }
+  /** Current entry count. Useful for tests / metrics. */
+  size() {
+    return this._store.size;
+  }
+};
+var HEADERS_TO_PERSIST = [
+  "content-type",
+  "etag",
+  "last-modified",
+  "cache-control",
+  "vary",
+  "link",
+  "ngsild-results-count",
+  "fiware-total-count",
+  "x-total-count",
+  "ngsild-next",
+  "fiware-next-token"
+];
+function snapshotHeaders(headers) {
+  const out = {};
+  for (const name of HEADERS_TO_PERSIST) {
+    const value = headers.get(name);
+    if (value !== null) out[name] = value;
+  }
+  return out;
+}
+function isCacheableMethod(method) {
+  const upper = method.toUpperCase();
+  return upper === "GET" || upper === "HEAD";
+}
 
 // src/sdk/auth.ts
 var _AuthManager = class _AuthManager {
-  constructor(baseUrl, apiKey, tenant) {
+  constructor(baseUrl, apiKey, tenant, debug = false) {
     __publicField(this, "_baseUrl");
     __publicField(this, "_apiKey");
     __publicField(this, "_tenant");
+    __publicField(this, "_debug");
     __publicField(this, "_token", null);
     __publicField(this, "_tokenExpiry", 0);
     __publicField(this, "_tokenType", "Bearer");
@@ -164,9 +329,20 @@ var _AuthManager = class _AuthManager {
     __publicField(this, "_tokenPromise", null);
     /** Callback to emit tokenRefresh events. Set by GeonicDB class. */
     __publicField(this, "onTokenRefresh", null);
+    /**
+     * SDK-level cache (#991 Phase A). When set, cacheable GET requests are
+     * served via ETag/304 with automatic If-None-Match negotiation, and
+     * concurrent requests to the same path are deduplicated.
+     */
+    __publicField(this, "_cache", null);
+    /** Emitter for cacheHit / cacheMiss / cacheInvalidated events. */
+    __publicField(this, "_emitCacheEvent", null);
+    /** In-flight request map keyed by `${METHOD}:${path}` for request deduplication. */
+    __publicField(this, "_inFlight", /* @__PURE__ */ new Map());
     this._baseUrl = baseUrl;
     this._apiKey = apiKey;
     this._tenant = tenant;
+    this._debug = debug;
     if (dpopSupported) {
       this._dpopReady = generateDPoPKeyPair().then((kp) => {
         this._dpopKeyPair = kp;
@@ -175,8 +351,28 @@ var _AuthManager = class _AuthManager {
       });
     }
   }
+  _log(...args) {
+    if (this._debug) console.log("[GeonicDB]", ...args);
+  }
+  /** Wire an SdkCache instance (called by GeonicDB constructor when caching is enabled). */
+  setCache(cache) {
+    this._cache = cache;
+  }
+  /** Provide the cache event emitter (forwarded to the GeonicDB EventEmitter). */
+  setCacheEventEmitter(emitter) {
+    this._emitCacheEvent = emitter;
+  }
+  /** Expose the cache for invalidation (e.g. WebSocket entity events). */
+  getCache() {
+    return this._cache;
+  }
+  /** Emit a cache event if a listener is wired. */
+  emitCacheEvent(name, payload) {
+    this._emitCacheEvent?.(name, payload);
+  }
   /** Login with email and password (Bearer JWT). */
   async login(email, password) {
+    this._log("login", email);
     const headers = {
       "Content-Type": "application/json"
     };
@@ -188,7 +384,7 @@ var _AuthManager = class _AuthManager {
     });
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
+      throw new AuthenticationError(
         e.detail || e.description || "Login failed: " + res.status
       );
     }
@@ -197,6 +393,7 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
     this._tokenType = "Bearer";
     this._refreshToken = data.refreshToken;
+    this._invalidateAuthScopedState();
     return data;
   }
   /**
@@ -211,6 +408,7 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = opts.expiresIn != null ? Date.now() + (opts.expiresIn - 60) * 1e3 : Date.now() + DEFAULT_TOKEN_TTL_SEC * 1e3;
     this._refreshToken = opts.refreshToken || null;
     this._tokenPromise = null;
+    this._invalidateAuthScopedState();
   }
   /** Clear all credentials. */
   logout() {
@@ -218,6 +416,17 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = 0;
     this._refreshToken = null;
     this._tokenPromise = null;
+    this._invalidateAuthScopedState();
+  }
+  /**
+   * Drop everything that may have been associated with the previous auth
+   * context. Called on `login()` (after token assignment), `setCredentials()`,
+   * and `logout()`. Without this, a cached body or in-flight Response from
+   * user A could be returned to user B after a credentials swap.
+   */
+  _invalidateAuthScopedState() {
+    this._cache?.clear();
+    this._inFlight.clear();
   }
   /** Ensure a valid token is available, refreshing or acquiring as needed. */
   async ensureToken() {
@@ -235,6 +444,7 @@ var _AuthManager = class _AuthManager {
     return this._tokenPromise;
   }
   async _refreshBearerToken() {
+    this._log("refreshing Bearer token");
     try {
       const res = await fetch(this._baseUrl + "/auth/refresh", {
         method: "POST",
@@ -245,7 +455,7 @@ var _AuthManager = class _AuthManager {
         this._refreshToken = null;
         this._token = null;
         this._tokenPromise = null;
-        throw new Error("Token refresh failed: " + res.status);
+        throw new AuthenticationError("Token refresh failed: " + res.status);
       }
       const data = await res.json();
       this._token = data.accessToken;
@@ -274,7 +484,7 @@ var _AuthManager = class _AuthManager {
         body: JSON.stringify({ api_key: this._apiKey })
       });
       if (!nonceRes.ok)
-        throw new Error("Nonce request failed: " + nonceRes.status);
+        throw new AuthenticationError("Nonce request failed: " + nonceRes.status);
       const nonceData = await nonceRes.json();
       if (nonceData.dpop_nonce) this._dpopNonce = nonceData.dpop_nonce;
       const proof = await solvePoW(nonceData.challenge, nonceData.difficulty);
@@ -287,7 +497,7 @@ var _AuthManager = class _AuthManager {
       });
       const res = await this._doTokenExchange(tokenUrl, tokenBody, this._dpopNonce);
       if (!res.ok)
-        throw new Error("Token request failed: " + res.status);
+        throw new AuthenticationError("Token request failed: " + res.status);
       const newNonce = res.headers.get("DPoP-Nonce");
       if (newNonce) this._dpopNonce = newNonce;
       const data = await res.json();
@@ -327,20 +537,98 @@ var _AuthManager = class _AuthManager {
           return this._doTokenExchange(tokenUrl, tokenBody, serverNonce, retryCount + 1);
         }
       }
-      throw new Error(
-        "Token request failed: " + (errBody.error_description || errBody.error)
+      throw new GeonicDBError(
+        "Token request failed: " + (errBody.error_description || errBody.error),
+        400
       );
     }
     return res;
   }
   /**
    * Make an authenticated HTTP request with automatic token refresh and DPoP.
+   *
+   * When the SDK cache is enabled and the request is cacheable
+   * (GET / HEAD without a body), this method:
+   *   - Sends `If-None-Match` / `If-Modified-Since` derived from a previously
+   *     cached entry, if any.
+   *   - Returns the cached body wrapped in a synthesized `200` Response when
+   *     the server replies `304 Not Modified`.
+   *   - Persists fresh `200` responses (with their ETag/Last-Modified) into
+   *     the cache.
+   *   - Deduplicates concurrent in-flight requests to the same path.
    */
   async request(method, path, body) {
+    this._log(method, path);
+    if (!this._cache || !isCacheableMethod(method) || body !== void 0) {
+      const token = await this.ensureToken();
+      const res = await this._doAuthenticatedRequest(method, path, body, token);
+      this._log(method, path, "\u2192", res.status);
+      return res;
+    }
+    const key = SdkCache.keyFor(method, path);
+    const inFlight = this._inFlight.get(key);
+    if (inFlight) {
+      return inFlight.then((res) => res.clone());
+    }
+    const promise = this._cachedRequest(method, path, key);
+    this._inFlight.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      this._inFlight.delete(key);
+    }
+  }
+  async _cachedRequest(method, path, key) {
+    const cache = this._cache;
+    if (!cache) {
+      const token2 = await this.ensureToken();
+      return this._doAuthenticatedRequest(method, path, void 0, token2);
+    }
+    const cached = cache.get(key);
+    const conditional = {};
+    if (cached?.etag) conditional["If-None-Match"] = cached.etag;
+    if (cached?.lastModified) conditional["If-Modified-Since"] = cached.lastModified;
     const token = await this.ensureToken();
-    return this._doAuthenticatedRequest(method, path, body, token);
+    const res = await this._doAuthenticatedRequest(method, path, void 0, token, 0, conditional);
+    this._log(method, path, "\u2192", res.status);
+    if (res.status === 304 && cached) {
+      const refreshedHeaders = { ...cached.headers, ...snapshotHeaders(res.headers) };
+      const refreshedEtag = res.headers.get("etag") ?? cached.etag;
+      const refreshedLastModified = res.headers.get("last-modified") ?? cached.lastModified;
+      cache.set(key, {
+        ...cached,
+        etag: refreshedEtag,
+        lastModified: refreshedLastModified,
+        headers: refreshedHeaders,
+        cachedAt: Date.now()
+      });
+      this.emitCacheEvent("cacheHit", { key, path });
+      const body = typeof cached.data === "string" ? cached.data : JSON.stringify(cached.data);
+      return new Response(body, { status: 200, headers: refreshedHeaders });
+    }
+    if (res.status === 200) {
+      const etag = res.headers.get("etag") ?? void 0;
+      const lastModified = res.headers.get("last-modified") ?? void 0;
+      if (etag || lastModified) {
+        const text = await res.clone().text();
+        let data = text;
+        try {
+          data = JSON.parse(text);
+        } catch {
+        }
+        cache.set(key, {
+          etag,
+          lastModified,
+          data,
+          headers: snapshotHeaders(res.headers),
+          cachedAt: Date.now()
+        });
+        this.emitCacheEvent("cacheMiss", { key, path });
+      }
+    }
+    return res;
   }
-  async _doAuthenticatedRequest(method, path, body, token, retryCount = 0) {
+  async _doAuthenticatedRequest(method, path, body, token, retryCount = 0, extraHeaders = {}) {
     const url = this._baseUrl + path;
     const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair;
     const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
@@ -356,7 +644,8 @@ var _AuthManager = class _AuthManager {
       const headers = {
         Authorization: (reqIsDPoP ? "DPoP " : "Bearer ") + reqToken,
         "Content-Type": "application/ld+json",
-        Accept: "application/ld+json"
+        Accept: "application/ld+json",
+        ...extraHeaders
       };
       if (dpopProof) headers["DPoP"] = dpopProof;
       if (this._tenant) headers["Fiware-Service"] = this._tenant;
@@ -392,7 +681,7 @@ var _AuthManager = class _AuthManager {
       if (retryNonce) this._dpopNonce = retryNonce;
       const delay = parseInt(res.headers.get("Retry-After") || "1", 10) * 1e3;
       await new Promise((resolve) => setTimeout(resolve, delay));
-      return this._doAuthenticatedRequest(method, path, body, currentToken, retryCount + 1);
+      return this._doAuthenticatedRequest(method, path, body, currentToken, retryCount + 1, extraHeaders);
     }
     return res;
   }
@@ -423,6 +712,9 @@ var WebSocketManager = class {
     this._emit = emit;
     this._wsEndpointOverride = wsEndpointOverride || null;
   }
+  _log(...args) {
+    if (this._auth._debug) console.log("[GeonicDB:WS]", ...args);
+  }
   /** Establish WebSocket connection (authentication is automatic). */
   async connect() {
     if (this._reconnectTimer) {
@@ -500,10 +792,12 @@ var WebSocketManager = class {
     const endpoint = await this._discoverWsEndpoint();
     return new Promise((resolve, reject) => {
       const wsUrl = endpoint + (endpoint.indexOf("?") === -1 ? "?" : "&") + "tenant=" + encodeURIComponent(this._tenant);
+      this._log("connecting", wsUrl);
       const ws = new WebSocket(wsUrl, [SUB_PROTOCOL, token]);
       this._ws = ws;
       ws.onopen = () => {
         if (this._ws !== ws) return;
+        this._log("connected");
         this._reconnectAttempts = 0;
         const isDPoP = this._auth._tokenType === "DPoP" && !!this._auth._dpopKeyPair;
         const bindPromise = isDPoP ? createDPoPProof(this._auth._dpopKeyPair, "GET", wsUrl, null).then(
@@ -548,6 +842,14 @@ var WebSocketManager = class {
           this._emit("error", new Error(msg.message));
           return;
         }
+        this._log("event", msg.type, msg.entityId || "");
+        if (msg.entityId && msg.data && typeof msg.data === "object") {
+          msg.entity = {
+            id: msg.entityId,
+            type: msg.entityType,
+            ...msg.data
+          };
+        }
         this._emit(msg.type, msg);
         this._emit("message", msg);
       };
@@ -650,19 +952,55 @@ var GeonicDB = class extends EventEmitter {
       if (!tenant) tenant = script?.getAttribute?.("data-tenant") || "";
       if (!baseUrl) baseUrl = script?.getAttribute?.("data-base-url") || "";
     }
-    this._auth = new AuthManager(baseUrl, apiKey, tenant);
+    this._auth = new AuthManager(baseUrl, apiKey, tenant, opts.debug);
     this._auth.onTokenRefresh = (creds) => {
       this.onTokenRefresh?.(creds);
       this.emit("tokenRefresh", creds);
     };
+    if (opts.cache !== false) {
+      const cache = new SdkCache(opts.cacheMaxEntries ?? SDK_CACHE_MAX_ENTRIES_DEFAULT);
+      this._auth.setCache(cache);
+      this._auth.setCacheEventEmitter((name, payload) => this.emit(name, payload));
+    }
     this._ws = new WebSocketManager(
       this._auth,
       baseUrl,
       tenant,
-      (event, data) => this.emit(event, data),
+      (event, data) => {
+        this.emit(event, data);
+        if (event === "entityCreated" || event === "entityUpdated" || event === "entityDeleted") {
+          this._invalidateCacheForEntityEvent(data);
+        }
+      },
       opts.wsEndpoint
     );
   }
+  /**
+   * Drop cache entries that may have been affected by an entity change.
+   *
+   * The SDK does not know which lists exactly contain the entity, so the
+   * conservative strategy is to drop all NGSI-LD / NGSIv2 entity-related
+   * paths. ETag re-validation on the next read brings the data back in one
+   * round trip with `If-None-Match`, so this remains efficient even when
+   * over-invalidating.
+   */
+  _invalidateCacheForEntityEvent(event) {
+    const cache = this._auth.getCache();
+    if (!cache) return;
+    const entityId = event?.entityId;
+    const removed = cache.deleteWhere((key) => {
+      if (key.includes("/ngsi-ld/v1/entities") || key.includes("/v2/entities")) return true;
+      if (entityId && key.includes(entityId)) return true;
+      return false;
+    });
+    for (const key of removed) {
+      this._auth.emitCacheEvent("cacheInvalidated", { key, path: key.split(":").slice(1).join(":") });
+    }
+  }
+  /** Drop every cached response. Useful in tests and on manual auth changes. */
+  clearCache() {
+    this._auth.getCache()?.clear();
+  }
   // --- Authentication ---
   /** Login with email and password (Bearer JWT). */
   async login(email, password) {
@@ -687,9 +1025,7 @@ var GeonicDB = class extends EventEmitter {
     const res = await this._auth.request("POST", "/ngsi-ld/v1/entities", entity);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Create failed"
-      );
+      throw createErrorFromResponse(res.status, e, "Create failed");
     }
     return { created: true };
   }
@@ -701,35 +1037,88 @@ var GeonicDB = class extends EventEmitter {
     );
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Not found"
-      );
+      throw createErrorFromResponse(res.status, e, "Not found");
     }
     return await res.json();
   }
   /** Query entities with optional filters. */
   async getEntities(params) {
-    let qs = "";
-    if (params) {
-      const parts = [];
-      if (params.type) parts.push("type=" + encodeURIComponent(params.type));
-      if (params.limit != null) parts.push("limit=" + params.limit);
-      if (params.offset != null) parts.push("offset=" + params.offset);
-      if (params.q) parts.push("q=" + encodeURIComponent(params.q));
-      if (parts.length) qs = "?" + parts.join("&");
-    }
-    const res = await this._auth.request(
-      "GET",
-      "/ngsi-ld/v1/entities" + qs
-    );
+    const res = await this._auth.request("GET", buildEntitiesPath(params));
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Query failed"
-      );
+      throw createErrorFromResponse(res.status, e, "Query failed");
     }
     return await res.json();
   }
+  /**
+   * Poll for entity list changes using ETag-based revalidation (#991 Phase A).
+   *
+   * The handle's `stop()` ends the loop. Each tick performs a normal
+   * `getEntities()` call; the SDK's cache layer issues `If-None-Match`
+   * automatically. The poll detects "no change" by comparing the previous
+   * ETag with the response's ETag (the cache exposes the cached ETag on 304
+   * replays as well, so the comparison stays valid in both 200 and 304
+   * paths).
+   *
+   * @example
+   * ```typescript
+   * const handle = db.poll({ type: 'Room' }, {
+   *   interval: 5000,
+   *   onData: (rooms) => render(rooms),
+   *   onNoChange: () => {},
+   * });
+   * // ...later
+   * handle.stop();
+   * ```
+   */
+  poll(params, options) {
+    const interval = options.interval ?? SDK_POLL_INTERVAL_MS_DEFAULT;
+    if (!Number.isFinite(interval) || interval <= 0) {
+      throw new Error(`poll interval must be a positive number (got ${String(interval)})`);
+    }
+    let stopped = false;
+    let timer = null;
+    let prevEtag;
+    let prevPath;
+    const buildPath = () => buildEntitiesPath(params);
+    const tick = async () => {
+      if (stopped) return;
+      try {
+        const path = prevPath ?? (prevPath = buildPath());
+        const res = await this._auth.request("GET", path);
+        if (stopped) return;
+        const etag = res.headers.get("etag") ?? void 0;
+        if (prevEtag !== void 0 && etag !== void 0 && prevEtag === etag) {
+          options.onNoChange?.();
+        } else {
+          if (!res.ok) {
+            throw createErrorFromResponse(res.status, {}, "Poll request failed");
+          }
+          const data = await res.json();
+          prevEtag = etag;
+          options.onData?.(data);
+        }
+      } catch (err) {
+        options.onError?.(err);
+      } finally {
+        if (!stopped) {
+          timer = setTimeout(() => {
+            void tick();
+          }, interval);
+        }
+      }
+    };
+    void tick();
+    return {
+      stop() {
+        stopped = true;
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      }
+    };
+  }
   /** Count entities matching the given filters. */
   async count(params) {
     const parts = ["count=true", "limit=0"];
@@ -742,9 +1131,7 @@ var GeonicDB = class extends EventEmitter {
     );
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Count failed"
-      );
+      throw createErrorFromResponse(res.status, e, "Count failed");
     }
     const countHeader = res.headers.get("NGSILD-Results-Count");
     return countHeader ? parseInt(countHeader, 10) : 0;
@@ -758,9 +1145,7 @@ var GeonicDB = class extends EventEmitter {
     );
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Update failed"
-      );
+      throw createErrorFromResponse(res.status, e, "Update failed");
     }
     return { updated: true };
   }
@@ -772,9 +1157,7 @@ var GeonicDB = class extends EventEmitter {
     );
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Delete failed"
-      );
+      throw createErrorFromResponse(res.status, e, "Delete failed");
     }
     return { deleted: true };
   }
@@ -871,9 +1254,7 @@ var GeonicDB = class extends EventEmitter {
     const res = await this._auth.request("GET", path);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || fallbackError
-      );
+      throw createErrorFromResponse(res.status, e, fallbackError);
     }
     return await res.json();
   }
@@ -882,9 +1263,7 @@ var GeonicDB = class extends EventEmitter {
     const res = await this._auth.request("POST", path, body);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || fallbackError
-      );
+      throw createErrorFromResponse(res.status, e, fallbackError);
     }
     if (res.status === 204) return {};
     return await res.json();
@@ -898,9 +1277,7 @@ var GeonicDB = class extends EventEmitter {
     const res = await this._auth.request(method, path, body);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new Error(
-        e.detail || e.description || "Request failed: " + res.status
-      );
+      throw createErrorFromResponse(res.status, e, "Request failed: " + res.status);
     }
     const ct = res.headers.get("Content-Type") || "";
     if (res.status === 204 || !ct) return null;
@@ -940,8 +1317,25 @@ var index_default = GeonicDB;
 if (typeof window !== "undefined") {
   window.GeonicDB = GeonicDB;
 }
+function buildEntitiesPath(params) {
+  if (!params) return "/ngsi-ld/v1/entities";
+  const parts = [];
+  if (params.type) parts.push("type=" + encodeURIComponent(params.type));
+  if (params.limit != null) parts.push("limit=" + params.limit);
+  if (params.offset != null) parts.push("offset=" + params.offset);
+  if (params.q) parts.push("q=" + encodeURIComponent(params.q));
+  return parts.length > 0 ? "/ngsi-ld/v1/entities?" + parts.join("&") : "/ngsi-ld/v1/entities";
+}
 export {
+  AuthenticationError,
+  AuthorizationError,
+  ConflictError,
   GeonicDB,
+  GeonicDBError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
   index_default as default
 };
 //# sourceMappingURL=geonicdb.mjs.map