@geolonia/geonicdb-sdk 0.14.0 → 0.16.0

package/README.md

@@ -115,6 +115,30 @@ On runtimes without Web Crypto (`subtle.generateKey`, e.g. a non-HTTPS
 context), the session cannot be sender-constrained: the SDK silently keeps
 the plain Bearer session and **login still succeeds** (`tokenType === 'Bearer'`).
 
+#### First-login forced password change (#1532)
+
+When an administrator issues a **temporary password** — either at creation
+(`POST /admin/users` with `passwordResetRequired: true`) or afterwards
+(`POST /admin/users/{userId}/reset-password`) — the user must set a new password
+on first login. Logging in with only the temporary password throws
+`PasswordResetRequiredError`; supply `newPassword` to set the new password and
+receive tokens in the same call (no re-login needed):
+
+```typescript
+import { PasswordResetRequiredError, TemporaryPasswordExpiredError } from '@geolonia/geonicdb-sdk';
+
+try {
+  await db.login('user@example.com', temporaryPassword);
+} catch (err) {
+  if (err instanceof PasswordResetRequiredError) {
+    // Prompt the user for a new password, then complete login in one call:
+    await db.login('user@example.com', temporaryPassword, { newPassword });
+  } else if (err instanceof TemporaryPasswordExpiredError) {
+    // Ask an administrator to re-issue the temporary password.
+  }
+}
+```
+
 #### Keeping the user signed in across page reloads
 
 By default a session is held in memory only — reloading the page loses it
@@ -196,6 +220,11 @@ 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).
+
 ```typescript
 // Create
 await db.createEntity({ id: 'urn:ngsi-ld:Room:001', type: 'Room', ... });
@@ -228,9 +257,11 @@ await db.deleteEntity('urn:ngsi-ld:Room:001');
 ## Types / Attributes Discovery
 
 ```typescript
-const types = await db.getTypes();
+// getTypes()/getAttributes() は EntityTypeList/AttributeList オブジェクトを返す。
+// 型名・属性名の一覧は typeList / attributeList から取得する。
+const { typeList } = await db.getTypes();          // string[]
 const roomType = await db.getType('Room');
-const attributes = await db.getAttributes();
+const { attributeList } = await db.getAttributes(); // string[]
 const tempAttr = await db.getAttribute('temperature');
 ```
 
@@ -459,9 +490,9 @@ handle.stop();
 
 | Method | Parameters | Returns | Description |
 |--------|-----------|---------|-------------|
-| `getTypes()` | — | `Promise<Record<string, unknown>[]>` | List all entity types |
+| `getTypes()` | — | `Promise<EntityTypeList>` | List all entity types (`{ id, type, typeList }`) |
 | `getType(typeName)` | `string` | `Promise<Record<string, unknown>>` | Get details for a specific entity type |
-| `getAttributes()` | — | `Promise<Record<string, unknown>[]>` | List all attributes |
+| `getAttributes()` | — | `Promise<AttributeList>` | List all attributes (`{ id, type, attributeList }`) |
 | `getAttribute(attrName)` | `string` | `Promise<Record<string, unknown>>` | Get details for a specific attribute |
 
 ### Temporal API

package/geonicdb.cjs

@@ -29,7 +29,9 @@ __export(index_exports, {
   GeonicDBError: () => GeonicDBError,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
+  PasswordResetRequiredError: () => PasswordResetRequiredError,
   RateLimitError: () => RateLimitError,
+  TemporaryPasswordExpiredError: () => TemporaryPasswordExpiredError,
   ValidationError: () => ValidationError,
   buildPathWithParams: () => buildPathWithParams,
   default: () => index_default
@@ -80,6 +82,7 @@ var RECONNECT_MAX_ATTEMPTS = 10;
 var RECONNECT_BASE_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
 var SUB_PROTOCOL = "access_token";
+var NGSI_LD_CORE_CONTEXT = "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld";
 var SDK_CACHE_MAX_ENTRIES_DEFAULT = 1e3;
 var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
 var DPOP_IDB_NAME = "geonicdb-sdk";
@@ -321,6 +324,20 @@ var ConflictError = class extends GeonicDBError {
     this.name = "ConflictError";
   }
 };
+var PasswordResetRequiredError = class extends AuthenticationError {
+  constructor(message = "Password reset required: set a new password to complete login") {
+    super(message);
+    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);
+    this.name = "TemporaryPasswordExpiredError";
+    this.statusCode = 403;
+  }
+};
 var ValidationError = class extends GeonicDBError {
   constructor(message = "Validation failed") {
     super(message, 422);
@@ -711,16 +728,24 @@ var _AuthManager = class _AuthManager {
       "Content-Type": "application/json"
     };
     if (this._tenant) headers["NGSILD-Tenant"] = this._tenant;
+    const loginBody = { email, password };
+    if (options?.newPassword !== void 0) loginBody.newPassword = options.newPassword;
     const res = await fetch(this._baseUrl + "/auth/login", {
       method: "POST",
       headers,
-      body: JSON.stringify({ email, password })
+      body: JSON.stringify(loginBody)
     });
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
-      throw new AuthenticationError(
-        e.detail || e.description || "Login failed: " + res.status
-      );
+      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);
+      }
+      if (res.status === 403 && code.includes("TemporaryPasswordExpired")) {
+        throw new TemporaryPasswordExpiredError(message);
+      }
+      throw new AuthenticationError(message);
     }
     const data = await res.json();
     this._anonymous = false;
@@ -1221,7 +1246,15 @@ var _AuthManager = class _AuthManager {
     }
     const url = this._baseUrl + path;
     const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair && token !== null;
-    const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
+    const isEntityWrite = path.split("?")[0].startsWith("/ngsi-ld/v1/entities");
+    let effectiveBody = body;
+    if (isEntityWrite && effectiveBody !== null && typeof effectiveBody === "object" && !Array.isArray(effectiveBody) && !("@context" in effectiveBody)) {
+      effectiveBody = {
+        ...effectiveBody,
+        "@context": NGSI_LD_CORE_CONTEXT
+      };
+    }
+    const bodyStr = effectiveBody !== void 0 ? JSON.stringify(effectiveBody) : void 0;
     const doRequest = async (reqToken, dpopNonce) => {
       const reqIsDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair && reqToken !== null;
       const dpopProof = reqIsDPoP ? await createDPoPProof(
@@ -1934,7 +1967,13 @@ var GeonicDB = class extends EventEmitter {
     return { deleted: true };
   }
   // --- Types / Attributes Discovery ---
-  /** List all entity types. */
+  /**
+   * List all entity types.
+   *
+   * `details` 未指定の `GET /types` は ETSI OpenAPI v1.8.1 準拠の
+   * `EntityTypeList` オブジェクト（`{ id, type: 'EntityTypeList', typeList }`）を返す。
+   * 型名の一覧は `typeList` から取得する。
+   */
   async getTypes() {
     return this._jsonGet("/ngsi-ld/v1/types", "Types query failed");
   }
@@ -1945,7 +1984,13 @@ var GeonicDB = class extends EventEmitter {
       "Type not found"
     );
   }
-  /** List all attributes. */
+  /**
+   * List all attributes.
+   *
+   * `details` 未指定の `GET /attributes` は ETSI OpenAPI v1.8.1 準拠の
+   * `AttributeList` オブジェクト（`{ id, type: 'AttributeList', attributeList }`）を返す。
+   * 属性名の一覧は `attributeList` から取得する。
+   */
   async getAttributes() {
     return this._jsonGet("/ngsi-ld/v1/attributes", "Attributes query failed");
   }