@geolonia/geonicdb-sdk 0.16.0 → 0.18.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 */
-	entityType: string;
-	/** Entity attributes */
+	/** Entity type, compacted with the subscription `@context` (#2026). Multi-type is `string[]` (#2477 / Table 5.2.4). */
+	entityType: string | string[];
+	/**
+	 * 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` 未指定）のレスポンス。
@@ -319,6 +410,26 @@ declare class EventEmitter {
  * Copyright (c) 2026 Geolonia Inc.
  * Released under the MIT License. See src/sdk/LICENSE for details.
  */
+/**
+ * Which request produced an error.
+ *
+ * `login()` performs two requests — `POST /auth/login` and then
+ * `POST /auth/dpop-bind` — and both surface the server's `detail` /
+ * `description` verbatim as an `AuthenticationError`. Without this, a rejected
+ * credential and a rejected DPoP bind are indistinguishable from the error
+ * alone, so callers (and anyone reading a bug report) cannot tell which step
+ * actually failed.
+ */
+export interface RequestContext {
+	method: string;
+	/**
+	 * The endpoint path, without the base URL — e.g. `/auth/dpop-bind`. When the
+	 * base URL itself carries a path prefix (`https://host/broker`), the path on
+	 * the wire includes that prefix; this field names the endpoint, not the full
+	 * request path.
+	 */
+	path: string;
+}
 /**
  * Base error class for GeonicDB SDK.
  * All SDK errors extend this class, allowing `instanceof GeonicDBError` checks.
@@ -326,11 +437,18 @@ declare class EventEmitter {
 export declare class GeonicDBError extends Error {
 	/** HTTP status code (if applicable) */
 	readonly statusCode: number;
+	/** The request that failed, when the SDK knows it. */
+	readonly request?: RequestContext;
 	constructor(message: string, statusCode?: number);
 }
-/** 401 — Authentication failed (invalid credentials, expired token). */
+/**
+ * Authentication failed (invalid credentials, expired token, or an HTTP
+ * failure on an auth endpoint). Defaults to 401; when thrown from an HTTP
+ * response, pass the real status so callers see what the server returned
+ * (#2649). Subclasses override with 409 / 403 for control-flow errors.
+ */
 export declare class AuthenticationError extends GeonicDBError {
-	constructor(message?: string);
+	constructor(message?: string, statusCode?: number);
 }
 /** 403 — Authorization denied (insufficient permissions). */
 export declare class AuthorizationError extends GeonicDBError {
@@ -528,8 +646,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

@@ -296,13 +296,20 @@ var GeonicDBModule = (() => {
       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 GeonicDBModule = (() => {
   };
   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 GeonicDBModule = (() => {
         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 GeonicDBModule = (() => {
       }
       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 GeonicDBModule = (() => {
           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 GeonicDBModule = (() => {
           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 GeonicDBModule = (() => {
         });
         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 GeonicDBModule = (() => {
             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 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) => {
@@ -1326,6 +1343,7 @@ var GeonicDBModule = (() => {
       __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 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;
@@ -1414,6 +1433,9 @@ var GeonicDBModule = (() => {
           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 GeonicDBModule = (() => {
     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 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) {
@@ -1720,6 +1750,7 @@ var GeonicDBModule = (() => {
         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 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 +2061,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",