@geolonia/geonicdb-sdk 0.2.1 → 0.3.0

package/README.md

@@ -153,7 +153,8 @@ const result = await db.request('GET', '/ngsi-ld/v1/subscriptions');
 db.subscribe({ entityTypes: ['Room'] });
 
 db.on('entityUpdated', (event) => {
-  console.log(`${event.entityId} updated:`, event.data);
+  // event.entity contains the complete NGSI-LD entity ({ id, type, ...attributes })
+  console.log(`${event.entityId} updated:`, event.entity);
 });
 
 db.on('error', (err) => console.error(err));
@@ -192,6 +193,7 @@ await db.connect();
 | `tenant` | `string` | No | Tenant name (or use `data-tenant` attribute on script tag) |
 | `baseUrl` | `string` | No | API base URL (auto-detected from script `src` if omitted) |
 | `wsEndpoint` | `string` | No | WebSocket endpoint URL (auto-detected from `baseUrl` if omitted) |
+| `debug` | `boolean` | No | Enable debug logging to console (default: `false`) |
 
 ### Authentication
 
@@ -300,6 +302,39 @@ await db.connect();
 | `on(event, listener)` | `string, Function` | `this` | Register an event listener |
 | `off(event, listener)` | `string, Function` | `this` | Remove an event listener |
 
+## Error Handling
+
+All async methods throw typed errors extending `GeonicDBError`. Use `instanceof` to distinguish error types.
+
+```typescript
+import { GeonicDBError, AuthenticationError, NotFoundError } from '@geolonia/geonicdb-sdk';
+
+try {
+  await db.getEntity('urn:ngsi-ld:Room:404');
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // 401 — re-login needed
+  } else if (err instanceof NotFoundError) {
+    // 404 — entity not found
+  } else if (err instanceof GeonicDBError) {
+    console.error(err.message, err.statusCode);
+  } else {
+    console.error(err);
+  }
+}
+```
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `GeonicDBError` | — | Base class (`statusCode` property) |
+| `AuthenticationError` | 401 | Invalid credentials or expired token |
+| `AuthorizationError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Entity already exists |
+| `ValidationError` | 422 | Bad request payload |
+| `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
+| `NetworkError` | — | Fetch failure, DNS error, timeout |
+
 ## License
 
 MIT

package/geonicdb.cjs

@@ -22,7 +22,15 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/sdk/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  AuthorizationError: () => AuthorizationError,
+  ConflictError: () => ConflictError,
   GeonicDB: () => GeonicDB,
+  GeonicDBError: () => GeonicDBError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  ValidationError: () => ValidationError,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -173,12 +181,88 @@ var RECONNECT_BASE_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
 var SUB_PROTOCOL = "access_token";
 
+// 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/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");
@@ -192,6 +276,7 @@ var _AuthManager = class _AuthManager {
     this._baseUrl = baseUrl;
     this._apiKey = apiKey;
     this._tenant = tenant;
+    this._debug = debug;
     if (dpopSupported) {
       this._dpopReady = generateDPoPKeyPair().then((kp) => {
         this._dpopKeyPair = kp;
@@ -200,8 +285,12 @@ var _AuthManager = class _AuthManager {
       });
     }
   }
+  _log(...args) {
+    if (this._debug) console.log("[GeonicDB]", ...args);
+  }
   /** Login with email and password (Bearer JWT). */
   async login(email, password) {
+    this._log("login", email);
     const headers = {
       "Content-Type": "application/json"
     };
@@ -213,7 +302,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
       );
     }
@@ -260,6 +349,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",
@@ -270,7 +360,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;
@@ -299,7 +389,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);
@@ -312,7 +402,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();
@@ -352,8 +442,9 @@ 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;
@@ -362,8 +453,11 @@ var _AuthManager = class _AuthManager {
    * Make an authenticated HTTP request with automatic token refresh and DPoP.
    */
   async request(method, path, body) {
+    this._log(method, path);
     const token = await this.ensureToken();
-    return this._doAuthenticatedRequest(method, path, body, token);
+    const res = await this._doAuthenticatedRequest(method, path, body, token);
+    this._log(method, path, "\u2192", res.status);
+    return res;
   }
   async _doAuthenticatedRequest(method, path, body, token, retryCount = 0) {
     const url = this._baseUrl + path;
@@ -448,6 +542,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) {
@@ -525,10 +622,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(
@@ -573,6 +672,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);
       };
@@ -675,7 +782,7 @@ 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);
@@ -712,9 +819,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 };
   }
@@ -726,9 +831,7 @@ 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();
   }
@@ -749,9 +852,7 @@ var GeonicDB = class extends EventEmitter {
     );
     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();
   }
@@ -767,9 +868,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;
@@ -783,9 +882,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 };
   }
@@ -797,9 +894,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 };
   }
@@ -896,9 +991,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();
   }
@@ -907,9 +1000,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();
@@ -923,9 +1014,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;