@geolonia/geonicdb-sdk 0.17.0 → 0.18.0

package/README.md

@@ -2,6 +2,16 @@
 
 GeonicDB JavaScript SDK — NGSI-LD Context Broker client for browser and Node.js.
 
+> **Server-side reference**: most responses carry a
+> `Link: </llms.txt>; rel="describedby"` header pointing at
+> `https://<your-broker>/llms.txt` — a single Markdown document covering the API
+> surface, the auth flow, the entity data model, and a **Troubleshooting**
+> section for symptoms whose cause is not what the error text suggests. NGSI-LD
+> paginated list responses are the exception: their `Link` header carries only
+> `rel="next"`/`rel="prev"`, not the discovery link. Read `/llms.txt` directly
+> alongside this README when a request fails for a reason the SDK cannot
+> explain on its own.
+
 ## Installation
 
 ```bash
@@ -209,6 +219,7 @@ const entities = await db.getEntities({ type: 'GeoJSON' });
 ```
 
 - `apiKey` and `anonymous: true` cannot be combined (constructor throws).
+- A **presented but invalid** Bearer / DPoP token returns HTTP 401 from the server (#2794), not an anonymous 403 — so refresh can fire. True anonymous mode sends **no** `Authorization` header.
 - `db.login()` upgrades the SDK out of anonymous mode (Bearer JWT).
 - `db.setCredentials({ token, tokenType: 'Bearer', ... })` upgrades from
   anonymous. **`tokenType: 'DPoP'` is rejected** for anonymous-built instances
@@ -322,6 +333,12 @@ const result = await db.request('GET', '/ngsi-ld/v1/subscriptions');
 > other `/v2/*` caller are **not** delivered — entities are protocol-isolated and the socket is an
 > NGSI-LD reader. Use HTTP subscriptions (`/v2/subscriptions`) for NGSIv2 changes.
 
+> **Dedicated deployments (#2867):** REST resolves the database from the custom domain (`Host`), but
+> WebSocket uses a shared execute-api endpoint. The SDK calls `GET /sdk/v1/streaming` on your
+> `baseUrl`, reads the optional `deployment` hostname from the response, and appends
+> `?deployment=<hostname>` on `$connect`. Raw `WebSocket` clients must set the same query parameter
+> manually when connecting to a non-default deployment.
+
 ```typescript
 db.subscribe({ entityTypes: ['Room'] });
 
@@ -342,6 +359,9 @@ await db.connect();
 | `entityCreated` | `EntityEvent` | Entity was created |
 | `entityUpdated` | `EntityEvent` | Entity was updated |
 | `entityDeleted` | `EntityEvent` | Entity was deleted |
+
+`EntityEvent.entityType` is `string | string[]` (#2477): a single type is a string; multi-type entities use a string array (same rule as NGSI-LD GET / Table 5.2.4).
+
 | `open` | — | WebSocket connection opened |
 | `connected` | — | WebSocket ready |
 | `subscribed` | — | `subscribe()` filter is now active on the server. Applying a subscription is asynchronous (the server resolves the supplied `@context` to expand `entityTypes` for matching), so events published before this fires are not guaranteed to be delivered |
@@ -624,13 +644,23 @@ handle.stop();
 All async methods throw typed errors extending `GeonicDBError`. Use `instanceof` to distinguish error types.
 
 ```typescript
-import { GeonicDBError, AuthenticationError, NotFoundError } from '@geolonia/geonicdb-sdk';
+import {
+  GeonicDBError,
+  AuthenticationError,
+  PasswordResetRequiredError,
+  TemporaryPasswordExpiredError,
+  NotFoundError,
+} from '@geolonia/geonicdb-sdk';
 
 try {
   await db.getEntity('urn:ngsi-ld:Room:404');
 } catch (err) {
-  if (err instanceof AuthenticationError) {
-    // 401 — re-login needed
+  if (err instanceof PasswordResetRequiredError) {
+    // 409 — collect a new password and call login(..., { newPassword })
+  } else if (err instanceof TemporaryPasswordExpiredError) {
+    // 403 — temporary password expired; ask an administrator to re-issue it
+  } else if (err instanceof AuthenticationError) {
+    // Other auth failures — re-login needed (typically 401; for HTTP-derived errors see err.statusCode)
   } else if (err instanceof NotFoundError) {
     // 404 — entity not found
   } else if (err instanceof GeonicDBError) {
@@ -644,7 +674,9 @@ try {
 | Class | Status | Description |
 |-------|--------|-------------|
 | `GeonicDBError` | — | Base class (`statusCode` property) |
-| `AuthenticationError` | 401 | Invalid credentials or expired token |
+| `AuthenticationError` | Real HTTP status (default 401) | Invalid credentials, expired token, or an HTTP failure on an auth endpoint. HTTP-derived errors carry the server status |
+| `PasswordResetRequiredError` | 409 | First login with a temporary password — set a new password (`AuthenticationError` subclass) |
+| `TemporaryPasswordExpiredError` | 403 | Temporary password expired (`AuthenticationError` subclass) |
 | `AuthorizationError` | 403 | Insufficient permissions |
 | `NotFoundError` | 404 | Resource not found |
 | `ConflictError` | 409 | Entity already exists |
@@ -652,6 +684,54 @@ try {
 | `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
 | `NetworkError` | — | Fetch failure, DNS error, timeout |
 
+### Which request failed (`request`)
+
+`login()` makes up to two requests, the second one conditionally: `POST /auth/login`,
+followed by `POST /auth/dpop-bind` (RFC 9449 session sender-constraining) **only when
+that login succeeded and a DPoP key pair exists**. Where Web Crypto (`crypto.subtle`)
+is unavailable no key pair is generated, so the bind is skipped and login succeeds with
+a plain Bearer token.
+
+Both requests surface the server's `detail` / `description` verbatim as an
+`AuthenticationError` (or one of its subclasses, `PasswordResetRequiredError` /
+`TemporaryPasswordExpiredError`). When the server answers both with the same body, the
+error alone cannot tell a rejected credential from a rejected bind.
+
+Errors from those two requests carry a `request` property (`{ method, path }`), and
+their message is prefixed with `[METHOD path]`.
+
+```ts
+try {
+  await db.login(email, password);
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    if (err.request?.path === '/auth/dpop-bind') {
+      // The credentials were accepted; the DPoP bind is what failed.
+    }
+    console.error(err.message); // "[POST /auth/dpop-bind] Access denied: no applicable policy"
+  } else {
+    console.error(err);
+  }
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `request` | `RequestContext \| undefined` | `{ method, path }`. `path` is the endpoint path without the base URL — if the base URL itself carries a path prefix, the request path on the wire includes that prefix too. |
+
+Only `POST /auth/login` (`AuthenticationError`, `PasswordResetRequiredError`,
+`TemporaryPasswordExpiredError`) and `POST /auth/dpop-bind` set it. Other auth failures
+already name their step in the message (`Token refresh failed: <status>` and friends),
+so they leave `request` as `undefined` — but `statusCode` still reflects the real HTTP
+status. When the bind never runs — no Web Crypto, or a
+failed `/auth/login` — there is no `/auth/dpop-bind` error to attribute in the first
+place.
+
+> `PasswordResetRequiredError` / `TemporaryPasswordExpiredError` are control-flow
+> errors whose `message` an app may render as a prompt. With the prefix that text reads
+> `[POST /auth/login] Password reset required: …`, so branch on `err.request` and supply
+> your own wording rather than displaying the message verbatim.
+
 ## React Hooks (`@geolonia/geonicdb-sdk/react`)
 
 Optional React integration, shipped as a separate subpath so the core SDK stays

package/geonicdb.cjs

@@ -296,13 +296,20 @@ var GeonicDBError = class extends Error {
     super(message);
     /** HTTP status code (if applicable) */
     __publicField(this, "statusCode");
+    /** The request that failed, when the SDK knows it. */
+    __publicField(this, "request");
     this.name = "GeonicDBError";
     this.statusCode = statusCode;
   }
 };
+function withRequest(error, request) {
+  error.request = request;
+  error.message = `[${request.method} ${request.path}] ${error.message}`;
+  return error;
+}
 var AuthenticationError = class extends GeonicDBError {
-  constructor(message = "Authentication failed") {
-    super(message, 401);
+  constructor(message = "Authentication failed", statusCode = 401) {
+    super(message, statusCode);
     this.name = "AuthenticationError";
   }
 };
@@ -326,16 +333,14 @@ var ConflictError = class extends GeonicDBError {
 };
 var PasswordResetRequiredError = class extends AuthenticationError {
   constructor(message = "Password reset required: set a new password to complete login") {
-    super(message);
+    super(message, 409);
     this.name = "PasswordResetRequiredError";
-    this.statusCode = 409;
   }
 };
 var TemporaryPasswordExpiredError = class extends AuthenticationError {
   constructor(message = "Temporary password expired: ask an administrator to re-issue it") {
-    super(message);
+    super(message, 403);
     this.name = "TemporaryPasswordExpiredError";
-    this.statusCode = 403;
   }
 };
 var ValidationError = class extends GeonicDBError {
@@ -740,12 +745,21 @@ var _AuthManager = class _AuthManager {
       const message = e.detail || e.description || "Login failed: " + res.status;
       const code = e.error || e.type || e.title || "";
       if (res.status === 409 && code.includes("PasswordResetRequired")) {
-        throw new PasswordResetRequiredError(message);
+        throw withRequest(new PasswordResetRequiredError(message), {
+          method: "POST",
+          path: "/auth/login"
+        });
       }
       if (res.status === 403 && code.includes("TemporaryPasswordExpired")) {
-        throw new TemporaryPasswordExpiredError(message);
+        throw withRequest(new TemporaryPasswordExpiredError(message), {
+          method: "POST",
+          path: "/auth/login"
+        });
       }
-      throw new AuthenticationError(message);
+      throw withRequest(new AuthenticationError(message, res.status), {
+        method: "POST",
+        path: "/auth/login"
+      });
     }
     const data = await res.json();
     this._anonymous = false;
@@ -848,8 +862,12 @@ var _AuthManager = class _AuthManager {
     }
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new AuthenticationError(
-        e.detail || e.description || "DPoP bind failed: " + res.status
+      throw withRequest(
+        new AuthenticationError(
+          e.detail || e.description || "DPoP bind failed: " + res.status,
+          res.status
+        ),
+        { method: "POST", path: "/auth/dpop-bind" }
       );
     }
     return await res.json();
@@ -1021,7 +1039,7 @@ var _AuthManager = class _AuthManager {
         this._refreshToken = null;
         this._token = null;
         this._tokenPromise = null;
-        throw new AuthenticationError("Token refresh failed: " + res.status);
+        throw new AuthenticationError("Token refresh failed: " + res.status, res.status);
       }
       const data = await res.json();
       this._token = data.accessToken;
@@ -1089,7 +1107,7 @@ var _AuthManager = class _AuthManager {
         body: JSON.stringify({ api_key: this._apiKey })
       });
       if (!nonceRes.ok)
-        throw new AuthenticationError("Nonce request failed: " + nonceRes.status);
+        throw new AuthenticationError("Nonce request failed: " + nonceRes.status, nonceRes.status);
       const nonceData = await nonceRes.json();
       if (nonceData.dpop_nonce) this._dpopNonce = nonceData.dpop_nonce;
       const proof = await solvePoW(nonceData.challenge, nonceData.difficulty);
@@ -1102,7 +1120,7 @@ var _AuthManager = class _AuthManager {
       });
       const res = await this._doTokenExchange(tokenUrl, tokenBody, this._dpopNonce);
       if (!res.ok)
-        throw new AuthenticationError("Token request failed: " + res.status);
+        throw new AuthenticationError("Token request failed: " + res.status, res.status);
       const newNonce = res.headers.get("DPoP-Nonce");
       if (newNonce) this._dpopNonce = newNonce;
       const data = await res.json();
@@ -1144,8 +1162,8 @@ var _AuthManager = class _AuthManager {
           return this._doTokenExchange(tokenUrl, tokenBody, serverNonce, retryCount + 1);
         }
       }
-      throw new GeonicDBError(
-        "Token request failed: " + (errBody.error_description || errBody.error),
+      throw new AuthenticationError(
+        "Token request failed: " + (errBody.error_description || errBody.error || "400"),
         400
       );
     }
@@ -1325,6 +1343,7 @@ var WebSocketManager = class {
     __publicField(this, "_emit");
     __publicField(this, "_ws", null);
     __publicField(this, "_wsEndpoint", null);
+    __publicField(this, "_deploymentHostname", null);
     __publicField(this, "_wsIntentionalClose", false);
     __publicField(this, "_reconnectAttempts", 0);
     __publicField(this, "_tokenRefreshTimer", null);
@@ -1414,6 +1433,9 @@ var WebSocketManager = class {
         const info = await res.json();
         if (info.enabled && info.endpoint) {
           this._wsEndpoint = info.endpoint;
+          if (info.deployment) {
+            this._deploymentHostname = info.deployment;
+          }
           return this._wsEndpoint;
         }
       }
@@ -1425,7 +1447,11 @@ var WebSocketManager = class {
   async _openWebSocket(token) {
     const endpoint = await this._discoverWsEndpoint();
     return new Promise((resolve, reject) => {
-      const wsUrl = endpoint + (endpoint.indexOf("?") === -1 ? "?" : "&") + "tenant=" + encodeURIComponent(this._tenant);
+      const params = new URLSearchParams({ tenant: this._tenant });
+      if (this._deploymentHostname) {
+        params.set("deployment", this._deploymentHostname);
+      }
+      const wsUrl = endpoint + (endpoint.indexOf("?") === -1 ? "?" : "&") + params.toString();
       this._log("connecting", wsUrl);
       const ws = new WebSocket(wsUrl, [SUB_PROTOCOL, token]);
       this._ws = ws;
@@ -1724,6 +1750,7 @@ var GeonicDB = class extends EventEmitter {
       if (!tenant) tenant = script?.getAttribute?.("data-tenant") || "";
       if (!baseUrl) baseUrl = script?.getAttribute?.("data-base-url") || "";
     }
+    baseUrl = baseUrl.replace(/\/+$/, "");
     this._auth = new AuthManager(baseUrl, apiKey, tenant, opts.debug, opts.anonymous);
     this._auth.onTokenRefresh = (creds) => {
       this.onTokenRefresh?.(creds);