@geolonia/geonicdb-sdk 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geolonia Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -47,19 +47,6 @@ await db.createEntity({
 </script>
 ```
 
-### Browser (direct distribution from GeonicDB)
-
-```html
-<script src="https://your-geonicdb.example.com/sdk/v1/geonicdb.js"
-  data-api-key="your-api-key"
-  data-tenant="your-tenant"
-  data-base-url="https://your-geonicdb.example.com"></script>
-<script>
-  var db = new GeonicDB(); // auto-initialized from data-* attributes
-  db.getEntities({ type: 'Room' }).then(console.log);
-</script>
-```
-
 ## Authentication
 
 ### API Key (DPoP + Proof of Work)
@@ -166,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));
@@ -189,6 +177,164 @@ await db.connect();
 | `error` | `Error` | Error occurred |
 | `tokenRefresh` | `RefreshedCredentials` | Bearer token was refreshed |
 
+## API Reference
+
+### Constructor
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `new GeonicDB(options?)` | `GeonicDBOptions` | `GeonicDB` | Create a new SDK instance |
+
+#### `GeonicDBOptions`
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `apiKey` | `string` | No | API key (or use `data-api-key` attribute on script tag) |
+| `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
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `login(email, password)` | `string, string` | `Promise<LoginResponse>` | Login with email and password (Bearer JWT) |
+| `setCredentials(opts)` | `CredentialsOptions` | `this` | Set credentials externally (e.g. from a login API response) |
+| `logout()` | — | `void` | Clear all credentials and disconnect WebSocket |
+
+### Entity CRUD
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `createEntity(entity)` | `Record<string, unknown>` | `Promise<{ created: true }>` | Create a new entity |
+| `getEntity(entityId)` | `string` | `Promise<Record<string, unknown>>` | Get a single entity by ID |
+| `getEntities(params?)` | `GetEntitiesParams` | `Promise<Record<string, unknown>[]>` | Query entities with optional filters |
+| `count(params?)` | `CountEntitiesParams` | `Promise<number>` | Count entities matching the given filters |
+| `updateEntity(entityId, attrs)` | `string, Record<string, unknown>` | `Promise<{ updated: true }>` | Update entity attributes (partial) |
+| `deleteEntity(entityId)` | `string` | `Promise<{ deleted: true }>` | Delete an entity |
+
+#### `GetEntitiesParams`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Entity type filter |
+| `limit` | `number` | Max results |
+| `offset` | `number` | Pagination offset |
+| `q` | `string` | NGSI-LD query expression |
+
+#### `CountEntitiesParams`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Entity type filter |
+| `q` | `string` | NGSI-LD query expression |
+
+### Types / Attributes Discovery
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getTypes()` | — | `Promise<Record<string, unknown>[]>` | List all entity types |
+| `getType(typeName)` | `string` | `Promise<Record<string, unknown>>` | Get details for a specific entity type |
+| `getAttributes()` | — | `Promise<Record<string, unknown>[]>` | List all attributes |
+| `getAttribute(attrName)` | `string` | `Promise<Record<string, unknown>>` | Get details for a specific attribute |
+
+### Temporal API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getTemporalEntities(params?)` | `GetTemporalEntitiesParams` | `Promise<Record<string, unknown>[]>` | Query temporal entities |
+| `getTemporalEntity(entityId)` | `string` | `Promise<Record<string, unknown>>` | Get temporal representation of a single entity |
+
+#### `GetTemporalEntitiesParams`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Entity type filter |
+| `id` | `string` | Entity ID |
+| `idPattern` | `string` | Entity ID pattern (regex) |
+| `attrs` | `string` | Attribute names to retrieve |
+| `q` | `string` | NGSI-LD query expression |
+| `timeproperty` | `string` | Time property (`observedAt`, `createdAt`, `modifiedAt`) |
+| `timeAt` | `string` | Start time (ISO 8601) |
+| `endTimeAt` | `string` | End time (ISO 8601) |
+| `timerel` | `string` | Temporal relation (`before`, `after`, `between`) |
+| `limit` | `number` | Max results |
+| `offset` | `number` | Pagination offset |
+
+### Batch Operations
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `batchCreate(entities)` | `Record<string, unknown>[]` | `Promise<Record<string, unknown>>` | Create multiple entities |
+| `batchUpsert(entities)` | `Record<string, unknown>[]` | `Promise<Record<string, unknown>>` | Upsert multiple entities |
+| `batchUpdate(entities)` | `Record<string, unknown>[]` | `Promise<Record<string, unknown>>` | Update multiple entities |
+| `batchDelete(entityIds)` | `string[]` | `Promise<Record<string, unknown>>` | Delete multiple entities by ID |
+
+### Generic Request
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `request(method, path, body?)` | `string, string, unknown` | `Promise<unknown>` | Authenticated request with automatic JSON parsing |
+| `requestRaw(method, path, body?)` | `string, string, unknown` | `Promise<Response>` | Authenticated request returning raw `Response` (for accessing headers) |
+
+### WebSocket
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `connect()` | — | `Promise<void>` | Establish WebSocket connection |
+| `reconnect()` | — | `Promise<void>` | Force-reconnect (preserves subscriptions) |
+| `disconnect()` | — | `void` | Disconnect WebSocket |
+| `isConnected()` | — | `boolean` | Check if WebSocket is currently open |
+| `subscribe(options?)` | `SubscribeOptions` | `void` | Subscribe to entity events |
+
+#### `SubscribeOptions`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `entityTypes` | `string[]` | Entity types to subscribe to |
+| `idPattern` | `string` | Entity ID regex pattern |
+
+### Event Handling
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `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
 
-AGPL-3.0-or-later
+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;