@geolonia/geonicdb-sdk 0.16.0 → 0.17.0

package/geonicdb.d.ts

@@ -103,6 +103,12 @@ export interface GetEntitiesParams {
 	geometry?: string;
 	/** Coordinates string (semicolon-delimited pairs or flat comma-separated) */
 	coordinates?: string;
+	/**
+	 * 多重属性のインスタンス絞り込み (`datasetId` クエリ、ETSI GS CIM 009 clause 4.5.5.1)。
+	 * カンマ区切りで複数指定可。既定インスタンスは `@none`。一致が 1 件なら単一要素、
+	 * 0 件ならその属性は応答から落ちる。
+	 */
+	datasetId?: string;
 	/** Comma-separated attribute names to retrieve */
 	attrs?: string;
 	/** Comma-separated attribute names to keep (alternative to attrs) */
@@ -124,13 +130,24 @@ export interface GetEntitiesParams {
 	/**
 	 * NGSI-LD representation options (`options` query param)。カンマ区切りで複数指定可。
 	 * - `sysAttrs` — システム属性 (`createdAt` / `modifiedAt`) を含める
-	 * - `keyValues` — 簡易表現 (属性を値だけに圧縮)
+	 * - `keyValues` — 簡易表現 (属性を値だけに圧縮)。多重属性 (`datasetId` 付きインスタンス) は
+	 *   一致が複数のときだけ `dataset` マップになる (既定インスタンスのキーは `@none`)。
+	 *   1 件なら素の値 (ETSI GS CIM 009 clause 4.5.4 / 4.5.5.1)
 	 * - `concise` — concise 表現
 	 * - `normalized` — 正規化表現 (デフォルト)
 	 *
 	 * 例: `'sysAttrs'`, `'keyValues,sysAttrs'`。
 	 */
 	options?: string;
+	/**
+	 * ローカルスコープに限定する (`local` クエリパラメータ、ETSI GS CIM 009 clause 5.5.13 / Table 6.3.18-1)。
+	 *
+	 * **#2278**: `GET /ngsi-ld/v1/entities` は clause 5.7.2.4 により
+	 * `type` / `attrs` (非システム属性を含む) / `q` (非システム属性を含む) / geoquery / local scope の
+	 * いずれかを必須とする。**絞り込み無しで全件を取りたい場合は `local: true` を指定する**
+	 * (指定しないと `400 BadRequestData` = too wide query)。
+	 */
+	local?: boolean;
 }
 /** Parameters for counting entities. */
 export interface CountEntitiesParams {
@@ -140,15 +157,42 @@ export interface CountEntitiesParams {
 	q?: string;
 	/** NGSI-LD scope query expression (#1132) */
 	scopeQ?: string;
+	/**
+	 * ローカルスコープに限定する (`local` クエリパラメータ、ETSI GS CIM 009 clause 5.5.13 / Table 6.3.18-1)。
+	 *
+	 * **#2278**: `GET /ngsi-ld/v1/entities` は clause 5.7.2.4 により
+	 * `type` / `attrs` (非システム属性を含む) / `q` (非システム属性を含む) / geoquery / local scope の
+	 * いずれかを必須とする。**絞り込み無しで全件を取りたい場合は `local: true` を指定する**
+	 * (指定しないと `400 BadRequestData` = too wide query)。
+	 */
+	local?: boolean;
 }
 /** Options for subscribing to entity events via WebSocket. */
 export interface SubscribeOptions {
-	/** Entity types to subscribe to */
+	/**
+	 * Entity types to subscribe to.
+	 *
+	 * **#2055.** Matched against the canonical stored form: the supplied `@context` is
+	 * resolved once at `subscribe` time and these names are expanded before matching,
+	 * so a term defined by a custom `@context` changes which entities match.
+	 */
 	entityTypes?: string[];
-	/** Entity ID regex pattern */
+	/** Entity ID regex pattern. Matched against the stored form verbatim (no `@context` expansion). */
 	idPattern?: string;
 	/** NGSI-LD scope query expression (#1132). Server-side filter; only events whose entity scope matches are delivered. */
 	scopeQ?: string;
+	/**
+	 * JSON-LD `@context` used to render delivered events (#2026).
+	 *
+	 * The entity type and attribute names are compacted against it (ETSI GS CIM 009 clause 5.5.7)
+	 * and the value is echoed back in each event's `@context`. Omit for the core `@context`.
+	 * URL string / array of URL strings only — inline context objects are rejected.
+	 *
+	 * **#2055: it also governs `entityTypes` matching** — the context is resolved once at
+	 * `subscribe` time to expand `entityTypes` into the canonical stored form. `idPattern`
+	 * alone is matched against the stored form verbatim.
+	 */
+	"@context"?: string | string[];
 }
 /** Entity event received via WebSocket. */
 export interface EntityEvent {
@@ -160,14 +204,20 @@ export interface EntityEvent {
 	servicePath: string;
 	/** Entity ID */
 	entityId: string;
-	/** Entity type */
+	/** Entity type, compacted with the subscription `@context` (#2026) */
 	entityType: string;
-	/** Entity attributes */
+	/**
+	 * Entity attributes in NGSI-LD normalized representation (clause 4.5.2, #2026 / #2044).
+	 * Attribute names are compacted with the subscription `@context`; sub-attributes are inline;
+	 * multi-attributes appear as an instance array carrying `datasetId` (clause 4.5.5).
+	 */
 	data: Record<string, unknown>;
 	/** Complete NGSI-LD entity (id + type + attributes from data). Undefined when data is unavailable (e.g. some delete events). */
 	entity?: Record<string, unknown>;
 	/** Changed attribute names (update only) */
 	changedAttributes?: string[];
+	/** Vocabulary the names in this event were rendered with (#2026) */
+	"@context"?: string | string[];
 	/** ISO 8601 timestamp */
 	timestamp: string;
 }
@@ -235,6 +285,14 @@ export interface GeonicDBEventMap {
 	};
 	disconnected: undefined;
 	reconnecting: ReconnectingEvent;
+	/**
+	 * #2055: 購読フィルタがサーバ側で有効になった (`{"type":"subscribed"}` の受信)。
+	 *
+	 * `subscribe()` の適用は非同期 — サーバは渡された `@context` を解決して `entityTypes` を
+	 * 照合用の canonical 形へ展開する (ETSI GS CIM 009 clause 5.5.7)。このイベントより前に
+	 * 発生した更新は配信が保証されない。
+	 */
+	subscribed: undefined;
 	error: Error;
 	message: Record<string, unknown>;
 	tokenRefresh: RefreshedCredentials;
@@ -273,13 +331,46 @@ export interface GetTemporalEntitiesParams {
 	offset?: number;
 	/**
 	 * NGSI-LD representation options (`options` query param)。カンマ区切りで複数指定可。
-	 * - `sysAttrs` — システム属性 (`createdAt` / `modifiedAt`) を含める
 	 * - `temporalValues` — 時系列を簡易配列表現で返す
-	 * - `aggregatedValues` — 集約表現で返す
+	 * - `simplified` — `temporalValues` の同義語 (GeonicDB 拡張)
+	 * - `aggregatedValues` — 集約表現で返す (ETSI clause 4.5.19 の「メソッド名をキー +
+	 *   [値, 開始, 終了] の 3 要素配列」形。#1815 で独自形から是正)
+	 * - `sysAttrs` — システム時相属性 (`createdAt` / `modifiedAt`、TTL 設定時は `expiresAt`) を
+	 *   normalized 表現の各インスタンスへ含める (ETSI 6.3.11、#1817)。簡易表現・集約表現には
+	 *   載せる場所が無いため受理して無視される (400 にはならない)
 	 *
-	 * 例: `'sysAttrs'`, `'temporalValues'`。
+	 * 注:
+	 * - この SDK では `aggregatedValues` は `options` で指定し、`aggrMethods` との併用が必須
+	 * - サーバ側では `format=aggregatedValues` に対しても同じ必須条件が適用される
+	 * - `options` は ETSI 6.3.12 で deprecated。`format` を併用した場合は **`format` が優先される**
+	 *
+	 * 例: `'temporalValues'`, `'aggregatedValues'`。
 	 */
 	options?: string;
+	/**
+	 * #1814: 表現形式 (`format` query param、ETSI GS CIM 009 clause 6.3.12)。
+	 * `'temporalValues'` / `'aggregatedValues'` のいずれか (`'simplified'` は `'temporalValues'` の
+	 * 別名として受理される GeonicDB 拡張)。**未知値はサーバが 400 InvalidRequest で拒否する。**
+	 * `options` と併用した場合は **`format` が優先される**。
+	 *
+	 * SDK は npm 向けに単独ビルドされ本体の `@config/defaults` を import しないため、
+	 * 許可値はここでリテラル union として持つ。**本体の
+	 * `NGSI_LD.TEMPORAL_REPRESENTATION_FORMATS` を変えたらこの union も同期すること**
+	 * (SDK Consistency)。
+	 */
+	format?: "temporalValues" | "aggregatedValues" | "simplified";
+	/**
+	 * #1815: 集約メソッド (カンマ区切り)。`totalCount` / `distinctCount` / `sum` / `avg` / `min` /
+	 * `max` / `stddev` / `sumsq`。`aggregatedValues` を `format` か `options` で指定する場合は必須。
+	 * 応答は clause 4.5.19 形 (メソッド名がキー、各期間は `[値, 開始, 終了]` の 3 要素配列)。
+	 */
+	aggrMethods?: string;
+	/**
+	 * 集約期間 (ISO 8601 duration。例 `'PT1H'`)。
+	 * ETSI GS CIM 009 Table 5.2.21-1 の cardinality は 0..1 で**任意**。省略時は `PT0S` として
+	 * 扱われ、クエリの時間範囲全体が 1 期間として集約される (clause 4.5.19.1)。
+	 */
+	aggrPeriodDuration?: string;
 }
 /**
  * `GET /ngsi-ld/v1/types`（`details` 未指定）のレスポンス。
@@ -528,8 +619,22 @@ export declare class GeonicDB extends EventEmitter {
 	getTemporalEntity(entityId: string): Promise<Record<string, unknown>>;
 	/** Create multiple entities in a single request. */
 	batchCreate(entities: Record<string, unknown>[]): Promise<Record<string, unknown>>;
-	/** Upsert multiple entities in a single request. */
-	batchUpsert(entities: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+	/**
+	 * 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
+	 */
+	batchUpsert(entities: Record<string, unknown>[]): Promise<string[] | Record<string, unknown>>;
 	/** Update multiple entities in a single request. */
 	batchUpdate(entities: Record<string, unknown>[]): Promise<Record<string, unknown>>;
 	/** Delete multiple entities by ID. */

package/geonicdb.iife.js

@@ -1246,13 +1246,12 @@ var GeonicDBModule = (() => {
       }
       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 GeonicDBModule = (() => {
         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 GeonicDBModule = (() => {
             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 GeonicDBModule = (() => {
         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 GeonicDBModule = (() => {
         "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",