@geolonia/geonicdb-sdk 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geolonia/geonicdb-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "GeonicDB JavaScript SDK — NGSI-LD Context Broker client for browser and Node.js",
   "main": "geonicdb.cjs",
   "module": "geonicdb.mjs",

package/react/index.d.ts

@@ -105,6 +105,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) */
@@ -126,13 +132,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 {
@@ -142,15 +159,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 {
@@ -162,14 +206,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;
 }
@@ -237,6 +287,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;
@@ -275,13 +333,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` 未指定）のレスポンス。
@@ -454,8 +545,22 @@ 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. */