@geolonia/geonicdb-sdk 0.16.0 → 0.17.0

package/README.md

@@ -220,10 +220,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 +317,11 @@ 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.
+
 ```typescript
 db.subscribe({ entityTypes: ['Room'] });
 
@@ -324,6 +344,7 @@ await db.connect();
 | `entityDeleted` | `EntityEvent` | Entity was deleted |
 | `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 +498,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 +508,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 +526,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 +537,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 +609,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
 

package/geonicdb.cjs

@@ -1246,13 +1246,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) => {
@@ -1398,6 +1397,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;
@@ -1465,6 +1465,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) {
@@ -1931,7 +1935,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 +2034,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",