@geolonia/geonicdb-sdk 0.16.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
@@ -220,10 +231,25 @@ const entities = await db.getEntities({ type: 'GeoJSON' });
 
 ## Entity CRUD
 
-> **Automatic `@context` (#1583)**: the SDK sends requests as `application/ld+json`,
-> which requires an inline JSON-LD `@context` in the body. When your body omits
-> `@context`, the SDK injects the NGSI-LD core context automatically; a
-> `@context` you provide is always preserved (never overwritten).
+> **Automatic `@context` (#1583 / #1599 / #2069)**: the SDK sends requests as
+> `application/ld+json`, which per ETSI GS CIM 009 clause 6.3.5 requires an inline JSON-LD
+> `@context` in the body. When your body omits `@context`, the SDK injects the NGSI-LD core
+> context automatically; a `@context` you provide is always preserved (never overwritten).
+>
+> Injection covers the **whole NGSI-LD API (`/ngsi-ld/v1/**`)** — the same surface where the
+> broker enforces clause 6.3.5 (`/ngsi-ld/v1/jsonldContexts` is excluded, since its body *is*
+> the context document). **Batch array bodies (`/entityOperations/*`) get it per element**,
+> because each element is its own JSON-LD document (clause 5.6.7.3) and an element without a
+> `@context` comes back as a per-entity `BadRequestData` inside a **`207 Multi-Status`**.
+> Arrays of ID strings (`entityOperations/delete`, clause 5.6.10.3) are left alone, as are
+> non-NGSI-LD endpoints (auth / admin / rules), whose `.strict()` schemas reject unknown keys.
+>
+> **Do not attach a `Link` header to writes (#1924)**: ETSI GS CIM 009 clause 6.3.5
+> restricts where `@context` may come from based on `Content-Type` and forbids
+> mixing the two. Since the SDK always sends `application/ld+json`, adding a
+> JSON-LD `Link` header to a `POST` / `PATCH` / `PUT` via the `request()` /
+> `requestRaw()` escape hatch returns `400 BadRequestData`. Put the `@context`
+> in the body for writes; the `Link` header remains the channel for reads.
 
 ```typescript
 // Create
@@ -302,6 +328,17 @@ const result = await db.request('GET', '/ngsi-ld/v1/subscriptions');
 
 ## WebSocket Event Streaming
 
+> **NGSI-LD changes only (#2284).** A WebSocket connection streams entity changes made through the
+> NGSI-LD API. Writes performed with the NGSIv2 client (`@geolonia/geonicdb-sdk/ngsi-v2`) or any
+> 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'] });
 
@@ -322,8 +359,12 @@ 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 |
 | `close` | `{ code, reason }` | WebSocket closed |
 | `disconnected` | — | Unexpected disconnect |
 | `reconnecting` | `{ attempt, delay }` | Auto-reconnect starting |
@@ -477,7 +518,9 @@ handle.stop();
 | `limit` | `number` | Max results |
 | `offset` | `number` | Pagination offset |
 | `q` | `string` | NGSI-LD query expression |
-| `options` | `string` | NGSI-LD representation options (comma-separated): `sysAttrs` (include `createdAt`/`modifiedAt`), `keyValues`, `concise`, `normalized` |
+| `datasetId` | `string` | Multi-attribute instance filter (comma-separated; default instance is `@none`). A single match is returned as one Attribute element (ETSI GS CIM 009 clause 4.5.5.1) |
+| `options` | `string` | NGSI-LD representation options (comma-separated): `sysAttrs` (include `createdAt`/`modifiedAt`), `keyValues`, `concise`, `normalized`. Under `keyValues`, multi-attributes (instances with a `datasetId`) are returned as a `dataset` map **only when more than one instance matches**, the default instance keyed by `@none`. A single matching instance stays a bare value (ETSI GS CIM 009 clause 4.5.4 / 4.5.5.1) |
+| `local` | `boolean` | **#2278.** Limit execution to local scope (ETSI GS CIM 009 clause 5.5.13). `GET /ngsi-ld/v1/entities` requires at least one of `type` / `attrs` (with a non-system attribute) / `q` (with a non-system attribute) / a geoquery / local scope (clause 5.7.2.4). **To fetch everything without a filter, pass `local: true`** — otherwise the broker returns `400 BadRequestData` (too wide query) |
 
 #### `CountEntitiesParams`
 
@@ -485,6 +528,7 @@ handle.stop();
 |----------|------|-------------|
 | `type` | `string` | Entity type filter |
 | `q` | `string` | NGSI-LD query expression |
+| `local` | `boolean` | **#2278.** Limit execution to local scope (ETSI GS CIM 009 clause 5.5.13). `GET /ngsi-ld/v1/entities` requires at least one of `type` / `attrs` (with a non-system attribute) / `q` (with a non-system attribute) / a geoquery / local scope (clause 5.7.2.4). **To fetch everything without a filter, pass `local: true`** — otherwise the broker returns `400 BadRequestData` (too wide query) |
 
 ### Types / Attributes Discovery
 
@@ -502,6 +546,8 @@ handle.stop();
 | `getTemporalEntities(params?)` | `GetTemporalEntitiesParams` | `Promise<Record<string, unknown>[]>` | Query temporal entities |
 | `getTemporalEntity(entityId)` | `string` | `Promise<Record<string, unknown>>` | Get temporal representation of a single entity |
 
+> Temporal reads answer with **`206 Partial Content`** and a `Content-Range` header when `lastN` is present or the default instance cap actually truncated the history (#2343, ETSI GS CIM 009 clause 6.3.10). Untruncated reads are `200`. Empty results and aggregated representations (`aggrMethods`) remain `200` even when `lastN` is specified, because `Content-Range` cannot be derived. Both methods are unaffected — the SDK checks `res.ok`, which accepts any 2xx. Use `requestRaw()` when you need to read the `Content-Range` value itself.
+
 #### `GetTemporalEntitiesParams`
 
 | Property | Type | Description |
@@ -511,20 +557,23 @@ handle.stop();
 | `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`) |
+| `timeproperty` | `string` | Time property (`observedAt`, `createdAt`, `modifiedAt`, `deletedAt`; default `observedAt`) |
 | `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 |
-| `options` | `string` | NGSI-LD representation options (comma-separated): `sysAttrs`, `temporalValues`, `aggregatedValues` |
+| `options` | `string` | NGSI-LD temporal representation options (comma-separated): `temporalValues`, `simplified` (alias), `aggregatedValues` (ETSI clause 4.5.19 shape — one member per aggregation method, each period an array of `[value, start, end]`; `aggrMethods` is required when `aggregatedValues` is specified via `options` in this SDK, and the server applies the same requirement to `format=aggregatedValues`), `sysAttrs` (ETSI 6.3.11 — adds `createdAt` / `modifiedAt` / `expiresAt` to each instance of the normalized representation where known; accepted and ignored for the simplified and aggregated representations). `options` is deprecated in favour of `format` (ETSI 6.3.12); when both are present, **`format` takes precedence** |
+| `format` | `'temporalValues' \| 'aggregatedValues' \| 'simplified'` | NGSI-LD temporal representation format (ETSI 6.3.12): `temporalValues` or `aggregatedValues` (`simplified` is accepted as an alias of `temporalValues`). Unknown values are rejected by the server with `400 InvalidRequest`. **Takes precedence over `options`** when both are present |
+| `aggrMethods` | `string` | Aggregation methods (comma-separated): `totalCount`, `distinctCount`, `sum`, `avg`, `min`, `max`, `stddev`, `sumsq`. Required when `aggregatedValues` is requested via `format` or `options` |
+| `aggrPeriodDuration` | `string` | Aggregation period as an ISO 8601 duration (e.g. `PT1H`). Optional (ETSI Table 5.2.21-1 cardinality 0..1) — when omitted, the whole time range of the query is aggregated as a single period (`PT0S`) |
 
 ### 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 |
+| `batchUpsert(entities)` | `Record<string, unknown>[]` | `Promise<string[] \| Record<string, unknown>>` | Upsert multiple entities. Per ETSI clause 5.6.8.5 the server returns **201** with a `string[]` of the **created** entity IDs when anything was created, **204** (mapped to `{}`) when every entity already existed, or **207** with `{ created, updated, errors }` on partial failure (#1742) |
 | `batchUpdate(entities)` | `Record<string, unknown>[]` | `Promise<Record<string, unknown>>` | Update multiple entities |
 | `batchDelete(entityIds)` | `string[]` | `Promise<Record<string, unknown>>` | Delete multiple entities by ID |
 
@@ -580,6 +629,8 @@ handle.stop();
 |----------|------|-------------|
 | `entityTypes` | `string[]` | Entity types to subscribe to |
 | `idPattern` | `string` | Entity ID regex pattern |
+| `scopeQ` | `string` | NGSI-LD scope query expression (#1132) |
+| `@context` | `string \| string[]` | **#2026.** JSON-LD `@context` used to render delivered events — entity type and attribute names are compacted against it (ETSI GS CIM 009 clause 5.5.7) and echoed back in each event's `@context`. URL string(s) only. **#2055.** It also governs `entityTypes` matching — the `@context` is resolved once at `subscribe` time to expand `entityTypes` into the canonical stored form, so custom terms change which entities match. `idPattern` alone matches the stored form verbatim |
 
 ### Event Handling
 
@@ -593,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) {
@@ -613,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 |
@@ -621,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
       );
     }
@@ -1246,13 +1264,12 @@ var _AuthManager = class _AuthManager {
     }
     const url = this._baseUrl + path;
     const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair && token !== null;
-    const isEntityWrite = path.split("?")[0].startsWith("/ngsi-ld/v1/entities");
+    const pathname = path.split("?")[0];
+    const isNgsiLdWrite = pathname.startsWith("/ngsi-ld/v1/") && pathname !== "/ngsi-ld/v1/jsonldContexts";
+    const withCoreContext = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !("@context" in value) ? { ...value, "@context": NGSI_LD_CORE_CONTEXT } : value;
     let effectiveBody = body;
-    if (isEntityWrite && effectiveBody !== null && typeof effectiveBody === "object" && !Array.isArray(effectiveBody) && !("@context" in effectiveBody)) {
-      effectiveBody = {
-        ...effectiveBody,
-        "@context": NGSI_LD_CORE_CONTEXT
-      };
+    if (isNgsiLdWrite && effectiveBody !== void 0) {
+      effectiveBody = Array.isArray(effectiveBody) ? effectiveBody.map(withCoreContext) : withCoreContext(effectiveBody);
     }
     const bodyStr = effectiveBody !== void 0 ? JSON.stringify(effectiveBody) : void 0;
     const doRequest = async (reqToken, dpopNonce) => {
@@ -1326,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);
@@ -1398,6 +1416,7 @@ var WebSocketManager = class {
       if (options.entityTypes) msg.entityTypes = options.entityTypes;
       if (options.idPattern) msg.idPattern = options.idPattern;
       if (options.scopeQ) msg.scopeQ = options.scopeQ;
+      if (options["@context"]) msg["@context"] = options["@context"];
     }
     this._subscription = msg;
     if (this._pendingSubscription) return;
@@ -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;
@@ -1465,6 +1491,10 @@ var WebSocketManager = class {
           return;
         }
         if (msg.type === "pong") return;
+        if (msg.type === "subscribed") {
+          this._emit("subscribed", void 0);
+          return;
+        }
         if (msg.type === "dpop_verified") {
           this._pendingSubscription = false;
           if (this._subscription) {
@@ -1720,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);
@@ -1931,7 +1962,9 @@ var GeonicDB = class extends EventEmitter {
       limit: 0,
       type: params?.type,
       q: params?.q,
-      scopeQ: params?.scopeQ
+      scopeQ: params?.scopeQ,
+      // #2278: clause 5.7.2.4 の "too wide query" 免除条件 (e) local scope。
+      local: params?.local
     });
     const res = await this._auth.request("GET", path);
     if (!res.ok) {
@@ -2028,7 +2061,21 @@ var GeonicDB = class extends EventEmitter {
       "Batch create failed"
     );
   }
-  /** Upsert multiple entities in a single request. */
+  /**
+   * Upsert multiple entities in a single request.
+   *
+   * #1742: the server follows ETSI GS CIM 009 clause 5.6.8.5 / Table 6.15.3.1-1:
+   *  - **201** with a `string[]` of the **created** entity IDs, when at least one entity
+   *    was newly created and none failed (merely updated entities are not listed);
+   *  - **204** with no body, when every entity already existed and was updated
+   *    (`_jsonPost` maps this to `{}`);
+   *  - **207** with a `BatchOperationResult` (`{ created, updated, errors }`), on partial
+   *    or total failure.
+   *
+   * The return type reflects all three shapes. Narrow with `Array.isArray(result)` to
+   * detect the "something was created" case.
+   * https://cim.etsi.org/NGSI-LD/official/clause-6.html
+   */
   async batchUpsert(entities) {
     return this._jsonPost(
       "/ngsi-ld/v1/entityOperations/upsert",